伺服器與執行階段設定
伺服器設定控制本機代理如何監聽、保護遠端流量、管理資源,並在供應商請求周圍執行輔助功能。
| 欄位 | 型別 | 預設值 | 意義 |
|---|---|---|---|
port |
number |
10100 |
代理監聽連接埠。 |
hostname? |
string |
"127.0.0.1" |
綁定位址。非回送綁定需要 OPENCODEX_API_AUTH_TOKEN。 |
proxy? |
string |
— | 對外 HTTP(S) 或 SOCKS5 代理 URL(socks5://host:port)或 ${ENV_VAR}。HTTP URL 僅在那些變數未設定時套用至 HTTP_PROXY / HTTPS_PROXY。SOCKS5 URL 使用內建的真實 SOCKS5 通道,也會套用至 ALL_PROXY(ocx start --socks5),並清除此行程繼承的 HTTP(S)_PROXY。回送保留在 NO_PROXY 中。 |
emptyCompletionRetry? |
boolean |
false |
明確啟用:當 Responses 完成時沒有文字或工具呼叫,以相同請求重試一次。重試可能產生費用。OCX_EMPTY_COMPLETION_RETRY=0 可在不變更設定的情況下停用;combo 與 routed-compaction turn 不適用。 |
stallTimeoutSec? |
number |
300(public)/ 停用(local) |
上游無有效進展(Responses 與原生 Chat)多少秒後切斷串流。未設定時本地上游(loopback、private、.local/.lan 名稱)預設停用,公網上游預設 300 秒;正值對兩者生效(最小 1 秒);0 全面停用靜默 watchdog。對於把 canonical ChatGPT SSE 折疊為非串流 JSON 的 Responses 請求,即使 watchdog 已停用,仍保留獨立的 15 分鐘整體上限。/v1/responses/compact 的擱置回應本文讀取共用此預算,但即使本地上游也預設 300 秒;明確值(含 0)優先。 |
connectTimeoutMs? |
number |
200000(public)/ 停用(local) |
從送出請求到上游傳回首個回應 header 的每次嘗試截止時間(DNS/TCP/TLS 及等待 header);它在 body 生成前結束,與管理 body 串流的 stallTimeoutSec 無關。未設定時本地上游(loopback、private、.local/.lan 名稱)預設停用,公網上游預設 200 秒;正值對兩者生效;0(或任何非正值)全面停用該 header 截止時間。停用後,本地模型在大提示上可花費數分鐘進行 prompt prefill,而首個 header 時鐘不會切斷健康的請求。 |
shutdownTimeoutMs? |
number |
5000 |
在中止活躍回合前的優雅排空截止時間。 |
websockets? |
boolean |
false |
廣告並允許面向 client 的 Responses WebSocket 路徑。False 時 client 使用 HTTP/SSE;不會停用符合條件的 canonical ChatGPT upstream WS 最佳化。 |
corsAllowOrigins? |
string[] |
[] |
額外的精確 CORS 來源。回送來源恆被允許。 |
apiKeys? |
OcxApiKey[] |
[] |
生成的 ocx_… data-plane 准入憑證(用於非回送綁定)。它們不授權管理 API;管理存取使用管理 API 參考中說明的獨立憑證。由儀表板管理。 |
storageCleanupPolicy? |
StorageCleanupPolicy |
停用 | 選擇加入的已封存 session 清理政策。永不隱含啟用。 |
appOwnedMemoryBudgetMb? |
number |
256 |
以 MiB 為單位、可被驅逐的 app 擁有日誌、快取、blob 與 continuation payload 上限。範圍 64–4096;非 RSS 上限。 |
metricsExport.enabled? |
boolean |
false |
在已驗證的 GET /api/metrics 啟用程序本機的彙總請求指標。需要重新啟動;停用時路徑回傳 404,且不會啟動任何匯出活動。 |
serviceHealthRecovery.enabled? |
boolean |
false |
背景服務的選用復原:一個小型監看程序探測 /healthz,當代理程序仍存活但在連續探測中約一分鐘毫無回應時將其終止,交由服務管理員(工作排程器、launchd、systemd、WinSW)重新啟動。僅受管服務子程序會啟動它;卡住程序持有的請求不會重送。每小時最多 3 次。需要重新啟動。自動復原需要數字繫結位址(或預設的 localhost/萬用字元對應);不監控 DNS 繫結名稱。記錄的位址或連接埠變更時會停止監控。 |
codexAutoStart? |
boolean |
true |
讓 Codex shim 在啟動 Codex 前執行 ocx ensure。False 使 ensure 為 no-op。 |
codexShimAutoRestore? |
boolean |
true |
在完成的外部 Codex 更新取代已安裝的 shim 後還原它。環境退出:OPENCODEX_CODEX_SHIM_AUTO_RESTORE=0。 |
syncResumeHistory? |
boolean |
true |
可逆的 Codex App 歷史相容性。原始中繼資料由 ocx stop / ocx restore 備份並還原。 |
shadowCallIntercept? |
{ enabled?: boolean; model?: string; sourceModels?: string[] } |
off | 將識別的 Codex helper/shadow call 重定向到所選模型,並保留為請求設定的 reasoning effort。預設來源前綴為 gpt-6-luna, gpt-5.6-luna;0.144.x 及更舊的客戶端使用 gpt-5.4-mini,可透過 sourceModels 恢復。 |
webSearchSidecar? |
OcxWebSearchSidecarConfig |
可用時開啟 | 網頁搜尋 sidecar 選項。 |
visionSidecar? |
OcxVisionSidecarConfig |
可用時開啟 | 圖片描述 sidecar 選項。 |
images? |
OcxImagesConfig |
自動 OpenAI 選擇 | Codex image_gen 的獨立 Images 中繼選項。 |
telemetry? |
OcxTelemetryConfig |
人工知悉提示後預設開啟 | 匿名每日使用遙測的同意狀態(decision、decidedAt、noticeShownAt)。在人工看到提示或主動同意之前不會傳送任何資料。可被 OCX_TELEMETRY=0 或 DO_NOT_TRACK=1 覆寫。請見遙測(telemetry)與遙測與隱私。 |
若較舊的開發組建在備份支援存在前變更了 resume-history 中繼資料,請執行 ocx recover-history --legacy-openai --yes 以強制原生供應商復原。
此命令會重新標記所有含有使用者訊息的 opencodex row,其中也包含正常的專用 provider 歷史;執行前請查看 lifecycle reference 中的完整範圍警告。
原生 Chat 的逾時與完成狀態
Section titled “原生 Chat 的逾時與完成狀態”原生 Chat 等待上游輸出時也使用 stallTimeoutSec。非空文字、推理、拒絕內容、工具更新及完成事件會重設等待額度;保活註解、僅角色事件及單獨的用量資訊不會。等待慢速用戶端讀取時暫停計時。逾時產生 upstream_stall_timeout:串流請求收到錯誤事件,非串流請求回傳 HTTP 502。終態結果到達前取消請求會回傳取消錯誤,不會將部分答案當成成功。非串流 Chat 支援 LF、CRLF 與多行 data 的 SSE 格式。
預設的 127.0.0.1 綁定僅限回送。如 0.0.0.0 的非回送位址需要在 /api/* 與 data plane 上都進行 token 認證。在啟動前匯出 token:
export OPENCODEX_API_AUTH_TOKEN="your-secret-token"ocx start代理在沒有此變數時拒絕遠端綁定。對於背景服務,請在 ocx service install 前匯出它,以便 launchd、systemd 或 Task Scheduler 接收它。客戶端應發送:
x-opencodex-api-key: your-secret-token| 端點 | Authorization: Bearer |
x-opencodex-api-key |
x-api-key |
|---|---|---|---|
/v1/responses |
不接受 | 必填 | 不接受 |
/v1/chat/completions |
不接受 | 必填 | 不接受 |
/v1/messages |
接受 | 接受 | 接受 |
/v1/messages/count_tokens |
接受 | 接受 | 接受 |
/v1/models |
接受 | 接受 | 接受 |
Responses 與 Chat Completions 為可能的 Codex Direct passthrough 保留 Authorization,因此那裡僅接受專屬的許可標頭。儀表板生成的 apiKeys 可在啟動後取代環境 token;候選值以常數時間比對。
Messages 與 count_tokens 為相容路由客戶端仍接受三種許可形式。但在非回環綁定上,原生 Anthropic 透傳只透過
x-opencodex-api-key 接受代理許可,並將 Authorization 與 x-api-key 保留給 Anthropic
憑證。放在這些供應商標頭中的代理許可密鑰會在轉發前移除。
無法接收 token 的本機用戶端
Section titled “無法接收 token 的本機用戶端”遠端綁定要求每個呼叫者都要有憑證,包括本機呼叫者。這會破壞一個特定情境:由 host process 啟動、
直接解析 Codex entrypoint(require.resolve('@openai/codex/bin/codex.js'))的 codex app-server
永遠不會經過生成的 codex shim,因此它不會繼承 OPENCODEX_API_AUTH_TOKEN,每次模型呼叫都會在
stream 開啟前以 401 失敗。
unauthenticatedLoopbackListener 會開啟第二個綁定到 127.0.0.1 的 listener,不要求憑證即可
放行。主 listener 不受影響——遠端呼叫者仍需要 token。
{ "hostname": "0.0.0.0", "port": 10100, "unauthenticatedLoopbackListener": { "enabled": true, "port": 10200 }}接著 ocx sync 會把 base_url = "http://127.0.0.1:10200/v1" 寫入受管的 Codex provider 區塊,
並省略 auth header,因此直接生成的 app-server 不需要任何憑證管線即可運作。
該 port 是必填的,且必須與 proxy port 不同。它絕不會由 OS 指派:臨時 port 會在重啟時改變,而
已執行的 app-server 仍保留先前的 base_url。
該 listener 只服務 POST /v1/responses、其 WebSocket upgrade、POST /v1/responses/compact、
POST /v1/alpha/search(Codex 原生網頁搜尋中繼)、GET /v1/models,以及獨立語音 WebSocket upgrade。
其他一切,包括 /api/* 與儀表板,都會回傳 404。
SSH 連接埠轉發
Section titled “SSH 連接埠轉發”遠端使用不需要遠端綁定。保持回送並轉發它:
ssh -L 20100:localhost:10100 you@remote任何本機連接埠皆可。Host 解析為 localhost、127.0.0.1 或 ::1 的請求,不論連接埠皆保持回送,因此 http://localhost:20100/v1 可運作。在客戶端設定該 base URL;ocx 僅將預設的本機 127.0.0.1 位址寫入受管客戶端設定。
供應商 OAuth callback 在固定遠端連接埠監聽。在遠端機器上登入或也轉發該連接埠:
ssh -L 20100:localhost:10100 -L 1455:localhost:1455 you@remote遙測(telemetry)
Section titled “遙測(telemetry)”匿名每日使用遙測僅在使用者看到告知提示(透過 GUI 彈窗或互動式終端機提示)後才預設開啟。config.json 中的 telemetry 區塊記錄該同意狀態:
{ "telemetry": { "decision": "accepted", "decidedAt": "2026-11-07T09:00:00.000Z", "noticeShownAt": "2026-11-07T09:00:00.000Z" }}| 欄位 | 型別 | 預設值 | 意義 |
|---|---|---|---|
telemetry.decision? |
"accepted" | "declined" |
未設定(未決定) | 使用者的明確選擇。"declined" 會停用遙測並立即刪除 <OPENCODEX_HOME>/telemetry-id.json;"accepted" 會啟用每日報告。 |
telemetry.decidedAt? |
string (ISO 8601) |
未設定 | 記錄 decision 的 UTC 時間戳記。僅傳送嚴格晚於 decidedAt ?? noticeShownAt 所在 UTC 日期的已完成 UTC 日曆日(day > formatUtcDay(decidedAt ?? noticeShownAt));同意當天及更早的日期絕不會補送。 |
telemetry.noticeShownAt? |
string (ISO 8601) |
未設定 | 人類使用者在網頁儀表板或互動式終端機中看到告知提示的 UTC 時間戳記。當 decision 未設定時,僅在已設定 noticeShownAt 時才會傳送遙測(default-on);否則代理保持在 awaiting-notice 狀態。 |
收集器端點(https://telemetry.opencodex.me/v1/events)是程式碼常數,無法在 config.json 中設定。
兩個環境變數會覆寫 config.json 並立即停用遙測,且不會修改已儲存的 config.json(在代理啟動或排程器週期偵測到任一變數時,還會在 <OPENCODEX_HOME>/telemetry-state.json 中記錄當日 UTC 日期為 ineligibleThroughDay 並刪除 <OPENCODEX_HOME>/telemetry-id.json,因此移除變數後不會補送這些日期,並會產生新的安裝 ID):
OCX_TELEMETRY=0(不分大小寫,也接受false、off或no)DO_NOT_TRACK=1(不分大小寫,也接受true或yes)
ocx config set telemetry 與 ocx config unset telemetry 會被拒絕,且 ocx config import 對所有呼叫方都會忽略匯入的 telemetry 區塊並保留已持久化的同意狀態;請改用 ocx telemetry enable(需要互動式終端機並確認告知提示,否則以 agent_consent_required / tty_required 結束)、ocx telemetry disable、ocx telemetry status [--json] 或儀表板 Proxy details 中的開關。完整負載結構與保留政策請參閱遙測與隱私。
storageCleanupPolicy 預設停用。啟用時,它在已封存位元組超過 trigger.archivedBytesOver 後於 startup、daily、weekly 或 manual 執行。它朝 target.reduceToBytes 或 target.removeOldestPercent 選擇最舊的封存。mode 預設為 quarantine;僅將 permanent 作為明確的破壞性選擇。政策持久化 lastRun 與 nextRun。在 Storage 頁面或以 GET/PUT /api/storage/cleanup-policy 設定它;以 POST /api/storage/cleanup-policy/run 觸發手動執行。
Claude Code(claudeCode)
Section titled “Claude Code(claudeCode)”這些設定治理 /v1/messages、/v1/messages/count_tokens、ocx claude 啟動器與 Claude 儀表板頁面。
| Key | 型別 | 預設值 | 說明 |
|---|---|---|---|
claudeCode.bodyStallSec? |
number |
90 |
原生 passthrough body 在讀取待決時的不活動預算(秒),非總持續時間。最小 1;精確 0 停用。 |
claudeCode.bodyMaxBytes? |
number |
67108864 |
串流與緩衝回應的累積原生 passthrough body 上限。精確 0 停用。 |
claudeCode.authMode? |
"proxy" | "subscription" |
自動 | 啟動如何處理 ANTHROPIC_AUTH_TOKEN。自動每次啟動偵測認證;明確值永不被覆寫。 |
claudeCode.authModeMigratedAt? |
string |
未設定 | 內部一次性升級標記。請勿手動設定。 |
claudeCode.subagentEffort? |
"low" | "medium" | "high" | "xhigh" | "max" |
繼承 | 寫入生成的 ~/.claude/agents/ocx-*.md 的 effort;與 Codex guidance 與代理上限分開。透過 ocx claude 重啟以重新生成。 |
自動認證在找到已儲存的 Claude 認證時選擇訂閱,無認證時選擇 proxy,偵測不明確時選擇訂閱並附帶警告。請見Claude Code 認證模式。
Shadow call
Section titled “Shadow call”Codex 使用小型 helper 模型處理如標題與 commit 訊息等任務。啟用 shadowCallIntercept 以將識別的來源模型前綴重定向到另一個已設定的模型。替換後仍會保留為請求設定的 reasoning effort。僅在客戶端使用不同的 helper id 時設定 sourceModels。
裸模型 ID 符合 sourceModels 的請求可被攔截,但 x-codex-turn-metadata 同時包含 request_kind: "turn" 和 thread_source: "user" 的使用者回合保留所選模型。連線標頭 x-openai-subagent: collab_spawn(HTTP 請求或 WebSocket 交握) 或中繼資料中的 subagent_kind: "thread_spawn" 標記的子代理也保留模型。WebSocket 的回合中繼資料僅依據每個框架的 client_metadata["x-codex-turn-metadata"],不使用交握中的回合中繼資料分類後續框架。中繼資料缺失或格式錯誤時保留原有攔截行為。輔助呼叫也可能帶有 request_kind: "turn",因此單憑此欄位不能豁免。這些規則適用於具體模型與 combo 目標。
{ "shadowCallIntercept": { "enabled": true, "model": "gpt-5.5", "sourceModels": ["gpt-6-luna", "gpt-5.6-luna"] }}目標無法使用時
Section titled “目標無法使用時”替換目標是操作者選定的唯一目的地,因此無法再解析的目標會讓輔助呼叫失敗,而不是把它送到別處。當目標的供應商被停用或刪除,或其組合已不存在時,被攔截的請求會在向上游送出任何內容之前回傳 409 與錯誤代碼 intercept_target_unavailable。請求記錄會記下相同代碼。請求不會直通給原生輔助模型,也不會退回預設供應商,因為兩者都會在你未選擇的情況下改變目的地、憑證與費用。組合或路由設定檔目標仍會在自身成員之間容錯移轉。像 provider/model 這樣的限定目標,若其供應商部分未指向任何已設定項目,也以相同方式處理,設定 API 會拒絕儲存。透過預設供應商解析的不帶前綴模型 ID 仍然有效。
停用(帶 disabled: true 的 PATCH /api/providers?name=<provider>)或刪除目標所解析到的供應商仍會成功;回應會加入 dependentShadowIntercept: { model, enabled },儀表板會顯示警告。重新啟用該供應商或選擇其他目標即可恢復攔截。
Sidecar
Section titled “Sidecar”images(OcxImagesConfig)
Section titled “images(OcxImagesConfig)”| 欄位 | 型別 | 預設值 | 意義 |
|---|---|---|---|
provider? |
string |
自動 OpenAI 選擇 | 用於 /v1/images/generations 與 /v1/images/edits 的明確自訂 API-key openai-responses 供應商。Registry 管理的 id 被拒絕。 |
timeoutMs? |
number |
300000 |
一個獨立 Images 請求的整體請求逾時。 |
明確選擇在供應商缺失、停用、不相容或缺少可用金鑰時 fail closed;它永不後退到另一個付費上游。端點必須實作 Codex 預期的 OpenAI Images API 路徑與回應結構。
webSearchSidecar(OcxWebSearchSidecarConfig)
Section titled “webSearchSidecar(OcxWebSearchSidecarConfig)”| 欄位 | 型別 | 預設值 | 意義 |
|---|---|---|---|
enabled? |
boolean |
可用時開啟 | 主開關。為 false 時,OpenCodex 停止攔截 web_search,且 Codex 整合會把 web_search = "disabled" 寫入 ~/.codex/config.toml。 |
backend? |
"openai" | "anthropic" | "xai" | "gemini" | "exa" |
openai |
明確設定優先;省略時一律使用 openai。anthropic 與 xai 僅在明確設定時執行;gemini 與 exa 在 executor 推出前仍為保留值。 |
model? |
string |
視 backend 而定 | OpenAI 為 gpt-5.6-luna、Anthropic 為 claude-sonnet-5、xAI 為 grok-4.6。舊版明確 gpt-5.4-mini 在啟動時遷移。 |
exaApiKey? |
string |
無 | exa backend 的操作員金鑰。僅可寫入:管理讀取永遠不會傳回已儲存的值。 |
xSearch? |
object |
省略 | xAI 專用的託管 x_search opt-in:enabled、互斥的 allowedXHandles / excludedXHandles 陣列(最多 20 項),以及 ISO fromDate / toDate(YYYY-MM-DD)。 |
reasoning? |
string |
low |
Sidecar effort。minimal 在網頁搜尋時被拒絕。 |
maxSearchesPerTurn? |
number |
3 |
每個主模型回合允許的實際搜尋。 |
routedModelStallTimeoutMs? |
number |
200000 |
僅設定檔的路由模型原始 body 不活動截止時間。整數 1–2147483647;每個非空 chunk 重置它。 |
timeoutMs? |
number |
60000 |
一個代管搜尋的截止時間。 |
OpenAI backend 需要 ChatGPT 登入與啟用的 ChatGPT forward 供應商。Claude-inbound 路由重播將主 ChatGPT 認證注入內部請求。Anthropic backend 使用來自已啟用 Anthropic OAuth 供應商的現用已儲存憑證。明確選擇的 Anthropic backend 在無可用帳號時 fail closed 而非後退。Anthropic 執行器使用其原生 web_search_20250305 工具。xAI backend 需要可用的已儲存 Grok OAuth 帳號,使用託管 web_search,並在 xSearch.enabled 為 true 時加入託管 x_search。格式錯誤的 xSearch 管理輸入會傳回 400;格式錯誤的持久化區塊會在規劃期間 fail closed。gemini 與 exa 通道絕不會因憑證探索或 fallback 而啟用;操作員必須明確選擇它們。exaApiKey 可在寫入時接受,但會從管理回應中省略。
四個時鐘治理搜尋:基礎 stallTimeoutSec、connectTimeoutMs、路由模型不活動與代管搜尋逾時。有效的橋接看門狗為最大值加 30 秒。路由停滯是不活動防護,而非總生成截止時間。
visionSidecar(OcxVisionSidecarConfig)
Section titled “visionSidecar(OcxVisionSidecarConfig)”| 欄位 | 型別 | 預設值 | 意義 |
|---|---|---|---|
enabled? |
boolean |
可用時開啟 | 主圖片描述開關。 |
backend? |
"openai" | "anthropic" |
自動 | 明確值優先;未設定時優先使用可用的已儲存 Anthropic OAuth 憑證,否則使用 openai。 |
model? |
string |
視 backend 而定 | OpenAI 為 gpt-5.6-luna 或 Anthropic 為 claude-sonnet-5。 |
maxDescriptionsPerTurn? |
number |
8 |
每個主回合允許的新描述快取未命中。0 停用呼叫;無效值使用預設。 |
timeoutMs? |
number |
45000 |
Sidecar 擷取逾時。整數 1–2147483647。 |
視覺僅對發送到其供應商 noVisionModels 中模型的圖片啟用。OpenAI 的登入/forward 需求與搜尋相同;明確選擇的 Anthropic 在無可用憑證時 fail closed。成功的 data: 描述使用以 backend、模型、細節、圖片位元組與正規化訊息 context 為 key 的有界快取。命中與同回合重複不消耗限制。遠端 https: 圖片與失敗或空的描述不被快取。
Anthropic OAuth sidecar 重用 opencodex 既有的 Claude Code OAuth 指紋。請對預期帳號與工作負載進行浸泡測試。
Remote Hub 金鑰與預設值
Section titled “Remote Hub 金鑰與預設值”runtimeRole 預設為 standalone。Hub 使用 hub.managementPublicOrigin、僅限迴路的 hub.managementIngress(缺省為 enabled:false)與正確的 remoteGui.allowedTailscaleUsers(缺省為空)。用戶端金鑰保存在 service-api-token 而不是 config.json;輪替期間可能暫時存在 service-api-token.prev。用量不會鏡像。
remoteGui.allowInsecureHttp 是已棄用的 no-op,只為讓舊的 strict-schema 設定繼續載入而保留。請從設定移除:pairing grant 僅接受 loopback 或已驗證的 HTTPS;設為 true 也不會重新開放明文 HTTP pairing。
Codex 配額網路診斷
Section titled “Codex 配額網路診斷”主 Codex 帳戶列中的 quotaRefresh 描述配額查詢結果,並不代表剩餘配額或模型存取權限。讀取快取或未執行查詢時,這個欄位可能省略。查詢使用執行中代理服務的環境,而不是目前終端機的環境。未設定 proxy 時保留既有環境;"auto" 在啟動時讀取 Windows 或 macOS 靜態 HTTP/HTTPS 設定;macOS 上若有繼承代理則略過讀取。macOS 會將有效的 *.<domain> 轉成 .<domain>:*.local 讓 foo.local 與裸網域 local 直連,但不比對 xlocal。精確的 169.254/16、169.254.0.0/16、fe80::/10 網段會略過並顯示診斷,因此鏈路本機 IP 位址使用代理。IP 位址與 * 仍可使用;其他 CIDR、萬用字元形式及簡單主機名稱例外會在修改環境前拒絕自動探索。不會自動處理 PAC/WPAD、僅 SOCKS 的設定或執行中的變更。TUN 測試成功本身不能證明 HTTP 代理路徑正常。命令與狀態說明請見英文網路診斷章節。
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.
歷史集區用量的連續性
Section titled “歷史集區用量的連續性”提供者集區額度依路由選定的標準提供者計算,請求日誌仍保留帳戶顯示標籤。對於目前設定的每個提供者 P,讀取餘額時會自動將本安裝環境的加鹽集區別名 h(pool, P) 綁定至 P,相同別名下保留的歷史餘額也適用。各提供者的獨立額度不需要手動加入自身對應,也不需要用鹽值自行計算雜湊。
其他歷史標籤,包括帶有帳戶序號的標籤,不會自動綁定。每份原始餘額只計入所屬群組一次;仍未綁定的正餘額則保守地計入每個候選集區一次。已結算、預留及尚未確認的用量都會計入,因此未知歷史可能限制尚未使用的集區。目前名稱或帳戶排列順序不能證明歷史歸屬。根請求及身分額度仍各自獨立。
對於已確認歸屬的歷史,請在 config.json 最上層設定 spendPoolAliases,不要放在 spend 內。索引鍵是本安裝環境日誌中的完整歷史集區加鹽別名,由 32 個小寫十六進位字元組成;值必須是已確認且目前已設定的提供者完整 ID,前後不得有空白。請保密保存日誌、鹽值及確認依據。已設定提供者自己的集區別名不能對應到另一個提供者;提供者集合變更時會重新驗證。驗證只讀取現有鹽值,不會建立新鹽值。
自動綁定及明確對應都只在讀取時套用,不搬移原始餘額,也不將身分關聯寫入日誌。刪除明確對應會讓該歷史重新成為歸屬未知;但如果別名屬於目前設定的提供者自身,自動綁定仍然有效。無效對應在寫入時會遭拒;手動編輯留下無效對應時,既有額度仍保留,但拒絕新的集區請求。
閒置的未知歷史只有在最後活動時間嚴格早於 spend.retentionDays 的期限後才會到期。容量不足不會提早刪除正餘額的未知歷史。活動中的預留及其目標即使為零權杖也會保留;只有刪除紀錄已持久化後,請求准入判斷才會使用減少後的餘額。
預留及傳送次數上限
Section titled “預留及傳送次數上限”若根請求、身分或集區額度適用,每個目標或金鑰的首次傳送都必須先取得一般追蹤容量的預留。無法預留時,不會傳送至提供者。同一目標的重試沿用原有範圍;不同目標或金鑰需要新的預留。L 是整個請求共用的實體傳送次數上限,在請求開始時固定。預設為四次;既有 OAuth 請求設定最多允許十八次。
是否執行額度限制、適用的根請求/身分/集區權杖額度,以及 L,都在請求開始時確定。設定變更只影響變更後開始的請求。已經執行中的請求在所有重試及後續傳送中保留開始時的策略:啟用或降低額度不會收緊它,提高或刪除額度也不會放寬它。以僅觀察模式開始的請求會維持該模式直到結束。
最終結算會等待已開始傳送的回報完成。只有帳務已持久化後才會遺忘傳送 ID,餘額仍會保留。上限限制的是傳送次數而非帳單,超過初始估算的實際用量仍全數計入。沒有適用額度時,維持原有的僅觀察行為,包括追蹤容量已滿時省略記帳;不會新增身分關聯檢查點。
Claude CLI、CodeBuddy 及 Qoder 將每次 CLI 呼叫計為一次傳送,啟動前仍須取得一般預留,否則拒絕啟動。CLI 內部重試及工具回合不會另外消耗整個請求的傳送次數上限。費用依回報的實際用量結算,包括超出初始估算的部分。
回復至 2.80.0:契約 C
Section titled “回復至 2.80.0:契約 C”新紀錄使用一般 v1 格式及 pool 別名範圍。未修改的 2.80.0 可依其逐標籤規則讀取、壓縮日誌及套用保留期限。請保留最新日誌及鹽值;還原較舊副本會遺失該副本之後記錄的支出。不需要回補修正、啟動阻擋機制或對帳指令。
降版後不保證維持標準提供者的彙總,也不保證與相同流量從未升級、始終由 2.80.0 處理時具有相同的剩餘額度。再次升級時,目前設定提供者的自動綁定及明確對應會套用至 2.80.0 仍保留的原始餘額。新檢查點不含需要舊版讀取器保留的身分關聯中繼資料。
未發布實驗版本的日誌若含 pool-current 或 poolContinuity,即使後來經過壓縮,仍不屬於契約 C。其原始餘額會作為未知歷史保留至正常到期,不會立即轉換或刪除。
完整但無效的紀錄,包括最後一行的 null,會使有額度限制的請求遭拒。壓縮仍可將有效帳務保留在乾淨的檢查點;目前程序的拒絕狀態會持續到重新啟動並讀取乾淨日誌。寫入中斷的最後一行 JSON 沿用原有復原規則。詳細範圍及錯誤碼請見英文原文。
本機上游逾時分類
Section titled “本機上游逾時分類”此分類只決定逾時政策,不授予網路存取權限。HTTP(S) 目的地依名稱或位址字面值分類,不查詢 DNS:精確的 localhost(不分大小寫,允許結尾句點)、0.0.0.0、IPv4 loopback(127/8)、RFC 1918 私有位址及 link-local(169.254/16)、IPv6 loopback、link-local(fe80::/10)、unique-local(fc00::/7)、IPv4-mapped 等價位址,以及 .local/.lan 名稱屬於本機。其他 DNS 名稱即使解析到 loopback,也保留公開上游逾時。無效目的地、不支援的協定及 localhost.example 亦保留公開預設值。
關閉回應標頭期限仍保留用戶端取消及外層整體期限。明確的正值 stallTimeoutSec 仍限制本機回應本文靜默;本機 header/stall 都未設定時,標頭抵達前沒有自動期限。原生 Chat/Messages 本機 JSON 讀取使用 stall 預算,公開 JSON 讀取保留原有 max(connectTimeoutMs ?? 200000, 5000)。Compact 本文即使本機也預設 300 秒。影像/搜尋 sidecar 預算不變。
選用的 opencodeClientExport 包含 headerTimeoutMs、chunkTimeoutMs、timeoutMs,接受正毫秒數或表示關閉的 false。省略時保留 OpenCode 預設值,無效欄位不匯出。設定在 V1 options 與 V2 settings 中對整個 provider 生效。請參閱慢速本機模型。