概要
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 g有る様子