🚀 使用 CLI Proxy API 接入 Gemini 模型完整指南

💡 极简方案：相比 Claude Code Router，CLI Proxy API 提供更简洁的配置方式，通过 Homebrew 一键安装，Web UI 可视化管理，让 Gemini 接入 Claude Code 变得更简单。

🎯 本文目标：通过 CLI Proxy API 将 Google Gemini 2.5 Pro 免费接入 Claude Code，实现 0 成本、最简配置 的 AI 编程体验。

📋 目录导航

前置准备
安装 Claude Code
安装 CLI Proxy API
获取 Gemini API Key
配置 CLI Proxy API
设置环境变量
启动和验证
常见问题解决
进阶配置
总结

🔧 前置准备

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

系统要求

✅ 操作系统：macOS（推荐）/ Linux
✅ Homebrew：已安装 Homebrew 包管理器
✅ 网络：能够访问 Google AI Studio（可能需要科学上网）
✅ 终端权限：具有系统管理员权限

验证 Homebrew

# 检查 Homebrew 是否已安装
brew --version

# 如果未安装，执行以下命令安装
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

💡 为什么选择 CLI Proxy API？
✨ 一键安装：通过 Homebrew 快速安装，无需手动配置依赖
🎨 Web UI 管理：可视化配置界面，操作更直观
🔄 自动服务管理：通过 brew services 轻松管理启动/停止
📊 使用统计：实时查看 API 调用统计和配额使用情况
🛠️ 配置简单：相比 CCR 配置更简洁，适合快速上手

✅ 步骤 1：安装 Claude Code

1.1 下载并安装

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

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

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

1.2 初始化配置

# 首次运行 Claude Code
claude code

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

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

✅ 步骤 2：安装 CLI Proxy API

2.1 通过 Homebrew 安装

CLI Proxy API 提供了便捷的 Homebrew 安装方式：

# 安装 CLI Proxy API
brew install cliproxyapi

# 启动服务（设置为开机自启）
brew services start cliproxyapi

# 验证服务状态
brew services list | grep cliproxyapi

2.2 手动启动（可选）

如果不想开机自启，可以手动启动：

# 手动启动
cliproxyapi

# 后台运行
cliproxyapi &

# 查看运行状态
ps aux | grep cliproxyapi

2.3 配置文件位置

macOS (Intel)：/usr/local/etc/cliproxyapi.conf
macOS (Apple Silicon)：/opt/homebrew/etc/cliproxyapi.conf
Linux：/etc/cliproxyapi.conf

# 查看配置文件
cat /opt/homebrew/etc/cliproxyapi.conf

# 编辑配置文件
vim /opt/homebrew/etc/cliproxyapi.conf

📚 参考文档：CLI Proxy 官方文档

✅ 步骤 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。CLI Proxy API 支持自动轮询多个 Key。

创建多个 Google Cloud 项目（例如：gemini-project-1, gemini-project-2, gemini-project-3）
为每个项目创建一个 API Key
在 CLI Proxy API 中添加所有 Key

使用统计查看：

Gemini API 使用统计

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

✅ 步骤 4：配置 CLI Proxy API

CLI Proxy API 提供了两种配置方式：Web UI 配置（推荐）和配置文件编辑。

4.1 Web UI 配置（推荐）

4.1.1 访问管理界面

启动服务后，通过浏览器访问管理界面：

# 打开管理界面
open http://127.0.0.1:8317/management.html

或直接在浏览器中输入：http://127.0.0.1:8317/management.html

4.1.2 添加 Gemini API Key

在 Web UI 中配置 API Key：

点击 “Add API Key” 或 “添加 API 密钥”
填写以下信息：
- Provider：选择 Google Gemini
- API Key：粘贴您的 Gemini API Key
- Name：为 Key 添加备注名称（如：gemini-key-1）
- Priority：设置优先级（数字越小优先级越高）
点击 “Save” 保存配置

4.1.3 配置多个 Key（轮询）

重复上述步骤，添加多个 API Key：

Key 1：优先级 1
Key 2：优先级 2
Key 3：优先级 3

CLI Proxy API 会自动在多个 Key 之间轮询，避免单个 Key 配额用尽。

CLI Proxy API Key 配置界面

4.2 配置文件方式（高级）

如果您偏好直接编辑配置文件，可以手动修改：

# 编辑配置文件
vim /opt/homebrew/etc/cliproxyapi.conf

配置示例：

# Gemini API Keys
[provider.gemini]
enabled = true
api_keys = [
    "YOUR_GEMINI_API_KEY_1",
    "YOUR_GEMINI_API_KEY_2",
    "YOUR_GEMINI_API_KEY_3"
]

# 服务配置
[server]
port = 8317
host = 127.0.0.1

# 日志配置
[logging]
level = info
file = /var/log/cliproxyapi.log

重启服务以应用配置：

# 重启服务
brew services restart cliproxyapi

# 查看日志验证
tail -f /var/log/cliproxyapi.log

4.3 Web UI 功能介绍

CLI Proxy API 的 Web UI 提供了丰富的管理功能：

📝 API Key 管理：添加、编辑、删除 API Key
📊 使用统计：查看 API 调用次数、成功率、失败率
🔍 请求日志：实时查看 API 请求和响应
⚙️ 配置管理：调整服务参数和路由规则
🎨 主题切换：支持亮色/暗色主题

✅ 步骤 5：设置环境变量

为了让 Claude Code 能够使用 CLI Proxy API，需要设置以下环境变量。

5.1 临时设置（当前会话）

# 设置 Anthropic API 基础 URL（指向 CLI Proxy API）
export ANTHROPIC_BASE_URL=http://127.0.0.1:8317

# 设置认证 Token（与 CLI Proxy API 中配置的一致）
export ANTHROPIC_AUTH_TOKEN=your-token-here

# 设置默认模型映射
export ANTHROPIC_DEFAULT_OPUS_MODEL=gemini-2.5-pro
export ANTHROPIC_DEFAULT_SONNET_MODEL=gemini-2.5-pro
export ANTHROPIC_DEFAULT_HAIKU_MODEL=gemini-2.5-flash

5.2 永久设置（推荐）

macOS / Linux (使用 Bash)

编辑 ~/.bashrc 或 ~/.bash_profile：

# 编辑配置文件
vim ~/.bashrc

# 添加以下内容
export ANTHROPIC_BASE_URL=http://127.0.0.1:8317
export ANTHROPIC_AUTH_TOKEN=your-token-here
export ANTHROPIC_DEFAULT_OPUS_MODEL=gemini-2.5-pro
export ANTHROPIC_DEFAULT_SONNET_MODEL=gemini-2.5-pro
export ANTHROPIC_DEFAULT_HAIKU_MODEL=gemini-2.5-flash

# 使配置生效
source ~/.bashrc

macOS / Linux (使用 Zsh)

编辑 ~/.zshrc：

# 编辑配置文件
vim ~/.zshrc

# 添加以下内容
export ANTHROPIC_BASE_URL=http://127.0.0.1:8317
export ANTHROPIC_AUTH_TOKEN=your-token-here
export ANTHROPIC_DEFAULT_OPUS_MODEL=gemini-2.5-pro
export ANTHROPIC_DEFAULT_SONNET_MODEL=gemini-2.5-pro
export ANTHROPIC_DEFAULT_HAIKU_MODEL=gemini-2.5-flash

# 使配置生效
source ~/.zshrc

5.3 环境变量说明

环境变量	说明	示例值
`ANTHROPIC_BASE_URL`	CLI Proxy API 服务地址	`http://127.0.0.1:8317`
`ANTHROPIC_AUTH_TOKEN`	认证令牌（在 CLI Proxy 中配置）	`your-token-here`
`ANTHROPIC_DEFAULT_OPUS_MODEL`	Opus 模型映射到 Gemini	`gemini-2.5-pro`
`ANTHROPIC_DEFAULT_SONNET_MODEL`	Sonnet 模型映射到 Gemini	`gemini-2.5-pro`
`ANTHROPIC_DEFAULT_HAIKU_MODEL`	Haiku 模型映射到 Gemini	`gemini-2.5-flash`

5.4 验证环境变量

# 验证环境变量是否设置成功
echo $ANTHROPIC_BASE_URL
echo $ANTHROPIC_AUTH_TOKEN
echo $ANTHROPIC_DEFAULT_SONNET_MODEL

# 查看所有 ANTHROPIC 相关变量
env | grep ANTHROPIC

💡 模型映射策略：
Opus/Sonnet → gemini-2.5-pro：用于复杂任务，代码质量更高
Haiku → gemini-2.5-flash：用于简单任务，响应更快，节省配额

✅ 步骤 6：启动 Claude Code

6.1 启动 Claude Code

确保 CLI Proxy API 服务正在运行，然后启动 Claude Code：

# 验证 CLI Proxy API 服务状态
brew services list | grep cliproxyapi

# 启动 Claude Code
claude

# 或使用完整命令
claude code

6.2 常用命令

# 启动 Claude Code
claude

# 查看 Claude Code 版本
claude --version

# 查看帮助信息
claude --help

# 退出 Claude Code
# 在 Claude Code 中输入 /exit 或按 Ctrl+C

💡 运行提示：
CLI Proxy API 会自动将 Claude Code 的请求转发到 Gemini API
首次启动可能需要几秒钟初始化
所有请求会通过 http://127.0.0.1:8317 代理

✅ 步骤 7：验证是否成功

7.1 测试基本功能

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

示例 1：代码生成

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

示例 2：代码解释

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

示例 3：调试帮助

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

7.2 验证成功标志

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

✅ 响应正常：收到 Gemini 生成的详细回答 ✅ 速度较快：响应时间通常在 2-5 秒内 ✅ Web UI 统计：在管理界面能看到 API 调用记录 ✅ 无错误提示：没有连接错误或认证失败提示

7.3 查看使用统计

访问管理界面查看实时统计：

# 打开统计页面
open http://127.0.0.1:8317/management.html

在统计页面可以看到：

API 调用总数
成功/失败次数
响应时间统计
配额使用情况

Claude Code 与 Gemini 交互示例

🔧 常见问题解决

问题 1：CLI Proxy API 服务未启动 🚫

错误现象：

Claude Code 无法连接
提示连接被拒绝

解决方案：

# 检查服务状态
brew services list | grep cliproxyapi

# 如果未运行，启动服务
brew services start cliproxyapi

# 查看服务日志
tail -f /var/log/cliproxyapi.log

# 手动测试服务
curl http://127.0.0.1:8317/health

问题 2：环境变量未生效 ⚠️

错误现象：

Claude Code 仍然尝试连接官方 API
提示 API Key 无效

解决方案：

# 验证环境变量
env | grep ANTHROPIC

# 如果为空，重新 source 配置文件
source ~/.zshrc  # 或 source ~/.bashrc

# 在当前终端重新设置
export ANTHROPIC_BASE_URL=http://127.0.0.1:8317
export ANTHROPIC_AUTH_TOKEN=your-token-here

# 重启 Claude Code
claude

问题 3：Web UI 无法访问 🌐

错误现象：

浏览器无法打开管理界面
显示连接超时

解决方案：

# 检查端口占用
lsof -i :8317

# 查看防火墙设置
# macOS: 系统偏好设置 → 安全性与隐私 → 防火墙

# 尝试使用其他端口（修改配置文件）
vim /opt/homebrew/etc/cliproxyapi.conf
# 修改 port = 8318

# 重启服务
brew services restart cliproxyapi

问题 4：API Key 无效 🔑

错误现象：

Web UI 显示 API Key 验证失败
日志中出现 401/403 错误

解决方案：

重新创建 API Key
- 访问 Google AI Studio
- 删除旧 Key，创建新 Key
- 在 CLI Proxy API 中更新
检查 API Key 格式
- 确保没有多余的空格或换行
- 复制完整的 Key 字符串
验证 API Key

# 使用 curl 测试
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"

问题 5：达到配额限制 📊

错误现象：

返回 429 错误（Too Many Requests）
Web UI 显示配额已用尽

Gemini 免费配额：

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

解决方案：

配置多个 API Key：在 Web UI 中添加多个 Key，CLI Proxy API 会自动轮询
查看使用统计：

# 访问统计页面
open http://127.0.0.1:8317/management.html

优化使用策略：
- 简单任务使用 gemini-2.5-flash
- 复杂任务使用 gemini-2.5-pro
- 避免频繁的短请求

问题 6：Homebrew 安装失败 ⚠️

错误现象：

brew install cliproxyapi 报错
找不到包

解决方案：

# 更新 Homebrew
brew update

# 添加 tap（如果需要）
brew tap router-for-me/tap

# 重新安装
brew install cliproxyapi

# 如果仍然失败，查看详细错误
brew install cliproxyapi --verbose

🚀 进阶配置

1. 自定义状态栏

使用 ccstatusline 自定义 Claude Code 的状态栏显示：

# 安装 ccstatusline
npx ccstatusline@latest

# 按照提示配置状态栏
# 可以显示当前使用的模型、Token 消耗等信息

参考文档：ccstatusline GitHub

2. 日志管理

配置详细的日志记录，便于调试：

# 查看实时日志
tail -f /var/log/cliproxyapi.log

# 配置日志级别（在配置文件中）
vim /opt/homebrew/etc/cliproxyapi.conf

# 设置日志级别为 debug
[logging]
level = debug
file = /var/log/cliproxyapi.log
max_size = 10M
backup_count = 5

3. 自定义模型映射

根据需求调整模型映射策略：

# 所有任务都使用 flash（速度优先）
export ANTHROPIC_DEFAULT_OPUS_MODEL=gemini-2.5-flash
export ANTHROPIC_DEFAULT_SONNET_MODEL=gemini-2.5-flash
export ANTHROPIC_DEFAULT_HAIKU_MODEL=gemini-2.5-flash

# 所有任务都使用 pro（质量优先）
export ANTHROPIC_DEFAULT_OPUS_MODEL=gemini-2.5-pro
export ANTHROPIC_DEFAULT_SONNET_MODEL=gemini-2.5-pro
export ANTHROPIC_DEFAULT_HAIKU_MODEL=gemini-2.5-pro

4. 配置开机自启

确保 CLI Proxy API 开机自动启动：

# 设置开机自启
brew services start cliproxyapi

# 验证自启状态
brew services list | grep cliproxyapi
# 应显示 "started" 和用户名

# 取消开机自启
brew services stop cliproxyapi

📚 总结

核心要点回顾

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

✅ 环境准备：安装 Claude Code 和 CLI Proxy API
✅ API 获取：申请 Gemini API Key（支持多 Key 轮询）
✅ 服务配置：通过 Web UI 或配置文件管理 API Key
✅ 环境变量：设置 Claude Code 连接到 CLI Proxy API
✅ 验证测试：确认配置成功并能正常使用

🎯 配置成功的标志

✅ CLI Proxy API 服务正常运行（brew services list 显示 started）
✅ 环境变量正确设置（env | grep ANTHROPIC 显示所有变量）
✅ Claude Code 可以正常启动并响应
✅ Web UI 显示 API 调用统计
✅ 响应速度在 2-5 秒之间

💰 成本优势

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

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

年度节省：$240-600

🔑 快速参考卡片

常用命令

# CLI Proxy API 服务管理
brew services start cliproxyapi    # 启动服务
brew services stop cliproxyapi     # 停止服务
brew services restart cliproxyapi  # 重启服务
brew services list                 # 查看状态

# Claude Code
claude                            # 启动
claude --version                  # 查看版本
claude --help                     # 查看帮助

# 日志查看
tail -f /var/log/cliproxyapi.log  # 实时日志

# 环境变量验证
env | grep ANTHROPIC              # 查看变量

重要文件路径

配置文件 (Apple Silicon)：/opt/homebrew/etc/cliproxyapi.conf
配置文件 (Intel Mac)：/usr/local/etc/cliproxyapi.conf
日志文件：/var/log/cliproxyapi.log
Web UI：http://127.0.0.1:8317/management.html
Shell 配置：~/.zshrc 或 ~/.bashrc

重要链接

🚀 下一步建议

优化配置
- 配置多个 API Key 进行轮询
- 根据任务类型调整模型映射
- 配置日志记录便于调试
提升效率
- 安装 ccstatusline 自定义状态栏
- 熟悉 Claude Code 的快捷键
- 学习编写有效的提示词
监控和维护
- 定期检查 Web UI 的使用统计
- 查看日志了解系统运行状态
- 关注 CLI Proxy API 的更新
探索高级功能
- 尝试不同的模型映射策略
- 配置自定义路由规则
- 集成其他 AI 模型

🎊 最终效果

配置完成后，你将拥有：

技术收益

🤖 免费 AI 编程助手：媲美 Claude Code Max 的体验
⚡ 简化的配置流程：相比 CCR 更简单，通过 Homebrew 一键安装
🎨 可视化管理界面：Web UI 让配置和监控更直观
📊 完整的统计系统：实时查看 API 使用情况

实际应用

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

✨ 一句话总结：CLI Proxy API 提供了最简单的方式将 Gemini 接入 Claude Code，通过 Homebrew 一键安装、Web UI 可视化管理，让你快速享受免费的企业级 AI 编程助手！

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

📋 目录导航#

🔧 前置准备#

系统要求#

验证 Homebrew#

✅ 步骤 1：安装 Claude Code#

1.1 下载并安装#

1.2 初始化配置#

✅ 步骤 2：安装 CLI Proxy API#

2.1 通过 Homebrew 安装#

2.2 手动启动（可选）#

2.3 配置文件位置#

✅ 步骤 3：获取 Gemini API Key#

3.1 访问 Google AI Studio#

3.2 创建 API Key#

✅ 步骤 4：配置 CLI Proxy API#

4.1 Web UI 配置（推荐）#

4.1.1 访问管理界面#

4.1.2 添加 Gemini API Key#

4.1.3 配置多个 Key（轮询）#

4.2 配置文件方式（高级）#

4.3 Web UI 功能介绍#

✅ 步骤 5：设置环境变量#

5.1 临时设置（当前会话）#

5.2 永久设置（推荐）#

macOS / Linux (使用 Bash)#

macOS / Linux (使用 Zsh)#

5.3 环境变量说明#

5.4 验证环境变量#

✅ 步骤 6：启动 Claude Code#

6.1 启动 Claude Code#

6.2 常用命令#

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

7.1 测试基本功能#

7.2 验证成功标志#

7.3 查看使用统计#

🔧 常见问题解决#

问题 1：CLI Proxy API 服务未启动 🚫#

问题 2：环境变量未生效 ⚠️#

问题 3：Web UI 无法访问 🌐#

问题 4：API Key 无效 🔑#

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

问题 6：Homebrew 安装失败 ⚠️#

🚀 进阶配置#

1. 自定义状态栏#

2. 日志管理#

3. 自定义模型映射#

4. 配置开机自启#

📚 总结#

核心要点回顾#

🎯 配置成功的标志#

💰 成本优势#

🔑 快速参考卡片#

常用命令#

重要文件路径#

重要链接#

🚀 下一步建议#

🎊 最终效果#

技术收益#

实际应用#

📋 目录导航

🔧 前置准备

系统要求

验证 Homebrew

✅ 步骤 1：安装 Claude Code

1.1 下载并安装

1.2 初始化配置

✅ 步骤 2：安装 CLI Proxy API

2.1 通过 Homebrew 安装

2.2 手动启动（可选）

2.3 配置文件位置

✅ 步骤 3：获取 Gemini API Key

3.1 访问 Google AI Studio

3.2 创建 API Key

✅ 步骤 4：配置 CLI Proxy API

4.1 Web UI 配置（推荐）

4.1.1 访问管理界面

4.1.2 添加 Gemini API Key

4.1.3 配置多个 Key（轮询）

4.2 配置文件方式（高级）

4.3 Web UI 功能介绍

✅ 步骤 5：设置环境变量

5.1 临时设置（当前会话）

5.2 永久设置（推荐）

macOS / Linux (使用 Bash)

macOS / Linux (使用 Zsh)

5.3 环境变量说明

5.4 验证环境变量

✅ 步骤 6：启动 Claude Code

6.1 启动 Claude Code

6.2 常用命令

✅ 步骤 7：验证是否成功

7.1 测试基本功能

7.2 验证成功标志

7.3 查看使用统计

🔧 常见问题解决

问题 1：CLI Proxy API 服务未启动 🚫

问题 2：环境变量未生效 ⚠️

问题 3：Web UI 无法访问 🌐

问题 4：API Key 无效 🔑

问题 5：达到配额限制 📊

问题 6：Homebrew 安装失败 ⚠️

🚀 进阶配置

1. 自定义状态栏

2. 日志管理

3. 自定义模型映射

4. 配置开机自启

📚 总结

核心要点回顾

🎯 配置成功的标志

💰 成本优势

🔑 快速参考卡片

常用命令

重要文件路径

重要链接

🚀 下一步建议

🎊 最终效果

技术收益

实际应用