Codex App Serverとは？仕組み・SDKとの違い・基本の使い方を解説

Codex App Serverは、OpenAIのコーディングエージェントCodexを独自のIDEや開発ツールへ組み込みたい開発者向けの仕組みです。会話履歴、ユーザー承認、エージェントの作業状況を扱えるため、Codexの実行過程を独自UIに表示できます。

本記事では、Codex App Serverの役割、Codex SDKとの使い分け、基本的な通信方法、利用時の注意点を解説します。

Codex App Serverとは何か

Codex App Serverは、リッチなクライアントからCodexを操作するためのJSON-RPCベースのサーバーです。JSON-RPCは、アプリケーション同士でメッセージを送受信するための通信方式です。CodexのVS Code拡張機能のように、会話画面、ターミナル実行、ファイル変更、承認ダイアログといった体験を自前のプロダクトへ組み込みたい場合に利用します。

App Serverを介すると、クライアント側はCodexとの会話をスレッドとして管理し、ユーザーの依頼をターンとして送信できます。Codexが作業中に出力するメッセージ、ツール実行、ファイル変更などもイベントとして受け取れるため、進捗を画面へリアルタイムに表示できます。

独自IDE・エディタ・開発支援ツールへのCodex統合
会話履歴や作業状況を表示する独自UIの実装
ユーザー承認を含む対話型のエージェント体験
ローカル環境やリモート開発環境でのCodex操作

実装はCodexリポジトリ内でオープンソースとして公開されています。ただし、CLI上ではexperimental（実験的機能）として扱われており、将来的に仕様が変更される可能性があります。

Codex App ServerとSDK・CLIの使い分け

Codexをプログラムから使う方法はいくつかあります。App Serverは万能な置き換えではなく、用途に応じて使い分けることが重要です。

Codex App Server：会話、承認、進捗イベントを扱う独自クライアントを作りたい場合
Codex SDK：CI/CD、バッチ処理、バックエンドからの自動実行などをコード中心で実装したい場合
Codex CLI：ターミナルから対話的にCodexを利用したい場合

独自の画面で依頼、進捗、承認を扱いたい場合は、App Serverが向いています。たとえば、社内向けの開発ポータルに「Codexへ依頼する画面」を設けるケースです。

一方、毎晩のリポジトリレビューや定型的なドキュメント更新のように、対話なしで実行する処理には、Codex SDKやCLIの非対話実行が適しています。

Codex App Serverの通信方式と起動方法

Codex App Serverは、主に次の通信方式をサポートしています。

stdio：標準入出力を利用する方式。既定値で、ローカルの子プロセスとして起動するクライアントに適しています。
WebSocket：localhostまたはSSHポートフォワードを介して接続する方式です。
Unix socket：Unix系環境で利用する、ローカルプロセス間の接続方式です。

最初の動作確認には、既定のstdioで起動する方法がもっともシンプルです。

codex app-server

WebSocketでローカル接続を受け付ける場合は、次のように起動します。

codex app-server --listen ws://127.0.0.1:4500

起動後、Codex CLIのターミナルUIをリモート接続することもできます。

codex --remote ws://127.0.0.1:4500

stdioでは改行区切りのJSON、WebSocketでは1メッセージごとのJSON-RPCとして通信します。

Codex App Serverの基本フロー：スレッドとターン

App Serverの基本単位は、Thread（スレッド）、Turn（ターン）、Item（アイテム）です。

Thread：ユーザーとCodexの会話全体を表す単位
Turn：1つの依頼と、それに対するCodexの作業
Item：メッセージ、コマンド実行、ファイル変更、ツール呼び出しなどの個別イベント

接続を初期化し、会話の単位となるスレッドを作成してから、ユーザーの依頼をターンとして送信する流れです。

initialize を送信する
initialized 通知を送信する
thread/start で新しい会話を開始する
turn/start でユーザーの依頼を送信する
メッセージやツール実行などのイベントを受信する
turn/completed を受信して完了を確認する

作業中のCodexへ追加の指示を送る場合は、別のターンを開始する代わりに turn/steer を使えます。これにより、「その変更は不要です」「先にテストを実行してください」といった軌道修正を、実行中の作業へ反映できます。

Codex App Serverの型定義・スキーマの生成

独自クライアントをTypeScriptで開発する場合は、CLIから型定義やJSON Schemaを生成できます。生成結果は実行したCodexのバージョンに対応するため、クライアント実装とプロトコルの差分を抑えやすくなります。

codex app-server generate-ts --out ./schemas
codex app-server generate-json-schema --out ./schemas

実験的なフィールドやメソッドを利用する場合は、クライアントの初期化時に実験的APIを有効化する必要があります。まずは安定したAPIだけで小さく始め、必要になった時点で追加機能を検討するのが安全です。

Codex App Server導入時のセキュリティ上の注意点

App Serverはローカル開発を主な想定としています。特にWebSocketを利用する場合は、App Serverを共有ネットワークやインターネットへ直接公開しないことが重要です。

ローカル利用では、127.0.0.1 にバインドする
リモート環境へ接続する場合は、SSHポートフォワード、VPN、メッシュネットワークを利用する
非ローカルのWebSocket接続では、TLS終端（通信をHTTPSで保護する仕組み）または安全なプロキシを用意する
WebSocket認証には能力トークンまたは署名付きBearerトークンを設定する
サーバー側の能力トークンはトークンファイルで管理し、リモート接続クライアントのBearerトークンは環境変数で渡す

WebSocket機能は実験的です。安定性を前提とした外部公開には、現時点では慎重な判断が必要です。まずはstdioまたはlocalhost接続で検証し、その後に組織のセキュリティ方針に沿って接続方法を設計しましょう。

まとめ

Codex App Serverは、Codexを単にコマンドとして実行するだけでなく、独自の対話型プロダクトへ組み込むための基盤です。スレッド、ターン、イベントストリームを利用することで、作業の進捗や承認を見せる独自の開発体験を構築できます。

一方で、App Serverは実験的な機能です。まずはstdio経由の最小クライアントで、スレッド開始とイベント受信までを試してみましょう。そのうえで、安定性・認証・ネットワーク公開の方針を確認しながら段階的に導入するのがおすすめです。