Codex Subagent

codex-subagent-mcp

一个 MCP 服务，可让 Claude Code 将编码任务委托给在同一台机器上运行的 OpenAI Codex CLI，并为每项任务选择模型和推理深度。Claude 仍担任编排者，Codex 则成为它可以调用的子 Agent。

这是一个独立项目，与 OpenAI 或 Anthropic 无关，未获其认可或支持。

快速开始

需要安装 Node.js 22+ 和 Codex CLI，将其加入 PATH，并完成登录。

claude mcp add codex-subagent -- npx -y codex-subagent-mcp

如果缺少任何内容，请让 Claude 运行 codex_doctor。有关平台配置、Claude Desktop 和其他安装选项，请参阅 docs/INSTALL.md；启用写入功能前，请先阅读安全性。

你将获得

• 每项任务都可以从 Codex CLI 实时报告的目录中选择模型和推理强度。
• 默认只读，并设有任何工具调用都不能超越的沙箱上限。
• 每次委托完成后，都会检查模型、推理强度、沙箱和请求使用的目录是否与 Codex 记录的运行信息一致，并说明两者不一致或无法确认的情况。
• 可选的 output_schema 可返回符合你所定义架构的 JSON，供 Claude 直接使用结果。
• 取消、超时或关闭服务时，会停止 Codex 及其启动且服务仍能找到的命令；脱离该进程树的命令可能会继续运行。

以下是一次真实的只读委托，要求提供包名，记录于 2026-09-30：

codex-subagent-mcp
Commands run (1 total):
- [exit 0] /bin/zsh -lc "sed -n '1,80p' package.json"
model=gpt-5.6-luna | effort=low | sandbox=read-only | working_dir=/Users/you/project | applied=confirmed | duration=8s | tokens=in 35701 (cached 28160, uncached 7541) / out 88 (reasoning 9) | thread_id=01a0f419-9fd2-79e2-8248-91436f04e297

项目缘起

让单个模型处理所有事情会反复遇到三个问题，而委托可以逐一解决：

上下文窗口有限。 让 Claude 读取四十个文件来回答一个问题，会占用你真正开展工作所需的上下文。委托调查后，它返回答案，而不是四十个文件。

单个模型只有一套盲点。 第二种意见最有价值的情况，是它来自不同的模型系列——训练方式不同，失效模式也不同。向同一个模型提问两次，大多只会得到两次相同的答案。

并非每项任务都值得投入相同的推理预算。 重命名变量和诊断竞态条件不是同一种工作。在这里，它们是两个独立的调节项：模型决定原始能力，推理强度决定模型会思考多久。简单任务交给快速模型；难题则交给能力更强的模型，让它思考到足够为止。

该服务在你的机器上运行，并驱动你已安装的 Codex CLI；它本身不持有任何凭据。提示词会通过 Codex 发送给 OpenAI，与自行运行 codex 时完全相同。

有关与其他 Codex MCP 服务的版本对比，请参阅对比说明。

使用方法

编写范围明确的委托

反复执行命令并将输出不断加入后续请求的上下文，会让委托变得耗费资源。明确提出具体问题、可能涉及的文件、停止条件，以及答案必须包含的证据；遇到模糊问题时再选择更高的推理强度，而不要养成习惯性选择的做法。 编写委托 介绍了经测量的成本模型、按优先级排列的规则，以及使用真实工具参数编写的弱与强示例。背景信息放在 context 中，角色设定或额外规则放在 system_instructions 中；两者都会叠加在内置质量规范之上。详见工具参考。

向不同模型系列征求第二意见

这里的价值不在于再运行一次，而在于换一组盲点。

让 Codex 检查 src/server.ts 是否存在正确性问题，重点关注错误处理路径。使用较高的推理强度，并要求它逐条报告发现的问题及其重要性。

这样的委派审查发现了本仓库运行器中的 terminate() 缺陷：两条代码路径都可能启动定时器，但最终只会清除其中一个。

调查问题，不占用你的上下文

把四十个文件交给它，取回一份答复。Codex 会自行搜索并阅读所需内容；你的对话只会收到结论。

让 Codex 追踪推理强度如何从 MCP 工具调用一路传递到交给 Codex CLI 的参数，并且只报告调用链。

在后台运行耗时任务，同时继续处理其他工作

在后台启动一次 Codex 运行，为 src/jobs.ts 编写单元测试，然后继续帮我处理 API 层。

你会立即获得一个 job_id。需要时可随时查询状态，并在任务完成后读取结果。最多可同时运行八个任务；CODEX_SUBAGENT_MAX_BACKGROUND_JOBS 可以降低这个上限。在创建任务前取消的后台请求不会启动任何任务。

为一个棘手问题投入深度推理

提高整个对话的推理强度很费资源，而只提高一次委派任务的推理强度则不然。

这个间歇性测试失败已经难住我两次了。让 Codex 用最高推理强度找出根本原因，提供 test/runner.test.ts 和 CI 日志，并告诉它不要更改任何内容——我想先看诊断结果。

延续对话

让 Codex 详细说明它的第二项发现。

后续请求会复用 Codex 的上下文，因此成本只是原始请求的一小部分。每次后续请求中，服务端都会重新说明相同的模型、推理强度和目录，因为 Codex 恢复时不会保留这些信息。

确认要它编写代码时，就让它动手

让 Codex 应用前两条建议。允许它编辑文件，但要让它在 git 工作树中操作，以保持我的工作树干净。

use_worktree 会将本次运行的编辑操作发送到 ~/.codex/worktrees/；结果会列出 Codex 报告的文件更改及其所在位置，最多列出一千个不同条目，然后报告省略的条目数，并通过一行说明工作树及其创建时所基于的提交。Codex 会事先获知，未提交的更改、未跟踪文件以及已安装依赖等被忽略的文件都不包含在其中。服务端不会清理工作树：其中可能留有尚未应用的工作。此实验性功能仅对本次调用启用；你的 Codex 配置不会改变。如果 Codex 的会话文件无法确认工作树位置，后续请求会要求提供 working_dir，而不是在你的工作树中恢复。有关写入范围，请参阅安全。

无论沙盒如何设置，只要委派任务进行了写入，报告都会列出 Codex 记录的文件更改。这是 Codex 提供的记录，并非对磁盘内容进行差异比较所得：

Files changed (2):
- [edit] src/codex/runner.ts
- [add] test/runner.test.ts

安全

此服务会在你的机器上运行另一个程序，因此在启用写入前，花两分钟了解一下是值得的。

哪些措施可以保护你

委派任务默认只读。写入需要明确设置 sandbox: "workspace-write"，或由用户设置默认值。use_worktree 会将编辑操作发送到受管理的 git 工作树，而不是你的检出目录；沙盒和 add_dirs 会限制它可以写入的位置。除非你明确选择这种最高权限，否则无法进行无沙盒运行。

隔离由操作系统自身的沙盒实现：macOS 上使用 Seatbelt，Linux 和 WSL2 上使用 bubblewrap，Windows 上使用原生沙盒。表格中的数据是在 macOS 上测得的； SECURITY.md 记录了测量细节。此处尚未测量 Linux 和 Windows；OpenAI 的 Windows 文档指出，沙盒命令可能无法读取某些目录，因此这些平台上的读取限制可能更严格：

	read-only	workspace-write	danger-full-access
在工作目录内写入	否	是	是
在工作目录外（你的主目录）写入	否	否	是
网络访问	否	否	是
读取工作目录外的内容	是	是	是

服务每次运行时都会选择沙盒模式；Codex 自身的 sandbox_workspace_write 设置（例如网络访问或额外的可写根目录）不会被覆盖，在 workspace-write 模式下仍然适用。此表反映的是 Codex 的默认设置。

沙盒会限制 Codex 在 shell 中运行的命令，但不会限制 MCP 或插件工具：这些工具以独立进程运行，拥有你账户的全部权限，包括网络访问；在 read-only 模式下，声明自身为只读的工具无需审批即可运行（在 codex-cli 0.159.2 上测得；ADR 16）。因此，除非你在服务配置中明确允许，否则委派任务不会继承 Codex 设置中的任何 MCP 服务、插件或应用；每项委派结果都会附上一行说明此次运行获准执行的操作。

服务的调用路径中没有 shell：CLI 通过 argv 数组启动，提示词写入其标准输入，不会插入命令字符串。提示词中的 shell 元字符不会产生作用。

哪些措施无法保护你

读取不受限制。 在所有模式下，Codex 都能读取你的用户账户可以访问的任何内容——包括你的 SSH 密钥和云凭据。这一点已在 macOS 上测得，在所有平台上都应按此假设。沙盒会阻止网络访问，因此它无法将这些内容发送到任何地方；但运行报告会返回给你，而这本身就是一个传递渠道。

提示词是不可信输入，Codex 会据此采取行动。 你没有撰写的内容——例如问题正文、网页、日志或他人仓库中的文件——都可能包含指令。在 workspace-write 模式下，这些指令可以让 Codex 修改你的仓库；即使在只读模式下，也可以让 Codex 读取敏感内容并将其放入回答中。沙盒限制了 Codex 可以在哪里写入，但不会判断它应该写什么，也不会判断它为何会收到这项要求。这就是提示词注入，也是此处最值得关注的风险。

结果未经清理。 返回的内容来自刚刚读取过你文件的模型。请将其视为数据，而不是指令；应检查委派任务实际执行了什么，而不要想当然地认为它完成了你要求的操作。

降低风险

• 保留内置默认设置。只读模式可用于调查、审查和诊断，这些占大多数委派任务。
• 如果你完全不需要写入，可将上限设为：CODEX_SUBAGENT_MAX_SANDBOX=read-only。任何对话都无法突破上限。请在仓库之外注册（Claude Code 的默认 local 作用域、--scope user 或 Claude Desktop 的配置），不要放在项目的 .mcp.json 中，以免启用了写入权限的委派修改它。请参阅配置。
• 启用写入时，请添加 use_worktree，以便更改先落到一个你可以检查的位置，再影响你的分支。
• 仅在任务需要时，才允许委派使用 MCP 服务、插件或应用，并按名称指定。获准使用的项目会在沙箱之外运行；启用 auto_approve 后，其工具完全无需审批。
• 如果你打算根据回答采取行动，不要用不可信内容拼接委派提示词。
• 如果这项威胁对你来说非常重要，请在无法访问你机密信息的账户或容器中运行 Codex。这样可以从根本上解决问题，而不是仅仅限制它。

SECURITY.md 包含完整的威胁模型、deny_read 策略可以带来的额外保护，以及漏洞报告方式。

配置

所有配置均为可选项，通过 MCP 服务的环境变量设置：

变量	可选值	默认值	作用
CODEX_SUBAGENT_DEFAULT_MODEL	list_codex_models 中的标识符	如果 CODEX_SUBAGENT_ALLOWED_MODELS 只有一个条目，则使用该条目；否则，不指定模型的调用会被拒绝并收到建议	调用未指定模型时使用的模型。
CODEX_SUBAGENT_DEFAULT_EFFORT	none、minimal、low、medium、high、xhigh、max、ultra	模型的默认值	调用未指定努力程度时使用的努力程度。
CODEX_SUBAGENT_ALLOWED_MODELS	以逗号分隔的 list_codex_models 中的标识符	不限	其他模型均会被拒绝；只有一个条目时，该条目将作为默认模型。空条目（如 a,,b 或末尾的逗号）会导致配置错误。
CODEX_SUBAGENT_DEFAULT_SANDBOX	read-only、workspace-write、danger-full-access	read-only	调用未指定沙箱时使用的沙箱；不得超过上限。
CODEX_SUBAGENT_MAX_SANDBOX	read-only、workspace-write、danger-full-access	workspace-write	超出上限的调用会被拒绝；danger-full-access 需要明确启用。
CODEX_SUBAGENT_MAX_EFFORT	none、minimal、low、medium、high、xhigh、max、ultra	不限	更高的努力程度会被降至受支持的级别；如果没有合适级别，则会被拒绝。
CODEX_SUBAGENT_MAX_DELEGATIONS_PER_HOUR	1 到 9007199254740991 之间的十进制整数	不限	限制每个服务进程在滚动小时内启动的委派及后续进程数；探测不计入。
CODEX_SUBAGENT_MAX_BACKGROUND_JOBS	1 到 8 之间的十进制整数	8	降低正在运行的后台任务数上限；阻塞调用不受此限制。
CODEX_SUBAGENT_MCP_SERVERS	none、all 或以逗号分隔的服务名称	none	委派保留的 Codex 配置中的 MCP 服务。递归保护机制会为每次委派关闭此服务。如果使用 all 时 MCP 列表获取失败，或此服务自身条目名称中含有点号或 =，结果会说明未应用保护机制。
CODEX_SUBAGENT_PLUGINS	none、all 或以逗号分隔的插件 ID（name@marketplace）	none	委派保留的已安装 Codex 插件，以及这些插件提供的 MCP 服务。
CODEX_SUBAGENT_APPS	on、off	off	委派是否保留 Codex 应用（连接外部服务的连接器）。
CODEX_SUBAGENT_USAGE_LOG	on、off	off	追加记录已启动委派的本地使用次数；使用 codex_usage 读取。不会记录提示词、代码或路径。标签由调用方提供文本。
CODEX_BIN	可执行文件名称或路径；在 Windows 上必须是可直接执行的文件，而非 .cmd 或 .bat 脚本	PATH 中的 codex	覆盖 CLI 解析方式；请参阅安装。
模型仅支持部分推理强度；不支持的推理强度会调整为最接近的受支持值，
并附上说明。完整语义请参见 docs/TOOLS.md#configuration，
沙盒边界请参见 安全性。

每个 CODEX_SUBAGENT_* 值都会经过去除首尾空白处理，且区分大小写；空值表示未设置；与上限或允许列表冲突的值属于配置错误。 两个数值边界仅接受 ASCII 数字，允许前导零。无效值会导致委派请求被拒绝，并由 codex_doctor 列出。只有你能提高这些限制。每小时窗口保存在内存中，重启后重置，且独立于使用日志。每次启动的运行都会计入 60 分钟，包括失败、超时和取消的运行。 待处理的调用会在任何探测之前预留名额；如果没有启动运行，则会释放名额。拒绝请求时，会给出最早计入的进程的 UTC 到期时间和剩余分钟数；如果尚未启动任何进程，则会提示调用方等待已获准调用的结果。启动前，codex_doctor 会报告两个边界、当前窗口中已启动的进程，以及仍在启动前占用名额的调用。

Claude 决定何时委派；每次运行都会将提示词发送给 OpenAI，并消耗你的 Codex 用量，适用于服务器可用的任何对话。docs/CONTROL.md 介绍客户端权限提示、服务器上限、版本范围，以及你自己的 CLAUDE.md 升级规则。这些规则由你掌控；有关策略划分，请参见 ADR 12 和 ADR 14。

连接时，服务器指令会说明该注册项的沙盒上限和默认值、配置的模型和推理强度默认值，以及委派可以保留的继承工具类型。因此，编排器可以在加载工具描述之前，区分具有不同策略的注册项。配置错误的注册项会说明其委派工具拒绝请求，并指向 codex_doctor，而不会公布回退值。

选择模型

使用 list_codex_models 获取已安装 CLI 的实时目录。模型和推理强度相互独立：模型决定原始能力；推理强度决定其思考时长。ultra 还会自动委派子任务。

服务器不会替你选择。 任务所用模型取决于你的预算，以及错误答案的代价。如果调用或配置中没有指定模型，服务器会拒绝请求，并建议由你决定。

如果没有已配置或隐含的默认值，codex_delegate 描述会提示 Claude 先调用 codex_recommend，公布建议的模型和推理强度，然后明确指定两者进行委派。如果设置了 CODEX_SUBAGENT_DEFAULT_MODEL，或 CODEX_SUBAGENT_ALLOWED_MODELS 中恰好只包含一个模型，则会改为提示 Claude 省略 model，以应用默认值。配置错误时仍会提供推荐指引。这只是给模型的指引，而非强制执行。需要建议时，可以询问：“哪个 Codex 模型适合将此仓库的测试迁移到 vitest？”建议会遵循你的模型允许列表和推理强度上限；请参见推荐参考。

若要在之后的委派中跳过这一步，可使用 list_codex_models 设置一次默认模型：

claude mcp add codex-subagent -e CODEX_SUBAGENT_DEFAULT_MODEL=gpt-5.6-terra -- npx -y codex-subagent-mcp

工具

工具	功能
codex_doctor	检查 Codex CLI 安装情况并报告修复方法；设置 extended: true 可选择生成耗时较长、需要联网的 config.load 报告。
list_codex_models	列出可用模型及其推理力度级别。
codex_recommend	根据任务描述推荐模型和推理力度。
codex_delegate	执行任务，可阻塞运行或在后台运行，并可选择返回符合某个架构的 JSON。
codex_follow_up	使用其 thread_id 继续之前委派的任务，可选择是否使用架构。
codex_job_status	检查后台委派任务的状态。
codex_job_result	读取已完成的后台委派任务输出。
codex_job_cancel	停止正在运行的后台委派任务。
codex_usage	按模型、标签、结果或类型分组，汇总指定时间段内选择启用的本地使用日志。

完整参数参考：docs/TOOLS.md。

常见问题

这需要付费吗？ 它使用你现有的 Codex 配额，和你自己运行 codex 一样。此服务不会产生额外费用，也无法查看费用。更高的推理力度会消耗更多配额，而 ultra 还会委派子任务；codex_recommend 有助于避免在 low 难度的工作上使用 ultra。

为什么要驱动 CLI，而不是调用 OpenAI API？ 委派编码任务并非一次性补全，而是一个包含沙箱、审批模型、会话持久化和项目指令文件的 Agent 循环。这些都属于 Codex 客户端，而不在模型端点中。请参阅 ADR 1。

我需要 Claude Code，还是 Claude Desktop 也可以？ 两者都可以。Claude Code 只需一行命令即可安装；Claude Desktop 则需要手动添加配置项。

它说没有安装 Codex，但我在终端里可以运行 codex。 最可能的情况是你在 Windows 上通过全局 npm 安装，这会生成一个 codex.cmd 批处理脚本垫片，无法在没有命令 shell 的情况下启动。codex_doctor 会将此问题报告为 unsupported-shim，并提供两种修复方法。在 macOS 和 Linux 上，请检查 Node 版本管理器是否将 codex 移出了 PATH。

它能在 Windows 和 Linux 上运行吗？ 每次更改时，CI 都会在 Windows、macOS 和 Linux 上构建、测试并启动服务，还会检查各平台是否能正确解析 Codex CLI。真实委派目前只在 macOS 上验证过——CI 运行器没有安装 Codex，也没有相应凭据。欢迎提供 Windows 和 Linux 上的使用反馈。在 Windows 上，请使用 PowerShell 安装程序安装 Codex CLI，而不是 npm；在 Linux 上，请安装 bubblewrap，以支持 Codex 沙箱。请参阅安装说明。

文档

• docs/INSTALL.md — 安装、平台说明和故障排除。
• docs/CONTROL.md — 权限、上限以及 Claude 何时会进行委派。
• docs/DELEGATING.md — 如何界定委派任务的范围，包含实测费用和示例提示词。
• docs/TOOLS.md — 每个工具及其参数。
• docs/COMPARISON.md — 与其他 Codex MCP 服务的版本化对比。
• docs/adr/ — 逐项说明设计决策及其原因。
• docs/ROADMAP.md — 计划内容以及明确不在范围内的内容。
• 问题 — 当前实际开放的问题。
• docs/VERSIONING.md — 此项目中哪些情况算作破坏性变更。
• CHANGELOG.md — 各版本的变更内容，以及经过验证的 Codex CLI 版本。
• CONTRIBUTING.md — 环境设置和不可妥协的规则。

免责声明

非官方产品。 这是一个独立的社区项目，与 OpenAI 或 Anthropic 无关联，也未获得其认可、赞助或支持。“Codex”、“ChatGPT”和“OpenAI”是 OpenAI 的商标；“Claude”和“Claude Code”是 Anthropic 的商标。此处仅使用这些名称描述本软件可与之互操作的对象，属于指称性使用，并不主张对这些名称拥有任何权利。两家公司均不对本软件负责；如遇到问题，请在此处反馈，而非联系它们。

不提供担保。 如 LICENSE 所述，本软件按“原样”提供，不附带任何形式的担保。使用风险由你自行承担。

启用写入功能前，请阅读 安全；委派操作会消耗你自己的 Codex 用量。

许可证

MIT。请参阅 LICENSE。