Gemini CLI 配置教程

使用 Gemini 原生接口和根地址,按所选配置工具完成启用。

先安装 Gemini CLI,并创建 QuickRouter API Key。

推荐用 QuickRouter Switch 一键配置。已安装 CC-Switch 的用户也可选择备选方式。

使用 QuickRouter Switch 配置

还没安装?下载并安装 QuickRouter Switch。

  1. 添加供应商

    打开 QuickRouter Switch,在左边选「Gemini CLI」,点「添加供应商」。

  2. 填写 API Key

    把自己的 API Key 粘贴到同名输入框。地址和接口格式已经填好。模型可换成自己实际要用、当前 Key 能调用的模型。

    填写 API Key,核对 Gemini CLI 的请求地址和模型。
    图 9 填写 API Key,核对 Gemini CLI 的请求地址和模型。
  3. 开始路由

    点右下角「添加」。回到列表,点「开始路由」,选中 QuickRouter 并确认。看到「路由中」后,退出 Gemini CLI,再运行 gemini。使用时保持 QuickRouter Switch 开着。

查看具体参数和更多操作

「请求地址」用 https://api.quickrouter.ai,沿用 Gemini 原生协议。模型预填 gemini-4-argon。预填模型仅作示例,可换成自己实际要用的模型。请填写当前 API Key 可调用的完整模型 ID。 选择支持 Gemini 原生协议的模型。

点击「添加」。回到供应商列表,点「开始路由」,将「路由到」选为 QuickRouter,再确认「开始路由」。卡片显示「路由中」后,退出并重新运行 gemini,并保持 QuickRouter Switch 运行。

使用 CC-Switch 配置

还没安装?下载并安装 CC-Switch。

查看 Gemini CLI 专题:配置、排错和可复跑案例

  1. 添加供应商

    打开 CC Switch,在左侧选择Gemini CLI,点击添加供应商,选择自定义配置。

  2. 填写连接信息
    • 名称填 QuickRouter,API Key 填自己的令牌,请求地址填根地址 https://api.quickrouter.ai。
    Gemini CLI 的根地址、API Key 与原生 Gemini 模型配置
    Gemini CLI:填写根地址和可用的 Gemini 原生模型,模型占位值需替换。
  3. 设置模型
    • 模型填当前令牌可用的 Gemini 原生模型 ID。截图中的 YOUR_AVAILABLE_GEMINI_MODEL_ID 是占位值,保存前替换为真实模型 ID。
  4. 保存供应商

    在表单底部点击添加。返回 Gemini CLI 供应商列表后,确认出现 QuickRouter 卡片。

  5. 启用并打开工具

    本节使用直连模式。

    在 Gemini CLI 页打开直连,点击 QuickRouter 卡片上的切换。如果本机正用路由,先按页面提示回到直连,再切换到 QuickRouter。退出正在运行的 Gemini CLI,在终端重新运行 gemini,让客户端读取新的 Key、地址和模型。

    Gemini CLI 的 CC Switch 供应商界面截图
    在「直连」页找到 QuickRouter 卡片,点「切换」。
  6. 发送消息验证

    在 Gemini CLI 新会话发送「请只回复 OK」。看到回复后,在QuickRouter 使用日志按发送时间和令牌核对本次请求,确认实际模型是所填的 Gemini 模型。

查看配置细节与排错

表单没有 Chat 格式下拉。客户端在根地址后构造 /v1beta/models/模型ID:generateContent;本节方案无需 CC Switch 协议转换或本地路由。切换后检查 ~/.gemini/.env 中的 GEMINI_API_KEY、GOOGLE_GEMINI_BASE_URL、GEMINI_MODEL,以及 settings.json 的认证与模型设置。

确认配置生效

打开 Gemini CLI 的新会话,选择刚配置的模型,发送「请只回复 OK」。在 QuickRouter 使用日志核对发送时间和实际请求模型。遇到 401 或 403 时,先检查令牌和模型权限。

返回工具教程列表

查看原有安装、手动配置与排错

更新于

适用范围:Gemini CLI 的 gemini-api-key 认证与 Gemini 原生请求协议。

版本与验证:2026-09-28,macOS 26.3,Python requests 2.33.1 / gemini-3.8-flash 原生 generateContent 真实调用通过;Gemini CLI 本机未安装,认证界面及工具未验证。

配置速查

配置项填写内容注意事项
GEMINI_API_KEYQuickRouter API Key选择 API key 认证。
GOOGLE_GEMINI_BASE_URLhttps://api.quickrouter.ai原生 Gemini 基础地址,不追加 OpenAI 的 /v1。
GEMINI_MODEL当前可用的 Gemini 模型 ID同时满足 CLI 和网关权限。

还没有 API Key?注册获取免费体验额度 · 已注册:进入控制台创建 API Key

为此工具单独创建令牌,并设置合理额度和模型权限。截图中的模型仅作示例,以账号当前可用模型为准;不要公开密钥或上传含密钥的配置文件。

第 1 步:安装并查看版本

按官方安装页准备支持的 Node.js 环境,然后安装 CLI。

npm install -g @google/gemini-cli
gemini --version

第 2 步:设置 Gemini 原生接口变量

macOS / Linux,在运行 CLI 的同一终端配置:

export GEMINI_API_KEY="YOUR_QUICKROUTER_API_KEY"
export GOOGLE_GEMINI_BASE_URL="https://api.quickrouter.ai"
export GEMINI_MODEL="YOUR_AVAILABLE_GEMINI_MODEL_ID"

Windows PowerShell:

$env:GEMINI_API_KEY = "YOUR_QUICKROUTER_API_KEY"
$env:GOOGLE_GEMINI_BASE_URL = "https://api.quickrouter.ai"
$env:GEMINI_MODEL = "YOUR_AVAILABLE_GEMINI_MODEL_ID"

模型占位符替换为 QuickRouter 当前支持的 Gemini 原生模型 ID。CLI 使用 Gemini 协议,不能将地址改为 OpenAI 的 /v1/chat/completions。

第 3 步:选择 API key 认证

运行 gemini,按认证引导选择 Gemini API key;GOOGLE_GEMINI_BASE_URL 在该认证模式下生效。之前使用 Google 登录时,应切换认证模式并重启 CLI,不只修改地址变量。

第 4 步:先验证文本再验证工具

询问一个短问题,核对网关原生 Gemini 路由上的请求记录。随后测试读取本地项目文件。认证正常但工具失败时,分别核对模型能力与 CLI 工具权限。

API Key 认证与 OAuth 分开核对

启动后选择 Use Gemini API key。GOOGLE_GEMINI_BASE_URL 仅对 gemini-api-key 模式生效;Google 登录或 Vertex 模式不会因设置此变量就改走该地址。检查项目与用户目录的 .gemini/.env 是否覆盖配置。

export GEMINI_API_KEY="YOUR_QUICKROUTER_API_KEY"
export GOOGLE_GEMINI_BASE_URL="https://api.quickrouter.ai"
export GEMINI_MODEL="gemini-3.8-flash"
gemini --version
gemini

Node.js 要求 20+。npm 的 latest 是公开发布版本;本机未安装 Gemini CLI,不能据此填写 CLI 实测版本。

真实调用记录与验证范围

测试日期:2026-09-28(Asia/Shanghai);macOS 26.3。查看脱敏记录、软件版本和真实生成图片。一次文本成功仅证明本次请求,不代表其他模型、工具执行、多轮上下文或桌面版均已通过。

client: Python requests 2.33.1
POST https://api.quickrouter.ai/v1beta/models/gemini-3.8-flash:generateContent
HTTP 200
output: QUICKROUTER_OK

原生接口真实调用已通过;Gemini CLI 的认证选择、工具和会话尚未实测。Google 登录仍出现、Base URL 未生效和 404 排查。

已额外验证 Gemini SDK 常用的 x-goog-api-key 鉴权头:同一原生路径返回 HTTP 200,算术题返回 4。这仍是接口测试,Gemini CLI 的认证界面及工具未验证。

怎样确认配置已生效

  1. CLI 使用 API key 模式而非 Google OAuth。
  2. 请求进入 QuickRouter 的 Gemini 原生路由。
  3. 短消息正常返回,再验证 CLI 工具能力。

接入失败时逐项检查

现象检查与处理
仍打开 Google 登录切换 CLI 认证方式到 API key,核对当前进程的 GEMINI_API_KEY。
请求到了 /v1/chat/completionsGemini CLI 原生协议不能直接使用 OpenAI 聊天路径。
model not found核对 GEMINI_MODEL 与原生 Gemini 路由上的模型 ID。

资料与下一步

遇到问题时保留软件版本、请求时间、模型 ID、错误码和请求 ID,联系支持时先隐藏 API Key。

在线客服