# Gemini CLI 集成

> 用 GOOGLE_GEMINI_BASE_URL 与 GEMINI_API_KEY 把 Google Gemini CLI 指向本平台的 Gemini 兼容端点

来源：https://qd.zsopc.com/docs/integrations/gemini-cli

> [Gemini CLI](https://github.com/google-gemini/gemini-cli) 是 Google 的命令行 AI 助手,走 Gemini API。本页按 Gemini CLI 0.68.0(2026-11-10 发布)与官方[配置文档](https://geminicli.com/docs/reference/configuration/)核对。

## 准备 API Key

在 [qd.zsopc.com/dashboard/keys](https://qd.zsopc.com/dashboard/keys) 创建 API Key(`sk-gpushare-` + 64 位十六进制,创建后可在 Key 详情页随时重新查看)。

## 配置

```bash
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` 里固定鉴权方式(已有这个文件就把这一项合并进去):

```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,完整列表见 [模型列表](../reference/models.md)。

Gemini CLI 的一些内部辅助调用(补全、分类等)固定使用 `gemini-2.5-flash-lite` 等官方模型名。本平台会把这类旧模型名映射到目录里对应的模型,按映射后的模型计费。

## 注意事项

- 遇到模型出错时,Gemini CLI 默认会询问是否切换到备用模型;备用模型同样走本平台计费。
- `privacy.usageStatisticsEnabled`(默认 `true`)控制 Gemini CLI 自己的用量统计,不想上报可在 settings.json 里设为 `false`。
- Gemini CLI 也能接 MCP 服务器,本平台的出图、视频、音乐工具见 [MCP 媒体工具](./mcp.md)。

## 常见问题

| 现象 | 排查 |
|---|---|
| 仍在请求 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 共享同一账户余额,到 [充值页](https://qd.zsopc.com/dashboard/billing) 充值 |

错误码完整说明见 [Gemini SDK](../sdks/gemini-sdk.md) 与 [错误码](../reference/errors.md)。

## 其他客户端

- [Claude Code](./claude-code.md) — Anthropic 的命令行编程助手
- [Codex CLI](./codex-cli.md) — OpenAI 的命令行编程助手
- [Gemini SDK](../sdks/gemini-sdk.md) — 在自己的代码里调 Gemini 协议
