使用自定义端点和免费模型的 Gemini CLI
Gemini CLI 是 Google 的开源终端编码代理。它可以将请求发送到自定义基础 URL。本指南将 Gemini CLI 指向 FreeLLMAPI,后者在 /v1beta 上提供原生 Gemini API。您的请求随后会发送到您的免费提供方池,其中可以包括免费的 Gemini API 密钥。
代码、模型名称和目录中的实时标签以英文显示。
2026 年 Gemini CLI 免费套餐的变化
请先阅读本节。Google 在 2026 年改变了 Gemini CLI 的免费使用方式。Gemini CLI 配额页面写道:"Unpaid tier and Google One users: Gemini CLI was replaced by Antigravity CLI on June 18th, 2026."
Google 的公告说明,Gemini CLI 仍可通过付费的 Gemini API 密钥使用,并面向企业客户提供。
- 免费套餐的 Google 登录:消费者账户不再由 Gemini CLI 提供服务。
- 带自定义基础 URL 的 Gemini API 密钥:Gemini CLI 配置参考仍记录了
GOOGLE_GEMINI_BASE_URL。设置此变量后,Gemini CLI 会将请求发送到您设置的 URL,而不是 Google。 - 免费的 Gemini API 密钥:Google AI Studio 仍为 Gemini API 列出免费套餐。FreeLLMAPI 可以使用这些密钥,也可以同时使用其他提供方的密钥。
本指南使用第二种方式。FreeLLMAPI 响应请求,并将每个请求发送到您的池中的一个免费模型。
第 1 步:安装 FreeLLMAPI 和 Gemini CLI
安装两者
curl -fsSL https://freellmapi.co/install.sh | bash
npm install -g @google/gemini-cli打开 http://localhost:3001。在 Keys 页面添加至少两个免费提供方密钥。免费的 Google AI Studio 密钥是很好的第一个密钥。从同一页面复制您的统一密钥。
第 2 步:将 Gemini CLI 指向网关
设置两个环境变量,然后启动 Gemini CLI。基础 URL 是服务器源地址,不包含 /v1beta。Gemini CLI 会自行添加 API 路径。
macOS 或 Linux
export GOOGLE_GEMINI_BASE_URL=http://localhost:3001
export GEMINI_API_KEY=<unified-key>
geminiWindows PowerShell
$env:GOOGLE_GEMINI_BASE_URL="http://localhost:3001"
$env:GEMINI_API_KEY="<unified-key>"
gemini当 Gemini CLI 要求选择身份验证方式时,请选择 Use Gemini API key。要保存此选择,请在 ~/.gemini/settings.json 中设置:
~/.gemini/settings.json
{
"security": {
"auth": {
"selectedType": "gemini-api-key"
}
}
}GEMINI_API_KEY。一个 Gemini CLI 问题报告称,版本 0.44.x 在将 GOOGLE_API_KEY 与 GOOGLE_GEMINI_BASE_URL 一起使用时会失败,并提示 "Invalid auth method selected"。如果已设置 GOOGLE_API_KEY,请使用 unset GOOGLE_API_KEY 将其移除。第 3 步:将 Gemini 模型名称映射到免费模型
Gemini CLI 会请求 Gemini 模型名称,例如 gemini-2.5-flash。FreeLLMAPI 不会将这些名称直接发送给 Google。它通过 Keys, Agents 标签页中的 Gemini 系列映射来解析这些名称。将每个系列(Pro、Flash 和 Flash-Lite)映射到 Auto,或映射到一个固定的目录模型。
- 使用 Auto 时,路由器会为每个请求选择一个免费模型。当某个提供方返回 429 错误时,它会尝试下一个提供方。
- 目录 ID 也可以用作模型名称。使用
gemini -m <catalog-id>启动 Gemini CLI,或设置GEMINI_MODEL。 - Gemini CLI 是一个带工具的代理。请将各系列映射到支持工具调用且上下文窗口较大的模型。
第一个表格列出了目录中当前的免费 Gemini 模型。第二个表格列出了其他可以映射到 Gemini 系列的免费模型。
| 模型 | 免费提供方 | 上下文 | 免费额度(最优惠) | 工具 | 视觉 |
|---|---|---|---|---|---|
| Gemini 3.8 Flash | Google AI Studio | 1M | Recurring provider quota | 是 | 是 |
| Gemini Flash (latest alias) | Google AI Studio | - | 10 请求/分钟 20 请求/天 250,000 令牌/分钟 ~3M | 是 | 是 |
| Gemini 3.7 Flash | Google AI Studio | 1M | 10 请求/分钟 20 请求/天 250,000 令牌/分钟 ~3M | 是 | 是 |
| Gemini 3.6 Flash | Google AI Studio | 1M | 10 请求/分钟 20 请求/天 250,000 令牌/分钟 ~3M | 是 | 是 |
| Gemini 3.5 Flash | Google AI Studio | 1M | 10 请求/分钟 20 请求/天 250,000 令牌/分钟 ~3M | 是 | 是 |
| Gemini 3.8 Live | Google AI Studio | - | 10 请求/分钟 20 请求/天 250,000 令牌/分钟 ~3M | 是 | 是 |
| Gemini 3.8 Live Extended Thinking | Google AI Studio | - | 10 请求/分钟 20 请求/天 250,000 令牌/分钟 ~3M | 是 | 是 |
| Gemini 3.5 Flash Lite | Google AI Studio | 1M | 15 请求/分钟 20 请求/天 250,000 令牌/分钟 ~3M | 是 | 是 |
显示 8 个(共 14 个匹配的免费模型)。 查看所有模型.
数据来自 FreeLLMAPI 目录(版本 2026.11.19,检查于 2026-11-19)。免费额度经常变化。该目录每天检查一次。
| 模型 | 免费提供方 | 上下文 | 免费额度(最优惠) | 工具 | 视觉 |
|---|---|---|---|---|---|
| GLM 5.3 | UnoRouter | 1M | 1 请求/分钟 1 req/min per model | 是 | 否 |
| GLM 5.3 Flash | NVIDIA NIM, UnoRouter | 1M | 40 请求/分钟 40 RPM | 是 | 是 |
| Qwen3.8 Flash Next | AMD Radeon Cloud | 262K | Recurring daily account allowance | 是 | 否 |
| Qwen3.8 Flash | ElectronHub | 1M | $0.25/week shared recurring credit | 是 | 是 |
| GPT-5.6 Luna | ElectronHub | 1M | $0.25/week shared recurring credit | 是 | 是 |
| Dots3 Note Preview | Kilo Gateway, OpenRouter | 512K | 20 请求/分钟 50 请求/天 50 req/day account-wide (1,000 after a $10 purchase) | 是 | 是 |
| DeepSeek V4 Flash | AMD Radeon Cloud, BazaarLink, ElectronHub | 1M | 10 请求/分钟 50 请求/天 Shared rate limit | 是 | 否 |
| Qwen3.8 27B | ElectronHub, Groq, OVH AI Endpoints | 262K | 30 请求/分钟 250 请求/天 70,000 令牌/分钟 ~6M | 是 | 是 |
显示 8 个(共 104 个匹配的免费模型)。 查看所有模型.
数据来自 FreeLLMAPI 目录(版本 2026.11.19,检查于 2026-11-19)。免费额度经常变化。该目录每天检查一次。
Gemini 免费套餐的限制
Google 的速率限制页面说明,限制按项目计算,而不是按 API 密钥计算。在同一项目中增加密钥不会增加配额。Google 还说明,限制不作保证,您可以在 Google AI Studio 中查看当前限制。预览模型的限制更低。
免费的 Gemini Flash 密钥每天允许的请求数很少。一次 Gemini CLI 任务可能会发送许多请求。添加其他提供方的密钥,这样当 Gemini 配额用完时,路由器可以继续工作。原生接口支持 generateContent、streamGenerateContent 加 ?alt=sse、countTokens 以及模型列表。
FreeLLMAPI 接受 x-goog-api-key 标头中的密钥、Bearer 令牌,或 Gemini 的 ?key= 查询参数中的密钥。请优先使用标头,因为 URL 中的密钥可能会泄露到 shell 历史记录和代理日志中。
故障排除
| 问题 | 原因 | 解决方法 |
|---|---|---|
| Gemini CLI 打开了 Google 登录 | 身份验证类型未设置为 Gemini API key | 选择 Use Gemini API key,或设置 security.auth.selectedType |
| "Invalid auth method selected" | 在自定义基础 URL 下使用了 GOOGLE_API_KEY | 使用 GEMINI_API_KEY,并取消设置 GOOGLE_API_KEY |
| 请求发送到 Google,而不是网关 | 此 shell 中未设置 GOOGLE_GEMINI_BASE_URL | 导出该变量,然后重新启动 gemini |
模型调用返回 404 | 基础 URL 包含 /v1beta | 仅使用源地址 http://localhost:3001 |
| 工具调用失败 | Gemini 系列映射到了工具调用能力较弱的模型 | 将该系列映射到上表中的某个模型 |
| "所有模型在 N 次尝试后均受速率限制" | 所有密钥都已达到限制 | 添加更多提供方的密钥,或等待冷却时间结束 |
常见问题
Gemini CLI 仍然免费吗?
2026 年 6 月 18 日,Google 结束了未付费用户和 Google One 用户通过 Google 登录免费使用 Gemini CLI 的方式。该 CLI 仍然支持自定义基础 URL,因此可以通过 FreeLLMAPI 等免费网关运行。
如何将 Gemini CLI 与自定义端点一起使用?
将 GOOGLE_GEMINI_BASE_URL 设置为端点源地址,将 GEMINI_API_KEY 设置为其密钥,然后选择 Use Gemini API key。该端点必须在 /v1beta 上支持原生 Gemini API。
Gemini CLI 能否使用非 Gemini 的模型?
可以,通过 FreeLLMAPI 实现。网关会将 Gemini Pro、Flash 和 Flash-Lite 系列名称映射到 Auto 或任何目录模型,例如 Qwen 或 GLM 模型。
Gemini API 免费套餐的限制是多少?
Google 按项目而不是按密钥设置限制,并在 Google AI Studio 中显示当前值。本页的表格列出了 FreeLLMAPI 目录中当前的免费 Gemini 模型及其限制。
为什么会出现 'Invalid auth method selected'?
Gemini CLI 的一个问题报告称,在版本 0.44.x 中,当将 GOOGLE_API_KEY 与 GOOGLE_GEMINI_BASE_URL 一起使用时会出现此错误。请使用 GEMINI_API_KEY,并取消设置 GOOGLE_API_KEY。
相关指南
- free gemini api
- Gemini API 配额超限(429 RESOURCE_EXHAUSTED)
- 如何免费使用 Claude Code
- 将 Codex CLI 与免费模型配合使用
- 最佳免费编程模型 API
来源
- Gemini CLI docs: configuration reference (检查于 20 November 2026)
- Gemini CLI docs: authentication (检查于 20 November 2026)
- Gemini CLI docs: quota and pricing (检查于 20 November 2026)
- Google Developers Blog: transitioning Gemini CLI to Antigravity CLI (检查于 20 November 2026)
- Gemini CLI issue 27550: auth with a custom base URL (检查于 20 November 2026)
- Google AI Studio: rate limits (检查于 20 November 2026)
- FreeLLMAPI docs: native Gemini API (检查于 20 November 2026)