codex

Codex 実行スキル

前提条件

• Codex CLI がインストールされ、設定されていること（~/.codex/config.toml）
• 利用可能か確認する：セッション内で初めて使用する際に codex --version を実行します

ワークフローチェックリスト

Codex のタスクごとに、次の手順に従います：

1. ☐ HPC／Slurm 環境を検出する：

   • HPC クラスター上で実行されているか確認します（/home/woody/、/home/hpc/、Slurm 環境変数を確認）
   • HPC が検出された場合：Landlock サンドボックスの制限を回避するため、必ず --yolo フラグを使用します

2. ☐ AskUserQuestion を使用して、実行パラメーターをユーザーに尋ねる（単一のプロンプト）：

   • モデル：gpt-5、gpt-5-codex、またはデフォルト
   • 推論の強さ：minimal、low、medium、high

3. ☐ タスクに基づいてサンドボックスモードを決定する：

   • read-only：コードレビュー、分析、ドキュメント作成
   • workspace-write：コードの変更、ファイルの作成
   • danger-full-access：システム操作、ネットワークアクセス
   • HPC の場合：Landlock の制限を回避するため、必ず --yolo フラグを追加します

4. ☐ 必須フラグを指定してコマンドを構築する：

   codex exec [OPTIONS] "PROMPT"
   

   必須フラグ：

   • -m <MODEL>（デフォルトを上書きする場合）
   • -c model_reasoning_effort="<LEVEL>"
   • -s <SANDBOX_MODE>（HPC では省略）
   • --skip-git-repo-check（git リポジトリ外の場合）
   • -C <DIRECTORY>（ワークスペースを変更する場合）
   • --full-auto（非対話型実行の場合、--yolo と併用できません）

   HPC コマンドの形式（Landlock を回避するため --yolo を使用）：

   codex exec --yolo -m gpt-5 -c model_reasoning_effort="high" --skip-git-repo-check \
     "Analyze this code: $(cat /path/to/file.py)" 2>/dev/null
   

   注：--yolo は --dangerously-bypass-approvals-and-sandbox のエイリアスであり、Landlock サンドボックスエラーを避けるため、HPC クラスターでは必須です。互換性がないため、--yolo と --full-auto は併用しないでください。

5. ☐ 標準エラー出力を抑制して実行する：

   • 思考トークンを非表示にするため、末尾に 2>/dev/null を追加します
   • ユーザーが詳細な出力またはデバッグを求めた場合に限り削除します

6. ☐ 実行結果を検証する：

   • 終了コードを確認します（0 = 成功）
   • 出力を要約してユーザーに伝えます
   • エラーが発生した場合は、実行可能な解決策とともに報告します
   • HPC で Landlock／サンドボックスエラーが発生した場合：--yolo フラグが使用されたか確認し、指定されていなければ再試行します

7. ☐ 再開機能について伝える：

   • 「いつでもこのセッションを再開できます：codex resume」

コマンドの形式

🔥 HPC のヒント：HPC クラスター（例：/home/woody/、/home/hpc/）では、Landlock サンドボックスエラーを避けるため、必ず --yolo フラグを追加してください。例：codex exec --yolo -m gpt-5 ...

読み取り専用の分析

codex exec -m gpt-5 -c model_reasoning_effort="medium" -s read-only \
  --skip-git-repo-check --full-auto "review @file.py for security issues" 2>/dev/null

標準入力（サンドボックスによるファイル制限を回避）

cat file.py | codex exec -m gpt-5 -c model_reasoning_effort="low" \
  --skip-git-repo-check --full-auto - 2>/dev/null

注：- フラグを使用した標準入力は、すべての Codex CLI バージョンでサポートされているとは限りません。

HPC／Slurm 環境（YOLO モード — Landlock を回避）

Landlock のセキュリティ制限がある HPC クラスター上で実行する場合は、--yolo フラグを使用します：

# Primary solution: --yolo flag bypasses Landlock sandbox
codex exec --yolo -m gpt-5 -c model_reasoning_effort="high" --skip-git-repo-check \
  "Analyze this code: $(cat /path/to/file.py)" 2>/dev/null

代替方法：コードを手動で注入（--yolo が利用できない場合）：

# Capture code content and pass directly in prompt
codex exec -m gpt-5 -c model_reasoning_effort="high" --skip-git-repo-check --full-auto \
  "Analyze this Python code: $(cat file.py)" 2>/dev/null

大きなファイルの場合は、heredoc を使用します：

codex exec --yolo -m gpt-5 -c model_reasoning_effort="high" --skip-git-repo-check "$(cat <<'ENDCODE'
Analyze the following code comprehensively:

$(cat file.py)

Focus on: architecture, algorithms, multi-GPU optimization, potential bugs, code quality.
ENDCODE
)" 2>/dev/null

注：--yolo は --dangerously-bypass-approvals-and-sandbox の短縮形であり、権限が限られている HPC のログインノードでは安全です。互換性がないため、--yolo と --full-auto は併用しないでください。

コードの変更

codex exec -m gpt-5 -c model_reasoning_effort="high" -s workspace-write \
  --skip-git-repo-check --full-auto "refactor @module.py to async/await" 2>/dev/null

セッションの再開

echo "fix the remaining issues" | codex exec --skip-git-repo-check resume --last 2>/dev/null

ディレクトリをまたいだ実行

codex exec -C /path/to/project -m gpt-5 -c model_reasoning_effort="medium" \
  -s read-only --skip-git-repo-check --full-auto "analyze architecture" 2>/dev/null

プロファイルの使用

codex exec --profile production -c model_reasoning_effort="high" \
  --full-auto "optimize performance in @app.py" 2>/dev/null

CLI リファレンス

主なフラグ

フラグ	値	使用する場面
-m, --model	gpt-5、gpt-5-codex	デフォルトのモデルを上書きします
-c, --config	key=value	実行時の設定を上書きします（繰り返し指定可能）
-s, --sandbox	read-only、workspace-write、danger-full-access	実行権限を設定します
--yolo	フラグ	HPC では必須です。すべてのサンドボックス制限を回避します（--dangerously-bypass-approvals-and-sandbox のエイリアスです）。--full-auto とは併用できません
-C, --cd	path	ワークスペースのディレクトリを変更します
--skip-git-repo-check	フラグ	Git リポジトリ外での実行を許可します
--full-auto	フラグ	非対話モード（workspace-write ＋失敗時に承認を求めます）。--yolo とは併用できません
-p, --profile	string	config.toml から設定プロファイルを読み込みます
--json	フラグ	JSON イベントを出力します（CI/CD パイプライン向け）
-o, --output-last-message	path	最終メッセージをファイルに書き込みます
-i, --image	path[,path...]	画像を添付します（繰り返し指定またはカンマ区切り）
--oss	フラグ	ローカルのオープンソースモデルを使用します（Ollama が必要です）

設定オプション

モデルの推論レベル（-c model_reasoning_effort="<LEVEL>"）：

• minimal：短時間で済むタスク、簡単な質問
• low：標準的な操作、定型的なリファクタリング
• medium：複雑な分析、アーキテクチャ上の判断（デフォルト）
• high：重要なコード、セキュリティ監査、複雑なアルゴリズム

モデルの詳細度（-c model_verbosity="<LEVEL>"）：

• low：最小限の出力
• medium：バランスの取れた詳細さ（デフォルト）
• high：詳しい説明

承認プロンプト（-c approvals="<WHEN>"）：

• on-request：ツールを使用する前に毎回
• on-failure：エラー時のみ（--full-auto のデフォルト）
• untrusted：最小限のプロンプト
• never：中断なし（注意して使用してください）

設定管理

設定ファイルの場所

~/.codex/config.toml

実行時の上書き

# Override single setting
codex exec -c model="gpt-5" "task"

# Override multiple settings
codex exec -c model="gpt-5" -c model_reasoning_effort="high" "task"

プロファイルの使用

config.toml で定義します：

[profiles.research]
model = "gpt-5"
model_reasoning_effort = "high"
sandbox = "read-only"

[profiles.development]
model = "gpt-5-codex"
sandbox = "workspace-write"

次のように使用します：

codex exec --profile research "analyze codebase"

再開時の動作

自動的に引き継がれる設定：

• モデルの選択
• 推論レベル
• サンドボックスモード
• 設定の上書き

再開時の構文：

# Resume last session
codex exec resume --last

# Resume with new prompt
codex exec resume --last "continue with next steps"

# Resume via stdin
echo "new instructions" | codex exec resume --last 2>/dev/null

# Resume specific session
codex exec resume <SESSION_ID> "follow-up task"

フラグの挿入（exec と resume の間）：

# Change reasoning effort for resumed session
codex exec -c model_reasoning_effort="high" resume --last

エラー処理

検証ループ

1. コマンドを実行します
2. 終了コードを確認します（0 以外は失敗です）
3. 状況を添えてエラーを報告します
4. AskUserQuestion でユーザーに方針を尋ねます
5. 調整して再試行するか、エスカレーションします

権限のリクエスト

影響の大きいフラグを使用する前に、AskUserQuestion でユーザーの承認を求めます：

• --full-auto：自動実行
• -s danger-full-access：システム全体へのアクセス
• --yolo / --dangerously-bypass-approvals-and-sandbox：
  • HPC クラスター：承認は不要です（操作に必須です）
  • 個人のマシン：承認を求めます（システム全体へのアクセス）

部分的な成功への対応

出力に警告が含まれている場合：

1. 成功した操作を要約します
2. 失敗した操作を状況とともに詳しく説明します
3. AskUserQuestion で次の手順を確認します
4. 具体的な調整案を提示します

トラブルシューティング

ファイルアクセスがブロックされる

症状：「shell is blocked by the sandbox」または権限エラーが表示されます

根本原因：サンドボックスの read-only モードにより、ファイルシステムへのアクセスが制限されています

解決策（優先順位順）：

1. 標準入力からのパイプ（推奨）：

   cat target.py | codex exec -m gpt-5 -c model_reasoning_effort="medium" \
     --skip-git-repo-check --full-auto - 2>/dev/null
   

2. 明示的な権限指定：

   codex exec -m gpt-5 -s read-only \
     -c 'sandbox_permissions=["disk-full-read-access"]' \
     --skip-git-repo-check --full-auto "@file.py" 2>/dev/null
   

3. サンドボックスのアップグレード：

   codex exec -m gpt-5 -s workspace-write \
     --skip-git-repo-check --full-auto "review @file.py" 2>/dev/null
   

無効なフラグのエラー

症状：「unexpected argument '--add-dir' found」と表示されます

原因：そのフラグは Codex CLI に存在しません

解決策：-C <DIR> を使用してディレクトリを変更します：

codex exec -C /target/dir -m gpt-5 --skip-git-repo-check \
  --full-auto "task" 2>/dev/null

終了コードの失敗

症状：明確なメッセージがないまま、0 以外の終了コードが返されます

診断手順：

1. 2>/dev/null を削除して、stderr 全体を確認します
2. インストールを確認します：codex --version
3. 設定を確認します：cat ~/.codex/config.toml
4. 最小限のコマンドをテストします：codex exec -m gpt-5 "hello world"
5. モデルへのアクセスを確認します：codex exec --model gpt-5 "test"

モデルが利用できない

症状：「model not found」または認証エラーが表示される

解決策：

1. 設定済みのモデルを確認します：grep model ~/.codex/config.toml
2. API にアクセスできることを確認します。有効な認証情報が必要です
3. 別のモデルを試します：-m gpt-5-codex
4. OSS にフォールバックします：--oss（Ollama が必要です）

セッションの再開に失敗する

症状：前回のセッションを再開できない

診断手順：

1. 最近のセッションを一覧表示します：codex history
2. セッション ID の形式を確認します
3. 特定の ID の代わりに --last フラグを試します
4. セッションの有効期限が切れていないか、クリーンアップされていないか確認します

HPC／Slurm のサンドボックスエラー

症状：「Landlock sandbox error」、「LandlockRestrict」、またはすべてのファイル操作が失敗する

根本原因：HPC クラスターでは、Codex のデフォルトのサンドボックスをブロックする Landlock／seccomp カーネルセキュリティモジュールが使用されています

✅ 解決策：--yolo フラグを使用します（優先順）：

1. YOLO フラグ（主な解決策 — HPC で動作します）：

   # Bypasses Landlock restrictions completely
   codex exec --yolo -m gpt-5 -c model_reasoning_effort="high" --skip-git-repo-check \
     "Analyze this code: $(cat /full/path/to/file.py)" 2>/dev/null
   

   動作する理由：--yolo（--dangerously-bypass-approvals-and-sandbox のエイリアス）は Codex のサンドボックスを完全に無効化し、HPC システムでファイルに直接アクセスできるようにします。注：--full-auto と --yolo は互換性がないため、併用しないでください。

2. コードの手動挿入（--yolo が利用できない場合の代替策）：

   # Pass code directly in prompt via command substitution
   codex exec -m gpt-5 -c model_reasoning_effort="high" --skip-git-repo-check --full-auto \
     "Analyze this code comprehensively: $(cat /full/path/to/file.py)" 2>/dev/null
   

3. 長いコードにはヒアドキュメントを使用：

   codex exec --yolo -m gpt-5 -c model_reasoning_effort="high" --skip-git-repo-check "$(cat <<'EOF'
   Analyze the following Python code for architecture, bugs, and optimization opportunities:
   
   $(cat /home/user/script.py)
   
   Provide technical depth with actionable insights.
   EOF
   )" 2>/dev/null
   

4. ログインノードで実行（コンピュートノードが外部への接続をブロックする場合）：

   # SSH to login node first, then run codex there (not in Slurm job)
   ssh login.cluster.edu
   codex exec --yolo -m gpt-5 --skip-git-repo-check "analyze @file.py" 2>/dev/null
   

5. Apptainer／Singularity を使用（クラスターがサポートしている場合）：

   # Build image with Codex installed, then run via Slurm
   singularity exec codex.sif codex exec --yolo -m gpt-5 "task"
   

HPC でのベストプラクティス：

• HPC クラスターでは必ず --yolo フラグを使用してください。すでに権限が制限されているログインノードでは安全です
• ログインノードで分析を実行し、計算負荷の高いジョブのみ Slurm に送信します
• ログインノードから読み取り可能な共有ファイルシステムにコードファイルを置きます
• --yolo と $(cat file.py) を組み合わせると、互換性を最大限に高められます

ベストプラクティス

推論レベルの選択

• minimal：構文の修正、簡単な名前変更
• low：標準的なリファクタリング、基本的な分析
• medium：複雑なリファクタリング、アーキテクチャのレビュー
• high：セキュリティ監査、アルゴリズムの最適化、重大なバグ

サンドボックスモードの選択

• read-only：あらゆる分析やレビューでのデフォルト
• workspace-write：ファイルの変更のみ
• danger-full-access：ネットワーク操作、システムコマンド（まれに使用）

標準エラー出力の抑制

• 次の場合を除き、常に 2>/dev/null を使用します：
  • ユーザーが思考トークンを明示的に要求した場合
  • 失敗したコマンドをデバッグする場合
  • 設定の問題をトラブルシューティングする場合

プロファイルの使用

よく使うワークフロー向けにプロファイルを作成します：

• review：高い推論レベル、読み取り専用
• refactor：中程度の推論レベル、ワークスペースへの書き込み
• quick：低い推論レベル、読み取り専用
• security：高い推論レベル、ワークスペースへの書き込み

標準入力とファイル参照

• 標準入力：単一ファイルの分析に使用し、権限の問題を回避します
• ファイル参照：複数ファイルのコンテキストや、コードベース全体にわたる変更に使用します

安全ガイドライン

HPC クラスター — --yolo は安全で、必須です：

• HPC のログインノードでは、すでに厳格な権限（root アクセスなし、ネットワーク変更なし）が設定されています
• --yolo は Codex のサンドボックスをバイパスしますが、HPC ユーザーとしての制限内で引き続き動作します
• Landlock エラーを避けるため、HPC では必ず --yolo を使用してください

通常の使用 — 注意してください：

• 制限のないシステム（個人のノート PC、完全な sudo 権限を持つクラウド VM）では --yolo を使用しないでください
• 通常の開発では --full-auto と -s workspace-write の併用を推奨します

次の操作を行う前に必ず確認してください：

• （HPC 以外で）danger-full-access サンドボックスを使用する
• 本番システムで承認プロンプトを無効化する
• sudo 権限を持つ個人用マシンで --yolo を実行する

次の場合はユーザーの承認を得てください：

• workspace-write を初めて使用する
• システム全体へのアクセスを要求する
• 破壊的な操作（削除、移行）を行う

高度な使用方法

CI/CD との統合

codex exec --json -o result.txt -m gpt-5 \
  -c model_reasoning_effort="medium" \
  --skip-git-repo-check --full-auto \
  "run security audit on changed files" 2>/dev/null

バッチ処理

for file in *.py; do
  cat "$file" | codex exec -m gpt-5 -c model_reasoning_effort="low" \
    --skip-git-repo-check --full-auto "lint and format" - 2>/dev/null
done

複数ステップのワークフロー

# Step 1: Analysis
codex exec -m gpt-5 -c model_reasoning_effort="high" -s read-only \
  --full-auto "analyze @codebase for architectural issues" 2>/dev/null

# Step 2: Resume with changes
echo "implement suggested refactoring" | \
  codex exec -s workspace-write resume --last 2>/dev/null

エスカレーションするタイミング

トラブルシューティング後もエラーが続く場合：

1. ドキュメントを確認する：

   WebFetch https://developers.openai.com/codex/cli/reference
   

   WebFetch https://developers.openai.com/codex/local-config#cli
   

2. ユーザーに報告する：

   • エラーメッセージの原文
   • 試した解決策
   • 設定の詳細
   • 終了コードと stderr の出力

3. ガイダンスを求める：

   • 代替アプローチ
   • 設定の調整
   • 手動での介入が必要な箇所

モデル選択ガイド

タスクの種類	推奨モデル	推論の労力
素早い構文修正	gpt-5	最小
コードレビュー	gpt-5	中
リファクタリング	gpt-5-codex	中
アーキテクチャ分析	gpt-5	高
セキュリティ監査	gpt-5	高
アルゴリズムの最適化	gpt-5-codex	高
ドキュメントの生成	gpt-5	低

よくあるワークフロー

コードレビューのワークフロー

1. ユーザーにモデルと推論の労力を尋ねます
2. 読み取り専用で分析を実行します
3. 調査結果を提示します
4. 変更が必要な場合：workspace-write で再開します
5. 変更を検証します
6. 再開できることを伝えます

リファクタリングのワークフロー

1. ユーザーにモデルと推論の労力を尋ねます
2. 現在のコードを分析します（読み取り専用）
3. 変更案を提示します
4. ユーザーの承認を得ます
5. 変更を適用します（workspace-write）
6. 検証／テストを実行します
7. 結果を報告します

セキュリティ監査のワークフロー

1. 高い推論の労力を使用します
2. 包括的な分析を実行します（読み取り専用）
3. 調査結果を記録します
4. 修正案を提示します
5. 承認された場合は修正を適用します（workspace-write）
6. 再監査して検証します
7. レポートを作成します