OpenClaw mcporter 技能：用 mcporter CLI 发现、鉴权、调用并生成外部 MCP 服务器

本篇以 OpenClaw 内置技能文件 skills/mcporter/SKILL.md 为主体，系统讲解 mcporter 技能的定位、完整命令集（list / call / auth / config / daemon / 代码生成）以及五种工具调用语法。读完后你能掌握：如何在 OpenClaw 环境中通过 mcporter 直接对接 HTTP 或 stdio 类型的 MCP 服务器、如何管理其注册表配置文件，并能从 OpenClaw 源码层面理解该注册表在安全审计中的处理方式和隔离边界。

技能定位：OpenClaw 的 MCP 客户端运行时

mcporter 是 OpenClaw 的一个内置技能（bundled skill），技能说明中给出的官方描述是：“List, configure, authenticate, call, and inspect MCP servers/tools with mcporter over HTTP or stdio.” 即用 mcporter 通过 HTTP 或 stdio 两条通道来列出、配置、鉴权、调用和检查 MCP 服务器与工具。

在 OpenClaw 的默认工作区参考文档 docs/reference/AGENTS.default.md 中，mcporter 被列在“核心技能”名册里，定位为 tool server runtime/CLI for managing external skill backends（用于管理外部技能后端的工具服务器运行时 / CLI）。

技能的元数据（位于 SKILL.md 的 YAML frontmatter 中）声明了它的依赖与安装方式：

• requires.bins: ["mcporter"] —— 技能可用性取决于系统中存在 mcporter 可执行文件；
• install —— 当二进制缺失时，OpenClaw 的技能安装器可通过 Node 通道安装 npm 包 mcporter（安装标签为 “Install mcporter (node)”），并产出 mcporter 这个 bin；
• homepage: http://mcporter.dev —— 上游项目主页（仅作技能声明，本文不展开外部站点内容）。

这意味着 mcporter 的“门槛”就是一个 CLI 二进制：OpenClaw 的技能门控（gating）只检查 bin 是否存在，安装策略则复用通用的 Skills config 机制（如 skills.install.nodeManager 控制用 npm/pnpm/yarn/bun 哪一个包管理器来装）。

快速上手：三条核心命令

SKILL.md 给出的 Quick start 是三条最小可用命令，覆盖了“发现 → 查看参数 → 调用”的主流程：

# 1. 列出当前注册表中的所有 MCP 服务器
mcporter list

# 2. 查看指定服务器暴露的工具及其 schema（参数定义）
mcporter list <server> --schema

# 3. 调用某个服务器的某个工具，key=value 形式传参
mcporter call <server.tool> key=value

其中 <server.tool> 采用“服务器名.工具名”的选择器写法；--schema 让输出从“有哪些工具”深入到“每个工具接受什么参数”，是编写调用命令前最有价值的一步。

调用工具：五种调用语法全解析

mcporter call 子命令支持五种写法，SKILL.md 全部给出了一手可运行的示例：

语法形式	示例	适用场景
选择器（selector）	mcporter call linear.list_issues team=ENG limit:5	常规调用，key=value 传参；limit:5 表示数字/结构化取值
函数式（function syntax）	mcporter call "linear.create_issue(title: \"Bug\")"	参数名与函数实参一一对应，语义上更像在调用一个函数
完整 URL	mcporter call https://api.example.com/mcp.fetch url:https://example.com	直接对某个 HTTP 端点发起调用，不依赖注册表中的服务器别名
Stdio 进程	mcporter call --stdio "bun run ./server.ts" scrape url=https://example.com	本地以 stdio 方式拉起一个 MCP 服务器进程并立即调用（示例用 bun run 启动本地 server.ts）
JSON payload	mcporter call <server.tool> --args '{"limit":5}'	参数复杂（嵌套对象、数组等）时，用 --args 传入完整 JSON

几条值得注意的要点：

• 选择器与函数式写法都要求目标服务器已在注册表中（或可用完整 URL 形式直接寻址）；
• stdio 形式把“服务器进程”内联进调用命令，适合本地脚本型 MCP 服务器，无需先 config add 持久化；
• 当参数包含引号等特殊字符时（如函数式中的 title: "Bug"），整条命令需要用引号包裹，这在 Agent 自动拼装命令时是常见的出错点。

鉴权与配置管理

SKILL.md 的 “Auth + config” 部分给出两组命令：

# OAuth 鉴权：对注册表中的服务器名或原始 URL 发起 OAuth 流程，--reset 重置凭据
mcporter auth <server | url> [--reset]

# 注册表配置管理
mcporter config list|get|add|remove|import|login|logout

mcporter config 是一组子命令：list / get 查看已有服务器条目，add / remove 增删，import 批量导入，login / logout 管理登录态。结合 mcporter auth，一个需要 OAuth 的 HTTP 型 MCP 服务器的典型接入流程是：config add 登记端点 → auth <server> 完成授权 → list <server> --schema 确认可用工具 → call 调用。

关于配置文件，SKILL.md 明确了两条约定：

1. 默认配置路径为 ./config/mcporter.json，可用 --config 覆盖；
2. 优先使用 --output json 获得机器可读结果 —— 这一条对 OpenClaw 场景尤其重要，因为技能通常由 Agent 以子进程方式执行 mcporter，结构化 JSON 输出才能被可靠解析（例如解析失败的原始子进程文本不会直接暴露给上层，这一点在 OpenClaw 的相关发布记录中也有体现，见 docs/releases/2026.7.1.md）。

在 OpenClaw 的实际部署中，该注册表位于状态目录下。Skills config 文档 在讨论 Agent 技能白名单的边界时，明确引用了 MCP 客户端注册表的真实路径：~/.openclaw/skills/config/mcporter.json。也就是说，默认 ./config/mcporter.json 的相对布局，落到 OpenClaw 宿主上就是状态目录下的 skills/config/mcporter.json。

这里还有一个容易混淆的边界：OpenClaw 自带 openclaw mcp 命令管理 mcp.servers 配置项，但按 docs/cli/mcp.md 的说明，list、show、set、unset 只读写 OpenClaw 自己管理的 mcp.servers 条目，不包含 mcporter 注册表中的服务器；要查看 mcporter 那一套注册表，应使用 mcporter list。两者是相互独立的 MCP 客户端注册表。

守护进程：daemon 管理

mcporter 支持以常驻守护进程方式运行服务器，SKILL.md 给出完整的生命周期命令：

mcporter daemon start
mcporter daemon status
mcporter daemon stop
mcporter daemon restart

守护进程模式适合需要被反复调用、不希望每次 call 都冷启动服务器的场景；restart 用于配置变更后的热更新。

代码生成：从 MCP 服务器到 CLI / TypeScript

SKILL.md 的 “Codegen” 部分提供了三类生成能力：

# 1. 生成 CLI 命令：按服务器名或 URL
mcporter generate-cli --server <name>
mcporter generate-cli --command <url>

# 2. 检查已生成的 CLI 产物（--json 输出机器可读结果）
mcporter inspect-cli <path> [--json]

# 3. 生成 TypeScript 代码
mcporter emit-ts <server> --mode client|types

• generate-cli 把 MCP 服务器的工具集物化为本地 CLI，使脚本和 CI 环境可以脱离 mcporter 本身直接调用；
• inspect-cli 用于验证生成产物的内容，配合 --json 可做程序化检查；
• emit-ts 面向 TypeScript 集成，--mode client 生成客户端代码、--mode types 生成类型定义。

这一组命令的价值在于：MCP 服务器的工具契约（工具名、参数 schema）被直接编译成本地代码工件，既缩短了调用链，也让 IDE 获得类型提示。

源码纵深：OpenClaw 如何审计 mcporter 注册表

以下内容来自 OpenClaw 源码，用于说明 mcporter 注册表在宿主安全体系中如何被对待。

有界读取：防止审计被超大注册表拖垮

audit-mcporter-registry.ts 实现了安全审计（src/security/audit.ts 调用）对 mcporter 注册表的有界读取 readBoundedMcporterRegistry，关键约束从源码常量可以直接读出：

• 注册表路径固定为 <stateDir>/skills/config/mcporter.json；
• 大小上限 MAX_MCPORTER_REGISTRY_BYTES = 16 MiB，以 64 KiB 分块读取，超限即拒绝；
• 返回三种状态：ok（读取成功）、missing（文件不存在，属于无需处置的情况）、rejected（存在但无法安全检查，附原因 oversized | unreadable | non-regular | malformed）。

几个实现细节值得注意：文件以 O_RDONLY | O_NONBLOCK 打开且故意不加 O_NOFOLLOW，以便合法符号链接指向的注册表能被跟随检查，同时用分块读取为总大小兜底；文件必须是常规文件（stat.isFile()），否则报 non-regular；JSON 解析失败则归为 malformed。被拒绝的注册表不会让审计静默跳过 MCP 边界输入，而是触发告警——“存在但无法检查”本身就是一种需要人工介入的安全信号。

技能白名单不是 shell 级授权边界

mcporter 注册表包含服务器端点与凭据上下文，因此 Skills config 文档 用一段专门的 Warning 明确了边界：Agent 技能白名单只控制技能的发现与加载，不构成 shell 时的授权边界。如果某个 Agent 能在宿主机执行 exec，它的 shell 同样能读取该用户可见的 ~/.openclaw/skills/config/mcporter.json。文档给出的隔离建议是：

• 结合沙箱 / 操作系统用户级隔离；
• 拒绝或严格白名单化宿主 exec；
• 优先为每个 Agent 配置独立的 MCP 服务器凭据（per-agent credentials）。

与浏览器中继的配合

OpenClaw 的 Chrome 扩展方案中，docs/tools/chrome-extension.md 说明本地客户端（“such as mcporter”）会复用扩展建立的 profile relay 端口访问浏览器；并且该中继支持 Browser Relay Authentication v2 客户端，mcporter 即其中之一。这表明 mcporter 在 OpenClaw 生态中不仅管理 HTTP/stdio 型 MCP 服务器，也可以作为中继认证的浏览器工具客户端使用。

实操要点与适用前提

1. 前提：系统装有 Node 环境；mcporter 二进制缺失时可通过 OpenClaw 技能安装器以 npm 包方式安装（skills.install.nodeManager 控制包管理器选择）。
2. 推荐工作流：mcporter list 发现服务器 → mcporter list <server> --schema 核对工具契约 → mcporter auth <server> 完成 OAuth（如需要）→ mcporter call ... 调用；复杂参数改用 --args '{"...": ...}' 的 JSON 形式。
3. Agent 集成：调用时始终加 --output json，保证输出可被程序解析；mcporter 输出中的告警类文本在 OpenClaw 上层会被过滤为清晰的错误而非原始子进程输出。
4. 配置覆盖：需要切换注册表（例如按项目隔离 MCP 服务器集合）时用 --config <path>，默认路径为 ./config/mcporter.json，在 OpenClaw 状态目录下对应 ~/.openclaw/skills/config/mcporter.json。
5. 区分两套注册表：openclaw mcp list 管理 OpenClaw 配置中的 mcp.servers；mcporter list 管理 mcporter 自己的注册表。二者互不包含，排障时先确认自己在查哪一份。
6. 安全基线：注册表文件应保持在常规文件形态且体积可控（审计上限 16 MiB）；多 Agent 共享宿主时，按上述隔离建议避免跨 Agent 的 MCP 凭据泄露。

小结

mcporter 技能把“MCP 客户端”这一层从 Agent 运行时中解耦为一个独立 CLI：发现（list / --schema）、调用（五种调用语法）、鉴权（auth + config）、常驻（daemon）、代码生成（generate-cli / emit-ts）全链路可用，且以 --output json 输出适配自动化解析。配合 OpenClaw 的有界注册表审计与技能隔离边界，这套机制既保持了 MCP 生态的开放接入能力，又把注册表这类含端点信息的敏感输入纳入了宿主安全体系的可检查范围。