Codex CLI 调用指南

Codex 技能指南

运行任务

1. 对于新会话（恢复会话会继承之前的模型/推理强度——参见步骤 5），通过 AskUserQuestion 以单个提示两个问题的形式询问用户使用哪个模型以及哪个推理强度。当用户没有偏好时，默认使用 gpt-6-astra 和 high。
   • 模型——默认 gpt-6-astra：
     • GPT-6： gpt-6-astra（前沿/能力最强——默认）
     • GPT-5.6： gpt-5.6-sol（可靠的智能体工作马）、gpt-5.6-terra（平衡日常使用）、gpt-5.6-luna（快速且经济）
     • 遗留模型（保留兼容性）： gpt-5.5、gpt-5.4、gpt-5.4-mini、gpt-5.3-codex-spark、gpt-5.3-codex
   • 推理强度——默认 high：low、medium、high、xhigh、max、ultra。
     • max/ultra 需要 GPT-6 或 GPT-5.6 模型；ultra 仅适用于 astra/sol/terra（luna 最高支持 max）；遗留模型最高支持 xhigh。
     • ultra = 最大推理强度并带有自动任务委派（最慢且最昂贵——留给最难的任务）。
     • 如果所选强度超过所选模型的最大支持强度，则回退到该模型支持的最高强度并告知用户。
2. 选择任务所需的沙箱模式；除非需要编辑或网络访问，否则默认使用 --sandbox read-only。
3. 使用适当的选项组装命令：
   • -m, --model <MODEL>
   • --config model_reasoning_effort="<low|medium|high|xhigh|max|ultra>"（max/ultra 仅适用于 GPT-6 / GPT-5.6 模型；ultra 仅适用于 astra/sol/terra——参见步骤 1）
   • --sandbox <read-only|workspace-write|danger-full-access>
   • --full-auto
   • -C, --cd <DIR>
   • --skip-git-repo-check
   • "your prompt here"（作为最终位置参数）
4. 始终使用 --skip-git-repo-check。
5. 当继续之前的会话时，通过标准输入使用 codex exec --skip-git-repo-check resume --last。恢复时，除非用户明确要求（例如指定了模型或推理强度），否则不要使用任何配置标志。恢复语法：echo "your prompt here" | codex exec --skip-git-repo-check resume --last 2>/dev/null。所有标志必须插入 exec 和 resume 之间。
6. 重要：默认情况下，在所有 codex exec 命令后附加 2>/dev/null 以抑制思考令牌（stderr）。仅当用户明确要求查看思考令牌或需要调试时才显示 stderr。
7. 重要（标准输入）：codex exec 总是读取标准输入并将其与位置提示词拼接——即使提示词已完全作为位置参数提供。如果标准输入未关闭，codex 将永久阻塞。当从后台任务、钩子、脚本等非 TTY 但标准输入也未关闭的环境中调用时，请显式重定向标准输入：在命令后追加 </dev/null，例如 codex exec ... "prompt" </dev/null 2>/dev/null。弄错这个的症状：标准输出为零字节、CPU 累积为零、进程似乎无限挂起。
8. 运行命令，捕获标准输出/标准错误（适当过滤），并向用户总结结果。
9. Codex 完成后，告知用户：“您可以随时通过说‘codex resume’或让我继续进行额外的分析或更改来恢复此 Codex 会话。”

快速参考

使用场景	沙箱模式	关键标志
只读审查或分析	read-only	--sandbox read-only 2>/dev/null
应用本地编辑	workspace-write	--sandbox workspace-write --full-auto 2>/dev/null
允许网络或广泛访问	danger-full-access	--sandbox danger-full-access --full-auto 2>/dev/null
恢复最近会话	继承自原始会话	echo "prompt" | codex exec --skip-git-repo-check resume --last 2>/dev/null（不允许携带标志）
从其他目录运行	匹配任务需求	-C <DIR> 加上其他标志 2>/dev/null

执行超时

Codex 不产生任何中间输出——仅在完成时写入结果。如果在完成前终止了进程，输出文件会静默为空（无错误）。

首选方法： 同步运行——完全消除了超时风险，并且对话无论如何都会等待结果。

如果在后台运行，请根据推理强度设置执行超时时间：

推理强度	超时时间
low	150 秒
medium	300 秒
high	600 秒
xhigh	1200 秒
max	1800 秒
ultra	1800 秒

后续跟进

• 在每次 codex 命令后，立即使用 AskUserQuestion 确认后续步骤、收集澄清信息，或决定是否使用 codex exec resume --last 恢复。
• 恢复时，通过标准输入传递新提示词：echo "new prompt" | codex exec resume --last 2>/dev/null。恢复的会话会自动使用原始会话的相同模型、推理强度和沙箱模式。
• 在提议后续操作时，重申所选的模型、推理强度和沙箱模式。

对 Codex 输出的批判性评估

Codex 由 OpenAI 模型驱动，有其自身的知识截止日期和局限性。将 Codex 视为同事，而非权威。

指南

• 有信心时相信自己的知识。如果 Codex 声称的内容您知道是错的，请直接反驳。
• 研究分歧。在接受 Codex 的声明之前，使用 Web 搜索或文档进行研究。如有必要，通过恢复 Codex 会话与 Codex 分享发现。
• 记住知识截止日期——Codex 可能不了解其训练数据之后发布的最新版本、API 或更改。
• 不要盲目听从——Codex 可能会出错。批判性地评估其建议，尤其是在以下方面：
  • 模型名称和能力
  • 最新的库版本或 API 更改
  • 可能已经演变的最佳实践

当 Codex 出错时

1. 向用户清楚说明您的异议
2. 提供证据（您自己的知识、网络搜索、文档）
3. 可选地恢复 Codex 会话以讨论分歧。表明您是 Claude，以便 Codex 知道这是 AI 同事间的讨论。使用您实际的模型名称（例如，您当前运行的模型）而不是硬编码名称：

   echo "这是 Claude (<your current model name>) 跟进。我不同意 [X]，因为 [证据]。您对此怎么看？" | codex exec --skip-git-repo-check resume --last 2>/dev/null
   

4. 将分歧表述为讨论而非纠正——任一 AI 都可能出错
5. 如果存在真正的歧义，让用户决定如何继续

错误处理

• 当 codex --version 或 codex exec 命令以非零退出时，停止并报告失败；在重试前请求指示。
• 在使用高影响标志（--full-auto、--sandbox danger-full-access、--skip-git-repo-check）之前，使用 AskUserQuestion 询问用户权限，除非已获得许可。
• 当输出包含警告或部分结果时，总结它们并使用 AskUserQuestion 询问如何调整。