Codex app-server: 標準入出力の JSON-RPC で、Codex を自分のアプリのバックエンドにする

codex app-server は VS Code 拡張が裏で使っているのと同じ仕組みで、標準入出力に1行1つの JSON を流して会話（thread）と作業（turn）を操作する。一度きりの実行なら Codex SDK、承認ダイアログや途中経過の表示を持つ常駐アプリなら app-server が向く。

最小の流れ

codex app-server を子プロセスで起動（既定は stdio。改行区切りの JSON）
initialize（clientInfo 付き）→ 返事を待って initialized 通知
thread/start（model 指定）→ 返ってきた thread.id で turn/start
item/started・item/completed・turn/completed などの通知を読み続ける

json

{"method":"initialize","id":0,"params":{"clientInfo":{"name":"my_app","title":"My App","version":"0.1.0"}}}
{"method":"initialized","params":{}}
{"method":"thread/start","id":1,"params":{"model":"gpt-6.1-sol"}}
{"method":"turn/start","id":2,"params":{"threadId":"thr_123","input":[{"type":"text","text":"Summarize this repo."}]}}

JSON-RPC 2.0 だが "jsonrpc":"2.0" は付けない
型は codex app-server generate-ts --out ./schemas（JSON Schema なら generate-json-schema）で、使っている Codex のバージョンに合ったものを生成できる

承認をアプリ側で受ける

コマンド実行やファイル変更に承認が要ると、サーバーから item/commandExecution/requestApproval・item/fileChange/requestApproval が届く
返す値は accept・acceptForSession・decline・cancel（コマンドは実行ポリシーの追加も可）

Claude Code との違い

@laiso によると、Claude Code の IDE 連携は WebSocket と MCP、Codex は標準入出力と独自 JSON-RPC。SDK は毎回プロセスを立てて引数を渡す形、app-server は送受信し続ける形なので、Codex をバックエンドにしたアプリに向く

注意点

WebSocket（--listen ws://...）は実験的でサポート外。ループバック以外で待ち受けると既定では認証なしになるので、--ws-auth を設定するか SSH のポート転送で使う
例のモデル名は公式ドキュメントのもの。使えるモデルは model/list で確かめる
CI や一括処理には Codex SDK を使うよう公式は勧めている

出典

@laiso · 2026-02-02
公式ドキュメント（Codex App Server）: developers.openai.com
OpenAI ブログ: openai.com