古法编程

Appearance

openclaw mcp ​

openclaw mcp 有两个职责：

  • 用 openclaw mcp serve 将 OpenClaw 作为 MCP 服务器运行
  • 用 list、show、set、unset 管理 OpenClaw 持有的出站 MCP 服务器定义

换句话说：

  • serve 是 OpenClaw 作为 MCP 服务器对外提供服务
  • list / show / set / unset 是 OpenClaw 作为 MCP 客户端注册表，为其他运行时存储 MCP 服务器配置

如果你想让 OpenClaw 自己托管一个代码助手会话并通过 ACP 路由，请使用 openclaw acp。

openclaw mcp serve：将频道会话暴露给 MCP 客户端 ​

什么时候用 serve ​

满足以下条件时使用 openclaw mcp serve：

  • Codex、Claude Code 或其他 MCP 客户端需要直接访问 OpenClaw 管理的频道会话
  • 你已有本地或远程 OpenClaw Gateway，且有可路由的会话
  • 想用一个 MCP 服务器统一访问 OpenClaw 各渠道（Slack、Telegram、iMessage 等），而非为每个渠道单独搭桥

想让 OpenClaw 自己托管代码运行时并将 Agent 会话保留在 OpenClaw 内部时，改用 openclaw acp。

工作原理 ​

openclaw mcp serve 启动一个 stdio MCP 服务器，由 MCP 客户端负责拉起该进程。客户端保持 stdio 会话期间，桥接器通过 WebSocket 连接到本地或远程 OpenClaw Gateway，并将已路由的频道会话暴露为 MCP 工具。

生命周期：

  1. MCP 客户端拉起 openclaw mcp serve
  2. 桥接器连接到 Gateway
  3. 已路由的会话变为 MCP 会话和历史/记录工具
  4. 实时事件在桥接器连接期间在内存中排队
  5. 如果启用了 Claude 频道模式，同一会话也可接收 Claude 专属推送通知

重要行为：

  • 实时队列从桥接器连接时开始
  • 较早的历史记录通过 messages_read 读取
  • Claude 推送通知只在 MCP 会话存活期间有效
  • 客户端断开连接后，桥接器退出，实时队列消失

选择客户端模式 ​

同一个桥接器支持两种用法：

  • 通用 MCP 客户端：仅使用标准 MCP 工具（conversations_list、messages_read、events_poll、events_wait、messages_send 以及审批工具）
  • Claude Code：标准 MCP 工具 + Claude 专属频道适配器。启用 --claude-channel-mode on 或保持默认 auto

目前 auto 行为与 on 相同，尚无客户端能力检测。

serve 暴露的内容 ​

桥接器利用 Gateway 会话中已有的路由元数据来暴露频道支持的会话。满足以下条件的会话才会出现：

  • channel（渠道类型）
  • 接收者或目标元数据
  • 可选 accountId
  • 可选 threadId

这让 MCP 客户端可以在一处完成：

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

用法 ​

bash
# 本地 Gateway
openclaw mcp serve

# 远程 Gateway（token 文件认证）
openclaw mcp serve --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

# 远程 Gateway（密码认证）
openclaw mcp serve --url wss://gateway-host:18789 --password-file ~/.openclaw/gateway.password

# 启用详细日志
openclaw mcp serve --verbose

# 禁用 Claude 专属推送通知
openclaw mcp serve --claude-channel-mode off

桥接工具 ​

当前桥接器暴露以下 MCP 工具：

  • conversations_list
  • conversation_get
  • messages_read
  • attachments_fetch
  • events_poll
  • events_wait
  • messages_send
  • permissions_list_open
  • permissions_respond

conversations_list — 列出 Gateway 会话状态中已有路由元数据的最近会话。可用过滤器：limit、search、channel、includeDerivedTitles、includeLastMessage。

conversation_get — 通过 session_key 返回单个会话。

messages_read — 读取某会话的最近历史消息记录。

attachments_fetch — 从单条历史消息中提取非文本内容块的元数据视图，不是独立的持久附件存储。

events_poll — 从数字游标处读取排队的实时事件。

events_wait — 长轮询，直到下一个匹配的排队事件到来或超时。适合通用 MCP 客户端在无 Claude 推送协议时获取近实时投递。

messages_send — 通过会话上已记录的同一路由发送文本回复。当前行为：需要已有会话路由，使用会话的渠道、接收者、accountId 和 threadId，仅支持发送文本。

permissions_list_open — 列出桥接器自连接以来观察到的待处理 exec/插件审批请求。

permissions_respond — 以 allow-once、allow-always 或 deny 解决一个待处理审批请求。

事件模型 ​

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

当前事件类型：

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

重要限制：

  • 队列是实时的，从 MCP 桥接器启动时开始
  • events_poll 和 events_wait 不会自行重放旧的 Gateway 历史
  • 持久历史应通过 messages_read 读取

Claude 频道通知 ​

桥接器可选择性地暴露 Claude 专属频道通知——标准 MCP 工具仍可用，但入站消息也可作为 Claude 专属 MCP 通知到达。

控制标志：

  • --claude-channel-mode off：仅使用标准 MCP 工具
  • --claude-channel-mode on：启用 Claude 频道通知
  • --claude-channel-mode auto：当前默认值，行为与 on 相同

启用后，服务器会声明 Claude 实验性能力，并可发出：

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

当前桥接器行为：

  • 入站 user 历史消息作为 notifications/claude/channel 转发
  • 通过 MCP 收到的 Claude 权限请求在内存中跟踪
  • 若关联会话后来发送 yes abcde 或 no abcde，桥接器将其转换为 notifications/claude/channel/permission
  • 这些通知仅限当前会话；MCP 客户端断开后无推送目标

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

MCP 客户端配置示例 ​

json
{
  "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 <url>Gateway WebSocket URL
--token <token>Gateway token
--token-file <path>从文件读取 token
--password <password>Gateway 密码
--password-file <path>从文件读取密码
--claude-channel-mode <auto|on|off>Claude 通知模式
-v, --verbose在 stderr 输出详细日志

条件允许时，优先使用 --token-file 或 --password-file 而非内联 secret。

安全与信任边界 ​

桥接器不自行创建路由，只暴露 Gateway 已知的会话路由。这意味着：

  • 发件人白名单、配对、频道级信任仍由底层 OpenClaw 渠道配置控制
  • messages_send 只能通过已存储的路由回复
  • 审批状态对当前桥接会话是实时/内存级的
  • 桥接器认证应使用与其他远程 Gateway 客户端相同的 token 或密码控制

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

测试 ​

OpenClaw 附带一个确定性的 Docker 烟雾测试：

bash
pnpm test:docker:mcp-channels

该测试会：

  • 启动一个预填充数据的 Gateway 容器
  • 启动第二个容器运行 openclaw mcp serve
  • 验证会话发现、历史读取、附件元数据读取、实时事件队列行为和出站发送路由
  • 通过真实 stdio MCP 桥接验证 Claude 风格的频道和权限通知

这是验证桥接器是否正常工作的最快方式，无需接入真实的 Telegram、Discord 或 iMessage 账号。

故障排查 ​

没有返回会话：通常说明 Gateway 会话不可路由。确认底层会话已存储渠道/提供者、接收者以及可选的 account/thread 路由元数据。

events_poll 或 events_wait 漏掉旧消息：预期行为。实时队列从桥接器连接时开始。用 messages_read 读取旧历史。

Claude 通知不出现：逐项检查：客户端保持了 stdio MCP 会话打开；--claude-channel-mode 为 on 或 auto；客户端确实理解 Claude 专属通知方法；入站消息发生在桥接器连接之后。

审批请求缺失：permissions_list_open 只显示桥接器连接期间观察到的审批请求，不是持久审批历史 API。

openclaw mcp list/show/set/unset：管理 MCP 服务器配置 ​

这是 openclaw mcp list、show、set、unset 这几个命令的功能。

这些命令不会将 OpenClaw 暴露为 MCP 服务器，它们管理的是 OpenClaw 配置中 mcp.servers 下的 MCP 服务器定义。

这些保存的定义供 OpenClaw 以后启动或配置的运行时（如嵌入式 Pi 和其他运行时适配器）使用，让这些运行时不需要维护各自重复的 MCP 服务器列表。

重要行为：

  • 这些命令只读写 OpenClaw 配置
  • 不会连接目标 MCP 服务器
  • 不验证命令、URL 或远程传输是否当前可达
  • 运行时适配器在执行时自行决定支持哪些传输方式

基本命令 ​

bash
openclaw mcp list
openclaw mcp show context7 --json
openclaw mcp set context7 '{"command":"uvx","args":["context7-mcp"]}'
openclaw mcp set docs '{"url":"https://mcp.example.com"}'
openclaw mcp unset context7

说明：

  • list 按名称排序输出服务器列表
  • show 不带名称时打印完整的已配置 MCP 服务器对象
  • set 接受命令行上的一个 JSON 对象值
  • unset 在目标服务器不存在时失败

配置格式 ​

json
{
  "mcp": {
    "servers": {
      "context7": {
        "command": "uvx",
        "args": ["context7-mcp"]
      },
      "docs": {
        "url": "https://mcp.example.com"
      }
    }
  }
}

Stdio 传输 ​

拉起本地子进程，通过 stdin/stdout 通信。

字段说明
command要启动的可执行文件（必填）
args命令行参数数组
env额外环境变量
cwd / workingDirectory进程工作目录

SSE / HTTP 传输 ​

通过 HTTP Server-Sent Events 连接远程 MCP 服务器。

字段说明
url远程服务器的 HTTP 或 HTTPS URL（必填）
headers可选 HTTP 头键值对（例如认证 token）
connectionTimeoutMs每服务器连接超时（毫秒，可选）
json
{
  "mcp": {
    "servers": {
      "remote-tools": {
        "url": "https://mcp.example.com",
        "headers": {
          "Authorization": "Bearer <token>"
        }
      }
    }
  }
}

url 中的敏感值（userinfo）和 headers 在日志和状态输出中会被脱敏。

Streamable HTTP 传输 ​

streamable-http 是除 sse 和 stdio 之外的另一种传输选项，使用 HTTP 流式传输与远程 MCP 服务器双向通信。

字段说明
url远程服务器的 HTTP 或 HTTPS URL（必填）
transport设为 "streamable-http" 选用此传输；省略时 OpenClaw 使用 sse
headers可选 HTTP 头键值对
connectionTimeoutMs每服务器连接超时（毫秒，可选）
json
{
  "mcp": {
    "servers": {
      "streaming-tools": {
        "url": "https://mcp.example.com/stream",
        "transport": "streamable-http",
        "connectionTimeoutMs": 10000,
        "headers": {
          "Authorization": "Bearer <token>"
        }
      }
    }
  }
}

这些命令只管理保存的配置，不会启动频道桥接、打开实时 MCP 客户端会话或验证目标服务器是否可达。

当前限制 ​

  • 会话发现依赖 Gateway 会话中已有的路由元数据
  • 除 Claude 专属适配器外，无通用推送协议
  • 暂无消息编辑或反应工具
  • HTTP/SSE/streamable-http 传输连接单个远程服务器，暂不支持多路复用上游
  • permissions_list_open 只包含桥接器连接期间观察到的审批请求

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 地豆 蜀ICP备2021007188号 | 关于本站 | 隐私政策