跳到內容

Claude Code 指南

opencodex 在 /v1/responses 之外還提供 POST /v1/messages(以及 count_tokens),因此 Claude Code 可以使用每一個已路由的供應商——包括 OAuth 登入、帳號池、金鑰故障轉移和 sidecar—— 而無需進行任何額外的身分驗證設定。

你可以透過 Providers 儀表板登入多個 Claude 帳號(ocx login anthropic / add-account)。預設 每個請求只使用作用中帳號。

實驗性、opt-in 的 Claude 帳號池(anthropicAccountPool.enabled)會在這些 OAuth 帳號之間加入 sticky session affinity 與依用量的新工作階段選擇。它不控制 429 容錯移轉:只要儲存了兩個以上可用帳號,被限流的請求無論此開關開或關都會切換到另一個帳號,且無法關閉。僅對新工作階段,anthropicAccountPool.strategy 會在合格帳號之間選擇:quota(預設)保留現用帳號,直到 anthropicAccountPool.quotaWindow 所設定視窗的用量 (five-hour 為預設,亦可選 weekly 或 max-utilization)達到 autoSwitchThreshold (預設 80),然後轉到用量最低的帳號,並優先選擇低於自身閾值的帳號; round-robin 平均分散(stickyLimit,預設 1);fill-first 一直使用作用中帳號直到冷卻、重新認證 或達到閾值,然後前進。它預設關閉,仍屬實驗性功能。

儀表板會列出帳號池的適用條件:你本人擁有或獲授權使用的訂閱、官方 Claude Code 用戶端,以及有人看顧的工作階段。 Anthropic 未認可自動帳號池;同一組織的帳號可能共用配額(新增帳號不一定能增加容量),切換帳號也無法避免供應商的 執行處置。OpenCodex 不會傳送保溫(keep-warm)請求,預設也不會在背景更新 Claude 權杖或讀取用量:只有儀表板、選單列 應用程式或 ocx 指令要求時才會讀取用量。門檻是選擇帳號的偏好,而非用量或計費上限。以上為產品說明,並非法律意見; 請查閱 Anthropic 的現行條款。

啟用時的營運契約:

  • 上游 429 會讓該帳號冷卻(有 Retry-After 時使用它,否則用預設 backoff), 並可能在同一個請求內輪換到另一個合格帳號(有上限)。只有共享配額拒絕會清除 affinity;暫時限流會保留綁定。
  • Affinity 可在相同設定目錄及提供者實例中跨 proxy 重啟保留(閒置 24 小時,最多 2,000 筆)。快照只存工作階段摘要及登入識別圍欄,不存原始工作階段金鑰或 token。沒有持久登入識別的舊帳號在再次登入前僅保留程序內綁定;一般 token 更新保留綁定,重新登入、移除、暫停、需要重新驗證或執行期間手動選擇帳號則使其失效。暫時限流的替代帳號不會覆寫原綁定。
  • Token 更新失敗保留既有 needsReauth 規則。明確的訂閱或帳號計費 403 可在輸出前切換帳號,冷卻遵循 Retry-After 或預設十分鐘;一般權限拒絕不切換。詳見帳號復原。
  • 如果每個合格帳號都在冷卻,proxy 會回傳 429(不是 401),並在已知時附上 Retry-After。
  • 復原(包括 429 容錯移轉)會使用 quotaWindow 為合格的替代帳號排序,且不改變現有的冷卻或 容錯移轉上限;round-robin 會忽略 quotaWindow。

請見 Configuration。

Terminal window
ocx claude

ocx claude 會確保代理正在執行,然後在接好環境變數的情況下啟動 Claude Code:

變數 值
ANTHROPIC_BASE_URL http://127.0.0.1:<port>
ANTHROPIC_AUTH_TOKEN 僅在代理要求 API 金鑰時設定——否則不會設定,因此你的 claude.ai 登入(訂閱 + 聯結器)會保持有效
CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY 1(原生 /model 選擇器發現)
CLAUDE_CODE_AUTO_COMPACT_WINDOW 自動上下文壓縮閾值(預設 829800);僅在啟用自動上下文時注入
ANTHROPIC_MODEL claudeCode.model(可選)
ANTHROPIC_DEFAULT_HAIKU_MODEL claudeCode.tierModels.haiku ?? claudeCode.smallFastModel(可選,也包括舊版 ANTHROPIC_SMALL_FAST_MODEL)
ANTHROPIC_DEFAULT_{OPUS,SONNET,FABLE}_MODEL claudeCode.tierModels.*(以訂閱方式啟動且未設定時為原生 claude-opus-5-5[1m] / claude-sonnet-5-5[1m] / claude-fable-5-1[1m])
ANTHROPIC_DEFAULT_{OPUS,SONNET,FABLE,HAIKU}_MODEL_NAME OpenCodex 將層級槽位設為路由別名時對應的 /model 標籤(例如 ocx-claude-native--gpt-6.1-sol → gpt-6.1-sol (native))。launchd 系統環境與 shell 掛鉤中也成對寫入。模型 ID 仍為別名。您自行設定的槽位或標籤不會被修改
CLAUDE_CODE_ALWAYS_ENABLE_EFFORT 啟用 alwaysEnableEffort 時設為 1(條件注入)
ENABLE_TOOL_SEARCH 設定 claudeCode.toolSearch 時注入(條件注入,預設關閉)
CLAUDE_CODE_MAX_CONTEXT_TOKENS 設定 maxContextTokens 時使用的舊版上下文覆蓋項(條件注入)
你自行匯出的變數始終優先。額外引數會直接透傳:ocx claude -p "hello"。

以前當 Claude 路由被關閉時,ocx claude 會直接報錯結束。現在它會改為啟動原生 claude 執行檔,因此在關閉路由的情況下該指令仍然可用:

路由關閉的位置 行為
設定中的 claudeCode.enabled: false 原生啟動,並提示路由已停用
執行中的代理在 GET /api/claude-code 回傳 enabled: false 原生啟動,並提示重新啟用後重啟服務
claudeCode.enabled 缺少或為 true 與以往一致,經代理路由

只有明確的 false 才會觸發回退,因此早於該欄位的舊代理仍會維持路由。代理不存在同樣不是觸發 條件——只要路由是開啟的,ocx claude 仍會照常啟動代理。

原生工作階段不應繼承代理狀態,因此回退只移除能夠證明屬於 OpenCodex 的值:僅當 ANTHROPIC_BASE_URL 指向本代理自身的回送位址與設定連接埠、且配對的 admission token 確實由代理 簽發時才移除;此外還會移除 CLAUDE_CODE_* 的探索與自動上下文開關,以及只能經由代理解析的模型 槽位(路由別名與 provider/model 形式)。其餘都屬於你自己的設定並會保留——無關的 http://localhost:8080 閘道器和你自己的 sk-ant- 憑證都會保留。

若儲存的 /model 選擇器預設值是僅限代理的模型,當 claudeCode.model 可在原生環境使用時會 回退到它,否則會警告你傳入 --model <Anthropic 模型>。明確的 --model 引數始終優先。

Claude Code 需要在 ANTHROPIC_AUTH_TOKEN 中有 token 才能與閘道器通訊,但設定該變數也會停用 你的 claude.ai 登入及其聯結器。你要哪一種,取決於 opencodex 可以查到的狀態,因此預設會自動判斷。

在 連線 → Claude 中把 認證模式 保持為 自動(預設值),opencodex 會在每次 啟動時決定:

偵測結果 行為
有 Claude 登入(~/.claude.json 的 OAuth 帳號、.credentials.json、macOS keychain,或已匯出的 ANTHROPIC_API_KEY) 不設定 token,讓你的訂閱與聯結器繼續運作
完全沒有 Claude 認證 注入佔位 token,讓 Claude Code 不再要求登入,並經由代理路由
無法判斷(keychain 無法讀取、檔案損毀) 假設為訂閱並印出警告——讀取失敗時絕不會把付費訂閱者改成走代理

此判斷會在每次啟動時重新計算,不會被記住,因此登入或登出會在下一次 ocx claude 時自動生效, 無需重新設定。

若要固定行為,請明確選擇 Subscription 或 Proxy。明確選擇會寫入 claudeCode.authMode, 之後即使登入狀態改變,偵測也不會覆寫——包括你稍後登入或登出。切回自動即可把決定權交回。

在 macOS 上,自動連線(claudeCode.systemEnv)也遵循相同解析邏輯,因此在 ocx 之外直接啟動的 claude 行為一致。該檔案是代理啟動或你儲存設定時重新整理的快照,而 ocx claude 則一律即時解析。

Claude Desktop 模式:閘道(預設)與第一方

Section titled “Claude Desktop 模式:閘道(預設)與第一方”

在儀表板的 連線 → Claude Desktop → 連線模式,或透過 ocx claude desktop apply --first-party|--gateway 選擇互斥的模式。

新安裝預設套用閘道設定檔:包含聊天分頁在內的整個應用程式都使用 OpenCodex。 僅限 claude.ai 的功能無法使用。舊版 --static、--hybrid 和 --discovery-only 選項也會選擇閘道。

Desktop 第一方模式透過 OpenCodex 處理 Code 分頁及其子代理。獨立的 Claude Code CLI 有單獨開關。兩者讀取同一份 settings.json 代理與 CA 設定:只啟用其中一個時,另一個仍會經過本機代理,TLS 在本機終止,但 Messages 請求會原樣轉送給 Anthropic。

模式儲存在 claudeCode.desktopMode。先前明確套用第一方模式或在此版本之前套用的安裝 會保留第一方模式;現有閘道安裝也維持不變。沒有明確設定時,依序檢查 OpenCodex 擁有的 已選閘道項目、儲存的閘道指紋、settings.json 中屬於 OpenCodex 的第一方設定; 都沒有時採用閘道。僅為 CLI 第一方模式寫入的環境變數,不能證明 Desktop 處於第一方模式。目錄同步和模型清單更新絕不會在已解析為第一方模式的安裝上 寫入閘道設定檔。若 claudeCode.intercept.enabled: false,現有第一方安裝的套用操作 會以 intercept_disabled 拒絕,新安裝則套用閘道。不會覆寫其他代理的設定。 切換模式後請完全結束並重新開啟 Desktop。

在 連線 → Claude 開啟 CLI 開關,或執行 ocx claude config set --first-party on;關閉時使用 off。若本機代理無法使用、CA 無法準備、設定無法讀取,或代理鍵由其他程式擁有,開啟要求會被拒絕。關閉仍可儲存。只有 Desktop 第一方模式開啟時,若要讓終端機完全原生直連,請在 shell 設定 NO_PROXY='*'。上述帳號風險也適用於 CLI。 第一方模式開啟期間,OpenCodex 也會在 ~/.claude/settings.json 的 NO_PROXY 加入 127.0.0.1、localhost、::1 和 0.0.0.0,讓本機 MCP 伺服器(包括 *.localhost 名稱)略過代理;其他 127.x 位址請自行加入。既有的 NO_PROXY 只會補上缺少的項目,關閉後,若 OpenCodex 已成功記錄原本的值且你之後未修改,就會還原原本的值;否則保留目前的值(包括新增的項目)。 關閉 Claude 路由會保留由 OpenCodex 管理的代理設定。監聽器仍執行時,所有 Messages 請求原樣轉送;停止後,執行 OpenCodex 或關閉 Desktop/CLI 第一方模式前,直接執行 claude 無法連線。ocx claude 原生啟動只在有自有設定且未繼承外部 HTTPS 代理時設定 NO_PROXY=*。否則保留外部代理,並警告設定中的攔截仍生效;請關閉第一方模式或取消該設定。 介面會區分設定無法讀取(unknown)、帶有 opencodex 權杖的代理 URL 卻搭配外部 CA(foreign:手動修正 HTTPS_PROXY / NODE_EXTRA_CA_CERTS),以及 Claude 路由已關閉但監聽器仍原樣轉送要求(disabled:重新啟動前關閉第一方模式以移除設定)。沒有監聽器時為 stopped;使用受管理的 CA 但連接埠或權杖不符時為 broken。第一方模式開啟但無法提供攔截服務時,stopped 和 broken 都顯示 routingOff:Claude 路由或攔截功能已關閉,或這台裝置是另一個 opencodex 中樞的用戶端;請在這台裝置上重新啟用攔截服務,或關閉第一方模式以移除設定。只有攔截服務可用時,stopped 才提示啟動 opencodex,broken 才提示執行 ocx ensure 或重新啟動。CLI 已開啟但沒有代理設定時為未套用;只開啟一個用戶端且代理正常時提示共享轉送;兩者皆關閉但代理設定仍在時提示殘留。 unknown 表示 opencodex 無法確定設定是否仍指向自己的代理。外部 CA 搭配 127.0.0.1 上沒有權杖的代理時顯示 local:無法確認歸屬;若不再使用,請從 ~/.claude/settings.json 移除 HTTPS_PROXY。disabled 僅在設定與執行中的監聽器相符時出現;連接埠或權杖不相符時,即使路由關閉也顯示 broken。

Picker 模式:在第一方 Code 分頁顯示 opencodex 模型

Section titled “Picker 模式:在第一方 Code 分頁顯示 opencodex 模型”

Picker 模式是第一方模式的一部分。在 macOS 和 Windows 上選擇第一方時預設開啟;設定 claudeCode.intercept.picker: false 後會保持關閉。它會修改第一方 Desktop 的 Code 分頁模型選擇器, 依名稱列出可用的 opencodex 模型。首次開啟時,macOS 可能會要求你在登入鑰匙圈中、Windows 可能會要求你在目前使用者根存放區中信任本機憑證授權單位。 該授權單位限制為 claude.ai 及其子網域。可匯出的簽章身分由 OS 認證資料儲存區保護,一般重新啟動會重用相同的憑證與金鑰。 OpenCodex 設定目錄不會儲存明文 Picker 簽章金鑰。受限 CA 的完整驗證與 OS 信任檢查仍然適用(Windows 按精確指紋與已驗證葉片驗證)。 已核准的身分不變且認證資料儲存區可用時,重新啟動不會新增或移除 macOS 憑證信任設定。啟動復原與狀態檢查絕不會安裝信任: 若信任缺失、遭撤銷或無法確認,Picker 會維持待處理狀態。請明確執行 ocx claude desktop picker on 或 ocx claude desktop picker trust 來授予信任(Windows 需要時含確認)。

從舊身分進行一次性移轉時,清除原有信任可能需要同意。清理未完成時,Picker 無法使用,已套用的設定檔 會使用不解密的中繼。macOS 也可能另外要求解鎖鑰匙圈或核准應用程式存取憑證,重新啟動或升級時也可能出現這些提示。Windows 上明確執行 on 或 trust 可能顯示新增根的確認。 Linux 仍不支援 Picker,不會啟動 Picker CA、認證資料儲存區或代理作業。主要 Claude 攔截功能仍可用, 其本機 CA 檔案受到擁有者、符號連結、檔案權限及 Windows ACL 檢查保護。

Picker 模式開啟期間,Claude Desktop 會透過 OpenCodex 存取網路。如果 OpenCodex 停止,Desktop 會離線, 直到你完全重新啟動 Desktop 或關閉 Picker 模式。使用 ocx claude desktop picker status 查看狀態, 使用 ocx claude desktop picker trust 重複信任步驟,或使用 ocx claude desktop picker off 關閉。 儀表板的 連線 → Claude Desktop 也有相同的切換開關。選取 Picker 設定檔後,請完全結束並重新開啟 Claude Desktop。

Picker 模式屬於第一方模式,因此第一方帳號風險同樣適用。

在上游首次回應之前,Picker 上傳若連續 60 秒沒有進展就會關閉。逾時會中斷上傳,不會回傳成功回應;HTTP/2 僅重設受影響的串流。上游背壓導致傳輸暫停時,閒置計時也會暫停;上傳完成或上游首次回應後,計時器會被移除。此閒置保護機制不會額外限制上傳總時長,現有執行階段與通訊協定限制仍然適用。回應串流不受此計時器限制。

只有閘道模式會將以下設定檔寫入 Desktop。

Claude Desktop 使用與 Claude Code 分開的設定檔。在儀表板開啟 連線 → Claude Desktop,可把每條 可用路由放到四個系列之一:Opus、Fable、Sonnet 或 Haiku。新設定檔中所有路由一開始都在 Opus。 第一個 Opus 路由會成為整體初始預設,且每個非空系列都一定會有一個系列預設。

若要改系列,可以把列拖到另一個系列。拖曳是可選的:每一列也都有可用滑鼠、觸控或鍵盤操作的 移動控制項。使用 設為預設 選擇系列預設,再選 儲存並套用到 Desktop。允許空系列。若已 儲存的預設暫時不可用,會改用該系列中第一個可用路由,直到原預設回來。

你也可以用命令列管理同一份設定檔:

以下設定檔編輯說明適用於本機設定檔;連接遠端 hub 時的套用方式另見下節。

Terminal window
ocx claude desktop [apply]
ocx claude desktop show [--json]
ocx claude desktop status [--json]
ocx claude desktop move <route> <opus|fable|sonnet|haiku> [--default]
ocx claude desktop default <opus|fable|sonnet|haiku> <route|none>
ocx claude desktop export <path|->
ocx claude desktop import <path> [--apply]

ocx claude desktop 與 apply 會套用選定模式:第一方寫入 Claude Code 代理環境變數, 閘道則寫入 Desktop 設定檔。show 提供可讀摘要;加上 --json 方便腳本使用。export - 會把帶版本的 JSON 寫到標準輸出。Import 會在儲存前驗證完整 檔案,因此無效檔案不會改動目前設定檔。加上 --apply 可在匯入有效設定檔後立即寫入 Desktop。 none 僅適用於空系列;每個非空系列都必須保留一個預設。

非 Anthropic 路由會得到穩定別名,例如 claude-fable-5-p01q,其後綴是以 p 開頭的四字元代碼。OpenCodex 仍會在內部保留合成日期槽位, 以維持既有設定檔配置的穩定性,但不會把日期當成 Desktop 模型 ID;目前的 Desktop 版本在比較作用中工作階段的模型時會移除尾端日期, 因而可能抑制模型切換。 真正的 Anthropic Claude 路由保留真實 id。新路由預設落在 Opus 系列,但移動路由不會改變它所呼叫的供應商或模型。舊版 apply 旗標 --static、--hybrid 與 --discovery-only 仍可供既有腳本使用。

當 claudeCode.systemEnv 設定為 true(預設:關閉)時,ocx start 會使用 launchctl setenv 在系統範圍內注入 ANTHROPIC_BASE_URL 和相關的 Claude Code 環境變數。因此,新開啟的終端視窗和 標籤頁可以直接透過代理路由普通的 claude 命令,無需使用 ocx claude 包裝器。已經開啟的 shell 不受影響,必須重新開啟。

ocx stop 和代理關閉操作會取消設定已注入的鍵(不會恢復之前的值——只會移除 opencodex 注入的鍵)。代理還會寫入 ~/.opencodex/claude-env.sh;ocx start 會安裝一個 .zshrc source hook,以自動載入該檔案,但僅限 PATH 中存在可執行的 Claude Code CLI。Claude Code 不存在或系統環境整合未啟用時,啟動程序和 ocx ensure 會移除 OpenCodex 自己寫入的 hook。 Claude Desktop 使用獨立 profile,不會觸發 shell hook 安裝。

可以在設定中設定 claudeCode.systemEnv: false,或使用 GUI 開關來停用。此功能僅適用於 macOS;在其他平臺上,請使用 ocx claude。

未設定身分驗證覆蓋時,Claude Code 會保留其 claude.ai OAuth 登入,並將其傳送給代理。 對於未被任何別名或模型對映佔用的真正 claude*/anthropic* 模型,請求會連同你的憑證 原樣轉發到 api.anthropic.com——beta、思考簽名、提示快取和計費身份都保持完全原生, 而已路由模型仍可在同一會話中透過選擇器別名使用。

**標頭處理:**轉發前一律移除逐跳標頭以及 host、content-length、 accept-encoding、x-opencodex-api-key 和 origin。在非回環綁定上,原生透傳還要求透過 x-opencodex-api-key 提供有效的代理許可憑證;此時 Authorization 與 x-api-key 僅屬於 Anthropic。若任一供應商標頭含有代理許可密鑰,該密鑰會被移除,而另一標頭中的真正供應商 憑證會保留。以逗號合併的模糊憑證標頭不會被轉發。

只有同時滿足以下所有條件時才會觸發透傳:nativePassthrough 不為 false;模型以 claude 或 anthropic 開頭;bearer token 或 x-api-key 以 sk-ant- 開頭;並且別名/模型對映 解析後回傳的模型保持不變;且在非回環綁定上,專用代理許可標頭有效。這也意味著使用 ocx claude 時不再出現 “claude.ai connectors are disabled”警告。

請求本文中唯一會改動的是工具呼叫 ID。Anthropic 會拒絕的 tool_use.id 或 tool_result.tool_use_id(含 a-zA-Z0-9_- 以外的字元或超過 64 個字元,例如工作階段早先由路由模型產生的 ID)會被改寫為合規 ID,並保持呼叫與結果的配對。合規 ID 原樣送出,空 ID 會在本地直接回傳 400。

可以設定 claudeCode.nativePassthrough: false 來停用;也可以透過 claudeCode.anthropicBaseUrl 指向其他位置。

已連接的機器執行 ocx claude desktop apply 或 ocx claude desktop 時,會讀取 hub 的 Desktop 快照,將 hub origin 和 hub 發出的完整模型 ID 原樣寫入本機 Desktop 設定,不再於本機 產生別名。static/hybrid 模式也複製模型清單;discovery-only 模式使用 hub origin,不嵌入清單。

Desktop 設定檔、模型家族分組及預設值由 hub 管理。在 hub 上修改後,請在客戶端重新套用, 並在 Desktop 中重新選擇模型。以前只在客戶端產生的別名也需要重新套用、重新選擇,不會自動 移轉。show、本機編輯及 import/export 仍只操作本機設定。連接期間不支援 ocx claude desktop import <path> --apply,會在儲存前拒絕;不帶 --apply 的 import 仍是本機操作。

讀取使用現有連線的資料存取憑證,不需要管理員權杖,也不會上傳設定檔。舊版 hub 不支援快照、 回應無效或 Desktop 清單為空時,套用會失敗,不會改用本機目錄或回環位址。 請更新或設定 hub 後重新套用。

本次別名修改不解決 #3719 中獨立的 thinking / redacted_thinking 重播與提示快取請求。 只有代理存取憑證不會啟用原生 Anthropic 透傳,但經過轉換的 Anthropic 路由仍可使用提示快取。 重播保真與快取命中率比較仍是獨立工作。

在 Desktop Code 分頁使用 opencodex 模型(第一方綁定)

Section titled “在 Desktop Code 分頁使用 opencodex 模型(第一方綁定)”

在第一方模式中,Code 分頁的模型選擇器屬於 claude.ai:其中的項目(Opus 5.5、Sonnet 5、 Haiku 4.5 以及 More models 下的舊模型)來自你的帳號,任何本機設定都無法新增 opencodex 項目。OpenCodex 在每個請求中收到的是選擇器裡的 Anthropic 模型 ID,因此改為把選擇器項目綁定到 opencodex 路由:

Terminal window
ocx claude desktop bind claude-sonnet-4-6 xai/grok-4.7
ocx claude desktop bind claude-opus-4-6 native/gpt-6.1-sol
ocx claude desktop unbind claude-opus-4-6

也可以在儀表板中透過 連線 → Claude Desktop → Code 分頁模型綁定 完成同樣操作。綁定之後,在 Code 分頁選擇 Sonnet 4.6 時會由 xai/grok-4.7 回應。選擇器仍顯示 Anthropic 名稱,且 Claude Code 的系統提示仍會把模型介紹為那個 Claude 模型,所以建議選擇平時不用的項目 (More models 中的項目是不錯的候選)。綁定於下一個請求即生效,無需重新啟動 Desktop。

  • 路由使用 Desktop 路由記法:provider/model,原生 OpenAI 池使用 native/<slug>。路由必須 是儀表板中列為可用的路由。
  • 帶日期的選擇器 ID(claude-haiku-4-5-20251001)會匹配無日期的綁定(claude-haiku-4-5), [1m] 和快速模式選擇也遵循同一綁定。
  • 綁定保存在 claudeCode.intercept.modelMap 中,僅適用於經由本機攔截代理的 Claude Code 流量: 第一方模式下的 Desktop Code 分頁和獨立的 claude CLI。ocx claude 工作階段和公開的 /v1/messages 端點會忽略綁定;全域 claudeCode.modelMap 仍然處處生效,同一 ID 時綁定優先。
  • ocx claude desktop status --json 在 firstParty.modelBindings 中報告目前生效的綁定。

金鑰輪換和復原會同步更新本機連線憑證與該連線管理的 Desktop 設定中的金鑰,無須為了移轉 金鑰而手動重新 apply。模型 ID、家族分組、預設值及目前設定選擇都會保留;輪換不會重新選取 管理設定,也不會啟用已關閉的整合。CLI JSON 的 rotation: "committed" 表示新金鑰已生效, rotation: "rolled_back" 表示保留或還原了舊金鑰,不代表新金鑰已提交或舊金鑰已撤銷。 結果不確定或復原未完成時,不會回報輪換成功。

首次連線套用會儲存原先的管理設定和選擇,以供還原;後續 apply 和輪換不會覆寫這份初始紀錄。 ocx disconnect 還原連線管理的設定,同時保留使用者新增欄位和其他設定檔。只有管理設定檔 仍被選取時才還原之前的選擇;使用者後來選取的其他有效設定檔保持不變。新建設定檔若已有 使用者新增內容,會保留為可讀取的標準模式,而不是刪除這些內容。--keep-catalog 保留的是 目錄,不是 Desktop 連線金鑰。

沒有原始紀錄的舊管理設定檔,只要能明確確認屬於目前 hub 和已識別的連線金鑰,就能移轉。 apply、輪換/復原或直接 disconnect 均可處理,無須新參數或事先重新 apply。系統會警告: 先前的設定未記錄,中斷連線時將使用標準模式。只移除連線擁有的閘道設定,保留使用者欄位和 另行選取的有效設定檔;結果標為標準回退,而非還原原始設定。

管理欄位衝突、無法識別的憑證或損壞的還原紀錄會保留並回報,不會覆寫。中斷的清理僅針對 同一連線繼續,不會刪除新連線,也不會在還原未完成時宣稱完成。中斷前先完成待處理的金鑰 輪換復原;重試中斷時保持原來的目錄保留選項。

套用、輪換/復原或還原設定後,請完全退出並重新開啟 Claude Desktop。修改磁碟檔案不會替換 執行中應用程式持有的金鑰,也不會自動退出或重新啟動應用程式。中斷連線在本機完成,不會 自動撤銷 hub 金鑰或刪除外部副本;如有需要,請另行在 hub 撤銷。

Claude Code 2.1.129+ 透過 GET /v1/models?limit=1000 發現閘道器模型,並在原生 /model 選擇器中列出。沒有 description 的列會顯示為“From gateway”;opencodex 會為 Claude Code CLI 的每一列送出 description(Routed by OpenCodex to <provider>/<model>;原生列為 Routed by OpenCodex to native <model>,Fast 列末尾加上 · Fast,1M 列沿用基礎描述),Claude Code 2.1.257+ 會改為顯示它。 Claude Code 2.1.278 接受包含 claude 或 anthropic 的 ID。以 claude- 開頭的未知 ID 在不關閉 compact 時按 200k 計算,因此 opencodex 會將已路由模型公開為包含 claude、但不以 claude- 開頭的穩定且可逆別名:

介面 格式 示例
Claude Code CLI ocx-claude-<provider>--<model>(plain)或 ocx-claude2-…(escaped) ocx-claude-native--gpt-5.6-sol
Claude Desktop 3P claude-fable-5-p<code>(3 字元 base36 設定檔槽位) claude-fable-5-p01q

代理會按請求選擇別名族:?ids=cli 或 ?ids=desktop 優先;否則,claude-code/* user-agent 會獲得易讀的 CLI 形式,其他用戶端會獲得 Desktop 代碼形式。兩種別名族都會永久 保持可解碼——以任一形式儲存在 settings.json 中的模型都能繼續工作。 每個條目帶有誠實的顯示名(如 gemini-3-pro (gemini)),並以官方 ModelInfo 形態附帶完整模型 能力(推理強度階梯、thinking 型別),使 Claude Desktop 的第三方閘道器模式能夠提供其推理強度 選擇器。真實 Anthropic 模型保留其規範 id。合成的 2026 日期是內部槽位,不是釋出日期。舊版雜湊 別名與較舊設定中的 claude-ocx-<provider>--<model> id 仍可解析,跳脫的 claude-ocx2-<provider>--<model> 也同樣可解析。已儲存的舊 id 仍會路由,但 Claude Code 對它仍按 200k 計算。把已儲存的 claude-ocx- 重新選一次對應的 ocx-claude-,跳脫的 claude-ocx2- 重新選一次 ocx-claude2-,即可同時用上真實上下文 視窗與 compact。 目錄中的有效上下文視窗為 1M 或不低於預設壓縮閾值(829,800)的模型會多出一個 …[1m] 選擇器列:選中後 Claude Code 會按完整 1M 上下文 計算該模型(自動壓縮仍開啟)——代理在路由前會去掉該標記。 選中後會儲存到 Claude Code 的 settings.json model 欄位;入站請求會將別名解析回路由 模型。在較舊的 Claude Code 版本中,選擇器保持原生——可透過 ANTHROPIC_MODEL 設定槽位,或在 /model 中輸入任意已路由 id(Claude Code 會原樣傳遞字串)。

**別名語法規則:**provider 不得包含 / 或 --,也不得等於 native。 不含 / 或 ~ 的一般 model ID 使用 v1 前綴 ocx-claude-…。包含 / 或 ~ 的 model ID 使用 v2 前綴 ocx-claude2-… 並跳脫(/ → ~s,~ → ~t),例如 openrouter/anthropic/claude-opus-4-8 → ocx-claude2-openrouter--anthropic~sclaude-opus-4-8。 v1 別名按字面解碼(歷史上 model ID 中包含的兩字元序列 ~s / ~t 會被保留);v2 別名會展開跳脫。 易讀形式無法表達的路由會回退到雜湊別名。模型 ID 可以包含 --(解析時只按第一個 -- 拆分);包含 -- 的原生 slug 會回退到雜湊形式。

**模型解析順序:**移除 [1m] 標記 → 解碼易讀別名 → 解碼 Desktop 雜湊別名 → modelMap 精確匹配 → 移除日期後的匹配(移除 -20250514)→ 透傳。

無法解析的日期型 Desktop ID 也可能是探索結果中缺少的真實原生模型 ID。現有資訊不足以 解析該 ID 時,Messages 和 count-tokens 回傳 HTTP 503 及固定錯誤 desktop_model_mapping_unavailable;這不代表 模型無效。未知的舊版雜湊別名仍回傳 HTTP 400。兩種情況都不會移除日期或回退到其他路由。 已知 ID、已註冊映射、精確 modelMap 匹配及已識別的真實原生 ID 維持原有處理方式。 請重新整理模型探索或重新套用已連接 hub 的設定後再試;僅重試本身不能保證解決。

每個條目都帶有類似 gemini-3-pro (gemini) 的顯示名稱,以及官方 ModelInfo 結構中的完整 模型能力(推理強度階梯、思考型別)。真正的 Anthropic 模型在兩個介面上都保留其規範 ID。

這些判斷使用目錄中的有效視窗,其中可能包含自訂供應商的推斷值。推斷值並不證明中轉的實際容量。

目錄中的有效上下文視窗為 1M 或不低於預設壓縮閾值(829,800)的模型會多出一個帶 …[1m] 的選擇器條目。 該下限是固定的,修改壓縮值不會降低它;Anthropic 路由上的 Claude 模型必須真正達到 1M;關閉自動上下文後只對 1M 模型生效。 超出真實視窗時會回傳 prompt is too long 錯誤,Claude Code 會自動壓縮。選擇它後,Claude Code 會按完整的 1M 上下文計算。 代理會在進行別名解析和路由之前移除不區分大小寫的 [1m] 字尾。

自動上下文(突破 200k 上限的大上下文模型)

Section titled “自動上下文(突破 200k 上限的大上下文模型)”

對於任何無法識別的模型,Claude Code 都會按 200k token 計算。預設開啟的自動上下文可解決 這一問題:

  1. 啟動環境槽位會在目錄中的有效視窗大於 200k 且至少達到所設定的自動壓縮閾值時帶上 [1m] 標記。探索列表和 Desktop 選擇器條目不跟隨該閾值:它們使用固定的 829,800 token 下限(Anthropic 路由上的 Claude 模型必須真正達到 1M)。
  2. 系統會注入 CLAUDE_CODE_AUTO_COMPACT_WINDOW(預設 829800,範圍 100000–1000000), 使對話在該位置自動進行摘要。

設定有三種狀態:

  • **缺省 / true:**啟用(預設)
  • **false:**停用——不新增標記,也不注入壓縮視窗
  • **設定了舊版 maxContextTokens:**隱式停用自動上下文

可以在 Claude 頁面調整壓縮值。**警告:**如果將其提高到超過模型的實際視窗,該模型將無法正常 工作——聊天會在觸發摘要之前報錯。

Messages 錯誤回應正規化使用固定文案,不保留提供方原文或 token 數量。辨識到上下文超限時傳回 prompt is too long: The request exceeds the model's context window.。串流中第一個欄位為 error 事件的區塊最多保留 1 MiB;超過後傳回不含壓縮觸發短語的固定錯誤。範圍和兩項例外請見英文指南。

低於 1M 的原生 Anthropic 模型絕不會被自動標記。你自行匯出的壓縮值在啟動槽位標記上始終優先(代理會使用你的 值來判斷哪些模型可以安全標記)。探索列表忽略該匯出值並保持固定下限。手動編輯設定時填入的無效值會回退到 829,800。

上下文計算方式(預設 1M,200k 需選擇啟用)

Section titled “上下文計算方式(預設 1M,200k 需選擇啟用)”

claudeCode.contextAccounting 決定 opencodex 預設選用的值。未設定(1m,預設)時,長上下文模型在啟動環境槽位、 Desktop 選擇器、Desktop 3P(prefer1m)和產生的子代理中按 1M 提供。設為 200k 即可退出:不再自動加上 [1m] 標記, 不注入 CLAUDE_CODE_AUTO_COMPACT_WINDOW,Desktop 3P 保留 supports1m 但移除 prefer1m。你自己標記 [1m] 的選擇仍可使用 (產生的子代理和強制子代理仍會移除模型視窗無法承載的標記),探索清單中目錄視窗至少為 1M 的模型的 · 1M 條目也仍然存在。200k 優先於 自動上下文:你自行匯出的壓縮值不會重新啟用自動標記,但 opencodex 不會改動你匯出的值。

Terminal window
ocx claude config set --context-accounting 200k

effectiveModelEnv 會計算由 ocx claude / 系統環境 / shell 檔案注入的六個槽位: ANTHROPIC_MODEL、四個 ANTHROPIC_DEFAULT_{OPUS,SONNET,HAIKU,FABLE}_MODEL,以及舊版 ANTHROPIC_SMALL_FAST_MODEL。有效 Haiku 值為 tierModels.haiku ?? smallFastModel,並會 提供給兩個 Haiku 變數。

以訂閱模式啟動 ocx claude 時,Claude Code 自身的登入會把 claude-sonnet-5 這類裸 Claude ID 直接送給 Anthropic,因此無論其他供應商為同一 ID 列出什麼,這些 ID 的上下文視窗都取自供應商登錄表。未設定的 Opus、Sonnet 或 Fable 槽位會填入 Claude Code 為該別名解析出的原生 ID,並帶上 [1m] 標記,因為在閘道之後,Claude Code 會把不帶標記的 ID 按 200k 計算。上限低於 1M 的 anthropic 列或 claudeCode.modelMap 項目會讓對應 ID 保持無標記,Haiku 永遠不會被填入或標記。以代理驗證啟動或關閉 nativePassthrough 時,由路由器決定,只有路由列的視窗生效。系統環境和 shell 檔案會讓未設定的槽位保持為空,因為它們的值也會傳到經由 hub 的啟動。

當 tierModels.haiku 和 smallFastModel 均未設定時,OpenCodex 會讓兩個輔助模型變數保持未設定;隨後 Claude Code 會選擇其原生輔助模型(目前為 Sonnet),並可能產生原生供應商費用。

ocx claude(以及系統環境 daemon)會把你的精選子代理名冊(Subagents 標籤頁,最多 5 個模型) 和 ocx-self 同步到 ~/.claude/agents/ocx-*.md。

  • ocx-self 固定你在 /model 選擇器中的預設模型(回退到 claudeCode.model);兩者均 不存在時省略。它不使用模型繼承。
  • 每個代理正文都包含一條 <!-- ocx-route: <model> --> 指令——代理使用該指令固定實際路由。 因此 Agent 工具的 model 引數不起作用;請傳入 "haiku" 作為佔位符。
  • Frontmatter 攜帶別名;路由由指令驅動。
  • 只有包含 generated-by: opencodex 且透過標記驗證的 ocx-*.md 檔案才會被覆蓋或清理; 你自己的代理絕不會被改動。
  • 檔案按單個檔案進行原子同步(寫入 + 重新命名)。
  • enabled: false 或 injectAgents: false 會清理所有經驗證歸屬的定義。
  • GUI PUT 和名冊變更會立即重新同步;啟動器/系統環境會在啟動時同步。

派發方式:subagent_type: "ocx-gpt-5-6-sol"。支援 1M 的目標會自動攜帶 [1m]。

Claude Code 內建的 claude-api 技能會注入約 840KB(約 136k token)的 Anthropic 文件內容, 並在提及 Claude 模型時自動觸發。已路由模型並未針對該文件包進行訓練,因此預設情況下, opencodex 會在已路由請求中將該技能內容替換為一個短佔位說明。原生 Anthropic 透傳不受影響。

會處理兩種載體:

  1. **工具結果載體:**assistant 的 Skill(...) 呼叫——當轉為小寫的 JSON 輸入包含被遮蔽名稱時, 與之配對的 tool_result 正文會被替換為佔位說明。
  2. **文字塊載體:**以 Base directory for this skill: 開頭且不少於 10,000 字元的使用者 文字塊——當目錄 basename 等於被遮蔽名稱時匹配(不區分大小寫)。目錄行最多只檢查 4,096 個 UTF-16 程式碼單元;更長的行會原樣送出,包括沒有結尾換行的情況。

透過 claudeCode.blockedSkills 設定(預設 ["claude-api"];[] 會完全停用省略)。 佔位說明會保持工具呼叫/結果的配對關係不變。

claudeCode.modelMap 會在路由前重寫傳入的 Anthropic 模型 ID:

{
"claudeCode": {
"modelMap": {
"claude-sonnet-4-5": "gemini/gemini-3-pro",
"claude-haiku-4-5": "gemini/gemini-3-flash"
}
}
}

查詢順序:發現別名 → 精確 ID → 移除日期字尾的 ID(-20250514)→ 透傳。

拒絕規則請見 Desktop 別名解析。

Sidecar 矩陣:Web Search 與圖像理解

Section titled “Sidecar 矩陣:Web Search 與圖像理解”

不同路由模型擁有的託管工具和圖像能力並不相同。opencodex 會在主模型回答前補齊這些能力:

  • Web-search sidecar 執行真實的託管搜尋,再把答案和來源作為工具結果交給路由模型。
  • Vision sidecar 在呼叫 noVisionModels 中的模型前描述附件圖像,並用文字描述替換圖像。

兩個 sidecar 都可使用以下任一後端:

後端 執行方式 所需條件
openai 透過 ChatGPT forward provider 呼叫小型 GPT 模型 ChatGPT 登入,以及已啟用的 authMode: "forward" provider
anthropic 透過已儲存的 Anthropic OAuth 呼叫 Claude;Web Search 使用 web_search_20250305,Vision 讓 Claude 描述圖像 已啟用的 adapter: "anthropic"、authMode: "oauth" provider,且其活動帳號未標記 needsReauth

顯式設定的 backend 始終優先。省略時,如果存在可用的 Anthropic OAuth 活動帳號,則選擇 anthropic;否則選擇 openai。顯式選擇 anthropic 卻沒有可用憑證時會關閉失敗 (fail closed):不會借用 ChatGPT 憑證,也不會靜默切換後端。同樣,OpenAI 後端缺少 ChatGPT 登入或 forward provider 時不會啟用。

Claude 入站的路由重放會把主 ChatGPT 登入附加到內部請求,因此即使 Claude Code 的 bearer 僅用於 代理認證,OpenAI sidecar 仍可存取。該 ChatGPT bearer 不會傳送給主路由 provider。

{
"webSearchSidecar": {
"backend": "anthropic",
"model": "claude-sonnet-5",
"maxSearchesPerTurn": 3
},
"visionSidecar": {
"backend": "anthropic",
"model": "claude-sonnet-5",
"maxDescriptionsPerTurn": 8
}
}

maxDescriptionsPerTurn 限制一個主模型 turn 中新增的圖像描述次數。快取命中和同一 turn 內重複的 進行中描述不會消耗配額。成功的 data: 圖像描述會按後端、模型、detail、圖像位元組和請求上下文 快取,避免每次重放都重複描述同一圖像與上下文。內容可能變化的遠端 https: 圖像不會快取。

全部設定項見設定參考。Anthropic OAuth Web Search 和圖像描述沿用儲存庫已有的 Claude Code OAuth fingerprint 先例,但在用於長時間無人值守任務前, 仍應使用你的帳號和實際負載進行充分 soak test。

對於從 Messages 轉換為 Responses 的請求,Claude Code 的 /effort 設定依下表對映:

傳輸格式 對映
thinking.type: "adaptive" + output_config.effort 直接傳遞強度(minimal|low|medium|high|xhigh|max|ultra)
thinking.type: "enabled" + budget_tokens ≤4096→low,≤16384→medium,更高→high
thinking.type: "disabled" reasoning: { effort: "none" };省略摘要

對於轉換後的請求,對映得到的等級會顯示在請求日誌的 Reasoning effort 欄中。 受管理的原生 Messages 請求在沒有可識別的 output_config.effort 時,將啟用的 thinking 預算記錄為 budget:<tokens>;此日誌記錄不會變更傳輸的請求本文。

代理會將每個 Anthropic Messages API 請求轉換為 Codex Responses API 格式:

Messages 輸入 Responses 輸出
頂層 system instructions(文字塊以 \n\n 連線)
messages[].role: "system" 同樣合併到 instructions
使用者文字 / 圖像 input_text / input_image(base64 → data URL)
Assistant 文字 output_text
Assistant tool_use function_call(input → JSON 字串化的 arguments)
使用者 tool_result function_call_output(is_error → [tool error] 字首)
重放 thinking / redacted_thinking reasoning 項目;簽名與遮蔽載荷保存在有界 ocxr1 信封中
Function 工具 {type: "function"}(web_search* → {type: "web_search"}) 帶有 allowed_domains、blocked_domains 或 user_location 的託管搜尋會從轉換後的 Responses/Chat 路由中移除;強制呼叫已移除的搜尋會回傳 400。有效的 defer_loading 函式定義仍可作為一般函式呼叫。參見轉換限制。
tool_choice auto→auto,none→none,any→required,指定名稱 function→{type:"function",name},hosted WebSearch/web_search→{type:"web_search"}
max_tokens max_output_tokens
stop_sequences stop

Claude Code 自動模式總是傳送 stop_sequences。對於路由目標提供者 noStopModels 清單中的模型,OpenCodex 在 Chat Completions 與 Responses 兩種線路上都會省略 stop,因此 grok-4.7、grok-4.6 等 xAI 推理模型不會回傳 400 invalid-argument 並被標記為暫時無法使用。參見 noStopModels。

在預期的 Anthropic 適配器上,保留未隱藏的簽名區塊(包括空 thinking)和不透明的 redacted 區塊。hideThinkingSummary 政策不變:不會向 Claude 用戶端公開本地隱藏的簽名文字,尚未證明經過此隱藏邊界的無損重播。舊版組合信封在串流文字發出後無法恢復原始區塊順序。claudeCode.compatibility: "enforce" 仍拒絕 thinking 重播。這不證明真實 Anthropic 接受請求或快取命中改善;#3719 仍未關閉。

**錯誤情況(400):**JSON 格式錯誤;缺少/空的 model;缺少/空的 messages;不支援的 role;tool_result 缺少 tool_use_id;tool_use 缺少 id/name;指定名稱的 tool_choice 缺少 name。

出站轉換(Responses → Messages SSE)

Section titled “出站轉換(Responses → Messages SSE)”
Responses 事件 Messages SSE
response.created message_start + ping
心跳 ping
文字增量 content_block_start → content_block_delta(文字)→ content_block_stop
推理摘要/文字 帶重播簽名或有界 ocxr1 備援信封的 thinking 塊
遮蔽推理 從推理信封重播的 redacted_thinking 塊
Function-call 幀 帶 input_json_delta 的 tool_use 塊
終止事件 message_delta → message_stop
在終止事件前 EOF 502 風格的 api_error

停止原因對映:completed → tool_use(如果有工具呼叫)或 end_turn; incomplete/max_output_tokens → max_tokens;incomplete/content_filter → refusal。

**錯誤分類:**400 invalid_request_error、401 authentication_error、 402 billing_error、403 permission_error、404 not_found_error、409 conflict_error、 413 request_too_large、429 rate_limit_error、504 timeout_error、529 overloaded_error, 其他 5xx 為 api_error。Retry-After 以整數秒傳送(HTTP 日期會換算為剩餘秒數),上限為 8 天。

**Anthropic 路由請求:**適配器會管理工具、系統內容和倒數第二條使用者訊息的快取斷點,以及頂層 自動 cache_control。穩定輪次通常能達到約 99.9% 的快取命中率。

**原生 OpenAI/ChatGPT 路由:**派生 prompt_cache_key(metadata.user_id 為字串時取自該值, 否則回退到系統內容雜湊),並僅在存在會話識別時派生用於快取親和性的 session_id 標頭(不會從共享回退鍵派生)。 由系統內容雜湊派生的回退鍵(僅在存在系統內容時使用)還包含模型和完整的工具 schema。

**Token 計算:**Anthropic 輸出會從 input_tokens 中減去 cached_tokens 和 cache_write_tokens,並將它們分別公開為 cache_read_input_tokens 和 cache_creation_input_tokens。請求日誌會將其對映回包含這些值的 inputTokens,讀取量同時 記錄在 cachedInputTokens 和 cacheReadInputTokens 中,寫入量記錄在 cacheCreationInputTokens 中。Usage 頁面會分別報告快取命中和快取建立。

**count_tokens:**已路由模型使用近似值(序列化後的 system + messages + tools)。使用 sk-ant- 憑證的原生 Anthropic 模型會將請求透傳到真實的 Anthropic /v1/messages/count_tokens 端點。

ocx debug claude on|off|status|reset、OCX_CLAUDE_DEBUG=1 或 PUT /api/debug {"claude": true} 控制入站捕獲。GET /api/claude/inbound-debug 回傳 {enabled, entries}(最新條目在前,環形緩衝區大小為 20)。

每個條目記錄:at、endpoint、model、resolvedModel、stream、maxTokens、 thinkingType、thinkingBudgetTokens、outputConfigEffort、metadataKeys、 hasMetadataUserId、hasSystem、原始 anthropicBeta,以及 user id / system 的八字元 HMAC 等值標籤。**不會儲存提示文字、原始物件或跨執行穩定的雜湊。**停用 Claude 除錯會立即 清空環形緩衝區。

儀表板的 連線 → Claude 在同一頁面顯示 Claude Code 設定。Claude Desktop 是 連線 下的另一個分頁。連線概覽中的 Claude 卡片也提供同一個連線開關。 頁面由上到下依序顯示:

  • Claude Code CLI 第一方 開關。
  • 開始使用:ocx claude 和手動環境變數區塊。
  • 一般:Fast Mode、自動上下文、壓縮閾值和子代理自動註冊設定。
  • 背景輔助模型:選擇用於聊天摘要、主題識別等背景工作的模型。
  • 模型攔截:將特定模型請求重新導向其他模型的 modelMap 編輯器。
  • 可用模型:/model 選單中模型別名的即時預覽。
  • Claude 連線 開關。

頁面底部的儲存列在捲動時保持可見,顯示 沒有變更 或 有未儲存的變更。還原 撤銷未儲存的設定變更;儲存 儲存編輯後的設定。Claude 連線 和 Claude Code CLI 第一方 開關立即生效;儲存 永遠不會改變這兩個開關的狀態。

GET /api/claude-code 回傳有效預設值、設定、上下文視窗登錄表、有效環境變數、可用路由 ID、 別名和埠。PUT /api/claude-code 接受部分更新並保留省略的欄位;null 會重置 context/blocklist/compact-window 值。

Claude Code 顯示“Did 0 searches”——目前版本會把已完成的 Responses web_search_call 轉換成配對的 Anthropic server_tool_use 和 web_search_tool_result block, 並寫入 usage.server_tool_use.web_search_requests。如果舊版本已經完成搜尋卻仍計為 0,請更新 opencodex。

Sidecar 未啟用——使用 backend: "openai" 時,請確認已登入 ChatGPT,並存在已啟用的 authMode: "forward" provider。使用 backend: "anthropic" 時,請確認已儲存的 Anthropic OAuth 活動帳號未標記 needsReauth。顯式選擇 Anthropic 卻沒有可用憑證時會按設計關閉失敗。

“claude.ai connectors are disabled”——你的 shell 中設定了 ANTHROPIC_API_KEY 或 ANTHROPIC_AUTH_TOKEN。ocx claude 特意不會設定 ANTHROPIC_API_KEY;如果你已將其 匯出,請取消設定。ocx claude 會注入 ANTHROPIC_BASE_URL、發現相關變數、自動上下文和已設定的模型槽位,但絕不會注入 ANTHROPIC_API_KEY。

模型未顯示在 /model 選擇器中——確認已設定 CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1(使用 ocx claude 時會自動設定)。執行 ocx claude 以重新整理 ~/.claude/cache/gateway-models.json 中的閘道器模型快取。檢查 claudeCode.enabled 不為 false。

埠更改後環境變數過時——如果代理埠發生變化,舊 shell 中的 ANTHROPIC_BASE_URL 可能已經過時。請開啟一個新終端,或重新執行 ocx claude。

大模型仍受 200k 上下文上限限制——在選擇器中選擇 [1m] 變體,或啟用自動上下文 (預設開啟)。如果選擇器中沒有 [1m] 條目,該模型在目錄中的有效上下文視窗可能低於固定的 829,800 token 下限。

技能載入導致 token 數量過高——內建的 claude-api 技能(約 136k token)會在提及 Claude 模型時自動載入。對於原生透傳,這是正常現象;對於已路由模型,opencodex 預設會將其 替換為佔位說明(blockedSkills: ["claude-api"])。

子代理派發到錯誤模型——名冊代理(ocx-*)使用 <!-- ocx-route: ... --> 指令, 而不是 Agent 工具的 model 引數。請確保指令與預期路由一致。傳入 "haiku" 作為模型佔位符。

在 config.json 中設定 claudeCode.stabilizePromptCache: true,可在轉換路由上移除系統指令末尾支援的 Claude 提示。辨識出的 <total_tokens>N tokens left</total_tokens> 格式的 token 頁尾會被刪除,包括重複出現的頁尾。TaskCreate 提醒仍依原有方式移到末尾的使用者訊息;如果移除的只有 token 頁尾,就不會新增輸入訊息。預設值為 false。僅在用戶端允許這種角色變更時啟用。程式碼圍欄中的範例和不符合的文字會保留,Anthropic 原生轉送不變。沒有中繼資料時,快取鍵依穩定後的指令計算。此選項不會產生對話識別碼,也不保證上游快取命中。

在所有轉換後的 Chat 路由上,時間線提醒都會保留在對話中的原有位置(排在尚待傳回的工具結果之後)。因此,新增提醒不會重寫開頭的系統提示,對話中途的指令也不會被移到它原本應跟隨的輪次之前。該位置攜帶哪個角色是另外決定的:除非提供者記錄了 foldDeveloperRoleToSystem: false,否則提醒以 system 傳送;該記錄表示上游接受 developer 角色,此時提醒在相同位置照原樣轉送。不接受該角色的上游會回應 400 role 'developer' is not allowed,該回合根本無法開始,所以未記錄的目的地採用摺疊。無論 stabilizePromptCache 是否啟用,此行為都會生效;Anthropic 原生轉送維持不變。快取重用仍需要穩定的工作階段識別碼和可用的上游快取。修改較早的指令或工具、壓縮對話也可能影響快取命中;僅保留提醒順序並不保證快取重用。

帳戶池啟用時,anthropicAccountPool.routes 依模型第一個符合的規則,將首次選擇和 429 重試限制在已儲存帳戶內。沒有可用帳戶時會在本機拒絕;fallback: true 才允許使用一般帳戶池。規則不代表帳戶確實有模型權限。

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] when the effective catalog window reaches the fixed 829,800-token floor, and only for a genuine 1M window on Anthropic Claude models and bare claude-* selectors; 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.

Explicit gateway selectors on a generated agent request take precedence over its legacy ocx-route fallback, even if the saved force setting changes after launch. For shell or settings overrides of generated roster agents, use an explicit gateway alias; bare Claude ids retain the older-client fallback behavior. Native aliases restore their bare model before the existing credential and model-map checks. Connected launches validate force targets against a fresh authenticated gateway catalog; failed discovery skips automatic force injection, and cached context windows alone never prove availability.

僅在輸出開始前的回應中,僅當 HTTP 401 的 authentication_error(無 error.code) 訊息完全等於 “OAuth access token has been revoked.” 時,發送請求的 OAuth 帳戶會被標記為需要重新登入,並清除工作階段綁定。輸出開始前,可在既有發送限制內切換到同一池的可用帳戶;沒有替代帳戶時回傳原始 401,該帳戶在重新登入前不會被選取。其他 401 的處理保持不變。