App Server | Codex で構築 | ChatGPT ドキュメント

Codex app-server は、Codex が高機能なクライアント（Codex VS Code 拡張機能など）を動作させるために使用するインターフェースです。認証、会話履歴、承認、ストリーミングされるエージェントイベントなど、自社製品内に緊密に統合したい場合に使用します。app-server の実装は、Codex GitHub リポジトリ（openai/codex/codex-rs/app-server）でオープンソースとして公開されています。オープンソースの Codex コンポーネントの全一覧については、オープンソースページをご覧ください。

CLI ターミナル UI に接続する

リモートターミナル UI モードでは、あるマシンで app-server を実行し、別のマシンから Codex CLI のターミナルインターフェースに接続できます。WebSocket リスナーを起動します。

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

次に、ターミナル UI に接続します。

codex --remote ws://127.0.0.1:4500

ローカル以外から接続する場合は、WebSocket 認証を設定し、接続を TLS の背後に配置してください。ベアラートークンを環境変数に保存し、コマンドラインにトークンを直接指定する代わりに、その環境変数名を渡します。

export CODEX_REMOTE_TOKEN="$(cat "$HOME/.codex/app-server-token")"
codex --remote wss://remote-host:4500 \
  --remote-auth-token-env CODEX_REMOTE_TOKEN

--remote オプションは、ws://、wss://、unix://、 unix://PATH の各エンドポイントを受け付けます。暗号化されていない WebSocket は、localhost または SSH でポートフォワーディングされた接続にのみ使用してください。

リモート Code Mode ホストに接続する

デフォルトでは、app-server はローカルの Code Mode ホストを起動します。代わりにリモートホストを使用するには、そのセキュアな WebSocket URL を渡します。

codex app-server --code-mode-host wss://code-mode.example.com/host

--code-mode-host は、app-server から Code Mode ホストへの送信接続を制御します。クライアントから app-server への接続方法を制御する --listen は変更しません。同じ app-server プロセス内のすべてのスレッドは、選択された Code Mode ホスト接続を共有します。

リモートホストには wss:// を使用してください。ws:// は localhost または SSH で転送された接続にのみ使用してください。app-server コマンドと WebSocket トランスポートは実験的な機能であり、本番ワークロードではサポートされていません。

プロトコル

MCP と同様に、codex app-server は JSON-RPC 2.0 メッセージを使用した双方向通信をサポートします（通信時には "jsonrpc":"2.0" ヘッダーが省略されます）。

サポートされるトランスポートは次のとおりです。

stdio（--listen stdio://、デフォルト）：改行区切りの JSON（JSONL）。
websocket（--listen ws://IP:PORT、実験的でサポート対象外）：WebSocket のテキストフレームごとに 1 つの JSON-RPC メッセージ。
Unix ソケット（--listen unix:// または --listen unix://PATH）：標準の HTTP Upgrade ハンドシェイクを使用し、 Codex のデフォルトの app-server 制御ソケットまたはカスタム Unix ソケットパス経由で接続する WebSocket。
off（--listen off）：ローカルトランスポートを公開しません。

--listen ws://IP:PORT で実行すると、同じリスナーが基本的な HTTP ヘルスプローブにも応答します。

リスナーが新しい接続を受け付けられるようになると、GET /readyz は 200 OK を返します。
リクエストに Origin ヘッダーが含まれていない場合、GET /healthz は 200 OK を返します。
Origin ヘッダーを含むリクエストは、403 Forbidden で拒否されます。

WebSocket トランスポートは実験的で、サポート対象外です。 ws://127.0.0.1:PORT などのローカルリスナーは、localhost や SSH ポートフォワーディングを使用するワークフローに適しています。現在、ループバック以外の WebSocket リスナーはロールアウト期間中、デフォルトで認証なしの接続を許可するため、リモートに公開する前に WebSocket 認証を設定してください。

サポートされる WebSocket 認証フラグは次のとおりです。

--ws-auth capability-token --ws-token-file /absolute/path
--ws-auth capability-token --ws-token-sha256 HEX
--ws-auth signed-bearer-token --ws-shared-secret-file /absolute/path

署名付きベアラートークンでは、--ws-issuer、--ws-audience、 --ws-max-clock-skew-seconds も設定できます。クライアントは WebSocket ハンドシェイク中に Authorization: Bearer <token> として資格情報を提示し、app-server は JSON-RPC initialize より前に認証を適用します。

生のベアラートークンをコマンドラインで渡すより、--ws-token-file を推奨します。 --ws-token-sha256 は、クライアントが生の高エントロピートークンを別のローカルシークレットストアに保持する場合にのみ使用してください。ハッシュは検証子にすぎず、クライアントには引き続き元のトークンが必要です。

WebSocket モードでは、app-server は容量制限付きキューを使用します。リクエストの受信キューが満杯になると、サーバーは新しいリクエストを JSON-RPC エラーコード -32001 とメッセージ "Server overloaded; retry later." で拒否します。クライアントは、指数関数的に増加する遅延とジッターを使用して再試行してください。

メッセージスキーマ

リクエストには method、params、id が含まれます。

{ "method": "thread/start", "id": 10, "params": { "model": "gpt-5.6-terra" } }

レスポンスは、result または error とともに id をそのまま返します。

{ "id": 10, "result": { "thread": { "id": "thr_123" } } }

{ "id": 10, "error": { "code": 123, "message": "Something went wrong" } }

通知では id を省略し、method と params のみを使用します。

{ "method": "turn/started", "params": { "turn": { "id": "turn_456" } } }

CLI から TypeScript スキーマまたは JSON Schema バンドルを生成できます。各出力は実行した Codex のバージョンに固有であるため、生成された成果物はそのバージョンと正確に一致します。

codex app-server generate-ts --out ./schemas
codex app-server generate-json-schema --out ./schemas

はじめに

codex app-server（デフォルトの stdio トランスポート）、 codex app-server --listen ws://127.0.0.1:4500（TCP WebSocket）、または codex app-server --listen unix://（デフォルトの Unix ソケット）でサーバーを起動します。
選択したトランスポート経由でクライアントを接続し、initialize、続いて initialized 通知を送信します。
スレッドとターンを開始し、アクティブなトランスポートストリームから通知を継続して読み取ります。

例（Node.js / TypeScript）：




const proc = spawn("codex", ["app-server"], {
  stdio: ["pipe", "pipe", "inherit"],
});
const rl = readline.createInterface({ input: proc.stdout });

const send = (message: unknown) => {
  proc.stdin.write(`${JSON.stringify(message)}\n`);
};

let threadId: string | null = null;

rl.on("line", (line) => {
  const msg = JSON.parse(line) as any;
  console.log("server:", msg);

  if (msg.id === 1 && msg.result?.thread?.id && !threadId) {
    threadId = msg.result.thread.id;
    send({
      method: "turn/start",
      id: 2,
      params: {
        threadId,
        input: [{ type: "text", text: "Summarize this repo." }],
      },
    });
  }
});

send({
  method: "initialize",
  id: 0,
  params: {
    clientInfo: {
      name: "my_product",
      title: "My Product",
      version: "0.1.0",
    },
  },
});
send({ method: "initialized", params: {} });
send({ method: "thread/start", id: 1, params: { model: "gpt-5.6-terra" } });

中核となるプリミティブ

スレッド：ユーザーと Codex エージェントの間の会話です。スレッドにはターンが含まれます。
ターン：1 件のユーザーリクエストと、それに続くエージェントの作業です。ターンには項目が含まれ、増分更新がストリーミングされます。
項目：入力または出力の単位です（ユーザーメッセージ、エージェントメッセージ、コマンド実行、ファイル変更、ツール呼び出しなど）。

スレッド API を使用して、会話を作成、一覧表示、アーカイブします。ターン API で会話を進め、ターン通知を通じて進捗をストリーミングします。

ライフサイクルの概要

接続ごとに 1 回初期化する：トランスポート接続を開いた直後に、クライアントのメタデータを含む initialize リクエストを送信し、続いて initialized を送出します。このハンドシェイクより前にその接続で送信されたリクエストは、サーバーによって拒否されます。
スレッドを開始（または再開）する：新しい会話には thread/start、既存の会話の続行には thread/resume、履歴を新しいスレッド ID に分岐するには thread/fork を呼び出します。
ターンを開始する：対象の threadId とユーザー入力を指定して turn/start を呼び出します。任意のフィールドでモデル、パーソナリティ、cwd、サンドボックスポリシーなどを上書きできます。
アクティブなターンに追加指示を送る：turn/steer を呼び出すと、新しいターンを作成せずに、現在進行中のターンへユーザー入力を追加できます。
イベントをストリーミングする：turn/start の後も stdout から通知を読み続けます。thread/archived、thread/unarchived、item/started、item/completed、item/agentMessage/delta、ツールの進捗、その他の更新が送られます。
ターンを終了する：モデルが処理を完了したとき、または turn/interrupt によるキャンセル後に、サーバーは最終ステータスを含む turn/completed を送出します。

初期化

クライアントは、接続上のほかのメソッドを呼び出す前に、トランスポート接続ごとに initialize リクエストを 1 回送信し、その後 initialized 通知で応答確認する必要があります。初期化前に送信されたリクエストには Not initialized エラーが返され、同じ接続で initialize を繰り返し呼び出すと Already initialized が返されます。

サーバーは、上流サービスに提示するユーザーエージェント文字列に加え、実行対象を表す platformFamily と platformOs の値を返します。統合を識別するために clientInfo を設定してください。

initialize.params.capabilities は、次のクライアント機能もサポートします。

optOutNotificationMethods - この接続で抑制する通知メソッドの正確な名前です。一致判定は完全一致です（ワイルドカードやプレフィックスは使用できません）。不明な名前は受け付けられ、無視されます。
requestAttestation - サーバーが開始する attestation/generate リクエストを受け取るようオプトインします。上流のアテステーションを提供するデスクトップホストは、不透明な { "token": "..." } 値で応答します。
mcpServerOpenaiFormElicitation - 下流の MCP サーバーが OpenAI 拡張形式の mcpServer/elicitation/request を送信できるようにします。

重要: OpenAI Compliance Logs Platform でクライアントを識別するには、clientInfo.name を使用してください。エンタープライズでの利用を目的とした新しい Codex インテグレーションを開発している場合は、既知のクライアント一覧に追加するため、OpenAI までお問い合わせください。詳細については、Codex ログリファレンスを参照してください。

例（Codex VS Code 拡張機能から）：

{
  "method": "initialize",
  "id": 0,
  "params": {
    "clientInfo": {
      "name": "codex_vscode",
      "title": "Codex VS Code Extension",
      "version": "0.1.0"
    }
  }
}

通知をオプトアウトする例：

{
  "method": "initialize",
  "id": 1,
  "params": {
    "clientInfo": {
      "name": "my_client",
      "title": "My Client",
      "version": "0.1.0"
    },
    "capabilities": {
      "experimentalApi": true,
      "optOutNotificationMethods": ["thread/started", "item/agentMessage/delta"]
    }
  }
}

実験的 API のオプトイン

一部の app-server メソッドとフィールドは、意図的に experimentalApi 機能によって制限されています。

安定版の API サーフェスを使用し続けるには、capabilities を省略（または experimentalApi を false に設定）します。この場合、サーバーは実験的なメソッドやフィールドを拒否します。
実験的なメソッドとフィールドを有効にするには、capabilities.experimentalApi を true に設定します。

{
  "method": "initialize",
  "id": 1,
  "params": {
    "clientInfo": {
      "name": "my_client",
      "title": "My Client",
      "version": "0.1.0"
    },
    "capabilities": {
      "experimentalApi": true
    }
  }
}

オプトインしていないクライアントが実験的なメソッドまたはフィールドを送信すると、app-server は次の内容で拒否します。

<descriptor> requires experimentalApi capability

API の概要

thread/start - 新しいスレッドを作成します。thread/started を送出し、そのスレッドのターン／項目イベントを自動的に購読します。
thread/resume - ID で既存のスレッドを再度開き、以後の turn/start 呼び出しがそのスレッドに追加されるようにします。
thread/fork - 保存済み履歴をコピーし、新しいスレッド ID にスレッドをフォークします。そのターンまでの履歴のみをコピーして後続のターンを除外するには lastTurnId を渡し、インメモリのフォークを作成するには ephemeral: true を渡します。新しいスレッドについて thread/started を送出します。返されるスレッドには、利用可能な場合は forkedFromId が含まれます。
thread/read - 保存済みスレッドを再開せずに ID で読み取ります。ターン履歴全体を返すには includeTurns を設定します。返される thread オブジェクトには、実行時の status が含まれます。
thread/list - 保存済みスレッドログをページ単位で取得します。カーソルベースのページネーションに加え、modelProviders、sourceKinds、archived、isPinned、cwd、useStateDbOnly、searchTerm、および実験的な parentThreadId または ancestorThreadId フィルターをサポートします。返される thread オブジェクトには、実行時の status が含まれます。
thread/turns/list - 実験的機能です。保存済みスレッドを再開せずに、ターン履歴をページ単位で取得します。ターンの項目を省略、要約、完全読み込みのいずれにするかは itemsView で制御します。
thread/items/list - 実験的機能です。永続化されたスレッド項目をページ単位で取得し、必要に応じて 1 つの turnId に限定します。アクティブなスレッドストアが項目のページネーションをサポートしている必要があります。
thread/loaded/list - 現在メモリに読み込まれているスレッド ID を一覧表示します。
thread/name/set - 読み込み済みスレッドまたは永続化されたロールアウトについて、ユーザー向けのスレッド名を設定または更新します。thread/name/updated を送出します。
thread/goal/set - スレッドの目標を設定します。thread/goal/updated を送出します。
thread/goal/get - スレッドの現在の目標を読み取ります。
thread/goal/clear - スレッドの目標をクリアします。thread/goal/cleared を送出します。
thread/metadata/update - 永続化された gitInfo と isPinned を含む、SQLite ベースの保存済みスレッドメタデータにパッチを適用します。
thread/archive - スレッドのログファイルをアーカイブディレクトリへ移動し、まだアーカイブされていない生成済み子孫スレッドのログもアーカイブしようとします。成功時には {} を返し、アーカイブした各スレッドについて thread/archived を送出します。
thread/delete - 永続化されたアクティブまたはアーカイブ済みスレッドと、生成されたすべての子孫スレッドを完全に削除します。成功時には {} を返し、削除した各スレッドについて thread/deleted を送出します。
thread/unsubscribe - この接続によるスレッドのターン／項目イベントの購読を解除します。最後の購読者だった場合、サーバーは購読者がいない状態での非アクティブ猶予期間後にスレッドをアンロードし、thread/closed を送出します。
thread/unarchive - アーカイブ済みスレッドのロールアウトをアクティブセッションディレクトリに復元します。復元された thread を返し、thread/unarchived を送出します。
thread/status/changed - 読み込み済みスレッドの実行時の status が変化したときに送出される通知です。
thread/compact/start - スレッドの会話履歴圧縮を開始します。{} を直ちに返し、進捗は turn/* と item/* の通知でストリーミングされます。
thread/shellCommand - スレッドに対してユーザーが開始したシェルコマンドを実行します。これはサンドボックスの外部でフルアクセス権限により実行され、スレッドのサンドボックスポリシーを継承しません。
thread/backgroundTerminals/clean - スレッドで実行中のすべてのバックグラウンドターミナルを停止します（実験的機能。capabilities.experimentalApi が必要です）。
thread/backgroundTerminals/list - 読み込み済みスレッドで実行中のバックグラウンドターミナルを一覧表示します（実験的機能。capabilities.experimentalApi が必要です）。
thread/backgroundTerminals/terminate - app-server の processId を指定して、実行中のバックグラウンドターミナルを 1 つ終了します（実験的機能。capabilities.experimentalApi が必要です）。
thread/rollback - 非推奨です。インメモリコンテキストから末尾の N ターンを削除し、ロールバックマーカーを永続化します。更新された thread を返します。
turn/start - スレッドにユーザー入力または単独のツール出力を追加して Codex の生成を開始します。最初の turn で応答し、イベントをストリーミングします。collaborationMode では、settings.developer_instructions: null は「選択したモードの組み込み指示を使用する」ことを意味します。
thread/inject_items - ユーザーターンを開始せずに、生の Responses API 項目を読み込み済みスレッドのモデルから見える履歴へ追加します。
turn/steer - スレッドで現在進行中のアクティブなターンにユーザー入力を追加します。受け付けた turnId を返します。
turn/interrupt - 進行中のターンのキャンセルを要求します。成功時は {} となり、ターンは status: "interrupted" で終了します。
review/start - スレッドに対して Codex レビュアーを起動します。enteredReviewMode と exitedReviewMode の項目を送出します。
command/exec - スレッド／ターンを開始せずに、サーバーのサンドボックス内で 1 つのコマンドを実行します。
command/exec/write - 実行中の command/exec セッションに stdin バイトを書き込むか、stdin を閉じます。
command/exec/resize - 実行中の PTY ベースの command/exec セッションのサイズを変更します。
command/exec/terminate - 実行中の command/exec セッションを停止します。
command/exec/outputDelta（通知）- ストリーミング中の command/exec セッションから、base64 エンコードされた stdout／stderr チャンクが送出されます。
process/spawn - Codex のサンドボックス外で明示的なプロセスセッションを開始します（実験的機能。capabilities.experimentalApi が必要です）。
process/writeStdin - 実行中の process/spawn セッションに stdin バイトを書き込むか、stdin を閉じます（実験的機能）。
process/resizePty - 実行中の PTY ベースのプロセスセッションのサイズを変更します（実験的機能）。
process/kill - 実行中のプロセスセッションを終了します（実験的機能）。
process/outputDelta と process/exited（通知）- ストリーミングされるプロセス出力とプロセス終了ステータスについて送出されます（実験的機能）。
model/list - 使用可能なモデルを、エフォートオプション、任意の upgrade、inputModalities とともに一覧表示します（hidden: true のエントリを含めるには includeHidden: true を設定します）。
modelProvider/capabilities/read - モデルとプロバイダーの組み合わせに対するプロバイダー機能の上限を読み取ります。
experimentalFeature/list - ライフサイクルステージのメタデータとカーソルページネーションを含む機能フラグを一覧表示します。
experimentalFeature/enablement/set - apps や plugins など、サポート対象の機能キーについてインメモリのランタイム設定にパッチを適用します。
environment/info - 実験的機能です。設定済みの実行環境に接続し、そのシェルとデフォルトの作業ディレクトリを返します。
permissionProfile/list - ベータ版の権限プロファイルと、有効な要件で各プロファイルが許可されているかどうかを、カーソルページネーション付きで一覧表示します。
collaborationMode/list - コラボレーションモードのプリセットを一覧表示します（実験的機能、ページネーションなし）。
skills/list - 1 つ以上の cwd 値についてスキルを一覧表示します（forceReload と任意の perCwdExtraUserRoots をサポートします）。
skills/extraRoots/set - スタンドアロンスキルの検出に使用するプロセスレベルの追加ルートを、永続化せずに置き換えます。
skills/changed（通知）- 監視対象のローカルスキルファイルが変更されたときに送出されます。
hooks/list - 1 つ以上の cwd 値について、検出されたライフサイクルフックを一覧表示します。
marketplace/add - リモートプラグインマーケットプレイスを追加し、ユーザーのマーケットプレイス設定に永続化します。
marketplace/remove - 設定済みのマーケットプレイスと、存在する場合はインストール済みのマーケットプレイスルートを削除します。
marketplace/upgrade - 設定済みの Git マーケットプレイスを更新します。マーケットプレイス名を省略すると、設定済みのすべての Git マーケットプレイスを更新します。
plugin/list - 開発中です。検出されたプラグインマーケットプレイスとプラグインの状態を一覧表示します。インストール／認証ポリシーのメタデータ、マーケットプレイスの読み込みエラー、注目のプラグイン ID、ローカル、Git、パッケージレジストリ、またはリモートのプラグインソースメタデータが含まれます。概要には、リモートの version、ローカルの localVersion、構造化されたライト／ダークアイコン、現在のリモート行では null、WORKSPACE_SETTING、IMPLICIT_CANONICAL_APP のいずれかになる installPolicySource を含めることができます。まだ本番クライアントからこのメソッドを呼び出さないでください。
plugin/read - 開発中です。マーケットプレイスパス、またはリモートマーケットプレイス名とプラグイン名を指定して 1 つのプラグインを読み取ります。バンドルされたスキル、アプリ、MCP サーバー名、およびリモートカタログで提供される場合はリモートプラグインの shareUrl が含まれます。まだ本番クライアントからこのメソッドを呼び出さないでください。
plugin/install - 開発中です。マーケットプレイスパスまたはリモートマーケットプレイス名からプラグインをインストールします。まだ本番クライアントからこのメソッドを呼び出さないでください。
plugin/uninstall - 開発中です。インストール済みのプラグインをアンインストールします。まだ本番クライアントからこのメソッドを呼び出さないでください。
plugin/skill/read - リモートマーケットプレイス、プラグイン ID、スキル名を指定し、リモートプラグインのスキル Markdown をオンデマンドで読み取ります。
app/installed - 各アプリの実効的な有効状態と呼び出し可能状態を含む、インストール済みアプリのランタイム状態を読み取ります。
app/list - アクセシビリティ／有効化のメタデータとページネーションを含む、使用可能なアプリ（コネクター）を一覧表示します。
app/read - 指定したアプリ ID のメタデータと、任意で表示専用のツール概要を取得します。
skills/config/write - パスを指定してスキルを有効または無効にします。
mcpServer/oauth/login - 設定済み MCP サーバーの OAuth ログインを開始します。認可 URL を返し、完了時に mcpServer/oauthLogin/completed を送出します。
tool/requestUserInput - ツール呼び出しのため、1～3 個の短い質問をユーザーに提示します（実験的機能）。質問では自由記述用の isOther を設定できます。
mcpServer/elicitation/request（サーバーリクエスト）- MCP サーバーが要求した構造化フォーム入力または URL フローの確認をクライアントに求めます。
item/permissions/requestApproval（サーバーリクエスト）- 組み込みの request_permissions ツールが要求したネットワークまたはファイルシステム権限の一部を許可するようクライアントに求めます。
config/mcpServer/reload - ディスクから MCP サーバー設定を再読み込みし、読み込み済みスレッドの更新をキューに追加します。
mcpServerStatus/list - MCP サーバー、ツール、リソース、認証状態を一覧表示します（カーソル＋上限によるページネーション）。完全なデータには detail: "full"、リソースを省略するには detail: "toolsAndAuthOnly" を使用します。
mcpServer/resource/read - 初期化済み MCP サーバー経由で単一の MCP リソースを読み取ります。
mcpServer/tool/call - スレッドに設定された MCP サーバー上のツールを呼び出します。
mcpServer/startupStatus/updated（通知）- 読み込み済みスレッドについて、設定済み MCP サーバーの起動状態が変化したときに送出されます。
windowsSandbox/setupStart - elevated または unelevated モードの Windows サンドボックス設定を開始します。すぐに制御を返し、後で windowsSandbox/setupCompleted を送出します。
feedback/upload - フィードバックレポートを送信します（分類＋任意の理由／ログ＋会話 ID、および任意の extraLogFiles 添付ファイル）。
config/read - 設定の階層を解決した後、ディスク上の有効な設定を取得します。
externalAgentConfig/detect - includeHome と任意の cwds を使用して移行できる外部エージェントの成果物を検出します。検出された各項目には cwd（ホームの場合は null）が含まれます。
externalAgentConfig/import - 明示的な migrationItems と cwd（ホームの場合は null）を渡し、選択した外部エージェント移行項目を適用します。サポートされる項目タイプには、設定、スキル、AGENTS.md、プラグイン、MCP サーバー設定、サブエージェント、フック、コマンド、セッションがあります。空でないインポートでは、作業の進行に応じて externalAgentConfig/import/progress と externalAgentConfig/import/completed が送出されます。プラグインとセッションのインポートは非同期で完了することがあります。
config/value/write - 単一の設定キー／値を、ディスク上のユーザーの config.toml に書き込みます。
config/batchWrite - ユーザーのディスク上の config.toml に設定変更をアトミックに適用します。
configRequirements/read - requirements.toml や MDM から、正確な管理対象設定、許可リスト、固定された featureRequirements、ネットワーク要件（未設定の場合は null）を含む要件を取得します。
fs/readFile、fs/writeFile、fs/createDirectory、fs/getMetadata、fs/readDirectory、fs/remove、fs/copy、fs/watch、fs/unwatch、fs/changed（通知）- app-server v2 ファイルシステム API を通じて絶対ファイルシステムパスを操作します。

プラグインの概要には、source のユニオンが含まれます。ローカルプラグインは { "type": "local", "path": ... }、Git ベースのマーケットプレイスエントリは { "type": "git", "url": ..., "path": ..., "refName": ..., "sha": ... }、パッケージレジストリエントリは { "type": "npm", "package": ..., "version": ..., "registry": ... }、リモートカタログエントリは { "type": "remote" } を返します。リモートのみのカタログエントリでは、PluginMarketplaceEntry.path が null になることがあります。それらのプラグインを読み取るかインストールする際は、 marketplacePath ではなく remoteMarketplaceName を渡します。

モデル

モデルを一覧表示する（`model/list`）

モデルまたはパーソナリティの選択 UI を表示する前に、model/list を呼び出して使用可能なモデルと機能を確認します。

{ "method": "model/list", "id": 6, "params": { "limit": 20, "includeHidden": false } }
{ "id": 6, "result": {
  "data": [{
    "id": "gpt-5.6-sol",
    "model": "gpt-5.6-sol",
    "displayName": "GPT-5.6-Sol",
    "hidden": false,
    "defaultReasoningEffort": "low",
    "supportedReasoningEfforts": [{
      "reasoningEffort": "low",
      "description": "Fast responses with lighter reasoning"
    }],
    "inputModalities": ["text", "image"],
    "supportsPersonality": true,
    "isDefault": true
  }],
  "nextCursor": null
} }

各モデルエントリには、次の項目が含まれる場合があります。

supportedReasoningEfforts - モデルでサポートされるエフォートオプション。
defaultReasoningEffort - クライアント向けに推奨されるデフォルトのエフォート。
upgrade - クライアントの移行案内で任意に使用する、推奨アップグレード先のモデル ID。
upgradeInfo - クライアントの移行案内で使用する任意のアップグレードメタデータ。
hidden - モデルがデフォルトの選択リストで非表示かどうか。
inputModalities - モデルがサポートする入力タイプ（例：text、image）。
supportsPersonality - モデルが /personality などのパーソナリティ固有の指示をサポートするかどうか。
isDefault - モデルが推奨デフォルトかどうか。

デフォルトでは、model/list は選択 UI に表示されるモデルのみを返します。完全な一覧が必要で、hidden を使用してクライアント側でフィルタリングする場合は、includeHidden: true を設定します。

inputModalities が存在しない場合（古いモデルカタログ）は、後方互換性のため ["text", "image"] として扱います。

実験的機能を一覧表示する（`experimentalFeature/list`）

このエンドポイントを使用して、メタデータとライフサイクルステージを含む機能フラグを確認します。

{ "method": "experimentalFeature/list", "id": 7, "params": { "limit": 20 } }
{ "id": 7, "result": {
  "data": [{
    "name": "unified_exec",
    "stage": "beta",
    "displayName": "Unified exec",
    "description": "Use the unified PTY-backed execution tool.",
    "announcement": "Beta rollout for improved command execution reliability.",
    "enabled": false,
    "defaultEnabled": false
  }],
  "nextCursor": null
} }

stage は、beta、underDevelopment、stable、deprecated、removed のいずれかです。ベータ版以外のフラグでは、displayName、description、announcement が null になる場合があります。

実行環境を調べる（実験的機能）

リモート環境で作業を開始する前に、environment/info を使用して設定済みの環境を調べます。このメソッドには capabilities.experimentalApi = true が必要です。

{ "method": "environment/info", "id": 8, "params": { "environmentId": "devbox" } }
{ "id": 8, "result": {
  "shell": { "name": "zsh", "path": "/bin/zsh" },
  "cwd": "file:///workspace/project"
} }

cwd は null になる場合があります。存在する場合、これは環境固有のパス構文を使用する正規の file: URI です。不明な環境 ID、接続障害、プロトコル障害では、リクエストエラーが返されます。

スレッド

thread/read は、保存済みスレッドを購読せずに読み取ります。ターンを含めるには includeTurns を設定します。
thread/turns/list は実験的機能で、保存済みスレッドを再開せずにターン履歴をページ単位で取得します。ターンの項目を省略、要約、完全読み込みのいずれにするかは、itemsView で選択します。
thread/items/list は実験的機能で、永続化されたスレッド項目をページ単位で取得し、必要に応じて 1 つのターンに限定します。
thread/list は、カーソルページネーションに加え、modelProviders、sourceKinds、archived、isPinned、cwd、useStateDbOnly、searchTerm、および実験的な parentThreadId または ancestorThreadId のフィルタリングをサポートします。
thread/loaded/list は、現在メモリにあるスレッド ID を返します。
thread/archive は、スレッドの永続化された JSONL ログをアーカイブディレクトリへ移動し、まだアーカイブされていない生成済み子孫スレッドのログもアーカイブしようとします。
thread/delete は、永続化されたアクティブまたはアーカイブ済みスレッドと、生成された子孫スレッドを完全に削除します。
thread/metadata/update は、永続化された gitInfo と isPinned を含む、保存済みスレッドメタデータにパッチを適用します。
thread/unsubscribe は、読み込み済みスレッドに対する現在の接続の購読を解除し、非アクティブ猶予期間後に thread/closed を発生させる場合があります。
thread/unarchive は、アーカイブ済みスレッドのロールアウトをアクティブセッションディレクトリへ復元します。
thread/compact/start は圧縮を開始し、{} を直ちに返します。
thread/rollback は非推奨です。インメモリコンテキストから末尾の N ターンを削除し、スレッドの永続化された JSONL ログにロールバックマーカーを記録します。
thread/inject_items は、ユーザーターンを開始せずに、生の Responses API 項目を読み込み済みスレッドのモデルから見える履歴へ追加します。

スレッドを開始または再開する

新しい Codex の会話が必要な場合は、新しいスレッドを開始します。

{ "method": "thread/start", "id": 10, "params": {
  "model": "gpt-5.6-terra",
  "cwd": "/Users/me/project",
  "approvalPolicy": "never",
  "sandbox": "workspaceWrite",
  "personality": "friendly",
  "serviceName": "my_app_server_client"
} }
{ "id": 10, "result": {
  "thread": {
    "id": "thr_123",
    "sessionId": "thr_123",
    "preview": "",
    "ephemeral": false,
    "modelProvider": "openai",
    "createdAt": 1730910000
  }
} }
{ "method": "thread/started", "params": { "thread": { "id": "thr_123" } } }

serviceName は任意です。app-server がスレッドレベルのメトリクスに統合サービス名のタグを付けるようにする場合に設定します。

thread/start、thread/resume、thread/fork は、読み込まれた指示ファイルのパス配列である instructionSources を返します。リモート環境を含め、各パスにはそのソース環境固有の絶対パス構文が使用されます。

実験的クライアントでは、thread/start の historyMode を、"legacy" （デフォルト）または "paginated" に設定できます。ページネーション付きのスレッド作成はまだサポートされておらず、 JSON-RPC エラー -32601 が返されます。app-server は既存のページ分割されたレコードの概要を一覧表示および読み取りできますが、ページ分割された履歴がサポートされるまで、全履歴の読み取り、ターンのページネーション、再開はフェイルクローズになります。

capabilities.experimentalApi にオプトインしたベータ版クライアントは、従来の sandbox フィールドの代わりに、名前付きの権限プロファイル ID を permissions で渡せます。 permissions と sandbox を同時に送信しないでください。使用可能なプロファイルと、管理対象の要件で各プロファイルが許可されるかどうかを確認するには、プロジェクトの cwd とともに permissionProfile/list を使用します。

thread.sessionId は、現在のライブセッションツリーのルートを識別します。ルートスレッドでは自身のスレッド ID がセッション ID になります。フォークされたスレッドは、分岐元のルートのセッション ID を引き継ぎます。クライアントは、スレッド ID から導出せず、 thread.sessionId からセッション ID を読み取ってください。

保存済みセッションを続行するには、以前記録した thread.id を指定して thread/resume を呼び出します。レスポンスの形状は thread/start と同じです。personality など、thread/start でサポートされるものと同じ設定の上書きも渡せます。

{ "method": "thread/resume", "id": 11, "params": {
  "threadId": "thr_123",
  "personality": "friendly"
} }
{ "id": 11, "result": { "thread": { "id": "thr_123", "name": "Bug bash notes", "ephemeral": false } } }

スレッドを再開するだけでは、thread.updatedAt（またはロールアウトファイルの更新時刻）は更新されません。タイムスタンプはターンを開始すると更新されます。

有効な MCP サーバーを設定で required として指定し、そのサーバーの初期化に失敗した場合、thread/start と thread/resume は、そのサーバーなしで続行せずに失敗します。

thread/start の dynamicTools は実験的なフィールドです（capabilities.experimentalApi = true が必要です）。Codex はこれらの動的ツールをスレッドのロールアウトメタデータに永続化し、新しい動的ツールを指定しなかった場合は thread/resume で復元します。

ロールアウトに記録されたモデルとは異なるモデルで再開すると、Codex は警告を送出し、次のターンで 1 回限りのモデル切り替え指示を適用します。

スレッドの目標を管理する

thread/goal/set、thread/goal/get、thread/goal/clear を使用して、 TUI の /goal に表示されるものと同じ永続化された目標状態を管理します。

{ "method": "thread/goal/set", "id": 13, "params": {
  "threadId": "thr_123",
  "objective": "Finish the migration and keep tests green",
  "status": "active",
  "tokenBudget": 40000
} }
{ "id": 13, "result": { "goal": {
  "threadId": "thr_123",
  "objective": "Finish the migration and keep tests green",
  "status": "active",
  "tokenBudget": 40000,
  "tokensUsed": 0,
  "timeUsedSeconds": 0
} } }
{ "method": "thread/goal/updated", "params": {
  "threadId": "thr_123",
  "goal": {
    "threadId": "thr_123",
    "objective": "Finish the migration and keep tests green",
    "status": "active",
    "tokenBudget": 40000,
    "tokensUsed": 0,
    "timeUsedSeconds": 0
  }
} }

目標の目的は空にできず、最大 4,000 文字です。新しい目的を指定すると目標が置き換えられ、使用量の集計がリセットされます。現在の未完了の目的を指定するか、objective を省略すると、使用履歴を保持したままステータスまたはトークン予算が更新されます。

保存済みセッションから分岐するには、thread.id を指定して thread/fork を呼び出します。これにより新しいスレッド ID が作成され、そのスレッドについて thread/started 通知が送出されます。そのターンを含む位置まで履歴をコピーし、それ以降のターンを除外するには、lastTurnId を渡します。

{ "method": "thread/fork", "id": 12, "params": { "threadId": "thr_123", "lastTurnId": "turn_456" } }
{ "id": 12, "result": { "thread": { "id": "thr_456", "sessionId": "thr_123", "forkedFromId": "thr_123" } } }
{ "method": "thread/started", "params": { "thread": { "id": "thr_456" } } }

app-server は進行中の lastTurnId を拒否します。ソーススレッドがターンの途中であるときにこのフィールドを省略すると、フォークでは、マークのない不完全なターンを保持する代わりに中断マーカーが記録されます。

保存済みのスレッド一覧に追加せず、インメモリのフォークを作成するには ephemeral: true を渡します。

{
  "method": "thread/fork",
  "id": 13,
  "params": {
    "threadId": "thr_123",
    "ephemeral": true
  }
}
{
  "id": 13,
  "result": {
    "thread": {
      "id": "thr_789",
      "sessionId": "thr_789",
      "forkedFromId": "thr_123",
      "ephemeral": true
    }
  }
}

ページ分割されたスレッドの一時的なフォークには、excludeTurns: true も必要です。このフィールドは実験的であり、capabilities.experimentalApi = true が必要です。

ユーザー向けのスレッドタイトルが設定されている場合、app-server は thread/list、thread/read、thread/resume、thread/unarchive、thread/rollback のレスポンスで thread.name をハイドレートします。タイトルが後で設定されるまでは、thread/start と thread/fork で name が省略される（または null が返される）場合があります。

保存済みスレッドを読み取る（再開なし）

スレッドを再開したり、そのイベントを購読したりせずに保存済みスレッドのデータを取得する場合は、thread/read を使用します。

includeTurns - true の場合、レスポンスにはスレッドのターンが含まれます。false の場合、または省略した場合は、スレッドの概要のみが返されます。
返される thread オブジェクトには、実行時の status（notLoaded、idle、systemError、または activeFlags を伴う active）が含まれます。

{ "method": "thread/read", "id": 19, "params": { "threadId": "thr_123", "includeTurns": true } }
{ "id": 19, "result": { "thread": { "id": "thr_123", "name": "Bug bash notes", "ephemeral": false, "status": { "type": "notLoaded" }, "turns": [] } } }

thread/resume とは異なり、thread/read はスレッドをメモリに読み込まず、thread/started も送出しません。

スレッドのターンを一覧表示する

thread/turns/list は実験的機能です。保存済みスレッドを再開せずに、そのターン履歴をページ単位で取得するために使用します。結果はデフォルトで新しい順に並ぶため、クライアントは nextCursor を使用して古いターンを取得できます。レスポンスには backwardsCursor も含まれます。以前のページの先頭項目より新しいターンを取得するには、sortDirection: "asc" とともに cursor として渡します。

itemsView は、レスポンスに含めるターン項目のデータ量を制御します。

notLoaded は項目を省略します。
summary は要約された項目データを返します。省略した場合のデフォルトです。
full は完全な項目データを返します。

{ "method": "thread/turns/list", "id": 20, "params": {
  "threadId": "thr_123",
  "limit": 50,
  "sortDirection": "desc",
  "itemsView": "summary"
} }
{ "id": 20, "result": {
  "data": [],
  "nextCursor": "older-turns-cursor-or-null",
  "backwardsCursor": "newer-turns-cursor-or-null"
} }

thread/items/list も実験的機能です。スレッドを再開せずに、永続化された項目をページ単位で取得します。結果を 1 つのターンに限定するには turnId を渡し、スレッド全体の項目をページ単位で取得するには省略します。アクティブなスレッドストアが項目のページネーションをサポートしている必要があります。サポートしていない場合、サーバーは未対応メソッドエラーを返します。

スレッドを一覧表示する（ページネーションとフィルター）

thread/list を使用すると履歴 UI を表示できます。結果はデフォルトで createdAt に基づく新しい順になります。フィルターはページネーションの前に適用されます。次の項目を任意に組み合わせて渡せます。

cursor - 以前のレスポンスから得た不透明な文字列です。最初のページでは省略します。
limit - 未設定の場合、サーバーは妥当なページサイズをデフォルトとして使用します。
sortKey - created_at（デフォルト）、updated_at、recency_at のいずれかです。
sortDirection - desc（デフォルト）または asc です。
modelProviders - 結果を特定のプロバイダーに限定します。未設定、null、または空の配列の場合は、すべてのプロバイダーが含まれます。
sourceKinds - 結果を特定のスレッドソースに限定します。省略または [] の場合、サーバーはデフォルトで対話型ソース（cli と vscode）のみに限定します。
archived - true の場合、アーカイブ済みスレッドのみを一覧表示します。false の場合、または省略した場合は、アーカイブされていないスレッドを一覧表示します（デフォルト）。
isPinned - 指定すると、永続化されたピン状態が一致するスレッドのみを返します。ピン留め済みと未ピン留めの両方を返すには省略します。
cwd - セッションの現在の作業ディレクトリが、このパスまたは配列内のいずれかのパスと完全に一致するスレッドに結果を限定します。相対パスは app-server プロセスの作業ディレクトリを基準に解決されます。
useStateDbOnly - true の場合、メタデータを修復するために JSONL スレッドログをスキャンせず、状態データベースの結果を返します。デフォルトのスキャンと修復の動作を使用するには、省略するか false を渡します。
searchTerm - 抽出されたタイトルに、この大文字と小文字を区別するテキスト断片が含まれるスレッドに結果を限定します。
parentThreadId - 指定した親スレッドの直接の子スレッドに結果を限定します。このフィルターは実験的であり、capabilities.experimentalApi = true が必要です。
ancestorThreadId - 指定したスレッドから生成された、任意の深さの子孫スレッドに結果を限定します。このフィルターは実験的であり、capabilities.experimentalApi = true が必要です。parentThreadId と組み合わせないでください。

sourceKinds は、次の値を受け付けます。

cli
vscode
exec
appServer
subAgent
subAgentReview
subAgentCompact
subAgentThreadSpawn
subAgentOther
unknown

例：

{ "method": "thread/list", "id": 20, "params": {
  "cursor": null,
  "limit": 25,
  "sortKey": "created_at"
} }
{ "id": 20, "result": {
  "data": [
    { "id": "thr_a", "preview": "Create a TUI", "ephemeral": false, "isPinned": true, "modelProvider": "openai", "createdAt": 1730831111, "updatedAt": 1730831111, "name": "TUI prototype", "status": { "type": "notLoaded" } },
    { "id": "thr_b", "preview": "Fix tests", "ephemeral": false, "isPinned": false, "modelProvider": "openai", "createdAt": 1730750000, "updatedAt": 1730750000, "status": { "type": "notLoaded" } }
  ],
  "nextCursor": "opaque-token-or-null"
} }

nextCursor が null の場合、最後のページに到達しています。

保存済みスレッドのメタデータを更新する

スレッドを再開せずに保存済みスレッドのメタデータへパッチを適用するには、thread/metadata/update を使用します。スレッドをピン留めまたはピン留め解除するには isPinned を設定し、永続化された Git メタデータを変更するには gitInfo を更新します。省略したフィールドは変更されません。明示的な null を指定すると、保存済みの Git メタデータ値がクリアされます。

{ "method": "thread/metadata/update", "id": 21, "params": {
  "threadId": "thr_123",
  "isPinned": true,
  "gitInfo": { "branch": "feature/sidebar-pr" }
} }
{ "id": 21, "result": {
  "thread": {
    "id": "thr_123",
    "isPinned": true,
    "gitInfo": { "sha": null, "branch": "feature/sidebar-pr", "originUrl": null }
  }
} }

スレッドのステータス変更を追跡する

読み込み済みスレッドのランタイムステータスが変化するたびに、thread/status/changed が送出されます。ペイロードには threadId と新しい status が含まれます。

{
  "method": "thread/status/changed",
  "params": {
    "threadId": "thr_123",
    "status": { "type": "active", "activeFlags": ["waitingOnApproval"] }
  }
}

読み込み済みスレッドを一覧表示する

thread/loaded/list は、現在メモリに読み込まれているスレッド ID を返します。

{ "method": "thread/loaded/list", "id": 21 }
{ "id": 21, "result": { "data": ["thr_123", "thr_456"] } }

読み込み済みスレッドの購読を解除する

thread/unsubscribe は、現在の接続によるスレッドの購読を解除します。レスポンスのステータスは次のいずれかです。

接続が購読中で、購読が解除された場合は unsubscribed。
接続がそのスレッドを購読していなかった場合は notSubscribed。
スレッドが読み込まれていない場合は notLoaded。

これが最後の購読者だった場合、サーバーは購読者がおらず、スレッドのアクティビティがない状態が 30 分間続くまでスレッドを読み込んだままにします。猶予期間が終了すると、app-server はスレッドをアンロードし、notLoaded への thread/status/changed 遷移と thread/closed を送出します。

{ "method": "thread/unsubscribe", "id": 22, "params": { "threadId": "thr_123" } }
{ "id": 22, "result": { "status": "unsubscribed" } }

後でスレッドの有効期限が切れた場合：

{ "method": "thread/status/changed", "params": {
    "threadId": "thr_123",
    "status": { "type": "notLoaded" }
} }
{ "method": "thread/closed", "params": { "threadId": "thr_123" } }

スレッドをアーカイブする

thread/archive を使用して、永続化されたスレッドログ（ディスク上に JSONL ファイルとして保存）をアーカイブ済みセッションのディレクトリへ移動します。スレッドをアーカイブすると、まだアーカイブされていない生成済み子孫スレッドもアーカイブしようとします。

{ "method": "thread/archive", "id": 22, "params": { "threadId": "thr_b" } }
{ "id": 22, "result": {} }
{ "method": "thread/archived", "params": { "threadId": "thr_b" } }
{ "method": "thread/archived", "params": { "threadId": "thr_child" } }

archived: true を渡さない限り、アーカイブ済みスレッドは今後の thread/list 呼び出しには表示されません。サーバーは、実際にアーカイブした各スレッドについて thread/archived 通知を 1 件送出します。生成済みの子孫をアーカイブできない場合でも、その子孫についてアーカイブ通知を送出せずにリクエスト自体は成功することがあります。

スレッドを削除する

thread/delete を使用すると、永続化されたアクティブまたはアーカイブ済みのスレッドと、そこから生成された子孫スレッドを完全に削除できます。成功を返す前に、サーバーは既存のロールアウトファイルと関連メタデータを削除します。ロールアウトファイルが存在しない場合は、すでに削除済みとして扱われます。一時的なルートスレッドは削除できません。

{ "method": "thread/delete", "id": 23, "params": { "threadId": "thr_b" } }
{ "id": 23, "result": {} }
{ "method": "thread/deleted", "params": { "threadId": "thr_b" } }
{ "method": "thread/deleted", "params": { "threadId": "thr_child" } }

スレッドのアーカイブを解除する

thread/unarchive を使用すると、アーカイブ済みスレッドのロールアウトをアクティブセッションのディレクトリに戻せます。

{ "method": "thread/unarchive", "id": 24, "params": { "threadId": "thr_b" } }
{ "id": 24, "result": { "thread": { "id": "thr_b", "name": "Bug bash notes" } } }
{ "method": "thread/unarchived", "params": { "threadId": "thr_b" } }

スレッドのコンパクションを開始する

thread/compact/start を使用すると、スレッドの履歴を手動でコンパクションできます。リクエストは {} とともに即座に返されます。

App-server は、同じ threadId 上で標準の turn/* および item/* 通知として進行状況を送信します。これには、contextCompaction アイテムのライフサイクル（item/started、続いて item/completed）も含まれます。

{ "method": "thread/compact/start", "id": 25, "params": { "threadId": "thr_b" } }
{ "id": 25, "result": {} }

スレッドのシェルコマンドを実行する

スレッドに属する、ユーザーが開始したシェルコマンドには thread/shellCommand を使用します。進行状況が標準の turn/* および item/* 通知を通じてストリーミングされる間、リクエストは {} とともに即座に返されます。

この API はサンドボックスの外部でフルアクセス権を持って実行され、スレッドのサンドボックスポリシーを継承しません。クライアントでは、ユーザーが明示的に開始したコマンドに対してのみ公開してください。

スレッドにすでにアクティブなターンがある場合、コマンドはそのターンの補助アクションとして実行され、整形された出力がターンのメッセージストリームに挿入されます。スレッドがアイドル状態の場合、app-server はシェルコマンド用の独立したターンを開始します。

timeoutMs を設定すると、実行時間をミリ秒単位で制限できます。省略するか null を渡すと、デフォルトの 1 時間が使用されます。0 を指定すると即時タイムアウトが要求されます。負の値は拒否されます。タイムアウトによって即時の RPC 応答確認が遅れることはありません。

{ "method": "thread/shellCommand", "id": 26, "params": { "threadId": "thr_b", "command": "git status --short", "timeoutMs": 10000 } }
{ "id": 26, "result": {} }

バックグラウンドターミナルをクリーンアップする

thread/backgroundTerminals/clean を使用すると、スレッドに関連付けられている実行中のバックグラウンドターミナルをすべて停止できます。このメソッドは実験的であり、capabilities.experimentalApi = true が必要です。

{ "method": "thread/backgroundTerminals/clean", "id": 27, "params": { "threadId": "thr_b" } }
{ "id": 27, "result": {} }

thread/backgroundTerminals/list を使用すると、読み込み済みスレッドで実行中のバックグラウンドターミナルを確認できます。このリクエストは標準の cursor および limit ページネーションをサポートし、返される processId は app-server のプロセス ID です。このメソッドは実験的であり、capabilities.experimentalApi = true が必要です。

{ "method": "thread/backgroundTerminals/list", "id": 28, "params": { "threadId": "thr_b" } }
{ "id": 28, "result": { "data": [
  {
    "itemId": "item_456",
    "processId": "42",
    "command": "python3 -m http.server",
    "cwd": "/workspace",
    "osPid": null,
    "cpuPercent": null,
    "rssKb": null
  }
], "nextCursor": null } }

その processId とともに thread/backgroundTerminals/terminate を使用すると、1 つのバックグラウンドターミナルを停止できます。このメソッドは実験的であり、 capabilities.experimentalApi = true が必要です。

{ "method": "thread/backgroundTerminals/terminate", "id": 29, "params": { "threadId": "thr_b", "processId": "42" } }
{ "id": 29, "result": { "terminated": true } }

直近のターンをロールバックする

thread/rollback は非推奨であり、今後削除されます。メモリ内のコンテキストから最後の numTurns エントリを削除し、ロールアウトログにロールバックマーカーを永続化します。返される thread では、ロールバック後に turns が設定されます。

{ "method": "thread/rollback", "id": 30, "params": { "threadId": "thr_b", "numTurns": 1 } }
{ "id": 30, "result": { "thread": { "id": "thr_b", "name": "Bug bash notes", "ephemeral": false } } }

ターン

input フィールドはアイテムのリストを受け付けます。

{ "type": "text", "text": "Explain this diff" }
{ "type": "image", "url": "https://.../design.png" }
{ "type": "localImage", "path": "/tmp/screenshot.png" }

ターンごとに構成設定（モデル、エフォート、パーソナリティ、cwd、サンドボックスポリシー、要約）を上書きできます。指定した設定は、同じスレッド上の以降のターンでデフォルトになります。outputSchema は現在のターンにのみ適用されます。sandboxPolicy.type = "externalSandbox" では、networkAccess を restricted または enabled に設定します。workspaceWrite では、networkAccess は引き続き boolean です。

turn/start.collaborationMode では、settings.developer_instructions: null はモードの指示を消去するのではなく、「選択したモードに組み込まれている指示を使用する」ことを意味します。

サンドボックスの読み取りアクセス（`ReadOnlyAccess`）

sandboxPolicy は、明示的な読み取りアクセス制御をサポートします。

readOnly: オプションの access（デフォルトは { "type": "fullAccess" }。または制限されたルート）。
workspaceWrite: オプションの readOnlyAccess（デフォルトは { "type": "fullAccess" }。または制限されたルート）。

制限付き読み取りアクセスの形式：

{
  "type": "restricted",
  "includePlatformDefaults": true,
  "readableRoots": ["/Users/me/shared-read-only"]
}

macOS では、includePlatformDefaults: true により、制限付き読み取りセッション向けに厳選されたプラットフォーム標準の Seatbelt ポリシーが追加されます。これにより、/System のすべてへのアクセスを広範に許可することなく、ツールの互換性が向上します。

例：

{ "type": "readOnly", "access": { "type": "fullAccess" } }

{
  "type": "workspaceWrite",
  "writableRoots": ["/Users/me/project"],
  "readOnlyAccess": {
    "type": "restricted",
    "includePlatformDefaults": true,
    "readableRoots": ["/Users/me/shared-read-only"]
  },
  "networkAccess": false
}

ターンを開始する

{ "method": "turn/start", "id": 30, "params": {
  "threadId": "thr_123",
  "input": [ { "type": "text", "text": "Run tests" } ],
  "cwd": "/Users/me/project",
  "approvalPolicy": "unlessTrusted",
  "sandboxPolicy": {
    "type": "workspaceWrite",
    "writableRoots": ["/Users/me/project"],
    "networkAccess": true
  },
  "model": "gpt-5.6-terra",
  "effort": "medium",
  "summary": "concise",
  "personality": "friendly",
  "outputSchema": {
    "type": "object",
    "properties": { "answer": { "type": "string" } },
    "required": ["answer"],
    "additionalProperties": false
  }
} }
{ "id": 30, "result": { "turn": { "id": "turn_456", "status": "inProgress", "items": [], "error": null } } }

クライアントが実行したツールの出力を使ってターンを開始するには、空でない name、任意の namespace、および文字列またはコンテンツ項目の配列である output とともに、toolOutput を渡します。input は空の配列に設定してください。空でないユーザー入力と toolOutput を組み合わせることはできません。

{
  "method": "turn/start",
  "id": 31,
  "params": {
    "threadId": "thr_123",
    "input": [],
    "toolOutput": {
      "name": "run_tests",
      "namespace": null,
      "output": "All 42 tests passed."
    }
  }
}

この出力は会話内でツール出力として保持され、通知と永続化された履歴では functionCallOutput 項目として表示されます。通常のターンがすでにアクティブな場合、Codex はそのターン用に出力をキューへ追加します。

スレッドにアイテムを挿入する

thread/inject_items を使用すると、ユーザーターンを開始せずに、事前構築済みの Responses API アイテムを読み込み済みスレッドのプロンプト履歴へ追加できます。これらのアイテムはロールアウトに永続化され、以降のモデルリクエストに含まれます。

{ "method": "thread/inject_items", "id": 31, "params": {
  "threadId": "thr_123",
  "items": [
    {
      "type": "message",
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "Previously computed context." }]
    }
  ]
} }
{ "id": 31, "result": {} }

アクティブなターンを誘導する

turn/steer を使用すると、進行中のアクティブなターンにユーザー入力を追加できます。

expectedTurnId を含めてください。アクティブなターン ID と一致している必要があります。
スレッドにアクティブなターンがない場合、リクエストは失敗します。
turn/steer は新しい turn/started 通知を送信しません。
turn/steer はターンレベルの上書き（model、cwd、sandboxPolicy、outputSchema）を受け付けません。

{ "method": "turn/steer", "id": 32, "params": {
  "threadId": "thr_123",
  "input": [ { "type": "text", "text": "Actually focus on failing tests first." } ],
  "expectedTurnId": "turn_456"
} }
{ "id": 32, "result": { "turnId": "turn_456" } }

ターンを開始する（スキルの呼び出し）

テキスト入力に $<skill-name> を含め、その横に skill 入力アイテムを追加すると、スキルを明示的に呼び出せます。

{ "method": "turn/start", "id": 33, "params": {
  "threadId": "thr_123",
  "input": [
    { "type": "text", "text": "$skill-creator Add a new skill for triaging flaky CI and include step-by-step usage." },
    { "type": "skill", "name": "skill-creator", "path": "/Users/me/.codex/skills/skill-creator/SKILL.md" }
  ]
} }
{ "id": 33, "result": { "turn": { "id": "turn_457", "status": "inProgress", "items": [], "error": null } } }

ターンを中断する

{ "method": "turn/interrupt", "id": 31, "params": { "threadId": "thr_123", "turnId": "turn_456" } }
{ "id": 31, "result": {} }

成功すると、ターンは status: "interrupted" で終了します。

レビュー

review/start はスレッドに対して Codex レビュアーを実行し、レビューアイテムをストリーミングします。ターゲットには次のものがあります。

uncommittedChanges
baseBranch（ブランチとの差分）
commit（特定のコミットをレビュー）
custom（自由形式の指示）

既存のスレッドでレビューを実行するには delivery: "inline"（デフォルト）を使用し、新しいレビュースレッドをフォークするには delivery: "detached" を使用します。

リクエストとレスポンスの例：

{ "method": "review/start", "id": 40, "params": {
  "threadId": "thr_123",
  "delivery": "inline",
  "target": { "type": "commit", "sha": "1234567deadbeef", "title": "Polish tui colors" }
} }
{ "id": 40, "result": {
  "turn": {
    "id": "turn_900",
    "status": "inProgress",
    "items": [
      { "type": "userMessage", "id": "turn_900", "content": [ { "type": "text", "text": "Review commit 1234567: Polish tui colors" } ] }
    ],
    "error": null
  },
  "reviewThreadId": "thr_123"
} }

分離されたレビューには "delivery": "detached" を使用します。レスポンスの形式は同じですが、reviewThreadId は新しいレビュースレッドの ID になります（元の threadId とは異なります）。サーバーは、レビューターンのストリーミングを開始する前に、その新しいスレッドについて thread/started 通知も送信します。

Codex は通常の turn/started 通知をストリーミングし、続いて enteredReviewMode アイテムを含む item/started を送信します。

{
  "method": "item/started",
  "params": {
    "item": {
      "type": "enteredReviewMode",
      "id": "turn_900",
      "review": "current changes"
    }
  }
}

レビュアーが完了すると、サーバーは最終的なレビューテキストを持つ exitedReviewMode アイテムを含む item/started および item/completed を送信します。

{
  "method": "item/completed",
  "params": {
    "item": {
      "type": "exitedReviewMode",
      "id": "turn_900",
      "review": "Looks solid overall..."
    }
  }
}

クライアントでレビュアーの出力をレンダリングするには、この通知を使用します。

プロセス実行

process/* は、明示的にプロセスを制御する実験的な API です。 capabilities.experimentalApi = true が必要で、Codex のサンドボックス外で実行されます。クライアントでサンドボックスを使用せずにローカルプロセス制御を意図的に公開する場合にのみ使用してください。

process/spawn でプロセスを開始して processHandle を指定し、そのハンドルを標準入力、サイズ変更、強制終了の各リクエストに使用します。出力は process/outputDelta 通知を通じてストリーミングされ、完了は process/exited を通じてストリーミングされます。

{ "method": "process/spawn", "id": 48, "params": {
  "command": ["python3", "-m", "pytest", "-q"],
  "processHandle": "pytest-1",
  "cwd": "/Users/me/project",
  "tty": true
} }
{ "id": 48, "result": {} }
{ "method": "process/outputDelta", "params": {
  "processHandle": "pytest-1",
  "stream": "stdout",
  "deltaBase64": "Li4u"
} }
{ "method": "process/exited", "params": {
  "processHandle": "pytest-1",
  "exitCode": 0
} }

入力を送信するには、deltaBase64、closeStdin、またはその両方とともに process/writeStdin を使用します。 PTY のサイズ変更イベントには process/resizePty、実行中のプロセスの終了には process/kill を使用します。

コマンド実行

command/exec は、スレッドを作成せずに、サーバーのサンドボックス内で単一のコマンド（argv 配列）を実行します。

{ "method": "command/exec", "id": 50, "params": {
  "command": ["ls", "-la"],
  "cwd": "/Users/me/project",
  "sandboxPolicy": { "type": "workspaceWrite" },
  "timeoutMs": 10000
} }
{ "id": 50, "result": { "exitCode": 0, "stdout": "...", "stderr": "" } }

サーバープロセスをすでにサンドボックス化しており、Codex 独自のサンドボックス適用を省略する場合は、sandboxPolicy.type = "externalSandbox" を使用します。外部サンドボックスモードでは、networkAccess を restricted（デフォルト）または enabled に設定します。readOnly と workspaceWrite には、上記と同じオプションの access / readOnlyAccess 構造を使用します。

注意：

サーバーは空の command 配列を拒否します。
sandboxPolicy は turn/start と同じ形式（たとえば、dangerFullAccess、readOnly、workspaceWrite、externalSandbox）を受け付けます。
省略した場合、timeoutMs はサーバーのデフォルトにフォールバックします。
PTY ベースのセッションでは tty: true を設定し、その後に command/exec/write、command/exec/resize、または command/exec/terminate を使用する予定がある場合は processId を使用します。
コマンドの実行中に command/exec/outputDelta 通知を受信するには、streamStdoutStderr: true を設定します。

管理者要件を読み取る（`configRequirements/read`）

configRequirements/read を使用すると、requirements.toml や MDM から読み込まれた有効な管理者要件を確認できます。

{ "method": "configRequirements/read", "id": 52, "params": {} }
{ "id": 52, "result": {
  "requirements": {
    "allowedApprovalPolicies": ["onRequest", "unlessTrusted"],
    "allowedSandboxModes": ["readOnly", "workspaceWrite"],
    "featureRequirements": {
      "personality": true,
      "unified_exec": false
    },
    "network": {
      "enabled": true,
      "allowedDomains": ["api.openai.com"],
      "allowUnixSockets": ["/tmp/example.sock"],
      "dangerouslyAllowAllUnixSockets": false
    }
  }
} }

要件が構成されていない場合、result.requirements は null になります。サポートされているキーと値の詳細については、requirements.toml のドキュメントを参照してください。

Windows サンドボックスのセットアップ（`windowsSandbox/setupStart`）

カスタム Windows クライアントでは、起動時のチェックでブロックする代わりに、サンドボックスのセットアップを非同期で開始できます。

{ "method": "windowsSandbox/setupStart", "id": 53, "params": { "mode": "elevated" } }
{ "id": 53, "result": { "started": true } }

App-server はバックグラウンドでセットアップを開始し、後から完了通知を送信します。

{
  "method": "windowsSandbox/setupCompleted",
  "params": { "mode": "elevated", "success": true, "error": null }
}

モード：

elevated - 管理者権限を使用する Windows サンドボックスのセットアップパスを実行します。
unelevated - 従来のセットアップ／事前チェックパスを実行します。

ファイルシステム

v2 ファイルシステム API は絶対パスを使用します。ファイルまたはディレクトリの変更後にクライアントが UI の状態を無効化する必要がある場合は、fs/watch を使用します。

{ "method": "fs/watch", "id": 54, "params": {
  "watchId": "0195ec6b-1d6f-7c2e-8c7a-56f2c4a8b9d1",
  "path": "/Users/me/project/.git/HEAD"
} }
{ "id": 54, "result": { "path": "/Users/me/project/.git/HEAD" } }
{ "method": "fs/changed", "params": {
  "watchId": "0195ec6b-1d6f-7c2e-8c7a-56f2c4a8b9d1",
  "changedPaths": ["/Users/me/project/.git/HEAD"]
} }
{ "method": "fs/unwatch", "id": 55, "params": {
  "watchId": "0195ec6b-1d6f-7c2e-8c7a-56f2c4a8b9d1"
} }
{ "id": 55, "result": {} }

ファイルを監視すると、置換または名前変更の操作による更新も含め、そのファイルパスに対して fs/changed が送信されます。

イベント

イベント通知は、スレッドのライフサイクル、ターンのライフサイクル、およびそれらに含まれるアイテムについてサーバーが開始するストリームです。スレッドを開始または再開した後は、thread/started、thread/archived、thread/unarchived、thread/closed、thread/status/changed、turn/*、item/*、serverRequest/resolved の各通知を受信できるよう、アクティブなトランスポートストリームの読み取りを続けてください。

通知のオプトアウト

クライアントは、initialize.params.capabilities.optOutNotificationMethods で正確なメソッド名を送信することにより、接続ごとに特定の通知を抑制できます。

完全一致のみ：item/agentMessage/delta はそのメソッドだけを抑制します。
不明なメソッド名は無視されます。
現在の thread/*、turn/*、item/*、および関連する v2 通知に適用されます。
リクエスト、レスポンス、エラーには適用されません。

あいまいファイル検索イベント（実験的）

あいまいファイル検索のセッション API は、クエリごとに通知を送信します。

fuzzyFileSearch/sessionUpdated - アクティブなクエリの現在の一致結果を持つ { sessionId, query, files }。
fuzzyFileSearch/sessionCompleted - そのクエリのインデックス作成と照合が完了すると送信される { sessionId }。

警告イベント

configWarning - 回復可能な構成または初期化の問題を示す { summary, details?, path?, range? }。
warning - 致命的ではないランタイム警告を示す { threadId?, message }。

Windows サンドボックスのセットアップイベント

windowsSandbox/setupCompleted - windowsSandbox/setupStart リクエストの完了後に送信される { mode, success, error }。

ターンイベント

turn/started - ターン ID、空の items、および status: "inProgress" を持つ { turn }。
turn/completed - turn.status が completed、interrupted、または failed である { turn }。失敗時には { error: { message, codexErrorInfo?, additionalDetails? } } が含まれます。
turn/diff/updated - ターン内のすべてのファイル変更を集約した最新の unified diff を持つ { threadId, turnId, diff }。
turn/plan/updated - エージェントが計画を共有または変更するたびに送信される { turnId, explanation?, plan }。各 plan エントリは { step, status } で、status は pending、inProgress、または completed です。
hook/started および hook/completed - 同期ライフサイクルフックの開始時と、その最終実行サマリーが利用可能になったときに送信される { threadId, turnId?, run }。これらの通知は非同期フックでは送信されません。
model/safetyBuffering/updated - レスポンスが一時的な安全性バッファリングに入ったときの { threadId, turnId, model, useCases, reasons, showBufferingUi, fasterModel }。
model/rerouted - サービスがリクエストを別のモデルにルーティングしたときの { threadId, turnId, fromModel, toModel, reason }。
model/verification - サービスがアカウントの追加確認を要求するときの { threadId, turnId, verifications }。
thread/tokenUsage/updated - アクティブなスレッドの使用量更新。

turn/diff/updated と turn/plan/updated には現在、アイテムイベントがストリーミングされる場合でも空の items 配列が含まれます。ターンアイテムの信頼できる情報源として item/* 通知を使用してください。

アイテム

ThreadItem は、ターンのレスポンスと item/* 通知に含まれるタグ付き union です。一般的なアイテムタイプは次のとおりです。

userMessage - ユーザー入力（text、image、または localImage）のリストである content を持つ {id, content}。
functionCallOutput - turn/start.toolOutput を通じて渡された単独のツール出力を表す {id, name, namespace, output}。namespace は null にできます。
agentMessage - 蓄積されたエージェントの応答を含む {id, text, phase?}。存在する場合、phase は Responses API の wire 値（commentary、final_answer）を使用します。
plan - plan mode で提案された計画テキストを含む {id, text}。item/completed からの最終的な plan アイテムを正として扱ってください。
reasoning - ストリーミングされた推論サマリーを保持する summary と、生の推論ブロックを保持する content を持つ {id, summary, content}。
commandExecution - {id, command, cwd, status, commandActions, aggregatedOutput?, exitCode?, durationMs?}。
fileChange - 提案された編集を記述する {id, changes, status}。changes は {path, kind, diff} のリストです。
mcpToolCall - {id, server, tool, status, arguments, appContext?, pluginId?, result?, error?}。信頼済み MCP アプリでは、appContext に connectorId、linkId、resourceUri、appName、templateId、および安定したコネクター actionName を含めることができます。以前に永続化されたアイテムでは、新しいメタデータが省略されている場合があります。非推奨のトップレベル mcpAppResourceUri の代わりに appContext.resourceUri を使用してください。
dynamicToolCall - クライアントが実行する動的ツール呼び出し用の {id, tool, arguments, status, contentItems?, success?, durationMs?}。
collabToolCall - {id, tool, status, senderThreadId, receiverThreadId?, newThreadId?, prompt?, agentStatus?}。
webSearch - エージェントが発行した Web 検索リクエスト用の {id, query, action?}。
imageView - エージェントが画像ビューアーツールを呼び出したときに送信される {id, path}。
enteredReviewMode - レビュアーの開始時に送信される {id, review}。
exitedReviewMode - レビュアーの完了時に送信される {id, review}。
contextCompaction - Codex が会話履歴をコンパクションしたときに送信される {id}。

webSearch.action では、アクション type は search（query?、queries?）、openPage（url?）、または findInPage（url?、pattern?）のいずれかです。

App server では従来の thread/compacted 通知は非推奨です。代わりに contextCompaction アイテムを使用してください。

すべてのアイテムは、共通する 2 つのライフサイクルイベントを送信します。

item/started - 新しい作業単位の開始時に完全な item を送信します。item.id はデルタで使用される itemId と一致します。
item/completed - 作業の完了時に最終的な item を送信します。これを正しい状態として扱ってください。

アイテムのデルタ

item/agentMessage/delta - エージェントメッセージにストリーミングされたテキストを追加します。
item/plan/delta - 提案された計画テキストをストリーミングします。最終的な plan アイテムは、連結したデルタと完全には一致しない場合があります。
item/reasoning/summaryTextDelta - 読みやすい推論サマリーをストリーミングします。新しいサマリーセクションが開くと summaryIndex が増加します。
item/reasoning/summaryPartAdded - 推論サマリーのセクション間の境界を示します。
item/reasoning/textDelta - 生の推論テキストをストリーミングします（モデルでサポートされている場合）。
item/commandExecution/outputDelta - コマンドの stdout/stderr をストリーミングします。デルタを順番に追加してください。
item/fileChange/outputDelta - 従来の apply_patch テキスト出力用の非推奨の互換性通知です。現在の app-server バージョンでは送信されません。代わりに fileChange アイテムと turn/diff/updated を使用してください。

エラー

ターンが失敗すると、サーバーは { error: { message, codexErrorInfo?, additionalDetails? } } を持つ error イベントを送信し、その後 status: "failed" でターンを終了します。上流の HTTP ステータスが利用可能な場合は、codexErrorInfo.httpStatusCode に含まれます。

一般的な codexErrorInfo の値は次のとおりです。

ContextWindowExceeded
UsageLimitExceeded
HttpConnectionFailed（上流の 4xx/5xx エラー）
ResponseStreamConnectionFailed
ResponseStreamDisconnected
ResponseTooManyFailedAttempts
BadRequest、Unauthorized、SandboxError、InternalServerError、Other

上流の HTTP ステータスが利用可能な場合、サーバーは関連する codexErrorInfo バリアントの httpStatusCode でそれを転送します。

承認

ユーザーの Codex 設定によっては、コマンドの実行やファイルの変更に承認が必要です。App-server はサーバー起点の JSON-RPC リクエストをクライアントへ送信し、クライアントは決定ペイロードで応答します。

コマンド実行の決定：accept、acceptForSession、decline、cancel、または { "acceptWithExecpolicyAmendment": { "execpolicy_amendment": ["cmd", "..."] } }。
ファイル変更の決定：accept、acceptForSession、decline、cancel。
リクエストには threadId と turnId が含まれます。これらを使用して、UI の状態をアクティブな会話に限定してください。
サーバーは作業を再開または拒否し、item/completed でアイテムを終了します。

コマンド実行の承認

メッセージの順序：

item/started は、command、cwd、およびその他のフィールドを持つ保留中の commandExecution アイテムを表示します。
item/commandExecution/requestApproval には、itemId、threadId、turnId、オプションの reason、オプションの command、オプションの cwd、オプションの commandActions、オプションの proposedExecpolicyAmendment、オプションの networkApprovalContext、オプションの availableDecisions が含まれます。initialize.params.capabilities.experimentalApi = true の場合、ペイロードには、要求されたコマンドごとのサンドボックスアクセスを記述する実験的な additionalPermissions も含められます。additionalPermissions 内のファイルシステムパスは、wire 上ではすべて絶対パスです。
クライアントは、上記のコマンド実行承認の決定のいずれかで応答します。
serverRequest/resolved は、保留中のリクエストへの回答またはクリアを確認します。
item/completed は、status: completed | failed | declined を持つ最終的な commandExecution アイテムを返します。

networkApprovalContext が存在する場合、プロンプトは管理対象ネットワークアクセス用であり、一般的なシェルコマンドの承認ではありません。現在の v2 スキーマは対象の host と protocol を公開します。クライアントではネットワーク固有のプロンプトを表示し、command がユーザーにとって意味のあるシェルコマンドのプレビューであることを前提にしないでください。

Codex は、同時に発生したネットワーク承認プロンプトを宛先（host、プロトコル、ポート）ごとにグループ化します。そのため app-server は、同じ宛先に対してキューに入っている複数のリクエストを 1 つのプロンプトで許可する場合があります。一方、同じホストでもポートが異なる場合は別々に扱われます。

ファイル変更の承認

メッセージの順序：

item/started は、提案された changes と status: "inProgress" を持つ fileChange アイテムを送信します。
item/fileChange/requestApproval には、itemId、threadId、turnId、オプションの reason、オプションの grantRoot が含まれます。
クライアントは、上記のファイル変更承認の決定のいずれかで応答します。
serverRequest/resolved は、保留中のリクエストへの回答またはクリアを確認します。
item/completed は、status: completed | failed | declined を持つ最終的な fileChange アイテムを返します。

`tool/requestUserInput`

クライアントが item/tool/requestUserInput に応答すると、app-server は { threadId, requestId } を持つ serverRequest/resolved を送信します。クライアントが応答する前に、ターンの開始、完了、または中断によって保留中のリクエストがクリアされた場合、サーバーはそのクリーンアップについて同じ通知を送信します。

リクエストの params には、整数のミリ秒タイムアウトまたは null として autoResolutionMs が含まれます。これがある場合、ホストクライアントは、ユーザーが応答しなければその時間が経過した後にプロンプトを自動的に解決できます。

権限リクエスト

組み込みの request_permissions ツールは、 threadId、turnId、itemId、 environmentId、cwd、オプションの reason、および要求されたネットワークまたはファイルシステムの権限を持つ item/permissions/requestApproval を送信します。許可するサブセットのみを含む permissions で応答してください。同じセッションの後続ターンでも許可を維持するには、scope を "session" に設定します。ターン限定の許可にするには、省略するか "turn" を使用します。要求されていない権限は無視されます。

MCP サーバーの elicitation リクエスト

MCP サーバーは mcpServer/elicitation/request によってターンを中断できます。リクエストには、threadId、オプションの turnId、serverName、および次のいずれかのリクエスト形式が含まれます。

mode: "form" または mode: "openai/form"。message と requestedSchema を含みます。
mode: "url"。message、url、elicitationId を含みます。

action: "accept" と要求された content、または action: "decline" か "cancel" と content: null で応答します。その後、app-server は serverRequest/resolved を送信します。openai/form バリアントを受信するには、 initialize.params.capabilities.mcpServerOpenaiFormElicitation でオプトインしてください。

動的ツール呼び出し（実験的）

thread/start の dynamicTools と、対応する item/tool/call のリクエストまたはレスポンスフローは、実験的な API です。

動的ツール名と名前空間名は、Responses API の命名制約に従う必要があります。組み込みの Codex ツールで使用されている予約済み名前空間名は避けてください。

ターン中に動的ツールが呼び出されると、app-server は次の処理を行います。

item.type = "dynamicToolCall"、status = "inProgress"、さらに tool と arguments を持つ item/started を送信します。
サーバーからクライアントへのリクエストとして item/tool/call を送信します。
クライアントが、返されたコンテンツアイテムを含むペイロードで応答します。
item.type = "dynamicToolCall"、最終的な status、および返された contentItems または success の値を持つ item/completed を送信します。

MCP ツール呼び出しの承認（アプリ）

アプリ（コネクター）のツール呼び出しにも承認が必要な場合があります。アプリのツール呼び出しに副作用がある場合、サーバーは tool/requestUserInput を使用し、承認、拒否、キャンセルなどの選択肢を提示して承認を求めることがあります。ツールに低い権限を示す注釈もある場合でも、破壊的操作の注釈があれば必ず承認が求められます。ユーザーが拒否またはキャンセルすると、関連する mcpToolCall アイテムはツールを実行せず、エラーとして完了します。

スキル

ユーザーテキスト入力に $<skill-name> を含めると、スキルを呼び出せます。サーバーがモデルによる名前解決に依存せず、完全なスキルの指示を挿入できるように、skill 入力アイテムも追加することを推奨します。

{
  "method": "turn/start",
  "id": 101,
  "params": {
    "threadId": "thread-1",
    "input": [
      {
        "type": "text",
        "text": "$skill-creator Add a new skill for triaging flaky CI."
      },
      {
        "type": "skill",
        "name": "skill-creator",
        "path": "/Users/me/.codex/skills/skill-creator/SKILL.md"
      }
    ]
  }
}

skill アイテムを省略した場合も、モデルは $<skill-name> マーカーを解析してスキルの検索を試みますが、レイテンシーが増加する可能性があります。

例：

$skill-creator Add a new skill for triaging flaky CI and include step-by-step usage.

利用可能なスキルを取得するには skills/list を使用します（オプションで cwds によりスコープを指定し、forceReload を設定できます）。さらに、特定の cwd 値に対する user スコープとして、追加の絶対パスをスキャンする perCwdExtraUserRoots も含められます。App-server は、cwd が cwds に存在しないエントリを無視します。skills/list は cwd ごとにキャッシュされた結果を再利用する場合があります。ディスクから更新するには forceReload: true を設定します。SKILL.json が存在する場合、サーバーはそこから interface と dependencies を読み取ります。

{ "method": "skills/list", "id": 25, "params": {
  "cwds": ["/Users/me/project", "/Users/me/other-project"],
  "forceReload": true,
  "perCwdExtraUserRoots": [
    {
      "cwd": "/Users/me/project",
      "extraUserRoots": ["/Users/me/shared-skills"]
    }
  ]
} }
{ "id": 25, "result": {
  "data": [{
    "cwd": "/Users/me/project",
    "skills": [
      {
        "name": "skill-creator",
        "description": "Create or update a Codex skill",
        "enabled": true,
        "interface": {
          "displayName": "Skill Creator",
          "shortDescription": "Create or update a Codex skill"
        },
        "dependencies": {
          "tools": [
            {
              "type": "env_var",
              "value": "GITHUB_TOKEN",
              "description": "GitHub API token"
            },
            {
              "type": "mcp",
              "value": "github",
              "transport": "streamable_http",
              "url": "https://example.com/mcp"
            }
          ]
        }
      }
    ],
    "errors": []
  }]
} }

サーバーは、監視対象のローカルスキルファイルが変更されたときにも skills/changed 通知を送信します。これを無効化シグナルとして扱い、必要に応じて現在の params で skills/list を再実行してください。

パスを指定してスキルを有効または無効にするには、次のようにします。

{
  "method": "skills/config/write",
  "id": 26,
  "params": {
    "path": "/Users/me/.codex/skills/skill-creator/SKILL.md",
    "enabled": false
  }
}

アプリ（コネクター）

app/installed を使用すると、コミット済みの最新のインストール済みアプリのランタイムスナップショットを読み取れます。各結果には、アプリの id、runtimeName（または null）、有効な enabled の状態、および callable の状態が含まれます。アプリを呼び出せるのは、有効な構成でアプリが有効化され、かつモデルから見えるツールのうち少なくとも 1 つがアプリとツールのポリシーに準拠している場合のみです。

{
  "method": "app/installed",
  "id": 49,
  "params": {
    "threadId": "thread-1",
    "forceRefresh": false
  }
}
{
  "id": 49,
  "result": {
    "apps": [
      {
        "id": "demo-app",
        "runtimeName": "Demo App",
        "enabled": true,
        "callable": true
      }
    ]
  }
}

読み込み済みスレッドの構成ではなくグローバル構成を使用するには、threadId を省略します。読み取る前にコネクターのランタイムスナップショットを更新するには、forceRefresh: true を設定します。グローバルまたはワークスペースのポリシーによってアプリアクセスがブロックされている場合、検出されたアプリは enabled と callable が false に設定された状態で引き続き表示されることがあります。

利用可能なアプリを取得するには app/list を使用します。CLI/TUI では /apps がユーザー向けの選択 UI です。カスタムクライアントでは app/list を直接呼び出します。各エントリには、isAccessible（ユーザーが利用可能）と isEnabled（config.toml で有効）の両方が含まれるため、クライアントはインストール／アクセスの状態とローカルでの有効化状態を区別できます。アプリのエントリには、オプションの branding、appMetadata、labels フィールドが含まれる場合もあります。

{ "method": "app/list", "id": 50, "params": {
  "cursor": null,
  "limit": 50,
  "threadId": "thread-1",
  "forceRefetch": false
} }
{ "id": 50, "result": {
  "data": [
    {
      "id": "demo-app",
      "name": "Demo App",
      "description": "Example connector for documentation.",
      "logoUrl": "https://example.com/demo-app.png",
      "logoUrlDark": null,
      "distributionChannel": null,
      "branding": null,
      "appMetadata": null,
      "labels": null,
      "installUrl": "https://chatgpt.com/apps/demo-app/demo-app",
      "isAccessible": true,
      "isEnabled": true
    }
  ],
  "nextCursor": null
} }

threadId を指定すると、アプリの機能ゲート（features.apps）はそのスレッドの構成スナップショットを使用します。省略した場合、app-server は最新のグローバル構成を使用します。

app/list は、アクセス可能なアプリとディレクトリアプリの両方が読み込まれた後に返されます。アプリのキャッシュをバイパスして最新データを取得するには、forceRefetch: true を設定します。キャッシュエントリは、更新に成功した場合にのみ置き換えられます。

また、いずれかのソース（アクセス可能なアプリまたはディレクトリアプリ）の読み込みが完了するたびに、サーバーは app/list/updated 通知を送信します。各通知には、最新の統合済みアプリリストが含まれます。

{
  "method": "app/list/updated",
  "params": {
    "data": [
      {
        "id": "demo-app",
        "name": "Demo App",
        "description": "Example connector for documentation.",
        "logoUrl": "https://example.com/demo-app.png",
        "logoUrlDark": null,
        "distributionChannel": null,
        "branding": null,
        "appMetadata": null,
        "labels": null,
        "installUrl": "https://chatgpt.com/apps/demo-app/demo-app",
        "isAccessible": true,
        "isEnabled": true
      }
    ]
  }
}

アプリ ID がすでに分かっており、インストール済みランタイムの状態ではなくアプリのメタデータが必要な場合は、app/read を使用します。appIds は最大 100 件まで渡せます。サーバーは、重複する各 ID の最初の出現のみを保持し、apps と missingAppIds の両方でその順序を維持します。不明またはアクセス不能なアプリは、リクエスト全体を失敗させずに missingAppIds で返されます。

{
  "method": "app/read",
  "id": 52,
  "params": {
    "appIds": ["demo-app", "missing-app"],
    "includeTools": true
  }
}
{
  "id": 52,
  "result": {
    "apps": [
      {
        "id": "demo-app",
        "name": "Demo App",
        "description": "Example connector for documentation.",
        "iconUrl": null,
        "iconUrlDark": null,
        "distributionChannel": null,
        "installUrl": null,
        "pluginDisplayNames": [],
        "toolSummaries": [
          {
            "name": "search",
            "title": "Search",
            "description": "Search the app.",
            "isEnabled": true,
            "disabledReason": null,
            "isReadOnly": true
          }
        ]
      }
    ],
    "missingAppIds": ["missing-app"]
  }
}

表示専用の公開ツールサマリーをリクエストするには、includeTools: true を設定します。メタデータのレスポンスには、インストール済みアプリのランタイム状態は含まれず、ツール呼び出しも許可されません。有効な enabled と callable の状態を確認するには、app/installed を使用します。

テキスト入力に $<app-slug> を挿入し、app://<id> パスを持つ mention 入力アイテムを追加すると、アプリを呼び出せます（推奨）。

{
  "method": "turn/start",
  "id": 51,
  "params": {
    "threadId": "thread-1",
    "input": [
      {
        "type": "text",
        "text": "$demo-app Pull the latest updates from the team."
      },
      {
        "type": "mention",
        "name": "Demo App",
        "path": "app://demo-app"
      }
    ]
  }
}

アプリ設定用の Config RPC の例

config/read、config/value/write、config/batchWrite を使用すると、config.toml 内のアプリ制御を確認または更新できます。

有効なアプリ構成の形式（_default とツールごとの上書きを含む）を読み取るには、次のようにします。

{ "method": "config/read", "id": 60, "params": { "includeLayers": false } }
{ "id": 60, "result": {
  "config": {
    "apps": {
      "_default": {
        "enabled": true,
        "destructive_enabled": true,
        "open_world_enabled": true,
        "approvals_reviewer": "user",
        "default_tools_approval_mode": "auto"
      },
      "google_drive": {
        "enabled": true,
        "destructive_enabled": false,
        "approvals_reviewer": "auto_review",
        "default_tools_approval_mode": "prompt",
        "tools": {
          "files/delete": { "enabled": false, "approval_mode": "approve" }
        }
      }
    }
  }
} }

apps._default.approvals_reviewer は、アプリごとの値で上書きされない限り、すべてのアプリのレビュアーを設定します。両方とも省略されている場合、アプリはトップレベルの approvals_reviewer 値を継承します。apps._default.default_tools_approval_mode は、アプリごとまたはツールごとの上書きがないツールについて、フォールバックの承認モードを設定します。管理対象の承認モード要件は、ツールの承認モード設定より優先されます。

単一のアプリ設定を更新するには、次のようにします。

{
  "method": "config/value/write",
  "id": 61,
  "params": {
    "keyPath": "apps.google_drive.default_tools_approval_mode",
    "value": "prompt",
    "mergeStrategy": "replace"
  }
}

複数のアプリ編集をアトミックに適用するには、次のようにします。

{
  "method": "config/batchWrite",
  "id": 62,
  "params": {
    "edits": [
      {
        "keyPath": "apps._default.destructive_enabled",
        "value": false,
        "mergeStrategy": "upsert"
      },
      {
        "keyPath": "apps.google_drive.tools.files/delete.approval_mode",
        "value": "approve",
        "mergeStrategy": "upsert"
      }
    ]
  }
}

外部エージェントの構成を検出してインポートする

externalAgentConfig/detect を使用して移行可能な外部エージェントのアーティファクトを検出し、選択したエントリを externalAgentConfig/import に渡します。

検出の例：

{ "method": "externalAgentConfig/detect", "id": 63, "params": {
  "includeHome": true,
  "cwds": ["/Users/me/project"]
} }
{ "id": 63, "result": {
  "items": [
    {
      "itemType": "AGENTS_MD",
      "description": "Import /Users/me/project/CLAUDE.md to /Users/me/project/AGENTS.md.",
      "cwd": "/Users/me/project"
    },
    {
      "itemType": "SKILLS",
      "description": "Copy skill folders from /Users/me/.claude/skills to /Users/me/.agents/skills.",
      "cwd": null
    }
  ]
} }

インポートの例：

{ "method": "externalAgentConfig/import", "id": 64, "params": {
  "migrationItems": [
    {
      "itemType": "AGENTS_MD",
      "description": "Import /Users/me/project/CLAUDE.md to /Users/me/project/AGENTS.md.",
      "cwd": "/Users/me/project"
    }
  ],
  "source": "claude-code"
} }
{ "id": 64, "result": { "importId": "8ae96ff3-3425-4f4c-8772-b6fd61502868" } }

オプションのトップレベル source インポートパラメーターは、選択した移行アイテムを生成した製品を示すラベルです。

サーバーは、各アイテムタイプの完了時に externalAgentConfig/import/progress を送信し、すべての同期およびバックグラウンドのインポートが完了すると externalAgentConfig/import/completed を送信します。これらの通知には、レスポンスと同じ importId、およびタイプごとの successes と failures を持つ itemTypeResults が含まれます。完了通知は、レスポンスの直後に届く場合も、バックグラウンドのリモートインポートが完了した後に届く場合もあります。

{ "method": "externalAgentConfig/import/progress", "params": {
  "importId": "8ae96ff3-3425-4f4c-8772-b6fd61502868",
  "itemTypeResults": [
    {
      "itemType": "AGENTS_MD",
      "successes": [
        { "itemType": "AGENTS_MD", "cwd": "/Users/me/project", "source": null, "target": "/Users/me/project/AGENTS.md" }
      ],
      "failures": []
    }
  ]
} }
{ "method": "externalAgentConfig/import/completed", "params": {
  "importId": "8ae96ff3-3425-4f4c-8772-b6fd61502868",
  "itemTypeResults": [
    {
      "itemType": "AGENTS_MD",
      "successes": [
        { "itemType": "AGENTS_MD", "cwd": "/Users/me/project", "source": null, "target": "/Users/me/project/AGENTS.md" }
      ],
      "failures": []
    }
  ]
} }

以前に完了したインポートを読み取るには、次のようにします。

{ "method": "externalAgentConfig/import/readHistories", "id": 65 }
{ "id": 65, "result": { "data": [
  {
    "importId": "8ae96ff3-3425-4f4c-8772-b6fd61502868",
    "completedAtMs": 1781784000000,
    "successes": [
      { "itemType": "AGENTS_MD", "cwd": "/Users/me/project", "source": null, "target": "/Users/me/project/AGENTS.md" }
    ],
    "failures": []
  }
] } }

サポートされている itemType の値は、AGENTS_MD、CONFIG、SKILLS、PLUGINS、 MCP_SERVER_CONFIG、SUBAGENTS、HOOKS、COMMANDS、SESSIONS です。 PLUGINS アイテムでは、details.plugins に各 marketplaceName と、Codex が移行を試行できる pluginNames が一覧表示されます。検出では、まだ作業が必要なアイテムのみが返されます。たとえば、AGENTS.md がすでに存在し、空でない場合、Codex は AGENTS の移行をスキップします。また、スキルのインポートでは既存のスキルディレクトリは上書きされません。

.claude/settings.json からプラグインを検出するとき、Codex は extraKnownMarketplaces に構成されているマーケットプレイスのソースを読み取ります。enabledPlugins に claude-plugins-official のプラグインが含まれているもののマーケットプレイスのソースがない場合、Codex は anthropics/claude-plugins-official をソースとして推測します。

認証エンドポイント

JSON-RPC の認証／アカウントサーフェスは、リクエスト／レスポンスメソッドとサーバー起点の通知（id なし）を公開します。これらを使用して、認証状態の確認、ログインの開始またはキャンセル、ログアウト、ChatGPT のレート制限の確認、クレジット枯渇または使用量上限到達についてのワークスペース所有者への通知を行えます。

認証モード

Codex は次の認証モードをサポートします。account/updated.authMode はアクティブなモードを示し、利用可能な場合は現在の ChatGPT planType を含みます。account/read はアカウントとプランの詳細も報告します。

API key（apikey） - 呼び出し元は type: "apiKey" で OpenAI API key を指定し、Codex は API リクエスト用にそれを保存します。
ChatGPT マネージド（chatgpt） - Codex が ChatGPT OAuth フローを管理し、トークンを永続化して自動的に更新します。ブラウザフローでは type: "chatgpt"、デバイスコードフローでは type: "chatgptDeviceCode" から開始します。
ChatGPT 外部トークン（chatgptAuthTokens） - 実験的な機能で、ユーザーの ChatGPT 認証ライフサイクルをすでに管理しているホストアプリ向けです。ホストアプリは accessToken、chatgptAccountId、およびオプションの chatgptPlanType を直接指定し、要求されたときにトークンを更新する必要があります。
Amazon Bedrock - account/read は Bedrock アカウントを type: "amazonBedrock" として報告し、認証情報が Codex 管理の Bedrock API key（credentialSource: "codexManaged"）と外部の AWS 認証情報チェーン（credentialSource: "awsManaged"）のどちらから取得されるかを示します。account/updated.authMode は Codex 管理の Bedrock API key に bedrockApiKey を使用します。

API の概要

account/read - 現在のアカウント情報を取得します。オプションでトークンを更新できます。
account/login/start - ログイン（apiKey、chatgpt、chatgptDeviceCode、または実験的な chatgptAuthTokens）を開始します。
account/login/completed（通知）- ログイン試行が完了したとき（成功またはエラー）に送信されます。
account/login/cancel - 保留中のマネージド ChatGPT ログインを loginId でキャンセルします。
account/logout - サインアウトします。account/updated がトリガーされます。
account/updated（通知）- 認証モード（authMode: apikey、chatgpt、chatgptAuthTokens、agentIdentity、personalAccessToken、bedrockApiKey、または null）が変更されるたびに送信され、利用可能な場合は planType を含みます。
account/chatgptAuthTokens/refresh（サーバーリクエスト）- 認可エラーの発生後に、外部で管理されている新しい ChatGPT トークンを要求します。
account/rateLimits/read - ChatGPT のレート制限を取得します。
account/rateLimits/updated（通知）- ユーザーの ChatGPT レート制限が変更されるたびに送信されます。
account/sendAddCreditsNudgeEmail - クレジットの枯渇または使用量上限への到達について、ワークスペース所有者にメールを送信するよう ChatGPT に依頼します。
account/rateLimitResetCredit/consume - 呼び出し元が指定した idempotencyKey 値を使用して、獲得済みのレート制限リセットを 1 回分使用します。
account/usage/read - ChatGPT アカウントのトークンアクティビティのサマリーと日別バケットを取得します。
account/workspaceMessages/read - 利用可能な場合は通知の見出しも含め、アクティブなワークスペースメッセージを取得します。
mcpServer/oauthLogin/completed（通知）- mcpServer/oauth/login フローの完了後に送信されます。ペイロードには { name, threadId, success, error? } が含まれます。アプリスコープまたはプラグインの OAuth フローでは、threadId を null にできます。
mcpServer/startupStatus/updated（通知）- 構成済み MCP サーバーの起動状態が変化したときに送信されます。ペイロードには { threadId, name, status, error, failureReason } が含まれます。アプリスコープの起動では、threadId は null です。起動に失敗した場合、failureReason: "reauthenticationRequired" は保存済みの OAuth 認証情報が期限切れで更新できなかったことを意味するため、クライアントではサーバーへの再接続を案内してください。

1）認証状態を確認する

リクエスト：

{ "method": "account/read", "id": 1, "params": { "refreshToken": false } }

レスポンスの例：

{ "id": 1, "result": { "account": null, "requiresOpenaiAuth": false } }

{ "id": 1, "result": { "account": null, "requiresOpenaiAuth": true } }

{
  "id": 1,
  "result": { "account": { "type": "apiKey" }, "requiresOpenaiAuth": true }
}

{
  "id": 1,
  "result": {
    "account": {
      "type": "amazonBedrock",
      "credentialSource": "codexManaged"
    },
    "requiresOpenaiAuth": false
  }
}

{
  "id": 1,
  "result": {
    "account": {
      "type": "amazonBedrock",
      "credentialSource": "awsManaged"
    },
    "requiresOpenaiAuth": false
  }
}

{
  "id": 1,
  "result": {
    "account": {
      "type": "chatgpt",
      "email": "user@example.com",
      "planType": "pro"
    },
    "requiresOpenaiAuth": true
  }
}

フィールドに関する注意：

refreshToken（boolean）：マネージド ChatGPT モードでトークンの更新を強制するには、true を設定します。外部トークンモード（chatgptAuthTokens）では、app-server はこのフラグを無視します。
ChatGPT アカウントにメールアドレスがない場合、email は null になります。
requiresOpenaiAuth はアクティブなプロバイダーを示します。false の場合、Codex は OpenAI の認証情報なしで実行できます。
Amazon Bedrock は、Codex が管理する Bedrock API key を使用する場合、 credentialSource: "codexManaged" を報告します。外部の AWS 認証情報パスでは、 credentialSource: "awsManaged" を報告します。これは選択された認証情報のソースを識別するものであり、AWS 認証情報チェーンで認証情報を解決できることを検証するものではありません。

2）API key でログインする

次を送信します。

   {
     "method": "account/login/start",
     "id": 2,
     "params": { "type": "apiKey", "apiKey": "sk-..." }
   }

次のレスポンスを待ちます。

   { "id": 2, "result": { "type": "apiKey" } }

通知：

   {
     "method": "account/login/completed",
     "params": { "loginId": null, "success": true, "error": null }
   }

   {
     "method": "account/updated",
     "params": { "authMode": "apikey", "planType": null }
   }

3）ChatGPT でログインする（ブラウザフロー）

開始します。

   {
     "method": "account/login/start",
     "id": 3,
     "params": {
       "type": "chatgpt",
       "useHostedLoginSuccessPage": true,
       "appBrand": "chatgpt"
     }
   }

デフォルトでは、ブラウザのコールバックが成功するとローカルの成功ページにリダイレクトされます。組織のセットアップが不要な場合にホストされた成功ページを使用するには、useHostedLoginSuccessPage: true を設定します。ホストされた成功ページを有効にすると、appBrand は "codex" または "chatgpt" にできます。省略した場合や null の値は、デフォルトで "codex" になります。

   {
     "id": 3,
     "result": {
       "type": "chatgpt",
       "loginId": "<uuid>",
       "authUrl": "https://chatgpt.com/...&redirect_uri=http%3A%2F%2Flocalhost%3A<port>%2Fauth%2Fcallback"
     }
   }

ブラウザで authUrl を開きます。app-server がローカルコールバックをホストします。
通知を待ちます。

   {
     "method": "account/login/completed",
     "params": { "loginId": "<uuid>", "success": true, "error": null }
   }

   {
     "method": "account/updated",
     "params": { "authMode": "chatgpt", "planType": "plus" }
   }

3b）ChatGPT でログインする（デバイスコードフロー）

クライアントがサインイン手順を管理する場合や、ブラウザのコールバックが不安定な場合は、このフローを使用します。

開始します。

   {
     "method": "account/login/start",
     "id": 4,
     "params": { "type": "chatgptDeviceCode" }
   }

   {
     "id": 4,
     "result": {
       "type": "chatgptDeviceCode",
       "loginId": "<uuid>",
       "verificationUrl": "https://auth.openai.com/codex/device",
       "userCode": "ABCD-1234"
     }
   }

verificationUrl と userCode をユーザーに表示します。UX はフロントエンドが管理します。
通知を待ちます。

   {
     "method": "account/login/completed",
     "params": { "loginId": "<uuid>", "success": true, "error": null }
   }

   {
     "method": "account/updated",
     "params": { "authMode": "chatgpt", "planType": "plus" }
   }

3c）外部管理の ChatGPT トークン（`chatgptAuthTokens`）でログインする

この実験的なモードは、ホストアプリケーションがユーザーの ChatGPT 認証ライフサイクルを管理し、トークンを直接指定する場合にのみ使用してください。このログインタイプを使用する前に、クライアントは initialize の実行中に capabilities.experimentalApi = true を設定する必要があります。

次を送信します。

   {
     "method": "account/login/start",
     "id": 7,
     "params": {
       "type": "chatgptAuthTokens",
       "accessToken": "<jwt>",
       "chatgptAccountId": "org-123",
       "chatgptPlanType": "business"
     }
   }

次のレスポンスを待ちます。

   { "id": 7, "result": { "type": "chatgptAuthTokens" } }

通知：

   {
     "method": "account/login/completed",
     "params": { "loginId": null, "success": true, "error": null }
   }

   {
     "method": "account/updated",
     "params": { "authMode": "chatgptAuthTokens", "planType": "business" }
   }

サーバーは 401 Unauthorized を受信すると、更新されたトークンをホストアプリに要求する場合があります。

{
  "method": "account/chatgptAuthTokens/refresh",
  "id": 8,
  "params": { "reason": "unauthorized", "previousAccountId": "org-123" }
}
{ "id": 8, "result": { "accessToken": "<jwt>", "chatgptAccountId": "org-123", "chatgptPlanType": "business" } }

更新のレスポンスが成功すると、サーバーは元のリクエストを再試行します。リクエストは約 10 秒でタイムアウトします。

4）ChatGPT のログインをキャンセルする

{ "method": "account/login/cancel", "id": 4, "params": { "loginId": "<uuid>" } }
{ "method": "account/login/completed", "params": { "loginId": "<uuid>", "success": false, "error": "..." } }

5）ログアウトする

{ "method": "account/logout", "id": 5 }
{ "id": 5, "result": {} }
{ "method": "account/updated", "params": { "authMode": null, "planType": null } }

6）レート制限（ChatGPT）

{ "method": "account/rateLimits/read", "id": 6 }
{ "id": 6, "result": {
  "rateLimits": {
    "limitId": "codex",
    "limitName": null,
    "primary": { "usedPercent": 25, "windowDurationMins": 15, "resetsAt": 1730947200 },
    "secondary": null,
    "rateLimitReachedType": null
  },
  "rateLimitsByLimitId": {
    "codex": {
      "limitId": "codex",
      "limitName": null,
      "primary": { "usedPercent": 25, "windowDurationMins": 15, "resetsAt": 1730947200 },
      "secondary": null,
      "rateLimitReachedType": null
    },
    "codex_other": {
      "limitId": "codex_other",
      "limitName": "codex_other",
      "primary": { "usedPercent": 42, "windowDurationMins": 60, "resetsAt": 1730950800 },
      "secondary": null,
      "rateLimitReachedType": null
    }
  },
  "rateLimitResetCredits": {
    "availableCount": 2,
    "credits": [{
      "id": "RateLimitResetCredit_1",
      "resetType": "codexRateLimits",
      "status": "available",
      "grantedAt": 1781654400,
      "expiresAt": 1784246400,
      "title": "Rate-limit reset",
      "description": "Reset an eligible Codex rate-limit window."
    }]
  }
} }
{ "method": "account/rateLimits/updated", "params": {
  "rateLimits": {
    "limitId": "codex",
    "primary": { "usedPercent": 31, "windowDurationMins": 15, "resetsAt": 1730948100 }
  }
} }

フィールドに関する注意：

rateLimits は、後方互換性のある単一バケット表示です。
rateLimitsByLimitId（存在する場合）は、計測対象の limit_id（たとえば codex）をキーとする複数バケット表示です。
limitId は計測対象バケットの識別子です。
limitName は、オプションのユーザー向けバケットラベルです。
usedPercent は、クォータ期間内の現在の使用量です。
windowDurationMins は、クォータ期間の長さです。
resetsAt は、次回のリセット時刻を示す Unix タイムスタンプ（秒）です。
サーバーがバケットに関連付けられた ChatGPT プランを返す場合、planType が含まれます。
サーバーがワークスペースの残りクレジットの詳細を返す場合、credits が含まれます。
rateLimitReachedType は、上限に到達した場合にサーバーが分類した制限状態を識別します。
rateLimitResetCredits には、サービスが提供する場合、利用可能な獲得済みリセット数が含まれます。それ以外の場合は null です。
件数のみが判明している場合、rateLimitResetCredits.credits は null です。空の配列は、サービスが詳細を取得し、利用可能なクレジットがなかったことを意味します。サービスは詳細行の数を制限する場合があるため、availableCount を正として扱ってください。
各詳細行には、不透明な id、resetType、status、grantedAt、expiresAt（null の場合があります）、title（null の場合があります）、description（null の場合があります）が含まれます。
リセットを使用した後は、account/rateLimits/read を取得してください。

7）トークン使用量（ChatGPT）

account/usage/read を使用すると、ChatGPT のトークンアクティビティのサマリーフィールドとオプションの日別バケットを取得できます。

{ "method": "account/usage/read", "id": 7 }
{ "id": 7, "result": {
  "summary": {
    "lifetimeTokens": 1234567,
    "peakDailyTokens": 45678,
    "longestRunningTurnSec": 540,
    "currentStreakDays": 8,
    "longestStreakDays": 14
  },
  "dailyUsageBuckets": [
    { "startDate": "2026-06-18", "tokens": 12345 }
  ]
} }

フィールドに関する注意：

サービスがその指標を返していない場合、summary の値は null になることがあります。
dailyUsageBuckets は null の場合があります。存在する場合、各バケットには startDate と tokens が含まれます。
このエンドポイントには、Codex サービスを基盤とする認証が必要です。ChatGPT、外部の ChatGPT トークン、エージェント ID、およびパーソナルアクセストークンによる認証は使用できますが、 API key のみの認証と Bedrock 認証は使用できません。

8）獲得済みのレート制限リセット（ChatGPT）

account/rateLimitResetCredit/consume を使用すると、獲得済みのリセットを 1 回分使用できます。

{ "method": "account/rateLimitResetCredit/consume", "id": 8, "params": { "idempotencyKey": "8ae96ff3-3425-4f4c-8772-b6fd61502868", "creditId": "RateLimitResetCredit_1" } }
{ "id": 8, "result": { "outcome": "reset" } }

フィールドに関する注意：

idempotencyKey は空にできません。論理的な引き換え試行ごとに UUID を使用し、その試行を再試行するときは同じ値を再利用してください。
creditId はオプションです。指定する場合、account/rateLimits/read から取得した空でない不透明な ID である必要があります。省略すると、サービスが次に利用可能なクレジットを選択します。
reset は、クレジットが使用されたことを意味します。
alreadyRedeemed は、同じ引き換えが以前に完了していることを意味します。これを冪等な成功として扱い、アカウントの制限を更新してください。
nothingToReset は、リセット対象となるレート制限期間がないことを意味します。
noCredit は、アカウントに利用可能な獲得済みリセットクレジットがないことを意味します。
更新された期間をこのレスポンスから推測せず、リセットの使用後に account/rateLimits/read を取得してください。

9）上限についてワークスペース所有者に通知する

account/sendAddCreditsNudgeEmail を使用すると、クレジットが枯渇した場合や使用量上限に到達した場合に、ワークスペース所有者へメールを送信するよう ChatGPT に依頼できます。

{ "method": "account/sendAddCreditsNudgeEmail", "id": 9, "params": { "creditType": "credits" } }
{ "id": 9, "result": { "status": "sent" } }

ワークスペースのクレジットが枯渇した場合は creditType: "credits"、ワークスペースの使用量上限に到達した場合は creditType: "usage_limit" を使用します。所有者に最近すでに通知されている場合、レスポンスのステータスは cooldown_active になります。

10）ワークスペースメッセージ（ChatGPT）

account/workspaceMessages/read を使用すると、利用可能な場合は通知の見出しも含め、現在のワークスペースのアクティブなメッセージを取得できます。

{ "method": "account/workspaceMessages/read", "id": 10 }
{ "id": 10, "result": { "featureEnabled": true, "messages": [
  { "messageId": "msg_123", "messageType": "headline", "messageBody": "Workspace maintenance starts at 5pm.", "createdAt": 1781395200, "archivedAt": null }
] } }

CLI ターミナル UI に接続する

リモート Code Mode ホストに接続する

プロトコル

メッセージスキーマ

はじめに

中核となるプリミティブ

ライフサイクルの概要

初期化

実験的 API のオプトイン

API の概要

モデル

モデルを一覧表示する（model/list）

実験的機能を一覧表示する（experimentalFeature/list）

実行環境を調べる（実験的機能）

スレッド

スレッドを開始または再開する

スレッドの目標を管理する

保存済みスレッドを読み取る（再開なし）

スレッドのターンを一覧表示する

スレッドを一覧表示する（ページネーションとフィルター）

保存済みスレッドのメタデータを更新する

スレッドのステータス変更を追跡する

読み込み済みスレッドを一覧表示する

読み込み済みスレッドの購読を解除する

スレッドをアーカイブする

スレッドを削除する

スレッドのアーカイブを解除する

スレッドのコンパクションを開始する

スレッドのシェルコマンドを実行する

バックグラウンドターミナルをクリーンアップする

直近のターンをロールバックする

ターン

サンドボックスの読み取りアクセス（ReadOnlyAccess）

ターンを開始する

スレッドにアイテムを挿入する

アクティブなターンを誘導する

ターンを開始する（スキルの呼び出し）

ターンを中断する

レビュー

プロセス実行

コマンド実行

管理者要件を読み取る（configRequirements/read）

Windows サンドボックスのセットアップ（windowsSandbox/setupStart）

ファイルシステム

イベント

通知のオプトアウト

あいまいファイル検索イベント（実験的）

警告イベント

Windows サンドボックスのセットアップイベント

ターンイベント

アイテム

アイテムのデルタ

エラー

承認

コマンド実行の承認

ファイル変更の承認

tool/requestUserInput

権限リクエスト

MCP サーバーの elicitation リクエスト

動的ツール呼び出し（実験的）

MCP ツール呼び出しの承認（アプリ）

スキル

アプリ（コネクター）

アプリ設定用の Config RPC の例

外部エージェントの構成を検出してインポートする

認証エンドポイント

認証モード

API の概要

1）認証状態を確認する

2）API key でログインする

3）ChatGPT でログインする（ブラウザフロー）

3b）ChatGPT でログインする（デバイスコードフロー）

3c）外部管理の ChatGPT トークン（chatgptAuthTokens）でログインする

4）ChatGPT のログインをキャンセルする

5）ログアウトする

6）レート制限（ChatGPT）

7）トークン使用量（ChatGPT）

8）獲得済みのレート制限リセット（ChatGPT）

9）上限についてワークスペース所有者に通知する

10）ワークスペースメッセージ（ChatGPT）

モデルを一覧表示する（`model/list`）

実験的機能を一覧表示する（`experimentalFeature/list`）

サンドボックスの読み取りアクセス（`ReadOnlyAccess`）

管理者要件を読み取る（`configRequirements/read`）

Windows サンドボックスのセットアップ（`windowsSandbox/setupStart`）

`tool/requestUserInput`

3c）外部管理の ChatGPT トークン（`chatgptAuthTokens`）でログインする