管理已保存的 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 直接使用 OpenClaw 的 transport 值，而 Claude Code 和 Gemini 接收 CLI 原生的 type 值，例如 http、sse 或 stdio。

已保存的 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 reload
• openclaw mcp unset <name>

说明：

• list 对服务器名称进行排序。
• 不带名称的 show 会输出完整配置的 MCP 服务器对象。
• status 在不连接的情况下对已配置的传输方式进行分类。--verbose 包含已解析的启动、超时、OAuth、过滤器和并行调用详细信息，包括存储的 OAuth token 需要额外授权的情况。在文本和 JSON 输出中，包含凭据的 stdio 参数会被脱敏处理。
• 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 或代理进程仍需要各自的重新加载或重启路径。
• 对于 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

对于已保存的现有服务器，仅更新其审批模式：

openclaw mcp configure 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 会在主机审批文档中保存一个持久的、按代理划分的服务器/工具授权。缺失或模糊的匹配，以及仅允许会话持久化的请求，会保留 Codex 的原生/会话行为。Codex 应用、原生插件服务器和 computer-use 服务器不包括在内。

存储的授权在 auto 模式或未指定服务器模式下生效。显式的 prompt 即使存在授权也会继续询问；显式的 approve 则已经绕过了审批。新的授权会在下一次线程配置和钩子注册时被拾取，例如新会话或重启。当前会话会继续沿用 Codex 记住的决定。

使用 openclaw approvals get --gateway 查看授权，并使用 openclaw approvals set --gateway --file <file> 通过编辑 agents.<agentId>.mcpTools 来撤销授权。撤销操作也会在下一次准备/注册时生效。当服务器保存在原生配置中时，Codex 还会额外持久化其自身的审批；如果存在，请单独撤销。有关文档结构及导出/编辑工作流，请参阅 MCP 工具授权。

有关通过 Slack 按钮交付审批，请参阅 Slack 中的原生审批。

当操作员拒绝 MCP 工具审批时，Codex 只会向模型报告其通用的 "user rejected MCP tool call"；补救措施会显示在操作员卡片上，而不是显示给模型。

可选的 codex 块仅是 OpenClaw 用于 Codex 应用服务器线程的投影元数据；它不会改变 ACP 会话、通用 Codex harness 配置或其他运行时适配器。使用非空的 codex.agents 可以将服务器仅投影到特定的 OpenClaw 代理 ID。空、空白或无效的代理列表会被配置验证拒绝，并被运行时投影路径省略，而不会成为全局配置。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

openclaw mcp add memory \
  --command npx \
  --arg -y \
  --arg @modelcontextprotocol/server-memory
openclaw 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.example
openclaw 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

```

直接桌面控制服务器会继承其启动的进程的权限。请使用范围较窄的工具过滤器和 OS 级别的权限提示。