Codex App Server¶

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

ジョブを自動化する場合や CI で Codex を実行する場合は、代わりに Codex SDK を使用してください。

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 ポートフォワーディング接続の場合にのみ使用してください。

プロトコル¶

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）: Codex のデフォルト app-server 制御ソケットまたはカスタム Unix ソケットパス上の WebSocket 接続。標準 HTTP Upgrade ハンドシェイクを使用します。
• 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.4" } }

レスポンスは 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

はじめに¶

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

例（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.4" } });

基本プリミティブ¶

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

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

ライフサイクルの概要¶

• 接続ごとに 1 回初期化する: トランスポート接続を開いた直後に、クライアントメタデータを含む initialize リクエストを送信し、initialized を発行します。このハンドシェイクより前にその接続で送信されたリクエストは、サーバーによって拒否されます。
• スレッドを開始（または再開）する: 新しい会話には thread/start、既存の会話の継続には thread/resume、履歴を新しいスレッド ID に分岐するには thread/fork を呼び出します。
• ターンを開始する: 対象の threadId とユーザー入力を指定して turn/start を呼び出します。オプションのフィールドで、モデル、パーソナリティ、cwd、サンドボックスポリシーなどを上書きできます。
• アクティブなターンを誘導する: turn/steer を呼び出すと、新しいターンを作成せずに、現在進行中のターンへユーザー入力を追加できます。
• イベントをストリーミングする: turn/start の後、標準出力で通知を読み続けます。通知には 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 を渡すと、そのターンまでの履歴をコピーし、それ以降のターンを省略します。新しいスレッドについて thread/started を発行します。返されるスレッドには、利用可能な場合、forkedFromId が含まれます。
• thread/read - 再開せずに、ID で保存済みスレッドを読み取ります。完全なターン履歴を返すには includeTurns を設定します。返される thread オブジェクトには、実行時の status が含まれます。
• thread/list - 保存済みスレッドログをページングします。カーソルベースのページネーションに加え、modelProviders、sourceKinds、archived、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 - SQLite ベースの保存済みスレッドメタデータにパッチを適用します。現在は永続化された gitInfo をサポートしています。
• 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 reviewer を起動します。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、構造化されたライト／ダークアイコン、installPolicySource を含めることができます。これは現在のリモート行では null、WORKSPACE_SETTING、IMPLICIT_CANONICAL_APP のいずれかになります。本番クライアントからはまだこのメソッドを呼び出さないでください。
• plugin/read - 開発中です。マーケットプレイスパス、またはリモートマーケットプレイス名とプラグイン名によって 1 つのプラグインを読み取ります。バンドルされたスキル、アプリ、MCP サーバー名、リモートカタログに存在する場合はリモートプラグイン shareUrl が含まれます。本番クライアントからはまだこのメソッドを呼び出さないでください。
• plugin/install - 開発中です。マーケットプレイスパスまたはリモートマーケットプレイス名からプラグインをインストールします。本番クライアントからはまだこのメソッドを呼び出さないでください。
• plugin/uninstall - 開発中です。インストール済みプラグインをアンインストールします。本番クライアントからはまだこのメソッドを呼び出さないでください。
• plugin/skill/read - リモートマーケットプレイス、プラグイン ID、スキル名によって、必要に応じてリモートプラグインのスキル Markdown を読み取ります。
• app/list - 利用可能なアプリ（コネクター）を、ページネーションおよびアクセシビリティ／有効化メタデータ付きで一覧表示します。
• 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 サーバー、ツール、リソース、認証ステータスを一覧表示します（カーソル + limit ページネーション）。完全なデータには 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 - cwd（ホームの場合は null）を指定した明示的な migrationItems によって、選択した外部エージェント移行項目を適用します。サポートされる項目タイプには、設定、スキル、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 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.4",
    "model": "gpt-5.4",
    "displayName": "GPT-5.4",
    "hidden": false,
    "defaultReasoningEffort": "medium",
    "supportedReasoningEfforts": [{
      "reasoningEffort": "low",
      "description": "Lower latency"
    }],
    "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、cwd、useStateDbOnly、searchTerm、実験的な parentThreadId または ancestorThreadId フィルタリングをサポートします。
• thread/loaded/list は、現在メモリ内にあるスレッド ID を返します。
• thread/archive はスレッドの永続化された JSONL ログをアーカイブ済みディレクトリへ移動し、まだアーカイブされていない派生子スレッドのログもアーカイブしようとします。
• thread/delete は永続化されたアクティブまたはアーカイブ済みのスレッドと、そこから派生した子スレッドを完全に削除します。
• thread/metadata/update は保存済みスレッドメタデータにパッチを適用します。現在は永続化された gitInfo が含まれます。
• 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.4",
  "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 フィールドの代わりに、permissions へ名前付き権限プロファイル ID を渡せます。permissions と sandbox を同時に送信しないでください。プロジェクト cwd とともに permissionProfile/list を使用して、利用可能なプロファイルと、管理要件が各プロファイルを許可するかどうかを検出します。

thread.sessionId は、現在のライブセッションツリーのルートを識別します。ルートスレッドは自身のスレッド ID をセッション ID として使用し、フォークされたスレッドは元のルートのセッション ID を保持します。クライアントはスレッド ID からセッション ID を導出するのではなく、thread.sessionId から読み取る必要があります。

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

{ "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 は警告を発行し、次のターンで一度だけモデル切り替え命令を適用します。

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

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 を拒否します。ソーススレッドがターンの途中にあるときにフィールドを省略すると、フォークでは、マークのない部分ターンを保持する代わりに中断マーカーが記録されます。

ユーザー向けスレッドタイトルが設定されている場合、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、または active と activeFlags）が含まれます。

{ "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 または省略時は、アーカイブされていないスレッドを一覧表示します（デフォルト）。
• 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, "modelProvider": "openai", "createdAt": 1730831111, "updatedAt": 1730831111, "name": "TUI prototype", "status": { "type": "notLoaded" } },
    { "id": "thr_b", "preview": "Fix tests", "ephemeral": true, "modelProvider": "openai", "createdAt": 1730750000, "updatedAt": 1730750000, "status": { "type": "notLoaded" } }
  ],
  "nextCursor": "opaque-token-or-null"
} }

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

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

スレッドを再開せずに保存済みスレッドメタデータへパッチを適用するには、thread/metadata/update を使用します。現在は永続化された gitInfo をサポートしています。省略したフィールドは変更されず、明示的な null は保存済みの値を消去します。

{ "method": "thread/metadata/update", "id": 21, "params": {
  "threadId": "thr_123",
  "gitInfo": { "branch": "feature/sidebar-pr" }
} }
{ "id": 21, "result": {
  "thread": {
    "id": "thr_123",
    "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 はシェルコマンド用のスタンドアロンターンを開始します。

{ "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.4",
  "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 } } }

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

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

{ "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 reviewer を実行し、レビューアイテムをストリーミングします。対象には次が含まれます。

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

reviewer が終了すると、サーバーは最終レビュー本文を含む exitedReviewMode アイテムを含む item/started および item/completed を発行します。

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

この通知を使用して、クライアントに reviewer の出力を表示します。

プロセス実行¶

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

process/spawn でプロセスを開始し、processHandle を指定します。その後、そのハンドルを stdin、サイズ変更、kill リクエストに使用します。出力は 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 エントリは、pending、inProgress、completed の status で { step, status } されます。
• 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 - content がユーザー入力のリスト（text、image、localImage）である {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 - reviewer の開始時に送信される {id, review}。
• exitedReviewMode - reviewer の終了時に発行される {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 でアイテムを終了します。

コマンド実行の承認¶

メッセージの順序:

1. item/started は、command、cwd、その他のフィールドを含む保留中の commandExecution アイテムを表示します。
2. item/commandExecution/requestApproval には itemId、threadId、turnId、オプションの reason、command、cwd、commandActions、proposedExecpolicyAmendment、networkApprovalContext、availableDecisions が含まれます。initialize.params.capabilities.experimentalApi = true の場合、ペイロードには、コマンドごとに要求されたサンドボックスアクセスを説明する実験的な additionalPermissions が含まれることもあります。additionalPermissions 内のファイルシステムパスはすべて、通信上では絶対パスです。
3. クライアントは、上記のコマンド実行承認の判断のいずれかで応答します。
4. serverRequest/resolved は、保留中のリクエストが回答または消去されたことを確認します。
5. item/completed は、status: completed | failed | declined を含む最終 commandExecution アイテムを返します。

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

Codex は、宛先（host、プロトコル、ポート）ごとに同時実行中のネットワーク承認プロンプトをグループ化します。そのため app-server は、同じ宛先への複数のキュー済みリクエストをまとめて解除する 1 つのプロンプトを送信する場合があります。一方、同じホスト上の異なるポートは別々に扱われます。

ファイル変更の承認¶

メッセージの順序:

1. item/started は、提案された changes と status: "inProgress" を含む fileChange アイテムを発行します。
2. item/fileChange/requestApproval には itemId、threadId、turnId、オプションの reason、grantRoot が含まれます。
3. クライアントは、上記のファイル変更承認の判断のいずれかで応答します。
4. serverRequest/resolved は、保留中のリクエストが回答または消去されたことを確認します。
5. 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 が含まれます。

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

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

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

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

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

1. item.type = "dynamicToolCall"、status = "inProgress"、tool、arguments を含む item/started。
2. クライアントへのサーバーリクエストとしての item/tool/call。
3. 返されたコンテンツアイテムを含むクライアントのレスポンスペイロード。
4. item.type = "dynamicToolCall"、最終 status、返された contentItems または success 値を含む item/completed。

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

アプリ（コネクター）のツール呼び出しにも承認が必要になる場合があります。アプリのツール呼び出しに副作用がある場合、サーバーは tool/requestUserInput と Accept、Decline、Cancel などのオプションで承認を求めることがあります。破壊的なツールアノテーションは、ツールが権限の低いヒントも提示している場合でも、常に承認を発生させます。ユーザーが拒否またはキャンセルすると、関連する 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 を指定できます。また、perCwdExtraUserRoots を含めると、特定の cwd 値の user スコープとして、追加の絶対パスをスキャンできます。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/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
      }
    ]
  }
}

テキスト入力に $<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 は、アプリごとの値で上書きされない限り、すべてのアプリの 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" } }