Codex App Server入門：自社サービスにCodexの脳を組み込む窓口

📖 この記事で分かること

• App Serverは自社サービスにCodexの脳を組み込む窓口
• Thread・Turn・Itemの3概念で全体像がつかめる
• 30行のコードで動かす最小実装が分かる
• サブスクとAPIキー、用途別の選び方が分かる

💡 知っておきたい用語

• JSON-RPC:クライアントとサーバーが双方向に話せる通信規格。RESTが「手紙」なら、JSON-RPCは「電話」。片方が話す途中に、もう片方からも話しかけられる。

---

最終更新日: 2026年7月21日

30秒で分かるCodex App Server

この記事のポイント

• OpenAIのCodex App Serverは、Web・CLI・VS Code拡張・macOSアプリ共通の同じエージェントループ(ハーネス)を自社製品から呼び出せる、双方向JSON-RPCのインターフェース。
• Thread・Turn・Itemの3階層と、initialize→initialized→thread/start の30行で最小動作。
• 利用はChatGPTの各プラン(Free〜Enterprise)に含まれ、Plusは月額20ドル(2026年7月時点)。自社サービス組み込みはAPIキー認証が現実的。

Codex App Serverを一言で言うと、「自社サービスにCodexの脳を組み込む窓口」です。

OpenAIのコーディングエージェントCodexは、Webアプリ・CLI・IDE拡張・macOSアプリなど複数の表面に存在し、その裏側はすべて同じCodexハーネス(すべてのCodex体験の基盤となるエージェントループとロジック)で動いている。それらをつなぐ決定的なリンクが、双方向JSON-RPC APIであるCodex App Serverです。

つまり 「OpenAI公式の製品と同じバックエンドを、自社のフロントから繋いで使える」 ということです。これはもともとTUIループを模したJSON-RPCプロトコルとして始まり、App Serverの非公式な初版になった経緯があります。

App Serverは、Codexがリッチクライアント(例:Codex VS Code拡張)を動かすためのインターフェースであり、認証・会話履歴・承認・ストリーミングされるエージェントイベントを含む深い統合を自社製品の中で行いたいときに使います。

仕組みは3階層だけ覚えればいい

App Serverの通信構造は、メールの構造とほぼ同じです。

App Serverの概念	役割	メールに例えると
Thread（スレッド）	会話全体を保存する箱	メールのスレッド
Turn（ターン）	1往復のやり取り	1通のメール＋返信
Item（アイテム）	1つの出力単位	メール本文の1段落・添付ファイル

Codexが3つのファイルを編集してテストを実行するとき、画面で見ているのは1つのターンが複数のItemをストリーミングしている様子です。この3階層を意識するだけで、App Serverのほとんどが理解できます。

Codexそのものの位置づけや「Model + Harness」という整理は、AIエージェントは「モデル＋ハーネス」で捉える整理も参考になります。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バックエンド付きのアプリができます。なお、thread/start では model パラメータでモデルを指定できます（公式ドキュメントの例では gpt-5.4 等のGPT-5系が示されています。2026年7月時点。使えるモデルは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

Work modeとCodexは、ChatGPTのFree・Go・Plus・Pro・Business・Edu・Enterpriseの各プランに含まれています（2026年7月時点）。公開されている個人向け価格は、Freeが月額0ドル、Goが月額8ドル、Plusが月額20ドル、Proが月額100ドル、Pro 20xが月額200ドルです。普段ChatGPTを契約していれば、そのプランの利用枠内でApp Serverを動かせます。codex login でChatGPTアカウントを選ぶだけです。

なお課金体系は2026年4月2日に、メッセージ単位からAPIトークン使用量に沿った課金へ更新され、新規・既存のPlus・Pro・ChatGPT Business・新規ChatGPT Enterpriseプランに適用されました。使用量は入力・キャッシュ入力・出力トークンで消費されるため、タスクの規模で変動します。

自社サービスに組み込むならAPIキー一択

「自社サービスのバックエンドにCodexを組み込む」用途では、実質APIキーが必須です。理由は3つあります。

1. ユーザーごとのChatGPTアカウントに依存できない エンドユーザー全員にChatGPTサブスクを契約させるのは現実的ではありません。

2. ヘッドレス環境で動かす必要がある APIキー利用は、ローカルワークフロー、CI/CDジョブ、プログラム的なCodex CLIワークフロー、SDK利用、共有エンジニアリング環境での自動化に向いています。サーバー上で無人で動かすなら、ブラウザOAuthは使えません。

3. 課金の責任が自社に集約できる APIキーでサインインすると、使用量はOpenAI Platformアカウントを通じて標準APIレートで課金され、ChatGPTプランのクレジットとは別建てになります。サービスアカウント・プロジェクト単位のキー・支出制御に向いており、アプリのバックエンド向けです。

自社サービス用のAPIキー認証は次のように起動します。

export OPENAI_API_KEY=sk-...
codex app-server  # APIキーが優先される

⚠️ 注意：サブスクサインインで意図せずAPI課金が発生することがある

ChatGPT Proユーザーが「Sign in with ChatGPT」フローを使うと、選択したAPI組織/プロジェクトにAPIキーが自動作成されると報告されています。このキーを取り消すとCLIが401エラーで動かなくなる、という挙動も報告されています。

「サブスクで使っているつもりがAPI側で課金されていた」という事故が起こりうるので、本番運用前に必ずOpenAI Platformの使用量ダッシュボードで実際の課金経路を確認してください。APIキー認証では、ChatGPTワークスペースアクセスやクラウドサービスに依存する一部機能が制限または利用不可になる場合がある点にも注意が必要です。

何が作れるか：5つのアイデア

仕組みが分かったところで、これで何ができるかを具体化します。

① 社内コードレビューBot Slackでコードを貼ると、Codexがレビューを返す。Threadを保持すれば「前の指摘を踏まえて」という会話が成立します。

② 半自動デプロイフロー PRを解析してデプロイ手順を提案 → エンジニアが承認 → 実行。承認フローがそのまま使えます。

③ 自然言語での社内ツール操作 「○○の設定を変えて」と書くと、Codexが対象ファイルを探して編集 → 差分をレビュー画面に表示。

④ マルチエージェント並列処理 複数Threadを並列起動して、リファクタリングやテスト生成を分散実行。

⑤ カスタムIDE App Serverクライアントは複数言語で実装できるため、独自エディタにもCodexを組み込めます。オンプレミス運用の可能性については、OpenAIとDellの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行コードに進めばすぐクライアントが書けます。

編集部の見方

編集部は、自社サービスへの本番組み込みでは「PoC はサブスク、本番は API キー」の使い分けが最も現実的だと考えます。技術的な導入ハードルより、課金経路の設計を先に決めるべきというのが結論です。

根拠は3点あります。第一に、App Serverは認証・会話履歴・承認・ストリーミングを含む深い統合を自社製品内で行うための公式インターフェースであるため、ステート管理をOpenAI側に寄せられ、会話履歴DBを自作する手間が省けます。第二に、Thread/Turn/Itemの3階層は概念が明快で、30行で最小動作が組めるほど学習コストが低い点。第三に、2026年4月に課金がトークン単位へ移行し、タスク規模でコストが変動するため、無人運用の自社サービスではAPIキー＋予算上限の設計が事故防止に直結する点です。

この見方が変わる条件は、エンドユーザーが全員ChatGPT有料プランを持つ社内限定ツールの場合です。その構成ならサブスク認証のまま本番運用でき、APIキーの課金設計は不要になります。競合との位置づけとしては、Anthropic・Google・OpenAIが各社「自社モデルを他者サービスに埋め込ませるSDK層」を整備しつつあり、選定軸は使いたいモデル・料金体系・自社業務との適合度に移っています。

---

よくある質問

Q: REST APIとは何が根本的に違うのですか？

A: RESTは「リクエスト1つ → レスポンス1つ」の同期型ですが、App Serverは「1つのリクエスト → イベントが何十個もストリームされる」非同期型で、サーバー側からもリクエストが来ます。エージェントの「考えながら動く」という性質には双方向・非同期が必要です。

Q: ChatGPT Plus契約者は、追加課金なしでApp Serverを使えますか？

A: 個人での利用ならYesです。ChatGPTのFree・Go・Plus・Pro・Business・Edu・Enterpriseの各プランにCodexが含まれています。ただし、自社サービスのバックエンドとして組み込む用途ではAPIキー認証が現実的です。また、サブスクサインインでAPIキーが裏で発行される挙動も報告されているので、Platformの使用量画面で実際の課金経路を確認してください。

Q: MCPサーバーとして使うのとどう違いますか？

A: MCPサーバーとして起動する方法もありますが、App ServerプロトコルはSDKより機能範囲が広く、リッチな製品統合向けに設計されています。会話状態・承認フロー・ストリーミングの細かい制御が必要な長期的なエージェント統合にはApp Serverが向きます。

Q: 本番で気をつけることは？

A: リクエスト受信が飽和すると、新規リクエストはJSON-RPCエラーコード-32001「Server overloaded; retry later.」で拒否されるため、クライアントはリトライ可能とみなしてジッター付きの指数バックオフを使うべきです。あわせてCodexのバージョンを固定し、アップデート後は codex app-server generate-ts でスキーマを再生成すると安全です。

---

まとめ

Codex App Serverは「AIにコードを書かせるAPI」ではなく、自社サービスにCodexの脳を組み込むための窓口です。役割（自社フロント×OpenAI公式バックエンド）、構造（Thread→Turn→Item）、通信（双方向JSON-RPC over stdio）、最小実装（30行）、認証（個人はサブスク、自社サービスはAPIキー）、拡張（承認フロー）の6点を押さえれば全体像がつかめます。課金は2026年4月にトークン単位へ移行しているため、本番前に使用量ダッシュボードで課金経路の確認を推奨します。

---

💡 編集部メモ

App Serverの面白さは「OpenAIが自社製品を動かしているのと同じハーネスを、そのまま外に開いた」点にあります。VS Code拡張もmacOSアプリも同じ口を叩いているので、公式クライアントの挙動がそのまま実装リファレンスになります。次に注目したいのは、OpenAIがJSON-RPCを書かずに済むSDKをどこまで各言語に広げるか。ここが整うと、社内ツールへの組み込み難度は一段下がりそうです。

---

【用語解説】

• JSON-RPC: JSON形式のリモート呼び出し規格。App Serverは独自バリアントで、"jsonrpc":"2.0" ヘッダーを省略してJSONLとしてstdioに流す。
• stdio: プログラムの標準入出力。App Serverはこれを通信路として使い、子プロセスとして起動する。
• OAuth【オーオース】: ID/パスワードを直接渡さず、トークン経由で認証する仕組み。ChatGPTサインインはこの方式。

---

免責事項: 本記事の情報は執筆時点のものです。AI技術と料金体系は急速に変化しているため、機能・価格・認証フローは予告なく変更される場合があります。実装前に必ず公式ドキュメントの最新版を確認してください。

---

この記事について: AI 支援で執筆、編集部が事実確認・編集しています。誤りや追加情報があれば Contact よりお知らせください。

---

関連する導入検討の記事は以下も参考になります:

OpenAIとDellがCodex提携。オンプレミスで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 – Codex Pricing公式ドキュメント – https://developers.openai.com/codex/pricing
• [4] GitHub openai/codex – App Server README – https://github.com/openai/codex/blob/main/codex-rs/app-server/README.md