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

前言：為什么是 CCR？

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

但實(shí)際用起來(lái)，問(wèn)題就來(lái)了：

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

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

claude-code-router（下文簡(jiǎn)稱(chēng) CCR）解決的就是這件事：

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

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

安裝過(guò)程

安裝過(guò)程有點(diǎn)折騰，差點(diǎn)把我勸退。CCR 的安裝倒是簡(jiǎn)單，一行命令：

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

裝完驗(yàn)證版本：

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

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

完事后我信心滿(mǎn)滿(mǎn)地運(yùn)行：

ccr code

然后……沒(méi)有任何響應(yīng)?；蛘邎?bào)錯(cuò)。

坑 1：Router 里的 Provider 名字寫(xiě)錯(cuò)了

這是我的 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", ... }
]

問(wèn)題很明顯：我引用了 arkcodingplan,glm-5.1 這個(gè)組合，但 Provider 名稱(chēng)是 volcengine，不是 arkcodingplan。

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

正確寫(xiě)法："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

我最初只寫(xiě)到了 /api/coding：

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

這個(gè)錯(cuò)誤很隱蔽——CCR 啟動(dòng)時(shí)不報(bào)錯(cuò)，只有實(shí)際請(qǐng)求來(lái)了才會(huì)拋出 404 或路由錯(cuò)誤。直到我用 curl 測(cè)試才抓到異常。

坑 3：國(guó)內(nèi)服務(wù)配了代理，但代理沒(méi)開(kāi)

配置文件里有一行：

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

這本來(lái)是給海外模型（如 OpenRouter、Gemini）準(zhǔn)備的。但問(wèn)題是：

1. 火山引擎是國(guó)內(nèi)服務(wù)，根本不需要代理
2. 我的 Clash 軟件沒(méi)啟動(dòng)，7890 端口沒(méi)人監(jiān)聽(tīng)
3. CCR 強(qiáng)制所有請(qǐng)求走這個(gè)代理端口

結(jié)果是每次請(qǐng)求都報(bào) fetch failed，沒(méi)有任何有用信息。

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

解決方案：國(guó)內(nèi)服務(wù)直接清空代理。

"PROXY_URL": ""    ← ?

需要再次用代理時(shí)再填回來(lái)，并確保代理軟件正在運(yùn)行。

坑 4：settings.json 和 CCR 搶方向盤(pán)（最容易忽視）

這是最隱蔽的坑，也是最大的問(wèn)題。

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

查了一圈發(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 直接指向火山引擎 → 完全繞過(guò)了 CCR
• ANTHROPIC_MODEL 和頂層 model 鎖死了模型 → /model 命令無(wú)法切換

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

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

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

CCR 跑通之后，我習(xí)慣性地用 Warp 終端打開(kāi) ccr code，準(zhǔn)備像以前一樣用右鍵"Attach as context"把代碼文件或截圖塞進(jìn)對(duì)話框——結(jié)果發(fā)現(xiàn)功能倒是有，但是點(diǎn)全部無(wú)效，點(diǎn)了沒(méi)一點(diǎn)反應(yīng)。

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

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

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

Windows（PowerShell）：

# 打開(kāi) PowerShell 配置文件
notepad $PROFILE

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

# 保存后刷新配置
& $PROFILE

macOS / Linux（Zsh/Bash）：

# 編輯 shell 配置
nano ~/.zshrc

# 添加：
alias claude="ccr code"

# 保存后刷新
source ~/.zshrc

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

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

如果 Alias 方案沒(méi)生效，可以在 ccr code 會(huì)話中按 Ctrl + G，強(qiáng)制拉起 Warp 的 Rich Input Editor（多行富文本輸入框），在里面點(diǎn)擊附件圖標(biāo)添加代碼或圖片。

解法 C：用@鍵盤(pán)流注入文件上下文

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

解法B/C沒(méi)試過(guò)，我用解法A就解決了我的問(wèn)題，Warp的絲滑體驗(yàn)又回來(lái)了！

最終配置（可以直接用）

~/.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
  }
}

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

最終效果

一切就緒后，實(shí)際效果是這樣的：

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

這感覺(jué)就像給一輛特斯拉換上了比亞迪的電池——儀表盤(pán)依然顯示"滿(mǎn)電"，但真正的動(dòng)力來(lái)源早已不是原廠貨。

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

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

總結(jié)：排錯(cuò)心法

爬完這幾 個(gè)坑，有必要理解一下從 CCR調(diào)用大模型 的分層架構(gòu)或者說(shuō)工作流：

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

每一層都可能配置沖突或覆蓋，排錯(cuò)的關(guān)鍵是逐層隔離驗(yàn)證：

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

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

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

最新評(píng)論