- Codex CLI は、ローカル環境で安全かつ効率的に 高品質なソフトウェア変更を実行するエージェント として設計されている
- 中核構造である エージェントループ(agent loop) は、ユーザー入力、モデル推論、ツール呼び出しを循環的に結び付けて意味のある作業を実行する
- ループの過程で生成される プロンプト構成、コンテキストウィンドウ管理、プロンプトキャッシュ が、性能と安定性の中核要素として機能する
- Codex は Responses API を通じてモデルと通信し、各リクエストは完全な JSON ペイロードで構成されることで ステートレス(stateless) な動作を維持する
- この構造により、Zero Data Retention(ZDR)、プロンプトキャッシュ、自動圧縮(compaction) などの高度な機能が可能になり、大規模エージェント設計の基盤を形成する
Codexエージェントループ概要
- Codex CLI は ユーザー、モデル、ツール間の相互作用を調整するループ構造 を中心に動作する
- ユーザーの入力を受け取り、モデルに渡す プロンプト(prompt) を構成する
- モデルが応答を生成するか ツール呼び出し(tool call) を要求すると、エージェントがそれを実行し、結果を再びプロンプトに追加する
- モデルがこれ以上ツール呼び出しを行わず、assistant メッセージ を生成すると 1 ターンが終了する
- 各ターンは 会話(conversation) の一部であり、以前のメッセージとツール呼び出し履歴はすべて次のリクエストのプロンプトに含まれる
- プロンプト長はモデルの コンテキストウィンドウ(context window) 制限の影響を受けるため、Codex はこれを管理する必要がある
Responses APIとCodexの通信構造
- Codex CLI はモデル推論のために Responses API に HTTP リクエストを送る
- API エンドポイントは設定に応じて異なり、OpenAI、ChatGPT、Azure、ローカル(LM Studio、Ollama など)環境ですべて利用できる
- API リクエストは JSON ペイロードで構成され、主要フィールドは次のとおり
- system/developer メッセージ: モデルの基本コンテキスト設定
- instructions: モデルが呼び出せるツール一覧
- tools: Codex CLI、Responses API、ユーザー(MCP サーバーなど)が提供するツール定義
- input: 会話履歴と環境情報を含むメッセージリスト
- Codex は
~/.codex/config.toml の設定と、プロジェクト内の AGENTS.md、skills ファイルなどを読み取り、ユーザー指示と環境情報を自動挿入 する
プロンプト構成とイベント処理
- Codex は各メッセージを JSON オブジェクト(
type, role, content)として構成し、Responses API に送信する
- サーバーはこの JSON を基に モデルプロンプトを生成 し、SSE(Server-Sent Events)ストリームで応答を返す
response.output_text.delta イベントはストリーミング出力に使われるresponse.output_item.added イベントは次のリクエストの input に追加され、ループを継続する
- 以前のプロンプトが 新しいプロンプトの正確な接頭辞(prefix) になるよう設計されており、プロンプトキャッシュ(prompt caching) を活用できる
性能最適化: キャッシュとステートレス設計
- Codex は
previous_response_id を使わず、完全なステートレス(stateless) リクエスト構造を維持する
- これにより Zero Data Retention(ZDR) 顧客対応とデータ保持の最小化が可能になる
- プロンプトキャッシュは同一の接頭部を再利用して サンプリングコストを線形化(linear) する
- キャッシュヒットはプロンプトの 正確な接頭辞一致 のときにのみ発生する
- ツール一覧、モデル、サンドボックス設定、作業ディレクトリの変更はキャッシュミスを引き起こす
- MCP ツールの動的変更はキャッシュ損失を招く可能性があるため、Codex は 新しいメッセージ挿入方式で変更を反映 する
コンテキストウィンドウ管理と自動圧縮(compaction)
- 会話が長くなると、コンテキストウィンドウ超過を防ぐために 会話圧縮(compaction) を実行する
- 当初は
/compact コマンドで手動要約を行っていたが、現在は Responses API の /responses/compact エンドポイント を自動使用する
- このエンドポイントは
type=compaction 項目 と 暗号化された encrypted_content を返し、モデルの理解を維持する
- Codex は auto_compact_limit を超えると自動で圧縮を実行し、会話の継続性を確保する
結論と今後の方向性
- Codex のエージェントループは、モデル推論、ツール呼び出し、キャッシュ、コンテキスト管理 を統合した中核構造
- この構造は 高性能・ステートレス・セキュリティ重視のエージェント設計 を可能にする
- 今後の投稿では、CLI アーキテクチャ、ツール利用実装、サンドボックスモデル など Codex の内部構造をさらに扱う予定
1件のコメント
Hacker Newsのコメント
このブログ記事の最も良い点は、まったく意外ではないことだ。Codex CLIがオープンソースなので、リバースエンジニアリングなしで内部を確認できる
Eric Traut（Pyrightで有名な開発者）のコミュニケーションも素晴らしい。issueやPRに積極的に参加している
GitHubリポジトリ
私もCLIにいくつか改善を貢献し、リリースやPRを継続的に追いながら知識を広げている
興味深いのは、圧縮（compaction）が「モデルの潜在的理解を保持する暗号化メッセージ」で行われるという部分だ
Codexはauto_compact_limitを超えると自動的にこのエンドポイントを使って会話コンテキストを効率的に縮小する
Codexの内部を見ていて驚いたのは、reasoningトークンがエージェントのツール呼び出しループでは維持される一方、ユーザーターンが変わるたびに削除されることだ
そのため複数ターンにわたってコンテキストを維持できるが、関連するユーザー要求の間では一部の文脈が失われる可能性がある
私はモデルに進捗や計画、デバッグ内容をMarkdownファイルに記録させ、複数のコンテキストウィンドウ間で一種のスナップショットとして機能するようにしている
GitHubリポジトリ
Codexで私が本当に欲しいのはCopilotスタイルのチェックポイント機能だ。GitHubに関連issueがいくつかあるが（#2788、#3585）、チームの優先事項ではないようだ
エージェントループでユーザー指示を集約するとき、複数ターンの会話でコンテキスト維持をどう管理しているのか気になる。ユーザー要求が変化したときに動的に調整する手法を試したことがあるのかも知りたい
Codexは好きだが、ChatGPTのWebインターフェースより遅く感じる。アイデアを素早くやり取りするときは、今でもWebでコピペするほうが生産的だ
Codexはしばしば見当違いのコードを修正し始めるので、フィードバックループが遅くてじれったい。それでもうまく動くときは素晴らしい。いつかWebのように速く、それでいてローカル作業もできる水準になることを願っている
特に新しい内容ではないが、それでも価値のある記事だった。エージェント型コーディングCLIでは、ループや履歴をもっと簡単に**振り返る（reflect）**ことができるとよい。MCP経由でチャット履歴を問い合わせる方法を試したが、明示的に指定しなければならず不便だ。継続学習がこうした問題を解決できるかもしれない
こうした挙動はOTELテレメトリでも観察できる。私はheadless codex execをよく使うが、組み込みテレメトリのサポートが不十分で、デバッグが難しい
そこでcodex-plusを自作して使っている。codex execインターフェースをそのまま反映しつつTypeScript SDK上に実装してあり、実行後にセッションログをリモートのOpenTelemetryコレクタへ送信し、codex-plus-log-viewerで分析できる
スキルを説明する部分は奇妙に感じた
関連コードへのリンク
なぜ単純にファイルを直接公開せず、モデルに通常のファイルのように要求させるのか疑問だ
Codex CLIを本気で使ってみた人がいるのか気になっていた。私はVSCode Codex拡張、Gemini CLI、Claude Code CLIを使ってきたが、どれも性能がひどいものだった
ところがRustで新しく作られたCodex CLIは性能が桁違いだ。UXも完璧で、ショートカットのような細かな部分までよくできている。Theoは「CLI最適化よりモデル改善に集中すべきだった」と言っていたが、使ってみるとまったく同意できない
関連記事: Scribe Swebench Benchmark