Codex App Serverは、Codexを自社アプリや社内ツールに深く組み込むための公式インターフェースです。ふだんCodexをチャット画面やCLI、IDE拡張から使っている場合は、画面の向こう側でCodexが会話、承認、作業履歴、進行イベントを扱っています。App Serverは、その仕組みに自分のアプリから接続するための入口です。
この記事では、専門用語をできるだけ避けながら、Codex App Serverを何に使うのか、どのように起動するのか、ThreadやTurnとは何か、Codex SDKとはどう使い分けるのかを整理します。結論から言うと、単発の自動化やCIではSDK、独自のリッチなクライアントを作りたい場合はApp Server、という使い分けが基本です。
Codex App Serverとは何か
Codex App Serverは、Codexがリッチなクライアントを動かすために使う接続口です。たとえば、CodexのVS Code拡張のように、認証、会話履歴、承認、ストリーミングされる作業イベントを扱う画面を作りたい場合に使います。OpenAIの公式マニュアルでは、App Serverは自社プロダクト内に深い統合を作るときの選択肢として説明されています。
イメージとしては、Codex本体と自分のアプリの間に置く「通信窓口」です。ユーザーがアプリ上で依頼を出すと、App Server経由でCodexに伝わり、Codexの考えたこと、実行した作業、途中経過、完了結果がイベントとして返ってきます。普通のAPI呼び出しよりも、会話や作業の流れをそのまま扱えるのが特徴です。
どんなときに使うべきか
App Serverが向いているのは、Codexを自分の製品や社内ツールの中に組み込みたい場合です。たとえば、社内の開発ポータルに「このリポジトリを調べて」「この失敗ログを直して」と依頼できる画面を作る、独自の承認UIを用意する、Codexの作業イベントを自社の監査ログやダッシュボードに流す、といった用途です。
一方で、CIで決まった作業を走らせる、スクリプトからCodexに1回依頼する、自社の自動化フローにCodexを組み込むだけなら、Codex SDKの方が扱いやすい場合があります。App Serverは便利ですが、接続、初期化、スレッド管理、イベント購読まで自分で扱う必要があるため、簡単な自動化には少し重い道具です。
起動方法の基本
基本の起動は、ターミナルで codex app-server を実行するだけです。標準設定では、標準入出力を使ってメッセージをやり取りします。これは、手元のプログラムからCodexプロセスを起動し、1行ずつJSON形式のメッセージを送受信するような使い方です。
WebSocketで試したい場合は、たとえば codex app-server --listen ws://127.0.0.1:4500 のようにローカルホストで起動します。公式マニュアルでは、WebSocketは実験的でサポート対象外とされているため、外部にそのまま公開する使い方は避けるべきです。ローカル検証やSSHポートフォワードのような閉じた用途にとどめるのが安全です。
最初に行うのは初期化、次にThreadとTurn
App Serverに接続したら、最初に初期化を行います。クライアント名、タイトル、バージョンなどを渡し、自分のアプリが何者かをCodexに伝えます。この初期化が終わる前に別の依頼を送ると、サーバー側で拒否されます。まず名乗ってから会話を始める、という流れです。
その後に作るのがThreadです。Threadは、ユーザーとCodexの会話単位です。さらに、そのThreadの中で1回の依頼とCodexの作業を表すのがTurnです。たとえば「このリポジトリを要約して」が1つのTurn、「次にテスト失敗を直して」が次のTurnです。Threadは会話の部屋、Turnはその部屋の中の1回の依頼、と考えると分かりやすいです。
進行状況はイベントとして流れてくる
App Serverの大きな特徴は、Codexの作業がイベントとして流れてくることです。ユーザーへの最終回答だけでなく、作業開始、アイテムの開始と完了、エージェントメッセージの差分、ツール実行の進行、Turn完了などを順番に受け取れます。これにより、自分のアプリ上に「今Codexが何をしているか」を表示できます。
これは、通常のチャットAPIとはかなり違います。普通のAPIでは、質問を投げて答えを待つだけになりがちです。しかしCodexの作業は、ファイル確認、コマンド実行、修正、検証などの長い流れを含みます。App Serverは、その長い流れを画面に出すための仕組みだと考えるとよいでしょう。
WebSocketで使う場合の安全上の注意
WebSocketで起動する場合、特に注意すべきなのは公開範囲です。公式マニュアルでは、ローカルリスナーはローカルホストやSSHポートフォワード向きであり、ループバック以外へ公開する場合は認証設定が必要だと説明されています。外部ネットワークにそのまま開けるのは危険です。
認証には、トークンファイルや署名付きBearerトークンなどの方式が用意されています。実務では、生のトークンをコマンドラインに直接書かず、トークンファイルを使う方が安全です。また、サーバーが混雑している場合は、過負荷を示すエラーが返ることがあります。その場合、クライアント側では少し待ってから再試行する設計が必要です。
SDKとの使い分け
CodexにはSDKも用意されています。TypeScript SDKやPython SDKを使うと、Threadを作ってプロンプトを実行する流れを、より簡単なコードで扱えます。CI/CD、自動レビュー、社内スクリプト、定期実行のように「Codexに仕事を頼んで結果を受け取る」用途では、まずSDKを検討するのが自然です。
一方、App Serverは、Codexを自社製品の中でリッチに見せたいときに向いています。会話履歴、承認UI、リアルタイム進行表示、作業イベントのログ化、独自のクライアント画面などを作るならApp Serverです。要するに、SDKは「Codexを使うための道具」、App Serverは「Codexの画面や体験を作るための接続口」と考えると整理しやすくなります。
まず試すならこの順番
最初にやることは、Codex CLIが手元で動くことを確認することです。次に codex app-server を標準入出力で起動し、初期化、Thread作成、Turn開始の流れを小さく試します。その後、必要に応じてWebSocketやUnix socketの接続を検討します。いきなり本番システムへ組み込まず、ローカルで小さく動かすのが安全です。
また、企業利用では、クライアント名をきちんと設定し、監査ログやコンプライアンスの扱いも確認しておく必要があります。Codexに何を読ませるのか、どの作業には承認を挟むのか、どの環境では書き込みを許すのか。App Serverを使うほどCodexの力を深く組み込める分、運用設計も同時に大切になります。
まとめ：App Serverは、Codexを自社体験に組み込むための土台
Codex App Serverは、Codexを単に使うだけでなく、自分のアプリや社内ツールの中に組み込むための土台です。Thread、Turn、Item、ストリーミングイベントを理解すると、Codexがどのように会話と作業を進めているかが見えてきます。まずはSDKとの違いを押さえ、小さなローカル検証から始めるのがよいでしょう。
コメント