Codex app server

自社の製品の中に Codex を深く組み込み、認証、会話履歴、承認、エージェントのイベントのストリーミングを扱う場面に向けたものです。1 台のマシンで app-server を動かし、別のマシンから Codex CLI のターミナル UI を接続する使い方もできます。

Codex app server は、Codex がリッチクライアントを動かすために使うインターフェースで、実装は Codex の GitHub リポジトリでオープンソースとして公開されています。

• 通信は JSON-RPC 2.0 のメッセージによる双方向通信です。送受信するメッセージでは "jsonrpc":"2.0" のヘッダーを省きます。
• 既定のトランスポートは stdio (--listen stdio://) で、改行区切りの JSON (JSONL) を使います。
• --listen ws://IP:PORT で起動すると、同じリスナーが基本的な HTTP のヘルスチェックにも応答します。
• CLI から TypeScript のスキーマ、または JSON Schema の一式を生成できます。生成物は実行した Codex のバージョンに対応したものです。

• レビュー: review/start はスレッドに対して Codex のレビュー担当を実行し、レビュー結果を順に送ります。対象には未コミットの変更、ベースブランチ、コミット、独自の指示を指定できます。
• コマンド実行: command/exec は、スレッドを作らずにサーバーのサンドボックス内で 1 つのコマンドを実行します。
• スレッドのシェルコマンド: thread/shellCommand はサンドボックスの外でフルアクセスで動き、スレッドのサンドボックス方針を引き継ぎません。クライアントは、利用者が明示的に実行したコマンドに限って使わせる前提です。
• 承認: 利用者の Codex の設定によっては、コマンドの実行やファイルの変更に承認が必要になる場合があります。その際、app-server はサーバー側から JSON-RPC のリクエストをクライアントに送り、クライアントが判断の内容を返します。
• Skills: 入力テキストに $<skill-name> を含めるとスキルを呼び出せます。skill の入力項目を加えると、サーバーがスキルの指示全体を差し込みます。
• ファイルシステム: v2 のファイルシステム API は絶対パスで動作します。fs/watch を使うと、ファイルやディレクトリの変更に合わせてクライアントの画面の状態を更新し直せます。
• 認証: auth/account の JSON-RPC で、認証状態の確認、ログインの開始・取り消し、ログアウトができます。
• 接続ごとの設定: 実験的なメソッドとフィールドは capabilities.experimentalApi を true にすると有効になります。initialize.params.capabilities.optOutNotificationMethods にメソッド名を正確に指定すると、その接続で特定の通知を止められます。

Remote terminal UI mode の流れは次のとおりです。

1. codex app-server --listen ws://127.0.0.1:4500 で WebSocket のリスナーを起動します。
2. codex --remote ws://127.0.0.1:4500 でターミナル UI を接続します。
3. ローカル以外の接続では、WebSocket の認証を設定し、接続を TLS の背後に置きます。ベアラートークンは環境変数に保存し、コマンドラインにトークンを直接書かず、--remote-auth-token-env でその環境変数の名前を渡します。

同じ app-server のプロセス内の複数スレッドでリモートの Code Mode ホストを共有するには、そのホストの HTTP/2 gRPC エンドポイントを --code-mode-host に渡します。

• ループバック以外の WebSocket リスナーは、現在、展開期間中は既定で認証なしの接続を許可します。外部に公開する前に WebSocket の認証を設定する必要があります。
• exec-server への直接の WebSocket 接続は、app-server 経由で設定したものも含めてベアラートークンで保護できます。
• thread/shellCommand はサンドボックスの外でフルアクセスで動きます。
• App-server の認証は、商用サービスやホスト型サービスでの利用がこれまで許可されていません。
• app-server の診断情報では、プロバイダー、認証のリフレッシュ、アテステーションのフィールドを含めて資格情報を秘匿します。
• 非推奨だった codex mcp-server のエントリポイントは利用できなくなっています。
• daemon の自動起動は既定で有効です。ローカルのバックグラウンドサーバーを使わずに動かすときは --no-daemon を指定します。

対象のプランは公式のリリースノートには記載がありません。

基本の使い始めの流れは次のとおりです。

1. サーバーを起動します。codex app-server (既定の stdio トランスポート)、codex app-server --listen ws://127.0.0.1:4500 (TCP WebSocket)、codex app-server --listen unix:// (既定の Unix ソケット) のいずれかを使います。
2. 選んだトランスポートでクライアントを接続し、initialize を送ったあと、続けて initialized 通知を送ります。
3. スレッドとターンを開始し、アクティブなトランスポートのストリームから通知を読み続けます。