Codex 子代理没启动？显式分工、实际派发与结果回收排查

你让 Codex 分几个代理处理任务，它只回复了一份分工；或者显示子任务已经启动，最后却缺了一项结果。先分别确认：是否提出了派发请求、是否真的创建子线程、是否有执行重叠、结果是否收齐并核对。 这四件事需要不同证据。

本文处理 Codex 子代理不主动用、只有主任务和 codex subagent not working。目标是定位卡住的阶段，完成一次可检查的小分工。若没有使用子代理，只是整个任务提前结束，先看任务没做完就停的状态与继续执行。

先按现象找下一步

你看到什么	下一步与应取得的证据
写了“分工方案”，没有子线程	第 1、2 步核触发要求和配置，再做第 3 步的小任务
说“已派发”，但找不到实际记录	第 4 步查派发工具结果或客户端子线程，先记为未确认
有两个子线程，只有一个在工作	查可用名额、状态与实际错误；两个线程存在不代表并行
子线程一直等待、报错或退出	第 4 步分审批、失败和未完成，不重复启动同一任务
最终回复缺一项，或两项内容一样	第 5 步逐项回收并比对原文件

1. 核对当前客户端与触发方式

适用条件： 还没看到子线程，或正在参考其他版本的教程。记录桌面应用、CLI 或 IDE 扩展的实际版本与执行主机。CLI 可在系统终端运行：

codex --version

当前官方子代理说明指出，本地 Codex 默认启用子代理工作流，但通常由用户明确请求，或适用的 AGENTS.md、技能指令要求委派时启动。“任务很复杂”“帮我审查代码”不等于已经发出了多代理请求；模型列出角色也不证明创建过线程。

使用位置	查看实际子代理的方式
桌面应用中的 Codex	从主聊天里的子代理活动打开对应线程，核对任务、进度与返回结果
交互式 CLI	在聊天输入框使用 /subagents，查看或切换当前会话的子线程
IDE 扩展	当前官方已说明子代理活动；后台代理面板可用时，在输入框上方展开状态或打开线程

/subagents 是聊天内命令，不是系统 shell 命令。当前命令参考还区分 /agents 的代理命令中心；不要把跨聊天列表当成本轮派发证明，也不要无条件照搬旧教程的 /agent。先查看本版本 / 菜单的实际可用项。

预期结果： 确认自己用的客户端、执行端和观察入口。缺少某个面板或命令时，记录版本、菜单与原始提示，继续核对配置和本轮是否实际派发；不能仅凭“没看到”就断定该端完全不支持。版本或启动来源不一致时看更新后版本没变排查。

ChatGPT Work 网页的托管子代理与本地 Codex 分开看。官方对 Work 的 Ultra 描述了主动委派能力，不能由此推断本地客户端在某个推理档位下一定会自行启动子代理。

2. 查生效配置、已有线程与父会话权限

适用条件： 明确请求过分工，仍没有派发记录，或者出现配置、名额、模型与权限错误。

先确定当前执行主机、启动目录、用户配置目录和实际使用的 profile。在支持的交互式 CLI 中，用 /debug-config 查配置层与受管来源，用 /status 查当前模型和权限；它们不是所有键的完整有效值导出器。路径或覆盖仍不明时，按config.toml 加载与优先级排查继续，不覆盖整份配置。

当前子代理配置需要关注：

• [agents] 下的 enabled 默认是 true；明确设为 false 会禁用多代理工具。不要因为文件里没写，就认定没有开启。
• max_concurrent_threads_per_session 限制同时开启的已派发线程，不包含主线程；未设置时由 Codex 选择默认值。已有开启的子线程可能占用名额，先核实际状态，不默认把上限调大。
• max_threads 是前述上限的旧别名。不要把旧文的固定默认数量或嵌套深度当作当前契约；同时出现新旧键时，先核当前版本的解析和错误，不猜哪个生效。
• 另设了子代理默认模型、推理档位或自定义代理时，核对当前账号是否可用，以及实际报错。先用现有可用模型和普通内置代理做小测试，避免同时引入角色、模型与配置变化。

自定义代理不是首次排查的必要条件。确实使用时，再核个人或项目的 .codex/agents/ 文件是否在正确执行端，TOML 是否有效，name、description、developer_instructions 是否齐全；按实际 name 指定角色。同名自定义代理可以覆盖内置代理，别只检查文件名。技能中的分工要求是否加载，另见Skills 显示与触发排查。

权限边界： 当前官方说明，自定义代理继承父会话的权限、provider 与 MCP；在自定义文件里写 sandbox_mode、approval_policy 或 mcp_servers，不能据此覆盖父设置。“只读分析”指令也不建立独立只读沙箱。需要只读限制时，应在父会话中核对适用权限，外部工具的读写授权仍分别检查。

预期结果： 知道有没有明确禁用、当前是否有可用名额、失败是否来自模型或审批。只改已确认错误的单项，重新从正常入口验证。组织要求限制功能时保留提示交管理员；不要用扩大权限、跳过审批或删除其他人的线程来制造“能启动”。

3. 用两个独立文件提出一次明确分工

适用条件： 需要验证本地派发和回收，且可以进行一次使用账号额度的小任务。使用仓库外的新目录、虚构内容和两个互不依赖的读取任务，不拿正在修改的前后端代码做首次测试。

你可以在新空目录手动创建两个文件。已有 Bash/zsh 的 macOS 或 Linux 环境也可执行以下命令；mktemp 创建新目录，不覆盖已有项目文件：

probe_dir="$(mktemp -d "${TMPDIR:-/tmp}/codex-subagents.XXXXXX")" &&
printf 'item=orchid\ncount=7\nnote=alpha-only\n' > "$probe_dir/alpha.txt" &&
printf 'item=cedar\ncount=13\nnote=beta-only\n' > "$probe_dir/beta.txt" &&
printf 'Test directory: %s\n' "$probe_dir"

预期结果： 得到一个新目录，其中两个文件各有三行。任何一步失败就先处理实际错误，不继续启动任务；不要把 Bash 引号用法直接当作 PowerShell 实测方法。Windows 可用编辑器在新目录创建同样内容，无需为这个例子安装新运行时。

把该目录作为本地测试项目或工作目录，先核对当前目录确实是刚创建的位置。独立目录只隔离样例文件，仍可能加载用户规则、工具和 hooks；已有全局业务流程时使用获准的测试环境，保留原配置。无需复制用户凭据到新目录，也不必更换 CODEX_HOME。

在新测试聊天发送下面的请求。它只要求两个子代理，各自读取一个文件；不要先把两份答案粘到聊天里：

请实际启动两个子代理，分别完成以下独立任务：
A：只读取当前测试目录的 alpha.txt，返回文件名、item、count、note，并指出读取证据。
B：只读取当前测试目录的 beta.txt，返回文件名、item、count、note，并指出读取证据。
不要让子代理继续派生代理，不修改或创建文件，不联网，不调用外部业务工具。
在当前允许的权限和可用名额内执行，不修改配置，不绕过审批。
请等待两项都返回后，在主线程按 A、B 分别汇总；失败或未完成的项必须单列。
如果无法启动，请报告实际失败阶段和工具错误，不要把分工计划说成已派发，也不要反复重试派发。

这段请求表达范围与完成条件，不保证模型必然照做，也不是安全沙箱。开始前记录时间和文件原件；测试后重新打开两个文件核对，不能仅凭模型说“没有修改”确认文件未变。需要严格确认字节是否变化时，对这两份非敏感文件保存前后 SHA256 再比较。

4. 分别检查实际派发、线程状态与执行重叠

适用条件： 请求已经发出。先观察这一轮，不立刻再发一条相同请求。

打开本轮子代理活动、线程或工具记录，逐项核对 A、B 的任务分配、开始与结束状态。客户端展示名称可能不同，不要求读者手动调用某个内部派发 API。

取得的证据	可以判断什么，以及下一步
只有“已启动两个代理”的文字	派发尚未确认；继续找实际记录，缺失就如实记未确认
派发工具成功返回，或能打开对应子线程	该项确实创建过；核对本轮任务与当前状态，不能据此判已完成
有子线程，但在等待审批或输入	看来源线程和具体请求；按原权限处理，不能把等待当结果
派发或子线程明确报错	保留错误和失败项；名额、模型、配置、权限分别按实际错误排查
A、B 都有结束记录	继续收集两条返回并验证；两个结束记录不证明并行或内容正确

交互式 CLI 中，审批可能来自当前未查看的子线程，官方说明审批界面会标来源，可打开对应线程查看。在非交互流程或无法提出新批准时，需要新审批的动作会失败并回传父流程；不要改成跳过审批来“修复子代理”。codex exec 的输出与终态另外参考非交互输出和异常退出排查。

判断并行要另取证。 两个线程同时存在，甚至“活动中”的时间重叠，都可能包含排队、等待模型或等工具。要报告本次有并行执行，应取得两个子线程中可定位的执行起止记录，确认执行片段确有重叠；这也不能证明两个推理请求在服务端同时计算。客户端没有足够细的时间记录，就写“实际子线程已确认，并行执行未确认”，不靠总耗时短或模型说“并行”推断。

没有子线程时，回第 1、2 步核明确请求、开关、可用名额、配置及工具错误。已有线程未完成时，先查看或询问该线程当前状态，只对已确认失败或未收齐的一项安排后续；不要整组重派，让多个任务读写同一处。

5. 按任务逐项收齐，并对照原文件

适用条件： 子代理已经返回，或主线程开始总结。建立一份与原请求对应的清单：

子任务	本例应核对的内容
A → alpha.txt	item 为 orchid，count 为 7，note 为 alpha-only
B → beta.txt	item 为 cedar，count 为 13，note 为 beta-only

对照时同时打开子线程返回与文件原件，检查是不是当前目录、当前轮次的文件，主线程是否漏项、串项或把一个结果重复填了两行。正确答案若已经出现在聊天或公开样例里，单靠答对不能证明真的读取过文件；仍要看子线程的实际读取证据。公开答案适合验证流程，不是模型盲测。

预期结果： A、B 各有可追溯的返回，内容与对应原件一致，主线程汇总没有遗漏；两个文件仍保持原样。缺一项就标未收齐：先查对应线程，区分仍在运行、等待审批、明确失败和已返回但汇总漏掉，再决定继续或仅重试该项。

如果两条返回齐全但某项读错，记为“回收齐全、内容验证失败”，核对应路径和读取记录，不能宣布全部成功。如果只有主线程自己读取并给出正确答案，记为“主线程完成了样例、子代理流程未通过”，不要用它补齐派发证据。

回到真实任务时，还要验证代码、测试或交付物。子代理全部返回不代表代码正确、测试完整，也不承诺比单代理更快或更省额度。需要多仓库修改时，按前后端两个仓库的逐库验收处理；子代理不自动等于独立 worktree，改动位置不明时看worktree 改动定位。

测试结束，先确认没有仍使用该目录的任务，再按本机正常文件管理方式清理自己创建的样例目录。保留必要的脱敏验证结果，不删除真实会话、用户配置或其他任务文件。

隔离验证结果与未实测范围

本文于 2026-10-23 重新读取官方子代理、CLI 命令、配置参考和配置诊断说明。在 macOS 的独立目录实际执行文中的 Bash/zsh 样例创建命令，核对两文件内容、新目录与前后哈希；空格与中文临时路径同样验证，不覆盖已有文件。TOML 配置片段与自定义代理必填字段使用本地解析器检查。

另用人工构造的记录检查判定边界：只有派发声称不能算真实线程；两项完整但顺序执行不能算并行；线程活动重叠但无执行片段不能算并行；执行片段重叠但缺返回不能算收齐；重复、串项、错误内容或未完成不能算全部通过。这些是对验证方法的隔离检查，不是 Codex 实际派发、真实子线程或并行执行实测。

本机帮助检查版本为 codex-cli 0.163.0-alpha.11.1，不代表功能最低版本。本次未调用真实模型或启动子代理，未逐端实测桌面、IDE 面板、Windows、WSL、SSH、云端以及真实审批；未修改用户现有 Codex 配置，也未安装第三方分工技能。当前命令与产品行为依据官方资料，读者仍需按实际版本复验。

完成标准： 分开记录派发、线程、并行、回收和内容核对的结果，未知项保留未知。求助时提供客户端与版本、执行位置、最小分工请求、失败阶段、各项状态、时间和脱敏错误；不要公开完整配置、真实会话、私有代码、原始工具日志或凭据。