Gemini CLI
将 Gemini CLI 接入 RunAPI 的 Gemini 原生 API，验证请求并恢复原有配置。
概览
Gemini CLI 是终端里的 agent。本指南将它的模型提供方改为 RunAPI 的 Gemini 原生 API；通过 MCP 添加 RunAPI tools 是单独的步骤。
开始前准备
npm install -g @google/gemini-cli
配置 RunAPI
先在当前 shell 中设置这些变量。base URL 是 HTTPS API 根地址，不带 /v1beta；SDK 会拼出 POST /v1beta/models/{model}:streamGenerateContent?alt=sse。仅 localhost 允许 HTTP。
export GOOGLE_GEMINI_BASE_URL=https://runapi.ai
export GEMINI_API_KEY=YOUR_RUNAPI_API_KEY
export GEMINI_MODEL=YOUR_RUNAPI_MODEL_ID
长期使用时，将同样的三个变量写入仓库外的 ~/.gemini/.env，并用 chmod 600 ~/.gemini/.env 限制访问。Gemini CLI 从当前目录向父目录查找 .env，然后检查 ~/.gemini/.env 和 ~/.env；注意排查相互冲突的文件。
将以下两项设置合并到 ~/.gemini/settings.json，保留其他设置。API key 鉴权使用 gemini-api-key，不要复用缓存的 Google 登录。默认通过 x-goog-api-key 请求头发送 key。
{
"security": {
"auth": {"selectedType": "gemini-api-key"}
},
"model": {"name": "YOUR_RUNAPI_MODEL_ID"}
}
选择模型
使用 GEMINI_MODEL、--model YOUR_RUNAPI_MODEL_ID 或交互会话里的 /model。避免 auto、pro 和 flash：这些别名可能解析为 RunAPI 不提供的 Google 模型 ID。CLI 内部的路由、分类和循环检测也可能请求 flash 或 flash-lite 辅助模型，需单独确认它们是否可用。
验证
在你信任的仓库中执行以下命令。在交互会话中用 /about 或 /stats 检查模型，再在 RunAPI 用量记录中确认对应的 streamGenerateContent 请求。仅 CLI 成功返回，不能证明请求发到了哪个端点。
gemini --version
gemini -p "Describe this repository in one sentence."
添加 RunAPI tools
MCP 添加的是工具，不是模型提供方。此命令注册本地服务器；请按 Local MCP 完成单独的鉴权和验证。
gemini mcp add runapi npx -y @runapi.ai/mcp
排查问题
请求仍发往 Google 时，检查冲突的 .env 文件、security.auth.selectedType、缓存登录及 Google/Vertex 鉴权环境变量。如果出现 Invalid auth method selected，在设置中选择 gemini-api-key 而非 gateway，然后重启。
遇到 401 时，检查 key 及 GEMINI_API_KEY_AUTH_MECHANISM 覆盖设置；默认使用 x-goog-api-key。遇到 404 时，从 base URL 移除 /v1beta，重新复制支持 Gemini 原生协议的模型 ID。辅助模型不可用时，检查请求的准确 ID；选好主模型并不保证 CLI 的所有功能都能使用。
RunAPI 不提供 countTokens 或 embedContent。countTokens 失败时，Gemini CLI 可回退到本地 token 估算，估算值可能与用量记录不同。除 localhost 外均使用 HTTPS，不要关闭证书校验。
移除 RunAPI
从当前 shell 和已保存的 .env 文件中移除三个变量，恢复原来的 security.auth.selectedType 和模型设置，并在 RunAPI 吊销专用 key。仅在不再需要工具时，才移除单独添加的 MCP 服务器。
unset GOOGLE_GEMINI_BASE_URL GEMINI_API_KEY GEMINI_MODEL