［開発者向け Codexを既存業務へ組み込む——exec・SDK・app-serverの選び方

2026-08-20

はじめに

　OpenAIが 2026年8月19日、Codexを既存の製品や業務画面へ組み込むためのオープンなエージェントハーネスを解説しました。本稿では、codex exec、Codex SDK、app-serverの使い分けと、物流サンプル「Relay」に見る実装設計を整理します。

参考記事

メイン記事:
タイトル: Codex as a platform: build on the open agent harness
著者: Nicolas Bonamy、Derrick Choi
発行元: OpenAI Developers
発行日: 2026年8月19日
URL: https://developers.openai.com/blog/codex-as-a-platform

要点

Codexハーネスは文脈維持、道具利用、進捗、失敗処理、承認、結果返却を担うオープンソースのエージェント実行基盤である
単発処理とCIにはcodex exec、プログラムからのタスク制御にはCodex SDK、製品内の深い統合にはapp-serverを使い分ける
製品側は業務画面、文脈、記録、MCPツール、承認条件を所有し、Codexはエージェントループを提供する
サンプルアプリRelayは配送ダッシュボードへCodexを埋め込み、再予約前に人間の承認を必須にしている
Thrive HoldingsとCreteの試験では7,000件の税務申告を処理し、準備時間を約3分の1短縮した

詳細解説

再利用できるのはモデル呼び出しより外側の仕組み

　AIエージェントは、プロンプトをモデルへ送り、答えを受け取るだけではありません。タスクを理解し、文脈を持ち続け、必要な情報を調べ、道具を呼び、途中経過を示し、失敗から復旧し、重要な操作では人に承認を求め、結果を業務システムへ返す必要があります。この一連の実行系がハーネスです。

　OpenAIによれば、ARC-AGI-3では推論の保持とコンテキスト圧縮を組み合わせることで、GPT-5.6 Solのスコアが13.3%から38.3%へ上がり、出力トークンは6分の1になりました。モデルが同じでも、どの文脈を残し、どの順序で道具を使わせるかによって結果とコストが変わることを示す例です。

　CodexのApp、CLI、IDE Extensionは同じオープンソースのハーネスを利用しています。開発者はCodexのエージェントループを扱った過去記事と合わせて、モデルの前後にある状態管理、道具、承認の設計を確認できます。

3つの統合レイヤーを選ぶ

　OpenAIは、用途に応じて三つの統合方法を示しています。

codex exec: スクリプト、CIジョブ、単発のバックグラウンド処理に向きます。範囲を限定したエージェント作業を非対話で実行し、構造化した結果を後続処理へ渡す用途です。
Codex SDK: アプリケーションコードからCodexのスレッドを開始、継続、再開したい場合に使います。CI/CD、社内ツール、自社アプリの処理へ組み込む中間レイヤーです。
Codex app-server: エージェントを製品体験そのものへ組み込む場合に使います。会話履歴、イベントのストリーミング、割り込み、道具、承認、画面更新を製品側で細かく制御できます。

　SDKは一般的なプログラム制御を簡単にし、app-serverはライフサイクルとユーザー体験を直接制御します。既存のapp-server解説を踏まえると、最初から最も低い層を選ぶのではなく、必要な画面統合と承認制御の深さから決める方法が適切です。

前提条件とCodex SDKの最小構成

　TypeScript版Codex SDKはサーバー側で使い、Node.js 18以上が必要です。以下の公式コマンドで導入します。

#TypeScript版Codex SDKを現在のプロジェクトへ追加します

npm install @openai/codex-sdk

　次の公式例は、スレッドを開始し、同じスレッドへ依頼を送る最小構成です。日本語コメントだけを補っています。

// Codex SDKのクライアントを読み込みます

import { Codex } from "@openai/codex-sdk";

// ローカルのCodex実行環境へ接続するクライアントを作ります

const codex = new Codex();

// 新しい会話スレッドを開始します

const thread = codex.startThread();

// スレッドへ作業依頼を送り、完了まで待ちます

const result = await thread.run(

  "Make a plan to diagnose and fix the CI failures"

);

// Codexが返した最終応答を表示します

console.log(result.finalResponse);

　同じthreadへ再度run()を呼べば作業を継続できます。保存済みのスレッドIDがある場合はresumeThread(threadId)で再開します。実際の製品では、スレッドIDを業務レコードと対応付け、誰が再開できるか、保持期間をどうするかを決める必要があります。

　SDKを採用する場合も、エージェントへ任せる範囲をコード上で限定します。入力へ含めるリポジトリやログ、利用できる道具、作業ディレクトリ、サンドボックス、失敗時の再試行回数をアプリ側で管理します。最終応答だけを保存するのではなく、業務レコードとスレッドID、承認履歴、処理結果を対応付けると、後から実行経緯を追いやすくなります。

app-serverで製品体験を制御する

　app-serverは、標準入力・出力のJSONLを既定の通信方法とし、スレッド、ターン、アイテム、承認要求をイベントとして扱います。クライアントは接続後にinitializeとinitializedを送り、thread/startで会話を作成し、turn/startで依頼を開始します。処理中は道具実行や差分、承認要求、応答の増分を受け取ります。

　ローカルのWebSocketで試す場合、公式文書は次のコマンドを示しています。

#ローカルホストの4500番ポートでapp-serverを起動します

codex app-server --listen ws://127.0.0.1:4500

#別のCLIから同じapp-serverへ接続します

codex --remote ws://127.0.0.1:4500

　WebSocket通信は実験的で、本番サポート対象ではありません。平文のws://はローカルホストかSSHポート転送に限定し、外部接続ではTLSを使うwss://と認証を設定する必要があります。トークンをコマンド行へ直接書かず、ファイルや環境変数で管理します。

　注意: app-serverのWebSocketを外部ネットワークへそのまま公開しないでください。公式文書では、非ループバックのリスナーを使う場合に認証を設定し、TLSで保護する必要があると説明しています。本番利用では、実験的機能のサポート範囲と更新時の互換性も確認します。

　app-serverを選ぶ価値は、承認を製品のUIへ統合できる点にあります。ファイル変更、コマンド、MCPツールなどの要求を、製品側の役割と業務規則に照らして許可、拒否、中止できます。モデルに全権を渡すのではなく、影響の大きい操作を既存の承認フローへ戻します。

Relayに見る責任分担

　Relayは、架空の配送ダッシュボードへCodexを組み込んだサンプルです。利用者は自由入力から始めず、対象の配送を選び「Compare recovery」を押します。アプリが配送の文脈を渡し、Codexはアプリ所有のMCPツールで最新のサンプル運用データを取得し、復旧案を説明します。

　配送の再予約は業務記録を書き換えるため、人間の承認後だけ実行します。道具が記録を更新したら、アプリは業務画面を再読み込みします。Codexは会話状態、進捗、道具利用を担いますが、ダッシュボード、記録、ビジネスルール、承認ボタンは製品側に残ります。

　この分担は物流以外にも応用できます。セキュリティ調査ではアラートと影響サービス、顧客サポートでは契約履歴とログ、製品開発ではタスクボードを主画面にします。汎用チャットへ利用者を移すのではなく、業務を理解する既存画面の横でエージェントを働かせます。

公開事例と導入時の確認点

　GitHubとJetBrainsは既存IDEへCodexを統合し、CiscoはCisco Cloud ControlのApp BuilderでCodex SDKを利用しています。OpenAIによれば、Thrive HoldingsとCreteの税務準備試験では7,000件の申告を処理し、準備時間を約3分の1短縮しました。実務家のフィードバックを処理へ戻した点も重要です。

　導入前には、製品が所有する文脈、Codexへ公開する道具、書き込み前の承認、結果を戻す記録システム、失敗時の再実行と監査ログを定義します。また、オープンソースなのはハーネスと統合面であり、モデルへのアクセスや管理サービスは別である点にも注意が必要です。技術選択だけでなく、業務側の責任分界を先に決めることが重要だと思います。