結論先說
claude-code-router(簡稱 CCR)是一個跑在你本機(預設127.0.0.1:3456)的開源協議轉換與路由網關,不是 Anthropic 官方組件。- 它的核心作用是「按請求特徵分流」:把 Claude Code 發出的請求識別為預設任務(
default)、後台輕量任務(background)、深度推理(think)和超長上下文(longContext),分別轉發給你配置的不同上游接口。 - 只建議填寫各模型廠商的官方直連 API 或本機 Ollama 地址,並用
${環境變量名}引用密鑰,避免明文密碼落盤或把倉庫代碼發往來路不明的非官方服務。 - 啟動時用
ccr code代替直接敲claude,工具會自動為當前子進程注入本機轉發地址,不需要手工改動全局 Claude Code 登入配置。

圖:本站根據 musistudio/claude-code-router 官方倉庫文檔 整理的示意圖
本文根據開源項目musistudio/claude-code-router官方倉庫說明整理,核對日期 2026-11-18。本文只介紹對接各模型廠商官方 API 與本機離線模型的配置方法。配圖為本站整理的示意圖,不是介面截圖。本站(bigolab.com)不是 Anthropic 官方網站。
適用於誰
- 搜「claude code router 配置 多 個 模型」「claude-code-router 怎麼用」的人;
- 手裏有 DeepSeek、Google Gemini 等多家廠商的官方開發者 API Key,或本機裝了 Ollama,想在 Claude Code 終端交互介面裏按任務分工調用的開發者;
- 想把後台生成標題、超長文件閱讀和主力改碼拆給不同接口處理的人。
如果你使用的都是 Claude 自家模型,優先用官方原生的 opusplan、/advisor 和子代理分模型機制就夠了,不需要額外部署路由層,具體見 /guides/claude-code-multi-model-opusplan-advisor-subagents。
一、工作原理與適用邊界
Claude Code 客戶端本身發送的是 Anthropic Messages API 格式的請求。當你想接入其他廠商的官方接口(大多采用 OpenAI 兼容格式或各自原生格式,例如 Google Gemini API)時,協議格式並不互通。
claude-code-router 在本機起一個本地 HTTP 服務,做兩件事:
- 協議轉換(Transformer):把 Claude Code 發出的請求和工具調用結構轉換成目標廠商官方 API 接受的格式,再把流式響應轉回 Claude Code 能識別的格式;
- 分槽位路由(Router):根據請求裏的模型標記、是否開啟思考模式以及上下文 Token 長度,自動挑選你在
Router字段裏指定的目標模型。
在動手配置前也要清楚它的邊界:第三方模型在工具調用穩定性、複雜補丁格式遵循度上可能不如原生 Claude 模型;如果你主要追求開箱即用的編碼質素,直接使用官方訂閱(可參考 /chongzhi/claude-code 的訂閱說明)或官方直連 API Key(見 /guides/claude-code-use-api-key-instead-of-login)會更省心。
二、安裝與配置文件位置
先確保本機已經安裝 Node.js 和官方 @anthropic-ai/claude-code,然後通過 npm 全局安裝路由工具:
bash
npm install -g @musistudio/claude-code-router
安裝完成後,主配置文件預設存放在用戶目錄下的 ~/.claude-code-router/config.json。如果你更習慣圖形化表單,也可以在終端運行 ccr ui 打開本地管理面板填寫並儲存,底層同樣會寫回這份 JSON 文件。

圖:本站根據 musistudio/claude-code-router 官方倉庫文檔 整理的示意圖
三、config.json 配置示例(僅使用官方接口與本機模型)
下面是一個只對接各廠商官方開發者接口與本機 Ollama 的典型結構示例。請先把各家的密鑰寫進你自己的系統環境變量(如 DEEPSEEK_API_KEY、GEMINI_API_KEY),在配置文件裏用插值語法引用:
json
{
"HOST": "127.0.0.1",
"PORT": 3456,
"LOG": true,
"API_TIMEOUT_MS": 600000,
"Providers": [
{
"name": "deepseek",
"api_base_url": "https://api.deepseek.com/chat/completions",
"api_key": "${DEEPSEEK_API_KEY}",
"models": ["deepseek-chat", "deepseek-reasoner"],
"transformer": { "use": ["deepseek"] }
},
{
"name": "gemini",
"api_base_url": "https://generativelanguage.googleapis.com/v1beta/models/",
"api_key": "${GEMINI_API_KEY}",
"models": ["gemini-2.5-pro", "gemini-2.5-flash"],
"transformer": { "use": ["gemini"] }
},
{
"name": "ollama",
"api_base_url": "http://127.0.0.1:11434/v1/chat/completions",
"api_key": "ollama",
"models": ["qwen2.5-coder:latest"]
}
],
"Router": {
"default": "deepseek,deepseek-chat",
"background": "ollama,qwen2.5-coder:latest",
"think": "deepseek,deepseek-reasoner",
"longContext": "gemini,gemini-2.5-pro",
"longContextThreshold": 60000
}
}
配置字段裏的幾個關鍵點:
HOST保持127.0.0.1:只監聽本機迴環網卡,避免局域網其他裝置直接調用你的本地端口消耗 API 額度;Providers數組:每一項定義一個官方上游提供方,name是你在下方路由表裏引用的短名,transformer用於修正不同官方接口在流式工具調用或推理字段上的格式差異;Router路由表:值統一採用"提供方name,模型名"的逗號分隔寫法。其中longContextThreshold設為60000表示當單次上下文超過約 6 萬 Token 時,自動切給longContext綁定的長窗口模型處理。
四、啟動會話與日常切換
儲存好 config.json 後,進入你的代碼倉庫目錄,用下面這條命令啟動:
bash
ccr code
如果修改了 config.json 裏的提供方或閾值,先運行 ccr restart 重啟後台本地路由服務使其生效。在會話進行中,如果你想臨時把當前對話切到你在 Providers 裏登記過的另一個模型,也可以按倉庫文檔支持的 /model 提供方名,模型名 語法手動指定;關於原生 /model 命令的預設行為可對照 /guides/claude-code-switch-model。
常見問題
Q:啟動 ccr code 後報 401 或環境變量讀不到怎麼辦?
檢查你在終端當前 Shell 會話裏是否真的導出了對應的環境變量(例如 echo $DEEPSEEK_API_KEY),以及環境變量名大小寫是否與 config.json 裏的 ${...} 完全一致。不要把 ~/.claude-code-router/config.json 提交進公開代碼倉庫。
Q:用了 claude-code-router 之後,平時直接敲 claude 還會走本地路由嗎?
只要你沒有在 ~/.claude/settings.json(見 /guides/claude-code-settings-json)或系統全局環境變量裏永久寫死 ANTHROPIC_BASE_URL,單獨運行 claude 依然走官方原有通道,只有運行 ccr code 啟動的那次終端會話才會經過本地路由。
Q:為什麼有的本地小模型接進去後不會改文件、只會打印代碼塊?
Claude Code 高度依賴模型的結構化工具調用(Tool Use)能力來執行 Read、Edit 和 Bash。參數量過小或不支持工具調用的模型無法穩定生成符合格式的參數,只適合放在 background 槽位做摘要類輔助工作,不適合放在 default 槽位當主力編碼模型。
相關教學
- /guides/claude-code-multi-model-opusplan-advisor-subagents:Claude Code 原生多模型配置(opusplan、顧問與子代理)
- /guides/claude-code-use-api-key-instead-of-login:Claude Code 免登入直接配置官方 API Key
- /guides/claude-code-switch-model:Claude Code
/model模型切換與推理強度詳解 - /guides/claude-code-settings-json:Claude Code
settings.json配置指南
參考資料
musistudio/claude-code-router官方 GitHub 倉庫 — https://github.com/musistudio/claude-code-router- Claude Code 官方文檔:Model configuration — https://code.claude.com/docs/en/model-config
0 條評論
還沒有評論,來搶沙發~