claude-code-router 是什麼、怎麼配:用官方 API 按任務分發多個模型的配置方法

claude-code-router(CCR)是社區開源的本機請求路由工具,可以把 Claude Code 的日常編碼、後台摘要、深度思考和超長上下文分別轉發給不同廠商的官方 API 或本機 Ollama。本文按開源倉庫文檔講清安裝、config.json 寫法與啟動步驟。

NNathaniel bigo··原創首發·AI 輔助撰寫
10 分鐘讀完
資料核對於 2026-11-18 · 依據官方文檔與公開資料整理 免費帳號 帳號

結論先說

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

claude-code-router 路由槽位對照

圖:本站根據 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 文件。

配置 claude-code-router 四步流程

圖:本站根據 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
  }
}

配置字段裏的幾個關鍵點:

  1. HOST 保持 127.0.0.1:只監聽本機迴環網卡,避免局域網其他裝置直接調用你的本地端口消耗 API 額度;
  2. Providers 數組:每一項定義一個官方上游提供方,name 是你在下方路由表裏引用的短名,transformer 用於修正不同官方接口在流式工具調用或推理字段上的格式差異;
  3. 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 槽位當主力編碼模型。

相關教學

參考資料

  • musistudio/claude-code-router 官方 GitHub 倉庫 — https://github.com/musistudio/claude-code-router
  • Claude Code 官方文檔:Model configuration — https://code.claude.com/docs/en/model-config

Nathaniel 的更多內容

  1. 01

    LangGraph 流式輸出(Streaming)詳解:逐字 Token 流、節點進度與自定義事件寫法

    多步智能體如果等全部節點跑完才返回,網頁前端就會白屏乾等十幾秒。本文按 LangGraph 官方文檔講清 updates、messages、custom 與 values 四種 stream_mode 的區別,以及組合訂閱逐字打字機輸出加工具內部實時進度的完整代碼。

    其他 AI 工具0
  2. 02

    LangGraph 持久化與長期記憶怎麼配:Checkpointer、Store 與 PostgreSQL 實戰

    在生產環境跑 LangGraph,單靠 InMemorySaver 一重啟就會丟失全部對話。本文按官方文檔講清線程內短期檢查點(Checkpointer)與跨線程長期記憶(Store)的分工,以及用 langgraph-checkpoint-postgres 對接 PostgreSQL 的完整步驟。

    其他 AI 工具0
  3. 03

    LangGraph 多智能體怎麼寫:Supervisor 主管包與 Subgraph 隔離子圖實戰

    在 LangGraph 裏把單個圖擴展成多智能體協作有兩條官方路線:快速原型用預置包 langgraph-supervisor,大型生產系統用原生子圖(Subgraph)嵌套。本文講清兩種寫法的完整代碼、私有狀態隔離防 Token 膨脹技巧以及檢查點傳播規則。

    其他 AI 工具0
  4. 04

    LangGraph 人工介入審批怎麼寫:interrupt 暫停圖運行與 Command 恢復實戰

    企業之所以選 LangGraph,很大程度看中它能安全掛起等待人工審批(Human-in-the-Loop)。本文按官方最新規範講清 interrupt() 動態暫停、Checkpointer 必備條件、Command(resume=...) 恢復執行,以及防止副作用重複運行的重入規則。

    其他 AI 工具0
  5. 05

    多 Agent 協作平台怎麼選:Dify、釦子(Coze)、n8n 與 LangGraph 多智能體機制對比

    搜「多agent協作平台」時,Dify、釦子、n8n 和 LangGraph 都宣稱支持多智能體,但底層的調度方式完全不同。本文跳過基礎安裝,專門從多 Agent 角色跳轉、子代理工具調用、上下文隔離與私有化部署四個維度幫你一次選準。

    其他 AI 工具0
  6. 06

    企業微信有官方 MCP 和 CLI 嗎:@wecom/cli 安裝初始化、長連接機器人與接入教學

    搜「企業 微信 有 mcp 嗎」不用再東拼西湊民間群機器人腳本了:企業微信官方已推出 @wecom/cli 命令行工具並內置 stdio 模式的 MCP Server。本文按官方開發者文檔講清安裝、智能機器人長連接初始化、業務命令與接入 Claude Code 步驟。

    Claude其他 AI 工具0

同產品的其他教學

  1. 01

    MCP 收費嗎:開源協議免費邊界、第三方 API 帳單與隱形 Token 開銷說明

    搜「mcp 收費 嗎」的人常擔心裝多了插件會被扣費。MCP(模型上下文協議)本身和官方 SDK 採用 MIT 協議完全免費;實際使用中可能產生費用的只有兩處:掛載過多工具佔用的大模型上下文 Token,以及部分外部商業數據源自帶的 API 套餐。

    Claude其他 AI 工具0
  2. 02

    MCP 協議最新版本更新了什麼:無狀態架構、OAuth 2.1、結構化輸出與異步 Tasks 詳解

    搜「mcp 重大 更新」「mcp 協議 更新」想補齊規範演進脈絡?本文對照 modelcontextprotocol.io 官方規範更新日誌,梳理從 Streamable HTTP 到無狀態優先架構、OAuth 2.1 資源伺服器、Elicitation 交互補參與異步 Tasks 擴展的核心變化。

    Claude其他 AI 工具0
  3. 03

    A2A 和 MCP 有什麼區別:工具連接協議與智能體通信協議的邊界和配合

    很多人問「有了 MCP 為什麼還要出 A2A,兩者是不是二選一的競爭關係」。兩份官方規範都明確寫明它們是上下互補關係:MCP 負責給單個智能體掛載工具與數據源,A2A 負責讓多個獨立黑盒智能體跨團隊、跨框架互相派單協作。

    Claude其他 AI 工具0
  4. 04

    LangGraph 怎麼使用 MCP:用 langchain-mcp-adapters 接入本地與遠程工具

    想讓自建的 LangGraph 狀態圖直接調用現成的 MCP 伺服器,官方標準方案是安裝 langchain-mcp-adapters 並使用 MultiServerMCPClient。本文講清 stdio 與 streamable_http 兩種配置寫法、異步圖運行及按節點分工具技巧。

    Claude其他 AI 工具0
  5. 05

    LangGraph 入門教學:Python 安裝、核心概念與跑通第一個狀態圖智能體

    面向搜「python 安裝 langgraph」和「langgraph 中文 文檔」的初學者:本文按 LangChain 官方最新 Graph API 規範,講清安裝步驟、State/Node/Edge 四大概念,並從零寫出第一個帶工具調用循環的 StateGraph。

    Claude其他 AI 工具0
  6. 06

    Claude Agent SDK 子代理怎麼寫:AgentDefinition 配置、權限收斂與 Python/TS 示例

    在 Python 或 TypeScript 裏用 Claude Agent SDK 編排多角色協作,核心是配置 ClaudeAgentOptions 的 agents 字段與 AgentDefinition。本文講清必開的 Agent 委派權限、工具收斂、模型分級與完整代碼示例。

    Claude0

0 條評論

登入 後參與評論

還沒有評論,來搶沙發~