Codex Subagent Pack

Codex Subagent Pack 是一套面向 Codex 的多 Agent 工作流配置包与安装工具。它把专业化 Helper Agent、任务边界、提示词、模型建议和路由规则封装成可重复安装的 Packs，支持 GPT-5.6 Sol、Terra、Luna、GPT-5.3-Codex-Spark、兼容模型和自定义 provider。

English README

它的目标不是简单增加更多 Agent，而是根据任务的复杂度、风险和工作类型，把边界明确的工作交给合适的 Helper Agent。Parent Codex 始终是当前激活的 coordinator，负责需求解释、架构与安全决策、最终代码审查和用户输出；Subagent 则聚焦于代码库探索、日志整理、局部实现、测试和评审等具体任务。

工具会安装 .codex/agents/*.toml、生成 AGENTS.md 路由策略，并在 .codex-subagent-pack.json 中记录实际使用的模型、reasoning effort、Pack 和托管文件状态。它只配置 Codex 项目文件，不修改 Codex runtime，也不会自动改变 Parent Codex 模型。

安装

需要 Node.js 20+，并已安装且可以正常运行 Codex CLI。请在要配置的项目根目录执行命令。

首次体验可以直接使用 npx，无需预先安装：

npx codex-subagent-pack@latest init

如果希望在项目中固定工具版本，建议安装为开发依赖：

npm install --save-dev codex-subagent-pack
npx codex-subagent-pack init

也可以选择全局安装：

npm install --global codex-subagent-pack
codex-subagent-pack init

除全局安装示例外，本文统一使用 npx codex-subagent-pack。它会优先调用当前项目安装的版本；没有本地版本时，npm 会临时获取 package。

快速开始

# 在项目根目录初始化 Standard Pack
npx codex-subagent-pack init --pack standard

# 检查生成的配置和 Agent 文件
npx codex-subagent-pack doctor

# 使用当前默认 Parent 模型启动 Codex
codex

standard 是默认 Pack，因此第一条命令也可以简写为：

npx codex-subagent-pack init

项目根目录选择

init 按以下顺序确定目标目录：显式传入的 --root、当前 Git worktree 边界内最近的已有 .codex-subagent-pack.json、Git worktree 根目录，最后是在 Git 仓库外使用当前目录。它不会再向上寻找父目录中的 package.json。

如果检测到的目标目录与当前目录不同，init 会同时显示两个路径并要求确认。只有确认目标无误时才应使用 --yes 跳过确认。若要明确安装到当前目录（包括 Git worktree 内的嵌套目录），请运行：

npx codex-subagent-pack init --root .

如果希望显式选择 Parent 模型，可以运行 codex -m gpt-5.6-sol。这只是启动 Codex 的示例；Pack 不要求 Parent 必须使用 Sol，也不会自动修改 Parent 模型。当前激活的 Codex 模型始终是 parent coordinator。

Standard Pack 的默认路由：

| Agent | 模型 | Effort | | --- | --- | --- | | Explorer | gpt-5.6-luna | low | | Log summarizer | gpt-5.6-luna | low | | Patch worker | gpt-5.6-terra | medium | | Test writer | gpt-5.6-terra | medium | | Reviewer | gpt-5.6-terra | high |

在 Codex 中使用

完成 init 后，像平常一样在项目根目录启动 Codex 并描述目标即可。生成的 AGENTS.md 会告诉 Parent 当前安装了哪些 Helper Agent，以及各自的职责、模型、effort 和 sandbox；当主动委派可用时，Parent 可以根据路由策略选择匹配的 Agent。

也可以在任务中显式指定 Agent，例如：

请先让 csp_codebase_explorer 定位认证流程涉及的文件和调用路径，再由 Parent 汇总结论。

请让 csp_reviewer 只读审查当前改动，重点检查回归风险和缺失测试，最终由 Parent 决定如何处理。

运行下面的命令可以查看针对当前已安装 Agent 生成的更多测试 Prompt：

npx codex-subagent-pack test-prompts --all

工作方式

1. Parent Codex 理解目标，并保留架构、安全和最终审批责任。
2. Pack 为不同角色提供预设的 Agent、模型和 reasoning effort。
3. Codex 根据生成的路由策略，将探索、实现、测试或评审等边界明确的子任务交给匹配的 Helper Agent。
4. Helper Agent 返回简洁、结构化的结果，由 Parent 复核并整合。
5. Manifest 记录最终解析结果和托管文件状态，doctor 负责诊断安装完整性与配置差异。

模型和 reasoning effort 按逐 Agent CLI 覆盖、全局 CLI 覆盖、Pack 配置、Template 推荐和 Model Catalog 默认值依次解析。这是安装时可复现的确定性路由，不是运行时自动切换 Parent 模型。

为什么使用

• 将搜索、日志和局部分析移出 Parent 上下文，减少无关信息占用。
• 用不同角色分离实现、测试和评审，降低同一 Agent 自写自审的偏差。
• 让高能力模型聚焦复杂或高价值工作，让轻量模型处理清晰、重复的任务。
• 将成熟的角色、提示词和模型路由封装成可复用 Pack，在不同项目中重复安装。
• 通过 Manifest、诊断和安全边界，让配置保持可追踪、可检查和可移除。

模型目录

npx codex-subagent-pack models list
npx codex-subagent-pack models info gpt-5.6-sol
npx codex-subagent-pack models recommend codebase/explorer

Catalog 中的模型 ID：

• 推荐：gpt-5.6-sol、gpt-5.6-terra、gpt-5.6-luna
• 专项预览：gpt-5.3-codex-spark
• 兼容：gpt-5.5、gpt-5.4、gpt-5.4-mini
• 高级：custom-provider

官方简写 gpt-5.6 会解析为 gpt-5.6-sol，Manifest 保存 canonical ID，保证配置可复现。sol、terra、luna、mini、spark 不是可独立使用的模型 ID。

GPT-5.6 是否可用取决于用户的 Codex 账号、套餐、workspace 和 rollout 状态。GPT-5.3-Codex-Spark 需要符合条件的权限，并且只支持 text-only 任务。

Packs

npx codex-subagent-pack init --pack testing
npx codex-subagent-pack init --pack review
npx codex-subagent-pack init --pack fast-coding
npx codex-subagent-pack init --pack spark-fast
npx codex-subagent-pack init --pack compatibility-gpt-5.4
npx codex-subagent-pack init --pack full

testing 使用 Luna、Terra、Sol 分层；review 使用 Terra 探索、Sol 评审；fast-coding 默认使用 Luna 和 Terra，不依赖 Spark；spark-fast 是显式的 text-only Spark 路径；compatibility-gpt-5.4 使用 GPT-5.4 Mini / GPT-5.4；full 对每个成熟 Template 只安装一个默认实例。

npx codex-subagent-pack packs list
npx codex-subagent-pack packs info standard
npx codex-subagent-pack packs info review

模型与 Effort 覆盖

覆盖整个 Pack：

npx codex-subagent-pack init \
  --pack standard \
  --model gpt-5.6-terra \
  --reasoning-effort medium

逐 Agent 覆盖：

npx codex-subagent-pack init \
  --pack standard \
  --model-map review/reviewer=gpt-5.6-sol \
  --effort-map review/reviewer=high

优先级从高到低：

1. --model-map / --effort-map
2. --model / --reasoning-effort
3. Pack 的逐 Agent 配置
4. Agent Template 推荐配置
5. Model Catalog 默认配置

未知模型默认拒绝。显式传入 --allow-unknown-model 后可以渲染，但 Manifest 会记录 isCatalogModel: false，工具不会声称其能力兼容性。

合法 reasoning effort：none、minimal、low、medium、high、xhigh、max、ultra。

Max 和 Ultra 是 reasoning mode，不是模型 ID。内置 Pack 不默认使用它们。Ultra 在支持的模型上可以主动委派更多工作，但 Helper Agent 默认仍保持 agents.max_depth = 1；Ultra 通常更适合 parent coordinator。本工具不会自动提高 agents.max_depth。

Agent Templates

Agent Template 只描述职责、风险、sandbox、能力要求、推荐模型、reasoning 策略和输出协议。完整模型元数据只存在于 Model Catalog。

npx codex-subagent-pack agents list
npx codex-subagent-pack agents info codebase/explorer
npx codex-subagent-pack agents add review/reviewer --model gpt-5.6-sol --reasoning-effort high
npx codex-subagent-pack templates validate registry/agents/codebase/explorer
npx codex-subagent-pack templates render registry/agents/codebase/explorer --model gpt-5.6-luna

生成的 Agent name 使用稳定 csp_ 前缀，例如 csp_codebase_explorer、csp_patch_worker、csp_reviewer。

社区 Template 不允许定义 provider/auth、脚本、MCP setup、danger-full-access、敏感信息收集或可写 custom-provider 行为。

Manifest 与 AGENTS.md

Manifest schema v3 记录：

• requested model 与 canonical model；
• family、tier、lifecycle、Catalog 成员状态；
• reasoning effort；
• 模型与 effort 的选择来源；
• sandbox、scope、Pack 和 managed-file hash。

Reader 支持 schema v2，并先迁移到内存中的 v3；下一次 init、packs add 或 agents add 会写回 v3，不会丢弃已有 Agent。

动态生成的 AGENTS.md 明确写入：

The active Codex model is the parent coordinator.

Installed Agent 表格来自 Manifest，包含 Role、Model、Effort、Sandbox。

测试与诊断

npx codex-subagent-pack doctor
npx codex-subagent-pack test-prompts --model gpt-5.6-luna
npx codex-subagent-pack test-prompts --model gpt-5.6-sol
npx codex-subagent-pack test-prompts --model gpt-5.3-codex-spark
npx codex-subagent-pack test-prompts --all

测试 Prompt 只根据当前已安装的项目 Agent 生成，不会要求 Codex spawn 不存在的名字。doctor 会比较 Manifest 与 Agent TOML 的 model/effort，但离线无法验证账号模型权限。

高级：Custom Provider

npx codex-subagent-pack provider add openrouter
npx codex-subagent-pack doctor --include-user
npx codex-subagent-pack test-prompts --model custom-provider

安全边界：

• 不询问或保存 API key 值。
• provider/auth 只写用户级 ~/.codex/config.toml。
• 不写项目级 provider/auth。
• 不修改全局 default model provider。
• doctor --include-user 只报告环境变量名及是否存在，不输出值。
• Custom-provider Agent 只读；workspace-write Template 会拒绝它。
• 优先支持 Responses-compatible provider。

custom-provider 是 Catalog 中的逻辑 target。实际 TOML 中的 model 和 model_provider 来自用户级 provider 配置。

init 生成的文件

项目级：

AGENTS.md
.codex/config.toml
.codex/agents/csp_*.toml
.agents/skills/codex-subagent-pack-router/SKILL.md
.codex-subagent-pack.json

可选用户级 provider：

~/.codex/config.toml
~/.codex/agents/csp_alt_explorer.toml
~/.codex/agents/csp_alt_log_summarizer.toml

Codex Subagent Pack 没有 postinstall，也不会把社区 Template 当作代码执行。

移除项目级托管文件和路由区块：

npx codex-subagent-pack remove

开发

npm install
npm run lint
npm test
npm run build
npm pack --dry-run

更多文档：文档导航、架构、模型目录、Registry、Template 编写、Provider 和安全模型。

License

MIT