MCP

openclaw mcp 有两个作用：

• 使用 openclaw mcp serve 将 OpenClaw 作为 MCP 服务器运行
• 使用 list、show、status、doctor、probe、add、set、configure、tools、login、logout、reload 和 unset 管理由 OpenClaw 管理的出站 MCP 服务器定义

serve 表示 OpenClaw 作为 MCP 服务器运行。其他子命令则表示 OpenClaw 充当 MCP 客户端侧注册表，供其自身运行时稍后使用其中的服务器。

当 OpenClaw 应自行托管编码工具链会话，并通过 ACP 路由该运行时时，请使用 openclaw acp。

选择正确的 MCP 路径

将 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 --verboseopenclaw 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 支持：

安全和信任边界

此桥接器不会自行创建路由。它只公开 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 账户即可验证桥接器是否正常工作的最快方式。

有关更广泛的测试背景，请参阅测试。

故障排除

将 OpenClaw 用作 MCP 客户端注册表

这是 openclaw mcp list、show、status、doctor、probe、add、set、 configure、tools、login、logout、reload 和 unset 路径。

这些命令不会通过 MCP 公开 OpenClaw。它们管理 OpenClaw 配置中 mcp.servers 下由 OpenClaw 管理的 MCP 服务器定义。它们不会从 config/mcporter.json 读取 mcporter 服务器。

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

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

Codex app-server 还支持每个服务器上的可选 codex 块。这是 仅用于 Codex app-server 线程的 OpenClaw 投影元数据；它不会 更改 ACP 会话、通用 Codex harness 配置或其他运行时适配器。 使用非空的 codex.agents，仅将服务器投影到特定 OpenClaw 智能体 ID。空白、仅含空格或无效的智能体列表会被配置 验证拒绝，并由运行时投影路径省略，而不会变为 全局配置。使用 codex.defaultToolsApprovalMode（auto、prompt 或 approve） 为受信任的服务器生成 Codex 原生的 default_tools_approval_mode。 OpenClaw 在将原生 mcp_servers 配置交给 Codex 之前， 会移除 codex 元数据。

已保存的 MCP 服务器定义

命令：

• openclaw mcp list
• openclaw mcp show [name]
• openclaw mcp status [--verbose]
• openclaw mcp doctor [name] [--probe]
• openclaw mcp probe [name]
• openclaw mcp add <name> [flags]
• openclaw mcp set <name> <json>
• openclaw mcp configure <name> [flags]
• openclaw mcp tools <name> [--include csv] [--exclude csv] [--clear]
• openclaw mcp login <name> [--code code]
• openclaw mcp logout <name>
• openclaw mcp reload
• openclaw mcp unset <name>

说明：

• list 对服务器名称排序。
• 不带名称的 show 会输出完整的已配置 MCP 服务器对象。
• status 在不建立连接的情况下对已配置的传输进行分类。--verbose 包含解析后的启动、超时、OAuth、筛选器和并行调用详细信息。
• doctor 在不建立连接的情况下执行静态检查。如果该命令还应验证已启用服务器能否连接，请添加 --probe。
• probe 建立连接，并报告工具数量、资源/提示词支持、列表变更支持和诊断信息。
• add 接受 stdio 标志，例如 --command、--arg、--env 和 --cwd；也接受 HTTP 标志，例如 --url、--transport、--header、--auth oauth、TLS、超时和工具选择标志。
• set 要求命令行中提供一个 JSON 对象值。
• configure 更新启用状态、工具筛选器、超时、OAuth、TLS 和并行工具调用提示，而不替换整个服务器定义。添加 --probe 可在保存前验证更新后的服务器。
• tools 更新各服务器的工具筛选器。包含/排除条目是 MCP 工具名称和简单的 * glob 模式。
• login 为使用 auth: "oauth" 配置的 HTTP 服务器运行 OAuth 流程。首次运行会输出授权 URL；批准后使用 --code 重新运行。
• logout 清除指定服务器已存储的 OAuth 凭据，但不移除已保存的服务器定义。
• reload 仅释放当前 CLI 进程中缓存的进程内 MCP 运行时。另一个进程中的 Gateway 网关或智能体进程仍需执行各自的重新加载或重启流程。
• 对 Streamable HTTP MCP 服务器使用 transport: "streamable-http"。为实现兼容性，openclaw mcp set 还会将 CLI 原生的 type: "http" 规范化为相同的标准配置形式。
• 如果指定服务器不存在，unset 将失败。

示例：

openclaw mcp listopenclaw mcp show context7 --jsonopenclaw mcp status --verboseopenclaw mcp doctor --probeopenclaw mcp probe context7 --jsonopenclaw mcp add memory --command npx --arg -y --arg @modelcontextprotocol/server-memoryopenclaw mcp set context7 '{"command":"uvx","args":["context7-mcp"]}'openclaw mcp tools context7 --include 'resolve-library-id,get-library-docs'openclaw mcp set docs '{"url":"https://mcp.example.com","transport":"streamable-http"}'openclaw mcp configure docs --timeout 20 --connect-timeout 5 --include 'search,read_*'openclaw mcp configure docs --auth oauth --oauth-scope 'docs.read'openclaw mcp login docsopenclaw mcp logout docsopenclaw mcp unset context7

常用服务器配置示例

这些示例仅保存服务器定义。之后运行 openclaw mcp doctor --probe，以确认服务器能够启动并公开工具。

openclaw mcp add files \  --command npx \  --arg -y \  --arg @modelcontextprotocol/server-filesystem \  --arg "$HOME/Documents" \  --include 'read_file,list_directory,search_files'openclaw mcp doctor files --probe

openclaw mcp add memory \  --command npx \  --arg -y \  --arg @modelcontextprotocol/server-memoryopenclaw mcp probe memory --json

openclaw mcp add local-tools \  --command node \  --arg ./dist/mcp-server.js \  --cwd /srv/openclaw-tools \  --env API_BASE=https://internal.exampleopenclaw mcp status --verbose

openclaw mcp add docs \  --url https://mcp.example.com/mcp \  --transport streamable-http \  --auth oauth \  --oauth-scope docs.read \  --timeout 20 \  --connect-timeout 5 \  --include 'search,read_*'openclaw mcp doctor docs --probe

openclaw mcp set cua-driver '{"command":"cua-driver","args":["mcp"]}'openclaw mcp tools cua-driver --include 'list_apps,observe,click,type'openclaw mcp doctor cua-driver --probe

JSON 输出结构

脚本和仪表板请使用 --json。字段集可能随时间增加，因此使用方应忽略未知键。

{  "path": "/home/user/.openclaw/openclaw.json",  "servers": [    {      "name": "docs",      "configured": true,      "enabled": true,      "ok": true,      "transport": "streamable-http",      "launch": "streamable-http https://mcp.example.com/mcp",      "auth": "oauth",      "authStatus": {        "hasTokens": true,        "hasClientInformation": true,        "hasCodeVerifier": false,        "hasDiscoveryState": true,        "hasLastAuthorizationUrl": false      },      "requestTimeoutMs": 20000,      "connectionTimeoutMs": 5000,      "toolFilter": {        "include": ["search", "read_*"],        "exclude": []      },      "supportsParallelToolCalls": true    }  ]}

{  "ok": true,  "path": "/home/user/.openclaw/openclaw.json",  "servers": [    {      "name": "docs",      "ok": true,      "issues": [        {          "level": "warning",          "message": "OAuth 凭据尚未授权；请运行 openclaw mcp login docs"        }      ]    }  ]}

{  "generatedAt": "2026-05-31T09:00:00.000Z",  "servers": {    "docs": {      "launch": "streamable-http https://mcp.example.com/mcp",      "tools": 2,      "resources": true,      "listChanged": {        "tools": true,        "resources": false,        "prompts": false      }    }  },  "tools": ["docs__read_page", "docs__search"],  "diagnostics": []}

配置结构示例：

{  "mcp": {    "servers": {      "context7": {        "command": "uvx",        "args": ["context7-mcp"]      },      "docs": {        "url": "https://mcp.example.com",        "transport": "streamable-http",        "timeout": 20,        "connectTimeout": 5,        "supportsParallelToolCalls": true,        "auth": "oauth",        "oauth": {          "scope": "docs.read"        },        "sslVerify": true,        "clientCert": "/path/to/client.crt",        "clientKey": "/path/to/client.key",        "toolFilter": {          "include": ["search_*"],          "exclude": ["admin_*"]        }      }    }  }}

Stdio 传输

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

SSE / HTTP 传输

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

示例：

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

日志和状态输出会遮盖 url（用户信息）和 headers 中的敏感值。当看似敏感的 headers 或 env 条目包含明文值时，openclaw mcp doctor 会发出警告，以便操作员将这些值移出已提交的配置。

OAuth 工作流程

OAuth 适用于声明支持 MCP OAuth 流程的 HTTP MCP 服务器。当服务器启用 auth: "oauth" 时，会忽略静态 Authorization 标头。由 openclaw mcp login 保存的凭据可用于嵌入式 MCP、CLI 运行程序和本地 Codex app-server。

在凭据可用之前，OpenClaw 只会从 Agent Runtimes 中省略该 MCP 服务器，而不会导致智能体轮次失败。之后，操作员或具有 shell 访问权限的智能体可以运行 openclaw mcp login <name>，并在后续轮次中使用该服务器。

当远程 MCP 服务已由另一个支持刷新的 OpenClaw 身份验证配置文件提供支持时，可以选择设置 oauth.authProfileId。OpenClaw 会在运行时投影之前刷新任一凭据来源，并且仅将当前 access token 传递给下游 MCP 客户端。

openclaw mcp set docs '{"url":"https://mcp.example.com/mcp","transport":"streamable-http","auth":"oauth","oauth":{"scope":"docs.read"}}'

openclaw mcp set docs '{"url":"https://mcp.example.com/mcp","transport":"streamable-http","auth":"oauth","oauth":{"authProfileId":"docs:mcp"}}'

openclaw mcp login docs

openclaw mcp login docs --code abc123

openclaw mcp status --verboseopenclaw mcp doctor docs --probe

openclaw mcp logout docs

如果提供商轮换令牌或授权状态卡住，请运行 openclaw mcp logout <name>，然后重复 login。即使 auth: "oauth" 已从配置中移除，只要服务器名称和 URL 仍可标识凭据存储条目，logout 仍可清除已保存 HTTP 服务器的凭据。

可流式 HTTP 传输

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

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

示例：

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

Control UI

浏览器 Control UI 在 /settings/mcp 提供专用的 MCP 设置页面；此前的 /mcp 路径仍作为别名保留。该页面会显示已配置服务器数量、启用/OAuth/筛选摘要、各服务器的传输方式行、启用/禁用控件、常用 CLI 命令，以及用于编辑 mcp 配置部分的范围限定编辑器。

使用该页面进行操作员编辑和快速清点。当需要实时服务器验证时，请使用 openclaw mcp doctor --probe 或 openclaw mcp probe。

操作员工作流程：

1. 打开 Control UI 并选择 MCP。
2. 查看服务器总数、已启用、OAuth 和已筛选的摘要卡片。
3. 使用每个服务器行查看传输方式、身份验证、筛选器、超时和命令提示。
4. 如果希望保留定义但将其排除在运行时发现之外，请切换启用状态。
5. 编辑范围限定的 mcp 配置部分，以进行新增服务器、标头、TLS、OAuth 元数据或工具筛选器等结构性更改。
6. 选择 Save 仅持久化配置，或选择 Save & Publish 通过 Gateway 网关配置路径应用配置。
7. 如果需要实时验证编辑后的服务器能够启动并列出工具，请运行 openclaw mcp doctor --probe。

注意：

• 命令片段会为服务器名称添加引号，以便名称特殊时仍可在 shell 中复制使用
• 类似 URL 的显示值如果包含嵌入式凭据，会在渲染前进行脱敏
• 该页面本身不会启动 MCP 传输
• 根据 MCP 客户端由哪个进程管理，活动运行时可能需要 openclaw mcp reload、发布 Gateway 网关配置或重启进程

MCP Apps

OpenClaw 可以渲染实现稳定版 MCP Apps 扩展的工具。Apps 需要主动启用，因为其 HTML 来自已配置的 MCP 服务器，并且可以向同一服务器请求 App 可见的工具或资源。

启用主机桥接：

openclaw config set mcp.apps.enabled true --strict-json

更改此设置后，请重启 Gateway 网关。启用后，OpenClaw 会在 Gateway 网关端口加一的端口上启动一个仅用于沙箱的 HTTP(S) 监听器（对于默认 Gateway 网关，即 18790）。Control UI 从该独立源加载 Apps；此监听器绝不会提供 Control UI、经过身份验证的 Gateway 网关路由或用户数据。

直接连接 Gateway 网关时需要能够访问这两个端口。如果反向代理或 TLS 终止器公开 Control UI，请为 Apps 分配专用公共源，并仅将该源代理到沙箱监听器：

{  mcp: {    apps: {      enabled: true,      sandboxOrigin: "https://mcp-apps.example.com",      sandboxPort: 18790,    },  },}

沙箱源必须与 Control UI 源不同。不要在其中托管其他经过身份验证或敏感的内容。

例如，可按如下方式配置官方基础 React 演示：

{  mcp: {    apps: { enabled: true },    servers: {      "basic-react": {        command: "npx",        args: ["-y", "@modelcontextprotocol/server-basic-react", "--stdio"],      },    },  },}

行为和安全边界：

• OpenClaw 仅在启用 Apps 时声明 io.modelcontextprotocol/ui 扩展。
• 仅渲染具有完全匹配 text/html;profile=mcp-app MIME 类型的 ui:// 资源。
• UI 资源上限为 2 MiB，通过专用外层源上的双 iframe 代理提供，加载到不透明的内层 App 源中，并受根据资源元数据生成的 CSP 约束。
• 仅供 App 使用的工具（_meta.ui.visibility: ["app"]）不会出现在模型工具列表中。Apps 只能调用其所属服务器上 App 可见的工具，并且这些工具还必须通过创建该视图的运行所采用的有效 OpenClaw 工具策略。
• 当内层 App 文档使用不透明源实现跨 App 隔离时，不会授予与源绑定的 App 权限，例如摄像头、麦克风和地理位置权限。
• App HTML、完整工具参数和原始结果保存在有界的十分钟内存视图租约中，不会写入磁盘或复制到转录预览元数据中。转录仅存储与原始工具调用 ID 绑定的有界服务器/工具/资源描述符。Gateway 网关重启后，Control UI 可以根据经过身份验证的会话转录验证该描述符并重新获取 ui:// 资源；在新的运行建立当前工具权限之前，重建的视图为只读。
• 启用桥接时，openclaw security audit 会发出警告。不需要时，请使用 openclaw config set mcp.apps.enabled false --strict-json 将其禁用。

当前限制

本页记录该桥接目前发布版本的行为。

当前限制：

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

相关内容

• CLI 参考
• 插件