コーデックスエージェントループの展開

122日前原文(openai.com)

概要

Codex CLI は高品質かつ信頼性の高いソフトウェア変更をローカル環境で安全・効率的に実行するクロスプラットフォームエージェント
本記事は Codexのコアロジック である「エージェントループ」に焦点を当て、その仕組みと設計思想を解説
エージェントループ はユーザー・モデル・ツール間のやり取りを統括し、会話型でソフトウェア作業を進行
プロンプト構築 やAPIとのやりとり、コンテキストウィンドウ管理など、実装上の工夫も紹介
今後もシリーズとして Codexの内部構造や設計上の知見 を継続的に発信予定

Codex CLIのエージェントループ概要

Codex CLI はOpenAIが提供するローカルソフトウェアエージェント
- クロスプラットフォーム対応
- 高品質なソフトウェア変更の自動化
- 安全性・効率性を重視
エージェントループ はCodex CLIの中核ロジック
- ユーザー入力、AIモデル、ツール呼び出しを統括
- 1ターンごとに「ユーザー入力→モデル推論→ツール実行→レスポンス生成」を繰り返す
- モデルがツール呼び出しを要求した場合は、ツール実行結果をプロンプトに追加して再推論
- モデルがユーザー向けメッセージを返した時点で1ターン終了
Codex CLI の「会話」は複数ターンから構成
- 各ターンの履歴（メッセージ・ツールコール）をプロンプトに含めて次のターンへ
- プロンプト長は会話が進むほど増加
- モデルの「コンテキストウィンドウ」制約への対応が必要

プロンプト構築とAPI連携

Codex CLI はResponses APIにHTTPリクエストを送信して推論を実行
- ChatGPTログイン時: https://chatgpt.com/backend-api/codex/responses
- APIキー認証時: https://api.openai.com/v1/responses
- gpt-oss利用時: http://localhost:11434/v1/responses
- Azure等クラウド環境にも対応
プロンプト生成 の流れ
- ユーザーはAPIに直接プロンプトを指定せず、各種入力タイプで指示
- Responses API側で「リスト形式プロンプト」に変換
- 各プロンプト要素には「role」が付与され、優先度順は system > developer > user > assistant
- toolsフィールドには利用可能なツール定義が含まれる
- developer_instructionsやユーザー指示、スキル設定もプロンプトに反映
JSONペイロード 例
- 各要素はtype, role, contentを持つJSONオブジェクト
- Authorizationヘッダーや追加パラメータもサポート
APIレスポンス はServer-Sent Events（SSE）ストリーム
- 各イベントはtypeで分類（例: response.output_text.delta）
- ツール呼び出し結果や推論結果を次回リクエストのinputに追加

エージェントループの性能と設計上の工夫

プロンプトはターンごとに増加 し、APIへのJSON送信量も増える
- Responses APIはprevious_response_idパラメータで最適化可能
- Codex CLIは「完全ステートレス」かつ「Zero Data Retention（ZDR）」構成を優先し、previous_response_idは未使用
- これによりプロバイダ側の実装がシンプル化
プロンプトキャッシュ 等による効率化も検討領域
- 今後のパフォーマンス最適化や設計改善に繋がる知見を蓄積中

Codex CLIの役割と今後の展望

Codex CLI はLLM活用のための「ハーネス」として機能
- ユーザー・モデル・ツールの橋渡し
- 実際のコード生成・編集・ファイル操作も担う
- 各ターンの終了時には必ず「assistantメッセージ」で完了を示す
今後もシリーズとして、Codex CLIの設計思想・実装詳細・得られた知見を継続的に発信予定
- 詳細はGitHub（https://github.com/openai/codex）で公開中
- IssueやPull Requestで設計上の議論も参照可能
Codex CLI は、AIソフトウェアエージェントの設計・運用における実践的な知見の集大成として、今後も進化予定

Hackerたちの意見

特に驚くような新しいことはないけど、やっぱり読んでみる価値はあるね。エージェントコーディングのCLIを使ってるときに、ループや履歴を振り返るのがもっと簡単だったらいいのに。チャット履歴をクエリできるMCPを使って成功したこともあるけど、使い方をすごく明確にしないといけないんだよね。それに、いろんなことと同じように、継続的な学習があれば解決できるかも。

Codexの内部を掘り下げて驚いたのは、推論トークンがエージェントのツール呼び出しループ中に持続するけど、ユーザーのターンごとに捨てられるってこと。これで多くのターンでコンテキストが保たれるけど、関連するユーザーターンの間にコンテキストが失われることもあるんだよね。ここで役立った戦略は、モデルに進捗更新（一般的な計画や仕様、デバッグなども含めて）をマークダウンファイルに書かせること。これが多くのコンテキストウィンドウで機能する「スナップショット」みたいな役割を果たすんだ。

└

同感！これがツールのデフォルトでできるようになったらいいな。SQLを使って同じことをしている人も見たし、この引き渡しデータを最もコンパクトに表現する提案もあったよね。

└

これが、私がCodexを最大限に活用できていない理由を説明してると思う。推論トークンで見えることに対して、私は割り込んで反応するのが好きなんだ。

└

それが「チャン」になる理由かもしれないね。長いスレッドを追跡するために内部状態を維持する必要があると思う？それとも、書かれたメモだけでギャップを埋められるかな？

└

だからCodex CLIが好きなんだ。すごくシンプルで軽量だから、その上にたくさんのツールを作れる。持続的な思考トークン？AIが書き込む別のファイルを使わせてほしいな。私たちが見る推論トークンは実際のトークンじゃないし、モデルは裏でいろいろやってるけど、APIはそれを隠してるんだ（どのプロバイダーもそうだね）。

└

APIのパスによるね。チャットの補完は君が言ってる通りだけど、これってレガシーじゃない？俺はcodexをresponses v1 APIでしか使ったことないけど、そっちは全く逆だよ。思考プロセスが終わる前にターンをキャンセルしても、すでに生成された推論トークンが次のメッセージを送った後も残ってるし。あと、responses v1のxhighモードは他のモードよりもコンテキストウィンドウをめちゃくちゃ早く消費するから、これには納得できる。

└

それは違うと思う。Codexはresponses APIでreasoning.encrypted_content=trueとstore=falseを使ってるって確信してる。reasoning.encrypted_content=true - サーバーは次の呼び出しで渡せる暗号化されたブロブの中にすべての推論トークンを返す。OpenAIだけがそれを復号化できる。store=false - サーバーは会話に関する情報をサーバーに保存しない。次の呼び出しではすべてのコンテキストを提供しなければならない。この2つのオプションを組み合わせることで、responses APIはステートレスになる。これらのオプションがないと、エージェントループで推論トークンが残るけど、クライアントが毎回推論を渡さなくても状態を持って処理される。

└

最近、emacsでagent-shellをよく使ってて、全てのやり取りのトランスクリプトを保存してるんだ。これのおかげで「最後のトランスクリプトを見て」って言えるから、何度も助けられた。トランスクリプトを書くのはエージェントの責任じゃなくてemacsだから、エージェントが何かをログに残すのを忘れる心配もないし。ただバッファをディスクに書き込んでるだけなんだ。

└

過去の会話を反映するスキルを作ったんだ。並行してヘッドレスCodexセッションを使ってる。コンテキストを構築するのにすごく役立つよ。リポジトリはこちら: https://github.com/olliepro/Codex-Reflect-Skill

└

これは効果的だし、コードと一緒にすべてのものがあるのは便利だけど、チーム環境や複数のブランチで同時に作業したいところでは問題が起こることがある。まだいい答えは思いついてないけど、次の実験はその部分を外部ストレージのデーモンにオフロードして、エージェント（または人間）がそれと対話できるCLIクライアントを作ることかな。

これの一番いいところは、プログラムが実践しながら学ぶ人間みたいに振る舞うところだね。最初から完璧を目指しているわけじゃなくて、結果を見ながら進歩しようとしてる。これがあれば、コンピュータが問題解決の面倒な部分を扱えるようになるから、もっと役立つようになると思う。

Codexエージェントループ：モデルを呼び出す。ツールを要求されたら、そのツールを実行して再度呼び出す（新しい結果を追加して）。そうでなければ、終了。 https://i.ytimg.com/vi/74U04h9hQ_s/maxresdefault.jpg

└

これ、ホーマー・シンプソンループって呼ぶべきだと思う。もっと適切な気がする。

Codexに求めてるのは、Copilotみたいなチェックポイントだね。GitHubでいくつかの問題が[0][1]オープンされてるけど、チームの優先事項にはなってないみたい。[0] https://github.com/openai/codex/issues/2788 [1] https://github.com/openai/codex/issues/3585

└

GitHubでは「アップボート」（絵文字リアクション）に基づいて優先順位をつけてるってよく言ってるし、あまり反応がない問題は閉じちゃうんだ。だから、これが欲しいなら、その問題に「アップボート」してね。

└

Gemini CLIにはこれがあるよ。

俺はCodexとAmpの2つのCLIを使ってる。ちょっとした変更が必要な時、ほぼ毎回AmpがCodexがコンテキストを構築するのにかかる時間でタスクを終わらせるんだ。これはシステムプロンプトや「リードループ」にも関係があると思う。Ampは一度に複数のファイルを読み込んでタスクに取り掛かるけど、Codexはファイルをほぼ一つずつ這いつくばって読む感じ。これに気づいた人いる？

└

CodexとAmpでどのGptモデルと推論レベルを使ったの？一般的に、Gpt 5.2 codexはClaude CodeのSonnet 4.5に比べて遅いって気づいた。

└

AMPの一般的な流れはどうなってるの？自分でも試してみようと思ってるけど、ずっと迷ってるんだよね。

このブログ記事の一番いいところは、驚くべきことが何もないってことだね。Codex CLIはオープンソースだから、リバースエンジニアリングしなくても内部を見られるのがいいよね。コミュニケーションも素晴らしいし、エリック・トラウト（Pyrightで有名）が問題やPRにしっかり関わってる。 https://github.com/openai/codex

└

なんでか知らないけど、Claude Codeがプロプライエタリだって知らない人が多いね。

└

その気持ちはわかるけど、OpenAIにはオープンソースに関しては全く評価してないよ。彼らの設立憲章と、金銭的に利用できるとわかった途端にそれを簡単に放棄したことを考えるとね。

└

今のところ、Claude CodeがOSSじゃないのは、コードが実際にどれだけひどいかを恥じてるからだと思ってる。月200ドルのClaudeサブスクリプションを持ってるけど、Claude CLIがどれだけ壊れてて、遅くて、使いにくいかにフラストレーションを感じてるから、もうすぐキャンセルしようと思ってる。

圧縮が「元の会話のモデルの潜在的理解を保持する」暗号化メッセージを使って行われるのは面白いね。 > それ以来、Responses APIは特別な /responses/compact エンドポイントをサポートするように進化した（新しいウィンドウで開く）。これにより、より効率的に圧縮が行われる。これは、会話を続けるために以前の入力の代わりに使えるアイテムのリストを返し、コンテキストウィンドウを解放する。このリストには、元の会話のモデルの潜在的理解を保持する不透明な encrypted_content アイテムを持つ特別な type=compaction アイテムが含まれている。今では、Codexは自動的にこのエンドポイントを使って、auto_compact_limit（新しいウィンドウで開く）を超えたときに会話を圧縮する。

└

彼らのコンパクションエンドポイントは、業界でダントツのベストだね。クロードは最下位だと思う。

└

コンパクターエンドポイントを独立して使うことってできるの？自分のドメイン特化のユースケース用にエージェントループを維持してるんだけど。コンパクションシステムは作ったけど、これの方がパフォーマンスが良さそうだね。

└

これはOpenAIのモデルじゃない他のモデルにはどう作用するの？

いいと思うけど、チャットGPTのウェブインターフェースと比べると、なんでこんなに遅いのか不思議だな。結局、チャットからコピー＆ペーストする方が生産的なことが多いし。ほぼ瞬時にフィードバックがもらえるし、アイデアを出し合う時とか、いろんなアプローチを試す時に、すごく自然に感じるんだよね。コーデックスに戻ると、間違ったことをするのを待たされてる気がするから、フィードバックサイクルが遅くてイライラする。特に、質問をしたらコードを編集し始めるのが嫌なんだ。これが結構頻繁にあるんだよね。とはいえ、うまくいった時は素晴らしい。いつか、ウェブインターフェースのように簡単でスムーズにチャットできるようになることを願ってるけど、ローカルタスクもこなせるようになってほしいな。

これらはOTELのテレメトリを通じても観察できるよ。ヘッドレスコーデックス実行をよく使うけど、内蔵のテレメトリサポートがデバッグや最適化には不十分で苦労してる。だから、自分用にcodex-plus（https://github.com/aperoc/codex-plus）を作ったんだ。これはコーデックス実行インターフェースをミラーリングしたCLIエントリーポイントで、TypeScript SDK（@openai/codex-sdk）の上に実装されてる。各実行後にフルセッションログをリモートのOpenTelemetryコレクターにエクスポートして、codex-plus-log-viewerを通じてデバッグや最適化ができるんだ。

ハクソク