openclaw-mcp-bridge
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@openclaw-mcp-bridge 让助手看一下今天的安排"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
openclaw-mcp-bridge
OpenClaw as MCP — expose OpenClaw agents to any MCP-compatible agent. Example: Qwen glasses → Qoder → OpenClaw.
把本机 OpenClaw 的 agent 暴露成标准 MCP 工具,任何支持 MCP 的客户端都能调用;典型链路是千问眼镜 → Qoder CN → OpenClaw。
功能
🎤 语音控制: 通过千问眼镜语音下发任务到 OpenClaw agent
🔀 多 Agent 支持: agent 白名单、别名、权限等级全部在
config.json里配置🎯 智能路由: 点名即执行;未点名时使用
defaultAgent(建议指向权限最小的 agent)📊 状态查询: 实时查询任务状态、读取历史、取消任务
🔊 语音优化: 自动提取首句播报,长回复标记需要总结
🔒 安全隔离: 会话锁、限流、审计、无 token 泄漏
Related MCP server: OpenClaw MCP Proxy
从零到能用
整条链路是这样的:
千问眼镜(语音)
→ Qoder CN 远程控制会话(跑在这台 Mac 上)
→ openclaw-mcp-bridge(stdio MCP)
→ openclaw CLI → OpenClaw Gateway → agent1. 在 Mac 上装 Qoder CN
装 Qoder CN 桌面版,不是 Qoder 国际版——两者是独立产品,配置目录也不同(CN 是 ~/.qoder-cn/,国际版是 ~/.qoder/),本项目只在 CN 桌面端验证过。
登录后确认远程控制 / 远程会话可用:眼镜侧正是以这种会话的形式,把任务发到你这台 Mac 上执行。
会话必须在本机执行。如果 Qoder 把任务委派到云端,云端进程访问不到你本机的 stdio MCP,这条链路就断了。
2. 千问眼镜绑定 Qoder CN
在千问 App 或眼镜端按官方引导绑定 Qoder CN 账号(通常是扫码登录授权)。绑定后,你对眼镜说的话会变成一个 Qoder CN 远程控制会话。具体入口和按钮名称可能随版本变化,以千问和 Qoder 当前的引导为准。
绑好后先验证一次:对眼镜说一句话,确认 Qoder CN 里出现了对应会话,并且它是在这台 Mac 上执行的。
3. 在这台 Mac 上安装本项目
前置条件:
Node.js ≥ 20(本项目在 v23 上测试)
本机已安装并登录 OpenClaw,且 Gateway 正在运行(
openclaw gateway status)桥接本身不需要任何 token:它复用
openclawCLI 的本机认证
git clone https://github.com/rainow/openclaw-mcp-bridge.git
cd openclaw-mcp-bridge
npm install
cp config.example.json config.json # 然后按你的 agent 名单改 config.jsonconfig.json 至少改这三处:allowedAgents 填 openclaw agents list 里真实存在的 agent ID;aliases 填语音里好念的名字;defaultAgent 建议指向权限最小的那个。
装完先手动跑一次,确认配置和 Gateway 都通:
npm start看到 [openclaw-mcp-bridge] Server started (OpenClaw …) 就说明没问题,Ctrl+C 退出即可——正常使用时这个进程由 Qoder 拉起,不需要你手动常驻。
config.json 写的是你本人的 agent 名单、别名和权限,不要提交到版本库。缺少它时服务器会回退到 config.example.json 并在 stderr 提示。
4. 在 Qoder CN 里配置 MCP
设置 → 扩展(Extensions)→ 连接器(Connectors)→ 添加自定义 MCP,传输方式选 stdio:
名称:
openclaw-mcp-bridge命令:
node的绝对路径(如/opt/homebrew/bin/node),不要只写node参数:
/绝对路径/openclaw-mcp-bridge/server.mjs工作目录:
/绝对路径/openclaw-mcp-bridge
参数和工作目录都必须是绝对路径。保存后如果工具里没出现这 5 个工具,对该服务器执行一次 retry,或重开会话。改过 server.mjs / lib/openclaw.mjs 之后同理,运行中的进程不会热更新。
桥接进程由 Qoder 按需拉起,不需要、也不应该做成系统级自启动任务(stdio 服务器脱离父进程就没有意义)。需要常驻的是 OpenClaw Gateway,是否让它开机自启由你决定。
5. 验证
在 Qoder CN 的新会话里说"列出可用的 OpenClaw agent",或直接在眼镜上说"让助手看一下今天的安排"(把"助手"换成你 aliases 里的名字)。第一次调用会先读 MCP 工具目录,这是客户端的懒加载行为,正常现象。
为什么不用在每个会话里教它
这个桥接不需要你在每个会话里重复解释自己会什么,用法写在两个地方:
服务器级
instructions:initialize时就返回,告诉任意 MCP 客户端"先oc_agents拿本机 agent 名单,再oc_run派活,running就oc_wait,别重复下发"。每个工具的
description:把同一段协议拆开写进各自工具里,所以客户端只要列出工具就能读全用法。这两处是用法的主来源,改动时要一起更新,别只改其中一边。
实测差异(Qoder CN 桌面端 0.x,2026-10-22):服务器 instructions 会正常出现在 initialize 响应里,但 Qoder 不会把它注入会话上下文;它注入的是"服务器名 + 工具名"的延迟目录。真正起作用的是工具 description —— 一个全新会话在完全没被提示的情况下,自己走 mcp_list / mcp_get 读到用法,再调 oc_agents 定位到本机的 agent,然后完成任务。所以配完就能用,但你依然可以直接说"让某某去做某事"。
MCP 工具
oc_agents
列出所有可用的 OpenClaw agent。
参数:
refresh(boolean, 可选): 强制刷新缓存
返回:
{
"openclawVersion": "2026.6.11",
"gatewayOk": true,
"agents": [...],
"defaultAgent": "main",
"cached": false
}oc_run
向指定 agent 下发任务。
参数:
message(string, 必填): 任务消息agent(string, 可选): Agent 名字或 ID,默认取config.json的defaultAgentwait_seconds(number, 可选): 同步等待秒数,默认 20,最大 120idempotency_key(string, 可选): 幂等键,5 秒内相同 key 不重复下发
返回:
{
"status": "done",
"runId": "req-xxx",
"agentId": "main",
"sessionKey": "agent:main:glasses",
"reply": "任务回复内容",
"voice": {
"speak": "播报文本(≤150 字符)",
"kind": "text",
"needsSummary": false,
"textLength": 100
},
"replyTruncated": false
}oc_wait
查询或等待任务状态。
参数:
runId(string, 必填): 任务 runIdtimeout_seconds(number, 可选): 等待秒数,0 表示立即返回
返回:
{
"status": "done",
"runId": "req-xxx",
"stopReason": "stop",
"startedAt": 1700000000000,
"endedAt": 1700000005000,
"voice": {...}
}oc_last
读取指定 agent 的 glasses 会话历史。
参数:
agent(string, 可选): Agent 名字或 ID,默认取config.json的defaultAgentlimit(number, 可选): 返回消息条数,默认 10
返回:
{
"agentId": "main",
"sessionKey": "agent:main:glasses",
"messages": [...],
"reply": "最后一条 assistant 回复",
"voice": {...},
"replyTruncated": false
}oc_cancel
取消指定任务。
参数:
runId(string, 必填): 任务 runId
返回:
{
"ok": true,
"status": "aborted",
"abortedRunId": "req-xxx"
}配置
config.example.json 是最小可用配置,复制成 config.json 后按需修改:
{
"defaultAgent": "main",
"allowedAgents": ["main", "coder"],
"disabledAgents": [],
"aliases": { "助手": "main", "coder": "coder" },
"execRisk": { "main": "allow", "coder": "allow" },
"session": { "suffix": "glasses", "maxKeyLength": 200 },
"rateLimit": { "perMinute": 6, "perHour": 60 },
"voice": { "maxSpeakChars": 150, "summaryThreshold": 400 },
"run": { "defaultWaitSeconds": 20, "maxWaitSeconds": 120, "cliTimeoutMs": 30000, "rpcTimeoutMs": 15000 },
"dedupe": { "windowSeconds": 5 },
"audit": { "dir": "~/Library/Application Support/openclaw-mcp-bridge" }
}几个字段的含义:
allowedAgents/disabledAgents: 允许、禁止通过桥接下发的 agent ID(ID 来自openclaw agents list)。aliases: 语音里更好念的名字 → agent ID。前缀匹配也能命中。execRisk: 仅作提示位,记录该 agent 是否有 exec 权限;桥接不会修改 OpenClaw 的权限策略。run.rpcTimeoutMs/maxWaitSeconds: 每次gateway call显式带--timeout,等待时长由请求换算(见 DESIGN §超时)。session.suffix: 会话键后缀,把眼镜侧的会话和其他来源隔离开。
环境变量
OPENCLAW_BIN: OpenClaw 可执行文件路径(默认/opt/homebrew/bin/openclaw)OPENCLAW_NODE_BIN: Node.js 可执行文件路径(默认process.execPath)OPENCLAW_BRIDGE_HOME: 审计日志目录(默认~/Library/Application Support/openclaw-mcp-bridge)
安全
✅ 不暴露 Gateway token、exec-approvals token
✅ 不修改 OpenClaw agent 权限
✅ 审计日志本地存储,权限 0700/0600
✅ 无公网入口
已知限制
会话锁是内存状态:Gateway 重启或桥接进程重启后会丢失,需要重新下发。
回复可能被 Gateway 截断(
replyTruncated)或读取失败(replyUnavailable),此时用oc_last再取一次。语音分类走启发式,极简的无文件头 diff 可能被判成普通文本;
voice.kind只作播报提示。真实提交响应丢失时,桥接会用已知的
runId对账并按running处理——健康的 Gateway 无法区分"从未受理"和"仍在排队",此时用oc_cancel是可靠的恢复手段。
许可证
MIT
Available Tools
5 toolsoc_agentsA
列出本机 OpenClaw 可用的 agent:id、名字、别名、是否默认、execRisk(allow=可落地动作,deny=只读或纯回复)。agent 名单来自本机的 config.json,每台机器都不同——用户提到某个名字、或你不确定能点名谁时,先调本工具确认,不要凭猜测点名。返回的 name 或 aliases 可以直接当作其他工具的 agent 参数。结果缓存 60 秒,refresh=true 强制刷新。Gateway 不在时返回 GATEWAY_UNAVAILABLE。语音场景只报名字和默认 agent,不要把 JSON 读出来。
Inputs: refresh.
oc_cancelA
取消 runId 对应的任务,成功返回 status=aborted。只有用户明确说要停掉/取消时才调用,成功后用一句话确认,不要念底层字段。Gateway 上已无活动任务时视为幂等成功(no-active-run),并释放本桥接的会话锁——因此任务长时间悬挂在 running、或 SESSION_BUSY 挡住新任务时,取消它是最可靠的恢复手段。
Inputs: runId (required).
oc_lastA
读取指定 agent 的 glasses 会话最近 limit 条消息(默认 10,最大 50),返回最后一条 assistant 回复和 voice 播报元数据。用于 runId 丢失、桥接进程重启、或需要确认“刚才那个任务”说了什么。只播报最后一条 assistant 的内容概要,不要把历史逐条读出来。它只反映历史,不代表任务当前是否在运行——查状态请用 oc_wait;手上没有 runId 时也不要据此断言“还在跑”或“已完成”。
Inputs: agent, limit.
oc_runA
向指定 agent 下发任务,并同步等待最多 wait_seconds(默认 20,最大 120)。 参数:agent 填 oc_agents 返回的名字或别名,留空则使用 config.json 里的 defaultAgent;用户点名的 agent 不在 oc_agents 列表里时不要调用本工具,直接告诉用户没有这个 agent。message 只放任务本身,不要带“让某某做”的转述。 安全:任务会被 agent 在本机真实执行,不是模拟。删除、格式化、重启、对外发送消息等破坏性动作先跟用户确认;下发时尽量限定范围。 返回判读:status=done 时 reply 是完整结果,voice.speak 是适合朗读的短句——语音场景只播报 voice.speak,reply 只用于屏幕查看或回答追问,不要整段朗读;voice.needsSummary 或 replyTruncated=true 表示内容偏长或被截断,此时用 1–3 句话总结 reply,不要朗读代码、日志、diff、JSON、URL 或长列表;voice 提示可能含敏感信息时不要复述具体值。status=running 表示仍在跑,请用返回的 runId 调 oc_wait 继续等,不要重复调用本工具;同一会话已有任务时会返回 SESSION_BUSY 并带上当前 runId;submitReconciled=true 表示提交响应丢失但已确认任务在跑,按 running 处理。 限流默认 6 次/分钟,超限返回 RATE_LIMITED 与重试时间,不要立刻重发。
Inputs: message (required), agent, wait_seconds, idempotency_key.
oc_waitA
按 runId 继续等待或查询已下发的任务,最多 timeout_seconds(0=只查状态不等待,默认 0)。刚下发还没结果、或用户问“怎么样了”时用。done 时返回本轮 reply 与 voice 元数据,按 voice.speak 播报或做 1–3 句总结;running 表示还在跑,只播报状态和已用时间,不要翻历史、不要猜进度,可以再调本工具;aborted/error 看 stopReason 和 error,并说清结果与下一步。任务已经结束后再调仍然能取到本轮回复。replyUnavailable=true 只是没读到回复,可改用 oc_last 查看。任何时候都不要因为本工具重复下发任务。
Inputs: runId (required), timeout_seconds.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool owns a distinct phase of the lifecycle: oc_agents discovers targets, oc_run dispatches, oc_wait polls a known runId, oc_last recovers history without a runId, and oc_cancel aborts. The descriptions explicitly pre-empt the likely confusions (wait vs. last, running vs. history) and state when not to use each tool.
All tools share a consistent oc_ prefix and snake_case, which makes the family instantly recognizable. The only minor deviation is that oc_agents is a plural noun while the rest are verbs (run/wait/last/cancel), but this is readable and predictable.
Five tools is tight and well-scoped for a bridge to a local agent gateway; every tool covers a non-redundant operation with no filler. Nothing suggests a missing sibling or an over-stuffed surface.
The dispatch lifecycle — discover agents, run, poll, recover history, cancel — is fully covered, including recovery paths for lost runIds and stuck sessions. Minor gaps remain: there is no tool to enumerate active runs across agents or to check gateway/health status other than error codes like GATEWAY_UNAVAILABLE.
Maintenance
Related MCP Connectors
Hosted MCP runtime where your agent publishes its own tools by tool call and keeps working.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Discover and call AI agents via MCP. Supports A2A agents and platform agents with async tasks.
Host any HTTP API as a standard MCP server; auto-distribute to 12+ mainstream agent platforms.
Related MCP Servers
- AlicenseBqualityFmaintenanceExposes OpenClaw tools (web search, page fetching, browser automation, PDF analysis, messaging, inter-agent communication, Canvas) as MCP tools for ACP agents.7-
- FlicenseNot gradedqualityDmaintenanceExposes app-registered tools as an MCP server for OpenClaw, forwarding actual tool execution back to the app over a WebSocket bridge.-
- AlicenseNot gradedqualityBmaintenanceExposes Agentweaver runs and outcomes as MCP tools for Claude Desktop and compatible clients.7MIT
- FlicenseNot gradedqualityDmaintenanceEnables interaction with OpenClaw agents via MCP, supporting natural language queries and session management.3-