codex

Codex CLI Agent

命令中的 SKILL_DIR 为当前已安装 codex Skill 的绝对目录，不是固定宿主路径。

核心规则

• 通过内置包装脚本调用 Codex，不要直接执行 codex exec。包装脚本负责捕获 JSONL、显示有效进度、记录会话 ID，并生成精简的 Markdown 结果。
• 常规调用不选择或传递模型、思考强度与模型提供商，由本机默认 Codex 配置决定。
• 每个任务先调用一次包装脚本。成功后读取 output_path，检查工作区结果，再判断是否需要继续同一会话。
• 委托提示词应包含目标、完成标准、约束和必要背景，不要规定每一个实现步骤，也不要粘贴大段文件内容。
• 使用 --file 提供 1–4 个重要入口文件，其余路径让 Codex 自己探索。
• 调用方仍负责范围、安全和最终验收。

委托契约

每次只委托一个边界清楚的任务。提示词应简短覆盖：

• 目标：要修改或查明什么，以及明确不应改动的范围。
• 完成标准：预期行为、必须覆盖的边界情况。
• 验证：从仓库配置中确认真实的测试、检查或构建命令，不要只写“运行测试”。
• 安全边界：不执行 git add、git commit，不顺手重构无关代码。
• 最终报告：说明改动与原因、涉及文件、验证结果，以及仍需决定或未完成的事项。

缺少的仓库事实应先查找；无法确认时明确报告，不要猜测。评审或诊断任务要求结论引用代码证据，并区分事实与推断。

包装脚本

macOS 与 Linux：

"$SKILL_DIR"/scripts/ask_codex.sh

Windows：

"$SKILL_DIR"/scripts/ask_codex.ps1

~/.claude/skills/codex 可以作为兼容软链接指向同一个 Skill。

常用调用

新任务：

"$SKILL_DIR"/scripts/ask_codex.sh "实现请求的改动"

指定工作区和入口文件：

"$SKILL_DIR"/scripts/ask_codex.sh "重构这些组件并完成验证" \
  --workspace "/path/to/repo" \
  --file "src/components/UserList.tsx" \
  --file "src/components/UserDetail.tsx"

探索或评审：

"$SKILL_DIR"/scripts/ask_codex.sh "追踪当前请求路径并引用文件和行号" \
  --workspace "/path/to/repo"

继续已有会话：

"$SKILL_DIR"/scripts/ask_codex.sh "继续修复刚才发现的问题" \
  --session <session_id>

使用默认 Codex 时，附加图片并要求结构化结果：

"$SKILL_DIR"/scripts/ask_codex.sh "比较截图与当前实现" \
  --image "/path/to/screenshot.png" \
  --output-schema "/path/to/result.schema.json"

工作流程

1. 读取足够的本地上下文，明确目标和重要限制。
2. 默认使用最高权限运行 Codex；只有用户明确要求限制权限时，才为新会话指定只读或其他沙箱模式。
3. 使用包装脚本派发一段聚焦的提示词，通常控制在 500 字以内。
4. 读取脚本返回的 output_path。
5. 先检查测试是否被删除、跳过或弱化，再检查工作区改动是否越界。
6. 重新运行真实验证命令；Codex 的“测试通过”只是报告，不能替代调用方验收。
7. 检查硬编码成功结果、吞掉异常、未经确认的 API、死代码和无调用方的抽象。
8. 需要返工时继续原会话，只发送新发现和修正要求，不重复整个任务。

包装脚本默认替新会话和续接会话给 Codex 传入 --dangerously-bypass-approvals-and-sandbox，使 Codex 不受自身沙箱和审批限制，调用包装脚本时不用再传。不要因任务是分析、探索或评审就自动加 --read-only；只读是用户明确要求时的权限选项。一次性测试可以使用 --ephemeral。调用方仍须检查 Codex 的改动与验证结果。

思考强度

正常调用不要传 --reasoning，由运行环境使用默认的 high。只有确实需要改变默认行为时才指定：

• high：默认档位，适合绝大多数编码、探索、实现和评审任务；无需显式传递。
• max：仅用于跨模块架构、疑难故障、复杂安全评审，或 high 已尝试但结论仍明显不足的任务。
• low：仅当用户明确优先考虑速度或成本，并且任务是简单、机械、低风险操作时使用。

不要仅因为任务描述较长就自动使用 max；先收窄目标和上下文。

输出

成功后脚本输出：

session_id=<thread_id>
runtime=default
output_path=<path>
result_path=<path>
events_path=<path>
elapsed=<seconds>s

Markdown 结果包含：

• ## Summary：Codex 的最终结论。
• ## Details：有意义的命令、写入、补丁和中间消息；纯读取与搜索会被省略。
• 耗时、命令数和可用的 token 使用信息。

使用 --output-schema 时，Summary 包含符合指定 JSON Schema 的结果。

每次运行使用独立目录，避免并行任务覆盖结果。result_path 是原子写入的结构化状态，包含 completed 或 failed、退出码、运行环境、会话 ID、最终消息、耗时及错误尾部；events_path 保留原始 JSONL，便于失败诊断和恢复。调用方平时只需读取 output_path，出现异常时再读取另外两个文件。

图片

--image 通过默认 Codex 运行环境发送给 Codex。

需要透明背景图片时：

1. 先明确要求生成透明背景 PNG。
2. 指定最终输出路径，并要求 Codex 报告该路径。
3. 只有原生透明效果不可靠时，才使用灰底抠图工具：

python3 "$SKILL_DIR"/scripts/cutout.py input.png output.png

使用该后备方案时，让图像生成在纯 #808080 背景上，执行抠图后确认输出为 RGBA，并检查边缘质量。

对外参数

• --workspace <path>：工作目录，默认使用当前目录。
• --file <path>：优先入口文件，可重复使用。
• --image <path>：附加图片，可重复使用。
• --session <id>：继续已有会话。
• --reasoning <low|high|max>：特殊情况下覆盖默认思考强度，常规调用不要传递。
• --sandbox <mode>：为新会话显式指定沙箱模式。
• --read-only：创建只读新会话。
• --full-auto：默认的最高权限，可省略；--dangerously-bypass-approvals-and-sandbox 是它的别名。
• --ephemeral：不持久化会话。
• --output-schema <path>：约束最终输出结构。
• --notify：长任务结束后发送通知。
• --output <path>：指定 Markdown 结果路径。

会话约束

续接会话保留原工作区上下文，但包装脚本会再次显式传入最高权限参数。--read-only 和 --sandbox 不能与 --session 同时使用；需要受限权限时开启新会话。续接会话使用本机默认 Codex 配置。

失败处理

• 非零退出码、turn.failed 或明确错误事件都视为失败。
• 失败运行也会输出 result_path 与 events_path；先读取结构化错误和事件尾部，再决定缩小任务、修正配置或续接会话。
• 退出码 137 通常表示进程被中断或终止；先检查资源压力或缩小任务范围，再决定是否重试。
• Skill 或插件加载警告通常不影响任务，除非 Codex 回合本身失败。
• Bash 包装脚本会检测 PTY 支持；不支持时回退到直接执行，任务仍可完成，但进度可能集中在结束时返回。