1. Claude code router 配置 gemini 报错到底卡在哪Claude Code Router下称 CCR本质是一个本地反向代理Claude Code 以为自己在跟 Anthropic 官方接口说话实际请求被 CCR 拦下来按你写的路由规则转发到别的模型供应商。所以当你把 provider 指向 gemini 时链路变成Claude Code → 127.0.0.1:3456CCR→ Gemini endpoint。这条链上任何一环的 endpoint 或鉴权写错报错都会以「Claude Code 报错」的形式冒出来很容易误判成 Claude Code 本身坏了。我见过最多的三类现象一是401 Unauthorized通常 Key 没被正确带上或者 endpoint 路径拼错导致请求打到了不存在的鉴权入口二是local proxy failed/Service not runningCCR 进程根本没起来或者端口被占三是429 RESOURCE_EXHAUSTED这个最容易被误解——它不一定是「额度用完」Gemini 的免费层对并发和每分钟请求数卡得很死CCR 默认会重试重试叠加就把配额瞬间打满。这篇排查清单就是围绕「endpoint 与鉴权」两个维度展开的。适合已经在用 Claude Code、想通过 CCR 把请求分流到 gemini、但被 401 或 local proxy failed 卡住的人。下面每一步都给可复制的配置片段和验证命令你可以边看边对照自己的~/.claude-code-router/config.json。核心检索词先记住Claude code router 配置 gemini 报错绝大多数不是模型问题而是通道配置和模型映射没对齐。2. 接入前把 TaoToken 的 Base URL 和 Key 准备好在动 CCR 配置之前先把「上游通道」这件事定死。CCR 支持多种 provider 类型但无论哪种你都需要三件套Base URL、API Key、Model ID。这三者必须来自同一个来源混搭是 401 的高发原因——比如 Key 是 A 平台的Base URL 却填了 B 平台的地址服务端自然认不出来。我现在的做法是统一走 TaoToken 的 API 入口它的 Base URL 是https://taotoken.net/api注意这里不要加任何多余路径后缀CCR 会自己在后面拼/v1/messages或/v1/chat/completions。Key 在控制台的 API Keys 页面生成生成后只显示一次建议直接存进环境变量而不是硬编码进 config.json避免以后提交配置时泄露。具体操作登录后进入控制台找到 API Keys 菜单新建一个 Key 并复制。然后在你本机终端里验证这个 Key 是否可用先不经过 CCR直接打一次接口把变量隔离出来export TAOTOKEN_API_KEYsk-你的key curl -s https://taotoken.net/api/v1/models \ -H Authorization: Bearer $TAOTOKEN_API_KEY | head -c 500如果这一步返回模型列表说明 Key 和 Base URL 是通的问题一定出在 CCR 配置层如果这一步就 401那先别碰 CCR去检查 Key 是否复制完整、有没有多余空格。这个「先绕开 CCR 验证上游」的习惯能帮你省掉一大半排查时间。模型对话入口可以用来快速确认某个模型 ID 是否可用接入文档里对每个端点的路径和鉴权头有完整说明配置前扫一眼能避免路径拼错。3. 可复制的 CCR 配置片段与逐项对照CCR 的配置文件默认在~/.claude-code-router/config.json。下面这份是我实测能跑通的片段重点看Providers数组里的api_base_url、api_key、models三个字段以及Router里把哪个场景映射到哪个模型{ LOG: true, API_TIMEOUT_MS: 600000, Providers: [ { name: taotoken, api_base_url: https://taotoken.net/api/v1/chat/completions, api_key: sk-你的key, models: [ gemini-2.5-pro, gemini-2.5-flash ] } ], Router: { default: taotoken,gemini-2.5-pro, background: taotoken,gemini-2.5-flash, think: taotoken,gemini-2.5-pro, longContext: taotoken,gemini-2.5-pro } }逐项对照这里有几个坑必须点出来。第一api_base_url的写法在不同 CCR 版本里要求不一样有的版本要求写到/v1/chat/completions全路径有的只写到/api由 CCR 补全。如果你填了全路径却报 404就退回到https://taotoken.net/api再试反之如果报「no such endpoint」就补全路径。第二Router里的值格式是provider名,模型ID中间是英文逗号不能有空格写成taotoken, gemini-2.5-pro逗号后带空格在某些版本会解析失败直接导致模型映射为空进而报 401 或 provider 找不到。第三模型 ID 必须和上游实际支持的名称完全一致。Gemini 系列在 TaoToken 上的 ID 形如gemini-2.5-pro不要写成gemini-pro或带日期后缀的旧名。你可以用第 2 节的/v1/models接口把可用 ID 列出来复制粘贴而不是手敲。第四如果你之前配过别的 provider比如 deepseek确认Router里没有残留指向旧 provider 的映射否则 Claude Code 发起的请求可能被路由到一个已经失效的通道表现就是间歇性 401。改完配置后CCR 需要重启才能生效。用ccr restart或先ccr stop再ccr start。启动日志里会打印加载了哪些 provider如果看到你的 provider 名和模型列表说明配置被正确解析了。4. 验证请求是否真的打通了配置改完不代表通了必须做分层验证。第一层确认 CCR 服务在跑并且端口在听ccr status lsof -i :3456 | head -5ccr status显示 runninglsof能看到 node 进程占用 3456说明本地代理层没问题。如果这里就失败直接跳到第 5 节的 local proxy failed 排查。第二层绕过 Claude Code直接对 CCR 发一个请求看它能不能正确转发到上游curl -s http://127.0.0.1:3456/v1/messages \ -H Content-Type: application/json \ -H x-api-key: any \ -d { model: gemini-2.5-flash, max_tokens: 64, messages: [{role: user, content: say hi}] } | head -c 800注意这里x-api-key随便填因为鉴权是 CCR 用你 config 里的 Key 去跟上游换的。如果返回正常内容说明 CCR → 上游这条链路通了问题只可能在 Claude Code 的启动参数上。如果返回 401说明 CCR 转发时没带上游 Key回去检查 config.json 里api_key字段是否被正确读取可以开LOG: true看日志里实际用的 Key 前缀。第三层启动 Claude Code 并确认它指向 CCR。正常启动后界面里会显示API Base URL: http://127.0.0.1:3456看到这行才说明 Claude Code 走的是 CCR 而不是官方接口。然后发一句hello观察返回。如果这一步报 429先别急着换 Key把 CCR 的重试次数调低、并发降下来Gemini 免费层对 RPM 很敏感连续重试会自己把自己限流。5. 常见报错逐条排查401 Unauthorized九成是 Key 或 endpoint 不匹配。排查顺序先用第 2 节的 curl 直连上游确认 Key 有效再确认 config.json 里api_key没有多余引号嵌套JSON 里字符串就是字符串别写成\sk-xxx\最后确认api_base_url和 Key 属于同一平台。如果 Key 是从环境变量读的确认 CCR 启动时那个变量确实存在ccr作为子进程不一定继承你 shell 里 export 的变量必要时写进 config 或用ccr start前手动 export。local proxy failed / Service not runningCCR 进程没起来或端口冲突。先ccr status没跑就ccr start并看输出。如果提示端口被占lsof -i :3456找到占用进程 kill 掉或改 CCR 的监听端口。Mac 上还常见一种情况pnpm 全局安装的 CCR 在切换 node 版本后路径失效重新pnpm add -g musistudio/claude-code-router即可。429 RESOURCE_EXHAUSTED这是上游配额或限流不是配置错。Gemini 免费层 RPM 很低CCR 默认重试 10 次会把配额瞬间打满。处理办法把API_TIMEOUT_MS保留但在 Router 里把background这类高频场景换成更轻的模型或者直接降低并发。如果持续 429说明该 Key 的额度确实用尽换 Key 或升级配额。reading choices of undefined这是响应体结构和 CCR 预期不符。通常发生在api_base_url指向了一个返回格式不是 OpenAI 兼容的端点。确认你填的是/v1/chat/completions这类兼容路径而不是原生 Gemini 的generateContent路径。CCR 按 OpenAI 格式解析响应路径错了就拿不到choices字段。OAuth / auth.json 相关报错如果你同时装了 Codex 或其它用auth.json的工具确认它们没有互相覆盖凭证文件。CCR 本身不用 OAuth但 Claude Code 的登录态和 CCR 的 Key 是两套东西别把 Claude Code 的 OAuth token 填进 CCR 的api_key。6. 把通道固定下来少走回头路排查完这一轮我的建议是把「上游三件套」写成一个独立的环境文件CCR 配置里只引用不硬编码。这样以后换模型或换 Key只改一处。长期跑编码任务的话用 Coding Plan 把常用模型和额度固定下来比每次临时找 Key 稳定得多。需要新建或轮换 Key 时直接去 API Keys 页面操作配合接入文档里的路径说明基本不会再踩 endpoint 拼错的坑。整套流程跑顺之后Claude Code 前端体验不变后端走哪条通道完全由你控制这才是 CCR 真正的价值。
1. Claude code router 配置 gemini 报错到底卡在哪Claude Code Router下称 CCR本质是一个本地反向代理Claude Code 以为自己在跟 Anthropic 官方接口说话实际请求被 CCR 拦下来按你写的路由规则转发到别的模型供应商。所以当你把 provider 指向 gemini 时链路变成Claude Code → 127.0.0.1:3456CCR→ Gemini endpoint。这条链上任何一环的 endpoint 或鉴权写错报错都会以「Claude Code 报错」的形式冒出来很容易误判成 Claude Code 本身坏了。我见过最多的三类现象一是401 Unauthorized通常 Key 没被正确带上或者 endpoint 路径拼错导致请求打到了不存在的鉴权入口二是local proxy failed/Service not runningCCR 进程根本没起来或者端口被占三是429 RESOURCE_EXHAUSTED这个最容易被误解——它不一定是「额度用完」Gemini 的免费层对并发和每分钟请求数卡得很死CCR 默认会重试重试叠加就把配额瞬间打满。这篇排查清单就是围绕「endpoint 与鉴权」两个维度展开的。适合已经在用 Claude Code、想通过 CCR 把请求分流到 gemini、但被 401 或 local proxy failed 卡住的人。下面每一步都给可复制的配置片段和验证命令你可以边看边对照自己的~/.claude-code-router/config.json。核心检索词先记住Claude code router 配置 gemini 报错绝大多数不是模型问题而是通道配置和模型映射没对齐。2. 接入前把 TaoToken 的 Base URL 和 Key 准备好在动 CCR 配置之前先把「上游通道」这件事定死。CCR 支持多种 provider 类型但无论哪种你都需要三件套Base URL、API Key、Model ID。这三者必须来自同一个来源混搭是 401 的高发原因——比如 Key 是 A 平台的Base URL 却填了 B 平台的地址服务端自然认不出来。我现在的做法是统一走 TaoToken 的 API 入口它的 Base URL 是https://taotoken.net/api注意这里不要加任何多余路径后缀CCR 会自己在后面拼/v1/messages或/v1/chat/completions。Key 在控制台的 API Keys 页面生成生成后只显示一次建议直接存进环境变量而不是硬编码进 config.json避免以后提交配置时泄露。具体操作登录后进入控制台找到 API Keys 菜单新建一个 Key 并复制。然后在你本机终端里验证这个 Key 是否可用先不经过 CCR直接打一次接口把变量隔离出来export TAOTOKEN_API_KEYsk-你的key curl -s https://taotoken.net/api/v1/models \ -H Authorization: Bearer $TAOTOKEN_API_KEY | head -c 500如果这一步返回模型列表说明 Key 和 Base URL 是通的问题一定出在 CCR 配置层如果这一步就 401那先别碰 CCR去检查 Key 是否复制完整、有没有多余空格。这个「先绕开 CCR 验证上游」的习惯能帮你省掉一大半排查时间。模型对话入口可以用来快速确认某个模型 ID 是否可用接入文档里对每个端点的路径和鉴权头有完整说明配置前扫一眼能避免路径拼错。3. 可复制的 CCR 配置片段与逐项对照CCR 的配置文件默认在~/.claude-code-router/config.json。下面这份是我实测能跑通的片段重点看Providers数组里的api_base_url、api_key、models三个字段以及Router里把哪个场景映射到哪个模型{ LOG: true, API_TIMEOUT_MS: 600000, Providers: [ { name: taotoken, api_base_url: https://taotoken.net/api/v1/chat/completions, api_key: sk-你的key, models: [ gemini-2.5-pro, gemini-2.5-flash ] } ], Router: { default: taotoken,gemini-2.5-pro, background: taotoken,gemini-2.5-flash, think: taotoken,gemini-2.5-pro, longContext: taotoken,gemini-2.5-pro } }逐项对照这里有几个坑必须点出来。第一api_base_url的写法在不同 CCR 版本里要求不一样有的版本要求写到/v1/chat/completions全路径有的只写到/api由 CCR 补全。如果你填了全路径却报 404就退回到https://taotoken.net/api再试反之如果报「no such endpoint」就补全路径。第二Router里的值格式是provider名,模型ID中间是英文逗号不能有空格写成taotoken, gemini-2.5-pro逗号后带空格在某些版本会解析失败直接导致模型映射为空进而报 401 或 provider 找不到。第三模型 ID 必须和上游实际支持的名称完全一致。Gemini 系列在 TaoToken 上的 ID 形如gemini-2.5-pro不要写成gemini-pro或带日期后缀的旧名。你可以用第 2 节的/v1/models接口把可用 ID 列出来复制粘贴而不是手敲。第四如果你之前配过别的 provider比如 deepseek确认Router里没有残留指向旧 provider 的映射否则 Claude Code 发起的请求可能被路由到一个已经失效的通道表现就是间歇性 401。改完配置后CCR 需要重启才能生效。用ccr restart或先ccr stop再ccr start。启动日志里会打印加载了哪些 provider如果看到你的 provider 名和模型列表说明配置被正确解析了。4. 验证请求是否真的打通了配置改完不代表通了必须做分层验证。第一层确认 CCR 服务在跑并且端口在听ccr status lsof -i :3456 | head -5ccr status显示 runninglsof能看到 node 进程占用 3456说明本地代理层没问题。如果这里就失败直接跳到第 5 节的 local proxy failed 排查。第二层绕过 Claude Code直接对 CCR 发一个请求看它能不能正确转发到上游curl -s http://127.0.0.1:3456/v1/messages \ -H Content-Type: application/json \ -H x-api-key: any \ -d { model: gemini-2.5-flash, max_tokens: 64, messages: [{role: user, content: say hi}] } | head -c 800注意这里x-api-key随便填因为鉴权是 CCR 用你 config 里的 Key 去跟上游换的。如果返回正常内容说明 CCR → 上游这条链路通了问题只可能在 Claude Code 的启动参数上。如果返回 401说明 CCR 转发时没带上游 Key回去检查 config.json 里api_key字段是否被正确读取可以开LOG: true看日志里实际用的 Key 前缀。第三层启动 Claude Code 并确认它指向 CCR。正常启动后界面里会显示API Base URL: http://127.0.0.1:3456看到这行才说明 Claude Code 走的是 CCR 而不是官方接口。然后发一句hello观察返回。如果这一步报 429先别急着换 Key把 CCR 的重试次数调低、并发降下来Gemini 免费层对 RPM 很敏感连续重试会自己把自己限流。5. 常见报错逐条排查401 Unauthorized九成是 Key 或 endpoint 不匹配。排查顺序先用第 2 节的 curl 直连上游确认 Key 有效再确认 config.json 里api_key没有多余引号嵌套JSON 里字符串就是字符串别写成\sk-xxx\最后确认api_base_url和 Key 属于同一平台。如果 Key 是从环境变量读的确认 CCR 启动时那个变量确实存在ccr作为子进程不一定继承你 shell 里 export 的变量必要时写进 config 或用ccr start前手动 export。local proxy failed / Service not runningCCR 进程没起来或端口冲突。先ccr status没跑就ccr start并看输出。如果提示端口被占lsof -i :3456找到占用进程 kill 掉或改 CCR 的监听端口。Mac 上还常见一种情况pnpm 全局安装的 CCR 在切换 node 版本后路径失效重新pnpm add -g musistudio/claude-code-router即可。429 RESOURCE_EXHAUSTED这是上游配额或限流不是配置错。Gemini 免费层 RPM 很低CCR 默认重试 10 次会把配额瞬间打满。处理办法把API_TIMEOUT_MS保留但在 Router 里把background这类高频场景换成更轻的模型或者直接降低并发。如果持续 429说明该 Key 的额度确实用尽换 Key 或升级配额。reading choices of undefined这是响应体结构和 CCR 预期不符。通常发生在api_base_url指向了一个返回格式不是 OpenAI 兼容的端点。确认你填的是/v1/chat/completions这类兼容路径而不是原生 Gemini 的generateContent路径。CCR 按 OpenAI 格式解析响应路径错了就拿不到choices字段。OAuth / auth.json 相关报错如果你同时装了 Codex 或其它用auth.json的工具确认它们没有互相覆盖凭证文件。CCR 本身不用 OAuth但 Claude Code 的登录态和 CCR 的 Key 是两套东西别把 Claude Code 的 OAuth token 填进 CCR 的api_key。6. 把通道固定下来少走回头路排查完这一轮我的建议是把「上游三件套」写成一个独立的环境文件CCR 配置里只引用不硬编码。这样以后换模型或换 Key只改一处。长期跑编码任务的话用 Coding Plan 把常用模型和额度固定下来比每次临时找 Key 稳定得多。需要新建或轮换 Key 时直接去 API Keys 页面操作配合接入文档里的路径说明基本不会再踩 endpoint 拼错的坑。整套流程跑顺之后Claude Code 前端体验不变后端走哪条通道完全由你控制这才是 CCR 真正的价值。
