管理 API
管理 API 是 opencodex 的控制平面。http://localhost:10100 的儀表板是它的一個客戶端;無頭的 ocx 供應商、模型、組合、帳號、設定、診斷與生命週期指令也是客戶端。API 僅在代理執行時可用。
使用網頁儀表板作為互動式客戶端,或在建構自動化時使用此參考。持久值最終遵循設定。
管理 API 有自己的管理憑證,獨立於 data-plane API 金鑰。在啟動時,opencodex 依此順序解析它:
OPENCODEX_ADMIN_AUTH_TOKEN,設定時。- 強化秘密檔案中生成的
ocx_admin_*token。
檔案支援的 token 僅在其目錄與檔案權限或 ACL 已被強化後才被接受。若無法保證,管理認證 fail closed 且 API 回傳 503,直到提供環境 token 或修復檔案狀態。
以任一形式發送管理 token:
X-OpenCodex-API-Key: <admin-token>Authorization: Bearer <admin-token>回送儀表板 session
Section titled “回送儀表板 session”在回送綁定上,儀表板 bootstrap 可接收短期的 ocx_session_* 憑證。每個 session 持續五分鐘並綁定到精確的儀表板來源。安全請求必須符合該來源。不安全方法還需要瀏覽器 Origin 與 session 的 CSRF token。
Session 簽發在需要 data-plane 認證時停用,這包含遠端綁定。遠端操作者必須以原始管理 token 認證;不簽發回送式 GUI session。
下方所有端點列繼承這些邊界錯誤。「主要錯誤」欄列出額外的路由專屬結果,而非重複此表。
| 狀態 | 型別或代碼 | 意義 |
|---|---|---|
| 401 | opencodex admin token required |
管理 token 或 GUI session 缺失、無效、過期、來源不符或缺少 CSRF 證據 |
| 403 | cross-origin request blocked |
請求來源在管理允許清單之外 |
| 404 | not_found |
無管理路由符合該方法與路徑 |
| 413 | request body too large |
POST、PUT 或 PATCH body 超過 2 MiB 管理限制 |
| 503 | management API unavailable |
管理憑證初始化或強化不可用 |
| 503 | oauth_mutation_busy |
另一個 OAuth 憑證變更持有寫入器;回應包含 Retry-After: 1 |
| 503 | catalog_busy |
目錄收集已達容量;回應包含 Retry-After: 1 |
代理與客戶端設定
Section titled “代理與客戶端設定”| 方法與路徑 | 用途 | 主要錯誤 |
|---|---|---|
GET, PUT /api/v2 |
讀取或變更原生多代理 v2 模式與執行緒設定 | 400 無效設定;502 轉換或持久化失敗 |
GET, PUT /api/injection-model |
讀取或設定注入的子代理模型、effort、prompt 與 guidance 設定 | 400 無效模型、effort 或 body |
GET, PUT /api/effort-caps |
讀取或設定全域與子代理 reasoning-effort 上限 | 400 無效階梯值 |
GET, PUT /api/subagent-models |
讀取或排序向子代理廣告的模型 | 400 無效清單或超過五個模型 |
GET, PUT /api/subagent-model-fallback |
讀取或設定有序的 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 計費重置 token 與有效期間 | 400 缺失帳號;401 未認證;502 上游 gRPC-Web 錯誤 |
POST /api/grok/reset-coupons/consume |
兌換一個合格的 reset coupon。請求主體為 { 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 容量 / ledger_unavailable; 500 attempt_mark_failed |
GET /api/anthropic/reset-grants?accountId=... |
讀取單一 Anthropic OAuth 帳號的 Claude 用量額度重設機會:資格、每次重設的剩餘次數、有效期間及可清除的用量視窗,以及任何尚未確認但仍可重試的使用嘗試 | 400 找不到相符帳號;401 需要重新認證;502 上游無法使用 |
POST /api/anthropic/reset-grants/consume |
使用一次重設機會。請求主體為 { 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 |
檢查已儲存 vs 已套用設定檔與 Desktop 健康 | 400 狀態讀取失敗 |
GET, PUT /api/claude-code |
讀取或更新 Claude Code 閘道、auth-mode、model-map、context、agent 與 sidecar 設定 | 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 以相同方式操作。每個已登入帳號列都有票券徽章,顯示剩餘重設次數;對話框會在第二次確認後使用一次重設機會。重設會補滿 5 小時與每週額度,但不會改變每週重設日。如果使用請求未收到回應,對話框會保留其 operationId,並在十分鐘內提供使用相同 ID 重試的選項;Claude Code 用戶端也以此方式復原。在此期間,系統會拒絕對同一重設機會發起新操作。重設機會只能透過儀表板使用:僅持有管理員權杖會收到 403 session_required。
關於模型名冊與加密 worker-task 行為背後的概念,請見子代理介面。
用戶端整合復原日誌
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 |
為單一用戶端規劃 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 設定檔的變更;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。兩者要麼都送出,要麼都省略:
只帶其中一個會被拒絕,operation 與所請求的變更不一致也會被拒絕。Aside 的綁定只針對單一設定
檔,因為一個指紋無法描述多個各自獨立變動的檔案。
伺服器在寫入前會重新規劃,若確認的內容已不再符合實際,會回傳 409 integration_preview_stale
並附上重新計算的 plan。請依新計畫再做一次決定;請求不會自動重試。
指紋只是樂觀檢查,不是授權。變更是否被允許,仍由管理 API 的驗證與歸屬規則決定。
刪除操作會附加墓碑記錄,而不會重寫日誌。伺服器會保護每個用戶端的最新操作, 以保留目前的復原點。
| 方法與路徑 | 用途 | 主要錯誤 |
|---|---|---|
GET /api/combos |
列出正規化的組合及其公開模型 id | 目錄工作可回傳 catalog_busy |
PUT /api/combos |
建立、取代或重新命名一個組合 | 400 無效 id、目標、設定、重新命名或普通碰撞;409 Codex 帳號命名空間碰撞 |
DELETE /api/combos?id=... |
刪除一個組合並清除其選擇/冷卻狀態 | 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 |
啟用或停用一個可切換的層 | 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 |
選擇預設基礎提示詞或一個已儲存的變體 | 400 無效本文、與任何已儲存變體不符的 id 回傳 unknown_layer;409 stale_revision、目前基礎提示詞為外部時 developer_instructions_not_owned |
PUT /api/codex-prompt/base |
建立(省略 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 |
讀取 runtime/啟動設定或更新自動啟動、串流模式與 app 擁有記憶體預算 | 400 無效或空更新 |
GET /api/startup-health |
讀取快取的服務/shim 啟動健康 | — |
POST /api/startup-action |
安裝或修復服務或 Codex shim | 400 無效動作;500 動作失敗 |
GET, POST /api/windows-tray |
讀取 Windows tray 狀態或安裝/啟動/停止/解除安裝它 | 400 不支援平台/動作;500 操作失敗 |
GET /api/diagnostics/project-config |
讀取快取的專案設定警告 | — |
POST /api/sync |
將目前模型目錄同步到 Codex | 500 同步失敗 |
GET /api/update/check |
非同步檢查 latest 或 preview 套件頻道,成功時更新快取 |
400 無效 tag |
POST /api/update/run |
非同步檢查新版套件,再啟動更新工作,並可選擇重新啟動 | 400 無效 body;工作專屬衝突/錯誤狀態 |
GET /api/update/status |
依 id 輪詢更新工作 | 404 未知工作 |
GET, PUT /api/sidecar-settings |
讀取或更新網頁搜尋與視覺 sidecar 模型/backend 設定 | 400 無效結構、backend 或限制 |
GET, PUT /api/shadow-call-settings |
讀取或更新 shadow-call 攔截設定 | 400 無效結構或值 |
日誌、用量與儲存
Section titled “日誌、用量與儲存”當上游指出實際回應的模型時,請求日誌會保留 servedModel;當送往上游的模型與呈現給用戶端的模型不同時,
也會保留 wireModel。兩者不同時,儀表板顯示 wire → served,提示文字則保留兩個值。若上游未提供
回應模型的資訊,該資訊會保持缺漏,不會從請求的模型推測。
| 方法與路徑 | 用途 | 主要錯誤 |
|---|---|---|
GET /api/logs |
查詢過濾的記憶體內請求日誌 | — |
GET, PUT /api/debug |
讀取除錯旗標;設定、清除或重置擷取類別 | 400 無效或空更新 |
GET /api/debug/logs |
讀取有界的供應商/除錯日誌項目 | — |
GET /api/debug/usage-logs |
讀取有界的 usage-debug 項目 | — |
GET /api/debug/injection-logs |
讀取有界的 guidance-injection 除錯項目 | — |
GET /api/claude/inbound-debug |
讀取 Claude inbound 除錯狀態與項目 | — |
GET /api/usage |
依範圍與客戶端介面摘要用量 | 若儲存無法讀取則回傳 500 { "error": "read_failed" } |
GET /api/metrics |
回傳程序本機的 Prometheus 文字指標,涵蓋邏輯請求、實際傳送、復原種類、持續時間與 TTFT。請求指標使用封閉標籤集合;Kiro 指標僅增加有上限的不透明帳號標籤;絕不匯出請求或憑證識別碼。 四個 Kiro 配額指標 opencodex_kiro_quota_{used_credits,limit_credits,used_percent,seconds_to_reset} 只讀取快取,最多使用 32 個不透明帳號標籤;擷取時不發起網路請求。 |
啟動時 metricsExport.enabled 不為 true 則回傳 404;需要一般管理驗證,資料平面憑證不能存取 |
GET /api/storage |
依 bucket 掃描 Codex 儲存用量 | 掃描失敗時回傳 error: "scan_failed" payload |
POST /api/storage/cleanup/preview |
預覽已封存 session 清理並回傳綁定摘要 | 400 invalid_json 或 invalid_percent |
POST /api/storage/cleanup |
隔離或永久移除預覽的已封存集合 | 400 無效輸入;409 過時/忙碌/被參照狀態;500 檔案系統/資料庫失敗 |
GET /api/storage/trash |
列出隔離的清理項目 | 500 trash_list_failed |
POST /api/storage/trash/restore |
還原一個隔離項目 | 400 無效 id;404 缺失 trash;409 忙碌/目的地衝突;500 還原失敗 |
GET /api/storage/trash/restore/test-stream |
僅測試的還原串流 hook | 測試 hook 關閉時 404 not_available |
GET, PUT /api/storage/cleanup-policy |
讀取或更新排程清理政策與工作狀態 | 400 無效政策 |
POST /api/storage/cleanup-policy/run |
啟動手動清理政策執行 | 409 already_running;500 cleanup_failed |
GET /api/storage/cleanup-policy/test-stream |
僅測試的政策串流 hook | 不可用時 404 not_found |
如果某行超過現有解析器的大小限制,GET /api/usage 和 GET /api/keys 會保留可讀取行的彙總,並在回應層級加入 usageIncomplete: true 和 usageIncompleteReason: "oversized_rows"。快取和增量附加會保留此診斷,即使結果為空或沒有篩選符合項目;重建時會重新計算。不會縮短供應商、模型或 API 金鑰識別碼來容納該行。沒有此標記不代表所有記錄均有效。它與 historyTruncated、entriesTruncated 及 token 測量覆蓋率相互獨立。
models、providers 及 days[].models 中的列也帶有 cacheHitRate:表示由供應商提示快取提供的輸入權杖比例,並限制在 [0, 1]。當供應商未回報快取遙測資料,或該列沒有輸入權杖時,其值為 null,絕不會是 0;因為「沒有快取資料」與「確實為 0% 的命中率」是不同事實,若圖表將兩者呈現為相同狀態,便會造成誤導。
| 方法與路徑 | 用途 | 主要錯誤 |
|---|---|---|
GET /api/catalog |
回傳已安裝的 Codex 目錄檔案 | 404 目錄未找到 |
GET /api/models |
回傳儀表板/CLI 模型列 | 收集飽和時 catalog_busy |
GET /api/client-config?client=... |
為 opencode、pi、omp、hermes、openclaw、kimi、gajae 或 dsh 建構唯讀客戶端設定 |
400 不支援客戶端;503 目錄不可用 |
PUT /api/disabled-models |
取代共享的 disabled-model 清單 | 400 無效 JSON |
PUT /api/model-visibility |
原子地變更供應商或模型層級可見性 | 400 無效供應商、scope、目標或 body; 409 initial_model_selection_pending (重新整理模型清單後再試。) |
GET, POST /api/custom-models |
列出自訂模型或新增一個 | 400 無效欄位;404 供應商缺失;409 重複模型 |
PUT, DELETE /api/custom-models/{id} |
編輯或刪除一個自訂模型 | 400 無效 id/欄位;404 未找到;409 重複模型 |
GET, PUT /api/selected-models |
讀取供應商允許清單與可用性,或取代一個允許清單 | 400 缺失供應商/body;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 帳號、供應商金鑰與 data-plane 金鑰
Section titled “OAuth 帳號、供應商金鑰與 data-plane 金鑰”| 方法與路徑 | 用途 | 主要錯誤 |
|---|---|---|
GET /api/oauth/providers |
列出有公開 OAuth 登入流程的供應商 | — |
GET /api/key-providers |
列出透過 API-key 登入設定的供應商 | — |
POST /api/oauth/login |
啟動 OAuth 登入或帳號新增流程 | 400 未知/無效供應商;oauth_mutation_busy |
POST /api/oauth/login/code |
提交手動 callback URL 或授權碼 | 400 無效供應商/碼;oauth_mutation_busy |
POST /api/oauth/login/cancel |
取消公開進行中的 OAuth 流程 | 400 未知供應商 |
GET /api/oauth/status |
輪詢一個供應商的 OAuth 流程 | 400 未知供應商 |
POST /api/oauth/logout |
移除所選的供應商憑證 | 400 未知供應商;oauth_mutation_busy |
GET /api/oauth/accounts |
列出遮罩帳號;Anthropic 與通用 OAuth 帳號列也會提供 paused 狀態。Kiro 列包含自動選取狀態 autoSelectable,排除時還包含封閉集合的 skipReason。唯一的有效帳號仍可傳送請求,配額查詢仍為選用。 |
400 無效供應商 |
DELETE /api/oauth/accounts |
移除一個帳號 | 400 無效供應商/id;404 帳號缺失;oauth_mutation_busy |
PUT /api/oauth/accounts/active |
選擇現用 OAuth 帳號 | 400 無效供應商/帳號;404 帳號缺失;409 帳號已暫停;oauth_mutation_busy; 503 affinity_reset_not_persisted (Anthropic: selectionCommitted: true, retryable: true; 帳戶選擇已儲存;即使已啟用,也請重新傳送相同請求) |
PUT /api/oauth/accounts/pause |
暫停或恢復一個 Anthropic 或通用 OAuth 帳號。Body { provider, accountId, paused };若暫停現用帳號,且有可用帳號,會切換至下一個。暫停會持久儲存且不受帳號池開關影響,恢復保留健康狀態與憑證。 |
400 不支援的供應商或無效 body;404 帳號缺失;oauth_mutation_busy; 503 affinity_reset_not_persisted (Anthropic: pauseCommitted: true, retryable: true; 暫停狀態已儲存;保留帳號和暫停狀態,加入 retryAffinityReset: true 後重試,伺服器重新啟動後也會確認重設) |
GET, PUT, PATCH /api/oauth/accounts/pool |
讀取或更新 Anthropic OAuth 池政策 | 400 非 Anthropic 供應商或無效政策 |
POST /api/oauth/accounts/clear-cooldown |
清除一個 OAuth 帳號的 runtime 冷卻 | 400 無效供應商/帳號 |
PUT /api/oauth/accounts/alias |
設定或清除 OAuth 帳號別名 | 400 無效供應商/帳號/別名 |
GET, POST, DELETE /api/providers/keys |
列出遮罩供應商金鑰、新增/啟用一個或移除一個 | 400 無效輸入;404 供應商/金鑰缺失 |
PUT /api/providers/keys/active |
選擇供應商的現用金鑰 | 400 無效輸入;404 供應商/金鑰缺失 |
PUT /api/providers/keys/alias |
設定或清除供應商金鑰別名 | 400 無效輸入;404 供應商/金鑰缺失 |
GET, POST, PATCH, DELETE /api/keys |
列出、建立、編輯或刪除 data-plane 許可金鑰 | 400 無效 body/id;404 金鑰缺失 |
PUT /api/oauth/accounts/affinity-reset |
無需帳戶即可確認 provider 全部對話繫結的重設已儲存。Body { provider };成功回傳 affinityResetConfirmed: true. CLI: ocx account reset-affinity anthropic --json (anthropic2 supported). |
400 invalid body/provider; 503 affinity_reset_not_persisted, retryable: true |
即使儲存的帳戶已消失,儀表板也會保留未確認的重設警告。清單載入失敗、帳戶暫停或需要重新驗證時,會保留重試並提示。清單確認帳戶不存在後,重試使用 { provider } 呼叫 PUT /api/oauth/accounts/affinity-reset,只有收到 affinityResetConfirmed: true 才清除警告。此操作會清除所有繫結,包括首次失敗後建立的繫結,但不會選擇或恢復帳戶,帳戶清單為空時也可執行。存在待完成重設時,刪除請求傳送 retryAffinityReset=true;儲存失敗回傳 503 affinity_reset_not_persisted、deletionCommitted: true 和 retryable: true。帳戶已經刪除,請重試專用重設端點而非刪除。一般刪除保留其他帳戶的繫結。專用清理僅適用於註冊的 Anthropic OAuth 執行個體,並保留原有管理驗證與來源檢查。
憑證清單回應被刻意遮罩。OAuth access token 與完整的供應商 API 金鑰不回傳給儀表板客戶端。
| 方法與路徑 | 用途 | 主要錯誤 |
|---|---|---|
GET /api/providers |
列出遮罩後的供應商設定與探索狀態 | — |
POST /api/providers |
新增或取代一個已驗證的供應商並可選擇設為預設 | 400 無效/危險目的地或設定;409 命名空間碰撞 |
PATCH /api/providers?name=... |
更新允許的供應商欄位、enabled/default 狀態或 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 |
讀取或更新全域、所有供應商或單一供應商的 context 上限 | 400 無效請求;404 未知供應商 |
GET /api/provider-presets |
回傳從 runtime registry 衍生的 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 session 讀取 repository 加星狀態 |
狀態專屬的固定結果代碼 |
POST /api/github/star |
僅從已認證的人類動作為 repository 加星 | 403 agent_consent_required,針對無儀表板 session 證據的 agent 驅動呼叫者 |
GET /api/update/badge |
直接讀取快取的套件更新徽章,不查詢登錄檔;快取缺失、頻道不符或已達 40 小時時回傳 unknown: true。surface=desktop&session=<id> 僅讀取該桌面應用程式工作階段。 |
400 無效 surface;桌面工作階段缺失或過期時回傳 unknown: true |
POST /api/update/desktop-snapshot |
桌面 shell 透過已繫結的代理用戶端發布 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 毫秒的整數。無效 JSON 或參數回傳 400,且不會開始重新啟動;綁定目標行程的本機 restart capability 不允許設定此參數(403)。回應中的 drainTimeoutMs 表示第一次接受的等待時間,重複呼叫不會變更已接受的時間或截止點。等待時間包含傳送接受回應前的延遲;清理與替代行程就緒仍分別保留獨立的 60 秒及 70 秒預算。被中斷的請求可能已經執行,重新傳送前應核對結果;此選項不會增加自動重新傳送。
| 方法與路徑 | 用途 | 主要錯誤 |
|---|---|---|
GET /api/system/memory |
回傳純量行程、heap、串流、回應狀態、看門狗與活躍回合指標 | — |
POST /api/system/restart |
在不移除客戶端注入的情況下開始感知排空的行程重啟 | 回傳 202;重複呼叫回報既有的排空 |
POST /api/stop |
停止服務、還原原生 Codex、移除受管 Grok 注入並排空代理 | 409 服務擁有權衝突;當 Windows 工作排程器包裝程序可能重新啟動 Proxy 且呼叫端不是 ocx stop 時回傳 409 respawnable_service(不會做任何變更);已安裝的管理器拒絕停止時回傳 409;無法讀取工作排程器狀態時回傳 409 service_state_unknown(不會做任何變更;修復查詢後重試) |
Codex 認證委派
Section titled “Codex 認證委派”根管理分派器將每個 /api/codex-auth/* 請求委派給 Codex 帳號管理員。其路由為:
| 方法與路徑 | 用途 | 主要錯誤 |
|---|---|---|
GET, POST, DELETE /api/codex-auth/accounts |
列出/重新整理或刪除 Codex 帳號。POST 僅保留為已停用的相容 endpoint;成功的 DELETE 回應包含 catalogRefreshPending。 |
POST 一律回傳 403 manual_import_disabled;DELETE 輸入無效時回傳 400 |
PUT /api/codex-auth/accounts/alias |
設定或清除帳號別名 | 400 無效帳號/別名 |
PUT /api/codex-auth/accounts/pause |
手動暫停或恢復帳號及身分相符的既有主帳號/帳號池項目;回傳 affectedAccountIds |
400 無效帳號/狀態;404 找不到帳號;503 主帳號身分資料使用中或無法讀取 |
PUT /api/codex-auth/accounts/pause-exhausted |
暫停配額耗盡的帳號 | 變更鎖失敗變為 503 |
POST /api/codex-auth/accounts/clear-cooldown |
清除一個或所有帳號的 runtime 冷卻 | 400 無效 id |
GET, PUT /api/codex-auth/active |
讀取或選擇現用帳號 | 400 無效或缺失帳號;409 暫停/舊列衝突 |
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 |
檢查帳號的 reset-credit 資格 | 400 缺失帳號 id;上游狀態 passthrough;500 查詢失敗 |
POST /api/codex-auth/reset-credits/consume |
消耗一個合格的 reset credit。選用的 operationId(UUIDv4)可讓兌換具備冪等性:相同 id 會重播同一筆持久化結果,而不會再消耗一個 credit。 |
400 缺失帳號 id 或無效的 operationId;若該 id 屬於其他帳號則 409 identity_mismatch;上游狀態 passthrough;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 |
輪詢流程或帳號登入狀態 | 未知流程回報 expired;無活躍流程回報 idle |
此委派家族下的設定寫入器或憑證重新整理鎖逾時回傳 HTTP 503 並附帶代碼 CONFIG_MUTATION_LOCK_UNAVAILABLE。客戶端應稍後重試,而非將該回應視為永久帳號失敗。
對於普通管理,網頁儀表板提供最安全的引導工作流程。對於無頭主機與自動化,請使用對應的 ocx 指令:它們呼叫此相同的即時 API,並在代理不可達或操作失敗時回傳非零結果。直接 HTTP 對需要上述精確端點契約的整合最為有用。
遠端工作階段與資料金鑰輪替
Section titled “遠端工作階段與資料金鑰輪替”POST /api/keys/rotate {id} 開始十分鐘重疊期,且只回傳一次新金鑰。POST /api/keys/rotate/commit {id,rotationId} 提交,DELETE /api/keys/rotate {id,rotationId} 中止。全部都需要管理驗證,資料金鑰不能呼叫。POST /api/session/logout 需要目前的 gui-session、相符的 Origin 與 CSRF。Admin token 會收到 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.