はじめに
OpenAIが2026年2月4日、コーディングエージェント「Codex」の技術基盤である「Codex App Server」の詳細を公開しました。本稿では、Web、CLI、IDE拡張、macOSアプリなど複数のCodexクライアントを支える統一的なAPI基盤の設計思想と実装について解説します。
参考記事
- タイトル: Unlocking the Codex harness: how we built the App Server
- 著者: Celia Chen (Member of the Technical Staff)
- 発行元: OpenAI
- 発行日: 2026年2月4日
- URL: https://openai.com/index/unlocking-the-codex-harness/
要点
- Codex App Serverは、Web、CLI、IDE拡張、macOSアプリなど全てのCodexクライアントを支える双方向JSON-RPC APIである
- 元々はVS Code拡張のために開発されたが、複数の製品やパートナー統合の需要に応じて安定したプラットフォームAPIへと進化した
- スレッド、ターン、アイテムという3つの会話プリミティブを中心に設計され、リッチなUI表現とストリーミング更新を可能にする
- ローカルアプリ・IDE、Codex Web、TUI/CLIという3つの統合パターンで異なるクライアント環境に対応している
- JSON-RPC over stdioという軽量なトランスポート層により、Go、Python、TypeScript、Swift、Kotlinなど多様な言語での実装が可能となっている
詳細解説
Codex App Serverの役割と位置づけ
OpenAIによれば、Codex App ServerはCodexのハーネス(エージェントループとロジック)とクライアントアプリケーションをつなぐ重要な架け橋です。ここでいう「ハーネス」とは、ユーザー、モデル、ツール間のインタラクションを統括するコアロジックを指します。
Codexハーネスの内部構造は、コアエージェントループに加えて、スレッドのライフサイクル管理、認証フロー、ツール実行とサンドボックス化などの機能を含んでいます。これらの機能は「Codex core」と呼ばれるCodex CLIコードベースの一部に実装されており、App Serverはこのコア機能をクライアントフレンドリーな形で公開する役割を担っています。
App Server開発の経緯
OpenAIの発表では、App Serverの開発経緯が詳しく説明されています。当初、Codex CLIはTUI(ターミナルユーザーインターフェース)として動作していました。VS Code拡張を開発する際、同じハーネスをIDE UIから駆動する必要が生じましたが、ハーネスを再実装するのではなく再利用する方法が求められました。
最初はMCP(Model Context Protocol)サーバーとしてCodexを公開する実験が行われましたが、VS Code向けにMCPセマンティクスを維持することが困難であったため、TUIループを反映したJSON-RPCプロトコルが導入されました。これが非公式な第一版のApp Serverとなりました。
その後数ヶ月間でCodexの採用が広がり、JetBrains、Xcodeなどのパートナーや内部チームが同じハーネスを自社製品に組み込みたいという要望が増加しました。この需要に応えるため、製品とパートナー統合の両方が安全に依存できる安定したプラットフォームAPIの設計が必要となったのです。
アーキテクチャと主要コンポーネント
OpenAIによれば、App Serverプロセスは4つの主要コンポーネントで構成されています。
第一に、stdioリーダーがクライアントからのJSON-RPCメッセージを受信します。第二に、Codexメッセージプロセッサーが各スレッドのコアセッションと直接通信し、クライアントリクエストを送信してアップデートを受信します。第三に、スレッドマネージャーが各スレッドごとに1つのコアセッションをスピンアップします。第四に、コアスレッドが実際のエージェントロジックを実行します。
この設計により、1つのクライアントリクエストが多数のイベントアップデートを生成できる仕組みが実現されています。詳細なイベントストリームこそが、App Server上にリッチなUIを構築できる理由と考えられます。
また、stdioリーダーとCodexメッセージプロセッサーは、クライアントとCodex coreスレッド間の翻訳レイヤーとして機能します。クライアントのJSON-RPCリクエストをCodex coreの操作に変換し、Codex coreの内部イベントストリームをリッスンして、UI対応の安定したJSON-RPC通知に変換します。
会話プリミティブの設計
OpenAIの説明によれば、エージェントループのAPIを設計することは、単純なリクエスト/レスポンスではないため困難です。1つのユーザーリクエストが、クライアントが忠実に表現する必要がある構造化されたアクションシーケンスに展開されるためです。
この課題に対応するため、3つのコアプリミティブが設計されました。
第一に「アイテム」は、Codexにおける入出力の原子単位です。アイテムは型付けされており(ユーザーメッセージ、エージェントメッセージ、ツール実行、承認リクエスト、差分など)、明示的なライフサイクルを持ちます。item/startedでアイテムが開始され、オプションでitem/*/deltaイベントがコンテンツをストリーミングし、item/completedで最終ペイロードとともに確定します。このライフサイクルにより、クライアントはstartedで即座にレンダリングを開始し、deltaで増分更新をストリーミングし、completedで確定できます。
第二に「ターン」は、ユーザー入力によって開始されるエージェント作業の1単位です。ターンは、その過程で生成される中間ステップと出力を表すアイテムのシーケンスを含みます。
第三に「スレッド」は、ユーザーとエージェント間の進行中のCodexセッションの永続的なコンテナです。スレッドは複数のターンを含み、作成、再開、分岐、アーカイブが可能です。スレッド履歴は永続化されるため、クライアントは再接続して一貫したタイムラインをレンダリングできます。
プロトコルの実際の動作
OpenAIの技術文書では、クライアントとサーバー間の会話フローが詳細に説明されています。
まず、会話の開始時にクライアントとサーバーは初期化ハンドシェイクを確立します。クライアントは他のメソッドより前に単一のinitializeリクエストを送信し、サーバーはレスポンスで確認します。これにより、サーバーは機能をアドバタイズでき、両側は実際の作業を開始する前にプロトコルバージョニング、機能フラグ、デフォルトについて合意できます。
新しいリクエストを行う際、クライアントはまずスレッドを作成し、次にターンを作成します。サーバーは進捗状況の通知(thread/startedとturn/started)を返送し、ユーザーメッセージなど登録した入力をアイテムとして返送します。
ツール呼び出しもアイテムとしてクライアントに返送されます。サーバーはアクションを実行する前にクライアントの承認を求めることがあり、サーバーリクエストを送信します。承認はクライアントが「allow」または「deny」で応答するまでターンを一時停止します。
最終的に、サーバーはエージェントメッセージを送信し、turn/completedでターンを終了します。エージェントメッセージのdeltaイベントは、item/completedでメッセージが確定されるまでメッセージの断片をストリーミングします。
異なるクライアントとの統合パターン
OpenAIによれば、3つの主要な統合パターンが存在します。
第一に、ローカルアプリとIDEの統合では、クライアントは通常、プラットフォーム固有のApp Serverバイナリをバンドルまたはフェッチし、長時間実行される子プロセスとして起動し、JSON-RPC用の双方向stdioチャネルを開いたままにします。VS Code拡張やデスクトップアプリでは、出荷アーティファクトにプラットフォーム固有のCodexバイナリが含まれ、テスト済みバージョンに固定されています。
一部のパートナー(Xcodeなど)は、リリースサイクルを分離し、クライアントを安定させながら必要に応じて新しいApp Serverバイナリを指すことができるようにしています。これにより、クライアントリリースを待たずにサーバー側の改善やバグ修正を採用できます。App ServerのJSON-RPC表面は後方互換性を持つように設計されているため、古いクライアントが新しいサーバーと安全に通信できます。
第二に、Codex Webの統合では、Codexハーネスをコンテナ環境で実行します。ワーカーがチェックアウトされたワークスペースを持つコンテナをプロビジョニングし、その内部でApp Serverバイナリを起動し、長時間存続するJSON-RPC over stdioチャネルを維持します。WebアプリはHTTPとSSE経由でCodexバックエンドと通信し、ワーカーが生成するタスクイベントをストリーミングします。
Webセッションは一時的である(タブが閉じる、ネットワークが切断される)ため、Webアプリは長時間実行されるタスクの信頼できる情報源にはなれません。サーバー側で状態と進捗を保持することで、タブが消えても作業が継続されます。ストリーミングプロトコルと保存されたスレッドセッションにより、新しいセッションが再接続し、中断したところから再開し、クライアント側で状態を再構築することなくキャッチアップできます。
第三に、TUI/Codex CLIについては、歴史的にTUIはエージェントループと同じプロセスで実行される「ネイティブ」クライアントであり、app-serverプロトコルではなくRustのコアタイプと直接通信していました。これにより初期の反復は高速でしたが、TUIを特殊ケースの表面にしました。
OpenAIによれば、今後TUIをリファクタリングしてApp Serverを使用する計画があり、他のクライアントと同様に動作するようになります。これにより、TUIがリモートマシンで実行されているCodexサーバーに接続するワークフローが可能になり、エージェントを計算に近く保ち、ラップトップがスリープまたは切断されても作業を継続しながら、ローカルでライブアップデートとコントロールを提供できます。
適切なプロトコルの選択
Codex統合の複数の方法とその適合性について説明されています。
JSON-RPCプロトコルとしては、まず「MCP serverとしてのCodex」があります。codex mcp-serverを実行し、stdioサーバーをサポートする任意のMCPクライアント(OpenAI Agents SDKなど)から接続できます。これは、既にMCPベースのワークフローを持っており、Codexを呼び出し可能なツールとして起動したい場合に適していると考えられます。欠点は、MCPが公開するものしか得られないため、リッチなセッションセマンティクスに依存するCodex固有のインタラクション(差分更新など)がMCPエンドポイントを通じてうまくマッピングされない可能性があることです。
また、クロスプロバイダーエージェントハーネスプロトコルも存在します。一部のエコシステムは、複数のモデルプロバイダーとランタイムをターゲットにできるポータブルインターフェースを提供しています。これは、複数のエージェントを調整する1つの抽象化が必要な場合に適していると思います。トレードオフは、これらのプロトコルが多くの場合、機能の共通サブセットに収束するため、特にプロバイダー固有のツールとセッションセマンティクスが重要な場合、リッチなインタラクションを表現することが難しくなる可能性があることです。
Codex App Serverは、完全なCodexハーネスを安定したUIフレンドリーなイベントストリームとして公開したい場合に選択すべきです。エージェントループの完全な機能と、Sign in with ChatGPT、モデルディスカバリー、構成管理などのサポート機能の両方を取得できます。主なコストは統合作業です。使用言語でクライアント側のJSON-RPCバインディングを構築する必要があります。ただし、実際にはCodexがJSON schemaとドキュメントを提供すれば多くの作業を行えるため、多くのチームがCodexを使用して迅速に動作する統合を作成できたとのことです。
その他の埋め込み方法としては、Codex Execという軽量でスクリプト可能なCLIモードがあり、1回限りのタスクとCI実行に適しています。また、Codex SDKというTypeScriptライブラリもあり、独自のアプリケーション内からローカルCodexエージェントをプログラム的に制御できます。
まとめ
OpenAIのCodex App Serverは、複数のクライアント表面で統一されたコーディングエージェント体験を提供するための技術基盤として設計されました。双方向JSON-RPCプロトコル、明確に定義された会話プリミティブ、後方互換性のある設計により、様々な開発環境への統合を可能にしています。今後も、エージェントをより多くの人々にアクセス可能にするための改善が期待されます。
