MCP

openclaw mcp 有两个用途：

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

serve 是作为 MCP 服务器运行的 OpenClaw。其他子命令则让 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 会先移除 codex 元数据，再将原生 mcp_servers 配置交给 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、过滤器和并行调用详情，包括已存储的 OAuth 令牌何时需要额外授权。文本和 JSON 输出中的含凭据 stdio 参数会被遮盖。
• 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,get_window_state,click,type_text'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,        "requiresAuthorization": false,        "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",        "requestTimeoutMs": 20000,        "connectionTimeoutMs": 5000,        "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",        "requestTimeoutMs": 20000,        "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。

原生 MCP OAuth 会话存储在仅所有者可访问的共享 SQLite 数据库 <state-dir>/state/openclaw.sqlite（mcp_oauth_stores）中。该行可包含访问令牌和刷新令牌、动态客户端注册密钥、发现元数据以及临时 PKCE 验证器。刷新、登录和注销使用同一个 SQLite 租约，因此并行的 OpenClaw 进程无法消耗同一个刷新令牌或恢复已注销的会话。

从已停用的 <state-dir>/mcp-oauth/*.json 存储升级只能由 openclaw doctor --fix 处理。运行时代码绝不会读取、写入这些文件，也不会回退到这些文件。

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

如果服务器以 insufficient_scope 拒绝令牌，OpenClaw 会保留请求的作用域并要求执行 openclaw mcp login <name>，而不是重复无法授予新作用域的刷新操作。该登录操作会启动新的授权请求，同时保留旧令牌，直至保存替代凭据。

当远程 MCP 服务已由单独的、支持刷新的 OpenClaw 身份验证配置文件提供支持时，可以选择设置 oauth.authProfileId。OpenClaw 会在运行时投影之前刷新任一凭据来源，并且仅将当前访问令牌传递给下游 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",        "connectionTimeoutMs": 10000,        "requestTimeoutMs": 30000,        "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"],      },    },  },}

行为和安全边界：

• 仅当 Apps 已启用时，OpenClaw 才会公布 io.modelcontextprotocol/ui 扩展。
• 仅渲染 MIME 类型与 text/html;profile=mcp-app 完全匹配的 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:// 资源；在新的运行建立当前工具权限之前，重建的视图为只读状态。
• 在渠道对话中，一个轮次内最新成功的 App 视图会向最终智能体回复添加一个 打开 App 样式的操作。Telegram 私信使用原生 Mini App 按钮；Slack 和 Discord 将同一可移植操作渲染为链接。其他渠道保留原始回复文本，并附加易于理解的 HTTPS 链接。
• 仅当 Gateway 网关的 Tailscale 暴露已准备好发布的 HTTPS 来源时，渠道启动链接才可用。gateway.tailscale.mode: "serve" 仅可从 tailnet 访问；"funnel" 可从公共互联网访问。由 gateway.tailscale.preserveFunnel 保留的外部托管 Funnel 也被视为可从互联网访问。请参阅 Tailscale。
• 启动票据是不透明的，仅在生成最终渠道回复时签发，并在最多两分钟后或底层视图租约到期时失效，以较早者为准。URL 不包含 Gateway 网关 bearer 凭据、会话密钥、视图元数据、App HTML、工具输入或工具结果。
• 如果没有可用的已发布来源或票据容量、视图或票据已过期，或者传输协议无法渲染原生控件，原始智能体文本仍然可用。Control UI 会保留其现有的内嵌 App 画布，并且不会收到重复的启动操作。
• 启用桥接时，openclaw security audit 会发出警告。不需要时，请使用 openclaw config set mcp.apps.enabled false --strict-json 将其禁用。

当前限制

本页记录当前已发布的桥接实现。

当前限制：

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

相关内容

• CLI 参考
• 插件