OpenAI Codex CLI : セットアップと基本操作

概要

openai の CLI coding agent codex を簡単に使用してみる
コーディングに

前提条件

• mac m3 sequoia
• openai の api key を必要とする

システム要件

• macOS 12+, Ubuntu 20.04+/Debian 10+, or Windows 11 via WSL2
• Node.js 22 or newer (LTS recommended)
• Git (optional, recommended) 2.23+ for built-in PR helpers
• RAM 4-GB minimum (8-GB recommended)

openai api key を準備

openai の platform から api key を作成し控える

api には rate limit が設定されており, tier2 未満では limit に達しやすい.
tier2 にするには 50$ 課金及び, 初めての課金から一週間経過している必要がある.
tier2~3 程をお勧めする. 数時間利用すれば 20 ~ 30 $ くらいは消費する.

api key を設定

.bash_profile などに api key を設定する

export OPENAI_API_KEY=xxxxxxxx

install

npm install -g @openai/codex
# or
yarn global add @openai/codex

実行方法

シンプルに起動

codex

上記で chat interface が起動する
git init 済みの directory で実行する必要がある. 問題がある場合は起動直後に以下の警告が表示される

model を指定

codex -m gpt-4.1-mini

任意のプロンプト (context) をファイルから与える

codex --project-doc ~/bank/xxxx.md

image ファイルの読み込み

codex -i ~/bank/ui.jpg

wireframe の画像を元に html を作成するなどが可能

設定関連

config file

codex を一度起動し, 以下を開く.

~/.codex/config.json

最初はほぼ空の状態だが, codex が自動で書き込む場合もある

{
  "model": "gpt-4.1-mini",
  "approvalMode": "auto-edit",
  "history": {
    "maxSize": 1000,
    "saveHistory": true,
    "sensitivePatterns": []
  }
}

config : approvalMode

実行時の permission 設定となる. 制限を強くすると対話する際に, 承認を求めてくる頻度が上がる.

• Suggest (提案モード): ファイル読み取りは自由、書き込みやコマンド実行は承認が必要。
• Auto Edit (自動編集モード): ファイルの読み取りと編集は自動、コマンド実行は承認が必要。
• Full Auto (完全自動モード): ファイル読み取り/書き込み、制限付きでのコマンド実行ともに自由

context の読み込み

codex は以下の順序でファイルから context を読み込む.
これらを使い分け全体, リポジトリ毎のルールや context を管理する.

- ~/.codex/instructions.md         - 全体的な設定
- リポジトリのルートにある codex.md    - プロジェクトの設定
- 現在の作業ディレクトリにある codex.md

実行後にモデルや設定を変更する

codex 実行後に / を入力する事でいくつかの command を実行できる

記憶の管理

個人的な利用方法になりますが, codebase の概要, issue (task), 一時的な context の管理を repository 内部の bank directory で行っています
以下 bank directory 構造を ~/.codex/instructions.md で明示する事で, それなりに動作しています.

bank/
├── codebase.md  // codex が解析した codebase の概要. 作業後は更新を行い最新に保つ.
├── codex.md     // project 固有の情報
├── issues/      // codex が作成した issue や task を個別ファイルに保存. ファイルを指定する事で個別のタスクを進める
└── tmp/         // codex が作業中の文脈を外部保存する場合に用いる. 精度への関与は不明だが, 実際に使用するケースが見受けられた

並列動作

こちらも個人的な使用方法ですが, 複数の task を一気に消化したい場合に用いています.

directory 内で複数の codex を動作させ, それぞれが実装を行うと作業が衝突します.
source を異なる directory へ複数展開, task 毎に codex を異なる directory 配下で実行させます.
これにより衝突なく並列動作を行えます.

gpt-4.1 の問題

apply_path に失敗する

gpt-4.1 を試したのですが, ファイルへの書き出しに失敗していました.
apply_patch という機能で書き出しを行っている様です

o3 では問題なく使用できていのたで gpt-4.1 はコマンドの実行方法を間違えていると想定し, 正しい apply_patch のフォーマットを与えたところ, 正常に動作するようになりました.

正解フォーマットの抽出

o3 で apply_patch を実行し成功体験を積んだ後に, o3 へ apply_patch の使用方法の正解を出力してもらいました.
これを ~/.codex/instructions.md へ記述したところ, 失敗するケースが減少しました...
が実用的かというとまだ微妙です

以下 apply_patch のフォーマット

apply_patch:
    基本事項:
        - **ファイルの作成, 変更, 削除は apply_patch を必ず使用する事**
        - **apply_patch を使用する際, 当情報を必ず参考にする事**
        - `*** Begin Patch` と `*** End Patch` のマーカー行を必ず含める
        - `*** Update File:` の後に修正対象ファイルのパスを指定
        - 差分は unified diff（`@@ -oldStart,oldLines +newStart,newLines`）で記述
        - 変更は可能な限り最小の差分にとどめ、関連しない行を含めない
        - 新規ファイル追加時は `*** Add File: path/to/file.ext` を使用
        - ファイル削除時は `*** Delete File: path/to/file.ext` を使用
        - 変更後は `functions.shell` 等で `cat` コマンドにより内容を確認する
        - `pre-commit` が設定されている場合は `pre-commit run --files path/to/file.ext` でチェックを通す
        - **以下の実例の成功例を元にコマンドを組み立てる事**

    実例:
        ```
        # 空の新規ファイルを作成する
        await apply_patch({
          cmd: [
            "apply_patch",
            "*** Begin Patch\n" +
            "*** Add File: bank/tmp/empty_zero.txt\n" +
            "*** End Patch\n"
          ]
        });

        # 空のファイルへ追記する場合
        await apply_patch({
          cmd: [
            "apply_patch",
            "*** Begin Patch\n" +
            "*** Update File: bank/tmp/test.md\n" +
            "@@ -0,0 +1,1 @@\n" +
            "+こんにちは、世界！\n" +
            "*** End Patch\n"
          ]
        });

        # 既存ファイルを複数行変更する場合
        await apply_patch({
          cmd: [
            "apply_patch",
            "*** Begin Patch\n" +
            "*** Update File: docs/guide.md\n" +
            // hunk#1: 2〜5行目の書き換え
            "@@ -2,4 +2,5 @@\n" +
            "-This guide will help you...\n" +
            "+このガイドでは、プロジェクトのはじめ方を解説します。\n" +
            "- Old feature A description\n" +
            "- Old feature B description\n" +
            "+ • 新機能Aの概要\n" +
            "+ • 新機能Bの概要\n" +
            // hunk#2: 追加で節を挿入（元ファイル6行目は空行なので +1 行挿入）
            "@@ -6,0 +6,2 @@\n" +
            "+### FAQ\n" +
            "+よくある質問と回答をまとめています。\n" +
            "*** End Patch\n"
          ]
        });

        # ファイルを削除する場合
        await apply_patch({
          cmd: [
            "apply_patch",
            "*** Begin Patch\n" +
            "*** Delete File: path/to/obsolete.txt\n" +
            "*** End Patch\n"
          ]
        });

        # ファイルを作成する場合の成功例
        "arguments": "{\"command\":[\"apply_patch\",\"*** Begin Patch\\n*** Add File: test.md\\n+This is a newly created test file.\\n*** End Patch\\n\"]}",

        # ファイルを削除する場合の成功例
        "arguments": "{\"command\":[\"apply_patch\",\"*** Begin Patch\\n*** Delete File: test.md\\n*** End Patch\\n\"], \"timeout\": 3000}",
        ```

どうやら bug が有る様子