Codex CLIの使い方｜インストールとAGENTS.md設定

Codex CLIは、OpenAIが出したオープンソースのターミナル向けAIコーディングエージェントで、Rust製です。
ChatGPTのブラウザ画面ではなく自分のマシンのターミナルで自然言語の指示を出し、コード生成からファイル編集、シェルコマンド実行までを一気に進められるので、貼って戻す作業から解放される感覚を最初に掴めます。
初めて codex と打ってTUIを立ち上げ、日本語で「READMEを読んでテストを追加して」と頼むと、差分プレビューが順に出て承認を求められ、導入の手触りは驚くほど直感的です。
導入方法はnpm、Homebrew、公式スクリプトの3通りあり、Node.js 18以上とnpm 8以上を満たしているなら npm install -g @openai/codex がもっとも手早い入口になるでしょう。

Codex CLIとは？ターミナルで動くAIコーディングエージェント

Codex CLIは、OpenAIが開発するオープンソースのターミナル向けAIコーディングエージェントです。
Rust製なので起動や応答が軽く、ChatGPTの画面で指示を往復させるのではなく、ローカルのリポジトリを直接読み書きしながら作業を進められます。
コードを貼って戻してを繰り返していた作業が、ひとつの端末内でまとまる感覚に変わるのが、このツールのいちばん大きな価値でしょう。

Codex CLIでできること

自然言語で「このバグを直して」「テストカバレッジを上げて」と頼むと、Codex CLIはコード生成、ファイル編集、シェルコマンド実行までを連続して処理します。
人は毎回の細かな手作業から離れ、差分の確認と承認に集中できるため、修正のたびに画面を行き来する負担が減ります。
単なるチャット補助ではなく、作業そのものを委ねる発想に近い。
だからこそ、リポジトリ全体を相手にする変更で強みが出ます。

さらに、プロジェクトの動かし方を記したAGENTS.mdを読ませられるので、ビルド手順やテスト方法、出荷時の注意点を事前に共有したまま動かせます。
ルートの設定とグローバル設定を連結し、近い階層を優先する仕組みもあるため、チームごとの運用ルールを保ちやすいです。
作業中は /model や /diff で挙動を切り替えたり、codex exec で非対話実行に回したりもできます。

CLI版・GUIアプリ版・IDE拡張版の違い

同じCodexでも、ターミナルで動くCLI版、GUIアプリ版、IDE拡張版では向いている仕事が異なります。
CLI版は自動化やスクリプト連携に強く、codex exec を使えばCI/CDや無人実行にも組み込みやすいので、開発ワークフローの中核に置きやすいでしょう。
画面を開いたまま細かくやり取りするより、端末から一気に処理したい場面に合っています。

GUIアプリ版は操作の見通しを取りやすく、IDE拡張版はエディタ内でコードを見ながら進められるのが利点です。
つまり、CLI版は「自動で回す」、GUI版は「流れを見ながら進める」、IDE拡張版は「書いている場所の近くで補助してもらう」という役割分担になります。
初回は端末で試し、その後に必要な導線へ広げていくと整理しやすいでしょう。

料金体系

利用方法は大きく2つあり、ChatGPT Plusの$20/月やProの$200/月のプラン枠を消費する方法と、APIキーで従量課金する方法があります。
プラン枠を使う形なら、対話しながら試すときに追加課金を気にしなくてよいので、試行回数の多い開発作業と相性がいいです。
反対に、APIキー課金は実行単位で管理しやすく、codex exec のような非対話運用に向いています。

認証は codex login のChatGPT OAuthと、OpenAIダッシュボードのAPIキー利用に分かれます。
対話中心なら前者、CI/CDや無人実行なら後者と考えると迷いません。
ChatGPTログインが有効なままだとAPIキーへ切り替わらない場合があるため、そのときは codex logout か ~/.codex/auth.json の削除で切り替える運用になるでしょう。

インストール前の準備と3つの導入方法

Codex CLI は、まず Node.js 18以上と npm 8以上が入っているかを確認してから導入するとつまずきにくいです。
node -v と npm -v で手元の版を見ておけば、途中で command not found が出る原因を早めに切り分けられます。
準備が整っていれば、導入経路は npm、Homebrew、公式スクリプトの3通りから選べます。
環境を増やしたくないか、既存の管理方法に寄せたいかで、最短ルートは自然に決まるでしょう。

前提環境

Codex CLI を動かす土台は Node.js 18以上と npm 8以上です。
ここが満たされていないと、インストール自体は進んでも実行時に codex が見つからない、あるいは依存関係の取得で止まる、といった回り道が起きます。
先に node -v と npm -v を打って版数をそろえるだけで、後の確認作業がずっと軽くなるのです。
準備の段階で足場を固める。
これがいちばん効きます。

方法1: npmでグローバルインストール

もっとも標準的なのは npm でのグローバルインストールです。
npm install -g @openai/codex を1回実行すればよく、すでに Node 環境を持っている開発者にはこれが最短ルートになります。
コマンドひとつで済むので、日常的に npm 管理へ寄せている人ほど扱いやすいはずです。
完了したら codex --version を実行して、入ったことをその場で確かめましょう。

npm で入れたのに codex: command not found になる場面は珍しくありません。
原因の多くは、npm のグローバル bin の場所が PATH に入っていないことです。
npm bin -g で出たパスを環境変数に追加し、必要ならターミナルを開き直せば通ります。
初心者がつまずきやすい流れですが、手順は単純です。

方法2・3: Homebrewとインストールスクリプト

macOS では brew install --cask codex でも導入できます。
Homebrew 管理に統一したい場合や、Node 環境を新しく作りたくない場合には、この選び方が自然です。
実際、環境を増やさずに済むので、他のツールと同じ流儀で管理しやすくなります。
管理の一本化を重視するならおすすめです。
Node を触らずに済ませたいなら、公式インストールスクリプトも使えます。
Mac/Linux は curl で取得して実行し、Windows は同等の PowerShell スクリプトで導入します。
導入後は codex --version で版数を見て、起動確認まで終えると流れがきれいです。
ターミナルを閉じたままにせず、反映の確認まで一気に進めましょう。

初回起動と認証

インストール後に最初に通る関門は認証です。
codex login を実行するとブラウザが開き、ChatGPT の OAuth 認証へ進みます。
成功するとトークンはローカルにキャッシュされ、追加の API 課金が乗らないまま ChatGPT プランの利用枠を使って始められます。

codex loginでChatGPTアカウント認証

初回セットアップでは、ターミナルで codex login を打ってから画面を追う流れをそのまま覚えるのが早いです。
ブラウザ側で ChatGPT にログインし、認証を許可してターミナルへ戻ると、もう作業環境は認証済みになっています。
この一連の動きが見えると、以後の操作で何がローカルに残り、何がクラウド側の利用枠を使うのかを切り分けやすくなるでしょう。
対話的に手を動かす用途なら、まずこの方式で始めるのがおすすめです。

APIキーで認証する場合

もう1つの入口は API キー認証です。
OpenAI ダッシュボードで取得したキーを使うため、リクエストごとの従量課金になり、コストの見通しが立てやすい反面、実行量が増えると支払いも積み上がります。
人が画面を見ながら試すのではなく、CI/CD やサーバー上の無人実行、サービスアカウント運用に向くのはこのためです。
使い分けの目安は明快で、対話利用は ChatGPT ログイン、定常実行は API キーと覚えておくと迷いません。

認証が通ったら、作業の入口はそのまま広がります。
codex だけで対話セッションを起動してもいいし、codex "このリポジトリにテストを追加して" のようにワンショットで指示しても構いません。
TUI が立ち上がったら / を打てばスラッシュコマンドの一覧が開くので、まずは操作の地図を確かめられます。

最初の一歩：自然言語で指示を出す

最初の指示は、影響の小さいものから始めるのが安全です。
たとえば「READMEを要約して」や「テストを1つ追加して」と頼み、差分を確認してから承認する流れにすると、承認フローと差分プレビューの手触りをつかみやすくなります。
日本語の指示もそのまま通るため、構文を整えるより先に、短い自然文を投げて反応を見るほうが実践的です。
小さく試してから本番に移る、この順番が使いこなしの近道になります。

AGENTS.mdの書き方と探索ルール

AGENTS.mdは、Codexが作業を始める前に読む“現場の動かし方”をまとめたMarkdownです。
READMEのような概要説明ではなく、どうビルドし、どうテストし、どうレビューして出荷するかを具体的に書くほど効きます。
ルートに置くか、~/.codex/AGENTS.md に置くかで役割が分かれ、探索順も階層で決まる仕組みです。

AGENTS.mdの役割と設置場所

AGENTS.mdは、作業前に読ませるための運用指示書として置くのが基本です。
プロジェクト固有のルールはリポジトリルート、全案件に共通する癖や好みは ~/.codex/AGENTS.md に分けると、指示が混ざらず扱いやすくなります。
たとえばコミットメッセージの流儀はグローバルに寄せ、触ってよいディレクトリやテスト手順はルートに書く、という切り分けが自然でしょう。

階層的な探索と後勝ちの優先順位

探索はルートからカレントディレクトリまで階層的に行われ、見つかったAGENTS.mdは連結されます。
しかもカレントに近いファイルほど後ろに置かれるため、下位階層の指示が後勝ちで上書きできます。
モノレポで全体方針をルートに書き、各パッケージ配下に固有ルールを置くと、同じリポジトリでもパッケージごとの作法を守らせやすくなります。
これはかなり実用的です。

連結には project_doc_max_bytes の上限があり、既定は32KiBです。
空ファイルはスキップされるので、余計な散文を増やすより、短く要点を絞ったほうが確実に読み込まれます。
初期状態では /init を打てばカレントディレクトリにひな形を生成できますが、そのままでは足りません。
実際に使うテストコマンドや、触ってはいけないディレクトリ、出荷前の確認手順へ書き換えてこそ機能します。

何を書くか・何を書かないか

書くべきなのは、npm test のようなテストコマンド、命名規則、生成物の置き場所、編集禁止ディレクトリのような操作的な情報です。
逆に「きれいなコードを書く」のような抽象論や、鍵情報・秘密情報の直書きは向きません。
1行ごとに「何をする」「何を避ける」が見える文にすると、機械にも人にも通じるAGENTS.mdになります。

実際、/init で作られた初期AGENTS.mdにテストコマンドと非編集領域を追記しただけで、指示の通り方は一気に良くなりました。
的外れな変更が減り、どこまで触ってよいかの判断も安定します。
要点はシンプルで、READMEではなく運用のための命令を書くこと。
そこを外さなければ、AGENTS.mdは静かに効き続けます。

承認モードとサンドボックスの設定

承認モードとサンドボックス、そしてネットワークの可否は、どこまで自動で動くかを決める三本柱です。
まずはこの3軸を切り分けると、危険な自動化を避けながら必要なところだけ任せやすくなります。
手元で試すなら read-only から始め、慣れたら workspace-write に上げる流れが安全でした。
そこで不足するのはたいてい通信の許可なので、次にそこを見ます。

3軸

approval_policy はどのくらい承認を求めるか、sandbox_mode はファイルやコマンドがどこまで触れるか、network_access は外部通信を許すかを分けます。
ここを混ぜると設定の意味がぼやけますが、3軸で見ると役割がはっきりするのです。
read-only は読むだけ、workspace-write は作業ディレクトリ内の書き込みまで、danger-full-access は制限なしで動きます。
最初は workspace-write を基準にし、danger-full-access は安易に使わないほうが安全でしょう。

段階的に権限を緩めると、何が原因で止まったのかを切り分けやすくなります。
read-only で挙動を観察し、必要になったら workspace-write に上げ、さらに通信が要る場面だけ network_access を開く、という順番だと迷いません。
権限を一気に広げるより、どこで止まるかを一つずつ確認したほうが運用は安定します。
おすすめです。

--full-autoと-a neverの違い

--full-auto は --ask-for-approval on-request と --sandbox workspace-write をまとめたショートカットです。
承認の手数を減らしつつ、書き込み先を作業ディレクトリ内に抑えるので、速度と安全性のバランスが取りやすい設定になります。
実際に使うと、単純な編集や実行はかなり快適でした。
ところがパッケージインストールだけは通らず、原因を追うと network_access が既定でオフだったわけです。

この落とし穴は見落としやすいですが、意味は明快です。
ファイル操作の範囲と通信の可否は別管理なので、ローカル編集だけ速くしても外部取得は止まる、という設計になっています。
--full-auto で快適になったのに止まる場面があるのは、その境界がはっきりしているからだと理解するとでしょう。

config.tomlでの恒久設定と優先順位

毎回フラグを付けるのは面倒なので、常用設定は ~/.codex/config.toml に書いて恒久化します。
その場だけ変えたいときは CLI 引数、基本方針は config.toml と分けると運用しやすいです。
優先順位は CLI 引数 > プロファイル > config.toml > 既定値で、上から順に強く上書きされます。
だから一時的な実験はフラグ、普段の基準は config.toml に置くのが筋でしょう。

組織で使うなら requirements.toml で制約を強制できます。
たとえば approval_policy="never" や danger-full-access を禁止しておけば、個々の設定ミスで危険側に倒れにくくなります。
個人の便利さだけでなく、チーム全体で同じ安全基準を保てるのが利点です。
設定の自由度を残しつつ、越えてはいけない線はファイル側で固定しておく。
運用としてはそれがいちばん安定します。

スラッシュコマンドとMCP・非対話実行で使いこなす

Codexは、対話中の操作をスラッシュコマンドで素早く切り替え、重い作業は非対話実行とMCP連携に逃がすと運用が安定します。
/model や /approvals でその場の設定を変え、/resume で作業の続きに戻り、codex exec でCIに載せる、という役割分担が軸になるでしょう。
日常の試行錯誤と自動化の境目をはっきり分けると、ターミナルの中だけで回る作業環境が作りやすくなります。

主要スラッシュコマンドとセッション再開

コンポーザーで / を打つとコマンド一覧が開き、/model でモデル、/approvals で権限、/diff でGit差分、/init でAGENTS.mdのひな形を扱えます。
設定確認のたびに画面を行き来しなくて済むので、編集・承認・差分確認の流れが途切れにくい。
/goal を使って作業の目的を明示しておくと、会話の焦点もぶれにくくなります。

/resume は長い作業ほど効いてきます。
夕方に止めたタスクを翌朝に呼び戻したとき、保存済みセッションを選ぶだけで文脈をそのまま引き継げるため、説明し直す手間がほぼ消えます。
日をまたぐ修正や調査では、この再開性がそのまま作業速度になる。
作業の途中で迷ったら、まず呼び戻す。
シンプルです。

codex execで非対話・CI実行

自動化の入口が codex exec、別名 codex e です。
非対話で実行し、結果をstdoutやJSONLに流せるので、1回のコマンドで終わる検査や整形をそのままCI/CDのステップに差し込めます。
手作業で回していたコード整形をここに落とし込むと、プルリクごとに自動チェックが走るようになり、抜け漏れの確認が人の記憶に依存しなくなる。
無人実行はAPIキー認証と組み合わせるのが定石で、承認待ちの往復を減らしやすいでしょう。

非対話実行のよさは、再現性がそのまま残る点にもあります。
どの入力に対して何が返ったかをJSONLで追えるため、あとから結果を機械的に集計しやすい。
手元では速く、CIでは堅く回す。
役割を分けるほど運用は安定します。

MCP連携とモデル切り替え

外部ツール連携はMCP（Model Context Protocol）で行います。
~/.codex/config.toml にSTDIOやHTTPのMCPサーバーを登録するか、codex mcp コマンドで管理すると、セッション開始時にサーバーが起動し、組み込みツールと並んで使えるようになります。
リポジトリの外にある情報や社内ツールまで扱えるようになるので、Codexを単なる会話相手ではなく作業基盤として使いやすくなる。

モデルの切り替えは /model か config.toml の model 設定で行います。
複雑なコーディングや広い文脈が必要な場面では gpt-5.5 のような高性能モデルを選び、軽い確認や定型処理には軽量モデルを当てると、コストと速度の釣り合いが取りやすい。
全部を同じモデルで済ませるより、場面ごとに切り替えるほうが実戦的です。

よくあるトラブルとClaude Codeとの使い分け

導入直後に詰まりやすいのは、codex: command not found と認証ループの2つです。
前者は PATH 未設定が原因で、npm のグローバル bin を PATH に足すか、Homebrew やスクリプト導入に切り替えれば抜けられます。
後者は API キーを入れても ChatGPT ログインのキャッシュが優先されるのが根っこで、codex logout か ~/.codex/auth.json の削除でいったん記憶を消してから入れ直すと通りやすくなります。

command not foundとPATHの解決

codex: command not found が出たら、まず PATH を疑うのが早いです。
Codex CLI 自体が壊れているのではなく、インストール先の実行ファイルにシェルが届いていないだけ、というケースがほとんどだからです。
npm のグローバル bin を PATH に追加するか、Homebrew やスクリプト導入に切り替えると解決しやすく、ここを先に潰すと次の検証に進めます。

手元で見える症状は単純でも、放置すると「入っているはずなのに動かない」という無駄な切り分けが増えます。
インストール直後のつまずきはこの型に収束しやすいので、まずコマンドが見える状態を作りましょう。

認証ループとAPIキー切替の対処

認証まわりで厄介なのが、ChatGPT ログイン中に API キー認証へ切り替わらない現象です。
OPENAI_API_KEY を設定しても「キーを設定して」と促され続けるなら、裏側で古いログイン状態が残っていると考えるのが自然でしょう。
codex logout を実行するか、~/.codex/auth.json を削除してキャッシュを消し、改めて認証し直すと堂々巡りから抜けやすくなります。

実際、API キーを設定したのに認証が通らず、同じ画面を往復するだけになった場面では、codex logout でキャッシュを消してから入り直しただけであっさり通りました。
認証情報は一度食べ違うと長引くので、最初から再ログインを前提に切り分ける方が早いです。

Claude Codeとの使い分け

つまずきの型を押さえたら、次は役割分担です。
承認プロンプトが止まらない、ネットワークが拒否される、WSL や macOS でサンドボックスエラーが出る、認証ループに入る――この4類型として整理すると、どこを直すべきかが見えます。
承認ポリシーの緩和、network_access の有効化、サンドボックス設定の見直し、再ログインを順に当てるだけで、迷いはかなり減ります。

使い分けの目安は明快です。
速度とトークン効率、サンドボックス実行を重視するなら Codex が向き、依存関係が絡む大規模変更や深い推論が要る場面では Claude Code が強いでしょう。
実務では両方を併用するのが現実的で、日常のリファクタは Codex、設計判断が絡む横断変更は Claude Code に回すと、どちらか一方に無理をさせずに済みます。
速く回したい作業は Codex、難所は Claude Code。
この切り替えだけで運用は安定します。