Claude Code Router——將 Claude Code 路由至任意模型，或完全略過路由器

搜尋Claude Code Router的大多數人想要的是兩種不同需求之一：讓 Claude Code 在多個模型提供者之間路由，或只是將 Claude Code 執行在比 Anthropic 列表價格更便宜的位置。只有第一種需求需要路由器。Claude Code 原生讀取 ANTHROPIC_BASE_URL，因此第二種需求只需設定三個環境變數，完全不需要額外軟體。

本指南涵蓋兩條路徑，包括精確的變數名稱、會產生靜默 401 的認證陷阱，以及透過任何閘道後哪些功能會停止運作的完整清單。如果你最近讀過其他 CCR 文章，請先跳到選項 B：那些文章要求你編輯的 config.json 已不再是路由器讀取的設定檔。

你實際需要哪一個？

路由器是一項本機服務：需要額外執行、設定並保持最新的程序；截至 2026 年，它還是一個具有自身 UI 的桌面應用程式，而不是供你編輯的檔案。當你確實需要多供應商路由、每次請求的帳務，或子代理程式層級的模型選擇時，這項成本是值得的。如果只需設定基礎 URL 就能完成，則不值得使用它。

選項 A — 交換基礎 URL（無需安裝）

Kunavo 在 /v1/messages 提供原生的 Anthropic Messages API，這就是 Claude Code 呼叫的端點。請將 Claude Code 指向該端點：

export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...              # create at kunavo.com/app/keys
export ANTHROPIC_MODEL=claude-sonnet-5             # exact slug — see the table below
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5     # the opus alias and plan mode (v2.1.280+)
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5   # the sonnet alias; Sonnet 5.5 is not on Kunavo
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5   # background tasks

ANTHROPIC_BASE_URL 僅是 Origin——Claude Code 會自行附加 /v1/messages，因此不要包含路徑。保留模型列：Claude Code 內建的預設模型及其 opus 別名都會解析至最新的 Opus；若 Kunavo 尚未提供該模型，第一次請求會回傳 404。sonnet 別名會要求 Kunavo 不提供的 Sonnet 5.5，因此若沒有 ANTHROPIC_DEFAULT_SONNET_MODEL 設定，/model sonnet、opusplan 的執行階段，以及任何設定為 model: sonnet 的子代理程式都會回傳 404。opus 別名會固定為 Opus 5.5（claude-opus-5-5），這需要 Claude Code v2.1.280 或更新版本——若您的版本較舊，請執行 claude update。請在註冊並儲值 $10 後，從控制面板取得金鑰；金鑰只會顯示一次。

使用哪個認證變數 — 以及為何重要

Claude Code 會將兩個認證變數傳送至不同的 HTTP 標頭；如果金鑰放在伺服器不讀取的標頭中，便會失敗並回傳 401：

優先使用 ANTHROPIC_AUTH_TOKEN 有一個明確的原因：ANTHROPIC_API_KEY 需要在互動式工作階段中核准一次，而且一旦你曾拒絕某個金鑰，之後該金鑰就會被忽略，也不會再出現提示 — 這種失敗情況令人困惑，因為變數明明已設定，卻明明沒有被使用。在 Kunavo 上，模型探索並不是決定選用哪個變數的因素。當 ANTHROPIC_AUTH_TOKEN 已設定時，Claude Code 的閘道模型探索只會傳送 bearer token，否則會改用 x-api-key；而 Kunavo 的 /v1/models 端點可從這兩種標頭中的任一種讀取金鑰。

讓設定持續生效

Shell 匯出只適用於該終端機及從中啟動的任何程式 — 從 Dock 開啟的編輯器看不到這些設定，背景代理程式也看不到。將值放入設定檔即可涵蓋所有情況：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.kunavo.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-kn-...",
    "ANTHROPIC_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5"
  }
}

所有專案都使用 ~/.claude/settings.json。絕不要將金鑰放入專案的 .claude/settings.json — 該檔案會被提交至版本控制。

在信任之前先驗證

先直接測試端點，讓失敗能指向設定，而不是 Claude Code：

curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":1,"messages":[{"role":"user","content":"."}]}'

# A response starting with {"id":"msg_ means the URL and key both work.
# 401 -> the key is in the wrong header; see "Which credential variable" below.

接著從相同的 shell 啟動 claude 並執行 /status。顯示 api.kunavo.com 的 Anthropic base URL 行，以及標示你所用變數的 Auth token 行，即可確認兩個部分都已生效。

設定自訂模型 — 明確選取 slug

Kunavo 會以完全相符的方式解析模型 slug，不會為帶日期後綴的名稱建立別名，因此 claude-sonnet-4-5-20250929 會回傳 404，而 claude-sonnet-5 會成功。請務必設定 ANTHROPIC_MODEL，不要依賴內建預設值：

別名變數可讓您針對每項任務進行路由，完全不需要路由器：ANTHROPIC_DEFAULT_OPUS_MODEL支援opus別名與 plan 模式，ANTHROPIC_DEFAULT_SONNET_MODEL支援sonnet以及opusplan的執行階段，而ANTHROPIC_DEFAULT_HAIKU_MODEL支援haiku，以及 Claude Code 的背景工作——那些悄悄累積成本的摘要與標題。將前者指向claude-haiku-4-5，是設定檔中價值最高的一行。（ANTHROPIC_SMALL_FAST_MODEL是相同設定的棄用寫法。）

選用：在選擇器中顯示所有模型

設定 CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1（Claude Code v2.1.129+）後，Claude Code 會在啟動時查詢 GET /v1/models，將找到的內容加入標示為 From gateway 的 /model 選擇器。Kunavo 提供該端點，因此每個已啟用的 Claude 模型都會顯示，而 /model 會成為即時選單，不再是需要手動維護的清單。兩種認證變數都可使用 — 請參閱上文。

選項 B — claude-code-router，如今實際的運作方式

請從這裡開始，因為幾乎所有關於 CCR 的文章描述的都是已不存在的版本。路由器過去是 JSON 檔案和 ccr code 指令。現在它是具備桌面應用程式、管理 UI、請求日誌和模型閘道的本機控制平面 — 而且教學中都會顯示的config.json已不再用於設定它。

CCR 將執行階段設定儲存在 ~/.claude-code-router/config.sqlite（Windows 上為 %APPDATA%\claude-code-router\config.sqlite）。當尚不存在 SQLite 設定時，舊版 config.json 會作為遷移來源讀取一次。第一次執行後，編輯它不會影響正在執行的設定 — 不會出現錯誤，也不會有警告。你仔細貼上的 Providers 區塊根本不是設定檔。

這也包含 2026-09-06 之前的本頁內容：過去放在這裡的 JSON 程式碼片段是錯的，而且是那種會浪費一個下午的錯，因為沒有任何訊息告訴你它被忽略了。現在設定必須在 UI 中完成（或備份時使用 Settings → Export data — CCR 執行期間不要複製即時 SQLite 檔案）。

安裝並啟動

CCR 提供兩種方式：來自 GitHub Releases 的桌面應用程式（系統匣、自動更新、桌面整合），以及用於無頭或受監督部署的 npm CLI。兩者共用相同的設定目錄。

# CCR ships as a desktop app (GitHub Releases) or an npm CLI. Both read the
# same ~/.claude-code-router directory. The CLI needs Node.js 22+.
npm install -g @musistudio/claude-code-router
ccr ui        # management UI on :3458, model gateway on :3456

# Configure the provider and an Agent Config profile in that UI, then launch
# Claude Code through the profile by name:
ccr "Claude Code - Kunavo"        # npm CLI
ccr-app "Claude Code - Kunavo"    # the desktop app's own launcher

# There is no 'ccr code' in the current command reference. The service commands
# are start / ui / stop / serve / web; everything else is a profile name.

新增 Kunavo 只需一個供應商項目 — Providers → Add provider，預設集 Other / custom API endpoint、端點 https://api.kunavo.com、你的 sk-kn- 金鑰 — 以及一個 Agent Config → Add profile → Claude Code 設定檔。逐欄說明（包括 Check Connection 和模型探索）位於 Claude Code Router integration page。本節其餘內容涵蓋該頁未說明的部分：認證、成本與失敗模式。

三種認證，以及 401 分別代表哪一種

這是最常見的情況：設定明明可運作，卻看起來像壞掉。CCR 有三個彼此獨立的密鑰，分別認證三個不同的跳轉：

連接埠配對也常讓人困惑：管理服務預設使用 127.0.0.1:3458，模型閘道使用 127.0.0.1:3456。將基礎 URL 指向 3458 會連到 UI，而不是閘道。（Docker 會刻意將兩者合併至同一個 Nginx 端點，因此 Docker 指示看起來不同。）可連線的 UI 不代表閘道正常運作：在閘道位址檢查 /health，並確認 Server 顯示 Running。

每個 tier 的對應才是重點

Claude Code 不會要求模型，而是要求一個 tier — 主迴圈需要 Sonnet 或 Opus，而背景工作（子代理程式、搜尋、摘要、對話標題）需要較小且快速的模型。Agent Config 中的 Claude Code 設定檔會將這些項目呈現為個別欄位：預設的 Model，以及可選的 Fable、Opus、Sonnet 和 Haiku 覆寫值，每個欄位都接受 Provider/model 值。留空某個 tier，Claude Code 就會自行選擇。

在複製他人的層級配置前，請先閱讀該表，因為最明顯的拆分是第一個槓桿：claude-sonnet-5在 Kunavo 上的成本比claude-opus-5-5低50%（$1.40 / $7.00，相較於$2.80 / ）。第二個槓桿是 Haiku 層級：其價格為$0.70 / $3.50，比 Sonnet 5 便宜2×，而且承載著您看不見的用量——每個子代理、每次檔案分類、每個產生的標題。claude-sonnet-4-6已不再是便宜的 Sonnet：其價格為$2.10 / $10.50，比 Sonnet 5 貴50%，因此上方的片段會設定ANTHROPIC_MODEL=claude-sonnet-5。

子代理程式路由 — tier 對應無法做到的事

Tier 覆寫會將所有子代理程式固定到同一個模型。CCR 可以做得更細：當 Claude Code 請求符合內建路由時，它會將可用模型清單注入 Agent / Task 工具說明，而 Claude Code 會在每個產生的代理程式提示前加上標籤，指出它想要的模型：

<CCR-SUBAGENT-MODEL>provider/model</CCR-SUBAGENT-MODEL>

CCR 會移除標籤並據此路由該次請求，因此搜尋子代理程式可以使用 Haiku，而審查子代理程式使用 Opus，依工作選擇，而非固定不變。這個切換很容易被忽略：除非模型頁面上至少有一個模型具有 Description，否則此機制會保持關閉。沒有說明時，CCR 不會注入任何內容，所有子代理程式都會悄悄退回設定檔預設值。請將說明寫成適合的工作 — Haiku 可寫「程式碼搜尋、檔案分流、低成本平行子代理程式」，Opus 可寫「架構分析、高風險審查」。運作時，請求日誌會將 builtin:claude-code-subagent 顯示為路由原因。

通訊協定選擇，以及它在快取方面的成本

CCR 會探測端點並選擇線路通訊協定。提供裸 origin https://api.kunavo.com 時，它會使用 Anthropic Messages；提供 https://api.kunavo.com/v1 時，它會使用 OpenAI-compatible 格式。兩種介面都使用相同的金鑰運作，你也可以在 Advanced settings 中覆寫自動偵測。

優先使用 Anthropic Messages 格式。它會讓 cache_control 保留在傳輸內容中，因此提示快取能傳達至模型，而快取輸入的計費為輸入費率的 10%（運作方式） — 對於每一步都重新傳送穩定前綴的代理程式迴圈而言，這是可取得的最大單項節省。必須坦白說明的是，路徑中的路由器仍會編輯請求：CCR 會移除 Claude Code 注入的計費標頭系統訊息，並在啟用子代理程式路由時將模型清單加入工具說明。兩者都位於你的快取斷點之前，因此每次該內容變更都會造成一次快取未命中，直到新的前綴預熱完成。之後會保持穩定 — 但這確實是選項 A 的快取效果略優於選項 B 的原因之一，此外選項 A 也較少需要維護。

備援：重試與故障轉移

在需要之前，值得先設定 Routing 頁面的 Default on failure。Retry 會在 408、409、429 和 5xx 時將請求重新傳送至相同模型，遵守 Retry-After；若未設定，則從 1s 開始以指數退避，最高上限為 30s。Fallback targets 會依序巡訪備援模型清單，並在任何 4xx 或 5xx 時觸發，因為找不到模型或供應商拒絕可能只影響目前的目標。個別規則可以覆寫全域設定。執行備援時，回應會帶有 x-ccr-fallback-attempts 和 x-ccr-fallback-model，讓你事後能辨識。

驗證它確實位於請求路徑中

從設定檔啟動 Claude Code，傳送一則訊息，然後在 CCR 中開啟 Request logs。該列會顯示 request model（Claude Code 要求的內容）、resolved provider 和 resolved model（請求前往的位置）— 這三項就是證據。在 CLI 中，/model 會列出 CCR 提供的模型。如果 Claude Code 有回覆但沒有日誌列，表示你是自行啟動 Claude Code，而不是透過 CCR 啟動；設定檔的範圍是 Only opened from CCR。

一次程式設計工作階段的成本

Claude Code 會在每一步重新傳送系統提示、對話和最新檔案內容，因此每 Token 的費率會快速累積。在 Kunavo 使用 claude-sonnet-5 的費率時：

在提示快取之前，這大約代表主力模型便宜 30%。完整費率請參閱 Claude API pricing guide，而 cost calculator 可使用你自己的 Token 數量。

哪些仍可運作 — 哪些不行

將 Claude Code 指向任何閘道都會改變幾項行為。在提交設定前，這份清單簡短但值得了解：

關於最後一列：Token 計數是 Anthropic 自身閘道規格標示為可選的唯一端點；缺少該端點時，Claude Code 會在本機估算內容使用量。Kunavo 目前不提供 /v1/messages/count_tokens，因此你的 /context 數值是估算值，而非精確計數。除了這個數值外，沒有任何功能會降級 — 自動壓縮和工作階段本身都不受影響。

疑難排解

基礎 URL 路徑

……以及路由器位於請求路徑中時

API 本身的逐一錯誤修正方式，請參閱 invalid API key 和 rate limit 疑難排解頁面。

常見問題