codex

Codex 技能指南

操作约定

1. 首先运行 codex --version 和 codex exec --help。如果 Codex 不可用，请停止；并且只能使用已安装 CLI 显示的标志。
2. 如果用户未指定模型或推理力度，请使用已安装版本的默认设置。不要硬编码模型列表；模型名称和支持的推理级别会随时间变化。
3. 选择所需的最小沙盒：检查时使用 --sandbox read-only，按要求进行本地编辑时使用 --sandbox workspace-write。网络访问、额外可写目录以及更宽泛的模式都需要单独授权。
4. 使用受支持的选项组装命令，例如：
   • -m, --model <MODEL>
   • --config model_reasoning_effort="<LEVEL>"
   • --sandbox <read-only|workspace-write|danger-full-access>
   • -C, --cd <DIR>
   • --add-dir <DIR>
   • --json
   • --ephemeral
   • --skip-git-repo-check
   • --dangerously-bypass-approvals-and-sandbox
5. 默认不要使用 --skip-git-repo-check。只有当用户明确要求在 Git 仓库之外运行，或已批准此命令绕过该边界时，才使用它。
6. 不要使用 --full-auto 等已弃用的兼容性快捷选项；请使用当前帮助信息中列出的明确沙盒选项。
7. 保留 stderr。将其写入有大小限制的文件中，避免将其放入父级上下文；只读取退出状态、简短末尾内容或针对性诊断信息。绝不要将其重定向到 /dev/null。
8. 对于自动化、批量工作、成本调查，或任何需要衡量用量的运行，请添加 --json，并将 stdout 保存为 JSONL。读取最终用量事件；如果其中包含相关信息，请报告输入、缓存输入、输出和推理令牌数。
9. 使用监管运行时强制设置硬性墙钟超时。遇到非零退出或超时时立即停止；不要自动重试高成本运行。
10. 继续真正的对话任务时，通过 stdin 使用 codex exec resume --last。不要为同质记录批次恢复会话；每个批次段都应启动全新且受限的 --ephemeral 运行，以免每次模型调用都重新发送累积的历史记录。

安全传递提示词

不要使用 echo "user prompt" | ... 来构建 Codex 命令；用户文本可能包含引号、替换内容或换行符。优先使用带引号的 heredoc，这样 shell 就不会重新解释提示词内容：

(
for required_command in python3 head wc mkfifo; do
  command -v "$required_command" >/dev/null 2>&1 || {
    printf 'Missing required command: %s\n' "$required_command" >&2
    exit 127
  }
done
codex_skill_dir=${CODEX_SKILL_DIR:-$HOME/.claude/skills/codex}
[ -f "$codex_skill_dir/scripts/run_with_timeout.py" ] || {
  printf 'Missing Codex timeout helper: %s\n' \
    "$codex_skill_dir/scripts/run_with_timeout.py" >&2
  exit 1
}
codex_artifacts=$(mktemp -d) || exit 1
codex_stderr_max_bytes=1048576
codex_stderr_pipe="$codex_artifacts/stderr.pipe"
mkfifo "$codex_stderr_pipe" || exit 1
head -c "$codex_stderr_max_bytes" <"$codex_stderr_pipe" \
  >"$codex_artifacts/stderr.log" &
codex_stderr_limiter_pid=$!
if python3 "$codex_skill_dir/scripts/run_with_timeout.py" 1800 \
  codex exec resume --last \
  2>"$codex_stderr_pipe" <<'EOF'
Your follow-up prompt goes here.
EOF
then
  codex_status=0
else
  codex_status=$?
fi
stderr_limiter_status=0
wait "$codex_stderr_limiter_pid" || stderr_limiter_status=$?
rm -- "$codex_stderr_pipe" || exit 1
artifact_status=0
stderr_bytes=$(wc -c <"$codex_artifacts/stderr.log") || exit 1
if [ "$stderr_bytes" -ge "$codex_stderr_max_bytes" ]; then
  printf 'Codex stderr reached its %s-byte artifact limit\n' \
    "$codex_stderr_max_bytes" >&2
  artifact_status=125
fi
if [ "$stderr_limiter_status" -ne 0 ]; then artifact_status=$stderr_limiter_status; fi
tail -c 4000 -- "$codex_artifacts/stderr.log"
tail_status=$?
if [ "$codex_status" -eq 0 ] && [ "$artifact_status" -eq 0 ] && [ "$tail_status" -eq 0 ]; then
  rm -R -- "$codex_artifacts" || exit $?
else
  printf 'Codex artifacts retained: %s\n' "$codex_artifacts" >&2
fi
if [ "$codex_status" -ne 0 ]; then exit "$codex_status"; fi
if [ "$artifact_status" -ne 0 ]; then exit "$artifact_status"; fi
exit "$tail_status"
)

快速参考

用例	沙盒模式	关键标志
只读审查或分析	read-only	--sandbox read-only
应用本地编辑	workspace-write	--sandbox workspace-write
应用需要网络访问的编辑	workspace-write 加配置	获得批准后使用 --sandbox workspace-write -c 'sandbox_workspace_write.network_access=true'
机器可读的用量信息	与任务匹配	使用 --json；将 JSONL 格式的 stdout 和 stderr 分别保存
独立批次段	与任务匹配	使用 --ephemeral --json；不要恢复上一批次段
允许额外写入范围	优先使用 --add-dir	添加额外可写目录前先征求许可
允许广泛访问文件	仅在获得批准后使用 danger-full-access	添加 --sandbox danger-full-access 前先征求许可
恢复对话任务	继承原设置	通过带引号的 heredoc 使用 codex exec resume --last
从其他目录运行	根据任务需要选择	使用 -C <DIR> 加其他标志

批量成本关卡

在进行多次类似的模型调用之前：

1. 为记录数、模型调用次数、实际耗时和检查点频率设定较小的校准上限；如果用户尚未授权进行哪怕是这种有界校准的操作，请先征求确认。
2. 在该上限内，使用 --json 运行一个有代表性的校准批次。
3. 根据 JSONL 事件流测量实际用量；不要仅根据记录数估算。
4. 根据测得的批次用量，推算剩余调用次数和 Token 数。
5. 说明完整运行的最大调用次数、最大记录数、实际耗时预算和检查点频率。
6. 如果推算出的完整运行规模明显大于校准规模，或用户尚未授权该具体预算，请征求确认。

如果测得的用量超过推算值，请在每个检查点停止。缓存输入仍属于 Token 用量：缓存输入占比高，通常意味着相同的大型前缀或累积的会话上下文被反复发送，而不是运行不耗费资源。

后续跟进

• 只有在需要先前对话上下文时才恢复运行。对于相互独立的记录，只传递该批次所需的指令和精简材料。
• 在提出另一个高成本批次之前，重述模型、推理力度、沙盒、测得的用量和剩余预算。
• 达到所请求的 done_when 条件即结束运行。遇到阻碍并不代表获得了安装、升级、重启服务、迁移或重新索引数据、编辑全局配置/钩子、写入其他仓库或执行 GitHub 写入操作的许可，除非当前请求明确授权了该操作。

错误处理

• 如果 codex --version 或 codex exec 命令以非零状态码退出，请停止并报告失败；重试前先征求指示。
• 使用高影响标志（--sandbox danger-full-access、--dangerously-bypass-approvals-and-sandbox、--dangerously-bypass-hook-trust、--skip-git-repo-check）之前，请使用 AskUserQuestion 征求用户许可，除非用户此前已授权。
• 如果输出包含警告、部分结果、用量缺失或超时，请保留相关证据并询问如何调整。不要悄悄改为不计量或范围更大的运行。

注意事项

• --skip-git-repo-check 会绕过重要的当前工作目录/工作树保护。应将其视为边界例外，而不是默认选项。
• danger-full-access 和 --dangerously-* 绕过标志都是高影响模式。优先使用 read-only，其次是 workspace-write，然后是已安装 CLI 明确列出的模式，再考虑通过具体的 --add-dir 授权，最后才考虑完全访问权限。
• 如果提示词来自用户或其他模型，请通过标准输入传递，或作为一个已正确引用的 CLI 参数传递。绝不要将其插入 shell 字符串。
• 隐藏 stderr 会丢失失败和进度证据；将所有 stderr 粘贴到上级会话则会浪费上下文。请保存 stderr，然后检查限定长度的末尾内容。
• 输出很少并不意味着运行成本低。反复发送的大型缓存前缀可能会让许多短调用的总用量居高不下。