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 自行托管编码 harness 会话，并通过 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> 是不含 l 的 5 字母请求 ID），桥接会将其转换为 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 接受 --command、--arg、--env 和 --cwd 等 stdio 标志，或 --url、--transport、--header、--auth oauth、TLS、超时和工具选择标志等 HTTP 标志。
• 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 应用服务器。

在凭据可用之前，OpenClaw 只会从 Agent Runtimes 中省略该 MCP 服务器，而不会导致智能体轮次失败。之后，操作员或具有 shell 访问权限的智能体可以运行 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",        "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"],      },    },  },}

行为和安全边界：

• 仅当 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 可见的工具。
• 当内层 App 文档使用不透明源实现跨 App 隔离时，不会授予与源绑定的 App 权限，例如摄像头、麦克风和地理位置权限。
• App HTML、完整工具参数和原始结果会保存在有界的十分钟内存视图租约中。它们不会写入磁盘，也不会复制到会话记录预览元数据中，并且过期的视图不会重启其 MCP 运行时。
• 桥接启用时，openclaw security audit 会发出警告。不需要桥接时，请使用 openclaw config set mcp.apps.enabled false --strict-json 将其禁用。

当前限制

本页面记录当前已发布桥接的行为。

当前限制：

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

相关内容

• CLI 参考
• 插件