管理 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 identity_mismatch；502 上游錯誤；503 ledger 容量 |
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 無效欄位或結構 |
儀表板從 Providers > xAI Grok > Accounts 驅動這兩條 coupon 路徑：每個已登入帳號列都帶有票券徽章，顯示剩餘的 reset coupon 數量，徽章會開啟對話框，列出有效期間並兌換最接近到期的 reset coupon。該對話框會送出由客戶端鑄造的 operationId，並在逾時後停止送出而不重試，因為日誌記錄仍為開啟的兌換會再次執行。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 |
PUT /api/oauth/accounts/pause |
暫停或恢復一個 Anthropic 或通用 OAuth 帳號。Body { provider, accountId, paused }；若暫停現用帳號，且有可用帳號，會切換至下一個。暫停會持久儲存且不受帳號池開關影響，恢復保留健康狀態與憑證。 |
400 不支援的供應商或無效 body；404 帳號缺失；oauth_mutation_busy |
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 金鑰缺失 |
憑證清單回應被刻意遮罩。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 “系統生命週期”| 方法與路徑 | 用途 | 主要錯誤 |
|---|---|---|
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 |
暫停或恢復一個帳號 | 400 無效帳號／狀態；404 缺失帳號 |
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.