CLI — openclaw mcp

概述

openclaw mcp 有两个职责：

职责	命令	说明
OpenClaw 作为 MCP 服务端	`mcp serve`	将 OpenClaw 渠道会话暴露给 MCP 客户端（Codex、Claude Code 等）
OpenClaw 作为 MCP 客户端注册表	`mcp list/show/set/unset`	管理 OpenClaw 保存的出站 MCP 服务器定义

若要 OpenClaw 托管编码运行时并通过 ACP 路由，用 openclaw acp，不是 mcp serve。

mcp serve — OpenClaw 作为 MCP 服务端

适用场景

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

工作原理

openclaw mcp serve 启动一个 stdio MCP 服务器。MCP 客户端拥有该进程。桥接器通过 WebSocket 连接到 Gateway，将路由的渠道会话暴露为 MCP 对话。

openclaw mcp serve                                                    # 本地 Gateway
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

选项

选项	说明
`--url`	Gateway WebSocket URL
`--token` / `--token-file`	Gateway token（优先用文件）
`--password` / `--password-file`	Gateway 密码（优先用文件）
`--claude-channel-mode`	`auto`（默认）/ `on` / `off`
`-v, --verbose`	详细日志输出到 stderr

暴露的 MCP 工具

工具	说明
`conversations_list`	列出有路由元数据的最近会话
`conversation_get`	按 session_key 获取单个会话
`messages_read`	读取会话的最近 transcript 消息
`attachments_fetch`	提取 transcript 消息中的非文本内容块
`events_poll`	从数字游标读取队列中的实时事件
`events_wait`	长轮询直到下一个匹配事件到达或超时
`messages_send`	通过会话已有路由发送回复
`permissions_list_open`	列出桥接器连接后观察到的待处理审批请求
`permissions_respond`	解决审批请求（`allow-once`/`allow-always`/`deny`）

事件类型

events_poll/events_wait 返回的事件：message、exec_approval_requested、exec_approval_resolved、plugin_approval_requested、plugin_approval_resolved、claude_permission_request

事件队列从桥接器连接时开始，不重放历史。历史消息用 messages_read。

Claude 渠道通知

--claude-channel-mode on/auto 时，服务器额外发送：

notifications/claude/channel：入站用户消息
notifications/claude/channel/permission：Claude 权限请求

仅对理解 Claude 特定通知方法的客户端有意义；通用 MCP 客户端用标准轮询工具。

MCP 客户端配置示例

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

安全边界

桥接器只暴露 Gateway 已知路由的会话
messages_send 只能通过已存储的路由回复
审批状态仅在当前桥接会话期间有效（内存中）
桥接器认证使用与其他远程 Gateway 客户端相同的 token/password 控制

mcp list/show/set/unset — MCP 客户端注册表

管理 OpenClaw 保存的出站 MCP 服务器定义（存储在 mcp.servers 配置中），供 embedded Pi 等运行时后续使用。

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 服务器，不验证可达性。

传输类型

传输	关键字段	说明
stdio	`command`、`args`、`env`、`cwd`	启动本地子进程，通过 stdin/stdout 通信
SSE/HTTP	`url`、`headers`、`connectionTimeoutMs`	连接远程 HTTP SSE 服务器
streamable-http	`url`、`transport: "streamable-http"`、`headers`	HTTP 流式双向通信

stdio env 安全过滤：NODE_OPTIONS、PYTHONSTARTUP、PYTHONPATH 等解释器启动控制变量被拒绝，需在 Gateway 宿主进程中设置。

Wiki AI

目录