Subagent MCP

Subagent MCP

独立的执行环境。一个 Codex 编排器。

当一个模型既规划变更、又负责实现和审查时，审查者会沿用作者的上下文，也会有相同的盲点。它最终可能只是在确认自己的计划，而非检验计划。

Subagent MCP 保留 Codex 作为主 Agent 和最终决策者，同时将有明确边界的工作委派给外部 Agent 运行时。每个运行时都由一个模型及其原生执行环境组成，因此 Codex 可以从拥有不同上下文和假设的独立模型那里获得实现或审查。

这能扩展 Codex 的有效子 Agent 池，并利用你已有的提供商配额。Subagent MCP 绝不会启用、购买或自动充值用量额度，也不会在用户不知情的情况下选择使用额度或付费超额用量。

适配器会将每种原生执行环境转换为相同的生命周期：委派、观察、引导和关闭。核心不会硬编码任何提供商角色或模型名称。

稳定版： 1.0.31 面向 Windows。MCP、软件包、本地主机 UI，以及 Claude Code 和 DeepSeek 原生执行环境集成都已就绪。

运行时状态

• Claude Code — 已就绪。 使用原生 Claude Code 执行环境、提供商原生模型和推理设置、订阅 OAuth 身份，以及实时的无超额用量证据，并在此之后才接受其输出。项目／本地上下文和对精确自动压缩触发条件的证明仍是明确的能力缺口。
• DeepSeek Harness — 已就绪。 对有明确边界的任务使用其原生 ACP 传输和执行环境发布的模型目录。MCP 重启后的恢复、精确的提供商配额证据、交互式输入和已声明的 MCP 仍是明确的能力缺口。提供商已停用的模型路由会终止失败，不会在未经用户明确选择的情况下替换模型。
• Grok Build — 已可用于只读审查。 Windows 适配器仅使用缓存的原生登录，不允许使用额度、付费超额用量或回退模型。版本 1.0.31 仅声明并接受 repo_read。有界写入仍处于开发中，workspace_write 请求会在启动原生进程前失败。其他明确的能力缺口包括终端／测试／Git 执行、网络／网页／浏览器、MCP／插件／钩子、嵌套 Agent、原生工作树、重启恢复、macOS／Linux 支持，以及请求前的精确配额信息。

运行时行为由适配器提供，而非由核心中的提供商专属分支决定。

快速开始

1. 安装

如有需要，请安装 uv，然后注册指定的隔离版本并启动后台 UI：

winget install --id=astral-sh.uv -e
codex mcp add subagent-mcp -- uvx --isolated --from subagent-harness-mcp==1.0.31 subagent-harness-mcp serve
uvx --isolated --from subagent-harness-mcp==1.0.31 subagent-harness-mcp ui --background

注册完成后，启动一个新的 Codex 任务。

2. 配置运行时

在浏览器中打开 http://127.0.0.1:8765。如果后台 UI 已停止，请重新启动同一指定版本：

uvx --isolated --from subagent-harness-mcp==1.0.31 subagent-harness-mcp ui --background

设置和只读活动 UI 始终使用固定的环回端口，不依赖活跃的 MCP 连接。

如果运行时显示需要登录，请点击登录。其原生执行环境会打开操作系统的默认浏览器；Subagent MCP 绝不会索要或存储凭据。在浏览器中完成登录，然后点击刷新。状态检查本身不会打开浏览器。

当前和近期活动按外部 Agent 列出。选择一行即可查看其模型、原生执行环境、工作区、权限、写入集、当前阶段、生命周期、已用时间和经过脱敏的终端结果。提示词、对话记录、隐藏思考内容和原始提供商事件绝不会显示。

3. 委派

用通俗语言要求 Codex：

使用 Subagent MCP 请求外部 Agent 审查此更改，然后独立评估其发现。

Codex 决定委派什么任务、查看结果，并保留最终判断。生命周期响应默认简洁；完整的脱敏报告会保留在本地产品状态中，之后可通过绑定哈希的引用读取或转发。

若要针对某个确切文件进行审批，请在 agent_spawn（位于 task 内）或 agent_send 上传入 inputs：

[{"path":"docs/specs/review.md","expected_sha256":"<lowercase SHA-256>"}]

MCP 会在本机回合开始前，对每个仓库相对路径的文件立即进行只读哈希计算。状态会返回已验证的哈希和配置的推理证明；如果文件已更改，则会在外部 Agent 运行前失败。

模型和回退顺序

每个本机框架都会公布自己的模型选项。界面会显示易读名称和有序优先级列表；高级路由仍可使用精确的提供商 ID。

Claude 选项来自已安装的独立 CLI，并通过公开的 Agent SDK 获取。发现过程会将本机别名解析为精确的模型 ID，不会发送提示词，并将生成的元数据缓存最多 60 秒。CLI 身份变更会使缓存失效。若缺少身份验证或无法进行发现，仍可输入自定义的精确 ID；这不会更改已保存的模型选项。新增模型名称无需发布新的 MCP 版本，但模型仍可能要求使用较新版本的本机 CLI。常规兼容性探测仍单独进行。

模型选择器仅通过明确操作添加和移除模型。打开并应用选择器不会更改现有顺序，除非你对其进行编辑。

runtime_list 包含 config_revision。获得用户批准后，使用该修订版本和新的请求 ID，通过 runtime_configure 配置运行时：

{
  "request_id": "choose-claude-model-1",
  "expected_revision": 7,
  "patch": {
    "runtimes": {
      "claude-code": {
        "options": {
          "variant.0.model": "claude-opus-5-5",
          "variant.0.reasoning.effort": "max"
        }
      }
    }
  }
}

此示例会更改现有变体。若要创建新的运行时，请提供 enabled: true，并在 options.model_priority 中填写所选 ID 及其必需的推理选项。设置和 MCP 使用相同的验证和修订版本检查。重复提交相同的请求会返回已保存的回执；输入不同则需要新的请求 ID。若变更中断且没有回执，必须先检查当前状态，再进行其他更改。此工具无法更改项目的信任状态，也不会自动启动身份验证、实时探测或提供商任务。

当提供商明确报告配额或额度已耗尽 （QUOTA_PAUSED）时，Subagent MCP 会将该确切模型移至底部，供后续任务使用。它不会重试失败的任务。含义不明确的失败、崩溃和超时不会改变模型顺序，也不会触发另一笔付费请求。

该失败任务仍会处于终止状态，但下一次明确委派时会实时重新检查提供商；不会以缓存的重置时间或等待检查点代替此检查。当本机框架没有安全的请求前配额查询接口时，状态会保持未知，而不会推断为配额已耗尽。

运维恢复最多执行三次操作。可重试本地状态操作和明确发生在调用提供商之前的失败。DeepSeek 也会对明确的临时上游 HTTP 429 进行重试，总尝试次数最多为三次。通用提供商失败绝不会自动重放：只读任务会返回有限的指导，供用户明确发起新尝试；写入任务则不可重试，直到核对其写入范围和可能产生的影响。配额、额度、账单、超时及含义不明确的生命周期失败绝不会触发再次调用提供商。本机 ACP 失败会在框架提供相关信息时，附带有限的脱敏 RPC／提供商详情；配额未知属于提供商错误，而非配额耗尽。

DeepSeek 路由可以使用用户授权的现有订阅、无限量套餐或有余额的账户。Subagent MCP 绝不会购买、充值或增加该余额。

审查权限与来源授权

agent_spawn 会将任务和原生宿主读取的来源发送给所选外部提供方。省略 required_capabilities 或将其设为 null 时，默认值为 ["repo_read"]。显式列表（包括 []）会原样保留；绝不会推断写入权限。runtime_list 会公布每个清单的 required_semantic_permissions；Claude 和 Grok 需要 repo_read。

缺少强制权限时，会在本地以 REQUEST_INVALID 失败，不会进行运行时探测、读取任务输入、认领执行或启动提供方。响应包含 recovery.action="repair"、reason="declare_required_permissions" 和 max_attempts=1。请遵循 next_action：只有在所需的提供方／来源访问权限已获授权时，才使用新的 request_id 修正载荷。不得静默替换显式限制。此修正不允许重放失败的原生执行，也不允许重试配额、身份验证、访问、策略或启动状态不明确的失败。

控制器应复用针对指定提供方和来源范围已有的授权。如果仅审查规范需要额外的私有来源，请在派发前征求同意，例如：“是否允许所选提供方读取这份规范和这些指定的源文件夹，以进行只读审查？”请使用宿主支持的审批或用户提问工具；说明宿主拒绝请求的原因，将问题保持为待处理状态，并遵从答复。未获得所需批准时，不要重复已被拒绝的调用。task.inputs 用于验证文件身份；它不是读取沙箱，也不是授权凭证。若宿主在调用到达服务之前就拒绝了请求，MCP 服务无法显示问题；聊天中的同意也不会授予操作系统／OAuth 访问权限。

长时间运行的工作

agent_wait 是有界的本地观察，不是模型的截止时间。如果它返回 running 且 wait_policy=continue_while_running，外部 Agent 可能仍在工作或思考。请继续观察同一对话；仅凭经过的时间，绝不会触发重试、回退、中断或向另一个提供方发出请求。

并发写入者

写入任务可在 write_set 中声明最多 32 个相对于仓库的文件或目录根路径。规范化后的绝对路径集合互不相交时，外部写入者可以并发运行。相同路径以及父子路径会发生冲突；任务名称和通道名称不会影响锁定。

省略 write_set 时，为向后兼容，该执行会获得整个工作区。每个适配器也会在其原生宿主边界强制执行规范化后的路径。创建写入请求前请检查 runtime_list：write_root_mode=path-prefix 支持精确的文件或目录前缀，而 existing-directory 要求路径是现有目录。当前 DeepSeek Harness 原生会话公布的是 existing-directory，且仅支持一个可写根路径。Subagent MCP 不会将精确文件范围扩大到其父目录；只有在明确接受该更宽泛的范围时才使用该目录，否则请选择强制执行 path-prefix 的运行时。多个有效目录根路径会拆分为互不相交的写入者调用。这些租约用于协调 Subagent MCP 执行；它们不是针对无关本地进程的操作系统沙箱。

在当前 Windows 公共切片上，将 cwd 设为检出根目录，并使用 workspace="current"。对于 DeepSeek 写入，请传入 workspace_write，并且相对于 cwd 精确指定一个现有目录，例如 write_set=["Assets/_Project/Core/Scripts/GameSettings"]。绝对路径、不存在的路径或精确文件都不是有效的 existing-directory 根路径。

在 Windows 上，DeepSeek 原生沙箱必须创建受限令牌 ACE，因此当前用户还需要对所选目录拥有 WRITE_DAC 权限。Subagent MCP 会在 ACP 或提供方执行前以只读方式检查此权限。它不会更改所有权或 ACL。检查失败时会保持为 CAPABILITY_MISSING；绝不会回退到 danger-full-access。

工作原理

flowchart LR
    C["Codex<br/>Main agent & orchestrator"]
    M["Subagent MCP<br/>Gateway"]
    UI["Localhost UI<br/>Settings & activity"]

    C -->|"delegate · steer · observe"| M
    UI --> M

    subgraph E["External agent runtimes — adapter-driven"]
        R1["Model<br/>+<br/>native harness"]
        R2["Model<br/>+<br/>native harness"]
        RN["Future runtimes<br/>via adapters"]
    end

    M -->|"normalized lifecycle"| R1
    M -->|"normalized lifecycle"| R2
    M -->|"normalized lifecycle"| RN

Subagent MCP 负责生命周期规范化、状态、脱敏、租约和熔断。每个适配器都会将该契约转换为对应原生框架所需的格式。完整契约请参阅架构。

在 Windows 上更新或回滚

切换版本时，无需重新安装可能仍在运行的环境。第一个命令使用源版本；添加和启动命令使用目标版本。此示例将 1.0.30 升级到 1.0.31：

uvx --isolated --from subagent-harness-mcp==1.0.30 subagent-harness-mcp ui --stop
codex mcp remove subagent-mcp
codex mcp add subagent-mcp -- uvx --isolated --from subagent-harness-mcp==1.0.31 subagent-harness-mcp serve
uvx --isolated --from subagent-harness-mcp==1.0.31 subagent-harness-mcp ui --background

更改入口后，启动一个全新的 Codex 任务。现有任务会继续使用旧运行时，直到结束。回滚时，使用相同的命令序列，并将精确版本号对调。

如果正在运行的 MCP 报告 UPDATE_QUARANTINED，则无法安全地热加载替换项。不要重试该常驻实例；请使用原生回退方式完成任务，并在全新任务中使用新的精确注册项。

如果要从直接使用 subagent-harness-mcp serve 的入口进行一次性迁移，请先替换注册项，再让旧任务自然结束。替换后，请关闭所有 Codex 窗口一次，然后再按需移除现已不再使用的持久化工具。保留该工具是安全的，因为上述每条新命令都会使用 uvx --isolated。

Subagent MCP 不会自行编辑 Codex 配置、终止 Codex/提供方进程，也不会清除 uv 缓存。

安全与计费

• Subagent MCP 绝不会启用使用额度或更改计费设置。
• Claude 任务可能会消耗订阅包含的额度。每个任务都会验证绑定的 CLI、订阅身份验证、凭据优先级和控制连接，然后要求同一响应提供安全的速率证据，之后才会接受其输出。
• Provider Refresh 不会发送模型提示词。如果原生框架无法在响应前提供精确的速率证据，状态将保持未知，而不会捏造额度结果或使用重置计时。
• 只有在明确耗尽额度后才会触发回退。不安全或含糊的证据绝不会触发另一笔付费请求。
• 原生转录内容仍由原生框架管理。产品状态保存在明确指定的本地根目录中，Agent 输出必须视为未经信任的建议。

启用写入权限前，请阅读安全和 威胁模型。

项目

• 架构
• 适配器编写指南
• 贡献指南
• 更新日志
• MIT 许可证