エージェントループ

毎ターン、Codex は同じループを回します。これを理解することが、最もレバレッジの高い単一の行動です:

read → reason → propose → approve → apply → verify のループ

1. READ       — load relevant files, git status, prior turns
2. REASON     — decide the next action (run cmd? edit file? ask user?)
3. PROPOSE    — surface the action; if high-risk, pause for approval
4. APPLY      — execute the approved action
5. VERIFY     — re-read, run tests, check the result
       ↺ repeat until the goal is met or it asks for help

なぜ重要か: チャットボットはテキストを出力します。エージェントは行動し、結果を観察し、軌道を修正します。このループこそが Codex の価値が発揮される場所であり、ハーネス（AGENTS.md、config、承認ポリシー）が有効なコンテキストと反復の質を形作る場所でもあります。

Threads

Thread（スレッド）は Codex における会話とコンテキストの単位です。各スレッドは自身のメッセージ履歴と蓄積された状態を持ちます。実用的な含意:

• 1 スレッド 1 タスク — 無関係な作業を 1 つのスレッドに詰め込まない; コンテキストは腐敗します。
• レジューム — Codex は過去のスレッドをレジュームし、蓄積されたコンテキストを引き継げます。
• 並列 — デスクトップアプリと worktree により、複数のスレッドが干渉なく同時に走ります（タブ 5 を参照）。

黄金のルール

Codex は首輪のある有能なパートナーであり、願いを叶える井戸ではありません。 あなたの仕事は方向を与え、触れてよい境界を引き、迷走したら軌道修正することです。

この一文が、良い結果を得られるかを予測します。Codex は魔法ではなく、操縦が必要な強力な実行者です。ゴール（ステップバイステップのレシピではなく）を与え、許可する範囲（サンドボックス + 承認）を制約し、誤った前提を持ったら軌道修正してください。

コンテキストウィンドウ

ターンごとにモデルの作業記憶に収まるもの

Codex のターンあたりの有効な作業記憶は有限です。スレッドが成長するにつれ、以前のターン、ツールの出力、ファイル読み取りが蓄積します。2 つの実用的な帰結:

• 能動的に compact する — /compact はスレッドを要約して空間を再確保します; 品質が落ちた後ではなく、落ちる前に実行してください。
• 「1M コンテキスト」は 1M 使えるわけではない — システムプロンプト、ツール定義、取得されたファイルが大きな一部を消費します; あなたのタスクに使える有効な予算は、見出しの数字よりずっと小さいです。

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

Codex は2 つの独立したノブを公開しています — 1 つではありません。これが初心者の最も一般的な混乱点です:

3 つのサンドボックスモード:

3 つの承認ポリシー: untrusted（多く尋ねる）、on-request（日々のデフォルト）、never（ヘッドレス/CI のみ）。

💡 日々の開発の黄金の組み合わせ: workspace-write + on-request。エージェントはプロジェクト内で自由に編集し、プロジェクトの外に出るものはすべて前で一時停止します。

⚠️ --yolo = danger-full-access + never。使い捨てコンテナ用に存在します。実機では絶対に実行しないでください — ユーザーのファイルを削除した文書化された事例があります。

モデルと推論 effort

「Codex がどれだけ深く考えるか」を左右する 2 つのダイヤル:

• Model（/model または config の model = "..."）— 能力とコストで選ぶ。些末な編集に最強モデルをデフォルトにしない; 難しいリファクタにケチらない。
• Reasoning effort（/effort または effort ダイヤル）— low/medium/high/xhigh。モデルの切り替えより影響が大きく、調整も安価です。30 秒のリネームには low effort、モジュールのリファクタには high が必要です。

気分ではなくタスクにダイヤルを合わせてください。タスク→モデル+effort の表はタブ 6 のモデル選択セクションを参照してください。

スラッシュコマンド

スラッシュコマンドはCodex 自身（モデルの切り替え、コンテキストのクリア、状態の表示）を制御し、モデルを制御するものではありません。/ がメッセージの最初の文字のときのみ有効です。/ を入力すると、現在のエントリポイントで使えるものが表示されます。

目的別の日常 CLI コマンド:

⚠️ CLI は 40 以上のスラッシュコマンドを公開しています; デスクトップアプリは ~6、IDE は ~8 です。GUI サーフェスで CLI の完全なリストを期待しないでください。

プランモードとプロンプト

まず計画し、それから実行する。 些末でないことには、ゴールを記述して Codex に計画を作らせてください; 計画をレビューしてから実行させます。ステップバイステップのレシピではなく、ゴールと制約を与えてください — エージェントループはあなたよりシーケンス化が得意です。

プロンプトの原則:

• 言葉ではなく文脈を与える。 ファイルを指し、ゴールを述べ、制約を列挙する。冗長さは役立たず、具体性が物を言う。
• やってはいけないことを明示する — 否定的な指示（「legacy/ には触らない」「npm ではなく pnpm を使う」）は肯定的な指示よりも鋭い。
• 1 メッセージ 1 タスク — エージェントループは集中に報いる; マルチタスクのプロンプトはそれを希釈する。

一般的なワークフロー

4 つの日常フロー:

AGENTS.md

AGENTS.md は Codex のプロジェクト単位の指示ファイルです — 毎回の実行の最初、行動の前に読み込まれます。Claude Code の CLAUDE.md と同等（同じ概念、名前と探索ルールが異なる）です。

なぜ存在するか: 毎回の実行は白紙から始まります。AGENTS.md がなければ、「pnpm を使う、legacy/ には触らない、テストはこう走らせる」を毎回再説明することになります。

探索チェーン（3 階層、近い方が勝つ）:

1. Global — ~/.codex/AGENTS.md（または AGENTS.override.md、こちらが勝つ）。クロスプロジェクトのデフォルト。
2. プロジェクトルート — Git ルートの AGENTS.md。チーム共有のルール。
3. サブディレクトリ — ルートから現在のディレクトリまで歩き、各ディレクトリが AGENTS.md を寄与できます。作業ディレクトリに最も近いものが衝突時に勝ちます。

~/.codex/AGENTS.md          ← global defaults (your preferences)
project-root/AGENTS.md      ← team rules (overrides global on conflict)
project-root/src/AGENTS.md  ← subdirectory rules (closest wins)

💡 衝突は「最も近いものが勝つ」で解決する — プロジェクトルールが個人設定をオーバーライドし、サブディレクトリルールがプロジェクトルールをオーバーライドします。これはまさに望むチーム協業の挙動です。

効果的な AGENTS.md の書き方

最もレバレッジの高い使い方: フィードバックループとして扱うこと。Codex がコードベースについて誤った前提を持ったら、チャットで修正するだけ（それは 1 回限り）ではなく、修正を AGENTS.md に書かせてください。数週間でファイルにはすでに捕まえた落とし穴が蓄積し、新しいセッションは同じエラーを繰り返さなくなります。

config.toml の基本

config.toml は挙動ノブのファイルです — エージェントが逐語的に実行するマシン設定であり、AGENTS.md（自然言語の指針）とは別物です。車に例えると: AGENTS.md は取扱説明書、config.toml はダッシュボードのノブです。

2 つの場所:

⚠️ トラストゲート: プロジェクトレベルの .codex/config.toml は信頼されていないプロジェクトでは無視されます。これにより、悪意あるクローンリポジトリが勝手に自分へ権限を付与するのを防ぎます。プロジェクト設定が「反映されない」場合は、初回オープン時にプロジェクトを信頼したか確認してください。

最小構成:

# ~/.codex/config.toml
model = "gpt-5.5"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

config.toml の高度な設定

ファイルを編集せずに実行ごとにオーバーライド:

codex -c model="gpt-5.5" -c approval_policy="never"

プロファイルでプリセット設定を切り替え:

codex --profile ci        # loads the [profiles.ci] block

workspace-write 内でネットワークを有効化（デフォルトはオフ — よくある落とし穴）:

[sandbox_workspace_write]
network_access = true

設定リファレンス

高頻度のキー:

ℹ️ 完全なリファレンス: developers.openai.com/codex/config-reference。

パーミッションと承認ポリシー

上記の 2 つのノブで設定します。日々の開発では、初期セットアップ後にめったに触りません — workspace-write + on-request が大半の作業をカバーします。never に緩めるのは信頼済みのコンテナ化された自動化のみ; 分析専用にリポジトリを Codex に渡すときは read-only に固定してください。

サンドボックスと承認

サンドボックスはワークスペースへのファイルシステム書き込みを隔離し、ネットワークの送信をゲートします。主な挙動:

• workspace-write では .git が読み取り専用で保護される — Codex はリポジトリメタデータを壊しません。
• 書き込みが許可されていてもネットワークはデフォルトでオフ — 明示的に有効化してください。
• danger-full-access はすべての境界を取り除く — コンテナ/VM のみ。

⚠️ Windows の警告（検証済み、必ず引き継ぐこと）: Windows で Full Access モードがユーザーのファイルを削除したという報告が複数あります（240〜700 GB の損失が報告）。Windows で Full Access を有効にしないでください。WSL2 を使い、workspace-write に留まってください。

Hooks（ライフサイクル）

管理者は requirements.toml で hooks をロックダウンできます:

allow_managed_hooks_only = true

これはユーザー/プロジェクト/セッションの hook 設定を無視しつつ、管理対象フックは許可します。requirements.toml でのみ有効です — config.toml に書いても無効です。エンタープライズガバナンスに使います（タブ 6 を参照）。

MCP — 外部ツール

MCP（Model Context Protocol） により、Codex は外部ツールを呼べます — ライブドキュメントの取得、データベースの照会、ブラウザの操作など。Codex がサポートするトランスポートは厳密に 2 種類です:

サーバーを 2 つの方法で追加:

# CLI (fastest) — context7 = free dev-docs server
codex mcp add context7 -- npx -y @upstash/context7-mcp

または config.toml に手書き:

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

モデルが外部ツールの呼び出しを決める仕組み

💡 すべての MCP 設定は config.toml に存在します — --scope はありません。スコープはどのファイルを編集するかで決まります（~/.codex/ = グローバル、<repo>/.codex/ = プロジェクト、トラストが必要）。CLI と IDE はこの 1 つの設定を共有します。

Subagent

Subagent（サブエージェント）は、独自のスレッド、モデル、指示、パーミッションを持つ専門エージェントです。Codex は複数を並列で走らせ、それぞれはメインスレッドに要約のみを返します — 雑多な中間出力をメインコンテキストから遠ざけます。

メインエージェントが作業を派遣し、サブエージェントは生の出力ではなく要約を返す

サブエージェントが解決する 2 つの問題:

• コンテキスト汚染 — 1 つの大きなタスクのログがメインスレッドを溢れさせる; サブエージェントは雑多なものを隔離します。
• コンテキストの腐敗 — 長いスレッドは劣化する; 分割により各コンテキストを短く集中させます。

⚠️ 直感に反しますが: Codex はサブエージェントを自動生成しません。明示的に依頼したときのみ派遣します。依頼しない限り並列性を期待しないでください — これはコストの暴走を防ぎます。

カスタムエージェントの定義は ~/.codex/agents/ または <repo>/.codex/agents/ の TOML ファイルとして:

# ~/.codex/agents/reviewer.toml
name = "reviewer"
model = "gpt-5.5"
instructions = "Review diffs for correctness bugs and security issues."

エージェント Skills

Skill（スキル）は、SKILL.md ファイル（と任意のスクリプト/リソース）を持つディレクトリとしてパッケージされた再利用可能なワークフローです。ワークフローを一度書けば、Codex が必要なときに呼び出します。

スキル: SKILL.md と任意のスクリプト・参照からなるディレクトリ

最小の SKILL.md:

---
name: summarize-diff
description: Summarize uncommitted changes and flag risks. Use when the user asks for a change summary.
---

Summarize the diff, group changes by file, and call out anything risky
(uncommitted secrets, large deletions, test coverage gaps).

⚠️ よくある落とし穴（古いチュートリアル由来）: フロントマターには name + description が必要です — trigger フィールドはありません。トリガーはキーワードではなく、description のセマンティックマッチングで行われます。また、ディレクトリは ~/.codex/skills ではなく .agents/skills 配下です。古いブログ記事ではなく公式ドキュメントに従ってください。

段階的ロード: 起動時に Codex は各スキルの name、description、path のみを読み込みます。完全な SKILL.md はスキルが使われるときのみ読み込まれます — コンテキストをリーンに保ちます。

Plugins

Plugin（プラグイン）は、一括インストール可能な機能の束です — skills + agents + hooks + MCP サーバーを、各ピースを手動設定する代わりに一度にセットアップできるようパッケージ化します。コミュニティやチームがすでに首尾一貫したツールキットをまとめている場合に plugin を使い、単独のものが必要な場合は個別の skills/MCP を使います。

Rules と Hooks

Rules と hooks は実行のチェックポイントとトリガーを追加します:

• Rules — コンテキストに基づいて読み込まれる条件付き指示（例: フレームワーク固有のルール）。
• Hooks — ライフサイクルイベント（pre-tool-use、post-turn など）で発火するシェルコマンド。決定的な自動化（保存時フォーマット、コマンドのブロック、通知）向け。

Hooks は config.toml またはエージェント単位で定義できます; エンタープライズは管理対象のみにロックできます（上記の allow_managed_hooks_only の注記を参照）。

Command → Agent → Skill モデル

Codex のオーケストレーションは Claude Code の 3 階層モデルを踏襲します:

拡張の種類の選び方

なぜハーネスが重要か

出力品質 = f(有効なコンテキスト, モデル能力, 反復ループ)

ハーネス — AGENTS.md、config、承認ポリシー、skills、hooks — は有効なコンテキストと反復の質を形作ります。プロンプト単独では再現できません: プロンプトは助言ですが、ハーネスはツール制限を強制し、パスでルールを遅延読み込みし、並列サブエージェントをスケジュールし、セッションをまたいで状態を永続化します。

プロンプトが届かない階層 — ハーネスがあなたのために何をするか

非対話モード（codex exec）

codex exec は TUI なしで Codex を実行します — プロンプトを与えると、作業し、結果を出力し、終了します。「人間が介在しない」シナリオ向け: スクリプト、cron ジョブ、CI パイプライン。

codex exec "Summarize this repo's structure and list 5 areas to watch"

重要な設計 — 進捗は stderr、結果は stdout。 この分離により、画面で進捗を見ながらクリーンな結果を次のプログラムにパイプできます:

# machine-readable event stream
codex exec --json "find flaky tests" | jq ...

# save just the final message to a file
codex exec -o result.txt "write release notes for last 10 commits"

⚠️ 非対話モードはデフォルトでread-only サンドボックスです。ファイル編集を許可するには、サンドボックスを明示的に引き上げ（-s workspace-write）、承認も引き上げます（完全な無人には -a never）。

実行ポリシー

codex exec は実行ポリシーで統制できます — 無人で許可されることをルールベースで制御します。実行可能なコマンド、書き込み可能なパスなどを制約するルールを定義します。安全な CI 利用に不可欠です。

Git と GitHub の統合

Codex は 2 つのトラックで Git/GitHub と統合します:

クラウドレビューには有料プラン + Codex クラウドへ認可されたリポジトリが必要です; ローカルの /review にはそのいずれも不要です。

レビュールールのカスタマイズは AGENTS.md の Review guidelines セクション経由 — 例:「すべての route に auth ミドルウェアが必要」「ログに PII を入れない」。Codex は汎用的な基準ではなく、あなたの基準で違反をフラグします。

GitHub Actions / CI

openai/codex-action は GitHub ホストランナー上で Codex を実行し、リポジトリイベント（PR オープン、CI 失敗）で起動します。これは CI/CD トラックです — デスクトップアプリのローカル Automations とは別物です。

最小のワークフロー:

# .github/workflows/codex-review.yml
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: openai/codex-action@v1
        with:
          prompt-file: .codex/prompts/review.md
          sandbox: workspace-write

💡 2 つの自動化トラック、混ぜないこと: GitHub Action（クラウドランナー、リポジトリイベント、チーム協業）vs デスクトップアプリ Automation（あなたのマシン、cron スケジュール、プライベートタスク）。作業がある場所にトラックを合わせてください。

Worktree — 並列の隔離

Worktree は各 Codex スレッドにリポジトリのファイルの隔離されたコピー（.git メタデータは共有）を与えます。これにより複数のタスクが互いを上書きすることなく並列で走れます。

git worktree add ../feature-x -b feature-x
cd ../feature-x && codex    # isolated work on feature-x

• 同じブランチを 2 つの worktree で同時にチェックアウトすることはできません。
• Worktree + Handoff（デスクトップアプリ）は作業をフォアグラウンド/バックグラウンド間で移動します — 例: 長いリファクタをバックグラウンドの worktree で始めつつ、前面でコーディングを続ける。
• 古い worktree は定期的に掃除してください — それぞれが完全なファイルコピーを保持します。

Automations

デスクトップアプリの Automations はあなたのマシン上でスケジュールされたバックグラウンドタスクを実行します — 「毎朝、昨日のコミットを要約して」。CI（GitHub ランナー）とは別物 — これらはあなたのマシンがオンの間のみ走ります。各スケジュールタスクを隔離するために worktree と組み合わせてください。

Computer Use

Computer Use は Codex に「手」を与えます — 画面を見て、UI をクリックし、ブラウザを操作できます。対象: GUI 自動化、ブラウザテスト、デスクトップアプリの操作。リスクは高い — 見えるものすべてに作用できる; workspace-write かコンテナに閉じ込め、最初の実行を密接に監視してください。

連携（Slack / Linear / SDK）

CLI 以外に、Codex は Slack と Linear から呼べ、SDK 経由で独自の製品に組み込めます。これらを使い、Codex を別の行き先ではなく既存のワークフローの一ノードにします — 例: Slack メッセージが Codex タスクを起動し、結果がチャネルに投稿し戻る。

メモリシステム

Codex のメモリは1 つではなく 2 つのシステムです:

⚠️ 2 つのよくある間違い: (1) メモリがリアルタイムだと思い込む — セッションがアイドルした後に書き込むので、即座にテストすると失敗します; (2) メモリが AGENTS.md を置き換えると思う — 置き換えません。「必ず常に適用すべき」ルールは AGENTS.md に; メモリに賭けないでください。

Chronicle は実験的な Codex 固有のメモリで、画面コンテンツから供給されます（Pro + macOS のみ、EU/UK/スイスを除外）。有効化する前にプライバシーの含意を確認してください。

セキュリティとリスクの境界

「Codex にこれを触らせるべきか」の意思決定フレームワーク:

⚠️ 譲れないこと: 実機で --yolo にしない; Windows で Full Access にしない; 信頼されていないクローンリポジトリの .codex/ は信頼不可として扱う（Codex はデフォルトでそうします — オーバーライドしないでください）。

エンタープライズとガバナンス

Codex を会社全体で（1 人ではなく）運用するにはガバナンスが必要です:

• 管理対象設定 — IT が展開し、ユーザーが緩められない組織設定。
• requirements.toml — allow_managed_hooks_only = true が hooks を管理対象のみにロック。
• トラストポリシー — どのプロジェクトの .codex/ 階層を読み込むかを制御。
• 許可リスト — MCP サーバー、ツール、モデルを承認済みの集合に制限。

料金とサードパーティモデル

課金は ChatGPT サブスクリプション（Pro/Plus/Team/Enterprise — 使用料込み）または API クレジット（トークン従量）のいずれかです。現在の料金は OpenAI のサイトで確認してください — 数字は移ろいます; 「〜時点」という日付を添えて引用してください。

サードパーティモデル: config.toml の model_provider で Codex を他のプロバイダ（DeepSeek、ローカルモデルなど）にルーティングします。コスト統制、データレジデンシー、オフライン利用に有用です。

Windows の注意とトラブルシューティング

Windows: WSL2 内で実行してください（ネイティブは非サポート）。Full Access のデータ喪失報告は Windows 固有です — workspace-write に留まってください。

よくある不具合:

Claude Code からの移行

あなたの Claude Code の認識モデルは ~90% 移行します。概念マップ:

エージェントループ、「行動前に読む」、「ステップではなくゴールを与える」の習慣はそのまま引き継がれます。

コマンド & 設定チートシート

# install / auth
curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex login                      # ChatGPT OAuth
printenv OPENAI_API_KEY | codex login --with-api-key
codex doctor                     # self-check

# daily CLI
codex                            # interactive
codex exec "..."                 # non-interactive
codex -s workspace-write -a on-request

# slash commands (in-session)
/init  /model  /effort  /status  /clear  /compact  /diff  /review  /mcp  /skills  /agents  /memories

# config.toml essentials
model = "gpt-5.5"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
[sandbox_workspace_write]
network_access = true

ベストプラクティスと FAQ

ありきたりな言葉を超えて、実際に効くもの:

• AGENTS.md をフィードバックループにする — Codex が犯す誤った前提は、すべて 1 行として書き込む。
• モデルではなく effort をタスクに合わせる — /effort の方が安価で効果が大きい。
• 1 スレッド 1 タスク — コンテキストの劣化は現実; 作業を詰め込まない。
• 品質が落ちる前に compact する、後ではなく。
• --yolo はコンテナで — 実機では絶対に使わない。

FAQ（短く）:

• Codex はセッションをまたいで記憶しますか? AGENTS.md（信頼）と Memories（ベストエフォート）にあるものだけです。
• 非 OpenAI モデルを使えますか? はい、config の model_provider 経由で使えます。
• ファイル編集を任せても安全ですか? workspace-write + on-request であれば安全です — プロジェクトの外に出る前に一時停止します。
• CLI とデスクトップアプリのどちら? CLI が上位集合です; まず CLI を学びましょう。

用語集