Codex 的封装:GPT-6 Astra 版
用途: 为 Codex 配置可迁移的模型分工、执行规则与验收流程
首次发布: 2026-09-02;官方资料核对: 2026-09-05
子代理容量核对: 2026-09-08
0.154.0 全篇复核: 2026-09-14
历史部署: Codex CLI 0.152.1、Sol 主线程,见第 13 节
本次状态: 按 CLI 0.154.0 与当前文档全篇复核;本机沙箱从 danger-full-access 改为 workspace-write,根 effort 与本文一致为 high,并发规则改为独立子代理并行;Astra 方案仍需在目标设备完成加载和任务验收
我对 Codex 的封装,主要落在三处:用配置固定角色,用指令约束执行,用证据决定任务是否完成。GPT-6 Astra 发布后,这套分工可以把主线程交给 Astra,同时保留 Sol、Terra 和 Luna 的职责。
2026-09-05 的更新补齐几项执行边界:何时需要用户决策,技能冲突如何处理,模型配置如何生效,以及只读权限如何验证。模型升级需要连同这些行为约定一起检查。
2026-09-08 的更新只核对子代理线程容量相关文档和配置行为;其他模型资料仍沿用 2026-09-05 的核对范围,本次没有把全篇资料重新验收一遍。
2026-09-14 的更新按 CLI 0.154.0 和当天下载的官方文档把全篇重新核对了一遍,修正了工具名、并发规则、effort 档位、验证命令和本机配置记录,见第 13.4 节。
目标
1.1 模型分工
以下是本文的工程配置基线。角色分配和 effort 是待任务验证的选择,不是 OpenAI 规定的唯一组合,也没有经过本文的新旧模型成本对照实验。
| 职责 | 模型 | 推理强度 | 交付物 |
|---|---|---|---|
| 根代理:拆分、协调、整合与验收 | gpt-6-astra | high | 范围、决策和最终验收 |
| 生产代码与测试实现 | gpt-5.6-sol | xhigh | 限定范围的 diff 与验证证据 |
| 独立代码审查 | gpt-5.6-sol | high | 有反例与行号的 findings |
| 构建、测试、浏览器与运行时 QA | gpt-5.6-terra | high | 命令、结果与证据边界 |
| 搜索、定位、盘点与日志归纳 | gpt-5.6-luna | medium | 聚焦的问题答案 |
| 可选的困难窄分析 | gpt-5.6-luna | max | 有边界的只读分析 |
官方模型指南把 Astra 用于跨步骤、跨工具的复杂工作,Sol 用于需要深入判断的任务,Terra 和 Luna 分别覆盖日常工作与明确、可重复的任务。这支持分层调度的方向;是否值得升级某个角色,要用同一任务的正确性、返工、耗时与用量比较。模型选择依据
这套分工遵循以下执行约束:
- 每次新建子代理线程都显式指定
model和reasoning_effort。只给 model 不给 effort 时,子代理用该模型自己的默认档,而本机模型目录缓存里gpt-5.6-sol的默认是low,所以“两者都显式”是硬规则。复用现有线程会继承原模型和 effort;接口没有覆写字段时不要虚构参数。 - 本文把
max_concurrent_threads_per_session设为6,限制同时保持打开的子代理线程,不含根线程。相互独立的子代理并行到这个上限:并发只改变墙钟,不改变用量,用量由派出的子代理数量、模型和 effort 决定。只有依赖前一步结果或涉及同一文件的工作才串行。 - 优先复用模型、effort、角色和文件所有权都匹配的线程;同一文件只能由一个实现者写入,独立审查仍须保持独立。子代理没有工作树参数;需要对同一批文件并行写入时,那是另开一个会话(0.154.0 新增的
codex --worktree,featureworktrees仍是 experimental)的事,不是放松所有权规则。 - 子代理不能继续委派、扩大范围、暂存、提交、推送或发布。
- 根代理必须检查 diff、验证证据和未验证边界后才能验收。
1.2 GPT-6 带来的规则调整
官方 GPT-6 指南提示:Astra 可能更常澄清问题,更敏感地遵循技能和 AGENTS.md,委派少于预期,并对小改动做过量验证。GPT-6 Astra 指南
因此,本文新增三项执行约定:在授权范围内持续推进;因技能规则停下时指出具体来源;按改动风险完成必要验证,出现新证据才扩大检查。代码委派保留明确触发条件,小型文字任务由根代理完成。
GPT-6 Astra 的 API 模型 ID 是 gpt-6-astra。本机的模型目录缓存(~/.codex/models_cache.json,2026-09-14)为它列出 low、medium、high、xhigh、max、ultra 六档,默认 medium;subagents 文档把 ultra 列为可以直接设置的 model_reasoning_effort,不只是一种工作方式。不要沿用 none 或 minimal。配置参考页的类型说明仍只写到 xhigh,以目录缓存和 subagents 文档为准。Responses API 是否接受 ultra 本文未验证,API 侧的档位要单独核对。模型规格、Codex 推理档位
目标设备必须确认账号、登录方式和客户端支持所选模型。文档列出 Astra 不等于每个账号已获得访问权限;不可用时保留现有配置并报告阻塞,不自动替换成其他模型。可用性说明
官方依据
- Custom instructions with AGENTS.md
- Codex Subagents
- Codex Configuration Reference
- Codex Models
- GPT-6 Astra Model
- GPT-6 Astra Model Guidance
关键配置事实:
- 官方文档每一页都有 Markdown 版本:在完整路径后加
.md(例如.../docs/agent-configuration/subagents.md),适合复核时逐字比对。 - 全局配置位于
~/.codex/config.toml。 - 全局行为指令位于
~/.codex/AGENTS.md。 - 全局自定义 Agent 位于
~/.codex/agents/*.toml。 - 项目规则位于项目根目录的
AGENTS.md。 - 项目专属 Agent 可以放在项目根目录的
.codex/agents/*.toml。 - Codex 在每次新运行或新会话开始时重新构建指令链。
- 独立 Agent TOML 必须包含
name、description和developer_instructions。 - 不要把
developer_instructions错写成instructions。 max_concurrent_threads_per_session限制同时打开的子代理线程,不含根线程;它不等于某一时刻实际执行的子代理数量。- 多代理工具集是
spawn_agent、send_input、resume_agent、wait_agent、close_agent(features.multi_agent,稳定且默认开启)。文档只说上限计的是打开的线程,没有说completed会释放槽位,本机 2026-09-08 观察到已完成线程仍占槽位;不再需要的线程要用close_agent关闭,关闭后以一次成功的 spawn 作为容量释放的证据。
迁移时还必须区分三类优先级:
- 模型配置: 自定义 Agent 文件设置的
model、model_reasoning_effort优先。应用该文件前,先按显式派发值、[agents]默认值、父代理值解析;只指定了 model 而没有 effort 时,用该模型自己的默认档(gpt-5.6-sol是low)。只改派发参数可能仍运行 TOML 中固定的旧模型。Subagents - 运行权限: 父会话的实时 sandbox 和 approval 覆盖会重新应用到子代理。TOML 的
read-only是配置默认值;需要隔离的只读验收应从只读父会话启动,并核对实际权限。--ask-for-approval never仅关闭审批询问。权限继承 - 指令文件: 每层优先读取
AGENTS.override.md;项目还会沿根目录到工作目录逐层加载。更近目录的规则可能覆盖前文。默认 32 KiB 限额必须检查实际发现的指令链,不能只相加全局文件和项目根文件。AGENTS.md 发现规则
本文要求每次新建子代理线程显式填写派发参数、限制递归委派和保留单一验收者,属于工作流约定。复用线程时按现有代理的模型、effort、角色和所有权匹配任务;send_input(已完成线程用 resume_agent)没有覆写字段时沿用原配置。spawn_agent 的 fork 选项、follow-up 和 close_agent 的参数要以当前会话实际提供的 schema 为准,不能把某个客户端的工具接口当成所有 Codex 版本的通用 API。
Codex Home 路径
先检查是否设置了 CODEX_HOME。
Windows PowerShell
$env:CODEX_HOME如果没有输出,默认路径是:
C:\Users\<用户名>\.codex也可以使用:
[Environment]::GetFolderPath('UserProfile')macOS / Linux
printf '%s\n' "$CODEX_HOME"如果没有输出,默认路径是:
$HOME/.codex下文统一用 ~/.codex 表示实际 Codex Home。
最终文件结构
~/.codex/
├── config.toml
├── AGENTS.md
└── agents/
├── sol-implementer.toml
├── sol-reviewer.toml
├── terra-qa.toml
├── luna-recon.toml
└── luna-recon-max.toml不要把整份部署文档复制到 AGENTS.md。只合并第 6 节的三节规则,并检查实际加载的指令链大小。
全局 config.toml 增量配置
必须保留目标电脑已有的 ~/.codex/config.toml。不要整文件覆盖,不要打印其中的 API key、HTTP header、token、MCP secret 或完整敏感内容。
先记录本次相关键的旧值和是否原本存在,再定点更新根级设置:
model = "gpt-6-astra"
model_reasoning_effort = "high"
model_verbosity = "low"这三行必须处于 TOML 根级,不能追加在 [agents] 或其他 table 内。model_verbosity = "low" 与本机模型目录缓存(~/.codex/models_cache.json)里每个模型的默认 verbosity 相同;文档只说未设置时用模型预设的默认值,没有写出那个值。写出来是为了让迁移后的机器与本机一致,不是为了省输出。已有同名根键时更新原位。另行核对 profile、可信项目配置和客户端当前任务选择是否覆盖默认值;已有任务不会因这段示例自动切换模型。配置参考
如果不存在 [agents],加入:
[agents]
enabled = true
max_concurrent_threads_per_session = 6
default_subagent_model = "gpt-5.6-luna"
default_subagent_reasoning_effort = "medium"
interrupt_message = true如果已经存在 [agents],只合并或更新以下五个键,不得创建第二个 [agents] 表:
enabled
max_concurrent_threads_per_session
default_subagent_model
default_subagent_reasoning_effort
interrupt_message注意:
6与官方完整配置示例一致,但不是跨版本承诺的固定默认值,也不是官方给出的最佳并发数。配置参考只说明未设置时由 Codex 选择默认值。官方完整示例、配置参考- 本文选择
6,是为了保留不同固定角色的可复用线程和调度余量;它计的是打开的线程,本机观察到已完成但未用close_agent关闭的线程仍占槽位(13.3),所以它不能保证容量永不耗尽。独立的子代理可以并行到这个上限,并发不改变用量。 - 目标机器的
[agents]若已有旧键max_threads(max_concurrent_threads_per_session的遗留别名),记录后删除,避免同一上限写两遍。 - 默认 Luna 只为未固定模型的派发提供默认值;不能覆盖自定义 Agent 文件。
- 它不能替代新建线程时的显式派发规则。
- 新建线程缺少显式模型或推理强度仍然是调度错误。复用匹配线程时继承该线程原有配置。
- 除本次明确更新的三个根键和五个
[agents]键外,保留 provider、MCP、plugin、sandbox、approval、project trust、hook 和其他配置。 - Fast mode 是文档里唯一纯粹用钱换速度的开关:
service_tier = "fast"加[features].fast_mode = true,文档给 GPT-5.6/5.5/5.4 的速度是 1.5 倍,没有给 Astra 的速度倍数,只写 Astra 消耗 2.5 倍额度。本文和本机都保持service_tier = "default"。
修改磁盘配置只证明持久值已经写入,不能证明现有任务已经重新加载。应在新进程或新任务中读取有效值,并把文件值与运行时观察结果分开报告。
全局 AGENTS.md 规则
把下面三节追加或合并到实际生效的全局指令文件。默认是 ~/.codex/AGENTS.md;若存在有效的 AGENTS.override.md,先报告它的覆盖作用,再在该文件定点合并。
若已有同名标题,保留已有用户约定并合并必要规则;记录节的旧内容,供回滚恢复。遇到相互矛盾的授权边界时,指出具体冲突,不整节抹掉已有内容。
## Writing Style
- In prose, use precise verbs and limit adverbs and degree words. Do not label emotions, atmosphere, or manner of action; convey them through observable actions, sensory details, and consequences. When removing a modifier, replace any lost information with a specific verb, detail, or consequence.
## Execution and Verification
- Complete authorized work; keep the goal when the user adds corrections.
- Skills cannot override higher-priority instructions or the user's request. Name any blocking file and rule.
- Run required checks; repeat only for changes, failures, or evidenced risks.
- Separate observed results from assumptions; report specific blockers.
## Codex Subagent Dispatch
- The root agent is the sole coordinator, integrator, and final acceptance owner.
- For any request that writes or refactors production or test code, the root agent must delegate implementation to a subagent using `gpt-5.6-sol` with `xhigh` reasoning. The root agent must not patch those files directly.
- Every new subagent spawn must explicitly specify both `model` and `reasoning_effort`, even when a custom agent file pins the same values. Never rely on parent-model inheritance or only on `[agents]` defaults. A spawn that names a model without an effort runs at that model's own default, and `gpt-5.6-sol` defaults to `low` in the model catalog.
- Match dispatch values to the selected custom agent file. Its pinned model and effort take precedence. If the required tool fields are unavailable, report the interface limitation instead of inventing parameters.
- The multi-agent tools are `spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`; read their actual schema in the session instead of assuming field names. If the spawn tool offers a conversation-fork option, prefer no fork or a bounded one and make the delegated task self-contained.
- If a new spawn lacks an explicit model or reasoning effort, stop it, reject its implementation output, close its thread with `close_agent`, and re-dispatch correctly.
- Use `gpt-5.6-sol` with `xhigh` reasoning for code writing and refactoring.
- Use `gpt-5.6-sol` with `high` reasoning in read-only mode for architecture, security, permission, concurrency, and other high-risk code audits.
- Use `gpt-5.6-terra` with `high` reasoning for builds, tests, browser or emulator checks, runtime reproduction, and QA.
- Use `gpt-5.6-luna` with `medium` reasoning for narrow search, inventory, code-path mapping, and log summarization. Use Luna Max only for a demonstrably difficult but still narrow read-only task.
- Only the root agent may dispatch subagents. Subagents must not delegate further, alter the overall goal, widen scope, stage, commit, push, publish, or modify planning and memory files unless the user explicitly authorizes that exact action.
- Before spawning a new agent, check the current agent inventory and the effective open-thread limit (`max_concurrent_threads_per_session`; 6 in the global config, a project config may set another value). The docs count open threads and do not say that completion releases a slot; on this machine completed agents were observed to keep their slots (2026-09-08), so close threads with `close_agent` instead of assuming completion freed capacity.
- Run independent subagents concurrently up to the open-thread limit. Concurrency is a wall-clock lever, not a cost lever: usage scales with how many agents you spawn and at which model and effort, not with how many run at the same time. Serialize only work that depends on an earlier result or touches the same files. Retain suitable agents for reuse across implementation, review, QA, and reconnaissance.
- Prefer `send_input`, or `resume_agent` for a completed thread, for related work on an existing agent whose model, reasoning effort, role, and file ownership match the task. Preserve reviewer independence and read-only boundaries; a follow-up does not change the agent's configured model or effort.
- After accepting results, close threads you no longer need with `close_agent` so their slots return. On `agent thread limit reached`, refresh agent state, close finished threads or reuse a suitable agent, and confirm capacity with a successful spawn before assuming it was released. Do not repeatedly retry, downgrade the model, or bypass mandatory delegation.
- If closing and reuse still leave no capacity, report the blocker. When the user authorizes a limit adjustment, update `max_concurrent_threads_per_session` and verify its effective value in a fresh process that is not attached to a running background app-server. A file edit alone does not prove that an existing task has reloaded the limit; do not silently increase it or claim recovery without runtime evidence.
- Only one write-capable implementation agent may own a file at a time. Parallel work is limited to read-only reconnaissance or clearly disjoint file ownership declared by the root agent. Spawned agents have no worktree or working-directory field; parallel writes to the same files belong to a separate session started with `codex --worktree`, not to a spawn, and never justify relaxing ownership.
- A subagent completion is an evidence handoff, not final acceptance. The root agent must inspect the diff, review verification evidence, resolve blocking findings, and decide acceptance.
- Do not silently downgrade a task to a cheaper model. If the required model is unavailable, serialize, narrow the task without weakening its quality boundary, or report the blocker. Reclassify the task explicitly before selecting another model.
- Every delegated task must define its objective, in-scope and out-of-scope work, owned files or modules, acceptance criteria, required verification, forbidden actions, evidence format, and stopping conditions.
- Prefer the smallest evidence-backed implementation. Do not add speculative abstraction, compatibility layers, fallbacks, retries, or validation to hide uncertainty.
- Preserve user-owned dirty files. Implementers do not stage or commit. After acceptance, the root agent stages exact task paths and commits only when authorized by the user and when the change forms one coherent theme.自定义 Agent TOML
以下五个文件保留原有角色分工。文件存在时先比较:属于本文旧版的,只更新本次涉及的规则;若同名文件承担其他职责,报告冲突,保留原文件。部署前在本机保留待改内容以便恢复,不把配置备份上传到仓库。
luna_recon_max 是可选角色。API 与客户端对档位的支持要分别核对;目标客户端未验证 max 时,报告该角色未部署,不把它改成另一个档位冒充成功。其余四个角色可以单独验收。
7.1 sol-implementer.toml
路径:~/.codex/agents/sol-implementer.toml
name = "sol_implementer"
description = "Implementation agent for tightly scoped production and test code changes."
model = "gpt-5.6-sol"
model_reasoning_effort = "xhigh"
sandbox_mode = "workspace-write"
developer_instructions = """
Implement only the explicitly assigned scope.
Follow all applicable AGENTS.md instructions.
Do not change the task goal, expand scope, add speculative features, or perform unrelated refactoring.
Do not add compatibility layers, fallbacks, abstractions, or defensive guards without direct evidence that they are required.
Do not delegate to another agent.
Do not stage, commit, push, publish, or modify planning and memory files.
Preserve user-owned and unrelated working-tree changes.
Use test-driven development when the repository requires it.
Run targeted verification appropriate to the change.
Return an evidence packet containing changed files, decisions, exact commands, results, failures, and remaining unknowns.
"""7.2 sol-reviewer.toml
路径:~/.codex/agents/sol-reviewer.toml
name = "sol_reviewer"
description = "Read-only independent reviewer for architecture, correctness, security, concurrency, and regression risks."
model = "gpt-5.6-sol"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
developer_instructions = """
Review only the assigned scope and remain read-only.
Follow all applicable AGENTS.md instructions.
Do not edit files, stage, commit, push, publish, or delegate.
Prioritize correctness, security, data integrity, concurrency, behavior regressions, and missing test coverage.
Do not report style-only findings unless they conceal a real defect.
For each finding, provide severity, file and line evidence, impact, reproduction or counterexample, and the smallest defensible remediation.
Distinguish confirmed findings from risks and unverified gaps.
End with an APPROVE or BLOCK recommendation; the root agent retains final acceptance authority.
"""7.3 terra-qa.toml
路径:~/.codex/agents/terra-qa.toml
name = "terra_qa"
description = "Independent QA agent for builds, tests, runtime reproduction, browser checks, and emulator evidence."
model = "gpt-5.6-terra"
model_reasoning_effort = "high"
sandbox_mode = "workspace-write"
developer_instructions = """
Validate only the assigned behavior.
Follow all applicable AGENTS.md instructions.
Do not modify production or test source files.
Workspace-write permission exists only because builds and tests may create generated outputs.
Do not delegate, stage, commit, push, or publish.
Record exact commands, exit codes, observed behavior, screenshots or logs when relevant, and the limits of the evidence.
Separate local engineering evidence from physical-device, production, external-service, or release proof.
Return PASS, FAIL, or BLOCKED for each acceptance criterion; do not claim the whole task is complete.
"""7.4 luna-recon.toml
路径:~/.codex/agents/luna-recon.toml
name = "luna_recon"
description = "Read-only agent for narrow searches, code-path mapping, inventory, and evidence collection."
model = "gpt-5.6-luna"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
Stay within the assigned question and remain read-only.
Follow all applicable AGENTS.md instructions.
Prefer targeted search and focused file reads over broad repository scans.
Do not repeat exploration already supplied by the root agent.
Do not propose speculative fixes unless explicitly asked.
Do not edit, delegate, stage, commit, push, or publish.
Return concise findings with file and symbol evidence, the smallest counterexample found, and remaining unknowns.
"""7.5 luna-recon-max.toml
路径:~/.codex/agents/luna-recon-max.toml
name = "luna_recon_max"
description = "Read-only Luna agent for a narrow, self-contained analysis that demonstrably needs deeper reasoning."
model = "gpt-5.6-luna"
model_reasoning_effort = "max"
sandbox_mode = "read-only"
developer_instructions = """
Accept only a narrow task with explicit inputs, outputs, evidence requirements, and stopping conditions.
Remain read-only and follow all applicable AGENTS.md instructions.
Do not implement code, make architecture decisions, approve security-sensitive changes, delegate, stage, commit, push, or publish.
Stop and return BLOCKED if the task requires broader context or production-code judgment.
Return only evidence-backed conclusions and remaining unknowns.
"""另一台电脑的一键部署 Prompt
把以下完整 Prompt 发送给目标电脑上的 Codex。最好从一个普通项目目录启动 Codex,并使用有权写入 Codex Home 的本地权限模式。
请在这台电脑上部署一套由 GPT-6 Astra 协调的全局 Codex subagent 配置。只修改当前用户的 Codex Home 配置,不修改任何项目文件,不暂存、不提交、不推送。
目标行为:
1. 根代理使用 gpt-6-astra / high,是唯一协调者、整合者和最终验收者。
2. 所有生产代码和测试代码实现必须委派给 gpt-5.6-sol / xhigh。
3. 架构、安全、权限、并发和高风险代码审查使用 gpt-5.6-sol / high,只读。
4. 构建、测试、浏览器、模拟器、运行时复现和 QA 使用 gpt-5.6-terra / high。
5. 窄范围搜索、盘点、代码路径定位和日志归纳使用 gpt-5.6-luna / medium,只读。
6. 提供一个可选的 gpt-5.6-luna / max 只读角色,只用于边界清晰但确实困难的窄分析;目标客户端不支持时报告未部署,其余四个角色单独验收。
7. 每次新建子代理线程都必须显式指定 model 和 reasoning_effort,禁止依赖父代理继承。
8. 把 max_concurrent_threads_per_session 设为 6;它限制同时打开的子代理线程,不含根线程。6 与官方示例一致,但不是固定默认值或官方最佳并发数。文档没有说完成会释放槽位,本机观察到不释放;不再需要的线程用 close_agent 关闭。
9. 相互独立的子代理并行到这个上限;并发只改变墙钟,不改变用量。只有依赖前一步结果或涉及同一文件的工作才串行。优先通过 send_input(已完成线程用 resume_agent)复用模型、effort、角色和所有权匹配的线程,复用时继承原配置;接口没有覆写字段时不要虚构参数。
10. 子代理不得继续委派、扩大范围、暂存、提交、推送、发布或修改规划和 memory 文件。
11. 子代理完成只代表证据交接;根代理检查 diff、验证证据和阻塞 finding 后才能验收。
12. 写作使用精确动词,限制副词和程度词;用可观察的动作、感官细节和后果传达情绪、气氛与动作方式。删除修饰语时,用具体动词、细节或后果补回丢失的信息。
13. 持续完成已授权工作;收到纠正时保留原目标并更新约束。必要验证通过后停止重复检查,除非出现新改动、失败或具体风险。
执行边界:
- 先使用 OpenAI Docs 或当前安装的官方 Codex 文档核对自定义 Agent、AGENTS.md、config.toml 和 reasoning effort 格式。
- 核对目标账号、登录方式和客户端是否提供 gpt-6-astra 及必需的子代理模型;API 文档列出模型不等于当前 Codex 账号可用。
- 运行 codex --version,记录当前版本。不要擅自升级 Codex。
- 检查 CODEX_HOME;若未设置,使用当前平台默认的 ~/.codex。
- 先盘点目标文件是否存在以及相关 section/key,不要打印完整 config.toml。
- 不输出 API key、HTTP header、token、MCP secret 或含凭据的环境变量;CODEX_HOME 仅用于确认配置路径。
- 保留所有现有配置和 AGENTS.md 内容,只做定点合并。
- 记录每个相关键、章节和 Agent 文件部署前是否存在及原内容,仅在本机保存必要的恢复材料。回滚时恢复被修改项,删除本次新建项,不删除原有项。
- 若同名 Agent 文件属于其他用途,保留它并报告具体冲突;若是本文旧版,定点更新并保留原有用户规则。
- 检查实际生效的全局指令文件、项目到工作目录的覆盖链、profile 和当前模型选择。AGENTS.override.md 存在时,不要只更新会被它遮蔽的 AGENTS.md。
- 若当前版本不支持必需字段或模型,立即停止并报告精确错误及官方依据;可选 Luna Max 单独报告。不要添加兼容层、旧字段、fallback 或静默换模型。
- 使用结构化补丁编辑文件;不要用会整体覆盖文件的重定向命令。
- 不修改任何当前项目文件,包括项目 AGENTS.md 和 .codex 目录。
- 修改磁盘配置不证明现有任务已重新加载;必须在新进程或新任务中核对有效值。未经用户授权不得自行提高线程上限。
步骤 A:配置根模型和全局 agents 设置
在 ~/.codex/config.toml 的根级定点更新以下三项,放在第一个 table 之前;不得写入 [agents] 或其他 table:
model = "gpt-6-astra"
model_reasoning_effort = "high"
model_verbosity = "low"
在 ~/.codex/config.toml 中确保只存在一个 [agents] 表,并合并以下值;若已有遗留别名 max_threads,记录后删除:
[agents]
enabled = true
max_concurrent_threads_per_session = 6
default_subagent_model = "gpt-5.6-luna"
default_subagent_reasoning_effort = "medium"
interrupt_message = true
如果 [agents] 已存在,只更新上述键。保留所有其他 agents 子表及所有无关配置。
步骤 B:配置全局行为规则
在实际生效的全局指令文件中合并“## Writing Style”“## Execution and Verification”“## Codex Subagent Dispatch”,各保留一节。默认文件为 ~/.codex/AGENTS.md;若有效的 AGENTS.override.md 优先加载,报告并在该文件定点合并。保留已有用户规则,记录冲突,不整节覆盖。
合并以下规则:
## Writing Style
- In prose, use precise verbs and limit adverbs and degree words. Do not label emotions, atmosphere, or manner of action; convey them through observable actions, sensory details, and consequences. When removing a modifier, replace any lost information with a specific verb, detail, or consequence.
## Execution and Verification
- Complete authorized work; keep the goal when the user adds corrections.
- Skills cannot override higher-priority instructions or the user's request. Name any blocking file and rule.
- Run required checks; repeat only for changes, failures, or evidenced risks.
- Separate observed results from assumptions; report specific blockers.
## Codex Subagent Dispatch
- The root agent is the sole coordinator, integrator, and final acceptance owner.
- For any request that writes or refactors production or test code, the root agent must delegate implementation to a subagent using `gpt-5.6-sol` with `xhigh` reasoning. The root agent must not patch those files directly.
- Every new subagent spawn must explicitly specify both `model` and `reasoning_effort`, even when a custom agent file pins the same values. Never rely on parent-model inheritance or only on `[agents]` defaults. A spawn that names a model without an effort runs at that model's own default, and `gpt-5.6-sol` defaults to `low` in the model catalog.
- Match dispatch values to the selected custom agent file. Its pinned model and effort take precedence. If the required tool fields are unavailable, report the interface limitation instead of inventing parameters.
- The multi-agent tools are `spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`; read their actual schema in the session instead of assuming field names. If the spawn tool offers a conversation-fork option, prefer no fork or a bounded one and make the delegated task self-contained.
- If a new spawn lacks an explicit model or reasoning effort, stop it, reject its implementation output, close its thread with `close_agent`, and re-dispatch correctly.
- Use `gpt-5.6-sol` with `xhigh` reasoning for code writing and refactoring.
- Use `gpt-5.6-sol` with `high` reasoning in read-only mode for architecture, security, permission, concurrency, and other high-risk code audits.
- Use `gpt-5.6-terra` with `high` reasoning for builds, tests, browser or emulator checks, runtime reproduction, and QA.
- Use `gpt-5.6-luna` with `medium` reasoning for narrow search, inventory, code-path mapping, and log summarization. Use Luna Max only for a demonstrably difficult but still narrow read-only task.
- Only the root agent may dispatch subagents. Subagents must not delegate further, alter the overall goal, widen scope, stage, commit, push, publish, or modify planning and memory files unless the user explicitly authorizes that exact action.
- Before spawning a new agent, check the current agent inventory and the effective open-thread limit (`max_concurrent_threads_per_session`; 6 in the global config, a project config may set another value). The docs count open threads and do not say that completion releases a slot; on this machine completed agents were observed to keep their slots (2026-09-08), so close threads with `close_agent` instead of assuming completion freed capacity.
- Run independent subagents concurrently up to the open-thread limit. Concurrency is a wall-clock lever, not a cost lever: usage scales with how many agents you spawn and at which model and effort, not with how many run at the same time. Serialize only work that depends on an earlier result or touches the same files. Retain suitable agents for reuse across implementation, review, QA, and reconnaissance.
- Prefer `send_input`, or `resume_agent` for a completed thread, for related work on an existing agent whose model, reasoning effort, role, and file ownership match the task. Preserve reviewer independence and read-only boundaries; a follow-up does not change the agent's configured model or effort.
- After accepting results, close threads you no longer need with `close_agent` so their slots return. On `agent thread limit reached`, refresh agent state, close finished threads or reuse a suitable agent, and confirm capacity with a successful spawn before assuming it was released. Do not repeatedly retry, downgrade the model, or bypass mandatory delegation.
- If closing and reuse still leave no capacity, report the blocker. When the user authorizes a limit adjustment, update `max_concurrent_threads_per_session` and verify its effective value in a fresh process that is not attached to a running background app-server. A file edit alone does not prove that an existing task has reloaded the limit; do not silently increase it or claim recovery without runtime evidence.
- Only one write-capable implementation agent may own a file at a time. Parallel work is limited to read-only reconnaissance or clearly disjoint file ownership declared by the root agent. Spawned agents have no worktree or working-directory field; parallel writes to the same files belong to a separate session started with `codex --worktree`, not to a spawn, and never justify relaxing ownership.
- A subagent completion is an evidence handoff, not final acceptance. The root agent must inspect the diff, review verification evidence, resolve blocking findings, and decide acceptance.
- Do not silently downgrade a task to a cheaper model. If the required model is unavailable, serialize, narrow the task without weakening its quality boundary, or report the blocker. Reclassify the task explicitly before selecting another model.
- Every delegated task must define its objective, in-scope and out-of-scope work, owned files or modules, acceptance criteria, required verification, forbidden actions, evidence format, and stopping conditions.
- Prefer the smallest evidence-backed implementation. Do not add speculative abstraction, compatibility layers, fallbacks, retries, or validation to hide uncertainty.
- Preserve user-owned dirty files. Implementers do not stage or commit. After acceptance, the root agent stages exact task paths and commits only when authorized by the user and when the change forms one coherent theme.
步骤 C:创建全局自定义 Agent
创建 ~/.codex/agents 目录,并按前述冲突处理规则新增或定点更新以下文件。每个文件必须使用 developer_instructions 字段;luna-recon-max.toml 是通过目标客户端能力核对后才部署的可选项。
文件 1:~/.codex/agents/sol-implementer.toml
name = "sol_implementer"
description = "Implementation agent for tightly scoped production and test code changes."
model = "gpt-5.6-sol"
model_reasoning_effort = "xhigh"
sandbox_mode = "workspace-write"
developer_instructions = """
Implement only the explicitly assigned scope.
Follow all applicable AGENTS.md instructions.
Do not change the task goal, expand scope, add speculative features, or perform unrelated refactoring.
Do not add compatibility layers, fallbacks, abstractions, or defensive guards without direct evidence that they are required.
Do not delegate to another agent.
Do not stage, commit, push, publish, or modify planning and memory files.
Preserve user-owned and unrelated working-tree changes.
Use test-driven development when the repository requires it.
Run targeted verification appropriate to the change.
Return an evidence packet containing changed files, decisions, exact commands, results, failures, and remaining unknowns.
"""
文件 2:~/.codex/agents/sol-reviewer.toml
name = "sol_reviewer"
description = "Read-only independent reviewer for architecture, correctness, security, concurrency, and regression risks."
model = "gpt-5.6-sol"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
developer_instructions = """
Review only the assigned scope and remain read-only.
Follow all applicable AGENTS.md instructions.
Do not edit files, stage, commit, push, publish, or delegate.
Prioritize correctness, security, data integrity, concurrency, behavior regressions, and missing test coverage.
Do not report style-only findings unless they conceal a real defect.
For each finding, provide severity, file and line evidence, impact, reproduction or counterexample, and the smallest defensible remediation.
Distinguish confirmed findings from risks and unverified gaps.
End with an APPROVE or BLOCK recommendation; the root agent retains final acceptance authority.
"""
文件 3:~/.codex/agents/terra-qa.toml
name = "terra_qa"
description = "Independent QA agent for builds, tests, runtime reproduction, browser checks, and emulator evidence."
model = "gpt-5.6-terra"
model_reasoning_effort = "high"
sandbox_mode = "workspace-write"
developer_instructions = """
Validate only the assigned behavior.
Follow all applicable AGENTS.md instructions.
Do not modify production or test source files.
Workspace-write permission exists only because builds and tests may create generated outputs.
Do not delegate, stage, commit, push, or publish.
Record exact commands, exit codes, observed behavior, screenshots or logs when relevant, and the limits of the evidence.
Separate local engineering evidence from physical-device, production, external-service, or release proof.
Return PASS, FAIL, or BLOCKED for each acceptance criterion; do not claim the whole task is complete.
"""
文件 4:~/.codex/agents/luna-recon.toml
name = "luna_recon"
description = "Read-only agent for narrow searches, code-path mapping, inventory, and evidence collection."
model = "gpt-5.6-luna"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
Stay within the assigned question and remain read-only.
Follow all applicable AGENTS.md instructions.
Prefer targeted search and focused file reads over broad repository scans.
Do not repeat exploration already supplied by the root agent.
Do not propose speculative fixes unless explicitly asked.
Do not edit, delegate, stage, commit, push, or publish.
Return concise findings with file and symbol evidence, the smallest counterexample found, and remaining unknowns.
"""
文件 5:~/.codex/agents/luna-recon-max.toml
name = "luna_recon_max"
description = "Read-only Luna agent for a narrow, self-contained analysis that demonstrably needs deeper reasoning."
model = "gpt-5.6-luna"
model_reasoning_effort = "max"
sandbox_mode = "read-only"
developer_instructions = """
Accept only a narrow task with explicit inputs, outputs, evidence requirements, and stopping conditions.
Remain read-only and follow all applicable AGENTS.md instructions.
Do not implement code, make architecture decisions, approve security-sensitive changes, delegate, stage, commit, push, or publish.
Stop and return BLOCKED if the task requires broader context or production-code judgment.
Return only evidence-backed conclusions and remaining unknowns.
"""
步骤 D:静态验证
1. 用 TOML 解析器检查主配置语法,并在步骤 E 的实际启动命令中启用 --strict-config 检查未知字段;不要用 --version 的成功退出代替配置校验。
2. 逐个解析已部署的 Agent TOML,核对 name、description、model、model_reasoning_effort、sandbox_mode 和 developer_instructions;文件存在或字符串匹配不代表配置有效。
3. 确认实际生效的全局指令文件中三个目标章节各有一节;对比合并前后的内容,保留用户规则。
4. 确认 ~/.codex/config.toml 只有一个 [agents] 表。
5. 枚举从全局、项目根目录到目标工作目录实际发现的指令文件,计入合并分隔符,检查是否超过 project_doc_max_bytes(默认 32768 字节)。
6. 确认 Astra 模型、effort 和 model_verbosity 是根级值,新建线程的派发值与自定义 Agent 固定值一致。单独报告可选 Luna Max 的状态。
7. 确认 max_concurrent_threads_per_session 的持久值为 6;不要把它写成同时运行数量或官方固定默认值。
步骤 E:新会话加载验证
按 codex exec --help 启动新进程或新任务,显式使用 --sandbox read-only、--ephemeral、--model gpt-6-astra、-c model_reasoning_effort=high、-c approval_policy=never,并启用 --strict-config。在已知项目目录执行下述验收;检查父会话实际权限,不能只靠 Prompt 宣称只读。读取运行时有效的 max_concurrent_threads_per_session;磁盘值正确不能证明旧任务已经热重载。
“Read-only activation smoke test. Do not modify files. Report the loaded instruction sources and whether Writing Style, Execution and Verification, and Codex Subagent Dispatch are present. Separate visible runtime settings from values merely read from configuration files.”
步骤 F:子代理烟测
新建一个范围明确的只读 luna_recon 线程。spawn 必须显式指定:
- model = gpt-5.6-luna
- reasoning_effort = medium
- 若 spawn_agent 提供对话 fork 选项,选不 fork 或有限轮次
先确认当前工具 schema 提供这些派发参数;不支持时报告接口限制。让它只定位一个已知文件中的已知符号,等待结果,并比较烟测前后的 Git 状态和 diff。保留原有脏文件,不把原有修改归因于烟测。
步骤 G:最终报告
报告:
- Codex 版本和实际 Codex Home。
- 修改和创建的文件。
- 合并了哪些键和 AGENTS.md section。
- 主配置和各 Agent TOML 分别使用的解析命令与结果。
- 根代理与已部署 Agent 的模型、effort 和 sandbox 矩阵;可选 Luna Max 的状态。
- 新会话加载结果。
- 只读子代理烟测结果。
- 新进程读取到的 max_concurrent_threads_per_session 有效值,并与磁盘值分开报告。
- 实际运行时是否显示子代理最终模型和 effort;如果没有显示,必须把它标记为可观测性限制,不能伪称已经独立观察到。
- 任何未验证项。
- 本机保存的恢复材料位置,不输出敏感原文。
- 确认没有修改、暂存、提交或推送任何项目文件;任何未完成项都不能写成全部部署成功。
完成前不要提交任何 Git 仓库,也不要更新 memory。部署完成后的验证 Prompt
启动一个全新的 Codex 对话后发送:
这是只读配置验收任务,不要修改任何文件,不要派发写入代理。
请报告:
1. 当前 Codex 版本和工作目录。
2. 本会话加载了哪些全局和项目 AGENTS.md 指令来源。
3. 是否存在 Writing Style、Execution and Verification、Codex Subagent Dispatch 三节规则。
4. 当前可用的自定义 Agent 名称。
5. 对根代理和每个 Agent 报告配置中的 model、model_reasoning_effort 和 sandbox_mode,并核对运行时可见值及覆盖来源。可选 Luna Max 单独报告。
6. 当前 max_concurrent_threads_per_session 的文件值和新进程有效值;说明它限制打开的子代理线程,不是同时执行数。
7. 是否存在 AGENTS.override.md 或项目配置覆盖全局规则。
8. 是否存在未知字段、重复 TOML table 或解析错误。
不要输出任何密钥、token、HTTP header、MCP secret 或完整 config.toml。
将“从配置文件读取到的值”和“运行时实际可观察到的值”分开报告;如果运行时不显示子代理实际模型或 effort,明确写成未直接观测。只读 Luna 烟测 Prompt
把目标文件和符号改成目标项目中确实存在的内容:
这是只读 subagent 烟测。先确认父会话已经处于 read-only 权限模式;否则停止烟测并报告需要调整的运行设置。
使用自定义 Agent `luna_recon` 完成且只完成一个任务:定位 `<目标文件>` 中定义 `<目标符号>` 的行号。
新建线程时必须显式指定:
- model = `gpt-5.6-luna`
- reasoning_effort = `medium`
- 若 `spawn_agent` 提供对话 fork 选项,选不 fork 或有限轮次
以当前会话工具 schema 为准;缺少必需字段时报告限制,不虚构参数。派发值必须与 luna_recon 配置一致。
不要修改文件,不要运行构建,不要继续派发,不要做额外仓库扫描。等待子代理返回,然后报告:Agent 类型、请求的模型和 effort、运行时实际显示的模型和 effort(若未显示则说明)、文件和行号证据,以及相对于烟测前 Git 状态和 diff 的变化。新项目接入 Prompt
全局 Agent 已部署后,每个项目只需要一份准确的项目根目录 AGENTS.md。把下面 Prompt 发给 Codex,并将 <项目路径> 替换为真实路径:
请为 `<项目路径>` 设计并创建或更新项目根目录 AGENTS.md。
执行边界:
- 先只读检查项目结构、构建文件、现有文档、真实测试命令和当前 Git 状态。
- 保留已有 AGENTS.md 内容,只做必要的项目级合并。
- 不复制全局“Codex Subagent Dispatch”全文;明确本项目继承全局调度规范,只写项目特有规则。
- 不修改生产代码或测试代码。
- 不暂存、不提交、不推送。
- 不写猜测性的构建命令、模块结构、依赖版本或测试数量。
- 发现信息不确定时列出未知项和可验证证据,不加入 fallback 或宽泛规则。
AGENTS.md 至少应覆盖:
1. 项目简介和真实技术栈。
2. 当前模块或目录结构。
3. 架构边界与禁止事项。
4. 安全、凭据和外部系统约束。
5. 真实可运行的构建、测试、lint 和格式化命令。
6. 针对 UI、移动端、后端、数据库或基础设施的验证要求。
7. Git、脏工作区、暂存、提交和发布纪律。
8. 项目专属的 subagent 路由例外;若没有例外,写明继承全局规则。
9. 指令优先级和适用范围。
完成后:
- 展示 AGENTS.md 的变更摘要。
- 报告使用了哪些来源验证每条关键事实。
- 按目标工作目录检查实际加载的完整指令链,包括 override、嵌套目录指令和合并分隔符,是否超过 project_doc_max_bytes(默认 32768 字节)。
- 给出一个新会话只读验证命令。
- 不创建 commit。正常工作 Prompt 示例
配置生效后,日常任务不需要重复完整调度规范。
实施任务
修复 `<具体问题>`,严格遵循已加载的全局 Codex Subagent Dispatch 和当前项目 AGENTS.md。
先锁定范围和验收条件;需要修改代码时交给 Sol 实现代理,完成后做独立代码审查与运行时 QA。保留用户已有修改,不扩大范围,不提交。只读审查
只需要 review,不修改任何代码或文档。按已加载的调度规范选择只读 Agent,并按严重性返回有文件和行号依据的 findings。没有发现时明确说明剩余验证缺口。深度调查
对 `<问题>` 做证据驱动的深度调查。根代理负责切分问题;只并行派发互不依赖的只读侦察。每次新建子代理线程都显式指定模型和 reasoning effort;匹配的已有线程可通过 followup 复用原配置。先给出最小反例、真实执行路径和未解决未知项,不实施修复。持续实施到完成
继续当前已明确范围的任务,按照 implement → independent review → exact repair → re-verify 循环执行,直到所有当前阶段验收条件满足或出现真实外部 blocker。不要静默扩大范围,不要提交或推送。实际部署记录
13.1 2026-09-02 至 09-04:旧版记录
以下保留原文的部署记录,适用范围是 CLI 0.152.1、Sol 主线程,不作为新版 Astra 方案的验收结果:
- Codex Home 使用
C:\Users\DS\.codex;增量配置[agents],创建五个角色 TOML,并合并全局调度规则。 - 原文记录新会话加载成功;Luna 烟测定位到
E:\DS-Studio\cordy-app\settings.gradle.kts:1的rootProject.name = "CordyAI",项目文件没有变化。 - 当时只观察到角色类型和请求的模型、effort,没有直接观察子代理最终生效值。
- 全局与 CordyAI 项目根指令的统计为
16,393字节。这个数字只覆盖当时统计的文件;其他工作目录仍须核对完整指令链。 - 2026-09-04 增加
Writing Style,未改子代理配置;原文记录没有暂存、提交或推送。
原文把 codex --strict-config --version 的成功返回写成“解析成功”,这项结论撤回。版本输出不足以证明配置加载或角色激活。
13.2 2026-09-05:本次核验范围
本次读取了官方 GPT-6、Codex 模型、子代理和配置文档,并核对本机 CLI 0.153.4 的帮助。另用临时、无凭据的 Codex Home 做了离线反例实验:
| 临时配置与命令 | 观察结果 | 能证明什么 |
|---|---|---|
未知根键 + codex --strict-config --version | 退出码 0,仅输出版本 | 不能据此验收配置 |
未知根键 + codex --strict-config features list | 退出码 1,提示该子命令不支持 strict-config | 不能作为替代校验命令 |
未知根键 + codex --strict-config exec --ephemeral --sandbox read-only,标准输入关闭且不提供 Prompt | 退出码 1,报告 unknown configuration field | exec 启动会读取并校验主配置 |
最后一种离线探测在配置有效但未提供 Prompt 时也会退出 1,须检查错误内容。它没有发起模型请求,也不能证明自定义 Agent 已加载、账号可访问 Astra,或任务质量已达标。
本次没有把博客示例部署到用户的全局配置,也没有重新执行完整 Astra 跨设备烟测。新版验收应在目标机器按下一节完成。
13.3 2026-09-08:子代理容量修正
本次只核对子代理线程容量。官方配置参考把 max_concurrent_threads_per_session 定义为同时打开的子代理线程上限,不含根线程;官方完整配置示例使用 6。官方资料只说明未设置时由 Codex 选择默认值,没有承诺跨版本固定默认值,也没有给出适用于所有任务的最佳并发数。
本机旧桌面任务连续 7 次新建线程返回 agent thread limit reached;最近两个子代理显示 completed 后仍无法新建,说明完成状态没有释放可用容量。当前工具没有关闭线程接口,随后通过 followup_task 复用匹配的 reviewer 成功继续工作。这些观察支持复用与关闭规则,不证明把配置文件改成 6 会让旧任务热重载。
本机 CLI 0.153.4 已用 --strict-config 启动新的 app-server 进程,config/read 读取到 max_concurrent_threads_per_session = 6;结构化 TOML 比对确认除该键从 2 改为 6 外,其余配置值相等。空 Codex Home 的 config/read 返回空 agents,没有暴露未设置时的有效默认值。此次没有完成新的 Sol 派发烟测,因此只确认新进程读取到容量配置,不把旧桌面任务或新实现代理写成已经恢复。
13.4 2026-09-14:0.154.0 全篇复核
本机已升级到 CLI 0.154.0(2026-09-09 发布)。把当天的官方文档按 .md 下载后,用三个读取器分别核对配置、本文和 Claude Code 的 Codex 插件,再由一个对抗式复核者逐条验证,70 条发现中 57 条确认。本次修正:
- 工具名:本文和 AGENTS.md 里的
followup_task、fork_turns、interrupt_agent在文档里不存在;features.multi_agent的说明列出的工具是spawn_agent、send_input、resume_agent、wait_agent、close_agent。13.3 写的“当前工具没有关闭线程接口”由此撤回:关闭线程用close_agent;文档没有说completed会释放槽位,13.3 观察到不释放。 - 并发规则:“通常最多同时运行两个子代理”删除。Codex 文档里所有成本句都按子代理计,没有一句说并发更贵;改为独立子代理并行到线程上限、按文件所有权串行写入。
- 本机配置:根 effort 从
xhigh改回本文的high(目录默认是medium,根代理只做拆分、派发和验收);sandbox_mode从danger-full-access改为workspace-write,approval_policy保持never(不弹窗,越界操作直接失败;docker、pnpm、vitest 等常用命令由rules/default.rules放行到沙箱外);[windows] sandbox从elevated改为unelevated,因为codex doctor报告提权沙箱 provisioning 失败,而删掉该键不会回退,文档写明未设置时优先 elevated。改完后codex doctor显示 filesystem restricted、network enabled,原来的失败项消失。 - 清理:
features.js_repl(codex features list标记为 removed);两条在codex plugin list里没有对应已安装插件的 plugin 项(github@openai-curated、sites@openai-bundled);outlook-email、figma在配置里写enabled = false但codex plugin list仍显示 installed, enabled,改用codex plugin remove卸载;13 条按0.1.1版本路径禁用的 real-engineer-skills(15 个里漏了caveman、zoom-out)合并为插件级enabled = false一行;rules/default.rules里 6 条一次性脚本规则删除,git add、git commit的放行保留,因为 workspace-write 下.git是只读保护路径,根代理经授权提交时需要它,但 rules 不能按代理区分,这两条对子代理同样生效,子代理不提交只靠 AGENTS.md 约束;25 条 temp 目录的 trust 条目删除;指向已不存在.orca路径的hooks.json.bak移入 backups。 - 未处理:config.toml 里的两把 MCP key 保持原样(用户决定);rollouts 2.1 GB 与 thread inventory 不一致由自带的 keep-codex-fast skill 和
codex doctor --json另行处理。 - 事实修正:Astra 的目录档位含
ultra,gpt-5.6-sol默认 effort 是low,model_verbosity = "low"只是复述每个模型的默认 verbosity,这三项的来源是本机~/.codex/models_cache.json(客户端缓存的模型目录),文档没有按模型列出这些默认值;0.153.4 起 Astra 是内置默认模型,显式 pin 仍保留;0.154.0 新增--worktree与 Windows 共享后台 app-server(codex app-server daemon),并移除codex mcp-server(本机配置和 Claude Code 的 Codex 插件都不依赖它,插件走codex app-server)。
验证命令
先用 codex doctor 做零 token 的健康检查:它报告版本、解析后的模型、config.toml 是否解析成功、登录状态、MCP、沙箱和审批策略。注意 doctor 不检查未知键:codex doctor --strict-config 直接报参数错误,放在前面当全局参数(codex --strict-config doctor)会被接受但对未知键仍显示解析成功,所以下面带 --strict-config 的 exec 探针不能省。再在已知项目目录启动显式只读的新会话。以下加载验收会使用模型;--ephemeral 控制会话文件持久化,不能代替 sandbox。实际来源、角色激活和模型值按第 9、10 节分别核对。
Windows 上 0.154.0 起可能存在共享的后台 app-server;“新进程读取有效值”的验证只在 doctor 的 Background Server 行显示未运行、或重启该 daemon 之后才成立。
Windows PowerShell
codex --version
codex doctor
codex exec --help验证某项目的指令加载:
codex exec --strict-config --ephemeral --sandbox read-only -c approval_policy=never --model gpt-6-astra -c model_reasoning_effort=high --cd "X:\Projects\my-project" "Read-only activation check. List the loaded instruction sources and summarize Writing Style, Execution and Verification, and Codex Subagent Dispatch. Do not modify files. Distinguish requested settings from visible runtime values."烟测前后各检查一次项目状态和 diff,比较差异:
git -C "X:\Projects\my-project" status --short --branch
git -C "X:\Projects\my-project" diffmacOS / Linux
codex --version
codex doctor
codex exec --help
codex exec --strict-config --ephemeral --sandbox read-only \
-c approval_policy=never --model gpt-6-astra -c model_reasoning_effort=high \
--cd "/path/to/project" \
"Read-only activation check. List the loaded instruction sources and summarize Writing Style, Execution and Verification, and Codex Subagent Dispatch. Do not modify files. Distinguish requested settings from visible runtime values."
git -C "/path/to/project" status --short --branch
git -C "/path/to/project" diff常见问题
15.1 修改配置后当前对话没有变化
原因:Codex 在每次运行或新会话开始时构建指令链,config.toml 与 AGENTS.md 的改动只对新会话生效。
处理:开启新对话或重启目标目录中的 Codex。无需手工清缓存。0.154.0 起插件工具、skills 和 hooks 会在运行中的会话内刷新,这几类不需要重启。
15.2 AGENTS.md 内容被截断
检查:实际加载的指令链是否达到默认 32 KiB,是否有 override 遮蔽目标文件;不要只根据两个文件的合计大小下结论。
处理:删除重复规则,保留全局通用规则和项目专属规则。只有确有必要时才调整 project_doc_max_bytes。
15.3 自定义 Agent 没有出现
检查:
- 文件是否位于实际
CODEX_HOME/agents。 - 是否开启了新会话。
- TOML 是否包含三个必需字段。
name是否唯一。- 主配置与对应 Agent TOML 是否分别解析成功,启动时是否出现角色加载错误。
- 当前 Codex 版本是否支持文档中的配置。
不要添加未经官方文档证明的旧式注册或兼容层。
15.4 子代理模型没有显示
历史 CLI 记录只显示 Agent 类型和请求值。0.153.0 起 app-server 的线程元数据带有 model 与 reasoningEffort 字段,thread/list 可按 parentThreadId 过滤出某个根线程的子线程(experimental API,需要 capabilities.experimentalApi = true),这两个字段可为 null,非空时子代理实际生效的模型和 effort 可以由此读回。目标客户端不显示这些值时,应:
- 检查 Agent TOML 固定值。
- 检查派发调用显式值。
- 检查二者一致。
- 把运行时实际值标记为“未直接观测”,不要声称已验证。
15.5 agent thread limit reached
这个错误表示当前任务已经达到打开的子代理线程上限,不表示同时有同样数量的代理正在执行。文档只计打开的线程,没有说 completed 会释放槽位,13.3 观察到不释放;关闭要用 close_agent。
处理顺序:
- 刷新代理清单,核对当前任务的有效线程上限。
- 用
close_agent关闭不再需要的已完成线程,以一次成功的 spawn 确认容量释放。 - 查找模型、effort、角色和文件所有权匹配的现有代理,通过
send_input(已完成线程用resume_agent)复用;保持 reviewer 独立性和只读边界。 - 修改过磁盘配置时,在未连接后台 app-server 的新进程中核对有效值,不把文件变化当成旧任务热重载的证据。
- 仍满额时,在新任务中接续并传递必要上下文。不要无限重试、降低 Sol /
xhigh或绕过独立审查。
用户已经授权调整线程上限时,可以定点修改该键并在新进程或新任务中验证。没有授权时不要自行提高上限。
15.6 模型容量不足
- 不要静默降级实现任务。
- 停止反复并发重试。
- 串行等待或缩小任务。
- 只有重新分类为 QA 或窄侦察后,才显式改用 Terra 或 Luna。
回滚
按部署前保存的本机恢复材料逐项撤回:
- 停止新子代理派发。
- 对三个根键和五个
[agents]键,原本存在的恢复原值,本次新增的才删除。[agents]表仅在本次新建且撤回后为空时移除。 - 恢复实际修改的全局指令文件中相关章节的原内容;只删除本次新增章节,保留部署前已有规则。
- 对 Agent TOML,恢复被更新文件的原内容,仅删除本次新建文件;可选 Luna Max 同样处理。
- 若部署后这些位置又有其他修改,先列出差异,不能用整份旧备份覆盖后续工作。保留凭据、MCP、plugin、hook 和项目配置。
- 按第 14 节验证恢复后的配置与指令加载;模型参数改回部署前记录值。
- 报告具体不兼容字段、版本及未恢复项。没有原始值时明确报告缺失,不猜测旧值。
安全检查清单
[ ] 已确认真实 CODEX_HOME
[ ] 已记录 Codex 版本
[ ] 没有打印或复制任何密钥
[ ] 没有整体覆盖 config.toml
[ ] 已在本机记录相关键、章节与文件的原始状态
[ ] Astra 模型、effort 与 model_verbosity 位于 TOML 根级
[ ] [agents] 只有一个,且没有遗留的 max_threads
[ ] max_concurrent_threads_per_session 的文件值与新进程有效值分别核对;没有把它写成同时执行数或固定默认值
[ ] 并发规则是“独立子代理并行到线程上限、按文件所有权串行”,没有残留“最多两个”的旧约定
[ ] 指令里只出现文档化的工具名(spawn_agent、send_input、resume_agent、wait_agent、close_agent)
[ ] Writing Style 只有一个
[ ] Execution and Verification 只有一个
[ ] Codex Subagent Dispatch 只有一个
[ ] 已部署 TOML 均包含 developer_instructions;可选 Luna Max 状态明确
[ ] 每个 Agent 的 model 和 effort 已显式固定
[ ] 派发值与自定义 Agent 文件一致
[ ] 新建线程显式指定 model 和 effort;复用线程的原配置、角色和所有权匹配任务
[ ] 主配置与 Agent TOML 分别完成解析,未用 --version 代替验收
[ ] 已核对实际指令链、覆盖来源和大小
[ ] 已开启新会话验证加载
[ ] 父会话的实际权限为只读,Luna 烟测未改变已有工作区差异
[ ] 已记录运行时模型可观测性边界
[ ] 没有修改项目代码
[ ] 没有暂存、提交或推送部署后的最终 Workflow
代码实施任务按以下流程执行;只读或文字任务按范围选择必要步骤。
User request
↓
Astra root defines scope, ownership, and acceptance criteria
↓
Optional Luna reconnaissance
↓
Sol implementation
↓
Sol independent high-risk review + Terra runtime QA
↓
Exact repair by the original Sol implementer when required
↓
Independent re-verification
↓
Astra root inspects diff and evidence
↓
Accepted
↓
Exact staging
↓
Commit or push only when explicitly authorized把第 8 节完整 Prompt 发送给目标电脑上的 Codex,即可开始兼容性核对与增量部署。只有配置加载、角色烟测和实际任务验收都有证据时,才把该设备标为部署完成。
自建 API 封装时,哪些能力属于运行时
前文配置的是 Codex 客户端。如果你还维护基于 Responses API 的自建执行器,GPT-6 的三个新能力需要运行时代码配合:
| 能力 | 接入位置与限制 | 对执行器的影响 |
|---|---|---|
| 异步工具调用 | 在 function 或 custom tool 定义上设置 async: true;不用于托管内置工具,也不与 Programmatic Tool Calling 混用 | 应用仍负责执行任务,并用原 call_id 回传结果;模型可继续处理独立工作。文档 |
| 执行中追加要求 | Responses WebSocket 的 response.steer | 接受事件只表示更新入队;它不会撤销已执行操作或取消已启动工具,执行器要继续处理事件和工具结果。文档 |
| 保留缓存前缀并调整推理强度 | 在相邻响应之间加入 configuration_update,保持请求级 reasoning.effort 不变;目前限 Astra 的 standard、single-agent 模式 | 为后续响应调整 effort,不能当成多代理编排的通用配置项。文档 |
这些是 API 协议能力,不能写成 config.toml 开关来启用。异步工具在 API Multi-agent 模式下还有不能与 parallel tool calls 组合的限制;它也不等于 Codex 的本地子代理调度。
自建 API 调用链迁移到 Astra 时,工具调用使用 Responses API,并检查旧请求中的 temperature、top_p、top_logprobs 等不支持参数。缓存、Fast mode 等变化按实际使用项迁移,避免把无关 API 参数混入这套 Codex 配置。迁移说明