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 を作成し控える

https://platform.openai.com/api-keys

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

https://platform.openai.com/docs/guides/rate-limits#usage-tiers





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

```
export OPENAI_API_KEY=xxxxxxxx
```




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

https://github.com/openai/codex






# 実行方法
## シンプルに起動
```
codex
```

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

![スクリーンショット 2025-05-07 16.55.39.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/118627/a07fafb2-d6e4-451b-98c5-668330b3bee3.png)




## model を指定
```
codex -m gpt-4.1-mini
```
![スクリーンショット 2025-05-07 18.51.00.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/118627/9e44d529-7b80-42d3-a6cc-f186c0364e71.png)




## 任意のプロンプト (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 を実行できる
![スクリーンショット 2025-05-07 20.09.17.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/118627/ce1e1781-661a-4f63-b7a8-4672830dc929.png)






# 記憶の管理
個人的な利用方法になりますが, 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 が有る様子
https://github.com/openai/codex/issues/593