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

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

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" } }

レスポンスは id をそのまま返し、result または error のいずれかを含みます。

{ "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 を送信します。

初期化

クライアントは、その接続でほかのメソッドを呼び出す前に、トランスポート接続ごとに 1 回だけ initialize リクエストを送信し、その後 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 - スレッド／ターンを開始せず、サーバーのサンドボックス内で単一のコマンドを実行します。
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 - 利用可能なモデルを一覧表示します（hidden: true を持つエントリを含めるには includeHidden: true を設定します）。エフォートのオプション、任意の upgrade、および inputModalities が含まれます。
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）を渡して、選択した外部エージェントの移行項目を適用します。サポートされる項目タイプには、config、skills、AGENTS.md、plugins、MCP server config、subagents、hooks、commands、sessions が含まれます。空でないインポートでは、作業の進行に応じて 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 の union が含まれます。ローカルプラグインは { "type": "local", "path": ... }、Git ベースのマーケットプレイスエントリは { "type": "git", "url": ..., "path": ..., "refName": ..., "sha": ... }、パッケージレジストリエントリは { "type": "npm", "package": ..., "version": ..., "registry": ... }、リモートカタログエントリは { "type": "remote" } を返します。リモート専用のカタログエントリでは、PluginMarketplaceEntry.path が null になる場合があります。このようなプラグインを読み取るかインストールするときは、 marketplacePath の代わりに remoteMarketplaceName を渡します。

モデル

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

モデルまたはパーソナリティのセレクターを表示する前に、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 は選択画面に表示されるモデルのみを返します。完全な一覧が必要で、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" } }

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

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

{ "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呼び出しには表示されません。サーバーは、実際にアーカイブしたスレッドごとに1件のthread/archived通知を送信します。生成された子孫スレッドをアーカイブできない場合でも、その子孫に対するアーカイブ通知なしでリクエストが成功することがあります。

スレッドを削除する

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

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

{ "method": "thread/shellCommand", "id": 26, "params": { "threadId": "thr_b", "command": "git status --short" } }
{ "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は引き続きブール値です。

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 } } }

スレッドに項目を挿入する

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"
    }
  }
}

レビュアーが完了すると、サーバーはitem/startedと、最終的なレビューテキストを持つexitedReviewMode項目を含む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 - ターン内のすべてのファイル変更を集約した最新の統合差分を含む{ 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/*通知で送られるタグ付きユニオンです。一般的な項目タイプは次のとおりです。

userMessage - ユーザー入力（text、image、localImage）のリストであるcontentを持つ{id, content}。
agentMessage - 累積されたエージェントの応答を含む{id, text, phase?}。phaseが存在する場合は、Responses APIのワイヤー値（commentary、final_answer）を使用します。
plan - プランモードで提案された計画テキストを含む{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内のファイルシステムパスは、ワイヤー上ではすべて絶対パスです。
クライアントは、上記のコマンド実行承認の決定のいずれかで応答します。
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を送信します。クライアントが応答する前に、ターンの開始、完了、中断によって保留中のリクエストがクリアされた場合も、そのクリーンアップに対して同じ通知を送信します。

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

権限リクエスト

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

MCPサーバーの追加情報要求

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通知も送信します。これを無効化シグナルとして扱い、必要に応じて現在のパラメーターで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がユーザー向けの選択画面です。カスタムクライアントでは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.toml内のアプリ制御を確認または更新するには、config/read、config/value/write、config/batchWriteを使用します。

有効なアプリ構成の形式（_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は、アプリ単位またはツール単位の上書きがないツールに対するフォールバックの承認モードを設定します。管理対象の承認モード要件は、ツールの承認モード設定より優先されます。

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

{
  "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に、Codexが移行を試行できる各marketplaceNameと 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（ブール値）：マネージド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）

ChatGPTのトークンアクティビティ要約フィールドと、省略可能な日次バケットを取得するには、 account/usage/readを使用します。

{ "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）

獲得済みのリセットを1つ消費するには、account/rateLimitResetCredit/consumeを使用します。

{ "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）上限についてワークスペース所有者へ通知する

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

{ "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サーバーの追加情報要求

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

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`）