文档信息

一、背景与目标

在使用 Codex 处理项目任务时，希望把“探索代码”“执行改动”“代码审查”等职责拆分给不同子代理，但又不希望不同子代理使用不一致的模型，导致输出风格和推理质量波动。

因此，这次配置的核心目标有两个：

• 所有子代理统一使用 gpt-5.4
• 仅通过 model_reasoning_effort 区分不同子代理的工作强度

二、本次配置结论

本次配置最终分成了两个层级：

• 全局配置：/Users/xiaoye/.codex
• 项目配置：当前项目根目录下的 .codex

实际执行顺序是：

1. 先为当前项目新增项目级 .codex 配置
2. 再将同一套子代理方案同步到全局配置

这样处理的原因是：

• 先局部验证：先在当前项目里确认配置结构和角色划分是否合理
• 再推广全局：方案确认可用后，再同步到所有项目
• 保留项目级扩展能力：后续某个项目如果要特殊 agent，仍然可以单独覆盖

最终新增了以下项目级文件：

.codex/
├── config.toml
└── agents/
    ├── default.toml
    ├── explorer.toml
    ├── worker.toml
    └── reviewer.toml

同时，全局目录也补充了对应文件：

/Users/xiaoye/.codex/
├── config.toml
└── agents/
    ├── default.toml
    ├── explorer.toml
    ├── worker.toml
    └── reviewer.toml

三、修改步骤整理

3.1 第一步：确认项目内是否已有 .codex 配置

先检查当前项目根目录下是否已经存在 .codex 目录，避免直接覆盖已有配置。

检查结果：

• 项目根目录原本没有 .codex 目录
• 当前环境中只存在全局配置文件 /Users/xiaoye/.codex/config.toml

这一步的目的很重要：

• 如果项目内已经存在 .codex 配置，应该先阅读原配置，再决定是合并还是覆盖
• 如果项目内不存在 .codex 配置，则可以直接创建项目级配置

3.2 第二步：确认全局配置现状

在创建项目级配置前，先查看全局配置，避免和当前使用方式冲突。

全局配置中的关键项如下：

model = "gpt-5.4"
model_reasoning_effort = "xhigh"

[features]
multi_agent = true

从这个结果可以得到两个结论：

• 当前环境已经启用了多代理能力
• 全局默认模型本身就是 gpt-5.4

但是，这并不等于子代理已经按项目需要被细分配置，因为：

• 全局配置只描述默认行为
• 子代理是否有专门职责，还要看项目级 .codex/agents/*.toml

3.3 第三步：确定配置策略

这次采用的是“全局统一基础配置 + 项目级可继续覆盖”的方式。

具体策略如下：

这里覆盖了三个常见内置角色：

• default
• explorer
• worker

另外额外补充了一个项目自定义角色：

• reviewer

3.4 第四步：编写 .codex/config.toml 中的 agents 配置

项目级总配置和全局总配置都只保留子代理运行限制，不重复声明顶层模型参数。

配置内容如下：

[agents]
max_threads = 6
max_depth = 1

这段配置目前已经同时存在于：

• 项目级 .codex/config.toml
• 全局 /Users/xiaoye/.codex/config.toml

这样配置的含义是：

• max_threads = 6
  • 最多允许并行 6 个子代理任务
• max_depth = 1
  • 当前项目先限制为单层委派，避免出现子代理继续递归创建子代理导致上下文失控

这是一种偏稳妥的起步方案，适合大多数文档类、前端类和中等规模代码修改任务。

3.5 第五步：为不同子代理定义职责和强度

虽然所有子代理都固定使用 gpt-5.4，但不同角色的目标不同，所以推理强度并不完全相同。

default 子代理

用途：

• 常规分析
• 中等复杂度实现
• 没有明确分类时的通用任务承接

配置：

name = "default"
model = "gpt-5.4"
model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"

选择理由：

• medium 足够覆盖大多数日常任务
• 允许写入工作区，便于直接做实现类修改

explorer 子代理

用途：

• 阅读代码
• 定位入口
• 收集调用链证据
• 梳理状态流

配置：

name = "explorer"
model = "gpt-5.4"
model_reasoning_effort = "low"
sandbox_mode = "read-only"

选择理由：

• explorer 主要是“读”和“找”，不是“改”
• low 足以支持代码检索、结构梳理和结论归纳
• 设置为 read-only 更符合职责边界

worker 子代理

用途：

• 执行定点实现
• 修复问题
• 补充局部验证

配置：

name = "worker"
model = "gpt-5.4"
model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"

选择理由：

• worker 通常承担落地代码修改任务
• medium 在实现效率和稳定性之间更平衡

reviewer 子代理

用途：

• 审查正确性
• 识别行为回归
• 发现安全问题
• 提示测试缺口

配置：

name = "reviewer"
model = "gpt-5.4"
model_reasoning_effort = "high"
sandbox_mode = "read-only"

选择理由：

• reviewer 的任务更偏“判断”和“质疑”，不是“执行”
• high 更适合做回归风险识别和逻辑严谨性审查
• read-only 可以避免审查角色和执行角色混淆

3.6 第六步：补充每个子代理的 developer_instructions

除了模型与强度，本次还给每个子代理写了专门的行为约束，避免不同角色做重复工作。

这些约束的核心作用是：

• 让 explorer 专注探索，不直接改代码
• 让 worker 专注落地，不顺手做无关重构
• 让 reviewer 优先关注真实缺陷，而不是风格问题
• 让 default 承接通用任务时保持范围收敛

也就是说，这次配置不只是“换模型”，而是把职责边界一起固化到了配置文件里。

四、最终落地文件

4.1 .codex/config.toml 总配置

项目级文件路径：

.codex/config.toml

全局文件路径：

/Users/xiaoye/.codex/config.toml

文件内容：

[agents]
max_threads = 6
max_depth = 1

4.2 子代理配置

文件路径：

.codex/agents/default.toml
.codex/agents/explorer.toml
.codex/agents/worker.toml
.codex/agents/reviewer.toml

全局也同步存在：

/Users/xiaoye/.codex/agents/default.toml
/Users/xiaoye/.codex/agents/explorer.toml
/Users/xiaoye/.codex/agents/worker.toml
/Users/xiaoye/.codex/agents/reviewer.toml

强度分配如下：

五、这样配置的实际价值

5.1 统一模型，降低输出风格漂移

所有子代理都固定为 gpt-5.4，这样做的直接好处是：

• 不同子代理的理解能力不会差异过大
• 回答风格、代码理解能力和推理质量更一致
• 降低“探索代理很弱、审查代理很强、执行代理很飘”的割裂感

5.2 通过强度区分角色，而不是通过模型分裂角色

这次不是给每个子代理配置不同模型，而是统一模型后，只调整：

• low
• medium
• high

这样更容易维护，因为：

• 后续调优只需要动强度，不需要频繁换模型
• 成本、效果和职责边界更容易观察

5.3 用权限模式强化职责边界

这次把“探索”和“审查”类角色都设为 read-only，本质上是在避免角色污染：

• explorer 不应该一边找问题一边偷偷改文件
• reviewer 不应该一边审查一边直接把代码改掉

这样更利于把结论、实现和审查三件事拆开。

六、后续使用建议

6.1 想让当前会话稳定识别新配置，建议重开会话

虽然项目内已经写好了 .codex 配置，但如果当前会话是在配置落地前启动的，最好重新打开当前 Codex 会话，让新配置从启动阶段就被读取。

6.2 在提示词里显式要求使用子代理

即使已经定义了 .codex/agents/*.toml，子代理也不是自动无条件触发的。

更稳妥的做法是，在任务提示里写清楚委派意图，例如：

开两个 subagents 并行：
1. explorer 先定位主题设置抽屉的状态流和入口文件
2. reviewer 审查这次改动的回归风险和测试缺口

或者：

先用 explorer 梳理 DefaultLayout 和 ThemeSettings 的通信链路，
再让 worker 做定点修改，
最后让 reviewer 做一次回归审查。

6.3 后续可继续细化

如果当前项目后面大量出现某一类固定任务，还可以继续拆出新的 agent，例如：

• doc-writer
• frontend-refactor
• test-auditor

但当前阶段先保留 default / explorer / worker / reviewer 四类，复杂度更可控。

七、总结

这次修改的本质，不只是“把子代理模型改成 gpt-5.4”，而是完成了四件事：

1. 为全局环境补齐了 .codex 子代理配置
2. 为当前项目建立了独立的 .codex 配置层
3. 用同名 agent 覆盖了常见内置角色
4. 在统一模型前提下，通过推理强度和权限模式区分了角色职责

最终结果是：

• 全局和当前项目都具备了更稳定的多代理协作基础
• 不同子代理的工作边界更清晰
• 后续继续扩展子代理体系时，也有了明确的配置模板