Gemini CLI 国内接入指南（2026）：v1beta 兼容端点实操
Gemini CLI 和 Google 官方 SDK 在国内使用，卡点和 Claude Code、Codex 一样：官方入口的可达性与支付。解法也一样——把 Base URL 指向一个协议兼容的网关。区别在于，Gemini 系工具走的是 Google 自己的 v1beta 协议与 x-goog-api-key 鉴权约定，本文用汕拓智算的 Gemini 兼容面走一遍完整流程。
Gemini 兼容面的三个约定
| 项目 | 约定 |
|---|---|
| Base URL | https://swato.ai/v1beta |
| 鉴权 | 请求头 x-goog-api-key: sk-...（也可用 ?key= 查询参数） |
| 密钥分组 | 平台必须为 Google |
和 OpenAI 兼容面最大的差异是鉴权头：Gemini 生态用 x-goog-api-key 而不是 Authorization: Bearer。网关沿用了这一原生约定，所以 Gemini CLI、Google SDK 不需要任何补丁。
三步接入
第一步：创建 Google 分组的密钥
在控制台创建 API 密钥，分组平台选 Google。分组平台决定这把密钥落在哪套协议面上——这是所有工具接入的第一原则，也是排错时第一个要检查的地方。
第二步：用 curl 验证连通性
先绕开工具本身，直接验证端点与密钥：
bash
curl "https://swato.ai/v1beta/models/gemini-3.5-pro:generateContent" \
-H "x-goog-api-key: sk-your-key" \
-H "Content-Type: application/json" \
-d '{
"contents": [{ "parts": [{ "text": "用一句话介绍你自己。" }] }]
}'模型名 gemini-3.5-pro 仅为示例，确切 id 以 GET /v1/models 或模型价格页为准。
第三步：配置 Gemini CLI / SDK
Gemini CLI 与各语言 SDK 都支持自定义 API 端点与密钥，把端点指向 https://swato.ai/v1beta、密钥填 sk-... 即可。以环境变量为例：
bash
export GOOGLE_GEMINI_BASE_URL="https://swato.ai/v1beta"
export GEMINI_API_KEY="sk-your-key"
gemini不同版本的 CLI/SDK 环境变量名可能不同，以工具自身文档为准；核心只有两件事——端点与密钥。
验证与排错
配置完成后跑一个小任务，然后到控制台的用量台账确认调用有记录：模型、输入/输出 token、费用、trace id 齐全，链路即打通。
| 现象 | 原因与处理 |
|---|---|
401 | 密钥无效或没传对。注意 Gemini 面用 x-goog-api-key 头，不是 Authorization |
404 | 密钥分组平台不是 Google，重新创建 Google 分组密钥 |
429 | 触发限流，按退避策略重试；限额与套餐相关 |
| 模型不存在 | 模型 id 凭记忆填写，用 GET /v1/models 取确切 id |
一个入口的好处
接通 Gemini 兼容面之后，同一个账号体系下你还可以用 OpenAI 面接 Codex / Cursor、用 Anthropic 面接 Claude Code——GPT、Claude、Gemini、DeepSeek 等 50+ 模型共用一本账，输入输出分开计量、逐笔可对账。多模型对比选型的具体方法，见旗舰模型写代码怎么选。
相关阅读
常见问题
Gemini CLI 的鉴权方式和 OpenAI 工具一样吗？
不一样。Gemini 系工具沿用 Google 自身的约定，通过请求头 x-goog-api-key 传密钥（也支持 ?key= 查询参数），而不是 Authorization Bearer。密钥本身仍是网关签发的 sk- 开头密钥。
需要什么分组的密钥？
Google 分组。汕拓智算按密钥分组决定协议面，Gemini 兼容面要求密钥所属分组的平台为 Google，用 OpenAI 或 Anthropic 分组的密钥调 v1beta 会报 404。
能用 Gemini 3.5 吗？确切的模型名怎么查？
在售模型包含 Gemini 3.5 系列，确切的模型 id 以 GET /v1/models 返回或控制台模型价格页为准，不要凭记忆填写。
走网关调用 Gemini 会比官方贵吗？
不会加价。汕拓智算按模型官方定价结算，失败与超时的请求不计费，确切单价以控制台定价页为准，每笔调用都可在用量台账核对。