switchboard

Switchboard

面向 AI 编码 Agent 的防火墙和密码管理器。

Switchboard 控制 Claude Code 和 Codex 在代码仓库中能够访问的内容。它会找出 Agent 已经能够访问的 MCP 服务和令牌，将密钥从明文配置中移出，改为使用命名的钥匙串引用，并为每个 Agent 发放一张范围受限、会自动过期的通行证。

所有操作都在本地运行。无需账户，无托管服务，无遥测。

功能

• switchboard scan 显示 Agent 在此代码仓库中能够访问哪些 MCP 服务和令牌，以及哪些路由完全绕过 Switchboard。
• switchboard import 将分散的 Claude/Codex MCP 配置整合到一条 Switchboard 路由中，并创建带时间戳的备份和精确的回滚命令。
• 密钥以命名引用的形式保存在操作系统钥匙串中。配置文件中保存的是 secretRef: "github/ci/token"，而不是令牌本身。
• switchboard grant 为 Agent 发放一张通行证：可访问指定工具，其他一律拒绝，数小时后自动失效。
• switchboard status 会告知当前通行证是否有效。switchboard revoke 可提前终止通行证。
• 每次经由 Switchboard 路由的工具调用都会写入本地审计日志。使用 switchboard logs 查看日志。

安装

npm install -g @switchboard-mcp/cli

也可以不安装，直接运行：

npx -y @switchboard-mcp/cli@latest scan

需要 Node 22 或更新版本。日常使用以 macOS 为主，CI 在 Linux 上运行；Windows 钥匙串后端也已提供，但使用较少。

快速入门

在 Agent 已经运行的代码仓库中开始：

$ switchboard scan

This looks like acme-app.

Detected:
- Codex Switchboard route missing
- Claude Switchboard route missing
- Claude direct MCP server "github" detected

Authority bypasses:
  high claude:github (github; direct-mcp-server, secret-env-name)

Warnings:
- 1 direct MCP bypass finding(s), including 1 high-risk finding(s), were detected.

这个高风险发现指的是 .mcp.json 中以明文保存的 GitHub 令牌。将它移至 Switchboard 管理：

switchboard import --dry-run          # see the plan first
switchboard import --write --cleanup-client
switchboard secrets set <ref>         # store the token; import prints the exact command
switchboard install claude --write    # route the agent through Switchboard

导入操作会将客户端配置改写为单条 Switchboard 路由，把明文令牌替换为命名的钥匙串引用，并留下备份和精确的回滚命令。导入操作本身绝不会读取密钥值；只有执行 secrets set 时，令牌才会真正写入钥匙串。接下来为 Agent 设置访问范围：

switchboard grant --for 4h

你会获得上面的通行证。想提前撤销时：

$ switchboard revoke
Revoked pass grant-main (main). The agent's scoped access is off now.

switchboard doctor 会随时告诉你下一步需要修复的问题。如果代码仓库尚无 MCP 配置，switchboard setup github-ci 会从安全的服务提供方模板开始。

Switchboard 不做什么

• 它不是沙箱。 Switchboard 只管控经由它的路径：Switchboard MCP 端点和 switchboard run。具有原始 Shell 访问权限、服务提供方 CLI、浏览器会话或直接 MCP 路由的 Agent 可以绕过它。switchboard scan 会报告这些绕过路由，供你清理或有意接受。
• 备份会原样保留旧配置。 如果导入前令牌以明文保存，备份中仍会包含该令牌。迁移后请轮换旧令牌，并妥善保管备份。
• 通行证只约束已接入的 Agent。 如果客户端尚未接入，switchboard grant 会明确说明这一点；使用 switchboard install <claude|codex> 可弥补这一缺口。
• 这是 Alpha 软件。 以本地优先的工作流为主、谨慎描述功能，同时仍有一些待完善之处。通行证和审计的契约采用版本化 JSON，但内容可能会有变更。

命令

命令	功能
switchboard scan	显示 Agent 在此仓库中可以访问的内容，包括绕过路由
switchboard import	将 Claude/Codex MCP 配置整合到一条受控路由中
switchboard grant / revoke	为仓库的 Agent 授予有期限、限定范围的通行权限，或立即撤销
switchboard status	当前是否有有效通行权限，以及正在使用哪份配置
switchboard doctor	检查设置并指出下一步要修复的问题
switchboard setup <preset>	根据提供方安全模板引导完成设置（运行 switchboard presets list 查看模板）
switchboard auth <preset>	将预设的提供方令牌存入钥匙串
switchboard secrets	设置、列出、移除和诊断已命名的密钥引用
switchboard run	使用通行权限范围内的凭据和审计记录，运行获准的提供方命令
switchboard install <client>	将 Claude Code 或 Codex 接入 Switchboard（添加 --scope user，即可在每个仓库中使用同一服务）
switchboard pass	创建和检查任务范围内的通行权限，包括租约、门控和移交
switchboard approvals	审查并决定受审批门控的工具调用
switchboard tools	列出通行权限开放的工具范围
switchboard logs	查看本地审计日志
switchboard dashboard	本地只读仪表板：有效通行权限、拒绝记录和审计流
switchboard audit	仓库权限状态报告，可导出为 JSONL

报告状态的命令支持使用 --json 供脚本和测试框架调用，并提供带版本号的 架构。其余信息请参阅 switchboard <command> --help。

工作原理

Switchboard 读取分层 YAML 配置（全局配置，然后是 .switchboard.yaml，再然后是 .switchboard.local.yaml）。每个配置档案都指定一个上游 MCP 服务及其所需的 密钥引用。运行时，Switchboard 会将获准的配置档案挂载为一个 MCP 端点，仅在启动时 从操作系统钥匙串解析密钥引用，并为每个工具添加命名空间，以便通行权限可以允许 github_ci_*，并拒绝其他所有内容。通行权限、审批和审计记录都是本地纯文本文件，其中 仅按名称引用密钥，不会保存密钥值。

默认使用操作系统钥匙串后端存储密钥。开发机器和 CI 可使用明文回退方式，但必须 显式选择启用：SWITCHBOARD_ALLOW_UNSAFE_SECRET_BACKENDS=1。

适用于测试框架和子 Agent 系统

switchboard pass create --from github-ci --json 会返回 workspaceLease.mcpLaunch 负载：用于启动通行权限范围内 stdio MCP 端点的确切 命令，以及通行权限策略和租约。Switchboard 授予并审计权限；测试框架负责调度、重试 和 Agent 进程。JSON 契约详见 docs/use-cases/harness-json-contracts.md。

替代方案

• 仅使用项目 MCP 配置也可行，但它只是静态接线，令牌保存在 文件中。Switchboard 会导入这些配置、迁移令牌，并在此基础上添加范围受限且会过期的访问权限。
• Docker MCP Gateway 和 MCP 运行时擅长运行和打包 MCP 服务。 Switchboard 是它们上层的本地权限层，负责决定 Agent 在某项任务中获得哪些配置档案、 工具和租约。网关也可以作为上游服务，配置在 Switchboard 配置档案中。
• 托管工具平台（Composio、Arcade）提供托管 OAuth 和广泛的 SaaS 覆盖。Switchboard 面向编码 Agent 仓库，优先采用本地方案：本地密钥、本地审计， 不依赖托管服务。
• 直接给 Agent 一个令牌虽然快捷，但令牌一旦权限过大、长期有效，或被 复制到错误的文件中，就会带来风险。这正是 Switchboard 要解决的问题。

开发

git clone https://github.com/wkoverfield/switchboard.git
cd switchboard
pnpm install
pnpm build
pnpm switchboard --help
pnpm test

欢迎贡献；请参阅 CONTRIBUTING.md，并按照 SECURITY.md 中的说明私下报告漏洞。

冒烟测试和全新 Agent 评估位于 scripts/；CI 会运行完整测试集。 首页演示是一个 VHS 磁带：brew install vhs && pnpm build && vhs examples/switchboard.tape。 更深入的文档：快速入门、 威胁模型、 提供方安全模板、 路线图。

Agent 可以通过 MCP 阅读这些文档： npx -y @switchboard-mcp/docs-mcp 提供 list_docs、read_doc 和 search_docs，并会及时更新 llms.txt。首页和文档 站点位于 site/（静态构建，pnpm --filter @switchboard-mcp/site build）。

许可证

MIT。请参阅 LICENSE。