🚀 Claude Code Router 接入 Gemini 配置指南

💡 进阶推荐：如需更强大的代理管理功能，建议使用 cli-proxy-manager。

🎯 本文目标：通过 Claude Code Router 将 Google Gemini 2.5 Pro 免费接入 Claude Code，实现 0 成本 AI 编程体验，支持多 API Key 轮询。

📋 目录导航

前置准备
安装 Claude Code
安装 Claude Code Router
获取 Gemini API Key
配置 Claude Code Router
启动和验证
常见问题解决
进阶配置
总结

🔧 前置准备

在开始之前，请确保您的系统满足以下要求：

系统要求

✅ 操作系统：macOS / Linux / Windows (WSL)
✅ Node.js：v18.0.0 或更高版本
✅ npm：v9.0.0 或更高版本
✅ 网络：能够访问 Google AI Studio（可能需要科学上网）

验证环境

# 检查 Node.js 版本
node --version

# 检查 npm 版本
npm --version

⚠️ 重要提示：如果版本不符合要求，请先升级 Node.js 和 npm。

✅ 步骤 1：安装 Claude Code

1.1 下载并安装

访问 Claude Code 官网或使用以下命令快速安装：

# 使用官方安装脚本（推荐）
curl -fsSL https://claude.ai/install.sh | bash

# 安装完成后验证
claude --version

1.2 初始化配置

# 首次运行 Claude Code
claude code

# 按照提示完成初始化配置

💡 安装提示：安装过程中可能需要授予终端权限，请按照提示操作。

✅ 步骤 2：安装 Claude Code Router

2.1 全局安装

使用 npm 全局安装 Claude Code Router：

# 安装 CCR
npm install -g @musistudio/claude-code-router

# 验证安装
ccr --version

2.2 初始化配置目录

# 创建配置目录（如果不存在）
mkdir -p ~/.claude-code-router

# 检查配置目录
ls -la ~/.claude-code-router

📚 参考文档：Claude Code Router GitHub

✅ 步骤 3：获取 Gemini API Key

3.1 访问 Google AI Studio

打开 Google AI Studio API Keys 页面
使用 Google 账号登录

3.2 创建 API Key

单个 Key 创建：

点击 “Create API Key” 按钮
选择或创建一个 Google Cloud 项目
复制生成的 API Key

多 Key 轮询配置（推荐）：

⚠️ 多 Key 策略：为避免单个 Key 达到速率限制，建议创建多个项目和 API Key 进行轮询。

创建多个 Google Cloud 项目（例如：gemini-project-1, gemini-project-2, gemini-project-3）
为每个项目创建一个 API Key
将所有 Key 保存到安全的地方

最佳实践：

📝 为每个 Key 添加备注说明用途
🔒 不要将 Key 提交到代码仓库
📊 定期检查 API 使用配额
⏰ 设置配额告警通知

🔐 安全提醒：API Key 具有完全访问权限，请妥善保管，不要分享给他人。

✅ 步骤 4：配置 Claude Code Router

4.1 创建配置文件

配置文件路径：

Mac/Linux：~/.claude-code-router/config.json
Windows：%USERPROFILE%\.claude-code-router\config.json

# 创建并编辑配置文件
vim ~/.claude-code-router/config.json

# 或使用其他编辑器
nano ~/.claude-code-router/config.json

4.2 基础配置（单 Key）

{
  "LOG": true,
  "API_TIMEOUT_MS": 600000,
  "NON_INTERACTIVE_MODE": false,
  "Providers": [
    {
      "name": "gemini",
      "api_base_url": "https://generativelanguage.googleapis.com/v1beta/models/",
      "api_key": "YOUR_GEMINI_API_KEY_HERE",
      "models": [
        "gemini-2.5-pro",
        "gemini-2.5-flash"
      ],
      "transformer": {
        "use": ["gemini"]
      }
    }
  ],
  "Router": {
    "default": "gemini,gemini-2.5-pro",
    "background": "gemini,gemini-2.5-flash",
    "think": "gemini,gemini-2.5-pro",
    "longContext": "gemini,gemini-2.5-pro",
    "longContextThreshold": 60000,
    "webSearch": "gemini,gemini-2.5-flash"
  }
}

4.3 高级配置（多 Key 轮询）

{
  "LOG": true,
  "API_TIMEOUT_MS": 600000,
  "NON_INTERACTIVE_MODE": false,
  "Providers": [
    {
      "name": "gemini",
      "api_base_url": "https://generativelanguage.googleapis.com/v1beta/models/",
      "api_key": [
        "YOUR_GEMINI_API_KEY_1",
        "YOUR_GEMINI_API_KEY_2",
        "YOUR_GEMINI_API_KEY_3"
      ],
      "models": [
        "gemini-2.5-pro",
        "gemini-2.5-flash"
      ],
      "transformer": {
        "use": ["gemini"]
      }
    }
  ],
  "Router": {
    "default": "gemini,gemini-2.5-pro",
    "background": "gemini,gemini-2.5-flash",
    "think": "gemini,gemini-2.5-pro",
    "longContext": "gemini,gemini-2.5-pro",
    "longContextThreshold": 60000,
    "webSearch": "gemini,gemini-2.5-flash"
  }
}

4.4 配置项说明

配置项	说明	推荐值
`LOG`	是否启用日志输出	`true`（便于调试）
`API_TIMEOUT_MS`	API 请求超时时间（毫秒）	`600000`（10分钟）
`NON_INTERACTIVE_MODE`	非交互模式	`false`
`api_base_url`	Gemini API 基础地址	必须以 `/` 结尾
`api_key`	API 密钥	可以是字符串或数组
`models`	可用模型列表	根据需求选择
`longContextThreshold`	长文本阈值（token数）	`60000`

Router 路由说明：

default：默认使用的模型
background：后台任务使用的模型（推荐用 flash 节省配额）
think：深度思考任务使用的模型
longContext：长文本处理使用的模型
webSearch：网络搜索使用的模型

4.5 Web UI 配置（可选）

CCR 提供了可视化配置界面，更方便管理配置：

# 启动 CCR 后访问 Web UI
ccr start

# 浏览器打开
open http://127.0.0.1:3456/ui/

Web UI 功能：

📝 可视化编辑配置
📊 查看 API 使用统计
🔍 实时日志查看
⚙️ 快速切换模型

💡 配置验证：保存配置后，建议使用 ccr restart 重启服务以应用新配置。

✅ 步骤 5：启动 Claude Code

5.1 启动 CCR 服务

# 重启 CCR 服务以应用配置
ccr restart

# 查看服务状态
ccr status

# 查看日志（可选，用于排查问题）
ccr logs

5.2 启动 Claude Code

# 启动 Claude Code（会自动连接到 CCR）
ccr code

# 或直接使用
claude code

💡 运行提示：首次启动可能需要几秒钟初始化，CCR 会自动将请求路由到 Gemini 2.5 Pro。

5.3 常用命令

# 查看 CCR 版本
ccr --version

# 查看帮助信息
ccr --help

# 停止 CCR 服务
ccr stop

# 重启 CCR 服务
ccr restart

# 查看实时日志
ccr logs --follow

✅ 步骤 6：验证是否成功

6.1 测试基本功能

在 Claude Code 中输入以下测试问题：

示例 1：代码生成

写一个 Python 函数，计算斐波那契数列的第 n 项

示例 2：代码解释

解释这段 JavaScript 代码的作用：
const sum = arr.reduce((a, b) => a + b, 0);

示例 3：调试帮助

我的 React 组件无法重新渲染，可能是什么原因？

6.2 验证成功标志

如果看到以下情况，说明配置成功：

✅ 响应正常：收到 Gemini 生成的详细回答 ✅ 速度较快：响应时间通常在 2-5 秒内 ✅ 日志正常：CCR 日志中显示成功调用 Gemini API ✅ 无错误提示：没有连接错误或认证失败提示

6.3 查看调用日志

# 查看最近的 API 调用记录
ccr logs --tail 50

# 实时监控
ccr logs --follow

成功的日志示例：

[INFO] Request to gemini,gemini-2.5-pro
[INFO] Response received in 2.3s
[INFO] Tokens used: input=45, output=312

Claude Code 与 Gemini 交互示例

🔧 常见问题解决

问题 1：无法连接，显示 “offline” 🚫

错误现象：

CCR 启动后显示离线状态
Claude Code 无法连接到 Gemini

可能原因：

Gemini API 地址格式错误
网络连接问题
CCR 服务未正常启动

解决方案：

# 1. 检查 API 地址格式（必须以 / 结尾）
# 正确：https://generativelanguage.googleapis.com/v1beta/models/
# 错误：https://generativelanguage.googleapis.com/v1beta/models

# 2. 检查网络连接
curl https://generativelanguage.googleapis.com/v1beta/models/

# 3. 重启 CCR 服务
ccr stop
ccr start

# 4. 查看详细日志
ccr logs --follow

问题 2：Gemini API Key 无效 🔑

错误现象：

返回 401 或 403 错误
日志显示认证失败

可能原因：

API Key 复制不完整或有误
API Key 未启用 Gemini API 权限
API Key 已过期或被撤销

解决方案：

重新创建 API Key
- 访问 Google AI Studio
- 删除旧 Key，创建新 Key
- 确保完整复制（不要有空格或换行）
检查 API 权限
- 在 Google Cloud Console 中确认已启用 Generative Language API
- 检查 API Key 的限制设置
验证 API Key

# 使用 curl 测试 API Key
curl -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":"Hello"}]}]}' \
  "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-pro:generateContent?key=YOUR_API_KEY"

问题 3：模型无法加载 ⚠️

错误现象：

提示模型不存在
加载模型失败

可能原因：

模型名称拼写错误
使用了不支持的模型版本
区域限制（某些地区可能无法访问特定模型）

解决方案：

正确的模型名称：

✅ gemini-2.5-pro
✅ gemini-2.5-flash
✅ gemini-1.5-pro
❌ gemini-pro（旧版本，可能已弃用）
❌ gemini-2.5-pro-latest（不正确的命名）

检查可用模型：

# 列出所有可用模型
curl "https://generativelanguage.googleapis.com/v1beta/models?key=YOUR_API_KEY"

问题 4：请求超时 ⏱️

错误现象：

请求长时间无响应
提示连接超时

可能原因：

网络速度慢或不稳定
API 响应时间过长
超时设置过短

解决方案：

{
  "API_TIMEOUT_MS": 900000,  // 增加到 15 分钟
  // ... 其他配置
}

网络优化：

使用稳定的网络连接
考虑使用 OpenRouter 代理（国内直连更快）
检查防火墙和代理设置

问题 5：达到配额限制 📊

错误现象：

返回 429 错误（Too Many Requests）
提示超出配额

Gemini 免费配额：

每分钟：15 个请求
每天：1500 个请求
每月：150,000 个请求

解决方案：

配置多 Key 轮询（推荐）

{
  "api_key": [
    "KEY_1",
    "KEY_2",
    "KEY_3"
  ]
}

优化请求策略

后台任务使用 gemini-2.5-flash（更快、配额消耗少）
仅复杂任务使用 gemini-2.5-pro
减少不必要的 API 调用

监控使用情况

# 查看今日使用统计
ccr stats --today

# 查看配额剩余
ccr quota

问题 6：响应内容不完整 📝

错误现象：

回答被截断
代码片段不完整

可能原因：

输出 token 限制
上下文长度超限

解决方案：

{
  "Router": {
    "longContext": "gemini,gemini-2.5-pro",
    "longContextThreshold": 100000  // 增加阈值
  }
}

分段处理：

将大型任务拆分成多个小任务
使用 “继续” 命令获取完整输出

💡 进阶配置（可选）

方案 1：使用 OpenRouter 代理 🌐

如果您在国内使用，直接访问 Google API 可能不稳定。OpenRouter 提供了稳定的代理服务，且支持国内直连。

1.1 注册 OpenRouter

访问 OpenRouter 官网
注册账号并获取 API Key
充值余额（支持信用卡）

1.2 配置 OpenRouter

{
  "PORT": 6123,
  "LOG": true,
  "API_TIMEOUT_MS": 600000,
  "Providers": [
    {
      "name": "openrouter",
      "api_base_url": "https://openrouter.ai/api/v1/chat/completions",
      "api_key": "sk-or-your-openrouter-key",
      "models": [
        "google/gemini-2.5-pro",
        "google/gemini-2.5-flash"
      ],
      "transformer": {
        "use": ["openrouter"]
      }
    }
  ],
  "Router": {
    "default": "openrouter,google/gemini-2.5-pro",
    "background": "openrouter,google/gemini-2.5-flash",
    "think": "openrouter,google/gemini-2.5-pro",
    "longContext": "openrouter,google/gemini-2.5-pro",
    "webSearch": "openrouter,google/gemini-2.5-flash"
  }
}

1.3 OpenRouter 优势

✅ 国内直连：无需科学上网
✅ 稳定性高：专业的代理服务
✅ 多模型支持：一个 API Key 访问多种模型
⚠️ 需要付费：按使用量计费（价格合理）

方案 2：混合配置（同时使用多个提供商） 🔀

{
  "Providers": [
    {
      "name": "gemini-direct",
      "api_base_url": "https://generativelanguage.googleapis.com/v1beta/models/",
      "api_key": ["KEY1", "KEY2", "KEY3"],
      "models": ["gemini-2.5-pro", "gemini-2.5-flash"],
      "transformer": { "use": ["gemini"] }
    },
    {
      "name": "openrouter",
      "api_base_url": "https://openrouter.ai/api/v1/chat/completions",
      "api_key": "sk-or-your-key",
      "models": ["google/gemini-2.5-pro"],
      "transformer": { "use": ["openrouter"] }
    }
  ],
  "Router": {
    "default": "gemini-direct,gemini-2.5-flash",
    "think": "openrouter,google/gemini-2.5-pro",
    "background": "gemini-direct,gemini-2.5-flash"
  }
}

混合策略优势：

💡 简单任务用免费的直连 Gemini
💡 复杂任务用稳定的 OpenRouter
💡 最大化利用免费配额，同时保证服务可用性

方案 3：本地代理优化 🚀

如果您有自己的代理服务器，可以配置本地代理：

# 设置代理环境变量
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890

# 启动 CCR
ccr restart

或在配置文件中添加代理设置：

{
  "PROXY": {
    "enabled": true,
    "http": "http://127.0.0.1:7890",
    "https": "http://127.0.0.1:7890"
  }
}

🌟 为什么推荐 Gemini 2.5 Pro？

模型对比

特性	Gemini 2.5 Pro	Claude 3.5 Sonnet	GPT-4	其他开源模型
代码能力	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐
免费额度	每天 1500 次	无免费	有限额度	完全免费
响应速度	快（2-5秒）	中等（3-8秒）	较慢（5-10秒）	快
上下文长度	2M tokens	200K tokens	128K tokens	通常较短
国内访问	需科学上网	需科学上网	需科学上网	部分可直连
与 CCR 兼容性	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐	⭐⭐
多语言支持	优秀	优秀	优秀	一般

Gemini 2.5 Pro 独特优势

🆓 完全免费：每天 1500 次请求，满足大部分个人开发需求
🚀 超长上下文：支持高达 2M tokens，可处理大型代码库
💡 代码生成强大：在编程任务上表现出色，特别擅长多语言代码生成
🔄 持续更新：Google 定期更新模型，性能不断提升
🌐 多模态能力：支持图片、音频等多种输入（通过 CCR 配置）

💡 综合评价：Gemini 2.5 Pro 在免费额度、性能和 Claude Code 兼容性之间达到了最佳平衡，是个人开发者的首选。

📚 总结

核心要点回顾

通过本教程，你已经成功完成：

✅ 环境准备：安装 Claude Code 和 Claude Code Router
✅ API 获取：申请 Gemini API Key（支持多 Key 轮询）
✅ 配置优化：完成 CCR 的基础和高级配置
✅ 问题排查：掌握常见问题的解决方法
✅ 进阶技能：了解 OpenRouter 等代理方案

🎯 配置成功的标志

如果您能看到以下情况，说明配置完全成功：

✅ CCR 服务正常运行（ccr status 显示 running）
✅ Claude Code 可以正常启动
✅ 提问后能收到 Gemini 的详细回答
✅ 日志中显示成功调用 Gemini API
✅ 响应速度在 2-5 秒之间

💰 成本优势

通过本方案，您可以节省：

💵 Claude Code Max 会员费：~$20/月
💵 Claude API 费用：按使用量计费
🆓 使用 Gemini 免费额度：每天 1500 次请求
📊 每月可节省：$20-50（取决于使用量）

年度节省：$240-600

🔑 快速参考卡片

CCR 常用命令

# 服务管理
ccr start        # 启动服务
ccr stop         # 停止服务
ccr restart      # 重启服务
ccr status       # 查看状态

# 日志查看
ccr logs         # 查看日志
ccr logs -f      # 实时日志

# 配置管理
ccr config       # 查看配置
ccr validate     # 验证配置

# 其他
ccr code         # 启动 Claude Code
ccr --help       # 查看帮助

配置文件位置

Mac/Linux：~/.claude-code-router/config.json
Windows：%USERPROFILE%\.claude-code-router\config.json
日志文件：~/.claude-code-router/logs/

重要链接

🚀 下一步建议

优化配置
- 配置多个 API Key 进行轮询
- 根据任务类型选择合适的模型（pro vs flash）
- 调整超时和上下文阈值
提升效率
- 熟悉 Claude Code 的快捷键和命令
- 学习编写有效的提示词（prompt engineering）
- 利用 CCR 的路由功能优化任务分配
监控和维护
- 定期检查 API 配额使用情况
- 查看日志了解系统运行状态
- 关注 CCR 和 Gemini 的更新
探索高级功能
- 尝试使用 Gemini 的多模态能力
- 集成其他 AI 模型（Claude、GPT-4 等）
- 自定义 transformer 实现特殊需求

💬 社区与支持

遇到问题或有建议？欢迎参与：

💬 在 GitHub 上提 Issue
🌟 为项目点 Star 支持开发者
📧 联系开发者反馈问题
👥 加入相关技术社区交流经验

🎊 最终效果

配置完成后，你将拥有：

技术收益

🤖 免费 AI 编程助手：媲美 Claude Code Max 的体验
⚡ 强大代码能力：Gemini 2.5 Pro 的代码生成和理解能力
🔄 灵活的路由系统：根据任务自动选择最合适的模型
📊 完整的日志系统：方便调试和优化

实际应用

💻 日常编程：代码补全、bug 修复、重构建议
📝 代码审查：代码质量分析、最佳实践建议
🔍 问题解决：调试帮助、性能优化建议
📚 学习提升：技术概念解释、代码示例生成

✨ 一句话总结：通过 Claude Code Router + Gemini API，你可以在本地免费享受企业级 AI 编程助手服务，大幅提升开发效率！

感谢阅读！ 如果本教程对你有帮助，欢迎分享给更多需要的开发者。祝你使用愉快！🎉

📋 目录导航#

🔧 前置准备#

系统要求#

验证环境#

✅ 步骤 1：安装 Claude Code#

1.1 下载并安装#

1.2 初始化配置#

✅ 步骤 2：安装 Claude Code Router#

2.1 全局安装#

2.2 初始化配置目录#

✅ 步骤 3：获取 Gemini API Key#

3.1 访问 Google AI Studio#

3.2 创建 API Key#

✅ 步骤 4：配置 Claude Code Router#

4.1 创建配置文件#

4.2 基础配置（单 Key）#

4.3 高级配置（多 Key 轮询）#

4.4 配置项说明#

4.5 Web UI 配置（可选）#

✅ 步骤 5：启动 Claude Code#

5.1 启动 CCR 服务#

5.2 启动 Claude Code#

5.3 常用命令#

✅ 步骤 6：验证是否成功#

6.1 测试基本功能#

6.2 验证成功标志#

6.3 查看调用日志#

🔧 常见问题解决#

问题 1：无法连接，显示 “offline” 🚫#

问题 2：Gemini API Key 无效 🔑#

问题 3：模型无法加载 ⚠️#

问题 4：请求超时 ⏱️#

问题 5：达到配额限制 📊#

问题 6：响应内容不完整 📝#

💡 进阶配置（可选）#

方案 1：使用 OpenRouter 代理 🌐#

1.1 注册 OpenRouter#

1.2 配置 OpenRouter#

1.3 OpenRouter 优势#

方案 2：混合配置（同时使用多个提供商） 🔀#

方案 3：本地代理优化 🚀#

🌟 为什么推荐 Gemini 2.5 Pro？#

模型对比#

Gemini 2.5 Pro 独特优势#

📚 总结#

核心要点回顾#

🎯 配置成功的标志#

💰 成本优势#

🔑 快速参考卡片#

CCR 常用命令#

配置文件位置#

重要链接#

🚀 下一步建议#

💬 社区与支持#

🎊 最终效果#

技术收益#

实际应用#

📋 目录导航

🔧 前置准备

系统要求

验证环境

✅ 步骤 1：安装 Claude Code

1.1 下载并安装

1.2 初始化配置

✅ 步骤 2：安装 Claude Code Router

2.1 全局安装

2.2 初始化配置目录

✅ 步骤 3：获取 Gemini API Key

3.1 访问 Google AI Studio

3.2 创建 API Key

✅ 步骤 4：配置 Claude Code Router

4.1 创建配置文件

4.2 基础配置（单 Key）

4.3 高级配置（多 Key 轮询）

4.4 配置项说明

4.5 Web UI 配置（可选）

✅ 步骤 5：启动 Claude Code

5.1 启动 CCR 服务

5.2 启动 Claude Code

5.3 常用命令

✅ 步骤 6：验证是否成功

6.1 测试基本功能

6.2 验证成功标志

6.3 查看调用日志

🔧 常见问题解决

问题 1：无法连接，显示 “offline” 🚫

问题 2：Gemini API Key 无效 🔑

问题 3：模型无法加载 ⚠️

问题 4：请求超时 ⏱️

问题 5：达到配额限制 📊

问题 6：响应内容不完整 📝

💡 进阶配置（可选）

方案 1：使用 OpenRouter 代理 🌐

1.1 注册 OpenRouter

1.2 配置 OpenRouter

1.3 OpenRouter 优势

方案 2：混合配置（同时使用多个提供商） 🔀

方案 3：本地代理优化 🚀

🌟 为什么推荐 Gemini 2.5 Pro？

模型对比

Gemini 2.5 Pro 独特优势

📚 总结

核心要点回顾

🎯 配置成功的标志

💰 成本优势

🔑 快速参考卡片

CCR 常用命令

配置文件位置

重要链接

🚀 下一步建议

💬 社区与支持

🎊 最终效果

技术收益

实际应用