OpenClaw

Why this agent

OpenClaw is an open-source personal AI assistant that plugs into messaging channels (WhatsApp, Telegram, Slack, Discord, iMessage, WeChat, QQ, Feishu, and more) and exposes a Skills + plugins extension surface. It speaks MCP both inbound (openclaw mcp serve exposes OpenClaw’s channel conversations to other MCP clients) and outbound (its mcp.servers.<name> registry stores MCP-server definitions that OpenClaw runtimes — embedded Pi, ACP, and others — consume). The canonical UX for outbound registration is the openclaw mcp set CLI.

Safety note (ADR-005): OpenClaw drives chat-bot UIs, which typically lack the “are you sure?” affordances coding-agents provide. For destructive espctl operations (flash, erase_flash, reboot) consider the human-in-the-loop pattern: ideation in OpenClaw, execution in Claude Code / Cursor / Codex CLI.

Prerequisites

• OpenClaw installed (openclaw onboard in a terminal, or follow Getting Started).
• espctl installed at a stable path on disk.
• (Optional, for remote builds) the Aegis build server URL + MCP_AUTH_SECRET.

Install snippet (or alternative)

Recommended — use the openclaw mcp set CLI, which takes only the inner per-server object (no envelope):

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

Or paste this entire envelope into your OpenClaw config (run openclaw mcp show espctl --json to see where OpenClaw writes it, then merge there):

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

Replace:

• /path/to/espctl — full path to your espctl executable.
• CONTROL_BASE_URL — your Aegis build server URL.
• MCP_AUTH_SECRET — the access key your build server gave you.

Or grab the same envelope pre-filled:

Read the install://openclaw resource.

After direct file edit, run openclaw doctor --fix to re-validate.

First-run verification

openclaw mcp list
openclaw mcp show espctl --json

Expected: espctl appears in the list, and show prints back the JSON you just registered. The runtimes that consume this registry (embedded Pi, ACP, etc.) will spawn espctl on demand — there is no single “is the MCP server connected?” command because OpenClaw is a registry, not a long-running MCP client by itself.

Troubleshooting

• openclaw mcp set rejects env keys — OpenClaw’s stdio env safety filter blocks interpreter-startup vars: NODE_OPTIONS, PYTHONSTARTUP, PYTHONPATH, PERL5OPT, RUBYOPT, SHELLOPTS, PS4. Our env keys (CONTROL_BASE_URL, MCP_AUTH_SECRET) are NOT on the block-list, but if you customise env on your side and hit this, set the blocked var on the OpenClaw gateway host process instead of under the server’s env.
• Want HTTP transport instead of stdio? Replace command / args / env with url: "https://esphome.cloud/mcp/esp-idf" and headers: { "Authorization": "Bearer your-access-key" }. For Streamable-HTTP add transport: "streamable-http".
• OpenClaw doctor warnings about CLI-native type: "http" — per docs/cli/mcp.md, OpenClaw normalizes CLI-native type: "http" to canonical transport: "streamable-http" on save and openclaw doctor --fix repairs old configs. Just rerun set or doctor.
• Destructive firmware ops triggered from chat without confirmation — switch to the human-in-the-loop pattern (ADR-005): OpenClaw for ideation, Claude Code / Cursor / Codex CLI for execution.

Tested as-of 2026-05-19

OpenClaw-specific notes

• OpenClaw also supports Codex-app-server projection — set a codex: {agents: [...], defaultToolsApprovalMode: "prompt"} block on the server to surface espctl only into specific OpenClaw agent ids and choose Codex’s per-server approval mode. OpenClaw strips that block before handing native mcp_servers to Codex.
• Embedded Pi consumes the canonical transport: "streamable-http" value directly; Claude Code / Gemini receive CLI-native type values. The same registry covers both.
• mcp.sessionIdleTtlMs (default 600000 = 10 minutes) reaps idle session-scoped bundled MCP runtimes — set 0 to disable.
• OpenClaw is the predecessor of Hermes (Nous Research forked off OpenClaw). Hermes ships a hermes claw migrate skill to import OpenClaw config + skills + memories; if you’re already on Hermes, see Hermes instead.