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 应自行托管编码 harness 会话并通过 ACP 路由该运行时时，请使用 openclaw acp。

# OpenClaw 作为 MCP 服务器

这是 openclaw mcp serve 路径。

# 何时使用 serve

在以下情况使用 openclaw mcp serve：

• Codex、Claude Code 或其他 MCP 客户端应直接与 OpenClaw 支持的渠道对话通信
• 你已经有一个带有已路由会话的本地或远程 OpenClaw Gateway 网关
• 你想要一个可跨 OpenClaw 渠道后端工作的 MCP 服务器，而不是运行单独的逐渠道桥接器

当 OpenClaw 应自行托管编码运行时并将智能体会话保留在 OpenClaw 内部时，请改用 openclaw acp。

# 工作方式

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

# 选择客户端模式

以两种不同方式使用同一个桥接器：

# serve 暴露的内容

桥接器使用现有 Gateway 网关会话路由元数据来暴露渠道支持的对话。当 OpenClaw 已有带已知路由的会话状态时，就会出现一个对话，例如：

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

这为 MCP 客户端提供一个位置来：

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

# 用法

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

# 桥接器工具

当前桥接器暴露这些 MCP 工具：

# 事件模型

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

当前事件类型：

• 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 abcde 或 no abcde，桥接器会将其转换为 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 支持：

# 安全与信任边界

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

这意味着：

• 发送方允许列表、配对和渠道级信任仍属于底层 OpenClaw 渠道配置
• messages_send 只能通过现有已存储路由回复
• 审批状态仅对当前桥接器会话实时/内存可用
• 桥接器认证应使用你愿意信任给任何其他远程 Gateway 网关客户端的相同 Gateway 网关令牌或密码控制

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

# 测试

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

pnpm test:docker:mcp-channels

该冒烟测试会：

• 启动一个带种子数据的 Gateway 网关容器
• 启动第二个容器，并生成 openclaw mcp serve
• 验证对话发现、转录记录读取、附件元数据读取、实时事件队列行为和出站发送路由
• 通过真实的 stdio MCP 桥接器验证 Claude 风格的渠道和权限通知

这是在不把真实 Telegram、Discord 或 iMessage 账号接入测试运行的情况下证明桥接器工作的最快方式。

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

# 故障排除

# OpenClaw 作为 MCP 客户端注册表

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

这些命令不会通过 MCP 暴露 OpenClaw。它们管理 OpenClaw 配置中 mcp.servers 下由 OpenClaw 拥有的 MCP 服务器定义。

这些已保存的定义用于 OpenClaw 稍后启动或配置的运行时，例如嵌入式 Pi 和其他运行时适配器。OpenClaw 会集中存储这些定义，因此这些运行时不需要维护自己的重复 MCP 服务器列表。

运行时适配器可能会将这个共享注册表规范化为其下游客户端期望的形态。例如，嵌入式 Pi 会直接使用 OpenClaw 的 transport 值，而 Claude Code 和 Gemini 会收到 CLI 原生的 type 值，例如 http、sse 或 stdio。

# 已保存的 MCP 服务器定义

OpenClaw 还会在配置中存储一个轻量级 MCP 服务器注册表，供需要 OpenClaw 管理的 MCP 定义的界面使用。

命令：

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

说明：

• list 会对服务器名称排序。
• 不带名称的 show 会打印完整的已配置 MCP 服务器对象。
• set 需要在命令行中提供一个 JSON 对象值。
• 对 Streamable HTTP MCP 服务器使用 transport: "streamable-http"。为保持兼容，openclaw mcp set 也会将 CLI 原生的 type: "http" 规范化为相同的规范配置形态。
• 如果指定名称的服务器不存在，unset 会失败。

示例：

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","transport":"streamable-http"}'
openclaw mcp unset context7

示例配置形态：

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

# Stdio 传输协议

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

# SSE / HTTP 传输协议

通过 HTTP 服务器发送事件连接到远程 MCP 服务器。

示例：

{
  "mcp": {
    "servers": {
      "remote-tools": {
        "url": "https://mcp.example.com",
        "headers": {
          "Authorization": "Bearer <token>"
        }
      }
    }
  }
}

url（userinfo）和 headers 中的敏感值会在日志和 Status 输出中被遮盖。

# Streamable HTTP 传输协议

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

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

示例：

{
  "mcp": {
    "servers": {
      "streaming-tools": {
        "url": "https://mcp.example.com/stream",
        "transport": "streamable-http",
        "connectionTimeoutMs": 10000,
        "headers": {
          "Authorization": "Bearer <token>"
        }
      }
    }
  }
}

# 当前限制

本页记录的是当前已发布的桥接能力。

当前限制：

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

# 相关内容

• CLI 参考
• 插件