以下の内容はhttps://kafkafinancialgroup.hatenablog.com/entry/2025/04/20/112026より取得しました。

OpenAI Codex CLI

 

OpenAI Codex CLI ドキュメント

バージョン: 1.0.0 (2025年4月現在)
リポジトリ: https://github.com/openai/codex

目次

  1. 概要

  2. はじめに

  3. 基本的な使い方

  4. 主要機能

  5. 高度な使い方

  6. セキュリティモデル詳細

  7. ベストプラクティス

  8. トラブルシューティング / FAQ

  9. コントリビューション (貢献)

  10. 結論

1. 概要

OpenAI Codex CLIは、ターミナル上で動作する軽量なAIコーディングエージェントです。開発者が自然言語で指示を与えることで、コードの生成、修正、実行、ファイル操作などを効率的に行うことを支援します。OpenAIの最新モデル (o3, o4-miniなど) を活用し、開発者の生産性を大幅に向上させることを目的として設計されたオープンソースツールです。

主な特徴:

  • ターミナルネイティブな操作感

  • 自然言語によるコード生成・修正

  • 安全なサンドボックス環境でのコード実行

  • リポジトリ内のファイル読み書き、パッチ適用

  • 柔軟な承認モードによる権限管理

  • マルチモーダル入力対応 (画像からのコード生成)

  • プロジェクト固有のコンテキストや指示の利用

  • オープンソースによる透明性と拡張性

2. はじめに

システム要件

  • OS:

  • Node.js: v22 以上 (LTS推奨)

  • Git: v2.23 以上 (必須ではないが強く推奨)

  • RAM: 4GB以上 (8GB以上推奨)

インストール

Node.jsパッケージマネージャー (npm, yarn, pnpm, bun) を使用してグローバルにインストールします。

# npm (推奨) npm install -g @openai/codex # yarn # yarn global add @openai/codex # pnpm # pnpm add -g @openai/codex # bun # bun install -g @openai/codex

注意: sudo を使用してグローバルインストールすることは推奨されません。パーミッションエラーが発生する場合は、npmの権限設定を見直してください。

初期設定 (APIキー)

Codex CLIを使用するにはOpenAI APIキーが必要です。以下のいずれかの方法で設定します。

  1. 環境変数 (推奨):
    現在のターミナルセッションで設定:

    export OPENAI_API_KEY="sk-..."

    永続的に設定するには、シェルの設定ファイル (~/.zshrc, ~/.bashrc, ~/.profile など) に上記の export 行を追加してください。

  2. .env ファイル:
    プロジェクトのルートディレクトリに .env という名前のファイルを作成し、以下のように記述します。

    text
    OPENAI_API_KEY=sk-...

    CLIは自動的に .env ファイルを読み込みます。.env ファイルを .gitignore に追加することを忘れないでください。

3. 基本的な使い方

対話モード (REPL)

最も基本的な使い方です。ターミナルで codex と入力すると、対話モードが開始されます。

codex

プロンプトを入力してEnterキーを押すと、Codexが応答します。初期プロンプトを指定して開始することも可能です。

codex "Reactのクラスコンポーネントを関数コンポーネントにリファクタリングして"

対話モードを終了するには Ctrl+C を押します。

非対話モード

スクリプトやパイプラインでの利用に適しています。-q または --quiet フラグを使用します。

# ファイルの内容を説明させる (標準出力へ) codex -q "utils.ts ファイルの概要を説明して" # JSON形式で出力 codex -q --json "この正規表現 ^(?=.*[A-Z]).{8,}$ の意味を解説して"

主要なコマンドラインフラグ

  • -m, --model <モデル名>: 使用するAIモデルを指定します (デフォルト: o4-mini)。例: -m o3

  • -a, --approval-mode <モード>: 承認モードを指定します (suggest, auto-edit, full-auto)。デフォルトは suggest です。詳細はセキュリティモデル詳細を参照してください。

  • -q, --quiet: 非対話モードで実行し、UIを表示しません。

  • --json: 非対話モード時に出力をJSON形式にします。

  • --notify: レスポンス完了時にデスクトップ通知を表示します。

  • --image <ファイルパス>: 画像ファイルを入力として渡します (マルチモーダル)。

  • --help: ヘルプメッセージを表示します。

シェル補完

コマンドやフラグの補完を有効にするスクリプトを生成できます。

# bashの場合 codex completion bash >> ~/.bash_completion source ~/.bash_completion # zshの場合 codex completion zsh > "${fpath[1]}/_codex" autoload -U compinit && compinit

4. 主要機能

自然言語からのコード生成

プロンプトで与えられた指示に基づき、コードスニペット、関数、クラス、テストケースなどを生成します。

codex "Pythonで現在時刻をISO 8601形式で取得する関数を書いて"

コード実行 (サンドボックス)

生成されたコードやシェルコマンドを安全なサンドボックス環境で実行できます。full-auto モード以外では、実行前にユーザーの承認が必要です。

ファイル操作

リポジトリ内のファイルを読み取り、内容に基づいてコードを生成したり、生成されたコードでファイルを修正したりできます (パッチ適用または直接書き込み)。

codex "src/components/Header.tsx のスタイルを修正して、背景色を #FAFAFA に変更して"

セキュリティと承認モード

ユーザーがエージェントの自律性を制御できるよう、3つの承認モードを提供します。

  • suggest (デフォルト): ファイル読み取りは許可。書き込みやコマンド実行は都度承認。

  • auto-edit: ファイル読み書き (パッチ適用) は許可。コマンド実行は承認必要。

  • full-auto: ファイル読み書き、コマンド実行は自動。ネットワーク無効、ディレクトリ制限あり。

詳細はセキュリティモデル詳細を参照してください。

マルチモーダル入力 (画像)

--image フラグで画像ファイルを指定し、その内容に基づいたタスクを依頼できます。

codex --image ./design_mockup.png "このデザインに合わせたReactコンポーネントを作成して"

プロジェクトコンテキストの利用

Codexは以下の順序でMarkdownファイルを読み込み、コンテキストとして利用します。

  1. ~/.codex/instructions.md: グローバルな個人設定

  2. リポジトリルートの codex.md: プロジェクト共通のルールやノート

  3. カレントディレクトリの codex.md: サブパッケージ固有の設定

これにより、プロジェクトのコーディング規約や背景情報をモデルに伝え、より適切な出力を得られます。

5. 高度な使い方

設定ファイル

~/.codex/config.yaml または ~/.codex/config.json に設定を記述することで、デフォルトの挙動をカスタマイズできます。

例 (config.yaml):

text
model: o4-mini # デフォルトモデル approvalMode: suggest # デフォルト承認モード notify: true # デスクトップ通知を有効化 safeCommands: # 自動承認するコマンドリスト - npm test - yarn lint - git status # 外部モデルプロバイダー設定 (例: Gemini) # providers: # - name: gemini # model: gemini-2.5-pro-preview-03-25 # api_key_env: GOOGLE_API_KEY

カスタム指示

~/.codex/instructions.md にMarkdown形式でカスタム指示を記述できます。常に守ってほしいルールや、応答スタイルなどを指定します。

例 (instructions.md):

text
# 私のカスタム指示 - 応答には常に絵文字を1つ以上含めてください。😄 - コードを生成する際は、必ずコメントを追加してください。 - git コマンドは、明示的に指示された場合のみ使用してください。 - TypeScript を優先的に使用してください。

CI/CDパイプラインでの利用

非対話モード (-q) と適切な承認モード (auto-edit または full-auto) を組み合わせることで、CI/CDプロセスに組み込めます。

例 (GitHub Actions):

text
name: Codex Auto Task on: [push] jobs: codex_job: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - uses: actions/setup-node@v3 with: node-version: '22' - name: Install Codex CLI run: npm install -g @openai/codex - name: Run Codex Task run: codex -a auto-edit -q "README.mdの変更点をCHANGELOG.mdに追記して" env: OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} CODEX_QUIET_MODE: 1 # 更にUI出力を抑制 # 必要に応じて変更をコミット・プッシュするステップを追加

デバッグとトレース

詳細なログ（APIリクエスト/レスポンスなど）を表示するには、DEBUG 環境変数を設定します。

DEBUG=true codex "この関数のバグを見つけて修正して"

Nix Flake開発サポート

Nix Flakeを使用している場合、nix develop で開発シェルに入り、依存関係のインストールやビルド、codex コマンドの実行が可能です。nix run .#codex で直接実行することもできます。

6. セキュリティモデル詳細

承認モード詳解

  • suggest (デフォルト): 最も安全なモード。エージェントはリポジトリ内のファイルを読み取れますが、ファイルの書き込み（パッチ適用含む）やシェルコマンドの実行には、常にユーザーの明示的な承認（y または n）が必要です。ネットワークアクセスは許可されます。

  • auto-edit: ファイルの読み取りと書き込み（パッチ適用）が自動的に許可されます。ただし、任意のシェルコマンドの実行には依然としてユーザーの承認が必要です。ネットワークアクセスは制限される場合があります。Git管理されていないディレクトリで実行すると警告が出ます。

  • full-auto: 最も自律的なモード。ファイルの読み書きとシェルコマンドの実行がすべて自動で行われます。ただし、このモードではセキュリティが最優先され、すべてのコマンドはネットワークアクセスが無効化され、カレントワーキングディレクトリとそのサブディレクトリ内に制限されたサンドボックス環境で実行されます。 意図しない操作を防ぐための強力な安全装置です。Git管理されていないディレクトリで実行すると警告が出ます。

サンドボックス化の仕組み

  • macOS (12+): Apple Seatbelt (sandbox-exec) を使用し、プロセスを厳格なサンドボックスに入れます。ファイルシステムアクセスは基本的に読み取り専用で、一部の必要な書き込みパスのみが許可されます。ネットワークアクセスは full-auto モードでは完全にブロックされます。

  • Linux: デフォルトではサンドボックス化されません。安全のため、Dockerコンテナ内でCodex CLIを実行することが推奨されます。リポジトリにDocker設定例が含まれています。full-auto モードでは、ネットワークアクセスをブロックしようと試みますが、OSレベルの厳密なサンドボックスは提供されません。

  • Windows (WSL2): Linuxと同様の挙動になります。Docker Desktop for Windowsとの連携が推奨されます。

APIキー管理ベストプラクティス

  • APIキーをコードリポジトリに絶対にコミットしないでください。

  • 環境変数または .env ファイル（.gitignore に追加）を使用してください。

  • 可能であれば、用途ごとに異なるAPIキーを使用し、定期的にローテーションしてください。

  • CI/CD環境では、GitHub Secretsなどのシークレット管理機能を使用してください。

  • 公開リポジトリやクライアントサイドコードにはAPIキーを含めないでください。

7. ベストプラクティス

効果的なプロンプト設計

  • 明確な指示: 何をしてほしいかを具体的に記述します。「〇〇を修正して」ではなく「〇〇関数の引数に型アノテーションを追加して」のように。

  • コンテキストの提供: 関連するファイル名、関数名、使用しているライブラリやフレームワーク、バージョンなどを指定します。

  • 構造化: 複雑なタスクは、### やマークダウンで見出しを使い、要件、制約、手順などを分けて記述します。

  • 出力形式の指定: 期待するコードの形式（例: 「JSON形式で結果を返す関数」）や、特定のスタイルガイド（例: 「PEP 8に準拠して」）を指示します。

  • 反復的な改善: 最初から完璧を求めず、生成されたコードに対して「変数名を〇〇に変更して」「エラーハンドリングを追加して」のように追加指示を与えて改善します。

モデル選択の指針

  • o4-mini (デフォルト): 速度と性能のバランスが取れており、ほとんどの日常的なタスクに適しています。

  • o3: より複雑な推論や高度なコード生成が必要な場合に使用します。応答速度は o4-mini より遅くなる可能性があります。

  • 他のGPTモデル (gpt-4, gpt-4-turbo など): --model フラグで指定可能ですが、Codex CLIの特定の機能（ファイル操作など）との相性はモデルによって異なる場合があります。

安全な運用

  • suggest モードの活用: 特に慣れないうちは、デフォルトの suggest モードを使用し、すべての変更とコマンド実行を確認してください。

  • Gitによる変更追跡: 常にGitリポジトリ内で作業し、Codexによる変更をコミット前に git diff で確認し、問題があれば元に戻せるようにします。

  • full-auto モードの慎重な利用: このモードは強力ですが、意図しない変更を引き起こす可能性もあります。信頼できるタスクや、影響範囲が限定的な場合にのみ使用してください。

  • 機密情報: プロンプトにAPIキー、パスワード、個人情報などの機密データを含めないでください。

8. トラブルシューティング / FAQ

  • Q: Zero Data Retention (ZDR) が有効な組織で使えますか？
    A: 現在サポートされていません。Codex CLIは内部的に store:true を使用するResponses APIに依存しており、ZDR組織ではこれが許可されていないためエラーが発生します。将来的に対応される可能性があります。

  • Q: 2021年のCodexモデルとは違うのですか？
    A: はい、異なります。元のCodexモデルAPIは2023年3月に廃止されました。このCodex CLIは、新しいアーキテクチャとモデル (o3, o4-miniなど) をベースにした新しいツールです。

  • Q: o3 や o4-mini が使えません。
    A: APIアカウントがこれらのモデルを利用するために検証が必要な場合があります。OpenAIのプラットフォーム設定を確認してください。

  • Q: 間違ったファイルを編集しそうです。どうすれば止められますか？
    A: suggest または auto-edit モードでは、ファイル変更やコマンド実行の前に確認プロンプトが表示されます。n を入力して拒否してください。モデルにフィードバックを与えることも可能です。full-auto モードでは自動実行されるため、事前の確認が重要です。

9. コントリビューション (貢献)

OpenAI Codex CLIはオープンソースプロジェクトであり、コミュニティからの貢献を歓迎します。

開発ワークフロー

  1. main ブランチから新しいトピックブランチを作成します (例: feat/add-new-feature)。

  2. 変更を加え、関連するテストを追加・更新します。

  3. 開発中は pnpm test:watch で高速なフィードバックを得られます。

  4. プッシュする前に、npm test && npm run lint && npm run typecheck を実行して、すべてのチェックをパスすることを確認します。

  5. プルリクエストを作成します。

コード品質:

  • テスト: Vitest

  • スタイル: ESLint + Prettier (Huskyによるプリコミットフックで自動フォーマット)

  • 型チェック: TypeScript (Huskyによるプリプッシュフックでチェック)

貢献者ライセンス契約 (CLA)

初めて貢献する場合、プルリクエストに以下のコメントを追加してCLAに署名する必要があります。

text
I have read the CLA Document and I hereby sign the CLA

CLA-Assistantボットが署名を確認します。

10. 結論

OpenAI Codex CLIは、ターミナル環境でAIの力を活用し、開発ワークフローを効率化するための強力なツールです。自然言語による指示、安全なコード実行、ファイル操作、プロジェクトコンテキストの理解など、多彩な機能を提供します。

オープンソースとして開発されており、コミュニティと共に進化していくことが期待されます。セキュリティに配慮した設計となっていますが、ユーザーは各承認モードの挙動を理解し、責任を持って利用することが重要です。

このツールを効果的に活用することで、開発者は反復的な作業から解放され、より創造的で本質的なタスクに集中できるようになるでしょう。

Perplexity の Eliot より: pplx.ai/share



以上の内容はhttps://kafkafinancialgroup.hatenablog.com/entry/2025/04/20/112026より取得しました。
このページはhttp://font.textar.tv/のウェブフォントを使用してます
不具合報告/要望等はこちらへお願いします。
モバイルやる夫Viewer Ver0.14