Codex 自调用 / 调 Claude Code / Loop

Z3 全文↑ Z2 条目

术-运行时 · 术层 skill 全文

本页是 <code>rules/skills/codex_self_evoke_call_claude_code_loop.md</code> 的逐字投影（仅隐私清洗，零改写）。

时点提示：本页是仓内文件 rules/skills/codex_self_evoke_call_claude_code_loop.md 的逐字投影（仅做隐私清洗：仓库根绝对路径→相对路径、家目录→~/；除此零改写）。若源文件后续有修订，以仓内真源为准。

Skill：Codex 自调用 / 调 Claude Code / Loop

使用时机

Codex 需要调用另一个 CLI agent，或需要用可恢复 Loop 形式推进一个跨轮任务时使用。目标可以是另一个非交互 Codex CLI 进程，也可以是 Claude Code / Claude-compatible wrapper，用于隔离实现、交叉验证、fallback、长上下文审查、Claude harness 专属工作，或把复杂任务拆成多个可审计闭环。

本 skill 是 Codex 侧统一调用入口。文件名故意写全 self_evoke、call_claude_code 和 loop，但这里的 loop 只表示 Codex runtime 执行形态。用户泛称“做 Loop”、持续推进、优化并测试 Skill、AAU/AOU 多轮任务、或处理 Skill 非正交问题时，先进入 workflow_controller_loop；只有 Controller 明确选择 Codex runtime、自调用或 Codex 调 Claude Code 时才使用本 skill。它覆盖三类动作：

Codex 自调用：通过 codex exec 执行隔离实现、审查、smoke test、第二意见或 Loop 中的独立证据 run。
Codex 调 Claude Code：通过 cli_agent、claude-zai、claude-kimi、native claude -p 让 Claude Code 读取 AGENTS.md、rules、skills 和 hook 注入后的项目上下文。
Codex Loop 执行：通过 Codex App thread heartbeat 或 codex exec fallback，把长任务推进为一轮轮有限的修改 / 验证 / 保留或丢弃 / 状态更新。

如果任务已经由 workflow_controller_loop 管理，本文件只提供 Codex runtime profile：如何调用模型、如何保留 durable run、如何处理 quota/fallback、如何恢复进程。需求、任务卡、在线审查和业务 closure 由 Controller 持有。

如果只是在选择 Codex App automation、cron、cloud、resume 等调度面，可以参考 codex_schedule_loop。调度层只负责唤醒和观测，不定义业务推进。

边界

按 Codex 运行时归属分 skill，而不是把 Codex 调 Codex、Codex 调 Claude Code、Codex Loop 拆开。三者共享同一组 Codex flag 顺序、durable output、sandbox、OpenAI quota scope、文件交接、fallback、状态恢复和失败分类。拆开会让 trigger 更窄，但会复制不变量并增加不一致风险。

一次性调用和 Loop 的区别是运行模式，不是 skill 边界：一次性调用以 durable result 结束；Loop 以磁盘状态决定下一轮继续、等待用户或停止。若上层存在 workflow_controller_loop，本 skill 不重新定义需求或 review verdict，只写 runtime execution contract。

运行时契约

Provider、模型 profile、key env 名、fallback chain、budget、限额识别只在 llm_runtime 维护，路径查 tools/INDEX.md。
新文档和新代码使用 llm_runtime 的 canonical tier alias。Codex 可精确使用 codex:low / medium / high / xhigh / max / ultra；用户未指定特殊 effort 时用 codex:xhigh（wire 值 xhigh）。codex:ultra 是独立 profile，不得 alias 到 xhigh。
直接 Codex CLI 调用必须先用当前机器的 codex exec --help 核对可用 flags。当前 CLI 使用 codex exec ...；approval 行为来自配置/profile。不要把旧示例中的 --ask-for-approval 写进新 wrapper，除非本机 help 明确支持该 flag。
Codex 结果必须走 durable output file：--output-last-message <file>。
Codex 不传递隐藏 reasoning 给 Claude Code。跨工具交接只通过 prompt 文件、输入文件列表、结果文件和 git diff。
Codex 调 Claude Code 子进程时必须用 env -u CLAUDECODE，并保留 --setting-sources "user,project" --strict-mcp-config。
长 prompt 通过 stdin 或文件传入，避免 shell quoting 和截断问题。
Loop 任务的业务状态必须落盘。heartbeat、cron 或 CLI resume 只负责唤醒，不能作为唯一状态源。
所有 Codex 唤起/唤醒方法都必须保存聊天记录和 rollout。不要使用 codex exec --ephemeral，不要删除 [codex-path] 下的 rollout；每次 agent/user-task run 都要在 ledger 或 receipt 中记录 session id/thread id、rollout_path、source kind 和 run dir。

工具路由

生产脚本优先走 cli_agent，由 router 统一处理 token pre-flight、context overflow、quota 文本识别、cooldown、fallback 和 durable result。工具路径查 tools/INDEX.md。

Codex 调用 Codex：

python3 tools/cli_agent/router.py \
  --task-name codex-subtask \
  --primary codex:xhigh \
  --fallback codex:medium claude-zai:high claude-kimi:medium claude:high \
  < prompt.md

Codex 调用 Claude Code：

python3 tools/cli_agent/router.py \
  --task-name claude-subtask \
  --primary claude-zai:high \
  --fallback claude-kimi:medium claude:high \
  < prompt.md

直接 CLI 只用于 harness 边界测试、CLI 行为验证、或 router 本身不可用的临时诊断。

直接调用 Codex

codex exec \
  --model "$LLM_CODEX_XHIGH_MODEL" \
  --config "model_reasoning_effort=\"$LLM_CODEX_XHIGH_REASONING\"" \
  --sandbox workspace-write \
  --cd ~/context-infra \
  --output-last-message /tmp/codex_last_message.txt \
  - < prompt.md

GPT-5.6 Sol/Terra 的 exact wire efforts 是 low / medium / high / xhigh / max / ultra，Luna 当前到 max。OpenAI 原生默认是 Sol + medium；本仓库 no-special-request policy 是 xhigh。对外可写 x-high，但 CLI 必须传 xhigh。Max 是最大单-agent推理，Ultra 还会自动委派 subagent。

常用 sandbox：

Sandbox	用途
`read-only`	审查、第二意见、解释
`workspace-write`	修改当前 workspace 文件
`danger-full-access`	只在明确需要且已确认风险时使用

Codex Desktop / App 内部已有工具调用面时，不要为小任务再套一层 codex exec。Agent invocation 的价值是隔离上下文、独立判断、或把任务交给另一个 CLI 运行面。直接 codex exec 也必须持久化 session/rollout；禁止为了“临时”或“减少记录”加 --ephemeral。

聊天记录保存是硬要求，App 默认列表可见性只是展示策略。codex exec 是 non-interactive，落库来源为 source=exec，官方 App Server thread/list 默认只列 cli 和 vscode 交互来源；因此它可以保存聊天/rollout，但不能满足“默认 App 列表可见”。用户明确要求在 Codex 中显示，或任务是独立且重要的主线运行（例如单独 Loop 进程、需要用户在 App 侧跟踪的长期任务）时，优先使用 Codex App thread/automation 或交互式 codex [PROMPT] 产生 source=cli 记录。library distillation 子步骤、judge、smoke test、任务内部 worker 等从属小运行默认不制造 App 默认列表噪声；使用 codex exec 或 subagent，但仍必须持久化 session/rollout 和 run logs。

直接调用 Claude Code

env -u CLAUDECODE claude-zai -p \
  --setting-sources "user,project" --strict-mcp-config \
  --max-turns 20 \
  --output-format json \
  --permission-mode acceptEdits \
  < prompt.md > /tmp/claude_result.json 2> /tmp/claude_stderr.log

Kimi 订阅可换成 claude-kimi -p：前台主 session/Opus 使用 k3（1M），Sonnet、Haiku 与普通 sub-agent 使用 kimi-for-coding（K2.7 Coding，256K）。Native Claude high profile：

env -u CLAUDECODE claude -p \
  --model "$LLM_CLAUDE_HIGH_CLI_MODEL" \
  --setting-sources "user,project" --strict-mcp-config \
  --max-turns 20 \
  --output-format json \
  < prompt.md > /tmp/claude_result.json 2> /tmp/claude_stderr.log

调用模式

模式	首选运行时	成功检查
隔离实现	默认 `codex:xhigh`；显式降档可用 `codex:high` 或 `codex:medium`	`git diff` 只含目标改动，测试或 smoke check 可复现
只读审查	`codex:medium` 或 `codex:low`	findings 有文件和行号，风险按严重度排序
跨模型第二意见	Codex agent 调用 + Claude fallback	两边结论差异被显式比较
Claude harness 任务	`claude-zai:high` / `claude-kimi:medium` / `claude:high`	子进程加载 workspace rules，输出 durable file
Judge/Eval	medium tier，证据放 prompt	PASS/FAIL JSON，evidence 引用 appendix
可恢复 Loop 任务	Codex App heartbeat + disk state；必要时 `codex exec` fallback	每轮证据、state、run ledger、next prompt 都落盘；停止条件可复查

可恢复 Loop 任务

Loop 模式用于一个 turn 无法稳妥完成、但可以拆成多个有限闭环的任务。Loop 不是无限后台思考，而是一个可恢复状态机：每轮只处理一到三个原子任务，产出证据，验证结果，更新状态，再决定继续、等待用户或停止。

已落地的参考实现：

adhoc_jobs/library_distillation_round2_codex_20260501/LOOP_ENGINE.codex.md：Codex App thread heartbeat 唤醒当前 thread，业务状态由 loop_state.codex.json、loop_runs.codex.jsonl、PROGRESS.md、HANDOFF.md、VERSION_LOG.md、_CONTEXT_INJECT.md 和 next_prompt.codex.md 决定；需要隔离证据时使用 codex exec durable run。
adhoc_jobs/library_distillation_workflow_audit_20260430_codex/LOOP_ENGINE.codex.md：同一套 self-loop 形态，明确 empty delivery、stderr warning、runtime failure 的分类。
adhoc_jobs/design_doc_protocol_loop_codex_20260501/README.md：每轮遵循修改 / 验证 / 保留或丢弃 / 版本记录，一轮只改一个具体点。

Loop 目录至少需要这些文件：

<loop_dir>/
├─ README.codex.md 或 README.md
├─ LOOP_ENGINE.codex.md
├─ loop_state.codex.json
├─ loop_runs.codex.jsonl
├─ PROGRESS.md
├─ HANDOFF.md
├─ VERSION_LOG.md
├─ _CONTEXT_INJECT.md
└─ next_prompt.codex.md

命名可以随任务调整，但语义不能缺：当前状态、已完成轮次、下一轮 prompt、运行 ledger、恢复说明、停止条件、版本或决策记录都必须能从文件恢复。

Loop 开始时必须恢复状态：

读取 workspace 强制规则、rules/skills/INDEX.md 和任务专属 prompt。
读取 Loop state、progress、handoff、context inject、version log 和 loop_runs 最后一行。
运行 git status --short，确认当前工作树上下文。
如果存在 STOP.codex 或 loop_state 为 awaiting_user，先读取 Controller 状态、USER_PROMPTS/ / REQUIREMENTS.md / HANDOFF.md 中是否有新的 requirement delta 和 allowed isolated action。若 Controller 已解除等待，写 runtime receipt 并继续允许的隔离动作；若仍无允许动作，只报告等待，不生成新业务证据。

Loop 执行时遵守四条硬约束：

每轮只做一个有限闭环，可以用 Polya 四步理解为理解 / 计划 / 执行 / 复核。
每轮必须有 evidence 或 no-op receipt。事实类判断要有机械验证，例如文件存在、字节数、JSON 可解析、turn.completed、样本数。
每轮结束必须更新 loop_state.codex.json、loop_runs.codex.jsonl、PROGRESS.md、HANDOFF.md、VERSION_LOG.md、_CONTEXT_INJECT.md 和 next_prompt.codex.md 中适用的文件。
停止不是默认动作。只有停止条件满足，且任务要求的用户确认已经出现时，才能创建 STOP.codex。

Codex App heartbeat 的职责只是唤醒当前 thread。heartbeat prompt 应指向 next_prompt.codex.md，并要求下一轮从磁盘恢复状态。automation 的创建、更新、cadence、thread/project/worktree 选择转 codex_schedule_loop；研究逻辑、判断依据和业务进度不能只写在 automation 描述里。

CLI fallback 使用独立 run 目录：

codex exec \
  --cd ~/context-infra \
  --json \
  --output-last-message "$RUN_DIR/last_message.md" \
  - < "$RUN_DIR/prompt.codex.md" \
  > "$RUN_DIR/events.jsonl" \
  2> "$RUN_DIR/stderr.log"
rc="$?"
printf "%s\n" "$rc" > "$RUN_DIR/rc.txt"
exit "$rc"

CLI fallback 命令不得包含 --ephemeral。如果某个 wrapper、profile 或示例会让 Codex 不写 [codex-path] / rollout，本方法不能作为唤醒或子调用路径，必须改用会保留 session 的启动面。

如果 CLI fallback 由 cron/launchd 启动，wrapper 必须在每次 invocation 里创建唯一 RUN_DIR，并写入 run ledger。不要让多个启动共用同一个 events.jsonl / stderr.log / last_message.md 路径；后台重复触发或重试会覆盖证据，导致 reviewer 无法判断哪一轮真正完成。

每次 CLI run 至少保留：

runs/loop_<NNN>_<slug>/
├─ prompt.codex.md
├─ events.jsonl
├─ stderr.log
├─ last_message.md
└─ rc.txt

如果上层是 workflow_controller_loop，RUN_DIR 应位于当前 task / loop 目录的 AGENT_RUNS/ 或 runs/agents/ 下，并额外保存 read_paths.txt 与 receipt.yaml。这样 Controller 和 reviewer 可以检查 prompt injection、输入隔离、输出和限制，而不读取完整执行者上下文。

CLI run 只有同时满足这些条件才算可用证据：

rc.txt 为 0。
last_message.md 非空。
events.jsonl 非空，且包含 turn.completed。
本轮预期 evidence 文件存在且可读。
Loop state 和 run ledger 已更新。

如果 rc=0 但 last_message.md 为空，或 events 没有 turn.completed，按 Codex empty delivery 处理。本轮不能计为业务完成。stderr 中的本地 skill YAML、plugin manifest、rollout record warning 可以记录为环境 warning；quota、auth、context overflow、panic、permission denied 是 blocking runtime failure。

提示词与结果交接

Prompt 写目标、边界、输入路径、验收标准、输出路径。
需要 Claude Code 读本仓库规则时，让 Claude Code 子进程自己通过 hook 注入上下文，不在 prompt 中复制整段规则。
Controller 管理下的任务把临时上下文、prompt 和结果放在 task-local AGENT_RUNS/ 或 runs/agents/；只有一次性诊断才放 tmp/<session_slug>/。
Codex 结果读取 --output-last-message 指定文件；Claude Code 结果读取 JSON result 和 stderr。
子进程失败时保留 prompt、结果、stderr、session id 和 rollout path，方便复查或 resume。

失败处理

失败	必需处理
Codex 请求成功但返回限额文本	当作 `openai` quota scope failure，不当作普通 subprocess success
ZAI / Kimi / native Claude 返回限额文本	当作对应 `zai` / `kimi` / `anthropic` quota scope failure
`--output-last-message` 为空	当作 empty result，进入 fallback
Codex CLI flag 不被当前版本支持	运行 `codex exec --help`，移除或改写 stale flag；旧 `--ask-for-approval` 示例不能继续复制到新 wrapper
Claude Code 子进程继承 `CLAUDECODE`	用 `env -u CLAUDECODE`
Claude Code 不知道 workspace 规则	加 `--setting-sources "user,project" --strict-mcp-config`
context 溢出	优先用 router；直接调用时拆输入或换更大 context tier
Loop heartbeat 醒来但 `loop_state` 为 `awaiting_user`	先读 Controller/user delta 和 allowed isolated actions；若等待已解除则写 runtime receipt 并继续允许动作，否则不生成新业务 evidence，只报告等待用户决策
Loop run 未更新 state 或 ledger	本轮不算完成，先补写状态或记录失败
Loop 试图创建 `STOP.codex` 但缺少明确停止条件	不停止，更新 `next_prompt` 和 handoff
模型升级	只改 `llm_runtime` 配置

验收标准

一次调用算完成，必须同时满足：

任务已选对模式：一次性调用直接结束；Loop 任务按本 skill 的磁盘状态契约继续、等待或停止。
使用 tier alias 和 llm_runtime，没有在业务代码里硬编码新模型 ID。
直接 Codex CLI flags 已用当前 codex exec --help 校验，并写入 --output-last-message。
调 Claude Code 时清掉 CLAUDECODE，真实任务加载 user/project settings 并启用 strict MCP config。
Loop 任务有磁盘状态、run ledger、next prompt、evidence、停止条件和恢复步骤；任何下一轮都能不依赖聊天上下文继续。
每个 Codex agent/user-task run 都确认保存了聊天/rollout 记录；没有使用 --ephemeral，ledger 或 receipt 可追到 session id/thread id 与 rollout_path。
结果、stderr 或日志可复查；quota、empty result、context overflow、未更新 state 等失败能进入 fallback 或给出明确失败原因。

← 返回术层 skill 索引 · 返回方法论区