连接 MCP 服务器
模型上下文协议(MCP)是智能体从另一个程序借用工具的方式:MCP 服务器暴露工具、资源和 Prompt,OpenClaw 连接到它,并使这些工具可供你的智能体使用。服务器定义位于配置中的 mcp.servers 下,它们暴露的工具与所有其他内容一样,经过相同的工具配置和工具策略控制——连接服务器不会绕过你的策略。
Note
本指南介绍如何将第三方 MCP 服务器连接到 OpenClaw。对于相反方向——将 OpenClaw 频道对话暴露给另一个 MCP 客户端——请使用 openclaw mcp serve。
从设置添加服务器¶
- 打开 Control UI,前往 设置 → MCP。
- 在 已配置服务器 下,选择 添加服务器。
- 为其指定一个唯一名称,并选择传输方式:Streamable HTTP、SSE 或 Stdio。
- 对于 HTTP 传输方式,输入服务器的
http://或https://URL。对于 stdio,输入命令及其参数。 - 选择 添加服务器。
这会通过 Gateway 写入新的 mcp.servers 条目。对于超出基础配置的内容——请求头、环境变量、OAuth 元数据、TLS 设置、超时、并行工具调用提示、工具过滤器——请使用页面下方的作用域配置编辑器。服务器行还允许你启用、禁用或删除定义。
服务器保存后,验证它确实有响应:
保存定义本身不能证明可达性——检查才能证明。启用 Gateway 热重载后,已更改或已删除的服务器会立即退役,下一轮发现将使用新定义。未更改的服务器会保留其连接和缓存工具,包括已在进行中的运行。请求方登录工具会在运行时替换后的下一条消息时刷新。
如果已连接的服务器退出或其连接必须被替换,OpenClaw 会在会话的面向模型目录中保留最后一次成功列出的工具和实用工具,同时恢复在后台运行。连接诊断和工具调用错误仍会报告不可用;保留的模式不会授予执行权限。成功列出会替换目录,包括服务器已删除的工具。显式配置更改、删除和插件重载会立即退役已更改的运行时;未更改的服务器保留其目录。
当 OpenClaw 内置 MCP 客户端无法启动服务器时,新运行时会在指数退避期间跳过它:30 秒,翻倍直至 10 分钟。遇到首次失败的运行时可以在其正常的五秒目录计划上重试一次,在退役失败连接后使用新连接。如果该恢复尝试也失败,则相同的指数退避也适用于它。失败状态会在普通会话清理后保留,并限定于服务器配置和请求方。有效工具清单会将服务器显示为不可用,并将该运行时的下次重试时间和可达性检查作为下一步。每次失败重试只记录一次日志;被跳过的运行不会重复警告。成功连接、配置发布或显式 MCP 重载会清除退避。重载拥有该连接的进程;CLI 重载不会重置独立的 Gateway。
从 composer 添加服务器¶
在 Control UI 聊天中,选择 + → 连接器 → 添加 MCP 服务器…。该对话框使用与设置相同的服务器字段,并且需要管理员访问权限。
选择 此会话 以仅启用当前会话,或选择 所有位置 以全局启用。任一作用域都会保存全局服务器定义;会话策略是逐会话层。有关完整的作用域和工具访问行为,请参阅 Composer 功能菜单。
从活动对话中,打开 + → 连接器 → 工具访问,以检查或拒绝该会话中的单个工具。该视图遵循会话的实际运行时所有者:内置 OpenClaw 会话读取进程内 MCP 目录,而原生智能体框架可以提供其线程拥有的目录。会话服务器和工具拒绝会在下一轮开始之前由任一运行时强制执行。
从 CLI 添加服务器¶
本地 stdio 服务器:
openclaw mcp add local-tools \
--command node \
--arg ./dist/mcp-server.js \
--cwd /srv/openclaw-tools
openclaw mcp doctor local-tools --probe
远程 Streamable HTTP 服务器,仅暴露其部分工具:
openclaw mcp add docs \
--url https://mcp.example.com/mcp \
--transport streamable-http \
--include 'search,read_*'
openclaw mcp doctor docs --probe
实用配套命令:openclaw mcp status --verbose 用于仅配置摘要,openclaw mcp probe <name> 用于实时能力,当 HTTP 服务器使用 OAuth 时使用 openclaw mcp login <name>。MCP CLI 参考 记录了每个命令、标志和输出格式,以及独立的 mcp serve 桥接。
直接配置服务器¶
将同一个 docs 服务器直接写入配置:
{
mcp: {
servers: {
docs: {
url: "https://mcp.example.com/mcp",
transport: "streamable-http",
enabled: true,
connectionTimeoutMs: 5000,
requestTimeoutMs: 20000,
toolFilter: {
include: ["search", "read_*"],
},
},
},
},
}
已启用的服务器需要一个命令(stdio)或一个 URL(SSE 或 Streamable HTTP)。精确的服务器名称 __proto__ 是保留的;请选择其他名称。设置 enabled: false 会保留定义而不连接它。请勿将凭据放在配置字面量中——通过支持的机密机制存储敏感请求头和环境变量。
交互式应用和插件扩展¶
MCP 服务器还可以提供沙箱化的交互式视图。启用可选的 MCP Apps 主机,以使用这些视图以及受支持的 插件扩展,包括应用入口点、设置、composer 资源和工作区文件查看器。连接服务器不会自动启用其 UI 代码,也不会绕过会话工具权限。
审批¶
Codex MCP 工具审批遵循会话权限姿态:默认的全权限姿态不会提示,而更严格的模式会检查没有安全注释的工具(workspace 可以使用自动审查;guarded 和 read-only 可以提示操作员)。
当提供持久保存时,始终允许 会为精确配置的服务器和工具保存按代理的授权,即使其参数发生变化。 当 OpenClaw 能够明确地将审批匹配到由 Gateway 拥有的实时工具调用时,这适用于 Gateway 托管的 Codex 运行;缺失或模糊的匹配将保留 Codex 的原生/会话行为。Codex 应用、原生插件服务器和 computer-use 服务器被排除。授权在重启后保留,并在下一次 线程配置和钩子注册时应用,例如新会话或 重启;当前会话使用 Codex 记住的决策。
使用 openclaw mcp configure <server> --approval approve|prompt|auto 覆盖服务器;显式模式优先于由姿态派生的默认值。已存储的授权仅在 auto 或未指定服务器模式下生效;显式 prompt 会持续询问。通过 MCP 工具授权 检查或撤销授权。有关详细信息,请参阅 Codex 工具审批;有关 Slack 按钮投递,请参阅 Slack 中的原生审批。
故障排除¶
服务器显示在设置中但未暴露任何工具¶
运行 openclaw mcp doctor <name> --probe。Doctor 首先验证已保存的定义,然后打开实时连接,并报告服务器声明的工具和其他能力。如果已连接但缺少预期工具,请检查 toolFilter.include 和 toolFilter.exclude。
stdio 服务器无法启动¶
确认 command 在 Gateway 进程环境中可解析,并且 cwd 存在。参数应放在 args 中,显式的 transport: "stdio" 要求命令非空。
对于由 OpenClaw 内置 MCP 客户端启动的服务器,调试日志会在 stderr 诊断前添加 bundle-mcp:<name>: 前缀。Unicode 字符在拆分写入中得以保留,并且关机诊断会被保留。没有换行符的输出会短暂缓冲最多 250 ms,然后作为进度片段记录;这不会等待服务器停止写入。超过 8 KiB 缓冲区的诊断会保留其 Unicode 安全尾部,并带有 [stderr line truncated] 标记。
HTTP 服务器需要授权¶
设置 auth: "oauth" 以及任何必需的 oauth 元数据。在 设置 → MCP 中,管理员可以为使用共享原生 OAuth 凭据的已启用 HTTP 服务器选择 登录。在浏览器中批准访问,然后返回设置。如果浏览器阻止新标签页,请使用对话框中的登录链接。
身份验证已保存 表示凭据已保存在开始登录时所选的 Gateway 上。这并不能证明服务器可访问或其工具可用;接下来请运行检查或使用连接器。更改所选 Gateway 或代理会关闭对话框。Gateway 重启会结束未完成的浏览器登录,但不会删除已保存的凭据。
浏览器登录要求设置位于 Gateway 自身的 HTTPS 地址(包括操作员管理的反向代理或 Tailscale Serve 路由)、其本地环回地址或其已发布的 Tailscale 地址。单独托管的 UI 无法接收 Gateway 的回调。旧版 Gateway 和不受支持的地址保留终端说明。具有现有 auth-profile 映射或按请求者身份识别的服务器改用该账户的登录路径;设置不会为它们创建第二个凭据。
未完成的 CLI 尝试可能会为 CLI 回调留下客户端注册。当尚未保存凭据时,浏览器登录会自动注册其自己的回调。与已保存凭据关联的注册会被保留,以便刷新令牌保持可用。
如果 登录 不可用,或现有凭据需要 CLI 回调,请在拥有该连接器的安装上运行以下命令:
按照显示的授权 URL 操作。OpenClaw 通常会捕获环回重定向并自动保存凭据;当浏览器无法访问回调监听器时,请使用显示的 --code 命令。
更改未到达活动代理¶
openclaw mcp reload 会刷新由当前 CLI 进程拥有的运行时。在其他位置运行的 Gateway 或代理需要其自身的重新加载、配置发布或重启。
相关¶
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw