登录
文档Gemini CLI

Gemini CLI

通过 CC Switch 一键导入，或使用 Gemini CLI 官方支持的 API Key、模型和自定义 Base URL 配置文件手动接入。

1. 准备 API Key 和模型

  1. 1
    在 API Key 页面 创建或复制密钥。
  2. 2
    在 模型定价页面 复制一个支持 Gemini 原生接口的准确模型 ID。
  3. 3
    确保 Gemini CLI 为较新版本，自定义 Base URL 是当前版本的正式配置项。

2. 使用 CC Switch 一键导入

  1. 1
    从 CC Switch 发布页 安装并打开 CC Switch。查看截图示例
    CC Switch 发布页安装包列表
    在发布页选择适合自己设备的安装包。
  2. 2
    在 API Key 页面 打开密钥操作菜单，选择 CC Switch 导入。查看截图示例
    打开 CC Switch 导入入口
    创建密钥后打开 CC Switch 导入入口。
  3. 3
    客户端选择 Gemini，再选择支持 Gemini 接口的模型。查看截图示例
    打开 CC Switch 导入对话框
    允许浏览器打开 ccswitch:// 链接后查看导入对话框。
  4. 4
    保留服务根地址 https://ikun.love，不要添加 /v1 或 /v1beta；完整流程可查看 CC Switch 详细步骤。查看截图示例
    确认 CC Switch 导入信息
    导入前检查服务商、模型和端点信息。
  5. 5
    保存并启用服务商，完全退出并重新打开 Gemini CLI。查看截图示例
    启用导入后的 CC Switch 配置
    导入成功后启用配置并重启 Agent。

3. 手动配置

3.1 将 API Key 写入 Gemini CLI 的用户 .env 配置文件

系统用户配置文件
Windows%USERPROFILE%\.gemini\.env
macOS / Linux~/.gemini/.env
.env
GEMINI_API_KEY=此处替换为 API Key
GOOGLE_GEMINI_BASE_URL=https://ikun.love
GEMINI_MODEL=此处替换为准确的模型 ID

Gemini CLI 从当前目录向上查找 .env，再读取用户级 ~/.gemini/.env，并使用找到的第一份配置文件，而不是合并所有文件。写入用户级 .env 后，关闭终端不会清除密钥；请将该文件视为私密配置，不要提交到 Git。如果项目目录已有 .env，请确认它没有覆盖或遗漏上述配置项。

3.2 Base URL 和认证头说明

  • GOOGLE_GEMINI_BASE_URL 使用服务根地址，不带 /v1 或 /v1beta；Google Gen AI SDK 会自行拼接 API 版本和模型路径。
  • 默认按 Gemini 原生方式发送 x-goog-api-key。
  • 只有网关明确要求 Authorization: Bearer 时，才额外设置下面的认证机制。
.env
GEMINI_API_KEY_AUTH_MECHANISM=bearer

如需使用该认证机制，请将这一行也写入同一个用户级 .env 配置文件，不要只在当前终端临时设置。

不要在没有认证错误的情况下随意切换认证头。

4. 启动并验证

  1. 1
    运行 gemini。
  2. 2
    首次提示认证方式时选择 Use Gemini API key，不要选择 Google 登录或 Vertex AI。
  3. 3
    发送一个简短提示并等待完整响应。
  4. 4
    打开 使用日志，确认请求使用预期的 Gemini 模型。
临时覆盖模型
gemini --model "此处替换为准确的模型 ID"

模型选择优先级为：--model、GEMINI_MODEL、settings.json 中的 model.name、默认模型。

5. 常见问题

Gemini CLI 仍使用 Google 登录

重启 CLI 并选择 Use Gemini API key；确认用户级 ~/.gemini/.env（Windows 为 %USERPROFILE%\.gemini\.env）中写入了 GEMINI_API_KEY，且项目 .env 没有抢先覆盖用户文件。

401 或 Invalid API key

  • 确认密钥、分组和模型权限有效。
  • 默认先使用 x-goog-api-key；如果使用日志或网关说明明确要求 Bearer Token，再设置 GEMINI_API_KEY_AUTH_MECHANISM=bearer。
  • 不要同时用 GOOGLE_API_KEY 配置 Vertex AI，这会改变认证路径。

404 Not Found

  • GOOGLE_GEMINI_BASE_URL 不要带 API 版本路径。
  • 模型必须支持 Gemini 原生接口；OpenAI 兼容模型不能只靠修改模型 ID 在 Gemini CLI 中使用。

自定义地址被拒绝

Gemini CLI 要求远程 Base URL 使用 HTTPS。只有 localhost、127.0.0.1 和 [::1] 可以使用 HTTP。

6. 官方参考