管理已保存的 MCP 服务器
本页介绍 OpenClaw 的 MCP 客户端注册表:读取和写入 mcp.servers 定义的子命令、它们的 Codex 审批行为,以及现成的服务器配置方案。
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 配置和 OAuth 凭据状态
status、list、show、不带--probe的doctor、set、configure、tools、logout、reload和unset不会连接到目标 MCP 服务器login为配置的 HTTP 服务器执行 MCP OAuth 网络流程,并保存由此产生的本地凭据status --verbose在不连接的情况下打印解析后的传输、认证、超时、过滤器和并行工具调用提示doctor检查已保存的定义,以发现本地设置问题,例如缺少 stdio 命令、无效的工作目录、缺少 TLS 文件、已禁用的服务器、字面形式的敏感 header/env 值,以及不完整的 OAuth 授权- 静态检查通过后,
doctor --probe会添加与probe相同的实时连接验证 probe连接到所选服务器或所有已配置的服务器,列出工具,并报告能力/诊断信息add根据 flags 构建定义并在保存前进行检查,除非设置了--no-probe,或需要先进行 OAuth 授权enabled: false会将服务器保留在已保存状态,但将其排除在嵌入式运行时发现之外requestTimeoutMs和connectionTimeoutMs以毫秒为单位设置每个服务器的请求和连接超时supportsParallelToolCalls: true标记适配器可以并发调用的服务器- HTTP 服务器可以使用静态 header、OAuth 登录、TLS 验证控制以及 mTLS 证书/密钥路径
- 嵌入式 OpenClaw 在正常的
coding和messaging工具配置中暴露已配置的 MCP 工具;minimal仍然隐藏这些工具,而tools.deny: ["bundle-mcp"]会显式禁用它们 - 整服务器级别的工具拒绝(如
tools.deny: ["bundle-mcp"]或tools.deny: ["docs__*"])会在连接前排除这些服务器;单个工具级别的拒绝仍适用于已发现的目录 - 每服务器的
toolFilter.include和toolFilter.exclude会在已发现的 MCP 工具成为 OpenClaw 工具之前对其进行过滤 - 声明提供资源或提示词的服务器还会公开用于列出/读取资源和列出/获取提示词的实用工具;这些生成的实用工具名称(
resources_list、resources_read、prompts_list、prompts_get)使用相同的包含/排除过滤器 - 获取的提示词会将其描述和带角色标签的消息呈现给智能体,包括供具备视觉能力的模型使用的原生图像块;Code Mode 保留原始提示词的 JSON 形态
- 动态的 MCP 工具列表变更会使该会话的缓存目录失效;下一次发现/使用时将从服务器刷新
- 重复的 MCP 工具请求/协议失败会短暂暂停该服务器,这样单个故障服务器不会消耗整个轮次
- 会话级的 MCP 运行时在轮次之间保持存活,直到会话重置/删除、压缩 ID 翻转、显式停止、相关的服务器配置更改或 Gateway 关闭;运行时拥有的 stdio 子进程会在清理期间终止
- 没有存续运行时会话的分离式一次性运行会在运行结束时回收其 MCP 运行时;保留的会话记录不会延长该生命周期
- 原生 harness 准备会保留最终 bundle 的服务器连接和 OAuth 上下文,直到会话关闭;该 bundle 之外未使用的发现服务器在准备完成后且没有其他租约需要它们时可以被回收
- 取消压缩会关闭为该压缩创建的 MCP 运行时,包括未完成的启动和工具发现
mcp.sessionIdleTtlMs是一个可选的空闲超时设置(毫秒):未设置或为0时保持运行时存活,正有限值启用空闲驱逐(小数部分向下取整)- 一个 Gateway 在会话和请求方分区中最多接纳 256 个带有服务器连接的 OpenClaw 管理运行时;没有可用服务器的会话以及仅需登录的目录不会消耗此限制。达到限制后,新的接纳请求将被拒绝,直到您停止或重置未使用的会话。详见 MCP 配置
运行时适配器可以将此共享注册表规范化为其下游客户端期望的形状。例如,嵌入式 OpenClaw 直接使用 OpenClaw 的 transport 值,而 Claude Code 和 Gemini 接收 CLI 原生的 type 值,如 http、sse 或 stdio。
CLI 的 login、logout、probe、doctor --probe 以及修改已保存服务器的命令(add、set、configure、tools、unset)要求本地 Gateway 已停止。这些命令在加载可写状态之前获取独占的状态所有权,并在 OAuth 回调、凭据刷新和清理期间保持该所有权。如果某个 Gateway 拥有所选的状态目录,该命令会在尝试本地写入之前拒绝执行,并给出停止后重试的指引。对于受支持的实时 MCP 设置和登录操作,请使用 Control UI。list、show、status 和不带 --probe 的 doctor 在 Gateway 运行期间仍然可用。
已保存的 MCP 服务器定义¶
命令:
openclaw mcp list [--json]openclaw mcp show [name] [--json]openclaw mcp status [--verbose] [--json]openclaw mcp doctor [name] [--probe] [--json]openclaw mcp probe [name] [--json]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 reloadopenclaw mcp unset <name>
说明:
list会对服务器名称进行排序。- 不带名称的
show会打印完整的已配置 MCP 服务器对象。 status会在不建立连接的情况下对已配置的传输进行分类。--verbose会包含已解析的启动、超时、OAuth、过滤器和并行调用详情,包括已存储的 OAuth 令牌需要额外授权的情况。包含凭据的 stdio 参数会在文本和 JSON 输出中被遮蔽。doctor会执行静态检查,而不建立连接。如果命令还应验证已启用的服务器能够连接,请添加--probe。probe会连接到已启用的已保存服务器,并报告工具数量、资源/提示支持、列表变更支持以及诊断信息。如果没有启用任何服务器,普通输出会说明无法检查任何服务器,并显示添加/启用命令;--json会保留其空结果信封。指定名称的已禁用服务器会被拒绝,并给出启用提示。add接受 stdio 标志,例如--command、--arg、--env和--cwd,或 HTTP 标志,例如--url、--transport、--header、--auth oauth、TLS、超时和工具选择标志。使用--approval auto|prompt|approve设置 Codex 工具审批模式。set期望在命令行上提供一个 JSON 对象值。configure会更新启用状态、工具过滤器、超时、OAuth、TLS、Codex 审批模式和并行工具调用提示,而不替换整个服务器定义。添加--probe可在保存前验证更新后的服务器。tools会更新每个服务器的工具过滤器。包含/排除条目是 MCP 工具名称和简单的*通配符。login会为配置了auth: "oauth"的 HTTP 服务器运行 OAuth 流程。对于回环重定向,OpenClaw 会监听浏览器回调并自动完成登录。打印的--code命令仍然是远程、无头或无法访问回调的回退方案。logout会清除指定服务器已存储的 OAuth 凭据,但不会删除已保存的服务器定义。reload仅释放当前 CLI 进程中缓存的进程内 MCP 运行时。位于其他进程中的 Gateway 或 agent 进程仍需要各自的重新加载或重启路径。- 对于 Streamable HTTP MCP 服务器,请使用
transport: "streamable-http"。openclaw mcp set还会将 CLI 原生的type: "http"规范化为相同的标准配置形状,以兼容。 - 如果指定名称的服务器不存在,
unset会失败。
示例:
openclaw mcp list
openclaw mcp show context7 --json
openclaw mcp status --verbose
openclaw mcp doctor --probe
openclaw mcp probe context7 --json
openclaw mcp add memory --command npx --arg -y --arg @modelcontextprotocol/server-memory
openclaw 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 docs
openclaw mcp logout docs
openclaw mcp unset context7
Codex 工具审批¶
MCP 工具审批遵循当前生效的 Codex 会话权限姿态,除非你显式覆盖该服务器的审批模式。默认的完全权限姿态不会提示,包括没有 MCP 安全注释的工具。更严格的姿态会保留审批检查:workspace 可以使用自动审查,而 guarded 和 read-only 可以针对未注释的工具向操作员提示。交互式回合可以在 Control UI 中批准这些调用。
对于你信任的服务器,在添加时设置模式:
openclaw mcp add memory \
--command npx \
--arg -y \
--arg @modelcontextprotocol/server-memory \
--approval approve
对于现有已保存的服务器,仅更新其审批模式:
该标志会写入 codex.defaultToolsApprovalMode。显式使用 openclaw mcp configure <server> --approval approve|prompt|auto 会覆盖该服务器由姿态派生的默认值:approve 绕过逐次调用审批,prompt 对每次调用都询问,auto 使用工具的安全注释。仅对受信任的服务器使用 approve。当服务器使用 auto 且其任何工具都没有安全注释时,mcp probe 和 mcp doctor --probe 会发出警告;该警告描述的是在需要提示的姿态下的调用。
当提供 Allow Always 时,它批准的是该工具,而不仅是当前参数。对于在 mcp.servers 中配置的服务器上运行的 Gateway 托管 Codex 运行,当提供持久化存储,并且该审批明确匹配一个正在运行的 Gateway 拥有的工具调用时,OpenClaw 会在主机审批文档中保存一个持久的、按 agent 划分的服务器/工具授权。缺失或模糊的匹配,以及仅允许会话持久化的请求,会保留 Codex 的原生/会话行为。Codex 应用、原生插件服务器和 computer-use 服务器被排除在外。
已存储的授权在 auto 或未指定服务器模式下生效。显式 prompt 即使已有授权也会继续询问;显式 approve 已经绕过审批。新授权会在下一次线程配置和 hook 注册时生效,例如新会话或重启。当前会话会继续使用 Codex 记住的决定。
使用 openclaw approvals get --gateway 检查授权,并使用 openclaw approvals set --gateway --file <file> 通过编辑 agents.<agentId>.mcpTools 撤销它们。撤销也会在下一次准备/注册时生效。当服务器保存在原生配置中时,Codex 还可以额外持久化其自身的审批;如果存在,请单独撤销它。有关文档结构和导出/编辑工作流,请参阅 MCP 工具授权。
有关通过 Slack 按钮交付审批,请参阅 Slack 中的原生审批。
当操作员拒绝 MCP 工具审批时,Codex 只会向模型报告其通用的“用户拒绝了 MCP 工具调用”;补救措施显示在操作员卡片上,而不是显示给模型。
可选的 codex 块是仅用于 Codex app-server 线程的 OpenClaw 投影元数据;它不会更改 ACP 会话、通用 Codex harness 配置或其他运行时适配器。使用非空的 codex.agents 可将服务器仅投影到特定的 OpenClaw agent id。空、空白或无效的 agent 列表会被配置校验拒绝,并由运行时投影路径省略,而不是变为全局。OpenClaw 会在将原生 mcp_servers 配置交给 Codex 之前剥离 codex 元数据。
常见服务器配置¶
这些示例仅保存服务器定义。之后运行 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
将文件系统服务器限定在 agent 应读取或编辑的最小目录树范围内。
openclaw mcp add memory \
--command npx \
--arg -y \
--arg @modelcontextprotocol/server-memory
openclaw mcp probe memory --json
如果服务器暴露了不应提供给普通 agent 的写入工具,请使用工具过滤器。
openclaw mcp add local-tools \
--command node \
--arg ./dist/mcp-server.js \
--cwd /srv/openclaw-tools \
--env API_BASE=https://internal.example
openclaw mcp status --verbose
doctor 会检查 cwd 是否存在,以及命令能否从配置的环境中解析。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw