nanobot

Why this agent

nanobot —— 上游 README 标题就写得很直白:“Build MCP Agents”。它是开源的独立 MCP host,把 MCP 服务、LLM、上下文组合起来,通过任意接口(CLI、语音、 短信、Slack 等等)对外暴露 agent。本手册里所有 agent 里,nanobot 对 MCP 的“原生程度“最高。

Prerequisites

• 通过 uv tool install nanobot-ai 安装 nanobot; nanobot --version 能跑。(uv 安装见 github.com/astral-sh/uv。)
• espctl 已安装在磁盘上某个稳定位置(下文需要完整路径)。
• 按 awesome-deepseek-agent 指南配好 DeepSeek(或兼容的)LLM API key。
• (可选,用于远程构建)Aegis 构建服务器地址 + MCP_AUTH_SECRET。

Install snippet (or alternative)

nanobot 从 nanobot.yaml(项目根目录)或者你 nanobot run <path> 传入的目录(默认 .nanobot/)读 MCP 服务列表。把 mcpServers.espctl 条目并入:

mcpServers:
  espctl:
    command: /path/to/espctl
    args:
      - mcp
      - serve
    env:
      CONTROL_BASE_URL: https://esphome.cloud
      MCP_AUTH_SECRET: your-access-key

然后在 agent 定义里引用它(直接写在 nanobot.yaml 里,或者放 agents/<name>.md 的 front-matter 里):

agents:
  shopping:
    model: deepseek-v4-pro
    mcpServers: espctl

替换:

• /path/to/espctl —— 你电脑上 espctl 程序的完整路径。
• CONTROL_BASE_URL —— 你的 Aegis 构建服务器地址。
• MCP_AUTH_SECRET —— 构建服务器给你的访问密钥。

nanobot schema 还支持 url:(HTTP-MCP)和 image:(Docker),以及 workdir、headers、ports 等高级字段。完整定义见上游 pkg/config/schema.yaml。

或者 —— 拿到预填好的代码片段:

读取 install://nanobot 资源。

First-run verification

cd /path/to/your/project
nanobot run ./nanobot.yaml

在 nanobot 会话里问:

你能调用哪些 espctl 工具?

预期:列出约 40 个 espctl 工具。

Troubleshooting

• 启动时 nanobot.yaml 解析错 —— 检查 mcpServers.espctl.command 是字符串(不是列表),args: 缩进 在 mcpServers.espctl: 下面。
• 列出了工具但每次调用返回 “auth required” —— MCP_AUTH_SECRET 缺失或已失效。回到控制面重新签发一份访问密钥再填进配置。
• {{...}} 占位符 YAML 转义 —— 如果你用 v2 风格的 {{MCP_AUTH_SECRET}} 占位符,要加引号: MCP_AUTH_SECRET: "{{MCP_AUTH_SECRET}}"。YAML 把不带引号的 { 当成 flow-mapping 语法。
• 多个 server / agent —— nanobot 支持单文件 nanobot.yaml 或 目录式 agents/*.md。MCP server 配置不管哪种都写在 nanobot.yaml 里。

Tested as-of 2026-05-19

nanobot 特有注意事项

• nanobot 按 schema 支持三种 MCP server 传输:stdio(上面那种, command: + args:)、HTTP/SSE(url: 指向 MCP 端点)、 Docker(image: 配合可选的 dockerfile:)。本地跑 espctl 用 stdio 最简单。
• 想完全沙箱化,设 unsandboxed: false(默认就是),让 nanobot 在 内置沙箱里跑 espctl。
• 废弃的 mcp-servers.yaml / mcp-servers.json 配置路径还能用 (向后兼容),新搭建走 nanobot.yaml。