组队 · 配置并调度多个 agentTeam Up · Configure and Orchestrate Multiple Agents.
多 Agent 不是把同一句话复制给一群模型,而是让主线程守住目标和决策,把探索、实现、测试与复核交给边界清楚的专门线程。本章从 [agents]、内置 default / worker / explorer 和两级自定义 agent 文件开始,走完手动指派、/agent、Ultra 主动委派、AGENTS.md / skill 触发四条路径,最后用一套可跑配置算清并发、写冲突与 token 账。Multi-agent work is not copying one prompt to a crowd of models. The main thread protects goals and decisions while bounded specialists explore, implement, test, and review. This chapter starts with [agents], the built-in default / worker / explorer roles, and personal or project agent files; follows direct delegation, /agent, Ultra, and AGENTS.md / skill triggers; then closes with a runnable configuration and an honest account of concurrency, write conflicts, and token cost.
多 Agent 不是把同一句需求复制四遍,等四个答案互相投票。它是一套分工:主线程保留目标、约束与最终决策,把能独立完成的探索、测试、实现或复核交给边界清楚的子线程;子线程交回证据摘要,主线程再决定下一步。当前 Codex 默认具备这套能力,但配置、调用路径和成本纪律决定它究竟是生产力,还是一台并行烧 token 的机器。Multi-agent work is not copying one request four times and letting four answers vote. It is division of labor: the main thread keeps the goal, constraints, and final decisions; bounded child threads take independent exploration, tests, implementation, or review; children return evidence summaries; and the main thread decides what happens next. Current Codex releases enable this workflow by default, but configuration, invocation, and cost discipline determine whether it becomes leverage or merely a machine that burns tokens in parallel.
— I
先认人:default、worker、explorerMeet the Team: default, worker, explorer.
Codex 自带三员。default 是通用 fallback,没有更贴切角色时接活;worker 偏执行,适合实现和修复;explorer 偏只读探索,适合追调用链、清点文件、找测试入口。2注 2Note 2OpenAI · Subagents / Custom agents —— 内置角色是 default、worker、explorer。个人自定义 agent 放 ~/.codex/agents/,项目级放 .codex/agents/;每个 TOML 必填 name、description、developer_instructions,也可覆写 model、model_reasoning_effort、sandbox_mode、mcp_servers 与 skills.config。同名自定义 agent 覆盖内置角色。截至 2026-08-05。OpenAI · Subagents / Custom agents — built-in roles are default, worker, and explorer. Personal custom agents live under ~/.codex/agents/ and project agents under .codex/agents/; every TOML file requires name, description, and developer_instructions, and may override model, model_reasoning_effort, sandbox_mode, mcp_servers, and skills.config. A custom agent with a built-in name wins. As of 2026-08-05.不要把它们当三种人格皮肤 —— 角色名是在告诉 orchestrator「这块活的形状」。要查清再动手,先 explorer;方案已定、写入范围清楚,再 worker;任务混合或不值得定制,才交 default。Codex ships with three roles. default is the general fallback when no sharper role fits; worker is execution-focused for implementation and fixes; explorer is read-heavy for tracing call paths, inventorying files, and locating test entry points.2注 2Note 2OpenAI · Subagents / Custom agents —— 内置角色是 default、worker、explorer。个人自定义 agent 放 ~/.codex/agents/,项目级放 .codex/agents/;每个 TOML 必填 name、description、developer_instructions,也可覆写 model、model_reasoning_effort、sandbox_mode、mcp_servers 与 skills.config。同名自定义 agent 覆盖内置角色。截至 2026-08-05。OpenAI · Subagents / Custom agents — built-in roles are default, worker, and explorer. Personal custom agents live under ~/.codex/agents/ and project agents under .codex/agents/; every TOML file requires name, description, and developer_instructions, and may override model, model_reasoning_effort, sandbox_mode, mcp_servers, and skills.config. A custom agent with a built-in name wins. As of 2026-08-05. These are not three personality skins — the role name tells the orchestrator what shape of work it is assigning. If you must understand before editing, start with explorer; when the plan and write scope are settled, use worker; when the task is mixed or not worth specializing, use default.什么时候自定义?不是每个项目都该先造一支军队。只有当一类工作反复出现,而且需要不同的模型、权限、工具或固定判断标准,才值得写 agent 文件。比如安全 reviewer 永远只读、总要高推理;文档核验员只接官方 docs MCP;迁移 worker 能写工作区,但禁止碰数据库。窄而专的 agent 好调度、好验收,也更不容易顺手做掉邻居的活。2注 2Note 2OpenAI · Subagents / Custom agents —— 内置角色是 default、worker、explorer。个人自定义 agent 放 ~/.codex/agents/,项目级放 .codex/agents/;每个 TOML 必填 name、description、developer_instructions,也可覆写 model、model_reasoning_effort、sandbox_mode、mcp_servers 与 skills.config。同名自定义 agent 覆盖内置角色。截至 2026-08-05。OpenAI · Subagents / Custom agents — built-in roles are default, worker, and explorer. Personal custom agents live under ~/.codex/agents/ and project agents under .codex/agents/; every TOML file requires name, description, and developer_instructions, and may override model, model_reasoning_effort, sandbox_mode, mcp_servers, and skills.config. A custom agent with a built-in name wins. As of 2026-08-05.When should you customize? Not every project should begin by building an army. Write an agent file only when a class of work repeats and needs a distinct model, permission set, tool surface, or fixed judgment standard. A security reviewer may always be read-only and high-reasoning; a docs verifier may get only an official docs MCP server; a migration worker may write the workspace but stay away from the database. Narrow, opinionated agents are easier to route and review, and less likely to casually absorb adjacent work.2注 2Note 2OpenAI · Subagents / Custom agents —— 内置角色是 default、worker、explorer。个人自定义 agent 放 ~/.codex/agents/,项目级放 .codex/agents/;每个 TOML 必填 name、description、developer_instructions,也可覆写 model、model_reasoning_effort、sandbox_mode、mcp_servers 与 skills.config。同名自定义 agent 覆盖内置角色。截至 2026-08-05。OpenAI · Subagents / Custom agents — built-in roles are default, worker, and explorer. Personal custom agents live under ~/.codex/agents/ and project agents under .codex/agents/; every TOML file requires name, description, and developer_instructions, and may override model, model_reasoning_effort, sandbox_mode, mcp_servers, and skills.config. A custom agent with a built-in name wins. As of 2026-08-05.
项目级多 Agent 默认 —— 信任仓库后加载Project-level multi-agent defaults — loaded after the repository is trusted
五个键别靠名字猜。enabled 是总开关,默认已经是 true。max_concurrent_threads_per_session 限制同时保持打开的子线程,不含主线程;不写则由 Codex 选默认,旧配置里的 max_threads 只是兼容 alias。两个 default_subagent_* 是没另行指定时的模型与推理力度。interrupt_message 决定打断子线程时是否把一条模型可见的中断消息记进上下文,也默认 true。3注 3Note 3OpenAI · Subagents / Global settings —— [agents] 支持 enabled、max_concurrent_threads_per_session、default_subagent_model、default_subagent_reasoning_effort、interrupt_message。enabled 与 interrupt_message 默认 true;并发上限不含主线程,max_threads 是旧 alias。显式 spawn 参数优先于 [agents] 默认;agent 文件显式 model / effort 又有自己的优先级。截至 2026-08-05。OpenAI · Subagents / Global settings — [agents] supports enabled, max_concurrent_threads_per_session, default_subagent_model, default_subagent_reasoning_effort, and interrupt_message. enabled and interrupt_message default to true; the concurrency cap excludes the primary thread, and max_threads is a legacy alias. Explicit spawn values beat [agents] defaults, while explicit model / effort values in an agent file have their documented precedence. As of 2026-08-05.Do not infer the five fields from their names alone. enabled is the master switch and already defaults to true. max_concurrent_threads_per_session caps concurrently open child threads, excluding the primary; when omitted, Codex chooses a default, and max_threads in older configs is only a compatibility alias. The two default_subagent_* fields provide model and reasoning defaults when nothing sharper is specified. interrupt_message controls whether interrupting a child records a model-visible interruption in its context, and also defaults to true.3注 3Note 3OpenAI · Subagents / Global settings —— [agents] 支持 enabled、max_concurrent_threads_per_session、default_subagent_model、default_subagent_reasoning_effort、interrupt_message。enabled 与 interrupt_message 默认 true;并发上限不含主线程,max_threads 是旧 alias。显式 spawn 参数优先于 [agents] 默认;agent 文件显式 model / effort 又有自己的优先级。截至 2026-08-05。OpenAI · Subagents / Global settings — [agents] supports enabled, max_concurrent_threads_per_session, default_subagent_model, default_subagent_reasoning_effort, and interrupt_message. enabled and interrupt_message default to true; the concurrency cap excludes the primary thread, and max_threads is a legacy alias. Explicit spawn values beat [agents] defaults, while explicit model / effort values in an agent file have their documented precedence. As of 2026-08-05.解析顺序也要记住。一次 spawn 明说的值先赢;否则看 [agents] 默认;再没有才继承父线程。自定义 agent 文件若显式写了 model 或 model_reasoning_effort,文件里的值生效。其他会话设置没写就继承父线程。还有一层实时边界:父线程这轮临时切过的权限模式会重新施加到孩子身上,不能靠 agent 文件绕过当前会话的安全选择。2注 2Note 2OpenAI · Subagents / Custom agents —— 内置角色是 default、worker、explorer。个人自定义 agent 放 ~/.codex/agents/,项目级放 .codex/agents/;每个 TOML 必填 name、description、developer_instructions,也可覆写 model、model_reasoning_effort、sandbox_mode、mcp_servers 与 skills.config。同名自定义 agent 覆盖内置角色。截至 2026-08-05。OpenAI · Subagents / Custom agents — built-in roles are default, worker, and explorer. Personal custom agents live under ~/.codex/agents/ and project agents under .codex/agents/; every TOML file requires name, description, and developer_instructions, and may override model, model_reasoning_effort, sandbox_mode, mcp_servers, and skills.config. A custom agent with a built-in name wins. As of 2026-08-05.Remember the resolution order too. An explicit value on a spawn wins; otherwise Codex uses the [agents] default; absent that, it inherits from the parent. If a custom agent file explicitly sets model or model_reasoning_effort, the file value applies. Other omitted session settings inherit from the parent. One live boundary sits above all of this: permission choices changed for the current parent turn are reapplied to children, so an agent file cannot bypass the active session's safety choice.2注 2Note 2OpenAI · Subagents / Custom agents —— 内置角色是 default、worker、explorer。个人自定义 agent 放 ~/.codex/agents/,项目级放 .codex/agents/;每个 TOML 必填 name、description、developer_instructions,也可覆写 model、model_reasoning_effort、sandbox_mode、mcp_servers 与 skills.config。同名自定义 agent 覆盖内置角色。截至 2026-08-05。OpenAI · Subagents / Custom agents — built-in roles are default, worker, and explorer. Personal custom agents live under ~/.codex/agents/ and project agents under .codex/agents/; every TOML file requires name, description, and developer_instructions, and may override model, model_reasoning_effort, sandbox_mode, mcp_servers, and skills.config. A custom agent with a built-in name wins. As of 2026-08-05.
— III
自定义 agent:一个 TOML,一份职责Custom Agents: One TOML, One Job.
个人 agent 放 ~/.codex/agents/,跟着你跨项目走;项目 agent 放仓库里的 .codex/agents/,随团队版本控制。每个 TOML 至少写 name、description、developer_instructions。文件名只是惯例,name 才是身份来源;如果它叫 explorer,就覆盖内置 explorer。2注 2Note 2OpenAI · Subagents / Custom agents —— 内置角色是 default、worker、explorer。个人自定义 agent 放 ~/.codex/agents/,项目级放 .codex/agents/;每个 TOML 必填 name、description、developer_instructions,也可覆写 model、model_reasoning_effort、sandbox_mode、mcp_servers 与 skills.config。同名自定义 agent 覆盖内置角色。截至 2026-08-05。OpenAI · Subagents / Custom agents — built-in roles are default, worker, and explorer. Personal custom agents live under ~/.codex/agents/ and project agents under .codex/agents/; every TOML file requires name, description, and developer_instructions, and may override model, model_reasoning_effort, sandbox_mode, mcp_servers, and skills.config. A custom agent with a built-in name wins. As of 2026-08-05.下面是一套能直接放进项目的三员配置:Personal agents live under ~/.codex/agents/ and follow you across projects; project agents live in the repository's .codex/agents/ and travel through version control. Every TOML file needs at least name, description, and developer_instructions. The filename is a convention; name is the identity source. Name one explorer and it shadows the built-in explorer.2注 2Note 2OpenAI · Subagents / Custom agents —— 内置角色是 default、worker、explorer。个人自定义 agent 放 ~/.codex/agents/,项目级放 .codex/agents/;每个 TOML 必填 name、description、developer_instructions,也可覆写 model、model_reasoning_effort、sandbox_mode、mcp_servers 与 skills.config。同名自定义 agent 覆盖内置角色。截至 2026-08-05。OpenAI · Subagents / Custom agents — built-in roles are default, worker, and explorer. Personal custom agents live under ~/.codex/agents/ and project agents under .codex/agents/; every TOML file requires name, description, and developer_instructions, and may override model, model_reasoning_effort, sandbox_mode, mcp_servers, and skills.config. A custom agent with a built-in name wins. As of 2026-08-05. Here is a three-person setup you can place directly in a project:
name = "repo_explorer"description = "只读扫描代码路径、测试入口和影响面;动手前用。"model = "gpt-5.6-terra"model_reasoning_effort = "medium"sandbox_mode = "read-only"developer_instructions = """只做证据驱动的探索。用文件和 symbol 定位结论。返回精炼摘要,不要粘原始日志,不要修改文件。"""
这三份也展示了每 agent 的配置面:model、model_reasoning_effort、sandbox_mode 和 mcp_servers 都能独立设。skills.config 也能放进单个 agent 文件,用于按 SKILL.md 的绝对路径启用或禁用一项已安装 skill;路径因机器而异,所以不把伪路径塞进这份可直接运行的仓库示例。没写的 MCP 与 skill 设置从父线程继承。2注 2Note 2OpenAI · Subagents / Custom agents —— 内置角色是 default、worker、explorer。个人自定义 agent 放 ~/.codex/agents/,项目级放 .codex/agents/;每个 TOML 必填 name、description、developer_instructions,也可覆写 model、model_reasoning_effort、sandbox_mode、mcp_servers 与 skills.config。同名自定义 agent 覆盖内置角色。截至 2026-08-05。OpenAI · Subagents / Custom agents — built-in roles are default, worker, and explorer. Personal custom agents live under ~/.codex/agents/ and project agents under .codex/agents/; every TOML file requires name, description, and developer_instructions, and may override model, model_reasoning_effort, sandbox_mode, mcp_servers, and skills.config. A custom agent with a built-in name wins. As of 2026-08-05.The three files also expose the per-agent surface: model, model_reasoning_effort, sandbox_mode, and mcp_servers can all differ. skills.config may also live in one agent file to enable or disable an installed skill by its absolute SKILL.md path; because that path is machine-specific, this runnable repository example does not pretend a placeholder is executable. Omitted MCP and skill settings inherit from the parent.2注 2Note 2OpenAI · Subagents / Custom agents —— 内置角色是 default、worker、explorer。个人自定义 agent 放 ~/.codex/agents/,项目级放 .codex/agents/;每个 TOML 必填 name、description、developer_instructions,也可覆写 model、model_reasoning_effort、sandbox_mode、mcp_servers 与 skills.config。同名自定义 agent 覆盖内置角色。截至 2026-08-05。OpenAI · Subagents / Custom agents — built-in roles are default, worker, and explorer. Personal custom agents live under ~/.codex/agents/ and project agents under .codex/agents/; every TOML file requires name, description, and developer_instructions, and may override model, model_reasoning_effort, sandbox_mode, mcp_servers, and skills.config. A custom agent with a built-in name wins. As of 2026-08-05.
只让这个 agent 覆写某项已安装 skill 的启用状态Override one installed skill's enabled state for this agent only
— IV
四条调用路径,别混成一条Four Invocation Paths, Not One.
手动指派Direct assignment
在 prompt 里点名角色、拆分方式、等待条件和要回的摘要。这是 Codex 本地与 Work 在大多数 intelligence level 上最确定的入口。Name the roles, split, wait condition, and requested summary in the prompt. This is the most deterministic entrance in local Codex and at most Work intelligence levels.
/agent/agent
CLI 里查看、切换 active / done 子线程。它是线程管理入口,不是一句 spawn 命令;先要求委派,再用它检查。Inspect and switch among active / done child threads in the CLI. It manages threads; it is not itself a spawn command. Ask for delegation first, then inspect.
Ultra 主动委派Ultra proactive delegation
在 eligible account 与受支持模型上,Work 的 Ultra 可判断并行确有收益时主动派 agent;其他档仍应明确要求。On eligible accounts and supported models, Ultra in Work may delegate proactively when parallel work materially helps; at other levels, ask explicitly.
AGENTS.md / skill 触发AGENTS.md / skill trigger
项目规矩或被触发的 skill 可以明确要求使用 subagents;它适合把稳定流程固化,不适合藏一次性的临时决定。Project guidance or a triggered skill can explicitly require subagents. Use this to codify a durable workflow, not to hide one-off decisions.
提示词PromptCodex · Multi-Agent
请用多 agent 完成这项任务。
目标:<要交付什么>
探索:派 <数量> 个 repo_explorer,分别检查 <互不依赖的范围>;只读,返回文件定位与风险摘要。
实现:等所有探索完成,由主线程合并方案;只派一个 implementation_worker 修改 <允许范围>。
验收:实现后派 reviewer 对照 <测试 / 安全 / 兼容标准> 独立复核。
边界:<不能改 / 不能访问 / 需要审批的动作>
返回:等所有 agent 完成,只给结论、证据、未决风险和最终 diff 摘要,不要倾倒原始日志。Use multiple agents for this task.
Goal: <deliverable>
Explore: spawn <count> repo_explorer agents for <independent scopes>; read-only, returning file locations and risk summaries.
Implement: wait for all exploration, have the main thread consolidate the plan, then assign exactly one implementation_worker to <allowed scope>.
Review: after implementation, spawn reviewer to check <test / security / compatibility criteria> independently.
Boundaries: <must not change / access / actions requiring approval>
Return: wait for every agent, then provide only conclusions, evidence, unresolved risks, and a final diff summary — no raw log dump.
请用多 agent 修复设置页保存后偶发回滚的问题。
目标:找到根因并提交最小修复,不改变 API schema。
探索:派两个 repo_explorer;一个追设置页状态与请求链,一个查相关测试和最近改动;都只读,返回文件定位与可复现条件。
实现:等两份摘要后由主线程定方案,只派一个 implementation_worker 改设置页与直接相关测试。
验收:实现后派 reviewer 检查竞态、错误处理、回归覆盖,并核对官方框架 API。
边界:不改数据库、不碰无关格式、不启动破坏性命令。
返回:等全部完成,给根因、改动、测试证据、review finding 与剩余风险。Use multiple agents to fix the settings page occasionally reverting after save.
Goal: find the root cause and ship the smallest fix without changing the API schema.
Explore: spawn two repo_explorer agents; one traces page state and the request chain, the other checks relevant tests and recent changes; both stay read-only and return file locations plus reproduction conditions.
Implement: after both summaries, let the main thread choose a plan and assign one implementation_worker to the settings page and directly related tests.
Review: after implementation, spawn reviewer to check races, error handling, regression coverage, and the official framework API.
Boundaries: no database changes, unrelated formatting, or destructive commands.
Return: wait for all work, then give root cause, changes, test evidence, review findings, and remaining risk.
— V
并行有收益,也有账Parallelism Has Leverage — and a Bill.
最稳的起点是读密集型并行:探索不同子系统、跑互不依赖的测试、清点迁移影响面、分析日志、核对文档。它们很少争同一个文件,产物又能压成摘要。官方也明确建议从这里开始。4注 4Note 4OpenAI · Subagents / Why subagent workflows help —— 官方建议从探索、测试、triage、总结等读密集型工作开始;子 agent 应回摘要而不是原始中间输出。多个 agent 同时写代码更容易冲突并增加协调开销。截至 2026-08-05。OpenAI · Subagents / Why subagent workflows help — the docs recommend starting with read-heavy exploration, tests, triage, and summarization; child agents should return summaries instead of raw intermediate output. Several agents editing at once are more likely to conflict and add coordination overhead. As of 2026-08-05.写密集型要反过来保守:多个 worker 同时改同一工作区,省下的等待很可能换成冲突、覆盖和重新协调。默认用「多路读、单路写、独立复核」;真要多路写,先给每路独立 worktree 或 cloud task。The safest starting point is read-heavy parallelism: explore different subsystems, run independent tests, inventory migration impact, analyze logs, or verify documentation. They rarely fight over one file and their output compresses naturally into summaries. The official guidance explicitly starts here.4注 4Note 4OpenAI · Subagents / Why subagent workflows help —— 官方建议从探索、测试、triage、总结等读密集型工作开始;子 agent 应回摘要而不是原始中间输出。多个 agent 同时写代码更容易冲突并增加协调开销。截至 2026-08-05。OpenAI · Subagents / Why subagent workflows help — the docs recommend starting with read-heavy exploration, tests, triage, and summarization; child agents should return summaries instead of raw intermediate output. Several agents editing at once are more likely to conflict and add coordination overhead. As of 2026-08-05. Be conservative in the opposite direction with write-heavy work: several workers editing one tree can exchange saved waiting time for conflicts, overwrites, and re-coordination. Default to many readers, one writer, one independent reviewer; if you truly need several writers, give each an isolated worktree or cloud task.
任务形状Shape of work
默认选择Default choice
为什么Why
一件复杂活,多路调查One complex job, several investigations
subagentsSubagents
共享目标,摘要回主线程Shared goal, summaries return to the main thread
几件独立改动,都要碰文件Several independent changes that write files
离机、长跑、要 PR 收回Off-machine, long-running, returned as PRs
多个 cloud tasksSeveral cloud tasks
隔离容器与远程生命周期Isolated containers and remote lifecycle
一条短而串行的小改One short serial change
单 agentOne agent
协调成本大于并行收益Coordination costs more than parallelism saves
动手 · 跑一次有边界的三段接力:Hands-on · run one bounded three-stage relay:
01
并行读Read in parallel
选一项跨两个子系统的问题,派两个 repo_explorer,明确只读范围和摘要格式。用 /agent 打开其中一条线程,确认它在查证而不是抢先改。Choose a problem crossing two subsystems, spawn two repo_explorer agents, and specify read-only scope plus summary format. Open one thread with /agent and confirm it is gathering evidence rather than editing early.
02
串行写Write serially
等两份结果齐全,由主线程消除矛盾并定方案,只让一个 implementation_worker 落地。写入变多时不要再加 worker,改用 worktree 隔离。Wait for both results, let the main thread resolve contradictions and choose a plan, then allow one implementation_worker to land it. When writes fan out, don't add more workers to one tree; isolate with worktrees.
03
独立验Review independently
让 reviewer 只看目标、diff 与测试证据,不要把 worker 的自我评价当结论。主线程最后合并 finding,决定接受、返工或留下待核项。Give reviewer only the goal, diff, and test evidence; do not treat the worker's self-assessment as the verdict. The main thread consolidates findings and decides to accept, rework, or leave a bounded open item.
主线程做决定,
子线程交证据.
The main thread decides;
child threads return evidence.
Aklman Library
— 讨论Discussion
讨论Discussion.
评论区初始化中…Initializing comments…
01 / 01
没有匹配结果No matches.
换个关键词，或按 Esc 回到页面Try another keyword, or press Esc to return
