将 OpenClaw 作为 MCP 服务器运行

本页介绍 openclaw mcp serve 路径：OpenClaw 通过 stdio 作为 MCP 服务器运行，并介绍其工具、事件模型及限制。

OpenClaw 作为 MCP 服务器¶

这是 openclaw mcp serve 路径。

何时使用 serve¶

在以下情况下使用 openclaw mcp serve：

• Codex、Claude Code 或其他 MCP 客户端需要直接与 OpenClaw 支持的渠道会话进行交互
• 你已经拥有带路由会话的本地或远程 OpenClaw Gateway
• 你希望一个 MCP 服务器即可跨 OpenClaw 的渠道后端工作，而不是为每个渠道分别运行桥接器

当 OpenClaw 需要自行托管编码运行时并将 agent 会话保留在 OpenClaw 内部时，请改用 openclaw acp。

工作原理¶

openclaw mcp serve 启动一个 stdio MCP 服务器。该进程由 MCP 客户端持有。当客户端保持 stdio 会话打开时，桥接器通过 WebSocket 连接到本地或远程 OpenClaw Gateway，并通过 MCP 暴露路由渠道会话。

1. 客户端启动桥接器

MCP 客户端启动 openclaw mcp serve。

2. 桥接器连接 Gateway

桥接器通过 WebSocket 连接到 OpenClaw Gateway。

3. 会话成为 MCP 对话

路由会话成为 MCP 对话，并转化为 transcript/历史工具。

4. 实时事件排队

桥接器连接期间，实时事件在内存中排队。

5. 可选的 Claude 推送

如果启用了 Claude 渠道模式，同一会话还可以接收 Claude 专属推送通知。

选择客户端模式¶

serve 暴露的内容¶

桥接器使用 Gateway 现有的会话路由元数据来暴露基于渠道的对话。当 OpenClaw 已经拥有带已知路由的会话状态时，对话即会出现，例如：

• channel
• 接收方或目的地元数据
• 可选的 accountId
• 可选的 threadId

这为 MCP 客户端提供了一个统一入口，用于：

• 列出最近的已路由对话
• 读取最近的 transcript 历史
• 等待新的入站事件
• 通过相同路由发送回复
• 查看桥接器连接期间到达的审批请求

用法¶

openclaw mcp serve

openclaw mcp serve --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

openclaw mcp serve --url wss://gateway-host:18789 --password-file ~/.openclaw/gateway.password

openclaw mcp serve --verbose
openclaw mcp serve --claude-channel-mode off

桥接器工具¶

事件模型¶

桥接器在连接期间维护一个内存事件队列。

当前事件类型：

• message
• exec_approval_requested
• exec_approval_resolved
• plugin_approval_requested
• plugin_approval_resolved
• claude_permission_request

Claude 频道通知¶

桥接器还可以暴露 Claude 专用的频道通知。这是 OpenClaw 对 Claude Code 频道适配器的等价实现：标准 MCP 工具仍然可用，但实时入站消息也可以作为 Claude 专用的 MCP 通知到达。

当 Claude 频道模式启用时，服务器会通告 Claude 实验性能力，并可以发出：

• notifications/claude/channel
• notifications/claude/channel/permission

当前桥接器行为：

• 入站 user 转录消息将作为 notifications/claude/channel 转发
• 通过 MCP 收到的 Claude 权限请求会在内存中跟踪
• 如果链接会话中的命令所有者随后发送 yes <id> 或 no <id>（<id> 是 5 个字母的请求 ID，不含 l），桥接器会将其转换为 notifications/claude/channel/permission
• 这些通知仅限实时会话；如果 MCP 客户端断开连接，则没有推送目标

这是有意设计为客户端专用的。通用 MCP 客户端应依赖标准轮询工具。

MCP 客户端配置¶

stdio 客户端配置示例：

{
  "mcpServers": {
    "openclaw": {
      "command": "openclaw",
      "args": [
        "mcp",
        "serve",
        "--url",
        "wss://gateway-host:18789",
        "--token-file",
        "/path/to/gateway.token"
      ]
    }
  }
}

对于大多数通用 MCP 客户端，请从标准工具界面开始，并忽略 Claude 模式。仅对真正理解 Claude 专用通知方法的客户端启用 Claude 模式。

选项¶

openclaw mcp serve 支持：

--url string (path)

Gateway WebSocket URL。配置后默认为 gateway.remote.url。

--token string (path)

Gateway 令牌。

--token-file string (path)

从文件读取令牌。

--password string (path)

Gateway 密码。

--password-file string (path)

从文件读取密码。

--claude-channel-mode "auto" | "on" | "off" (path)

Claude 通知模式。默认为 auto。

-v, --verbose boolean (path)

在 stderr 上输出详细日志。

安全与信任边界¶

桥接器不会凭空创建路由。它只暴露 Gateway 已经知道如何路由的会话。

这意味着：

• 发送者允许列表、配对和频道级信任仍然属于底层 OpenClaw 频道配置
• messages_send 只能通过现有存储的路由进行回复
• 审批状态仅存在于当前桥接器会话的实时内存中
• 桥接器身份验证应使用与任何其他远程 Gateway 客户端相同的 Gateway 令牌或密码控制

如果某个会话在 conversations_list 中缺失，通常原因不是 MCP 配置。而是底层 Gateway 会话中缺少或不完整的路由元数据。

测试¶

OpenClaw 为此桥接器提供了一个确定性的 Docker 冒烟测试：

pnpm test:docker:mcp-channels

该冒烟测试运行单个容器：它预置会话状态，启动 Gateway，然后将 openclaw mcp serve 作为 stdio 子进程启动，并作为 MCP 客户端驱动它。它验证会话发现、转录读取、附件元数据读取、实时事件队列行为，以及通过真实 stdio MCP 桥接器的 Claude 风格频道和权限通知。出站发送路由（messages_send 重用存储的会话路由）由 src/mcp/channel-server.test.ts 中的单元测试另行覆盖。

这是在测试运行中无需接入真实的 Telegram、Discord 或 iMessage 账户即可证明桥接器工作的最快方式。

有关更广泛的测试上下文，请参阅 测试。

故障排除¶

当前限制¶

该桥接存在以下限制：

• 会话发现依赖于现有的 Gateway 会话路由元数据
• 除 Claude 专用适配器外，没有通用推送协议
• 没有消息编辑或表情回应工具
• HTTP/SSE/streamable-http 传输连接到单个远程服务器；上游连接不会多路复用
• permissions_list_open 仅包含桥接连接期间观察到的审批