古法编程

Appearance

openclaw mcp 有两个职责：一是用 mcp serve 将 OpenClaw 频道会话暴露为 MCP 服务器，供 Claude Code、OpenAI Codex 等客户端接入；二是用 list/show/set/unset 管理 OpenClaw 保存的出站 MCP 服务器定义。本页覆盖完整用法、事件模型、Claude 频道通知模式和故障排查。如果 OpenClaw 需要自己承载 coding 运行时，改用 openclaw acp 命令。

OpenClaw MCP 配置：作为 MCP 服务器或管理客户端定义 ​

openclaw mcp 有两个职责：

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

换句话说：

  • serve 是 OpenClaw 作为 MCP 服务器
  • list / show / set / unset 是 OpenClaw 作为 MCP 客户端注册表

如果需要 OpenClaw 自己托管 coding harness 会话并通过 ACP 路由运行时，请使用 openclaw acp。

OpenClaw 作为 MCP 服务器（serve） ​

这是 openclaw mcp serve 路径。

何时使用 serve ​

适合以下场景：

  • Codex、Claude Code 或其他 MCP 客户端需要直接访问 OpenClaw 频道会话
  • 本地或远程已有 OpenClaw Gateway 并已路由会话
  • 希望一个 MCP 服务器统一覆盖 OpenClaw 的多个渠道后端

如果需要 OpenClaw 自己托管 coding 运行时并在内部保持 agent 会话，改用 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 会话存活期间有效
  • 客户端断开后，桥接退出，实时队列消失
  • 单次使用的 agent 入口（如 openclaw agent 和 openclaw infer model run）会在回复完成后销毁它们启动的 MCP 运行时，避免重复脚本运行积累 stdio MCP 子进程
  • OpenClaw 启动的 stdio MCP 服务器（内建或用户配置的）在关闭时会被进程树一并销毁，因此服务器启动的子进程在父 stdio 客户端退出后不会残留
  • 删除或重置一个会话时，该会话的 MCP 客户端会经过共享运行时清理路径被释放，不会遗留该会话的 stdio 连接

客户端模式选择 ​

同一桥接支持两种使用方式：

  • 通用 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 会话路由元数据暴露频道对话。当 OpenClaw 已有包含以下信息的会话状态时，该对话会出现：

  • 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

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

conversation_get

通过 `session_key` 返回单条对话。

messages_read

读取单个会话的最近历史消息。

attachments_fetch

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

events_poll

从数字游标开始读取排队的实时事件。

events_wait

长轮询，直到下一个匹配的排队事件到达或超时。
适用于通用 MCP 客户端在没有 Claude 特定推送协议时的近实时传递。

messages_send

通过会话上已记录的相同路由回复文本。
当前行为：
- 需要已存在的对话路由
- 使用会话的渠道、收件人、账号 id 和线程 id
- 仅发送文本

permissions_list_open

列出桥接自连接以来观察到的待处理 exec/plugin 审批请求。

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 特定的频道通知。这是 OpenClaw 等价于 Claude Code 频道适配器的功能：标准 MCP 工具仍然可用，同时实时入站消息也可以作为 Claude 特定 MCP 通知到达。

参数：

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

启用 Claude 频道模式后，服务器会通告 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 string

Gateway WebSocket URL。

--token string

Gateway token。

--token-file string

从文件读取 token（推荐）。

--password string

Gateway 密码。

--password-file string

从文件读取密码（推荐）。

--claude-channel-mode

Claude 通知模式。

-v, --verbose boolean

在 stderr 输出详细日志。

安全与信任边界 ​

桥接不自行创建路由。它只暴露 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 会话尚不可路由。确认底层会话已存储渠道/提供商、收件人及可选的账号/线程路由元数据。

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） ​

这是 openclaw mcp list、show、set、unset 路径。

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

这些保存的定义供 OpenClaw 后续启动或配置的运行时使用（如嵌入式 Pi 和其他运行时适配器）。OpenClaw 集中存储这些定义，避免运行时维护重复的 MCP 服务器列表。

重要行为：

  • 这些命令只读写 OpenClaw 配置，不连接目标 MCP 服务器
  • 不验证命令、URL 或远程传输当前是否可达
  • 运行时适配器在执行时自己决定支持哪种传输格式
  • 嵌入式 Pi 在 coding 和 messaging 工具配置中暴露已配置的 MCP 工具；minimal 配置隐藏它们，tools.deny: ["bundle-mcp"] 显式禁用它们
  • 会话作用域的内建 MCP 运行时在空闲 mcp.sessionIdleTtlMs 毫秒后自动清理（默认 10 分钟；设置为 0 禁用空闲清理）
  • 单次使用的嵌入式运行在运行结束时清理内建运行时

运行时适配器可能会将这个共享注册表转换为下游客户端期望的形式。例如，嵌入式 Pi 直接消费 OpenClaw 的 transport 值，而 Claude Code 和 Gemini 接收 CLI 原生 type 值（如 http、sse 或 stdio）。

Codex app-server 在每个服务器定义上可选的 codex 块。这是 OpenClaw 的投影元数据，仅用于 Codex app-server 线程；不影响 ACP 会话、通用 Codex harness 配置或其他运行时适配器。使用非空 codex.agents 将服务器投影到特定 OpenClaw agent id。空、空白或无效的 agent 列表会被配置验证拒绝，运行时投影路径会跳过它们，不会变成全局生效。使用 codex.defaultToolsApprovalMode（auto、prompt 或 approve）为受信任的服务器设置 Codex 的 default_tools_approval_mode。OpenClaw 在将 mcp_servers 配置传递给 Codex 之前，会剥离 codex 元数据。

保存的 MCP 服务器定义 ​

命令：

bash
openclaw mcp list
openclaw mcp show [name]
openclaw mcp set <name> <json>
openclaw mcp unset <name>

备注：

  • list 按服务器名排序
  • show 不加名称时打印完整配置的 MCP 服务器对象
  • set 在命令行接受一个 JSON 对象值
  • 使用 transport: "streamable-http" 配置 Streamable HTTP MCP 服务器。openclaw mcp set 也会将 CLI 原生 type: "http" 规范化为相同的配置形式，保持兼容
  • unset 若命名的服务器不存在则失败

示例：

bash
# 列出所有已保存的服务器
openclaw mcp list

# 查看特定服务器配置（JSON 格式）
openclaw mcp show context7 --json

# 添加 stdio 类型服务器
openclaw mcp set context7 '{"command":"uvx","args":["context7-mcp"]}'

# 添加 Streamable HTTP 类型服务器
openclaw mcp set docs '{"url":"https://mcp.example.com","transport":"streamable-http"}'

# 删除服务器
openclaw mcp unset context7

配置结构示例：

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

Stdio 传输 ​

启动本地子进程，通过 stdin/stdout 通信。

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

Stdio env 安全过滤器：OpenClaw 拒绝可能改变 stdio MCP 服务器启动行为的 env 键，即使它们出现在服务器的 env 块中。被阻止的键包括 NODE_OPTIONS、PYTHONSTARTUP、PYTHONPATH、PERL5OPT、RUBYOPT、SHELLOPTS、PS4 等运行时控制变量。这些键被拒绝时会抛出配置错误，防止它们注入隐式前导指令、替换解释器或针对 stdio 进程启用调试器。普通凭证、代理和服务器特定的环境变量（如 GITHUB_TOKEN、HTTP_PROXY、自定义 *_API_KEY）不受影响。如果 MCP 服务器确实需要被阻止的变量，请在 Gateway 主机进程上设置，而不是在 stdio 服务器的 env 下设置。

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 和 headers 中的敏感值会在日志和状态输出中被脱敏处理。

Streamable HTTP 传输 ​

streamable-http 是 sse 和 stdio 之外的附加传输选项，使用 HTTP 流与远程 MCP 服务器进行双向通信。

字段说明
url远程服务器的 HTTP/HTTPS URL（必填）
transport设置为 "streamable-http" 选择此传输方式；省略时 OpenClaw 默认使用 sse
headers可选的 HTTP 头键值对（如认证 token）
connectionTimeoutMs每服务器连接超时（毫秒，可选）

OpenClaw 配置使用 transport: "streamable-http" 作为规范写法。通过 openclaw mcp set 保存时接受 CLI 原生 MCP type: "http"，openclaw doctor --fix 也会修复现有配置，但嵌入式 Pi 直接消费的是 transport 字段。

示例：

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 仅包含桥接连接期间观察到的审批请求

相关链接 ​

常见问题 ​

mcp serve 和 acp 有什么区别？ ​

mcp serve 是把 OpenClaw 的频道会话暴露给外部 MCP 客户端（Claude Code、Codex）来读/写；acp 是让 OpenClaw 自己承载 coding 运行时，IDE 作为客户端连进来。前者是 OpenClaw 作为数据源，后者是 OpenClaw 作为计算宿主。

连上了但 conversations_list 是空的，怎么办？ ​

先检查 Gateway 里是否有已经路由的会话——即有存储 channel、收件人等元数据的会话。如果是全新安装，需要先通过某个渠道（Telegram、Discord 等）发送消息让 Gateway 建立会话状态，之后才会出现在列表中。

我能用 MCP 向 Telegram 群组发消息吗？ ​

可以，前提是 Gateway 已有对应会话的路由元数据。用 conversations_list 找到目标会话的 session_key，再用 messages_send 发送。messages_send 只能通过已存储的现有路由回复，不会创建新路由。

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

Copyright © 2026 古法编程 | 蜀ICP备2021007188号 | 关于本站 | 隐私政策