Claude Code 是目前最好的 AI 編程 Agent，接國內模型本身不難——難的是多模型切換和場景路由。 claude-code-router 解決了這件事，但這篇文章記錄的是我安裝它踩的 5 個坑。

前言：為什么是 CCR？

Claude Code 接國內模型這件事，本身并不難——改下 ~/.claude/settings.json 里的 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN，指向 DeepSeek、GLM、Kimi 任意一家的 Anthropic 兼容端點就行。

但實際用起來，問題就來了：

• 想換個模型試試？ 打開配置文件、改字段、保存、重啟 Claude Code
• 長上下文場景想切到 Kimi、思考任務想切到 reasoner？ 一次只能配一個，切來切去
• 接的接口不完全兼容 Anthropic 協(xié)議？ 自己寫轉換邏輯去吧
• 同事推薦一個新模型想快速試？ 重新走一遍上面流程

Claude Code 是個非常優(yōu)秀的 Agent 框架，文件編輯、命令執(zhí)行、上下文管理、子任務編排、todo 跟蹤、hook 和 skill 體系都打磨得很好——但它的模型配置是"單掛"模式，沒法把多個模型同時掛上、按場景智能分發(fā)。

claude-code-router（下文簡稱 CCR）解決的就是這件事：

• 多模型聚合：一份配置里同時掛多家 provider，熱切換不需要重啟
• 場景智能分發(fā)：default / background / think / longContext 各路由到不同模型
• transformer 適配層：自動處理 DeepSeek、Gemini 等非完全兼容接口的協(xié)議轉換
• 會話內動態(tài)切換：在 Claude Code 里一行命令就能換模型

一句話：Claude Code 是引擎，CCR 是變速箱。

安裝過程

安裝過程有點折騰，差點把我勸退。CCR 的安裝倒是簡單，一行命令：

npm install -g @musistudio/claude-code-router

裝完驗證版本：

ccr -v
# claude-code-router version: 2.0.0

一切都好。然后我配了一下 C:/Users/**/.claude-code-router/config.json,這個目錄和配置文件需要手動創(chuàng)建

完事后我信心滿滿地運行：

ccr code

然后……沒有任何響應?；蛘邎箦e。

坑 1：Router 里的 Provider 名字寫錯了

這是我的 config.json 最初的 Router 部分：

"Router": {
  "default": "arkcodingplan,glm-5.1",     ← ? arkcodingplan 根本不存在
  "background": "arkcodingplan,glm-5.1",
  "think": "arkcodingplan,glm-5.1",
  "longContext": "arkcodingplan,glm-5.1",
}

而我的 Providers 里定義的是：

"Providers": [
  { "name": "deepseek", ... },
  { "name": "volcengine", ... }
]

問題很明顯：我引用了 arkcodingplan,glm-5.1 這個組合，但 Provider 名稱是 volcengine，不是 arkcodingplan。

CCR 啟動日志里安靜地打印了 volcengine provider registered，但 Router 根本不知道 Volcengine 是誰——它只知道自己收到指令去找一個叫 arkcodingplan 的人，翻遍通訊錄都找不到。

正確寫法："provider名,模型名"，provider 名必須和上面 Providers 數(shù)組里 name 字段完全一致。

"Router": {
  "default": "volcengine,glm-5.1"
}

坑 2：API Base URL 路徑不完整

火山引擎方舟（volcengine ARK）有 Coding Plan 包月套餐，它的完整 API 地址是：

https://ark.cn-beijing.volces.com/api/coding/v1/chat/completions

我最初只寫到了 /api/coding：

"api_base_url": "https://ark.cn-beijing.volces.com/api/coding"   ← ? 缺路徑

這個錯誤很隱蔽——CCR 啟動時不報錯，只有實際請求來了才會拋出 404 或路由錯誤。直到我用 curl 測試才抓到異常。

坑 3：國內服務配了代理，但代理沒開

配置文件里有一行：

"PROXY_URL": "http://127.0.0.1:7890"

這本來是給海外模型（如 OpenRouter、Gemini）準備的。但問題是：

1. 火山引擎是國內服務，根本不需要代理
2. 我的 Clash 軟件沒啟動，7890 端口沒人監(jiān)聽
3. CCR 強制所有請求走這個代理端口

結果是每次請求都報 fetch failed，沒有任何有用信息。

# 驗證代理狀態(tài)
curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:7890
# 輸出 000 → 連不上

解決方案：國內服務直接清空代理。

"PROXY_URL": ""    ← ?

需要再次用代理時再填回來，并確保代理軟件正在運行。

坑 4：settings.json 和 CCR 搶方向盤（最容易忽視）

這是最隱蔽的坑，也是最大的問題。

其實 CCR 裝完、config.json 修完、代理清掉以后，ccr restart 服務已經(jīng)能正常啟動了。但詭異的是我運行 ccr code 之后，Claude Code 界面里的 /model 命令只能看到 glm-5.1，無法切換模型。

查了一圈發(fā)現(xiàn)，~/.claude/settings.json 里有這樣一段環(huán)境變量覆蓋：

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "ark-xxx",
    "ANTHROPIC_BASE_URL": "https://ark.cn-beijing.volces.com/api/coding",
    "ANTHROPIC_MODEL": "glm-5.1"
  },
  "model": "glm-5.1"
}

這意味著：

• ANTHROPIC_BASE_URL 直接指向火山引擎 → 完全繞過了 CCR
• ANTHROPIC_MODEL 和頂層 model 鎖死了模型 → /model 命令無法切換

CCR 的原理是在本地啟動一個代理服務器，運行 ccr code 時會自動設置環(huán)境變量讓 Claude Code 連到本地代理。但如果 settings.json 里的 env 配置優(yōu)先級更高，就會覆蓋 CCR 注入的值。

解決方案：刪除 settings.json 里與 ANTHROPIC 相關的 env 變量和 model 字段，讓 CCR 接管路由控制權。

坑 5：Warp 終端里無法添加文件、代碼片段或圖片到上下文

CCR 跑通之后，我習慣性地用 Warp 終端打開 ccr code，準備像以前一樣用右鍵"Attach as context"把代碼文件或截圖塞進對話框——結果發(fā)現(xiàn)功能倒是有，但是點全部無效，點了沒一點反應。

原因：Warp 的上下文注入功能（Attach code / Images as context）是基于進程指紋識別實現(xiàn)的。Warp 檢測到當前運行的是 claude 命令時，才會激活 Agent 增強型輸入框和上下文綁定面板。而你執(zhí)行的是 ccr code，Warp 只看到一個叫 ccr 的普通 Shell 命令，不會把它當成官方 AI Agent，于是拒絕激活上下文注入通道。

解法 A：用 Alias 欺騙 Warp（最推薦）

核心思路是把 ccr code 偽裝成 claude 命令，讓 Warp 正確識別。

Windows（PowerShell）：

# 打開 PowerShell 配置文件
notepad $PROFILE

# 在記事本最后一中添加：
function claude { ccr code @args }

# 保存后刷新配置
& $PROFILE

macOS / Linux（Zsh/Bash）：

# 編輯 shell 配置
nano ~/.zshrc

# 添加：
alias claude="ccr code"

# 保存后刷新
source ~/.zshrc

這些操作完了后，要把當前Warp終端關閉，在當前目錄下重新打開，之后在 Warp 中直接輸入 claude 啟動，Warp 就能識別到 claude 關鍵字，解鎖上下文注入功能。

解法 B：Ctrl + G 喚起富文本輸入框

如果 Alias 方案沒生效，可以在 ccr code 會話中按 Ctrl + G，強制拉起 Warp 的 Rich Input Editor（多行富文本輸入框），在里面點擊附件圖標添加代碼或圖片。

解法 C：用@鍵盤流注入文件上下文

如果 UI 級綁定徹底被 CCR 阻斷，可以放棄鼠標流，改用鍵盤流：在輸入框中鍵入 @，Warp 會基于當前 Git 倉庫彈出文件/目錄的快速搜索列表，選擇后以文本路徑方式注入上下文——這種方式 CCR 完全能理解。

解法B/C沒試過，我用解法A就解決了我的問題，Warp的絲滑體驗又回來了！

最終配置（可以直接用）

~/.claude-code-router/config.json

{
  "LOG": true,
  "LOG_LEVEL": "debug",
  "HOST": "127.0.0.1",
  "PORT": 3456,
  "APIKEY": "",
  "PROXY_URL": "",
  "Providers": [
    {
      "name": "deepseek",
      "api_base_url": "https://api.deepseek.com/chat/completions",
      "api_key": "sk-你的DeepSeekKey",
      "models": [
        "deepseek-chat",
        "deepseek-reasoner"
      ],
      "transformer": { "use": ["deepseek"] }
    },
    {
      "name": "volcengine",
      "api_base_url": "https://ark.cn-beijing.volces.com/api/coding/v1/chat/completions",
      "api_key": "ark-你的火山Key",
      "models": [
        "glm-5.1",
        "kimi-k2.6",
        "minimax-m3"
      ]
    }
  ],
  "Router": {
    "default": "volcengine,glm-5.1",
    "background": "volcengine,glm-5.1",
    "think": "volcengine,glm-5.1",
    "longContext": "volcengine,kimi-k2.6",
    "longContextThreshold": 60000,
    "webSearch": "",
    "image": "volcengine,kimi-k2.6"
  }
}

~/.claude/settings.json

{
  "theme": "dark",
  "enabledPlugins": {
    "understand-anything@understand-anything": true
  }
}

關鍵原則就是，settings.json 是 Claude Code 自身的配置，不要在里面寫什么 ANTHROPIC_* 環(huán)境變量。讓 CCR 來管路由，讓 settings.json 保持干凈。

最終效果

一切就緒后，實際效果是這樣的：

Claude Code 以為自己用的是 Opus 4.8，但每一行代碼、每一句回答都來自你配置的第三方模型。

這感覺就像給一輛特斯拉換上了比亞迪的電池——儀表盤依然顯示"滿電"，但真正的動力來源早已不是原廠貨。

切換模型也有三種方式（按推薦度排序）：

1. Claude Code 內直接輸入：/model volcengine,kimi-k2.6
2. CCR 交互式菜單：另開終端運行 ccr model，選擇模型后重啟，注意要在warp中操作
3. 編輯配置文件：改 Router.default 字段后 ccr restart

總結：排錯心法

爬完這幾 個坑，有必要理解一下從 CCR調用大模型 的分層架構或者說工作流：

終端（Warp）→ Claude Code → settings.json 的 env → CCR 本地代理 → Provider API

每一層都可能配置沖突或覆蓋，排錯的關鍵是逐層隔離驗證：

1. 檢查終端是否識別 Agent 進程（Warp 用戶注意進程名匹配）
2. 檢查 CCR 是否啟動：ccr status
3. 檢查日志有沒有 proxy 注冊：看 ~/.claude-code-router/logs/
4. 用 curl 直接測本地代理：curl http://127.0.0.1:3456/v1/messages
5. 檢查 settings.json 有沒有"越權"的 env 變量
6. 確認 Provider URL 的完整路徑
7. 確認 Router 里的 provider 名和上面定義的一致

如果你也在折騰 AI 工具的配置，歡迎轉發(fā)給需要的人。踩過的坑踩平了，后人就少摔一跤。

到此這篇關于詳解Claude Code Router 接入過程的爬坑記錄的文章就介紹到這了,更多相關Claude Code Router 接入內容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關文章，希望大家以后多多支持腳本之家！

最新評論