OpenClaw

Why this agent

OpenClaw 是开源的个人 AI 助手,接入消息平台(WhatsApp、Telegram、Slack、Discord、iMessage、微信、QQ、飞书等),Skills + 插件可扩展。原生支持 MCP 双向: 入站(openclaw mcp serve 把 OpenClaw 的会话暴露给其他 MCP 客户端)和出站(mcp.servers.<name> 注册表存 MCP 服务定义, OpenClaw 各运行时 —— 嵌入式 Pi、ACP 等 —— 按需消费)。出站注册的 canonical UX 是 openclaw mcp set CLI。

安全注记(ADR-005):OpenClaw 驱动 chat-bot 界面,通常缺编程 agent 的“你确定吗?“确认。对破坏性 espctl 操作(flash、 erase_flash、reboot)建议走 human-in-the-loop:OpenClaw 用来聊想法,具体执行交给 Claude Code / Cursor / Codex CLI。

Prerequisites

已安装 OpenClaw(openclaw onboard 命令行,或者跟 Getting Started)。
espctl 已安装在磁盘上某个稳定位置。
(可选,用于远程构建)Aegis 构建服务器地址 + MCP_AUTH_SECRET。

Install snippet (or alternative)

推荐 —— 用 openclaw mcp set CLI,只传内层 per-server 对象 (不要外层信封):

openclaw mcp set espctl '{"command":"/path/to/espctl","args":["mcp","serve"],"env":{"CONTROL_BASE_URL":"https://esphome.cloud","MCP_AUTH_SECRET":"your-access-key"}}'

或者把这整段完整信封并入 OpenClaw 配置(用 openclaw mcp show espctl --json 看 OpenClaw 写到哪个文件,然后往那里合并):

{
  "mcp": {
    "servers": {
      "espctl": {
        "command": "/path/to/espctl",
        "args": ["mcp", "serve"],
        "env": {
          "CONTROL_BASE_URL": "https://esphome.cloud",
          "MCP_AUTH_SECRET": "your-access-key"
        }
      }
    }
  }
}

替换:

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

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

读取 install://openclaw 资源。

直接改文件后,跑一下 openclaw doctor --fix 重新校验。

First-run verification

openclaw mcp list
openclaw mcp show espctl --json

预期:列表里有 espctl,show 把你刚注册的 JSON 原样打回。这个注册表的消费者(嵌入式 Pi、ACP 等)按需启动 espctl —— 没有单一的 “MCP 服务现在连上了吗?“命令,因为 OpenClaw 是注册表,不是自己持续跑的 MCP 客户端。

Troubleshooting

openclaw mcp set 拒了 env 里的某个 key —— OpenClaw 的 stdio env 安全过滤器拦解释器启动变量:NODE_OPTIONS、 PYTHONSTARTUP、PYTHONPATH、PERL5OPT、RUBYOPT、SHELLOPTS、 PS4。我们这边的 env key(CONTROL_BASE_URL、MCP_AUTH_SECRET) 不在黑名单上,但如果你自定义了 env 撞到了,把那个变量设到 OpenClaw gateway 主机进程上,别放在 server 的 env 里。
想用 HTTP 传输不走 stdio? 把 command/args/env 替换成 url: "https://esphome.cloud/mcp/esp-idf" + headers: { "Authorization": "Bearer your-access-key" }。Streamable-HTTP 加 transport: "streamable-http"。
OpenClaw doctor 警告 CLI-native type: "http" —— 按 docs/cli/mcp.md,OpenClaw 会把 CLI-native type: "http" 标准化成 canonical transport: "streamable-http",旧配置由 openclaw doctor --fix 修。重跑 set 或 doctor 即可。
聊天里没确认就触发了破坏性固件操作 —— 切到 human-in-the-loop 模式(ADR-005):OpenClaw 用来聊想法,Claude Code / Cursor / Codex CLI 用来执行。

Tested as-of 2026-05-19

OpenClaw 特有注意事项

OpenClaw 还支持 Codex-app-server 投射 —— 在 server 上加 codex: {agents: [...], defaultToolsApprovalMode: "prompt"} 块, 就能只把 espctl 投射到指定的 OpenClaw agent id,并指定 Codex 的 per-server approval 模式。OpenClaw 把原生 mcp_servers 交给 Codex 之前会先剥掉这个块。
嵌入式 Pi 直接消费 canonical 的 transport: "streamable-http" 值;Claude Code / Gemini 拿到的是 CLI-native 的 type 值。同一份注册表覆盖两边。
mcp.sessionIdleTtlMs(默认 600000 = 10 分钟)回收闲置的会话级 bundled MCP 运行时;设 0 禁用。
OpenClaw 是 Hermes 的前身(Nous Research 从 OpenClaw fork 出 Hermes)。Hermes 自带 hermes claw migrate skill,可以导入 OpenClaw 配置 + skills + 记忆;如果你已经在用 Hermes,见 Hermes。

Keyboard shortcuts

ESP-IDF MCP 用户手册