openclaw-control-mcp

openclaw-control-mcp

OpenClaw 控制平面的 MCP 服务。 通过 Claude Code、Cursor 或任意 MCP 客户端，操作网关的完整管理界面——列出并触发定时任务、检查会话、配置 Agent 和频道、管理技能与密钥、操作 doctor 记忆平面、配对设备、批准 exec/plugin 调用。143 个类型化工具，涵盖网关公开的所有 JSON-RPC 方法。

不同于上游的 openclaw-mcp，它只封装 /v1/chat/completions。本项目使用 OpenClaw 控制面板采用的 JSON-RPC 协议通信——因此你可以操作网关本身（包括其定时任务、会话、Agent、频道、技能、密钥等），而不只是通过它聊天。

不使用与使用

不使用 openclaw-control-mcp——你需要在控制面板 UI、终端和 Claude Code 之间来回切换。“列出我的定时任务”意味着打开 SPA。“跟踪这个 Agent 会话”意味着留在面板中并不断刷新。“这个技能为什么失败了？”意味着手动翻查 logs.tail。助手可以通过网关聊天，却无法操作网关。

使用 openclaw-control-mcp——同一个助手可以查询 openclaw_cron_list，接着调用 openclaw_sessions_tail 观察正在进行的轮次，通过 openclaw_skills_status 获取诊断数据，通过 openclaw_secrets_set 轮换密钥，并批准卡住的 openclaw_exec_approval——整个过程你无需离开聊天界面。控制面板变成了审计界面，而不是日常操作界面。

快速开始

# Claude Code — registers a stdio server under the default config
claude mcp add openclaw-control -- npx -y openclaw-control-mcp

从受支持的客户端一键安装：

首次启动时，封装程序会生成 Ed25519 设备身份，并显示一个 pairing request id。在 OpenClaw 控制面板中批准一次后，网关就会签发设备令牌，之后的每次调用都会透明地使用该令牌。完整配对流程见下文。

状态

0.8.3 — 已发布到 npm，并已在官方 MCP Registry 中编入索引，名称为 io.github.smurfy92/openclaw-control-mcp。支持多实例网关配置、基于文件的密钥（.env + store.json，模式为 0600，不访问操作系统密钥链——请参阅 ADR-006）、为 128 个已发布的 JSON-RPC 方法提供 143 个类型化工具，另有两个补充入口：openclaw_introspect 会枚举网关在其 hello-ok 中发布的所有方法和事件；openclaw_call 则可调用任何尚未封装为类型化工具的方法，因此无需等待新版本发布，即可使用新增的网关端点。

Ed25519 签名握手已针对网关 2026.4.12+ 完成实时验证。首次启动时，封装程序会生成一个长期有效的设备身份，将其保存到 ${XDG_CONFIG_HOME:-~/.config}/openclaw-control-mcp/store.json（模式为 0600），为 connect 帧签名，并显示生成的配对请求 ID，以便你通过 Control 面板批准一次。批准后，网关会发放设备令牌（位于 hello-ok.auth.deviceToken），该令牌会按网关缓存，并在后续连接时用于授予作用域。

线缆格式（帧类型、字段名称、签名规范化方式、作用域）是通过对精简后的 Control 面板 bundle（/api-docs/assets/index-*.js）进行逆向工程得出的，并与 openclaw/openclaw/scripts/dev/gateway-smoke.ts 交叉核对。该格式没有官方文档说明。如果 OpenClaw 更新网关，行为可能会在不另行通知的情况下发生变化。

首次运行／配对流程

1. 启动封装程序（注册到 ~/.claude.json 后，Claude Code 会自动执行此操作）。
2. 请 Claude 运行 openclaw_device_status。首次调用时：
   • 生成 Ed25519 密钥对并保存到磁盘，
   • 与网关建立 WS 连接，
   • 发送经过签名的 connect 帧，
   • 网关回复 PAIRING_REQUIRED 和 requestId，
   • 工具返回 { pendingPairing: { requestId }, nextStep: "approve in Control panel…" }。
3. 打开 OpenClaw Control 面板 → Devices 选项卡 → 批准 ID 与该请求匹配的请求。
4. 再次请 Claude 运行 openclaw_device_status。这次网关会接受连接，在 hello-ok 中返回 auth.deviceToken，封装程序会缓存该令牌，并在响应中显示 paired: true 以及已授予的作用域。
5. 此后，带作用域的工具（openclaw_cron_list、_status 等）即可正常使用。

安装

从 npm 安装（推荐）

claude mcp add openclaw-control -- npx -y openclaw-control-mcp

重启 Claude Code，然后跳转到配置。

从源代码安装（供贡献者使用）

git clone https://github.com/smurfy92/openclaw-control-mcp.git
cd openclaw-control-mcp
npm install
npm run build
claude mcp add openclaw-control -- node "$(pwd)/dist/index.js"

发布流程（通过 v*.*.* 标签，从 .github/workflows/publish.yml 同时发布到 npm 和官方 MCP Registry）记录在 CONTRIBUTING.md 中。

配置

封装程序需要 OpenClaw 网关的 WebSocket URL。公开的 Hostinger HTTPS 主机名不会暴露 WS 端点——你需要获取 Control 面板内部使用的 URL。

在浏览器中查找：

1. 打开 Control 面板并登录。
2. 在 DevTools 控制台中运行：

   Object.entries(localStorage).find(([k]) => k.startsWith("openclaw.control.settings.v1"))?.[1]
   

3. 复制 gatewayUrl 字段（通常为 ws://127.0.0.1:18789、Tailscale 地址 ws://100.x.y.z:18789，或专用的 wss://… 主机）。

与 Claude Code 配合使用

推荐：先注册，再在聊天中配置

这是最简便的方式——无需编辑 ~/.claude.json，也无需设置环境变量。安装后（通过 npx 或从源代码安装），在聊天中输入：

“使用网关 wss://your-gateway.example.com 和令牌 <your-token> 配置 OpenClaw”

Claude 会调用 openclaw_setup({ gatewayUrl, gatewayToken })，并将这些值保存到 ~/.config/openclaw-control-mcp/store.json（模式为 0600）。下一次调用 openclaw_device_status 时，会触发 WS 握手和配对流程。

openclaw_setup_show 会报告生效的配置；openclaw_setup_clear 会清除已保存的配置（不会影响设备身份／令牌）。

替代方案：由环境变量驱动

如果你更喜欢使用环境变量（它们的优先级高于已存储的配置），请编辑 ~/.claude.json：

"openclaw-control": {
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "openclaw-control-mcp"],
  "env": {
    "OPENCLAW_GATEWAY_URL": "wss://your-gateway.example.com",
    "OPENCLAW_GATEWAY_TOKEN": "<your-token>",
    "OPENCLAW_TIMEOUT_MS": "30000"
  }
}

重启 Claude Code，即可使用 openclaw_cron_list 等工具。

密钥与 .env 文件

服务绝不会访问你的操作系统密钥链——不会调用 security / secret-tool，不会弹出权限提示，也无需批准任何操作。从 0.8.0 开始，密钥只会按以下顺序从两个来源中解析：

#	来源	说明
1	实际环境变量	始终优先。OPENCLAW_GATEWAY_TOKEN=… npx -y openclaw-control-mcp 是有效的单次覆盖方式。
2	.env 文件	启动时加载到环境中。不会覆盖已设置的变量。
3	store.json（模式 0600）	openclaw_setup 和配对流程写入的内容。纯 JSON，位于你的配置目录中。

.env 候选文件按优先级从高到低排列：

1. $OPENCLAW_ENV_FILE — 显式路径
2. ./.env — 启动服务时所在的目录
3. ${XDG_CONFIG_HOME:-~/.config}/openclaw-control-mcp/.env

复制 .env.example，填写内容，然后运行 chmod 600 .env。如果其他用户也能读取该文件，服务会在 stderr 上发出警告。解析器刻意保持简洁——支持 KEY=value、export KEY=value、"quoted"、'''raw''' 和 # 注释——不会插值变量，因此密钥绝不会被展开或重新解释。

希望服务永远不将密钥写入磁盘？将 OPENCLAW_DEVICE_PRIVATE_KEY + OPENCLAW_DEVICE_TOKEN 放入 .env（可通过 npx tsx scripts/export-ci-secrets.ts 从已配对的安装中获取）。通过环境变量提供的身份信息会完全绕过存储。

--health 会报告已加载的 .env 文件以及它们提供的变量。

从 0.5.0 – 0.7.0 升级（移除密钥链）

这些版本会将密钥存放在操作系统密钥链中，并在 store.json 中留下空字段。请在下次会话前运行一次性导入，且只需运行一次：

npx -y openclaw-control-mcp --migrate-from-keychain

它会读取密钥链，将值写入 store.json（模式 0600），并打印现已不再使用的条目的 security delete-generic-password … / secret-tool clear … 命令——它本身绝不会删除密钥链中的任何内容。运行两次不会产生任何效果。这是该软件包中唯一会读取密钥链的代码路径；它会在该标志启用后动态导入，正常启动时绝不会运行。

如果你不想迁移，openclaw_device_repair 会清除孤立的设备，下次连接时会从头重新配对。

环境变量

变量	必需	描述
OPENCLAW_GATEWAY_URL	是	网关的 WebSocket URL（ws:// 或 wss://）
OPENCLAW_GATEWAY_TOKEN	建议	网关登录令牌
OPENCLAW_GATEWAY_PASSWORD	可选	额外密码（某些网关配置需要）
OPENCLAW_TIMEOUT_MS	可选	连接／请求超时时间（默认 30000）
OPENCLAW_DEBUG	可选	设为 1，将每个 WS 帧记录到 stderr
OPENCLAW_CONTROL_HOME	可选	覆盖用于持久化 store.json 的目录（默认为 ${XDG_CONFIG_HOME:-~/.config}/openclaw-control-mcp/）。旧版 OPENCLAW_CLAW_HOME 仍会作为后备读取。
OPENCLAW_ENV_FILE	可选	.env 文件的显式路径。在其他内容读取环境变量之前加载；优先级高于 ./.env 和 <configDir>/.env。请参阅密钥与 .env 文件。
OPENCLAW_HTTP	可选	设为 1，通过 /mcp 以 Streamable HTTP 而非 stdio 暴露 MCP。等同于传入 --http。
OPENCLAW_HTTP_PORT	可选	HTTP 端口（默认 3333）。等同于 --http-port=N。
OPENCLAW_HTTP_HOST	可选	HTTP 主机（默认 127.0.0.1）。等同于 --http-host=H。
OPENCLAW_MOCK	可选	设为 1（或传入 --mock），将 WebSocket 网关替换为内存中的 MockGateway。无需配置真实网关即可使用 MCP，适用于 CI、演示或试运行。状态保留在进程内，并在退出时丢弃。

多实例：按调用传入 instance 参数

每个工具都接受可选的 instance 字段，因此单个 MCP 无需先切换活动默认实例，即可连接多个网关：

// route this one call to the 'work' gateway, regardless of the active default
{ "name": "openclaw_cron_list", "arguments": { "instance": "work", "limit": 10 } }

使用 openclaw_setup({ instance: "work", gatewayUrl, gatewayToken }) 配置每个网关，使用 openclaw_setup_list 列出网关，并使用 openclaw_setup_select_default 切换活动默认实例。如果环境中设置了 OPENCLAW_GATEWAY_URL，它将覆盖所有设置（包括 instance 参数）——环境变量始终优先。

HTTP 模式

对于不支持 stdio 的客户端（Cursor、Continue、Cline、Zed、浏览器），可将 MCP 作为 Streamable HTTP 服务运行：

# Loopback (default 127.0.0.1:3333), no bearer — fine for local trust
npx -y openclaw-control-mcp --http --http-port=3333

# Same, but with bearer auth on (recommended even on loopback)
OPENCLAW_HTTP=1 OPENCLAW_HTTP_BEARER="$(openssl rand -hex 32)" \
  npx -y openclaw-control-mcp

# Bound to a public interface — bearer is REQUIRED (server refuses to start without)
OPENCLAW_HTTP=1 OPENCLAW_HTTP_HOST=0.0.0.0 OPENCLAW_HTTP_PORT=3333 \
  OPENCLAW_HTTP_BEARER="$(openssl rand -hex 32)" \
  npx -y openclaw-control-mcp

端点：POST/GET http://<host>:<port>/mcp（MCP Streamable HTTP，有状态——每个客户端都会获得自己的会话 ID）。stdio 仍是默认方式；只有显式启用后才会启动 HTTP 服务。

身份验证行为：

• 设置了 OPENCLAW_HTTP_BEARER → 每个 /mcp 请求都必须包含 Authorization: Bearer <token>。令牌不匹配或缺失时，会返回带有 WWW-Authenticate: Bearer realm="openclaw-control-mcp" 标头的 401 Unauthorized。比较采用恒定时间。
• 未设置 OPENCLAW_HTTP_BEARER 且绑定到环回地址 → 启动时会输出 stderr 警告。任何能够访问本地 shell 的人都可以调用所有工具。
• 未设置 OPENCLAW_HTTP_BEARER 且绑定到非环回主机（0.0.0.0、公网 IP 等）→ 服务拒绝启动。无身份验证的公网绑定存在被接管的风险，不可协商。

对于通过反向代理进行的长期部署，请在代理（nginx、Caddy、Traefik）上终止 TLS，并转发到 127.0.0.1:3333/mcp——Bearer 令牌也能保护代理到 MCP 的连接。

模拟模式（无需网关）

设置 OPENCLAW_MOCK=1（或传入 --mock），将 WebSocket 客户端替换为内存中的模拟客户端。适用于：

• CI — 无需连接实时网关即可运行测试／演示。
• 工作流演练 — 在连接生产环境之前，先对一系列 cron.add / cron.update / config.patch 调用进行试运行。
• 新手引导 — 无需配置网关实例即可试用 MCP。

# stdio
OPENCLAW_MOCK=1 npx -y openclaw-control-mcp
# or HTTP
OPENCLAW_MOCK=1 OPENCLAW_HTTP=1 npx -y openclaw-control-mcp

状态（添加的 cron 作业、配置补丁、会话）保留在进程内，并在退出时丢弃。模拟客户端会预置一个 cron 作业（sample-weekly）和一个会话，因此列表调用会返回非空结果。对于没有预设处理程序的方法，会返回 { mock: true, ok: true }，确保不会导致崩溃——可扩展 src/gateway/mock.ts，为其他方法添加专门处理。

Cron 模板（无需记忆计划语法）

cron.add 上的四个封装会为最常见的情况合成线格式：

// every Friday at 09:00 Paris, send a weekly digest to a Telegram channel
{ "name": "openclaw_cron_add_weekly", "arguments": {
    "name": "weekly-digest", "dayOfWeek": "fri", "hour": 9, "minute": 0,
    "tz": "Europe/Paris", "message": "Compose the weekly digest …",
    "channel": "telegram", "to": "-1001234567890"
}}

// every day at 07:00 UTC
{ "name": "openclaw_cron_add_daily", "arguments": {
    "name": "morning-check", "hour": 7, "tz": "UTC", "message": "Run the morning checks."
}}

// every 15 minutes (clock-agnostic)
{ "name": "openclaw_cron_add_every", "arguments": {
    "name": "ping", "intervalMinutes": 15, "message": "ping the upstream"
}}

// one-shot reminder, auto-deletes after firing
{ "name": "openclaw_cron_add_once", "arguments": {
    "name": "remind-meeting", "at": "2026-12-25T09:00:00+01:00",
    "message": "Don't forget the holiday call."
}}

四者都接受标准参数：agentId?、model?、timeoutSeconds?（默认值为 900）、channel? + to?、deliveryMode?（announce | direct | none）、instance?。

工具

143 个类型化工具封装了网关发布的 128 个 JSON-RPC 方法（以及 2 个独立的自省工具）。配对后运行一次 openclaw_introspect，即可查看特定网关上的实时方法和事件列表。

自省（无需作用域）

工具	说明
openclaw_introspect	返回服务器版本、你的角色和作用域，以及网关在其 hello-ok 中发布的完整 methods[] / events[] 列表。
openclaw_call	应急方案——使用任意参数调用任何 JSON-RPC 方法。适用于网关在发布版本之间新增方法的情况。如果有类型化封装，请优先使用。

设置（无需作用域）

工具	说明
openclaw_setup	将 { gatewayUrl, gatewayToken, gatewayPassword? } 保存到本地配置。
openclaw_setup_show	报告生效配置（环境变量或存储），不会打印令牌。
openclaw_setup_clear	清除已保存的网关配置。设备身份和令牌会保留。

设备与配对（device.pair.*、device.token.*）

openclaw_device_status / openclaw_device_pair_list / _pair_approve / _pair_reject / _pair_remove / openclaw_device_token_revoke / _token_rotate。管理你的本地 Ed25519 身份及为其签发的各网关令牌。

按领域划分的覆盖范围（需要 operator.read / operator.write / operator.admin）

领域	工具数	封装的 JSON-RPC 方法
cron	7	list status run runs add update remove
sessions	17	list preview create patch send abort reset delete compact compaction.{list,get,restore,branch} subscribe/unsubscribe messages.subscribe/unsubscribe
agents	7	list create update delete files.{list,get,set}
chat	3	send history abort
channels	2	status logout
logs	1	tail
models	1	list
usage	2	status cost
根状态	12	status health last-heartbeat set-heartbeats system-presence system-event wake send agent agent.identity.get agent.wait gateway.identity.get
config	6	get set patch apply schema schema.lookup
secrets	2	reload resolve
skills	6	status search detail install update bins
tools	2	tools.catalog tools.effective
exec.approval	9	list get request resolve waitDecision + 全局 / 按节点策略 get/set
plugin.approval	4	list request resolve waitDecision
wizard	4	start next cancel status
doctor.memory	7	status dreamDiary backfillDreamDiary dedupeDreamDiary repairDreamingArtifacts resetDreamDiary resetGroundedShortTerm
node	16	list describe invoke + invoke.result event rename pair.{request,verify,approve,reject,list} pending.{ack,drain,enqueue,pull} canvas.capability.refresh
tts	6	status enable disable providers setProvider convert
talk	3	config mode speak
voicewake	2	get set
其他	3	update.run commands.list message.action

工具名称遵循 openclaw_<domain>_<method> 格式。方法名称中的点会转换为下划线：cron.list → openclaw_cron_list，sessions.compaction.restore → openclaw_sessions_compaction_restore。

破坏性工具

这些工具会产生破坏性副作用（数据丢失、服务中断、访问权限撤销）。其 description 会对此进行标记，因此 Claude Code 的确认机制会在每次调用前提示确认：

• Cron：cron_remove、cron_run（实际执行）、cron_update
• Sessions：sessions_{abort,reset,delete,compaction_restore}
• Agents：agents_{delete,files_set}
• Chat：chat_abort
• Channels：channels_logout
• Device：device_{pair_remove,token_revoke,token_rotate}
• Config：config_{set,patch,apply}
• Secrets：secrets_resolve（返回密钥内容）
• Doctor memory：doctor_memory_{resetDreamDiary,resetGroundedShortTerm,repairDreamingArtifacts,backfillDreamDiary,dedupeDreamDiary}
• Node：node_{invoke,rename,pending_drain,pending_enqueue,pending_ack,pair_approve,pair_reject}
• Skills：skills_{install,update}
• Approvals：exec_approval_resolve、exec_approvals_{set,node_set}、plugin_approval_resolve
• Self-update：update_run（影响整个网关，可能中断会话）

示例

与 MCP 配对后，可直接复制并粘贴到 Claude 中的提示词。每条提示词都会调用相应的工具，并展示如何通过自然语言表达来触发具体调用。

健康状态与基本检查

> Run a full openclaw health check.

→ 调用 openclaw_health，报告 MCP 版本、网关服务版本、已配对设备的指纹、已授予的作用域，以及上次成功调用距今的时间。

> What gateway methods do I have access to right now?

→ 调用 openclaw_introspect，返回网关在其 hello-ok 中发布的 128 个 JSON-RPC 方法和 24 个事件。

Cron

> List all openclaw cron jobs, including disabled ones.

→ openclaw_cron_list({ enabled: "all" })。

> Show me the last 5 runs of cron job <id> — compact mode, just the summaries.

→ openclaw_cron_runs({ id: "<job-id>", limit: 5, compact: true }) — 摘要截断至 200 个字符，每条记录都会添加 runAtAgo: "3d ago" 字段。

> Create a cron that runs every Friday at 1pm Paris and posts a summary to Telegram group -1001234567890.

→ 生成 openclaw_cron_add 负载，并设置正确的 schedule.kind: "cron"、expr: "0 13 * * 5"、tz: "Europe/Paris" 和 delivery.mode: "announce"。

Sessions

> List the 10 most recent active openclaw sessions, ranked by last activity.

→ openclaw_sessions_list({ limit: 10, sortBy: "updatedAt", sortDir: "desc" })。

> Show me the last 8 messages of session agent:main:cron:<id>.

→ openclaw_sessions_preview({ keys: ["agent:main:cron:<id>"] }) — 直接从网关返回角色／文本轮次。

Agents 与 Channels

> List the agents configured on this gateway and which model they use.

→ openclaw_agents_list。

> What's the connection state of my Telegram channel?

→ openclaw_channels_status。

紧急通道

> Use openclaw_call to invoke "config.schema" with no params and return the keys it exposes.

→ 当网关端的方法尚无类型化封装，或你想检查仍处于测试阶段的功能时，此工具会很有用。

弹性

request() 会针对暂时性错误（网络中断、WebSocket 关闭、超时、DNS）采用指数退避进行重试：默认间隔为 1 秒 → 2 秒 → 4 秒，最多尝试 4 次。不可重试的错误（PAIRING_REQUIRED、INVALID、MISSING_SCOPE 等）会立即失败——重试权限问题没有意义。可通过以下选项调整：

• OPENCLAW_RETRY_ATTEMPTS — 尝试总次数（默认值为 4，范围 1–10）
• OPENCLAW_RETRY_BASE_MS — 初始退避时间，单位为毫秒（默认值为 1000，范围 100–60000）
• OPENCLAW_DEBUG=1 — 将每次重试决策输出到 stderr

请求放弃重试时，抛出的错误会以 gateway request '<method>' failed (attempt N/M): 为前缀，并将原始错误保留为 cause 以供检查。GatewayError 的 code／details／retryable 标志会在错误封装时保留。

客户端会跟踪 lastSuccessAtMs，供 openclaw_health 的 lastSuccessAgo 字段使用——这对调试“网关还在和我通信吗？”很有帮助。

诊断命令行工具

无需将 MCP 接入客户端，即可执行一次性健康检查：

npx -y openclaw-control-mcp --health

打印 JSON 报告（MCP 版本、网关 URL、配对状态、作用域、服务版本、距上次成功的时间，以及错误信息〔如有〕），并在失败时以非零状态码退出。适用于 CI／脚本。

Schema 宽松性

大多数 v0.3.0 封装器对 params 使用 z.passthrough()——它们接受文档中列出的字段以及其他任意字段，并将其传递给网关。这种做法以放弃严格的客户端验证为代价，换取向前兼容：随着网关演进，调用不会因新增字段而中断。缺点是，只有在网关拒绝请求时，你才会发现字段有误。如果遇到“缺少必需属性”错误，请查看网关的响应——它会告诉你确切的线上数据格式——然后更正调用，或提交 issue / PR 来收紧封装器的 Zod schema。

威胁模型

此 MCP 服务会向操作员通过自然语言驱动的 LLM 暴露包含机密和具有副作用的网关操作（config.*、secrets.*、cron.run、sessions.send、agent、频道发送）。请谨慎对待这一操作面：

• 网关令牌、设备私钥和每个网关的设备令牌会保存在 ${XDG_CONFIG_HOME:-~/.config}/openclaw-control-mcp/store.json 下（文件模式为 0600）。从 0.8.0 开始，服务绝不会访问你的操作系统密钥链——不会调用 security / secret-tool，也不会请求权限。如果你不希望服务将任何机密写入磁盘，请改用 .env 文件提供这些信息（参见机密信息与 .env 文件）。切勿提交 store 或 .env 文件，也不要未经脱敏就发布 --health 输出。
• openclaw_secrets_set 会通过 config.patch 写入网关配置树。任何调用此封装器的工具调用，都会在网关端轮换相应的底层机密。在 Agent 提示词中使用它时，应明确要求人工确认。
• openclaw_call 是一个逃生口——它会转发任意 JSON-RPC 方法调用。网关会强制执行每个作用域的权限，但客户端没有输入过滤器。如果不可信提示词可能触达 Agent，请限制 Agent 可见的工具目录。
• OPENCLAW_DEVICE_PRIVATE_KEY / OPENCLAW_DEVICE_TOKEN 环境变量（用于无头 / CI / 服务账户场景）优先于 store。只能在可信的执行环境中设置它们（GitHub secrets、K8s secrets、密码管理器导出内容、chmod 600 的 .env 文件——绝不能放在 shell 历史记录、Docker --env 中，或提交到仓库的 .env 文件中）。
• 提示词注入面：网关的响应（会话预览、日志、Agent 输出）会反馈给 MCP 客户端，其中可能包含攻击者控制的内容。在决定是否调用破坏性工具时，应将所有工具输出视为不可信内容（破坏性工具列表见 §破坏性工具——在将写入工具与读取工具的输出串联调用前，请先确认）。
• HTTP 传输面：使用 --http 运行时，如果设置了 OPENCLAW_HTTP_BEARER，服务会执行恒定时间的 Bearer 检查；没有该变量时，会拒绝绑定到非环回接口；如果在环回接口上启动但未设置该变量，则会在 stderr 输出醒目的警告。像轮换网关管理员令牌一样轮换 Bearer 令牌——任何能读取该令牌的主体都可以调用所有工具，包括写入 secrets.* 的工具。在将 HTTP 端口暴露到网络前，请先通过反向代理终止 TLS。

如果你发现漏洞，请在 GitHub 上提交私密安全公告，而不是公开 issue：https://github.com/smurfy92/openclaw-control-mcp/security/advisories/new.

路线图

• 自动重连并采用指数退避——已在 0.3.1 中发布（client.request() 会使用抖动进行重试；自 0.4.0 起，可通过 OPENCLAW_RETRY_ATTEMPTS / OPENCLAW_RETRY_BASE_MS 调整）。
• 将会话消息流回 MCP 客户端（目前，sessions.subscribe 会在服务端注册，但 stdio 无法将增量内容传递给 Claude Code）。
• 收紧 0.3.0 中新增封装器的 Zod schema——在完全确定各领域的网关结构之前，大多数封装器都使用 passthrough()。欢迎提交 PR。
• 除 stdio 外，支持 Streamable HTTP 传输——已在 0.5.0 中发布（--http、http://127.0.0.1:3333/mcp）；已在 0.7.0 中添加 bearer 令牌身份验证（OPENCLAW_HTTP_BEARER）。参见 ADR-005。
• Claude Desktop Extension（.mcpb）打包。

从 openclaw-claw-mcp 迁移（早期用户）

如果你使用过此前名称下的封装器（openclaw-claw-mcp）：

• 新路径为空时，Store 会自动将 ~/.config/openclaw-claw-mcp/store.json 作为备用路径读取，因此已配对的设备令牌仍可正常使用。
• 下次成功连接时，将创建新路径（~/.config/openclaw-control-mcp/store.json）。之后即可删除旧目录。
• 将 ~/.claude.json 中的条目名称从 openclaw-claw 改为 openclaw-control（仅影响外观——只会更改工具前缀 mcp__openclaw-control__*）。
• 本地工作目录 / 构建输出仍保留你克隆到的路径；其他内容无需迁移。

故障排除

• gateway request '…' failed: expected Uint8Array of length 32, got length=0——持久化的 device.privateKey 为空。在 0.8.0+ 中，通常是因为从 0.5.0–0.7.0 升级时密钥仍保存在操作系统密钥链中：运行一次 npx -y openclaw-control-mcp --migrate-from-keychain。否则，可使用 openclaw_device_repair 恢复。背景说明：docs/troubleshooting/empty-private-key.md。
• gateway request '…' failed: device nonce mismatch 在一段时间空闲后出现——WS 连接已失效，重试循环重复使用了已失效的 nonce。解决方法：使用相同参数再次调用 openclaw_setup（强制执行新的握手）。详情及拟议的修复方案：docs/troubleshooting/stale-connection-nonce-mismatch.md。

注意事项

• 该协议是通过逆向工程得出的，并无文档说明。网关更新可能会导致行为改变。
• 连接帧与 openclaw/openclaw/scripts/dev/gateway-smoke.ts 当前发送的内容一致（client.id: "openclaw-ios"、mode: "ui"，角色和作用域遵循 iOS 操作端的默认值）。不同的 client.id 会触发不同的服务端策略——例如，openclaw-control-ui 和 openclaw-tui 都要求设备身份 以及 安全上下文来源。
• OPENCLAW_DEBUG=1 会将每个 WS 帧记录到 stderr（截断至 8 KB）。在将握手与实时 Control 面板 SPA 进行比较时很有用。