Gemini CLI 集成
用 GOOGLE_GEMINI_BASE_URL 与 GEMINI_API_KEY 把 Google Gemini CLI 指向本平台的 Gemini 兼容端点
Gemini CLI 是 Google 的命令行 AI 助手,走 Gemini API。本页按 Gemini CLI 0.68.0(2026-11-10 发布)与官方配置文档核对。
准备 API Key#
在 qd.zsopc.com/dashboard/keys 创建 API Key(sk-gpushare- + 64 位十六进制,创建后可在 Key 详情页随时重新查看)。
配置#
npm install -g @google/gemini-cli
export GOOGLE_GEMINI_BASE_URL="https://qd.zsopc.com" # 不带 /v1beta
export GEMINI_API_KEY="sk-gpushare-xxx"
export GEMINI_MODEL="gemini-3.1-pro-low"
建议把这三行写进 ~/.zshrc / ~/.bashrc。Gemini CLI 也会读 .env 文件,但只读找到的第一个,而且在未受信任的工作区里只加载 Key 一类的变量,base URL 可能被跳过。
再在 ~/.gemini/settings.json 里固定鉴权方式(已有这个文件就把这一项合并进去):
{
"security": { "auth": { "selectedType": "gemini-api-key" } }
}
然后运行 gemini;交互界面问到鉴权方式时选 Use Gemini API key。非交互用法:gemini -p "你好"。
要点:
GOOGLE_GEMINI_BASE_URL只填域名,版本号v1beta由 Gemini CLI 自己加,最终请求https://qd.zsopc.com/v1beta/models/{model}:...。地址必须是 HTTPS。- 这个变量只在
gemini-api-key鉴权方式下生效,所以要在 settings.json 里写明selectedType;没写时,非交互模式可能报Invalid auth method selected。
选模型#
Gemini CLI 走 Gemini 原生协议,用 Gemini 系列模型:
| 用途 | 模型 |
|---|---|
| 默认 / 复杂任务 | gemini-3.1-pro-low、gemini-4-argon |
| 快速、省钱 | gemini-3.8-flash |
模型的优先级:-m / --model 参数 > GEMINI_MODEL 环境变量 > settings.json 的 model.name > 默认值 auto。auto 会落到 Google 官方的模型名,建议总是显式指定本平台目录里的 ID,完整列表见 模型列表。
Gemini CLI 的一些内部辅助调用(补全、分类等)固定使用 gemini-2.5-flash-lite 等官方模型名。本平台会把这类旧模型名映射到目录里对应的模型,按映射后的模型计费。
注意事项#
- 遇到模型出错时,Gemini CLI 默认会询问是否切换到备用模型;备用模型同样走本平台计费。
privacy.usageStatisticsEnabled(默认true)控制 Gemini CLI 自己的用量统计,不想上报可在 settings.json 里设为false。- Gemini CLI 也能接 MCP 服务器,本平台的出图、视频、音乐工具见 MCP 媒体工具。
常见问题#
| 现象 | 排查 |
|---|---|
| 仍在请求 Google 官方地址 / 提示登录 | GOOGLE_GEMINI_BASE_URL 没传进当前终端;settings.json 的 selectedType 不是 gemini-api-key |
401 UNAUTHENTICATED | GEMINI_API_KEY 是否为完整的 sk-gpushare- Key(共 76 字符) |
400 NOT_FOUND | 模型 ID 不在目录,改用上表里的 Gemini 模型 |
503 UNAVAILABLE | 该模型在 Gemini 原生协议下没有通道,换 Gemini 系列模型 |
402 RESOURCE_EXHAUSTED | 余额不足。所有 Key 共享同一账户余额,到 充值页 充值 |
错误码完整说明见 Gemini SDK 与 错误码。
其他客户端#
- Claude Code — Anthropic 的命令行编程助手
- Codex CLI — OpenAI 的命令行编程助手
- Gemini SDK — 在自己的代码里调 Gemini 协议