管理 API
Management API は opencodex のコントロール プレーンです。 http://localhost:10100 のダッシュボードはそのクライアントの 1 つです。 headless ocx プロバイダー、モデル、コンボ、アカウント、設定、診断、ライフサイクル コマンドもクライアントです。 API はプロキシの実行中にのみ使用できます。
対話型クライアントには ウェブダッシュボード を使用するか、自動化を構築する場合はこのリファレンスを使用します。永続値は最終的に 構成 に従います。
Management API には、データプレーン API キーとは独立した独自の管理者資格情報があります。起動時に、opencodex は次の順序で解決します。
OPENCODEX_ADMIN_AUTH_TOKEN、設定時。- 強化されたシークレット ファイル内に生成された
ocx_admin_*トークン。
ファイルベースのトークンは、そのディレクトリとファイルのアクセス許可または ACL が強化された後にのみ受け入れられます。それが保証できない場合、環境トークンが提供されるかファイルの状態が修復されるまで、管理認証は失敗して閉じられ、API は 503 を返します。
管理者トークンを次のいずれかの形式で送信します。
X-OpenCodex-API-Key: <admin-token>Authorization: Bearer <admin-token>ループバック ダッシュボード セッション
Section titled “ループバック ダッシュボード セッション”ループバック バインドでは、ダッシュボード ブートストラップは有効期間の短い ocx_session_* 資格情報を受け取ることができます。各セッションは 5 分間続き、正確なダッシュボードのオリジンにバインドされます。安全なリクエストはそのオリジンと一致する必要があります。安全でないメソッドには、ブラウザ Origin とセッションの CSRF トークンも必要です。
リモート バインドを含むデータ プレーン認証が必要な場合、セッションの発行は無効になります。リモート オペレーターは、生の管理トークンを使用して認証する必要があります。ループバック スタイルの GUI セッションは作成されません。
よくあるエラー
Section titled “よくあるエラー”以下のすべてのエンドポイント行は、これらの境界エラーを継承します。 「注目すべきエラー」列には、この表を繰り返すのではなく、追加のルート固有の結果がリストされます。
| ステータス | タイプまたはコード | 意味 |
|---|---|---|
| 401 | opencodex admin token required |
管理者トークンまたは GUI セッションが欠落している、無効である、期限切れである、オリジンが一致しない、または CSRF 証拠が欠落している。 |
| 403 | cross-origin request blocked |
リクエストの送信元が管理許可リストの外にあります。 |
| 404 | not_found |
メソッドとパスに一致する管理ルートはありません。 |
| 413 | request body too large |
POST、PUT、または PATCH 本文が 2 MiB の管理制限を超えています。 |
| 503 | management API unavailable |
管理者の資格情報の初期化または強化は利用できません。 |
| 503 | oauth_mutation_busy |
別の OAuth 資格情報の突然変異により、ライターが保持されます。応答には Retry-After: 1 |
| 503 | catalog_busy |
カタログ収集はすでに定員に達しています。応答には Retry-After: 1 |
エンドポイントマトリックス
Section titled “エンドポイントマトリックス”エージェントとクライアントの設定
Section titled “エージェントとクライアントの設定”| メソッドとパス | 目的 | 注目すべきエラー |
|---|---|---|
GET, PUT /api/v2 |
ネイティブ マルチエージェント v2 モードおよびスレッド設定の読み取りまたは変更 | 400 の無効な設定。 502 移行または永続化の失敗 |
GET, PUT /api/injection-model |
挿入されたサブエージェント モデル、作業量、プロンプト、およびガイダンス設定を読み取りまたは設定します。 400 無効なモデル、エフォート、またはボディ | |
GET, PUT /api/effort-caps |
グローバルおよびサブエージェントの推論工数の上限を読み取りまたは設定する | 400 無効なラダー値 |
GET, PUT /api/subagent-models |
サブエージェントにアドバタイズされたモデルを読むか注文する | 400 の無効なリストまたは 5 つ以上のモデル |
GET, PUT /api/subagent-model-fallback |
順序付けされたフォールバック チェーンとポーリング間隔を読み取るか設定します。 400 無効なリストまたはポーリング間隔 | |
GET /api/grok |
Grok 管理対象設定のステータスと候補モデルを読む | 400 ステータス読み取り失敗 |
PUT /api/grok/selection |
除外された Grok モデルを永続化します。 400 個の無効な選択またはサイズが大きすぎる選択 | |
POST /api/grok/apply |
管理された同期を通じて永続的な Grok 設定を適用する | 409 grok_apply_busy; 400/500 適用失敗 |
GET /api/grok/reset-coupons?accountId=... |
アクティブまたは指定された xAI アカウントの残り Grok 請求リセット トークンと有効期限ウィンドウを読む | 400 アカウントがありません; 401 未認証; 502 上流 gRPC-Web エラー |
POST /api/grok/reset-coupons/consume |
対象となるリセット クーポンを換金します。本文は { accountId?, tokenId?, operationId? }。任意の operationId（UUIDv4）により換金は冪等になります: 同じ ID を繰り返すと、二重換金せずに永続化された結果を再生します。 |
400 無効な JSON/UUID; 401 未認証; 409 operation_id_owned_by_another_account / coupon_unavailable / operation_token_mismatch / operation_state_changed / attempt_in_progress / attempt_unresolved; 502 上流エラー; 503 台帳容量 / ledger_unavailable; 500 attempt_mark_failed |
GET /api/anthropic/reset-grants?accountId=... |
1 つの Anthropic OAuth アカウントの Claude 使用量上限リセット付与を読み取ります。対象資格、各付与の残り回数、有効期間、リセットされる使用量枠、再試行可能な未確定の試行が含まれます。 | 400 該当するアカウントなし; 401 再認証が必要; 502 上流を利用できません |
POST /api/anthropic/reset-grants/consume |
リセット付与を 1 回分使用します。本文は { accountId, grantId, operationId }。operationId はリクエスト ID として上流へ送信する UUIDv4 で、同じ値を繰り返すと同じ請求を再試行します。ダッシュボードセッションが必要です。 |
400 無効な本文; 401 再認証が必要; 403 session_required; 409 grant_not_usable, in_flight, unresolved_prior_operation, unknown_outcome_expired, operation_identity_mismatch; 500 journal_write_failed; 502 unknown_outcome; 503 ジャーナルが使用中、利用不可、または満杯 |
GET, PUT /api/claude-desktop |
Claude Desktop のルーティング/ネイティブ プロファイルを読み取るか永続化する | 400 無効または使用できない割り当て |
POST /api/claude-desktop/apply |
保存したプロファイルを Claude Desktop の管理対象設定に書き込みます。 400/500 書き込み失敗 | |
GET /api/claude-desktop/status |
保存済みプロファイルと適用済みプロファイルおよびデスクトップの健全性を検査する | 400 ステータス読み取り失敗 |
GET, PUT /api/claude-code |
クロード コードのゲートウェイ、認証モード、モデル マップ、コンテキスト、エージェント、サイドカー設定の読み取りまたは更新 | 400 無効なフィールドまたは図形 |
tokenId を指定する場合は空でない文字列が必要です。不正な値は認証情報の読み取りや台帳を開く前に 400 invalid_token_id で拒否されます。30 日の保持期間内では、同じ operationId の再試行で accountId を省略すると、アクティブアカウントが変わっていても記録済みのアカウントを使います。実行可能な open の再試行で tokenId を省略すると記録済みのトークンを使います。別のアカウントやトークンを明示した場合は引き続き拒否されます。確定した失敗の後、ダッシュボードは該当する保留リクエストの暫定保留を解除し、新しい試行を明示的に確認できるようにします。本当に結果が不明な試行は保留を維持します。
換金前に台帳へ試行を記録し、一つのリクエストだけを実行します。上流から換金成功の応答を確認した場合だけ redeemed を記録します。一覧からクーポンが消えても、この操作の成功を示す証拠にはなりません。タイムアウトや結果保存の失敗後は、再換金せずに可用性だけを照会し attempt_unresolved を返します。最近の試行は attempt_in_progress を返します。遅れて完了した検査による拒否は、まだ open の操作だけに記録します。同じトランザクション内で、アカウントとトークンが一致する確定済みの最終結果は元のコードと HTTP 200 で再生します。結果が未確定、またはアカウントやトークンが一致しない場合は operation_state_changed を返し、同じ操作 ID を保持して復旧します。台帳を読めない、またはロックできない場合は換金せず ledger_unavailable を返します。
使用結果を確認できない場合は HTTP 502 と error.code: "attempt_unresolved"、実際の operationId を返します。この ID を保持してください。新しい ID は別の操作を開始します。CLI は送信前に ID を生成し、送信や応答が不確かな場合は同じ --operation-id を保持するよう案内します。旧バージョンの台帳の open 記録と結果未確認の redeem_failed 記録は不確定な試行として隔離され、再使用を許可しません。
Providers > xAI Grok > Accounts の各アカウントのチケットバッジから、残りのクーポンと有効期間を確認できます。ダイアログはクライアントで生成した operationId を送信します。送信や結果が不確定な場合、ダッシュボードはブラウザタブのセッション中は同じ試行を保持し、ダイアログを閉じて開き直しても、ページを移動または再読み込みしても維持します。保持は要求を送信する前に記録され、同じ operationId に対する確定応答でのみ解除されます。更新は GET のみで、追加の使用 POST を許可しません。ocx account grok-reset-coupons は対応するターミナルコマンドです。
Claude の使用量リセットも Providers > Anthropic > Accounts から同様に操作できます。サインイン済みの各アカウント行には残りのリセット回数を示すチケットバッジがあり、ダイアログで再度確認した後に 1 回分を使用します。リセットすると、週次枠のリセット曜日を変えずに 5 時間枠と週次枠が補充されます。請求に応答がない場合、ダイアログは operationId を保持し、10 分間は同じ ID で再試行できます。Claude Code クライアント自体もこの方法で復旧し、その間は同じ付与に対する新しい操作が拒否されます。使用できるのはダッシュボードからのみで、管理者トークンだけでは 403 session_required が返されます。
モデルロスターと暗号化されたワーカータスクの動作の背後にある概念については、「サブエージェントサーフェス」を参照してください。
クライアント統合のロールバックジャーナル
Section titled “クライアント統合のロールバックジャーナル”| メソッドとパス | 目的 | 主なエラー |
|---|---|---|
GET /api/client-integrations/journal?client=... |
ロールバック操作を一覧表示します。任意でクライアントを指定でき、各行にはサーバー計算の deletable が含まれます。 |
400 無効なクライアント |
DELETE /api/client-integrations/journal?opId=... |
古いロールバック操作を廃止し、可能ならスナップショットも削除します。成功時の snapshotRemoved が false の場合、保守処理で再試行されます。 |
400 opId なし、404 存在しないか廃止済み、409 そのクライアントの最新操作 |
統合変更のプレビュー
Section titled “統合変更のプレビュー”プレビューは変更を適用せずに内容だけを示します。スナップショットも所有権記録もジャーナルも ロックも復旧も、いっさい書き込みません。
| メソッドとパス | 目的 | 主なエラー |
|---|---|---|
POST /api/client-integrations/preview |
クライアント 1 つの apply、overwrite、disable を計画します。本文は { "clientId": "...", "operation": "..." } |
400 不正なクライアントまたは操作、400 invalid_aside_profile_path、409 integration_preview_unavailable |
POST /api/client-integrations/restore/preview |
取り消しを計画します。本文は { "opId": "...", "confirmDrift": false } |
404 該当操作なし、400 invalid_aside_profile_path、409 integration_preview_unavailable |
POST /api/client-integrations/aside/profiles/{profileId}/preview |
Aside プロファイル 1 つの変更を計画します。restore には opId が必要です |
400 不正な本文またはプロファイル未指定、404 該当プロファイルまたは操作なし、409 integration_preview_unavailable |
計画には version、clientId、operation、state、foreignEdit、kind と path の組からなる
changes、不透明な fingerprint、canApply、willChange が含まれ、refusalReason と
profileId は任意です。パスは管理対象スキーマのパスか、$snapshot、$ownership、$journal
の固定表記で、実行時に決まる位置は * になります。設定値やファイルの場所、選ばれた項目の
名前は返しません。
canApply が真で willChange が偽なら、操作は成功しますが管理対象のクライアント文書は何も
変わりません。すでに適用済みのものを適用した場合などです。
Aside プロファイルの変更はこの場合でも一つだけ保存します。確認を送ると、クライアント文書に触れる 前にそのプロファイルの同期設定が記録されるため、管理ブロックがすでにないプロファイルを無効にすると 設定だけが保存され、文書とその履歴はそのまま残ります。
integration_preview_unavailable は今使えるモデル一覧がないという意味です。プロキシを起動した
直後もそうですし、設定やプロバイダーキャッシュが変わって以前の一覧を破棄した場合もそうです。
GET /api/client-integrations を読むと、取得に成功し設定を特定できたときに用意されるので、
通常はこれで解決しますが、必ず用意されるとはかぎりません。
プレビューした変更の確定
Section titled “プレビューした変更の確定”変更要求の本文に operation と planFingerprint を一緒に送ります。両方送るか両方省くかの
どちらかで、片方だけ、または要求と異なる操作を書いた場合は拒否します。Aside はプロファイル
1 つにしか結び付けられません。1 つのフィンガープリントで複数ファイルの変更は説明できないから
です。
サーバーは書き込む前に計画し直し、確認した内容がもう当てはまらなければ新しい計画を添えて
409 integration_preview_stale を返します。自動で再試行はしないので、新しい計画を見て判断し
直してください。
フィンガープリントは楽観的な確認であって権限ではありません。変更してよいかどうかは管理 API の 認証と所有権の規則が決めます。
削除時はジャーナルを書き換えず、トゥームストーンを追記します。現在の取り消し地点を 残すため、各クライアントの最新操作はサーバー側で保護されます。
| メソッドとパス | 目的 | 注目すべきエラー |
|---|---|---|
GET /api/combos |
正規化されたコンボとその公開モデル ID をリストします。カタログ作業は catalog_busy を返すことができます |
|
PUT /api/combos |
1 つのコンボを作成、置換、または名前変更する | 400 無効な ID、ターゲット、構成、名前変更、または通常の衝突。 409 Codexとアカウントの名前空間の衝突 |
DELETE /api/combos?id=... |
コンボを 1 つ削除し、その選択/クールダウン状態をクリアします | 400 ID がありません。 404 未知のコンボ |
ターゲット戦略、クールダウン、エイリアス、およびルーティングの失敗については、コンボ を参照してください。
Codex プロンプトレイヤー
Section titled “Codex プロンプトレイヤー”| メソッドとパス | 目的 | 注目すべきエラー |
|---|---|---|
GET /api/codex-prompt |
プロンプトレイヤーのスナップショット(レイヤー、基本バリアント、選択、drift 状態)を読み取ります | — |
GET /api/codex-prompt/text |
codex debug prompt-input を介してモデルに表示されるプロンプトテキストをプローブします |
fail-soft: 利用できないプローブは HTTP エラーではなく本文のステータスに低下します |
PUT /api/codex-prompt/toggle |
切り替え可能な 1 つのレイヤーを有効または無効にします | 400 無効な本文または不明なレイヤー; 409 stale_revision、layer_not_toggleable |
PUT /api/codex-prompt/custom |
カスタムレイヤーセットを置き換えます | 400 無効な本文、invalid_characters、正規化された UTF-8 レイヤーが 65,536 バイトを超えると body_too_large、131,072 バイトを超えると composed_too_large; 409 stale_revision |
PUT /api/codex-prompt/base/select |
デフォルトの基本プロンプトまたは保存された 1 つのバリアントを選択します | 400 無効な本文、保存されたバリアントに一致しない id には unknown_layer; 409 stale_revision、現在の base が外部の場合は developer_instructions_not_owned |
PUT /api/codex-prompt/base |
1 つの基本バリアントを作成(id 省略または id: null)、編集、または削除(delete: true)します。指定された id は編集専用で、保存されたバリアントを参照する必要があります。body は測定・保存前に正規化されます(タブ展開、CR/CRLF を LF に折りたたみ) |
400 無効な本文、default id または保存されたバリアントに一致しない id には unknown_layer、正規化された UTF-8 本文が 65,536 バイトを超えると body_too_large; 409 stale_revision |
POST /api/codex-prompt/adopt |
config.toml の developer_instructions をカスタムレイヤーとしてインポートします |
400 無効な本文、invalid_characters、body_too_large、composed_too_large; 409 config_unreadable、nothing_to_adopt、adopt_unsupported_form、stale_revision |
POST /api/codex-prompt/repair |
config.toml と所有された projection 間の drift を修復します |
400 無効な本文; 409 config_unreadable、nothing_to_repair、repair_unsupported、stale_revision |
レイヤーモデルと各レイヤーが書き込むキーについては、Codex プロンプトレイヤー を参照してください。
設定、起動、同期、更新
Section titled “設定、起動、同期、更新”| メソッドとパス | 目的 | 注目すべきエラー |
|---|---|---|
GET /api/config |
編集された、管理上安全な構成 DTO を返します。 — | |
PUT /api/config |
フルコンフィグ置換ガードを無効にする | 405;代わりにフォーカスされたエンドポイントを使用してください。 |
GET, PUT /api/settings |
ランタイム/起動設定の読み取り、または自動起動、ストリーム モード、アプリ所有のメモリ バジェット、codexAccountPickerEnabled の更新 |
400 無効、object 以外、または空の更新 |
GET /api/startup-health |
キャッシュされたサービス/シムの起動状態を読み取る | — |
POST /api/startup-action |
サービスまたは Codex シムをインストールまたは修復する | 400 無効なアクション。 500 アクション失敗 |
GET, POST /api/windows-tray |
Windows トレイの状態を読み取るか、インストール/起動/停止/アンインストールする | 400 のサポートされていないプラットフォーム/アクション。 500 操作失敗 |
GET /api/diagnostics/project-config |
キャッシュされたプロジェクト設定の読み取りに関する警告 | — |
POST /api/sync |
現在のモデル カタログを Codex に同期する | 500 回の同期に失敗しました |
GET /api/update/check |
latest または preview のパッケージ更新を非同期で確認し、成功時にキャッシュを更新する |
400 無効なタグ |
POST /api/update/run |
新しいパッケージ版を非同期で確認してから更新ジョブを開始し、必要に応じて再起動する | 400 無効な本文。ジョブ固有の競合/エラーのステータス |
GET /api/update/status |
ID によって更新ジョブをポーリングする | 404 不明なジョブ |
GET, PUT /api/sidecar-settings |
Web 検索およびビジョンのサイドカー モデル/バックエンド設定の読み取りまたは更新 | 400 無効な形状、バックエンド、または制限 |
GET, PUT /api/shadow-call-settings |
シャドウ コール インターセプト設定の読み取りまたは更新 | 400 無効な形状または値 |
ログ、使用状況、およびストレージ
Section titled “ログ、使用状況、およびストレージ”リクエストログは、上流が応答したモデルを示した場合に servedModel を保持します。上流に送信したモデルが
クライアントに提示したモデルと異なる場合は wireModel も保持します。両者が異なるとき、ダッシュボードには
wire → served と表示され、ツールチップに両方の値が残ります。上流からモデルの情報が得られない場合、
リクエストされたモデルから推測せず、その情報は記録しません。
| メソッドとパス | 目的 | 注目すべきエラー |
|---|---|---|
GET /api/logs |
フィルタリングされたメモリ内リクエスト ログのクエリ | — |
GET, PUT /api/debug |
デバッグフラグを読み取ります。キャプチャ カテゴリを設定、クリア、またはリセットする | 400 無効または空の更新 |
GET /api/debug/logs |
制限されたプロバイダー/デバッグ ログ エントリを読み取る | — |
GET /api/debug/usage-logs |
制限された使用法デバッグ エントリを読み取る | — |
GET /api/debug/injection-logs |
制限付きガイダンス挿入デバッグ エントリを読み取る | — |
GET /api/claude/inbound-debug |
Claude インバウンドのデバッグ状態とエントリを読む | — |
GET /api/usage |
範囲とクライアント サーフェスごとの使用状況を要約する | ストレージを読み取れない場合は 500 { "error": "read_failed" } を返します。 |
GET /api/metrics |
論理リクエスト、物理送信、復旧種別、所要時間、TTFT のプロセスローカル Prometheus テキストメトリクスを返します。リクエストメトリクスのラベルは閉じた集合を使い、Kiro ゲージには上限付きの不透明なアカウントラベルのみを追加し、リクエストや認証情報の識別子は出力しません。 Kiro の 4 つのクォータゲージ (opencodex_kiro_quota_{used_credits,limit_credits,used_percent,seconds_to_reset}) はキャッシュのみを読み、最大 32 個の不透明なアカウントラベルを使います。収集時にネットワーク照会は行いません。 |
起動時に metricsExport.enabled が true でなければ 404。通常の管理認証が必要で、データプレーン認証情報ではアクセスできません。 |
GET /api/storage |
バケットごとの Codex ストレージ使用量をスキャン | スキャン失敗時に error: "scan_failed" ペイロードを返します。 |
POST /api/storage/cleanup/preview |
アーカイブされたセッションのクリーンアップをプレビューし、バインディング ダイジェストを返します。 400 invalid_json または invalid_percent |
|
POST /api/storage/cleanup |
プレビューされたアーカイブ セットを隔離または完全に削除します。 400 無効な入力。 409 古い/ビジー/参照状態。 500 ファイルシステム/データベース障害 | |
GET /api/storage/trash |
隔離されたクリーンアップ エントリを一覧表示する | 500trash_list_failed |
POST /api/storage/trash/restore |
隔離されたエントリを 1 つ復元する | 400 無効な ID; 404 ゴミが行方不明。 409 ビジー/宛先の競合。 500 復元の失敗 |
GET /api/storage/trash/restore/test-stream |
テストのみの復元ストリーム フック | 404 not_available テストフックがオフの場合 |
GET, PUT /api/storage/cleanup-policy |
スケジュールされたクリーンアップ ポリシーとジョブの状態を読み取りまたは更新します。 400 無効なポリシー | |
POST /api/storage/cleanup-policy/run |
手動クリーンアップ ポリシーの実行を開始します。 409 already_running; 500cleanup_failed |
|
GET /api/storage/cleanup-policy/test-stream |
テスト専用ポリシー ストリーム フック | 404 not_found 利用できない場合 |
行が既存のパーサーのサイズ上限を超えた場合、GET /api/usage と GET /api/keys は読み取れる行の集計を維持し、応答全体に usageIncomplete: true と usageIncompleteReason: "oversized_rows" を追加します。この診断はキャッシュや増分追記後も維持され、結果が空または一致なしでも返されます。再構築時には再計算されます。プロバイダー、モデル、API キーの識別子は短縮しません。フラグがないことは全行が有効だった証明にはなりません。historyTruncated、entriesTruncated、トークン測定カバレッジとは別の情報です。
models、providers、および days[].models の各行にも cacheHitRate が含まれます。これは、プロバイダーのプロンプト キャッシュから供給された入力トークンの割合で、[0, 1] の範囲に制限されます。プロバイダーがキャッシュ テレメトリを報告しなかった場合、または行に入力トークンがない場合は、0 ではなく null になります。「キャッシュ データなし」と「実際のヒット率 0%」は異なる事実であり、それらを同じように描画するチャートは誤解を招くためです。
モデルとカタログ
Section titled “モデルとカタログ”| メソッドとパス | 目的 | 注目すべきエラー |
|---|---|---|
GET /api/catalog |
インストールされている Codex カタログ ドキュメントを返します | 404 カタログが見つかりません |
GET /api/models |
ダッシュボード/CLI モデルの行を返す | 収集が飽和したときの catalog_busy |
GET /api/client-config?client=... |
サポートされているファイル連携の読み取り専用クライアント設定を作成する | 400 クライアントがサポートされていません。 503 カタログは利用できません |
PUT /api/disabled-models |
共有の無効モデル リストを置き換える | 400 無効な JSON |
PUT /api/model-visibility |
プロバイダーレベルまたはモデルレベルの可視性をアトミックに変更 | 400 プロバイダー、スコープ、ターゲット、または本文が無効です。; 409 initial_model_selection_pending (モデル一覧を更新してから再試行してください。) |
GET, POST /api/custom-models |
カスタム モデルをリストするか追加する | 400 個の無効なフィールド。 404 プロバイダーがありません。 409 複製モデル |
PUT, DELETE /api/custom-models/{id} |
1 つのカスタム モデルを編集または削除する | 400 個の無効な ID/フィールド。 404 が見つかりません。 409 複製モデル |
GET, PUT /api/selected-models |
プロバイダーの許可リストと可用性を読む、または許可リストを置き換える | 400 プロバイダー/本文の不足; 404 不明なプロバイダー; PUT 409 initial_model_selection_pending |
GET, PUT /api/model-presets |
プリセット情報を読む、または preset/all/custom モードを選ぶ | 400 不正なモードまたは未提供のプリセット; 404 不明なプロバイダー; PUT 409 initial_model_selection_pending |
手動モデルは、Models ダッシュボードで provider と model ID が一致する行を置き換えます。OpenAI の手動行は openai/<model> を維持し、表示状態を変更できます。削除すると、アカウント修飾子のないネイティブ行が復元されます。アカウント修飾付きのネイティブ行は別に保持されます。ネイティブルートやアカウントの権限は変更しません。OpenAI の非ネイティブ表示対象は、設定済みの手動モデルと一致する必要があります。
信頼できる初回モデル一覧が確定するまで、有効な PUT /api/selected-models と PUT /api/model-presets も HTTP 409 とコード initial_model_selection_pending を返します。GET /api/models などでモデル一覧を更新し、取得に成功してから再試行してください。
OAuth アカウント、プロバイダー キー、およびデータプレーン キー
Section titled “OAuth アカウント、プロバイダー キー、およびデータプレーン キー”| メソッドとパス | 目的 | 注目すべきエラー |
|---|---|---|
GET /api/oauth/providers |
パブリック OAuth ログイン フローを持つプロバイダーをリストする | — |
GET /api/key-providers |
API キー ログインを通じて構成されたプロバイダーをリストする | — |
POST /api/oauth/login |
OAuth ログインまたはアカウント追加フローを開始する | 400 不明または無効なプロバイダー。 oauth_mutation_busy |
POST /api/oauth/login/code |
手動コールバック URL または認証コードを送信する | 400 無効なプロバイダー/コード。 oauth_mutation_busy |
POST /api/oauth/login/cancel |
進行中のパブリック OAuth フローをキャンセルする | 400 不明なプロバイダー |
GET /api/oauth/status |
1 つのプロバイダーの OAuth フローをポーリングする | 400 不明なプロバイダー |
POST /api/oauth/logout |
選択したプロバイダー資格情報を削除します | 400 不明なプロバイダー。 oauth_mutation_busy |
GET, DELETE /api/oauth/accounts |
マスクされたアカウントを一覧表示するか、アカウントを 1 つ削除する Kiro の行には自動選択の autoSelectable と、除外時には閉じた集合の skipReason が含まれます。アクティブな単一アカウントは送信を続けられ、クォータ取得は任意です。 |
400 無効なプロバイダー/ID。 404 アカウントがありません。 oauth_mutation_busy |
PUT /api/oauth/accounts/active |
アクティブな OAuth アカウントを選択します | 400 無効なプロバイダー/アカウント。 oauth_mutation_busy |
GET, PUT, PATCH /api/oauth/accounts/pool |
Anthropic OAuth プール ポリシーの読み取りまたは更新 | 400 非 Anthropic プロバイダーまたは無効なポリシー |
POST /api/oauth/accounts/clear-cooldown |
1 つの OAuth アカウントのランタイム クールダウンをクリアする | 400 無効なプロバイダー/アカウント |
PUT /api/oauth/accounts/alias |
OAuth アカウント エイリアスを設定またはクリアする | 400 無効なプロバイダー/アカウント/エイリアス |
PUT /api/oauth/accounts/pause |
Anthropic または汎用 OAuth アカウントを一時停止・再開。Body { provider, accountId, paused }。アクティブなアカウントを停止すると、利用可能な別のアカウントがあれば切り替えます。 |
400 未対応のプロバイダーまたは無効な body；404 アカウントなし；oauth_mutation_busy |
GET, POST, DELETE /api/providers/keys |
マスクされたプロバイダー キーを一覧表示し、1 つを追加/アクティブ化するか、1 つを削除します。 400 無効な入力。 404 プロバイダー/キーがありません | |
PUT /api/providers/keys/active |
プロバイダーのアクティブなキーを選択します | 400 無効な入力。 404 プロバイダー/キーがありません |
PUT /api/providers/keys/alias |
プロバイダー キー エイリアスを設定またはクリアする | 400 無効な入力。 404 プロバイダー/キーがありません |
GET, POST, PATCH, DELETE /api/keys |
データ プレーン アドミッション キーの一覧表示、作成、編集、または削除 | 400 無効な本文/ID。 404 キーがありません |
資格情報リストの応答は意図的にマスクされます。 OAuth アクセス トークンと完全なプロバイダー API キーはダッシュボード クライアントに返されません。
Anthropic OAuth: pause / resume
Section titled “Anthropic OAuth: pause / resume”CLI コマンドは Anthropic OAuth アカウントを id または一意の別名で一時停止・再開します。別名は完全一致を優先し、次に大文字と小文字を区別せず照合します。ダッシュボードと同じ PUT /api/oauth/accounts/pause に { provider: "anthropic", accountId, paused } を送信します。paused はアカウントに保存され、GET /api/oauth/accounts にも表示されます。プロアクティブなプールが無効でも、停止中のアカウントは選択、セッションの紐付け、429 の切り替え候補から除外されます。全アカウントが停止中なら、再開するまでリクエストは 403 を返します。送信済みのリクエストは継続し、認証情報と健全性の状態は保持されます。再起動や再ログインでも停止は維持され、アカウント削除時に消えます。アカウント別のしきい値はこの操作に含まれません。
プロバイダー
Section titled “プロバイダー”| メソッドとパス | 目的 | 注目すべきエラー |
|---|---|---|
GET /api/providers |
編集されたプロバイダー設定と検出状態をリストする | — |
POST /api/providers |
検証済みプロバイダーを 1 つ追加または置換し、必要に応じてそれをデフォルトにします。 400 無効または危険な宛先または構成。 409 名前空間の衝突 | |
PATCH /api/providers?name=... |
許可されたプロバイダー フィールド（マージされる headers ブロックを含む）、有効/デフォルト状態、または OpenAI アカウント モードを更新します。 400 無効なフィールドまたは遷移。 404 不明なプロバイダ |
|
DELETE /api/providers?name=... |
プロバイダーを削除し、可能な場合はデフォルトを再割り当てします。 404 不明なプロバイダー。 409 last_provider; 409 provider_has_dependent_combos |
|
POST /api/providers/test?name=... |
制限されたライブプロバイダー接続/モデル検出プローブを実行する | 404 不明なプロバイダー。障害は通常、ok: false の証拠として返されます。 |
GET /api/provider-quotas |
プロバイダー クォータ レポートを読む。 refresh=1 強制更新 |
— |
GET, PUT /api/provider-context-caps |
グローバル、全プロバイダー、または 1 つのプロバイダーのコンテキスト キャップを読み取りまたは更新します。 400 無効なリクエスト。 404 不明なプロバイダ | |
GET /api/provider-presets |
ランタイム レジストリから派生した GUI プロバイダー プリセットを返します。 — |
コンテキスト上限のレスポンスには caps（有効な上限）と values（無効化後も保持される最後の選択値）が
含まれます。value を指定せずにプロバイダーの上限を有効にすると選択値を復元し、初回はグローバルの
contextCapValue を使います。OpenAI でも同様で、スイッチが特別な 922k モードを選ぶことはありません。
有効な上限はすべてのネイティブウィンドウに適用されます。長いコンテキストに対応したモデルは、
そのモデルが対応する上限まで拡張できます。
{ "value": 600000, "setAll": true } はグローバル値と有効な上限だけを更新します。
上限が無効なプロバイダーは選択値を保持し、後で有効にすると復元します。
value なしの { "setAll": true } は、設定済みの全プロバイダーの上限を現在のグローバル値で有効にし、
保存された選択値も置き換えます。無効化しても選択値は再読み込み後まで保持されますが、制限としては適用されません。
provider_has_dependent_combos は安全バリアです。プロバイダーを削除する前に、依存するコンボを削除または編集してください。
サイドバーと同意に基づくアクション
Section titled “サイドバーと同意に基づくアクション”| メソッドとパス | 目的 | 注目すべきエラー |
|---|---|---|
GET /api/github/star |
ユーザーの gh セッションを通じてリポジトリのスター ステータスを読み取ります。ステータス固有の固定結果コード |
|
POST /api/github/star |
認証された人間のアクションからのみリポジトリにスターを付けます。 403 agent_consent_required ダッシュボード セッションの証拠がないエージェント主導の発信者向け |
|
GET /api/update/badge |
レジストリに問い合わせずにキャッシュ済みパッケージのバッジを読む。キャッシュがない、チャネルが違う、または40時間以上古い場合は unknown: true。surface=desktop&session=<id> はそのデスクトップアプリのセッションだけを読む。 |
400 無効な surface。デスクトップセッションがない、または期限切れの場合は unknown: true |
POST /api/update/desktop-snapshot |
デスクトップシェルが紐付けられたプロキシクライアント経由で Tauri updater の表示状態を送信する | Origin ヘッダーがある場合、または生の admin-token principal 以外は403。フィールドが無効なら400。1 KiB超は413 |
デスクトップ snapshot は一時的な表示状態であり、インストール要求ではありません。プロキシはメモリ内に最大32セッションを保持し、最後の heartbeat から180秒で期限切れにします。surface=desktop を指定しない通常のブラウザは引き続きパッケージのバッジを読みます。
対象のパッケージでは、起動後にキャッシュがないか20時間以上古い場合に確認し、その後は毎時鮮度を確認します。OCX_DISABLE_UPDATE_CHECK=1 は自動確認だけを無効にします。明示的な確認と更新要求は引き続き使えます。
システムのライフサイクル
Section titled “システムのライフサイクル”POST /api/system/restart は、本文を省略した場合や {} の場合、既定の 60 秒のドレイン猶予を維持します。管理セッションまたは管理者トークンを使う呼び出し元は、{"drainGraceMs":2000} で短い猶予を明示的に選択できます。値は 1～60000 ミリ秒の整数です。不正な本文や値は再起動を開始せずに 400 を返します。対象プロセスに限定されたローカル再起動 capability では、このオプションを設定できません（403）。応答の drainTimeoutMs は最初に受け入れた猶予を示し、繰り返しの呼び出しでも期限は変わりません。猶予には応答送信までの遅延を含み、クリーンアップと置換プロセスの準備には別々の 60 秒・70 秒の予算があります。中断された処理が既に実行された可能性があるため、再送前に結果を確認してください。自動再送は追加されません。
| メソッドとパス | 目的 | 注目すべきエラー |
|---|---|---|
GET /api/system/memory |
スカラー プロセス、ヒープ、ストリーム、応答状態、ウォッチドッグ、およびアクティブ ターン メトリックを返します。 — | |
POST /api/system/restart |
クライアント インジェクションを削除せずに、ドレイン対応プロセスの再起動を開始します。 202 を返します。繰り返しの呼び出しにより、既存の排水が報告されます。 | |
POST /api/stop |
サービスを停止し、ネイティブ Codex を復元し、マネージド Grok インジェクションを削除し、プロキシをドレインします | 409 サービス所有権の競合、409 respawnable_service（Windows タスク スケジューラのラッパーがプロキシを再起動しうる状態で、呼び出し元が ocx stop でない場合。何も変更されません）、409 インストール済みマネージャが停止を拒否した場合、409 service_state_unknown（タスク スケジューラの状態を読み取れない場合。何も変更されません。クエリを修復して再試行してください） |
Codex認証の委任
Section titled “Codex認証の委任”GET /api/settings は有効な codexAccountPickerEnabled boolean を返します。この strict boolean を
PUT すると、空の map を有効化する場合は privacy-safe selector を初期化し、既存 label を保持したまま
先に永続化し、有効な picker 表示が変わったときだけ bounded catalog convergence を 1 回要求します。
成功応答の catalogRefreshPending: true は設定は保存済みだが POST /api/sync による再試行が必要という意味です。
ルート管理ディスパッチャーは、すべての /api/codex-auth/* リクエストを Codex アカウント マネージャーに委任します。そのルートは次のとおりです。
| メソッドとパス | 目的 | 注目すべきエラー |
|---|---|---|
GET, POST, DELETE /api/codex-auth/accounts |
Codex アカウントの一覧表示/更新または削除。POST は無効化された互換エンドポイントとしてのみ残り、成功した DELETE は catalogRefreshPending を返します。 |
POST は常に 403 manual_import_disabled。DELETE の入力が無効な場合は 400。 |
PUT /api/codex-auth/accounts/alias |
アカウント エイリアスの設定またはクリア | 400 無効なアカウント/エイリアス |
PUT /api/codex-auth/accounts/pause |
アカウントと、同じ ID 情報を持つ既存のメイン／プールのエントリを手動で一時停止または再開する。affectedAccountIds を返す |
400 無効なアカウント／状態、404 アカウントが見つからない、503 メインの ID 情報が使用中または読み取り不能 |
PUT /api/codex-auth/accounts/pause-exhausted |
クォータを使い果たしたアカウントを一時停止する | ミューテーションロックの失敗は 503 になります |
POST /api/codex-auth/accounts/clear-cooldown |
1 つのアカウントまたはすべてのアカウントのランタイム クールダウンをクリアする | 400 無効な ID |
GET, PUT /api/codex-auth/active |
アクティブなアカウントを読み取るか選択します | 400 アカウントが無効または欠落しています。 409 一時停止/レガシー行の競合、または account_selection_unavailable |
PUT /api/codex-auth/auto-switch |
id を省略した { threshold } でグローバルしきい値、{ id, threshold } でアカウント別の上書き値を設定する。id: '__main__' は Codex Desktop アカウントを指定する。id を指定した場合、threshold: null は上書き値を削除してグローバル値の継承に戻す |
400 無効な ID/しきい値、404 アカウントなし |
PUT, PATCH /api/codex-auth/pool-strategy |
Codex アカウントプールの選択戦略を更新 | 400 無効な戦略/構成 |
PUT /api/codex-auth/failover |
アカウントのフェイルオーバーしきい値を設定する | 400 無効なしきい値 |
GET /api/codex-auth/quota |
キャッシュされたクォータ状態をアカウントごとに読み取る | — |
GET /api/codex-auth/reset-credits |
アカウントのリセット クレジット資格を検査する | 400 アカウント ID がありません。アップストリームステータスパススルー。 500 検索失敗 |
POST /api/codex-auth/reset-credits/consume |
対象となるリセット クレジットを消費する。任意の operationId（UUIDv4）を指定すると消費が冪等になります。同じ id は 2 つ目のクレジットを消費せず、保存済みの結果を 1 回再生します。 |
400 アカウント ID がありません、または operationId が不正です。id が別のアカウントに属する場合は 409 identity_mismatch。アップストリームステータスパススルー。 503 server_busy、capacity、unavailable; 500 消費失敗 |
POST /api/codex-auth/login |
Codex のログインまたは再認証を開始する | 400 無効なリクエスト。競合/ビジー ログイン状態 |
POST /api/codex-auth/login/code |
Codex ログイン フローの手動コードを送信する | 400 無効なフロー/コード |
POST /api/codex-auth/login/cancel |
{ "flowId": "..." } で指定した保留中の Codex ログインのみキャンセルする |
400 フロー ID が未指定、不明、または保留中ではない |
GET /api/codex-auth/login-status |
フローまたはアカウントのログイン状態をポーリングする。新規アカウント完了時は回復が必要な場合だけ catalogRefreshPending: true を含みます。 |
不明なフローは expired を報告します。アクティブなフローは idle を報告しません |
PUT /api/codex-auth/active には { "accountId": "<id>" } が必要です。選択をクリアするには、
明示的に { "accountId": null } を指定します。別のプロセスが保存済みのアカウントを変更していても、
現在のアカウントの再選択は明示的な選択として扱われます。サーバーは無関係な保存済み設定を保持し、
ダッシュボードの読み込み後に削除または一時停止されたアカウントの選択を拒否します。保存済み設定が
利用できないか無効な場合、実行中の選択とアカウントへのアフィニティは変更されません。
設定を再読み込みしてから再試行してください。成功レスポンスはコミット済みの選択を示します。
既存のクォータとフェイルオーバーのルールによりピン留めが解除される場合は引き続きあります。
pinDrained は、現在判明しているピン留め解除の理由を示します。
新規 account の config row は保存されたものの credential setup を完了できない場合、OAuth の
login-status は status: "error" と
code: "codex_credential_persistence_failed"、accountId、needsReauth: true、必要に応じて
catalogRefreshPending: true を含み、storage error の詳細は公開しません。account row は保存済みなので、
account 作成を再試行する前に再認証するか削除してください。
この委任されたファミリーでの構成ライターまたは資格情報の更新ロックのタイムアウトは、コード CONFIG_MUTATION_LOCK_UNAVAILABLE の HTTP 503 を返します。クライアントは、その応答を永久的なアカウント障害として扱うのではなく、すぐに再試行する必要があります。
アカウント作成と削除は catalog convergence より先に永続化されます。失敗または延期された catalog 処理は 保存済み mutation をロールバックせず、内部 provider/account/path/credential detail も返しません。削除した account の selector binding は残るため、欠落中の exact route は fail closed し、同じ id の再追加で同じ selector が戻ります。
クライアントの選択
Section titled “クライアントの選択”通常の管理では、ウェブダッシュボード が最も安全なガイド付きワークフローを提供します。ヘッドレス ホストとオートメーションの場合は、対応する ocx コマンドを使用します。これらのコマンドは、これと同じライブ API を呼び出し、プロキシに到達できない場合、または操作が失敗した場合にゼロ以外の結果を返します。ダイレクト HTTP は、上記の正確なエンドポイント コントラクトを必要とする統合に最も役立ちます。
リモートセッションとデータキー更新
Section titled “リモートセッションとデータキー更新”POST /api/keys/rotate {id} は10分間の移行を開始し、新しい秘密値を一度だけ返します。POST /api/keys/rotate/commit {id,rotationId} で確定し、DELETE /api/keys/rotate {id,rotationId} で中止します。管理認証が必須で、データキーからは呼べません。POST /api/session/logout には現在の gui-session、一致する Origin、CSRF が必要です。管理トークンは 403 となり、同意セッションを作成できません。
Anthropic アカウント使用量しきい値
Section titled “Anthropic アカウント使用量しきい値”PUT /api/oauth/accounts/auto-switch
Anthropic OAuth のみ。{ provider: "anthropic", accountId, threshold }: 整数 0–100、null は継承、欠落はエラー。再起動後も保持され、アカウント削除時に消えます。
DTO は autoSwitchThresholdOverride（整数/null）、autoSwitchThreshold（プール既定値）、effectiveAutoSwitchThreshold を含みます。0 は使用量による切り替えのみ無効にし、一時停止と 429 復旧は維持します。
HTTP: 400 invalid/unsupported; 404 missing account; oauth_mutation_busy on lock contention.
Forced Claude Code subagent model
Section titled “Forced Claude Code subagent model”The Subagents page offers Force all subagents onto one model, off by default. Select an exposed roster-style id, such as combo/tev-auto, then enable the switch. The roster is offered first; unavailable saved roster entries cannot be force targets.
ocx agent subagents force combo/tev-auto sets claudeCode.subagentModelForce; ocx agent subagents force - clears it. ocx agent status reports the setting. GET /api/subagent-models returns force, forceAvailable, and forceStatus; PUT accepts { "force": "combo/tev-auto" } or { "force": null } without changing the roster. Omitting force leaves it unchanged. Invalid or unexposed targets are rejected on write; stale targets are reported and skipped at launch.
This takes effect on the next routed ocx claude launch, injecting CLAUDE_CODE_SUBAGENT_MODEL as an explicit proxy alias (with [1m] only for an authoritative million-token window; native Claude targets use a reversible native alias) and CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1. Each nonempty shell-exported variable independently wins. Native launches inject neither variable; plain claude is not affected. No plugin files or settings.json are modified by this setting.
Claude Code 2.1.257 or newer is required for FORCE. Plugin and built-in agents (including Explore/Plan) and per-call model arguments are overridden. Forks and subagent skills with model: inherit keep the main conversation model. The main loop and Haiku/small-fast sidecars are unaffected. Existing roster files remain available.
The dashboard warns about old or unknown CLI versions, unavailable targets, and either variable already present in settings.json → env (which overrides launch env). Detection is read-only and server-local: it cannot inspect another launch shell, another machine, or project-local settings. An unknown result is not proof of force support.