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 コマンドを作成しないでください。ユーザーのテキストには引用符、置換構文、改行が含まれる場合があります。シェルによるプロンプト内容の再解釈を防ぐため、引用符で囲んだヒアドキュメントを推奨します。

(
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 を追加する前に確認
会話形式のタスクを再開	元の設定を引き継ぐ	引用符で囲んだヒアドキュメント経由で codex exec resume --last
別のディレクトリから実行	タスクの要件に応じて選択	-C <DIR> とその他のフラグ

バッチコストゲート

類似したモデル呼び出しを複数回行う前に、次の手順を実行します。

1. レコード数、モデル呼び出し回数、実時間、チェックポイントの間隔について、小さなキャリブレーション上限を定めます。ユーザーがこの範囲内のキャリブレーションすら許可していない場合は、まず確認します。
2. その上限内で、代表的なキャリブレーション用の処理単位を1つ、--json を使って実行します。
3. レコード数だけから推定せず、JSONL イベントストリームから実際の使用量を測定します。
4. 測定した処理単位に基づいて、残りの呼び出し回数とトークン数を予測します。
5. 全実行の最大呼び出し回数、最大レコード数、実時間の予算、チェックポイントの間隔を示します。
6. 予測される全実行の規模がキャリブレーションを大幅に上回る場合、またはユーザーがその具体的な予算をすでに許可していない場合は、確認を求めます。

測定した使用量が予測を超えた場合は、各チェックポイントで停止します。キャッシュされた入力もトークン使用量に含まれます。キャッシュ入力の割合が高い場合、通常は、同じ大きなプレフィックスや蓄積されたセッションコンテキストが繰り返し送信されていることを意味し、実行に費用がかからないわけではありません。

続きの作業

• 過去の会話コンテキストが必要な場合に限り、再開します。独立したレコードの場合は、その処理単位に必要な指示と、簡潔な成果物のみを渡します。
• 費用のかかる次の処理単位を提案する前に、モデル、推論の労力、サンドボックス、測定済みの使用量、残りの予算を改めて示します。
• 要求された 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 は、重要な cwd/worktree のガードを回避します。デフォルトではなく、境界の例外として扱ってください。
• danger-full-access と --dangerously-* のバイパスフラグは、影響の大きいモードです。全アクセスを検討する前に、まず read-only、次に workspace-write、その次にインストール済み CLI が明示するモードを優先し、その後、個別の --add-dir による許可を検討してください。
• プロンプトがユーザーまたは別のモデルから提供された場合は、stdin またはすでに引用符で囲んだ単一の CLI 引数として渡します。シェル文字列に埋め込んではいけません。
• stderr を抑制すると、失敗や進行状況を示す証拠が隠れます。stderr をすべて親に貼り付けるとコンテキストを浪費します。保存してから、範囲を絞った末尾部分を確認してください。
• 出力が少なくても、実行のコストが低いとは限りません。大きなキャッシュ済みプレフィックスが繰り返されると、短い呼び出しが多数ある場合でも使用量の大部分を占めることがあります。