Codex CLI 完全ガイド ― インストールから自動化・チーム運用まで
はじめに
「Codex CLI、入れて`codex`は打ってみたけれど、`AGENTS.md`と`config.toml`と approval mode と sandbox と`exec`の使い分けが結局よく分からない」。
そういう声をよく聞きます。Claude Code と同じく機能が多く、それぞれ似ているようで役割が違うため、雰囲気で使うと「approval を毎回 Enter で流すだけ」「`--yolo`で全部スキップして事故る」といった両極端に振れがちです。
この記事は、2026年6月時点の公式ドキュメント（`developers.openai.com/codex`）を踏まえて、OpenAI のCodex CLI を過不足なく使い切るための完全ガイドです。インストール・基本操作から、AGENTS.md／config.toml／approval・sandbox／モデルと reasoning effort／MCP／`exec`によるヘッドレス実行／Codex Cloud／チーム運用まで、実務で必要な順に並べました。最後に「Claude Code との併用（相互レビュー）」という、いま一番おいしい使い方も置いてあります。
長いので、気になる節だけ拾い読みしても構いません。
1. Codex CLI とは: 立ち位置・他ツールとの違い
2. インストールと初回起動: macOS / Windows / Linux
3. 1日目に押さえる基本操作: 起動・承認・/init
4. AGENTS.md: プロジェクトの永続記憶
5. config.toml: 挙動を固定する設定ファイル
6. Approval と Sandbox: 暴走させない安全装置
7. モデルと reasoning effort: gpt-5.5 と思考量の調整
8. Slash コマンドとセッション: /review・resume・fork
9. MCP: 外部ツールとの接続
10. exec ― 非対話・ヘッドレス: パイプ・CI・自動化
11. Codex Cloud と GitHub 連携: クラウド実行とタスク取り込み
12. 複数の入口: IDE 拡張・app・remote
13. チーム運用: 共有とポリシー強制
14. つまずきポイント: よくある事故の防ぎ方
15. Claude Code との併用: 相互レビューで品質を上げる
16. チートシート: 最後にここだけ見ればよい
1. Codex CLI とは ― 「ターミナルに住む OpenAI のエージェント」
Codex CLI はOpenAI 公式のエージェント型コーディングツールです。リポジトリを読み、ファイルを編集し、ターミナルでコマンドを実行する一連の操作を、OpenAI のモデルに任せられます。実体は**Rust 製・オープンソース（Apache-2.0）**のフルスクリーン TUI で、macOS / Windows / Linux で動きます（公式ドキュメントは末尾のリンク集を参照）。
立ち位置を一言で言うと、「Claude Code の OpenAI 版」。エージェントの基本思想（永続記憶ファイル＋設定ファイル＋承認制御＋非対話モード＋MCP）はよく似ていて、語彙だけが違います。すでに Claude Code を使っている人なら、対応表を頭に置くと一気に馴染めます。
永続記憶
Claude Code: `CLAUDE.md`
Codex CLI: `AGENTS.md`
設定ファイル
Claude Code: `.claude/settings.json`
Codex CLI: `~/.codex/config.toml`
非対話実行
Claude Code: `claude -p`
Codex CLI: `codex exec`
安全装置
Claude Code: Plan mode / permissions
Codex CLI: approval_policy × sandbox_mode
外部接続
Claude Code: MCP
Codex CLI: MCP
推奨モデル
Claude Code: Opus/Sonnet 等
Codex CLI: gpt-5.5
Codex CLI の個性を一言で言うなら、**「approval（承認）と sandbox（隔離）を独立した2軸で細かく制御できる」**こと。Claude Code が permission ルールで縛るのに対し、Codex は「どこまで自動で進めるか（approval）」と「どこまで触れるか（sandbox）」を別々に設定します。ここが最大の差別化ポイントであり、6節で詳しく扱います。
対象読者は、すでに AI コーディング支援を日常的に使っていて、「ChatGPT のサブスクに付いてくる Codex を、ターミナルでちゃんと使いこなしたい」と感じている方を想定しています。
2. インストールと初回起動
2.1 インストール
代表的な入れ方は4通りです。どれを選んでも本体は同じです。
npm: `npm install -g @openai/codex`
Homebrew: `brew install --cask codex`
macOS / Linux スクリプト: `curl -fsSL https://chatgpt.com/codex/install.sh | sh`
Windows PowerShell: `powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"`
GitHub の Releases からバイナリを直接落とす手もあります。npm 版はパッケージ名が**`@openai/codex`**（スコープ付き）である点に注意してください。
2.2 ログイン
初回に`codex`を起動するとログインが走ります。明示的に行うなら：
codex login認証は2通りです。
ChatGPT アカウント：Plus / Pro / Business / Edu / Enterprise プランには Codex の利用枠が含まれます。サブスクの範囲で使えるので、追加の API 課金が発生しません
API キー：`OPENAI_API_KEY`を標準入力から渡してログインします（`printenv OPENAI_API_KEY | codex login --with-api-key`、PowerShell なら`$env:OPENAI_API_KEY | codex login --with-api-key`）。従量課金ですが、組織のキー管理やヘッドレス運用に向きます。なお Codex Cloud の利用には ChatGPT ログインが必要です
サインアウトは`codex logout`です。
2.3 初回起動
プロジェクトディレクトリで`codex`を打つと、フルスクリーンの対話 UI が立ち上がります。
cd your-project
codexここから自然文で指示を出すと、Codex はリポジトリを読み、計画を示し、承認を取りながらファイル編集とコマンド実行を進めます。
3. 1日目に押さえる基本操作
最初に体に入れておきたいのは3つです。
3.1 普通に話す
src/api/users.ts のテストを書いて、npm test を通して、失敗したら直してCodex は読む → 計画 → 編集 → 実行 を回します。途中で「このコマンドを実行していい？」と承認を求めてくるので、内容を見て許可・拒否します（この粒度は6節の approval 設定で変えられます）。
3.2 承認はインラインで判断
既定のAutoでは、ワークスペース内の編集やコマンドは自動で進み、ワークスペース外への書き込みやネットワークアクセスなど「踏み込んだ操作」で確認を挟みます。「全部自分で確認したい」「もう信頼して任せたい」という温度感は、後述の approval / sandbox で切り替えます。
3.3 `/init`で AGENTS.md を作る
新しいリポジトリで最初にやるべきは`/init`です。
/initCodex がコードベースを読んで、ビルド・テストコマンドや構成をまとめた**`AGENTS.md`**の叩き台をリポジトリ直下に生成します。これがプロジェクトの「取扱説明書」になり、以降のセッションで毎回読まれます。
4. AGENTS.md ― プロジェクトの永続指示
Codex のセッションは毎回まっさらから始まります。プロジェクト固有の前提を横断させる仕組みが**`AGENTS.md`**です。Claude Code の`CLAUDE.md`に相当する「プロジェクトへの恒久的な指示書」で、AGENTS.md というツール非依存のオープン規格に沿っています（Codex には別途、既定では無効の「Memories」機能もありますが、それは`AGENTS.md`とは別物です）。
4.1 置き場所と優先順位
グローバル
パス: `~/.codex/AGENTS.md`
用途: 全プロジェクト共通の好み
プロジェクト
パス: リポジトリ直下の`AGENTS.md`
用途: チームで共有（git 管理）
サブディレクトリ
パス: `packages/foo/AGENTS.md`
用途: その配下に限定したルール
起動時に、リポジトリのルートからその時のカレントディレクトリまでを辿って、見つかった`AGENTS.md`を結合します（各階層では`AGENTS.override.md` → `AGENTS.md`の順に最大1ファイルが読まれます）。特定パッケージのルールを効かせたいときは、そのディレクトリで`codex`を起動するか、`codex -C packages/foo`のように作業ディレクトリを指定します。モノレポでパッケージごとに別ルールを置けます。
4.2 書き方の勘どころ
中身は普通の Markdown で構いません。効くのは「具体的な事実」です。
# プロジェクト規約
## コマンド
- ビルド: `npm run build`
- テスト: `npm test`（変更後は必ず実行）
- Lint: `npm run lint`
## コードスタイル
- TypeScript: 2スペース・セミコロンなし・シングルクォート
- コミット: Conventional Commits（feat:, fix:, docs:）
## やってはいけないこと
- main ブランチへの直接コミット
- `node_modules/` の手編集肥大化させないこと、矛盾を残さないことは CLAUDE.md と同じ鉄則です。`AGENTS.md`対応ツール（Cursor など）とは共用でき、Claude Code で読ませたい場合は`CLAUDE.md`に`@AGENTS.md`を import するか symlink を張ります（15節参照）。
5. config.toml ― 挙動を固定する設定ファイル
「毎回モデルや承認モードを指定するのが面倒」というのは、**`config.toml`**に書いて固定します。
5.1 場所
ユーザー（共通）: `~/.codex/config.toml`
プロジェクト: リポジトリ直下の`.codex/config.toml`
システム: `/etc/codex/config.toml`（Unix）
5.2 よく使うキー
# 既定モデル
model = "gpt-5.5"
# 思考量（設定値: minimal〜xhigh。実際に選べる段階はモデル依存）
model_reasoning_effort = "high"
# 承認ポリシー（untrusted / on-request / never）
approval_policy = "on-request"
# サンドボックス（read-only / workspace-write / danger-full-access）
sandbox_mode = "workspace-write"
# Web 検索（cached / live / disabled）
web_search = "cached"
# 口調（none / friendly / pragmatic）
personality = "friendly"5.3 優先順位とプロファイル
設定は上書きの優先順位が決まっています（高い順）：
CLI フラグと`--config key=value`の上書き
プロジェクトの設定ファイル（カレントに近いものが勝つ。信頼済みプロジェクトのみ）
プロファイル（`~/.codex/<name>.config.toml`、`--profile`で選択）
ユーザー設定`~/.codex/config.toml`
システム設定`/etc/codex/config.toml`
組み込みの既定値
※ 管理環境では、MDM で配布される`managed_config.toml`や`requirements.toml`がこれより上位に来て、CLI の上書きよりも強く効きます（組織のガードレール用）。
「普段は安全側、CI では全自動」のように用途別の設定をプロファイルとして分け、`codex --profile ci ...`で切り替えると管理が楽になります。
6. Approval と Sandbox ― 暴走させない安全装置
ここが Codex CLI の肝です。Codex は安全性を2つの独立した軸で制御します。
approval_policy（承認）：どこまで人間に確認を取らずに進めてよいか
sandbox_mode（サンドボックス）：そもそもファイルやネットワークにどこまで触れてよいか
「確認は取るが触れる範囲は広い」「確認なしで進むが読み取り専用」といった組み合わせを、目的に応じて作れるのが強みです。
6.1 approval_policy
`untrusted`: 既知の安全なコマンドだけ自動実行し、それ以外のコマンドで承認を求める（編集できる範囲は sandbox が決める。最も慎重）
`on-request`: サンドボックスの境界を越える操作（作業外への編集・ネットワーク・要承認コマンド）で確認を挟む
`never`: 承認を求めない。ただしサンドボックスの制約は引き続き効く（自動化・CI 向け）
※ 設定ファイルでは、カテゴリ別に許可・自動拒否を決める granular 形式（`approval_policy = { granular = { ... } }`）も使えます。
6.2 sandbox_mode
`read-only`: コマンドは読み取り専用 sandbox 内で実行できるが、ファイルへの書き込みとネットワーク接続は不可
`workspace-write`: 作業ディレクトリ内の読み取り・編集・コマンド実行を許可。外部・ネットワークは制限
`danger-full-access`: サンドボックスの制限なし（承認の有無は`approval_policy`で別途決まる。要注意）
※ `sandbox_mode`は「触れてよい範囲」、`approval_policy`は「確認なしで進めてよいか」を決める独立した2軸です。たとえば「触れる範囲は広いが、未信頼のコマンドだけ確認する」「読み取り専用だが確認しない」といった組み合わせを作れます。両方を一度に外すのが`--dangerously-bypass-approvals-and-sandbox`（`--yolo`）です。
6.3 プリセットとフラグ
TUI 上はAuto（既定）/ Read-only / Full Accessのプリセットで切り替えられ、`/permissions`でいつでも変更できます。CLI からは個別に指定もできます。
# 読み取り専用で調査だけさせる
codex --sandbox read-only -a untrusted
# CI で全自動（承認なし・隔離なし）。意味を理解した上でのみ
codex exec --dangerously-bypass-approvals-and-sandbox "..."`--dangerously-bypass-approvals-and-sandbox`（別名`--yolo`）はapproval と sandbox の両方を同時に外すため、信頼できる環境（使い捨てコンテナや CI）以外では使わないのが鉄則です。
6.4 組織での強制
管理対象マシンでは`requirements.toml`で制約を強制できます。たとえば「`approval_policy = "never"`や`sandbox_mode = "danger-full-access"`を禁止」といったガードレールを組織側で固定し、個人設定で緩められないようにできます（Agent approvals & security）。
7. モデルと reasoning effort
7.1 既定モデル
推奨は**`gpt-5.5`** ―― 複雑なコーディング・コンピュータ操作・知識労働・リサーチ向けの、OpenAI の最新フロンティアモデルです。セッション中の切り替えは`/model`、起動時の指定は`-m`です。
codex -m gpt-5.5利用できるモデルは認証方法（ChatGPT アカウント / API キー）やプランによって変わります。`/model`で選択肢を確認するのが確実です。
7.2 reasoning effort（思考量）
`model_reasoning_effort`で「どれだけ考えてから動くか」を調整します。設定値としては`minimal / low / medium / high / xhigh`がありますが、実際に選べる段階はモデル依存です（例：`gpt-5.5`では`low / medium / high / xhigh`）。確実なのは`/model`で確認することです。
軽いタスク（雑なリネーム、定型修正）：`low`〜`medium`で十分速い
設計を伴う実装やデバッグ：`high`〜`xhigh`で精度を取る
レビューのような重い分析は`xhigh`、整形のような軽作業は`low`、と用途で振り分けると、速度と品質のバランスが取れます。
8. Slash コマンドとセッション管理
8.1 主な slash コマンド
`/init`: AGENTS.md を生成
`/review`: 変更内容をコードレビュー
`/model`: モデルを切り替え
`/permissions`: approval / sandbox を変更
`/theme`: シンタックスハイライトの配色
特に`/review`は強力で、いまの差分を Codex 自身に批評させられます。コミット前のセルフレビューに向きます。CLI からは`codex exec review`でも回せます（`--uncommitted`で未コミット変更、`--base <branch>`で基準ブランチとの差分、`--commit <SHA>`で特定コミットを対象にできます）。
8.2 セッションの再開と分岐
Codex は会話のトランスクリプトをローカルに保存するので、続きから再開できます。
# 直前のセッションを再開
codex resume --last
# セッションを指定して再開
codex resume <SESSION_ID>
# 過去セッションから枝分かれさせて別案を試す
codex fork --last`codex fork`は「ある時点まで同じ文脈で、そこから別のアプローチを試す」のに便利です。
9. MCP ― 外部ツールと繋ぐ標準プロトコル
Model Context Protocol は、AI ツールと外部データソースをつなぐオープン規格です。Codex CLI は MCP クライアントとして対応しており、Google Drive・Jira・Slack・社内ツールなどを「普通のツール呼び出しと同じ感覚」で扱えるようになります。
サーバの管理は`codex mcp`サブコマンドで行います（現行版では Experimental 扱いで、CLI の更新で変わり得ます）。
# MCP サーバを追加
codex mcp add <name> -- <command...>
# 一覧・削除
codex mcp list
codex mcp remove <name>MCP は便利な反面、設定が重くなりがちです。まずは AGENTS.md とシェルコマンドで代替できないかを考え、本当に必要になってから足すのが定石です。
10. exec ― 非対話・ヘッドレス・CI
Codex CLI は対話 UI だけでなく、**`codex exec`**でヘッドレス（非対話）実行できます。これがスクリプト・CI 連携の中心です。
10.1 基本
プロンプトは引数で渡すか、`-`で標準入力から流し込めます。なお`codex exec`の sandbox は既定で`read-only`なので、ファイルを編集させたいときは`--sandbox workspace-write`を付けます。
# ファイルを編集させる（workspace-write が必要）
codex exec --sandbox workspace-write "README を日本語に翻訳して PR 用の差分にして"
# 標準入力から渡す（パイプと相性が良い）
echo "build を通してから lint を直して" | codex exec --sandbox workspace-write -10.2 主なフラグ
`--output-last-message, -o <file>`: 最終応答をファイルに書き出す（結果を取り出す定番）
`--json`: イベントを改行区切り JSON で出力（機械処理向け）
`--skip-git-repo-check`: Git リポジトリ外でも実行を許可
`--ephemeral`: セッションファイルを残さない
`--ignore-rules`: execpolicy ファイルを無視
10.3 パイプで使う
`exec`は Unix のフィルタコマンドのように繋げられます。
# ログ異常を要約させる
tail -200 app.log | codex exec - -o /tmp/report.md
# 変更ファイルだけセキュリティレビュー
git diff main --name-only | codex exec "これらの変更をセキュリティ観点でレビューして"CI からは`--dangerously-bypass-approvals-and-sandbox`（使い捨て環境のみ）と`--output-last-message`を組み合わせ、結果ファイルを後続ステップで使う、というのが基本形です。`codex exec resume <SESSION_ID>`で前回の続きを非対話で回すこともできます。
11. Codex Cloud と GitHub 連携
ローカルだけでなく、クラウド側でタスクを走らせて結果を取り込む流れもあります（`codex cloud`は現行版では Experimental 扱い、`codex apply`は安定機能です）。
# クラウドのタスク一覧
codex cloud list
# クラウドのタスクが生成した差分をローカルに適用
codex apply <TASK_ID>GitHub 連携を入れると、PR や Issue 上で`@codex review`のように`@codex`をメンションして、レビューや作業を委譲できます。「重い変更はクラウドで非同期に走らせ、`codex apply`で手元に取り込む」という非同期ワークフローが組めます（独自の起動条件が必要なら GitHub Actions で組みます）。
12. 複数の入口 ― IDE 拡張・app・remote
同じ Codex を複数の入口から使えます。
エディタ内で使う: IDE 拡張（VS Code / Cursor / Windsurf 等）
デスクトップ体験: `codex app`（macOS / Windows）
リモートの app-server に接続: `--remote`（WebSocket または Unix socket）
ローカルの OSS モデルで動かす: `--oss`（Ollama / LM Studio などの provider が必要）
同じホスト上の CLI・IDE・app なら`AGENTS.md`と`config.toml`は共通なので、二重管理にはなりません（`--remote`の接続先や Codex Cloud は、その先のホスト側の設定・権限を使う点に注意）。
13. チーム運用のコツ
13.1 共有するもの / しないもの
`AGENTS.md`（リポジトリ直下・サブディレクトリ）: ⭕ git で共有
`.codex/config.toml`（プロジェクト設定）: ⭕（チーム共通の既定）
`~/.codex/config.toml`（個人設定）: ✕ 各自のマシン
認証情報: ✕ 共有しない
「自分のマシン固有のパスや好み」はユーザー設定（`~/.codex/`）に置き、チームで効かせたいことだけプロジェクトの`AGENTS.md` / `.codex/config.toml`に書く、という切り分けが基本です。
13.2 ポリシーの強制
組織として全員に同じガードを掛けたいときは、`requirements.toml`で`approval_policy = "never"`や`danger-full-access`を禁止し、危険な設定を個人が選べないようにします。「常に X はやらせない」を組織側で固定できるのが、チーム導入時の安心材料になります。新しめのバージョンでは、名前付きの permission profile（Beta）による、より細かいポリシー固定もできます。これは旧来の`sandbox_mode`系設定とは併用せず、どちらか一方を使う方式です（詳細は公式の Managed configuration）。
14. つまずきポイントと対処
14.1 承認が多すぎる / 少なすぎる
多すぎる → `approval_policy`を`on-request`に、`/permissions`で Auto に
少なすぎて不安 → `untrusted` ＋ `sandbox_mode = "read-only"`で「まず読むだけ」にする
14.2 ネットワークやファイル書き込みが弾かれる
`sandbox_mode`が`read-only`または`workspace-write`のときは外部アクセスや作業外への書き込みが制限されます。必要な操作だけ承認で個別許可するか、用途に応じて sandbox を上げる
14.3 AGENTS.md が効いていない気がする
置き場所（リポジトリ直下か、`~/.codex/AGENTS.md`）を確認
深い階層の`AGENTS.md`に上書きされていないか
肥大化・矛盾で守られにくくなっていないか
14.4 使いたいモデルが選べない
認証方法（ChatGPT アカウント / API キー）やプランで使えるモデルが変わります。`/model`で選択肢を確認。`codex doctor`で環境診断も取れます
14.5 Git リポジトリ外で実行できない
`exec`を Git 管理外のディレクトリで回すときは`--skip-git-repo-check`を付ける
15. Claude Code との併用 ― 相互レビューで品質を上げる
Codex CLI の一番おいしい使い方のひとつが、Claude Code との相互レビューです。片方に書かせ、もう片方に批評させると、観点が違うぶん見落としが補完され、単独で回すより品質が上がりやすくなります。
`codex exec`はヘッドレスで結果をファイルに出せるので、レビュー役として組み込むのが簡単です。
# Claude Code が書いた変更を、Codex にレビューさせる
git diff main | codex exec "この差分をレビューして。バグ・抜け漏れ・改善点を箇条書きで。" -o review.md逆に、Codex が書いたコードを Claude Code にレビューさせることもできます。両者で前提を揃えたいときは、`AGENTS.md`を共通の土台にするのが簡単です（Claude Code 側は`CLAUDE.md`から`@AGENTS.md`を import すれば AGENTS.md も読み込みます）。Codex はリポジトリの`AGENTS.md`を読むので、これで両者が同じプロジェクト文脈を共有できます。
ポイントは**「執筆役」と「レビュー役」を別エンジンにする**こと。同じモデルに自己採点させるより、異なるモデルに突っ込ませる方が、事実誤りや構成の弱さが浮かび上がります。この記事自体、Claude が書き、Codex がレビューして仕上げました。
16. チートシート ― ここだけ覚える
プロジェクトの永続事実を書く: `AGENTS.md`（`/init`で雛形生成）
モデルや承認の既定を固定: `~/.codex/config.toml`
用途別の設定を切り替える: プロファイル（`--profile`）
承認の厳しさを変える: `approval_policy`（untrusted / on-request / never）
触れる範囲を変える: `sandbox_mode`（read-only / workspace-write / danger-full-access）
思考量を調整: `model_reasoning_effort`（minimal〜xhigh）
いまの差分をセルフレビュー: `/review`
非対話・CI で回す: `codex exec`（`-o`で結果取り出し）
続きから再開 / 枝分かれ: `codex resume --last` / `codex fork`
外部ツールに繋ぐ: MCP（`codex mcp add`）
クラウドの差分を取り込む: `codex apply <TASK_ID>`
本体を更新する: `codex update`
使える機能フラグを見る: `codex features`
プラグインを管理する: `codex plugin`
サンドボックス内でコマンド実行: `codex sandbox`
環境を診断する: `codex doctor`
最初の一歩は「`/init`で AGENTS.md を作り、`config.toml`に model と approval / sandbox の既定を書く」の2つだけです。あとは「毎回指定して面倒なものは config.toml へ」「チームで守らせたいことは AGENTS.md へ」「自動化したいことは exec へ」を繰り返せば、自然と自分の運用が固まっていきます。
まとめ
Codex CLI はOpenAI 公式・Rust 製のエージェント型 CLI。Claude Code と思想は近く、語彙が違う（CLAUDE.md→AGENTS.md、settings.json→config.toml、`claude -p`→**`codex exec`**）
最大の個性はapproval（承認）と sandbox（隔離）の2軸で安全性を制御できること。「確認の厳しさ」と「触れる範囲」を別々に決められる
推奨モデルはgpt-5.5、`model_reasoning_effort`で思考量を調整できる（選べる段階はモデル依存）
自動化の中心は**`codex exec`**。パイプ・`--output-last-message`・`--json`で CI に組み込む
チーム運用は`AGENTS.md`と`.codex/config.toml`を git に乗せるだけ。組織配布は`requirements.toml`で危険設定を封じる
そしてClaude Code との相互レビューは、コストの低い品質向上策のひとつ
公式ドキュメント（developers.openai.com/codex）は更新が速いので、本体は`codex update`、使える機能は`codex features`（機能フラグ）、モデルは`/model`、変更点は changelog ―― とたまに確認しておくと、自分の使い方が腐りません（`codex doctor`は環境診断用です）。
