多代理、Subagents 与 Worktrees

这页补齐 Codex 的并行工作流入口。简单任务继续用单线程;当任务能拆成互不干扰的探索、审查、测试或实现片段时,再让 Codex 开 subagents 或 worktrees。

#能力选择

#Subagents

Codex 只有在你明确要求时才会开 subagents。提示词里要写清楚「分几个代理」「每个代理看什么」「是否等待全部完成」「最后返回什么格式」。

用并行 subagents 审查当前分支。
开 3 个代理:
1. 安全和权限风险
2. 测试缺口和回归风险
3. 可维护性和复杂度
等全部完成后,按 P0/P1/P2 汇总,每条带文件路径和理由。

适合 subagents 的任务:

不适合 subagents 的任务:

• 多个代理同时重写同一个核心文件。
• 需求还没定清楚,每个代理都可能朝不同方向发挥。
• 用户只需要一个小修复,并行开销比收益更高。

#Custom agents

Custom agents 是可复用的代理角色。个人级放在 ~/.codex/agents/,项目级放在 .codex/agents/。每个 TOML 文件至少需要:

name = "reviewer"
description = "Review code for correctness, security, regressions, and missing tests."
developer_instructions = """
Prioritize concrete bugs over style.
Return findings with file paths and severity.
Do not modify files.
"""
model_reasoning_effort = "high"
sandbox_mode = "read-only"

常用字段:

全局并发限制在 config.toml 的 [agents] 里配置:

[agents]
max_threads = 6
max_depth = 1
job_max_runtime_seconds = 1800

max_depth 默认保持 1 更稳,避免代理继续派生代理造成不可控的 fan-out。

#Worktrees

Codex App 的 worktree 基于 Git worktree。它会给后台线程创建独立 checkout,让 Codex 改代码时不干扰你的当前工作区。

使用前提:

• 项目必须是 Git 仓库。
• 当前分支、依赖和环境要能在新 checkout 里复现。
• 被 .gitignore 忽略但 worktree 必须用到的文件,需要用 .worktreeinclude 明确复制。

.worktreeinclude 示例:

.env.local
config/secrets.json

只列确实需要复制到 Codex 托管 worktree 的本地文件。不要把 tracked 文件写进去,也不要无脑复制整个密钥目录。

#Handoff

Handoff 用来在线程和代码之间切换前后台:

Git 不允许同一个分支同时被两个 worktree checkout。Codex 的 Handoff 会处理必要的 Git 操作,比手动 checkout 同一个分支更稳。

#并行安全策略

把并行工作流当成临时分支治理:

#Passion8 边界

本地 CLI、App 的 Local 线程、IDE 扩展使用本机 ~/.codex 配置,可以走 Passion8 的 https://passion8.cc/v1。

Cloud task、Slack、Linear、GitHub 托管 review 运行在 OpenAI 官方云端环境,不要假设它们继承本机 Passion8 Provider。需要云端能力时,按官方 ChatGPT / Codex workspace 的连接和权限配置处理。

#接着看

#官方参考

• Codex manual: Subagents
• Codex manual: Worktrees
• Codex manual: CLI features