📖 この記事で分かること – App Serverは「自社サービスにCodexの脳を移植する窓口」だと一言で理解できる – Thread・Turn・Itemという3つの概念で全体像がつかめる – 30行のコードで実際に動かす最小実装が分かる – サブスクとAPIキー、自社用途に応じた選び方が分かる
💡 知っておきたい用語 – JSON-RPC：クライアントとサーバーが双方向に話せる通信規格。RESTが「手紙」なら、JSON-RPCは「電話」。一方が話している途中に、もう一方からも話しかけられる。
最終更新日: 2026年05月06日
30秒で分かるCodex App Server
Codex App Serverを一言で言うと、「自社サービスにCodexの脳を移植する窓口」です。
OpenAIは現在、Codexの脳（エージェントループ）を1つだけ作り、それをWeb・デスクトップ・VS Code拡張・CLIすべてで使い回しています。その共通の窓口がApp Serverです。
つまり「OpenAI公式の製品と同じバックエンドを、自社のフロントから繋いで使える」ということ。これが革命的なポイントです。
App Serverはクライアントとサーバー間のJSON-RPCプロトコルであり、Codexコアのスレッドをホストする長期稼働プロセスでもあります。
仕組みは3階層だけ覚えればいい
App Serverの通信構造は、メールの構造とほぼ同じです。
| App Serverの概念 | 役割 | メールに例えると |
|---|---|---|
| Thread（スレッド） | 会話全体を保存する箱 | メールのスレッド |
| Turn（ターン） | 1往復のやり取り | 1通のメール＋返信 |
| Item（アイテム） | 1つの出力単位 | メール本文の1段落・添付ファイル |
Codexが3つのファイルを編集してテストを実行するとき、画面で見ているのは1つのターンが複数のItemをストリーミングしている様子です。
この3階層を意識するだけで、App Serverのほとんどが理解できます。
通信の特徴は「双方向」であること
App Serverと普通のAPIの一番の違いは、サーバー側からも話しかけてくることです。
【普通のREST API】
クライアント → サーバー → クライアント
（クライアントから話しかけるだけ）
【App ServerのJSON-RPC】
クライアント ⇄ サーバー
（どちらからも話しかける）
なぜ双方向が必要かというと、エージェントの作業中に「このコマンド実行していい？」とサーバーから許可を取る必要があるからです。App Serverはサーバーイニシエーテッドのリクエストをクライアントに送り、クライアントが決定を返すという承認フローを採用しています。これがREST APIにはない特徴です。
通信路としてはstdio（標準入出力）を使ったJSONL形式が安定版・推奨です。クライアントはApp Serverを子プロセスとして起動し、双方向のstdioチャンネルで会話します。
最小実装：30行で動かす
理論はここまでにして、実際に動くコードを見ます。これが App Server の本体動作です。
import { spawn } from "node:child_process";
import readline from "node:readline";
// ① App Serverを子プロセスとして起動
const proc = spawn("codex", ["app-server"]);
const rl = readline.createInterface({ input: proc.stdout });
const send = (m: any) => proc.stdin.write(JSON.stringify(m) + "\n");
let threadId: string | null = null;
// ② サーバーからの返事を聞く
rl.on("line", (line) => {
const msg = JSON.parse(line);
// スレッド作成完了 → ターン開始
if (msg.id === 1 && msg.result?.thread?.id) {
threadId = msg.result.thread.id;
send({ method: "turn/start", id: 2, params: {
threadId, input: [{ type: "text", text: "このリポジトリを要約して" }],
}});
}
// テキストが流れてくる → 画面に出す
if (msg.method === "item/agentMessage/delta") {
process.stdout.write(msg.params.delta.text ?? "");
}
});
// ③ 必須の3ステップ：初期化 → 通知 → スレッド開始
send({ method: "initialize", id: 0, params: { clientInfo: { name: "my_app", version: "0.1.0" }}});
send({ method: "initialized", params: {} });
send({ method: "thread/start", id: 1, params: {} });
これだけでCodexエージェントが動きます。すべての接続は必ずinitializeから始め、続けてinitialized通知を送る必要があります。これを守らないとリクエストはすべて失敗します。
このコードを軸に、自社サービスでは「ユーザーの入力を turn/start の input に渡す」「item/agentMessage/delta を自社のUIに流す」を実装すれば、それだけでCodexバックエンド付きのアプリができます。
承認フロー：本番運用の肝
最小実装に1つだけ追加するなら、承認フローです。これがApp Serverの真価です。
// サーバーから「このコマンド実行していい？」と聞かれる
if (msg.method === "serverRequest/approval") {
console.log(`承認リクエスト: ${msg.params.command}`);
send({
id: msg.id, // ← 同じIDで返すのがJSON-RPCのルール
result: { decision: "accept" }, // accept / acceptForSession / decline / cancel
});
}
「エージェントが提案 → 人間が承認 → 実行」というワークフローがプロトコルレベルで組み込まれているため、勝手にコマンドが走るリスクが構造的に防げます。社内ツールに組み込むときの安心材料になります。
認証と課金：本番に持ち込む前の必須知識
App Serverには認証方式が2つあり、用途で選び方が変わります。ここを間違えると、思わぬ請求が発生します。
Codex App ServerはChatGPTアカウント（OAuth）でもAPIキーでもサインインできます。
| 方式 | 課金 | 向いている用途 |
|---|---|---|
| ChatGPTサブスクリプション | プランの利用枠を消費 | 個人開発・学習・試作 |
| APIキー | OpenAI Platformで従量課金 | 自社サービス・CI/CD・ヘッドレス運用 |
個人で試すならサブスクでOK
ChatGPT Plus・Pro・Business・Enterprise/Eduプランすべてに Codex が含まれています。普段ChatGPTを契約していれば、追加コストなしで App Server を動かせます。codex login でChatGPTアカウントを選ぶだけです。
自社サービスに組み込むならAPIキー一択
「自社サービスのバックエンドにCodexを移植する」用途では、実質APIキーが必須です。理由は3つあります。
1. ユーザーごとのChatGPTアカウントに依存できない エンドユーザー全員にChatGPTサブスクを契約させるのは現実的ではありません。
2. ヘッドレス環境で動かす必要がある プログラム的なCodex CLIワークフロー（CI/CDジョブなど）にはAPIキー認証が推奨されています。サーバー上で無人で動かすなら、ブラウザOAuthは使えません。
3. 課金の責任が自社に集約できる APIキーでサインインすると、作業はOpenAI Platformアカウントとプロジェクトに紐づきます。サービスアカウント・プロジェクト単位のキー・支出制御に向いており、アプリのバックエンド向けです。
# 自社サービス用：APIキーで認証
export OPENAI_API_KEY=sk-...
codex app-server # APIキーが優先される
⚠️ 注意：サブスクサインインで意図せずAPI課金が発生することがある
ChatGPT Proユーザーが「Sign in with ChatGPT」フローを使うと、選択したAPI組織/プロジェクトにAPIキーが自動作成されると報告されています。このキーを取り消すとCLIが401エラーで動かなくなる、という挙動も報告されています。
「サブスクで使っているつもりがAPI側で課金されていた」という事故が起こりうるので、本番運用前に必ずOpenAI Platformの使用量ダッシュボードで実際の課金経路を確認することをお勧めします。
課金経路の選び方フロー
何が作れるか：5つのアイデア
仕組みが分かったところで、これで何ができるかを具体化します。
① 社内コードレビューBot Slackでコードを貼ると、Codexがレビューを返す。Threadを保持すれば「前の指摘を踏まえて」という会話が成立します。
② 半自動デプロイフロー PRを解析してデプロイ手順を提案 → エンジニアが承認 → 実行。承認フローがそのまま使えます。
③ 自然言語での社内ツール操作 「○○の設定を変えて」と書くと、Codexが対象ファイルを探して編集 → 差分をレビュー画面に表示。
④ マルチエージェント並列処理 複数Threadを並列起動して、リファクタリングやテスト生成を分散実行。
⑤ カスタムIDE App ServerクライアントはGo・Python・TypeScript・Swift・Kotlinで実装されており、独自エディタにもCodexを組み込めます。
最初の一歩：今日やること
理解したら手を動かすのが一番です。最初の一歩はこの1つに絞ります。
# 1. インストール
npm install -g @openai/codex
# 2. 認証（個人で試すならどちらかを選ぶ）
codex login # ChatGPTサブスクを使う
# または
export OPENAI_API_KEY=sk-... # APIキーで従量課金
# 3. App Serverを起動して、初期化メッセージを手で打ってみる
codex app-server
{"method":"initialize","id":0,"params":{"clientInfo":{"name":"test","version":"0.1.0"}}}
{"method":"initialized","params":{}}
{"method":"thread/start","id":1,"params":{}}
ターミナルで手打ちして返事を見る。これだけで、JSON-RPC over stdioの感覚がつかめます。ここまで来たら、上の30行コードに進めばすぐクライアントが書けます。
よくある質問
Q: REST APIとは何が根本的に違うのですか？
A: RESTは「リクエスト1つ → レスポンス1つ」の同期型ですが、App Serverは「1つのリクエスト → イベントが何十個もストリームされる」非同期型で、サーバー側からもリクエストが来ます。エージェントの「考えながら動く」という性質には双方向・非同期が必要なんです。
Q: ChatGPT Plus契約者は、追加課金なしでApp Serverを使えますか？
A: 個人での利用ならYesです。ChatGPT PlusにはCodexが含まれています。ただし、自社サービスのバックエンドとして組み込む用途ではAPIキー認証が現実的です。また、サブスクサインインでAPIキーが裏で発行される挙動も報告されているので、Platformの使用量画面で実際の課金経路を確認することをお勧めします。
Q: MCPサーバーとして使うのとどう違いますか？
A: MCPサーバーとして起動する方法もありますが、App Serverの方が機能が豊富です。会話状態・承認フロー・ストリーミングの細かい制御はApp Serverが優れているので、長期的なエージェント統合にはApp Serverが推奨されています。
Q: 本番で気をつけることは？
A: リクエストが飽和するとJSON-RPCエラーコード -32001（Server overloaded）が返るので、指数バックオフでリトライしてください。あとはCodexのバージョンをピン留めし、アップデート後は codex app-server generate-ts でスキーマを再生成することです。
まとめ
Codex App Serverは「AIにコードを書かせるAPI」ではなく、自社サービスにCodexの脳を丸ごと移植するための窓口です。
理解の地図はこれだけです。
- 役割を理解する: 「自社のフロント × OpenAI公式のバックエンド」が成立する
- 構造を理解する: Thread → Turn → Item の3階層
- 通信を理解する: 双方向のJSON-RPC over stdio
- 動かす: 30行のコードで疎通確認
- 認証を選ぶ: 個人ならサブスク、自社サービスならAPIキー
- 拡張する: 承認フローを足して本番品質に
ターミナルでJSONを手打ちしてみる。それが最初の一歩です。
【用語解説】
- JSON-RPC【ジェイソン・アールピーシー】: JSON形式のリモート呼び出し規格。App Serverは独自バリアントで、
"jsonrpc":"2.0"ヘッダーを省略してJSONLとしてstdioに流す。 - stdio【スタンダードアイオー】: プログラムの標準入出力。App Serverはこれを通信路として使い、子プロセスとして起動する。
- JSONL【ジェイソンエル】: 1行1JSONのテキストフォーマット。ストリーミングと相性が良い。
- サーバーイニシエーテッドリクエスト: サーバー側から先にリクエストを送る仕組み。承認フローがこれで実現される。
- Thread ID: 会話セッションのユニーク識別子。プロセス再起動後も会話を再開でき、フォークも可能。
- OAuth【オーオース】: ID/パスワードを直接渡さず、トークン経由で認証する仕組み。ChatGPTサインインはこの方式。
免責事項: 本記事の情報は執筆時点のものです。AI技術と料金体系は急速に変化しているため、機能・価格・認証フローは予告なく変更される場合があります。実装前に必ず公式ドキュメントの最新版を確認してください。
引用元:
- [1] OpenAI Engineering Blog – Unlocking the Codex harness – https://openai.com/index/unlocking-the-codex-harness/
- [2] OpenAI Developers – App Server公式ドキュメント – https://developers.openai.com/codex/app-server
- [3] OpenAI Developers – Authentication公式ドキュメント – https://developers.openai.com/codex/auth
- [4] OpenAI Developers – Pricing公式ドキュメント – https://developers.openai.com/codex/pricing
- [5] GitHub openai/codex – App Server README – https://github.com/openai/codex/blob/main/codex-rs/app-server/README.md
- [6] OpenAI Help Center – Using Codex with your ChatGPT plan – https://help.openai.com/en/articles/11369540-using-codex-with-your-chatgpt-plan
15年以上の開発経験を持つソフトウェアエンジニア。クラウドやWeb技術に精通し、業務システムからスタートアップ支援まで幅広く手掛ける。近年は、SaaSや業務システム間の統合・連携開発を中心に、企業のDX推進とAI活用を支援。
技術だけでなく、経営者やビジネスパーソンに向けた講演・執筆を通じて、生成AIの最新トレンドと実務への落とし込みをわかりやすく伝えている。
また、音楽生成AIのみで構成したDJパフォーマンスを企業イベントで展開するなど、テクノロジーと表現の融合をライフワークとして探求している。
