codex-cli

Codex CLI

ユーザーがこのエージェントに Codex との対話、Codex への相談、コーディング／レビュー／調査タスクの Codex CLI への委任、または Codex による画像生成を依頼した場合に、このスキルを使用します。

基本のインターフェースは次のとおりです。

codex exec "prompt"

自動化では、対話型の codex よりも非対話型の codex exec を優先してください。

最初の確認

Codex CLI を使用する前に、利用可能であることを確認してください。

command -v codex
codex --version
codex exec --help

codex が見つからない場合は、この環境では Codex CLI を利用できないことをユーザーに伝え、そこで終了してください。Codex の応答を捏造してはいけません。

codex exec --help を利用できる場合は、インストールされている CLI のフラグを確認する際の信頼できる情報源として使用してください。Codex CLI は時間とともに変更されます。

単発タスクのワークフロー

通常のタスク委任には、こちらを使用します。

codex exec -C "$PWD" -s read-only "Review this repository and identify likely bugs"

ファイルを編集する可能性のあるタスクでは、ユーザーが指定したサンドボックス、またはホストエージェントが許可するサンドボックスを使用してください。

codex exec -C "$PWD" -s workspace-write "Implement the requested change"

応答ファイルを使用する場合：

codex exec -C "$PWD" -o /tmp/codex-last-message.md "Summarize this project"

機械可読イベントを使用する場合：

codex exec -C "$PWD" --json -o /tmp/codex-last-message.md "Analyze this project"

プロンプトが長い場合は、stdin 経由で渡してください。

codex exec -C "$PWD" - < /tmp/prompt.txt

別のエージェントからのシェルコマンドを使用する際は、ユーザーが明示的に要求していない限り、危険なフラグは避けてください。レビュー、計画、批評、画像生成、分析には read-only を優先してください。

プロンプトの構成

複雑なタスクでは、OpenAI の Codex ベストプラクティスに沿った構成で、委任するプロンプトを作成してください。

Goal:
Context:
Constraints:
Done when:

プロンプトの範囲は 1 つのタスクに限定してください。複雑な実装作業では、まず read-only モードで Codex に計画を依頼し、その計画が承認されてから、別の書き込みタスクを実行してください。

セッションの再開

Codex は、通常の起動出力と、thread.started として出力される JSONL イベントにセッション ID を含めます。

再開するには：

codex exec resume <session-id> "Continue from the previous task"

インストールされている CLI が異なる再開構文に対応している場合は、codex exec resume --help に従ってください。

画像およびファイルの入力

Codex は自分で画像ファイルを閲覧したり読み取ったりできません。Codex に画像を見せるには、-i／--image で明示的に添付してください。これは入力側の機能です。画像生成については、後述の出力側の機能を参照してください。

画像を 1 枚添付する場合：

codex exec -C "$PWD" -s read-only -i screenshot.png "Explain the error shown here"

画像を複数枚添付します。カンマ区切りとフラグの繰り返しのどちらも使用できます。

codex exec -i before.png,after.png "Compare these two UI states"
codex exec -i mock1.png -i mock2.png "Which layout is closer to the spec?"

ベストプラクティス：

• -i フラグはプロンプトテキストより前に置いてください。
• 一般的なラスター形式を使用してください。スクリーンショット／UI には PNG（最適、可逆圧縮）、または JPEG が適しています。画像は適度なサイズにしてください。非常に大きな画像はリクエストの処理を遅くします。
• 画像には、明確なテキスト指示を添えてください。画像だけではコンテキストが不足することがほとんどです。
• 視覚的なレビュー／分析では、Codex が確認のみを行い編集しないよう、-s read-only を併用してください。

画像以外のファイルには添付フラグがありません。方法は 2 つあります。

• Codex がワークスペースからファイルを読み取れるようにします。-C "$PWD" でディレクトリを指定し、プロンプト内でファイル名を示してください（"Review src/auth.ts"）。リポジトリ内にあるファイルには、この方法を使用してください。
• ファイルの内容を stdin 経由で渡します。プロンプトも指定されている場合、stdin の内容は <stdin> ブロックとしてプロンプトに追加されます。

codex exec -C "$PWD" "Summarize the attached log" < /tmp/build.log

画像生成のワークフロー

codex exec 経由で依頼すると、Codex は組み込みの画像生成ツールを使って画像を生成できます。

例：

codex exec "Generate a black banana image with aspect ratio 16:9"

重要な動作：

• 組み込みの画像生成では、通常、ファイルは $CODEX_HOME/generated_images/<codex-session-id>/ の下に保存されます。
• CODEX_HOME が設定されていない場合は、~/.codex/generated_images/<codex-session-id>/ を使用します。
• Codex が最終応答にパスを出力しないことがあります。
• このスキルを使用するエージェントは、画像生成後に生成された画像のパスを積極的に見つけて報告する必要があります。
• PNG のメタデータから正確な画像モデルを特定できない場合があります。Codex の出力、CLI ログ、またはメタデータに明確な根拠がない限り、特定のバックエンドモデルを断定しないでください。

生成された画像を見つける

Codex による画像生成を依頼した後は、返信する前に画像のパスを見つけてください。

利用可能な場合は、まず出力から Codex のセッション ID を取得します。次のような形式です。

session id: 019e8cbf-5054-7131-9440-ee592f0d8a17

次に確認します。

ls -l "${CODEX_HOME:-$HOME/.codex}/generated_images/<session-id>"

セッション ID がわからない場合は、最近生成された画像を一覧表示します。

find "${CODEX_HOME:-$HOME/.codex}/generated_images" -type f -maxdepth 3 -print

可能な場合は、変更時刻で並べ替えてください。

find "${CODEX_HOME:-$HOME/.codex}/generated_images" -type f -maxdepth 3 -print0 \
  | xargs -0 ls -lt

ユーザーがプロジェクトのアセットを求めている場合、権限があれば、生成後に選択した画像をプロジェクト内にコピーまたは移動してください。プロジェクトで参照されるアセットを $CODEX_HOME/generated_images の下だけに置いたままにしないでください。

アスペクト比の確認

ユーザーが特定のアスペクト比を指定した場合は、回答する前に寸法を確認してください。

macOS の場合：

sips -g pixelWidth -g pixelHeight /path/to/image.png

移植性の高い代替方法：

file /path/to/image.png

実際の寸法と、おおよそ一致しているか、正確に一致しているかを報告してください。生成画像の多くは最も近い整数の寸法を使用するため、16:9 のリクエストで 1672 x 941 のような寸法になる場合があります。この場合、実質的には 16:9 ですが、数学的に正確ではありません。

結果の報告

通常の Codex タスクでは、以下を報告してください。

• 使用したコマンド。長い場合は要約してください
• Codex のステータスまたは最終回答
• Codex が変更したファイル（判明している場合）
• 制限事項、エラー、権限不足

画像タスクでは、必ず以下を報告してください。

• 生成画像のパス
• 実際の寸法（確認できる場合）
• パスが $CODEX_HOME 内にあるか、プロジェクトにコピーされているか
• 正確な画像モデルが判明しているかどうか

回答例：

Codex generated the image here:
/Users/me/.codex/generated_images/019e.../ig_....png

Actual size: 1672 x 941, effectively 16:9.
The output does not expose the exact image backend model, so I cannot verify whether it was gpt-image-2.

失敗時の対応

Codex がネットワーク、認証、またはモデルの更新に関するエラーで終了した場合は、エラーを明確に報告し、関連する stderr の行を含めてください。

Codex が画像を生成したと主張しているものの、$CODEX_HOME/generated_images 内に画像ファイルが存在しない場合は、その旨を明示し、パスを捏造しないでください。

ホストエージェントが $CODEX_HOME/generated_images を読み取れない場合は、ユーザーにアクセス権の付与を依頼するか、次のコマンドを実行するよう依頼してください。

find "${CODEX_HOME:-$HOME/.codex}/generated_images" -type f -maxdepth 3 -print0 | xargs -0 ls -lt

安全に関する注意事項

ユーザーが明示的に依頼し、リスクを理解していない限り、秘密情報を Codex に渡さないでください。

相談には read-only を使用してください。Codex にファイルを編集させる場合に限り、workspace-write を使用してください。ユーザーが管理された環境で明示的に要求した場合を除き、danger-full-access は使用しないでください。

Codex の最終メッセージだけを根拠に、Codex が作業を実行したと断言しないでください。ファイルの変更が重要な場合は、実行後にファイルシステムまたは Git の差分を確認してください。