Gemini CLI 转 API：一套可复制的配置与验证步骤

更新于 2026-10-26 · runapi.cfd

简答：Gemini CLI 转 API，实际是替换 CLI 的模型后端，不是把命令封装成新的 HTTP 服务。按“创建标准 API Key→复制 Gemini 原生模型 ID→设置变量→验证调用记录”的顺序操作；本文对应接入页给出的 Base URL 是 <code>https://runapi.ai</code>，不要追加 <code>/v1beta</code>，SDK 会自行拼接请求路径。

定义：Gemini CLI 转 API，是通过环境变量和配置文件让 Gemini CLI 使用指定的 Gemini 原生 API 网关，而不是继续使用默认的 Google 登录或把 CLI 改造成独立 HTTP 服务。

先照这张三步速查卡操作

本文面向需要把 Gemini CLI 请求切换到 Gemini 原生 API 的开发者。本站不是 RunAPI 官方站点；RunAPI 相关地址、模型 ID、Key 规则和控制台功能，应以对应账户文档当前内容为准。本文依据在 2026-10-26 检索到的 Gemini CLI 与接入页面整理，Gemini CLI 版本变化后请先运行 gemini --version，再对照官方配置文档。

对应接入页写明：Base URL 是 HTTPS API 根地址，不包含 /v1beta；SDK 会继续拼接 POST /v1beta/models/{model}:streamGenerateContent?alt=sse。创建标准 Key 可参考 RunAPI Authentication，模型 ID 应从 模型目录复制完整名称，接入变量和验证方式见 Gemini CLI 接入页。

核心认知：“Gemini CLI 转 API”通常表示替换模型服务地址与认证方式；MCP 是增加工具的另一条配置链路，不会因为改了模型 API 就自动完成。

创建 Key、选择模型与确认适用版本

1. 先确认 Gemini CLI 已安装。官方安装页提供安装方式；安装后运行 gemini --version，记录本机版本，后续若变量或配置字段不生效，先把本机版本与当前官方文档对照。可查看 Gemini CLI 官方安装文档。
2. 在对应账户中创建标准 API Key。接入页要求使用专用的标准 Key；认证文档说明，标准 Key 用于 LLM API 等普通调用，创建入口需要登录后进入 API Keys 页面。不要把管理 Key 当作普通模型调用 Key。
3. 打开模型目录，复制完整的 Gemini 原生模型 ID。不要只填写 auto、pro 或 flash 这类短别名，因为接入页提醒它们可能解析到不可用的 Google 模型 ID。主模型可用，也不代表分类、循环检测或其他辅助功能请求的模型一定可用。
4. 检查本机认证方式。Gemini CLI 官方认证文档把 Gemini API Key、Google 登录和 Vertex AI 认证分开说明；如果之前使用过 Google 登录、Vertex AI 环境变量或旧的 .env，应在配置前记录并清理冲突项。参考 Gemini CLI 官方认证文档。

目前没有一个固定的“适用于所有版本”的配置承诺。更稳妥的做法是先运行 gemini --version，再查看官方的认证、配置和命令参考页；如果页面字段与本机行为不同，以本机版本对应的官方说明为准。

Linux 或 macOS：临时环境变量接入

临时配置适合先验证地址、Key 和模型是否能工作。输入 Key 时不要把真实值放进 URL 查询参数、脚本仓库或公开日志；下面的 read -s 会在终端中隐藏输入。

read -s GEMINI_API_KEY; export GEMINI_API_KEY; printf '\n'

export GOOGLE_GEMINI_BASE_URL="https://runapi.ai"

export GEMINI_MODEL="YOUR_RUNAPI_MODEL_ID"

gemini --version

gemini -p "用一句话说明当前目录的用途"

交互模式中再输入 /stats 查看当前会话统计。官方命令参考说明，/stats 可查看会话、模型和工具相关统计，但这些信息只能说明 CLI 当前会话状态，不能单独证明请求已经到达目标网关。可参考 Gemini CLI 官方命令参考。

确认完成后清理当前终端变量：

unset GEMINI_API_KEY GOOGLE_GEMINI_BASE_URL GEMINI_MODEL

如果命令返回结果但账户调用记录没有对应的 Gemini 原生流式请求，不要仅凭输出判断已完成切换；应重新检查变量、认证类型、模型 ID，并在目标账户控制台中核对调用记录。

Windows PowerShell：当前会话与用户级 .env

PowerShell 当前会话可以先使用占位值测试流程，真实 Key 不要写入脚本文件：

$env:GOOGLE_GEMINI_BASE_URL = "https://runapi.ai"

$env:GEMINI_API_KEY = "YOUR_RUNAPI_API_KEY"

$env:GEMINI_MODEL = "YOUR_RUNAPI_MODEL_ID"

gemini --version

gemini -p "用一句话说明当前目录的用途"

测试后清除当前会话变量：

Remove-Item Env:GOOGLE_GEMINI_BASE_URL, Env:GEMINI_API_KEY, Env:GEMINI_MODEL -ErrorAction SilentlyContinue

需要持久化时，官方认证文档确认 Windows 用户目录可使用 %USERPROFILE%\.gemini\.env。下面的 PowerShell 命令会创建目录，并以 UTF-8 写入配置文件；请把模型 ID 和 Key 替换为自己的值：

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.gemini"

@"
GOOGLE_GEMINI_BASE_URL="https://runapi.ai"
GEMINI_API_KEY="YOUR_RUNAPI_API_KEY"
GEMINI_MODEL="YOUR_RUNAPI_MODEL_ID"
"@ | Out-File -FilePath "$env:USERPROFILE\.gemini\.env" -Encoding utf8

写入后不要直接打印完整 Key。可以只检查变量名是否存在：

Get-Content "$env:USERPROFILE\.gemini\.env" | ForEach-Object { ($_ -split "=", 2)[0] }

官方说明指出，Gemini CLI 会从当前目录向父目录查找第一个 .env，再检查用户目录下的 .gemini/.env；多个文件不应被理解为自动合并。若配置不生效，先检查项目目录、父目录和用户目录中是否有旧文件。参考 官方认证与 .env 加载说明。

settings.json：固定 API Key 认证并保留原配置

如果本机曾使用缓存的 Google 登录，仅设置环境变量可能无法达到预期。官方配置参考页将 security.auth.selectedType 定义为当前认证类型，将 model.name 定义为对话模型；两项配置均要求重启后再观察。字段说明见 Gemini CLI 官方配置文档。

先备份文件，再把下面字段合并到 ~/.gemini/settings.json；Windows 对应路径为 %USERPROFILE%\.gemini\settings.json。不要直接覆盖已有的 security、model 或其他设置：

{
"security": {
"auth": {
"selectedType": "gemini-api-key"
}
},
"model": {
"name": "YOUR_RUNAPI_MODEL_ID"
}
}

保存后重启 Gemini CLI。若出现 Invalid auth method selected，检查是否误填成其他认证类型；接入页给出的 API Key 认证值是 gemini-api-key。交互模式还可以使用 /model，或使用 --model YOUR_RUNAPI_MODEL_ID 临时指定模型，但具体命令行为应以本机版本的官方命令参考为准。

不要把真实 Key 提交到 Git。官方认证文档提醒 API Key 属于敏感凭据；如果已经出现在仓库、截图或日志中，应立即在对应账户中撤销并重新创建。

如何确认请求确实没有走错上游

接入页明确建议：先在可信仓库中运行 gemini --version 和最小提示词，再用 /about 或 /stats 检查会话，最后在账户 usage records 中核对匹配的 streamGenerateContent 请求。若该账户控制台没有调用记录功能，就只能把 CLI 输出、变量检查、模型配置和服务商反馈作为组合证据，不能把单次成功响应当成唯一证明。

配置完成后，如果希望少处理多供应商的 API 地址、Key 与模型切换，可以了解 犀速-AI 的统一 API 接入方案。

401、404、认证冲突与辅助模型排查

1. 401：先确认 GEMINI_API_KEY 是对应网关创建的标准 Key，而不是 Google AI Studio 或 Vertex AI 的凭据；再检查是否设置了 GEMINI_API_KEY_AUTH_MECHANISM 覆盖项。接入页说明默认使用 x-goog-api-key 发送 Key，具体仍以当前页面为准。
2. 404：先检查 GOOGLE_GEMINI_BASE_URL 是否误写成 https://runapi.ai/v1beta，正确示例是 https://runapi.ai；然后从模型目录重新复制完整的 Gemini 原生模型 ID。不要直接改成 auto、pro 或 flash。
3. 请求仍表现为 Google 登录：检查 settings.json 的 security.auth.selectedType、缓存登录状态、项目目录到用户目录之间的第一个 .env，以及 Google 或 Vertex AI 相关环境变量。这里只能根据这些可观察配置排查，不能仅凭一次响应断言请求一定走了某个上游。
4. 辅助模型不可用：记录报错中出现的准确模型 ID，再到当前模型目录核对。主模型可用不代表 CLI 的分类、循环检测或其他辅助功能请求的模型也可用；查不到支持信息时应标记为“未核实”，不要自行替换为相近别名。
5. HTTPS 问题：接入页要求使用 HTTPS，HTTP 仅允许用于 localhost；不要为了排错关闭证书校验。

恢复原配置时，删除当前 Shell 和保存的 .env 中的三个变量，恢复原来的 security.auth.selectedType 与模型设置；如果不再使用专用 Key，再按账户页面流程撤销。MCP 服务如果此前单独添加，也需要单独移除。

Gemini 原生 API 与 OpenAI 兼容 API不要混用

如果目标是让 Gemini CLI 使用 Gemini 原生模型后端，按本文配置；如果目标是让某个 SDK 调用 OpenAI 风格的 chat/completions 或 Responses 接口，则应另看对应兼容接口文档。两种请求格式、路径和模型 ID 不应混用。

常见问题

Gemini CLI 转 API 的 Base URL 应该怎么写？

按本文对应接入页，填写 <code>https://runapi.ai</code>，不要在后面添加 <code>/v1beta</code>。接入页说明 SDK 会自行拼接 Gemini 原生请求路径；如果使用其他网关，应改用它自己的 Base URL 文档。

GEMINI_API_KEY 应该填 Google Key 还是 API 网关 Key？

如果目标是把 Gemini CLI 请求发送到 API 网关，就填写该网关创建的标准 API Key。<code>GEMINI_API_KEY</code> 是 CLI 使用的变量名，不代表 Key 必须由 Google 签发；认证类型还应设置为 <code>gemini-api-key</code>。

为什么设置变量后请求仍像是原来的 Google 登录？

检查 <code>settings.json</code> 中的 <code>security.auth.selectedType</code>、缓存登录状态、项目目录到用户目录之间的第一个 <code>.env</code>，以及 Google 或 Vertex AI 变量残留。用账户调用记录核对前，不要仅凭 CLI 输出判断请求去向。

Gemini CLI 出现 404 时先改模型还是先改地址？

先检查 Base URL 是否误加 <code>/v1beta</code>，再从当前模型目录完整复制 Gemini 原生模型 ID。不要直接使用 <code>auto</code>、<code>pro</code> 或 <code>flash</code> 等可能解析到其他上游的别名。

Windows 用户级 .env 应该放在哪里？

官方认证文档列出的用户级位置是 <code>%USERPROFILE%\.gemini\.env</code>；Linux 或 macOS 通常对应 <code>~/.gemini/.env</code>。同时检查当前项目目录和父目录是否存在更早被找到的 <code>.env</code> 文件。

CLI 返回结果后，怎样确认请求真的经过目标网关？

先运行 <code>/about</code> 或 <code>/stats</code> 查看会话信息，再到对应账户的 usage records 核对匹配的 <code>streamGenerateContent</code> 请求。若控制台没有调用记录，只能做配置检查和组合判断，不能把一次成功响应视为充分证明。

相关阅读

• 继续排查 API Key 401
• 阅读 API Key 安全清单
• 了解模型不存在的 404 排查
• 查看站内 API 文档

参考资料

1. Gemini CLI | RunAPI（runapi.ai）
2. Gemini CLI Authentication Setup
3. Gemini CLI configuration
4. Gemini CLI commands