Subagent MCP

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

当一个模型负责规划变更、实现变更并审查变更时，审查者会共享作者的上下文和盲点。它最终可能只是在确认自己的计划，而不是检验它。

Subagent MCP 让 Codex 保持为主代理和最终决策者，同时将有边界的任务委托给外部代理运行时。每个运行时都是一个模型与其原生执行环境配对，因此 Codex 可以从具有不同上下文和假设的独立模型获得实现或审查。

这扩展了 Codex 的有效子代理池，并且可以利用你已有的提供商配额。Subagent MCP 从不启用、购买、自动充值或静默选择使用额度或付费超额。

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

稳定版： 1.0.7 面向 Windows。MCP、包、localhost UI 以及 Claude Code 和 DeepSeek 原生执行环境集成均已就绪。

运行时状态

• Claude Code — 就绪。 使用原生 Claude Code 执行环境、提供商原生模型和推理设置、订阅 OAuth 身份，并在接受其输出之前提供实时无超额证据。

• DeepSeek Harness — 就绪。 使用其原生 ACP 传输和由执行环境发布的模型目录来处理有界任务。MCP 重启后恢复、精确的提供商配额证据、交互式输入和声明的 MCP 仍然是明确的能力差距。

目前不支持其他运行时。未来的运行时使用适配器，而不是在核心中编写特定于提供商的分支。

Related MCP server: AI Knowledge Center MCP

快速开始

1. 安装

如有需要，先安装 uv，然后注册精确的隔离版本并启动其后台 UI：

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

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

2. 配置运行时

在浏览器中打开 http://127.0.0.1:8765。如果后台 UI 已停止，请再次启动同一精确版本：

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

设置和只读活动 UI 保持在固定的回环端口上，不依赖于活动的 MCP 连接。

当前和最近的活动按外部代理列出。选择一行以检查其模型、原生执行环境、工作区、权限、写入集、当前阶段、生命周期、已用时间和脱敏后的终端结果。提示词、转录、隐藏思考和原始提供商事件永远不会显示。

3. 委托

用自然语言向 Codex 提问：

使用 Subagent MCP 让外部代理审查此变更，然后独立评估其发现。

Codex 选择要委托的内容，观察结果，并保留最终判断。生命周期响应默认保持简洁；完整的脱敏报告保留在本地产品状态中，之后可以通过哈希绑定引用读取或转发。

模型与回退顺序

每个原生执行环境发布自己的模型选择。UI 显示友好名称和有序的优先级堆栈；精确的提供商 ID 仍可用于高级路由。

当提供商明确报告配额或信用已耗尽（QUOTA_PAUSED）时，Subagent MCP 将该精确模型移到未来任务的底部。它不会重试失败的任务。模糊的失败、崩溃和超时不会重新排序模型，也不会触发另一次付费请求。

操作恢复上限为三个操作。只有本地状态工作或明确可重试的提供商前失败才可能被重试；已经失败的提供商任务永远不会自动再次发送。

DeepSeek 路由可以使用用户授权的现有订阅、无限优惠或已充值的余额。Subagent MCP 从不购买、充值或增加该余额。

并发写入者

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

省略 write_set 会为执行提供整个工作区，以保持向后兼容。每个适配器还会在其原生执行环境边界强制执行规范化路径。当前 DeepSeek Harness 原生会话接受一个可写根；多根任务由控制器分解为多个不相交的写入调用，而不是扩大范围。真正的单会话多根仍保留给未来宣传官方 ACP additionalDirectories 并在原生层面强制执行该功能的执行环境。这些租约协调 Subagent MCP 执行；它们不是针对无关本地进程的操作系统沙箱。

整体架构

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.6 升级到 1.0.7：

uvx --isolated --from subagent-harness-mcp==1.0.6 subagent-harness-mcp ui --stop
codex mcp remove subagent-mcp
codex mcp add subagent-mcp -- uvx --isolated --from subagent-harness-mcp==1.0.7 subagent-harness-mcp serve
uvx --isolated --from subagent-harness-mcp==1.0.7 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、订阅身份验证、凭据优先级和控制连接，然后在接受其输出之前要求来自同一响应的安全速率证据。

• 提供商刷新不发送模型提示。如果原生执行环境无法在响应之前暴露精确的速率证据，状态保持为未知，而不是编造配额结果或使用重置的时钟。

• 回退仅在明确配额耗尽后发生。不安全或模糊的证据永远不会触发另一次付费请求。

• 原生转录仍归原生执行环境所有。产品状态保留在明确的本地根中，代理输出必须被视为不可信的建议。

在启用写入访问之前，请阅读 安全 和 威胁模型。

项目

• 架构

• 适配器编写

• 贡献

• 变更日志

• MIT 许可证