Gemini CLI 国内怎么用？安装、API Key 配置与第三方接入教程（2026）

先给直接答案：Gemini CLI 国内怎么用？ 安装这一步不难：装好 Node.js 20 或更高版本，执行 npm install -g @google/gemini-cli，终端里输入 gemini 就能启动。国内用户真正卡住的是认证：「Sign in with Google」要求能正常访问 Google 账号服务，而且从 2026 年 6 月 18 日起，个人 Google 账号（免费的 Gemini Code Assist 个人版、Google AI Pro / Ultra）已经不能再用这种方式登录 Gemini CLI。个人用户现在基本只剩 API Key 这条路。好在 Gemini CLI 的配置文档里写明了一个 GOOGLE_GEMINI_BASE_URL 环境变量，可以把请求发到任意兼容 Gemini 原生接口的地址，接入第三方 API 靠的就是它。下面按 Gemini CLI 文档和 GitHub 源码（稳定版 v0.61.0，2026-09-24 发布），把安装、认证、base URL、settings.json 和报错排查逐项讲清楚。

Key Takeaways（30 秒速读）

• 安装：Node.js ≥ 20，npm install -g @google/gemini-cli；macOS / Linux 也可以 brew install gemini-cli，只想先试试就用 npx @google/gemini-cli。
• 认证三选一：Google 登录、GEMINI_API_KEY、Vertex AI。个人账号的 Google 登录已停用，组织的 Code Assist Standard / Enterprise 订阅不受影响。
• 接第三方 API：GEMINI_API_KEY 填第三方令牌，GOOGLE_GEMINI_BASE_URL 只填根地址，不要带 /v1beta，SDK 会自己拼版本号。
• 固定认证方式：首次启动选「Use Gemini API Key」，或在 ~/.gemini/settings.json 里把 security.auth.selectedType 设成 gemini-api-key，无头模式（gemini -p）才不会报认证错误。
• 模型名：必须是服务商那边真实存在的名字；Auto 路由、子代理和联网搜索会调用你没手动选的模型，报「模型不存在」时先查这一点。

目录

• 一、Gemini CLI 是什么？2026 年还能用吗
• 二、Gemini CLI 怎么安装？npm、Homebrew 与 npx
• 三、Gemini CLI 有哪几种认证方式？API Key 怎么配
• 四、Gemini CLI 怎么接入第三方 API？GOOGLE_GEMINI_BASE_URL 配置
• 五、settings.json 在哪？怎么固定认证方式和默认模型
• 六、第三方接口上能用哪些 Gemini 模型？
• 七、Gemini CLI 常见报错怎么排查？
• FAQ 常见问题
• 结论

一、Gemini CLI 是什么？2026 年还能用吗

Gemini CLI 是 Google 在 GitHub 上开源（Apache 2.0 协议）的终端 AI 智能体。在项目目录里启动后，它能读写代码文件、执行 shell 命令、联网搜索，还能通过 MCP 接入外部工具。项目地址是 google-gemini/gemini-cli，稳定版每周发布一次。

2026 年它的处境有个大变化。Google 开发者博客在 5 月 19 日发了一篇《An important update: Transitioning Gemini CLI to Antigravity CLI》，把面向个人用户的精力转到新的 Antigravity CLI 上。和 Gemini CLI 用户相关的几条：

• 6 月 18 日起，Gemini CLI 和 Gemini Code Assist IDE 插件不再为 Google AI Pro、Ultra 以及免费的 Gemini Code Assist 个人版提供服务，这些账号不能再用「Login with Google」登录 Gemini CLI（见 Gemini Code Assist 说明页）。Gemini CLI 文档站的安装页顶部也挂着类似的提示。
• 组织用户不变：通过 Gemini Code Assist Standard / Enterprise 订阅使用的，访问方式不受影响。
• API Key 继续可用：博客在企业用户部分写明，Gemini CLI 仍可通过付费的 Gemini API Key 访问。

所以 Gemini CLI 本身还在正常更新（npm 上 9 月 24 日刚发布 0.61.0），变的是个人用户的入口：从「Google 账号登录」变成了「API Key」。对国内开发者来说，这反而让事情简单了。Google 登录本来就要求能访问 Google 账号服务、所在地区在支持列表里，国内网络环境下很难走通；现在大家都走 API Key，区别只在 Key 从哪来：Google AI Studio、Vertex AI，或者兼容 Gemini 原生接口的第三方服务。

第三方服务的局限也先说清楚：你的提示词和代码会经过第三方服务器；联网搜索、token 计数这类附加能力能不能用，要看服务商实现得全不全；出了问题要找服务商，而不是 Google。公司的敏感代码，建议先确认内部合规要求再用。怎么判断一家服务靠不靠谱，可以参考站内《API 中转站怎么辨别真假》。

二、Gemini CLI 怎么安装？npm、Homebrew 与 npx

安装文档给的运行环境要求是 Node.js 20.0.0 及以上，推荐系统为 macOS 15+、Windows 11 24H2+、Ubuntu 20.04+，Shell 支持 Bash、Zsh 和 PowerShell。先确认 Node 版本，再安装：

node -v                             # 确认 Node.js 版本，需要 v20 或更高
npm install -g @google/gemini-cli   # 全局安装 Gemini CLI 稳定版
gemini --version                    # 能输出版本号就说明装好了

另外几种安装方式，都来自 Gemini CLI 安装文档，按自己的系统选一条执行：

brew install gemini-cli          # macOS / Linux：Homebrew
sudo port install gemini-cli     # macOS：MacPorts
npx @google/gemini-cli           # 不安装，临时运行一次

国内从 npm 默认源下载比较慢，可以在这条命令里临时指定国内镜像源 npmmirror，不会改动你全局的 npm 配置：

npm install -g @google/gemini-cli --registry=https://registry.npmmirror.com

版本通道有三个：latest（稳定版，每周发布）、preview（预览版）、nightly（每日构建）。日常用稳定版就够了，升级也是同一条命令：

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

Windows 用户在 PowerShell 里执行同样的 npm 命令即可。装完如果提示找不到 gemini 命令，通常是 npm 的全局目录没加进 PATH：用 npm prefix -g 看一下全局安装位置（macOS / Linux 上命令在它下面的 bin 子目录里，Windows 上就是这个目录本身），把对应目录加进 PATH，再开一个新终端。

三、Gemini CLI 有哪几种认证方式？API Key 怎么配

第一次运行 gemini 会出现认证菜单。按 认证文档，一共三类：

Gemini API Key：到 Google AI Studio 创建 Key，然后：

export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
gemini    # 启动后在认证菜单里选 Use Gemini API Key

用 Google 自己的 Key 时，额度和计费以 Google AI Studio 页面为准。免费档还能不能用在 Gemini CLI 上，Google 几处页面的说法不完全一致，这里不下结论。

Vertex AI：以 gcloud 应用默认凭据为例。文档要求，如果之前设过 GOOGLE_API_KEY 或 GEMINI_API_KEY，要先清掉：

unset GOOGLE_API_KEY GEMINI_API_KEY
gcloud auth application-default login
export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
export GOOGLE_CLOUD_LOCATION="us-central1"
gemini    # 启动后在认证菜单里选 Vertex AI

只有 Vertex 的 API Key（express 模式）时，项目 README 给出的写法是：

export GOOGLE_API_KEY="YOUR_API_KEY"
export GOOGLE_GENAI_USE_VERTEXAI=true
gemini

这三类里，和「接入第三方 API」有关的只有第二类。Vertex AI 也有自己的 base URL 变量 GOOGLE_VERTEX_BASE_URL，但它要求对端实现 Vertex 格式的接口，大多数第三方服务提供的是 Gemini 原生格式，所以下面只讲 GOOGLE_GEMINI_BASE_URL。

四、Gemini CLI 怎么接入第三方 API？GOOGLE_GEMINI_BASE_URL 配置

结论先放前面：Gemini CLI 支持自定义 base URL，变量名是 GOOGLE_GEMINI_BASE_URL，填服务的根地址，不带 /v1beta。 这个结论有三处出处，都可以自己核对：

1. 配置文档的环境变量一节：GOOGLE_GEMINI_BASE_URL 用来覆盖 Gemini API 请求的默认 base URL（在 gemini-api-key 认证下生效），必须是合法 URL，除 localhost 外要用 HTTPS。
2. 源码 packages/core/src/core/contentGenerator.ts：非 Vertex 认证时读取 GOOGLE_GEMINI_BASE_URL，校验格式后放进 SDK 的 httpOptions.baseUrl。
3. Gemini CLI 底层用的 @google/genai SDK，拼请求地址的方式是「base URL + 版本号（默认 v1beta）+ models/模型名:方法」。

第 3 点决定了怎么填。比如 base URL 填 https://v2.cloudmist.cloud，CLI 发出的流式请求地址是：

https://v2.cloudmist.cloud/v1beta/models/gemini-2.5-pro:streamGenerateContent?alt=sse

要是把 /v1beta 也写进变量，地址就变成 /v1beta/v1beta/models/...，服务端只能回 404。API Key 默认放在请求头 x-goog-api-key 里发送；源码里还留了一个 GEMINI_API_KEY_AUTH_MECHANISM=bearer 的开关，打开后会额外带上 Authorization: Bearer 请求头，服务商没有特别要求就别动它。

以本站为例的配置步骤

本站（云雾API）的注册和调用都在新系统 v2.cloudmist.cloud 上，注册后控制台显示为「云岚API」，这是本站的新系统，不是走错了地方。新系统里的 Gemini 模型支持 Gemini 原生格式，接口路径就是 /v1beta/models/{model}:generateContent，和 Gemini CLI 的请求方式对得上。

第 1 步，建令牌。 在控制台「令牌」页创建一个 sk- 开头的令牌。创建时如果可以选分组，确认所选分组里有你要用的 Gemini 模型。注册和建令牌的完整步骤见《新手上手教程》。

第 2 步，先用 curl 验证链路。 下面用的是 Gemini 原生格式，和 CLI 的请求方式一致，能排除令牌、模型名和网络三方面的问题：

curl "https://v2.cloudmist.cloud/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: sk-你的令牌" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":"用一句话介绍你自己"}]}]}'

返回的 JSON 里有 candidates 字段，说明链路是通的；返回 401 就查令牌，返回模型相关的错误就查模型名和分组。

第 3 步，设置两个环境变量并启动（macOS / Linux）：

export GEMINI_API_KEY="sk-你的令牌"                          # 第三方服务的令牌
export GOOGLE_GEMINI_BASE_URL="https://v2.cloudmist.cloud"   # 只填根地址，不带 /v1 或 /v1beta
cd 你的项目目录
gemini

Windows PowerShell：

$env:GEMINI_API_KEY="sk-你的令牌"
$env:GOOGLE_GEMINI_BASE_URL="https://v2.cloudmist.cloud"
gemini

第 4 步，选认证方式。 首次在某个目录启动时，CLI 可能会先问是否信任这个目录（Trusted Folders），自己的项目目录选信任。认证菜单里选 Use Gemini API Key，弹出的输入框会带出 GEMINI_API_KEY 的值，回车确认。这个选择会写进用户级 settings.json，下次不用再选。

第 5 步，用无头模式发一条请求确认：

gemini -m gemini-2.5-flash -p "用一句话说明当前目录是做什么的"

注意这里的地址和 OpenAI 兼容客户端不一样：Cursor、各种 SDK 走 OpenAI 格式，base_url 是 https://v2.cloudmist.cloud/v1；Gemini CLI 走 Gemini 原生格式，只填根地址，这点和 Claude Code 的 ANTHROPIC_BASE_URL 类似。两种格式的区别，站内《base_url 怎么填》讲得更细；Claude Code 的接入可以对照《Claude Code 国内使用教程》。

让配置长期生效

每次开终端都 export 一遍很麻烦，文档给了两种持久化办法。第一种，写进 shell 配置文件（用 bash 的把 ~/.zshrc 换成 ~/.bashrc）：

cat >> ~/.zshrc <<'EOF'
export GEMINI_API_KEY="sk-你的令牌"
export GOOGLE_GEMINI_BASE_URL="https://v2.cloudmist.cloud"
EOF
source ~/.zshrc

第二种，写进 Gemini CLI 专用的 .env 文件：

mkdir -p ~/.gemini
cat >> ~/.gemini/.env <<'EOF'
GEMINI_API_KEY="sk-你的令牌"
GOOGLE_GEMINI_BASE_URL="https://v2.cloudmist.cloud"
EOF

.env 这条路有几个细节要知道：CLI 从当前目录往上找，只加载找到的第一个 .env，不合并，项目里有自己的 .env 时，~/.gemini/.env 就不会被读；shell 里已经有同名变量时，以 shell 里的值为准；当前目录没被信任时，CLI 不读任何 .gemini/.env（包括 ~/.gemini/.env）。拿不准的话，用 shell 配置文件最省心。

五、settings.json 在哪？怎么固定认证方式和默认模型

Gemini CLI 的持久化配置都在 JSON 文件里。按配置文档，一共有四个位置：

优先级从低到高依次是：内置默认值、系统默认、用户级、项目级、系统覆盖、环境变量、命令行参数。所以启动时加的 -m 会盖过 settings.json 里的模型设置。

接第三方 API 时，建议在用户级文件里写这两项：

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

• security.auth.selectedType：认证方式。源码里对应的取值是 oauth-personal（Google 登录）、gemini-api-key（API Key）、vertex-ai（Vertex AI）。在菜单里选过「Use Gemini API Key」的，这一项已经自动写好了。
• model.name：默认模型，换成服务商那边能用的模型名。也可以用环境变量 GEMINI_MODEL、启动参数 -m，或者在会话里输入 /model 切换。

为什么建议把 selectedType 写死？按 v0.61.0 源码的逻辑，无头模式（gemini -p）下如果 settings.json 里没有认证方式，CLI 会根据环境变量去推断：检测到 GOOGLE_GEMINI_BASE_URL 就推断成 gateway 类型，而当前的认证校验函数不认这个类型，结果是报 Invalid auth method selected. 然后退出。写死成 gemini-api-key，交互模式和脚本里都能正常用。

还有两点：API Key 别写进 settings.json 再提交到代码仓库，放在环境变量里更安全；项目级的 .gemini/settings.json 只在目录被信任时才会加载。

六、第三方接口上能用哪些 Gemini 模型？

用第三方服务时，-m 和 model.name 里填的必须是服务商模型列表里真实存在的名字。下面是本站新系统在 2026-09-29 这天、支持 Gemini 原生接口的对话类模型，按模型名和模型描述大致分了档（完整列表和实时价格以《模型价格总表》和控制台为准）：

同样支持 Gemini 原生接口的还有图像模型（如 gemini-3-pro-image-preview、gemini-2.5-flash-image）、语音合成模型（如 gemini-2.5-flash-preview-tts）和向量模型（gemini-embedding-001）。它们不是对话模型，别设成 Gemini CLI 的主模型。单个模型的说明可以看 gemini-2.5-pro、gemini-3.1-pro-preview、gemini-3.5-flash 这几张模型页。

下面两点和 CLI 自身的机制有关，接第三方时经常碰到：

• Auto 模式和子代理会调用别的模型。 /model 菜单里的 Auto 会在 Pro 和 Flash 之间自动路由。文档也说明，/model 和 --model 不会覆盖子代理用的模型；联网搜索、网页抓取这些内部功能，在源码的默认配置里也各有指定模型。服务商缺了哪个，对应那一步就会报「模型不存在」。
• CLI 会改写部分模型名。 源码里有一张映射表，满足特定条件时会把请求里的 gemini-3.5-flash 换成 gemini-3.8-flash、把 gemini-3.1-flash-lite 换成 gemini-3.5-flash-lite。所以控制台日志里的模型名偶尔和你选的不一样，不一定是服务商的问题。

不用 CLI 也能调这些模型。 上表里的 Gemini 模型在本站同时支持 OpenAI 兼容格式。NextChat、ChatBox 这类客户端，或者你自己的代码，把 base_url 设成 https://v2.cloudmist.cloud/v1、模型名照填就行：

from openai import OpenAI

client = OpenAI(
    api_key="sk-你的令牌",
    base_url="https://v2.cloudmist.cloud/v1",  # OpenAI 兼容格式要带 /v1
)

resp = client.chat.completions.create(
    model="gemini-2.5-flash",
    messages=[{"role": "user", "content": "用三句话解释什么是 MCP"}],
)
print(resp.choices[0].message.content)

七、Gemini CLI 常见报错怎么排查？

排查前先把调试信息打开：启动时加 --debug（或 -d），交互模式下按 F12 可以看调试控制台。用第三方服务的，再去控制台「日志」页看这次请求的原始报错。常见问题对照如下：

调试日志里偶尔还会看到 countTokens 请求失败。不少兼容服务没有实现这个接口，比如开源的 new-api 目前就会对它直接返回 404。按源码逻辑，CLI 这时会退回本地估算 token，一般不影响正常对话。余额不足、令牌限额这类和服务商账户有关的报错，可以对照站内《调用报错排查》。

FAQ 常见问题

Q1：Gemini CLI 国内能直接用吗？
工具本身能装能跑，npm 也可以走国内镜像源。卡住的是认证：个人 Google 账号登录已在 2026-06-18 停用，而且登录要能访问 Google 账号服务。国内网络环境下，常见做法是用 API Key，再通过 GOOGLE_GEMINI_BASE_URL 指向一个国内网络可用、兼容 Gemini 原生接口的服务。

Q2：Gemini CLI 的 API Key 从哪里来？
两个来源：Google AI Studio 创建的 Gemini API Key，或者第三方服务在控制台生成的令牌，都填进 GEMINI_API_KEY。用第三方令牌时必须同时设置 GOOGLE_GEMINI_BASE_URL，不然请求会发到 Google 的默认地址，令牌当然无效。

Q3：GOOGLE_GEMINI_BASE_URL 要不要带 /v1beta 或 /v1？
都不带。SDK 会在 base URL 后面自动加上 v1beta（版本号可以用 GOOGLE_GENAI_API_VERSION 改），再拼 models/模型名:方法。以本站为例填 https://v2.cloudmist.cloud；只有 OpenAI 兼容格式的客户端才填带 /v1 的地址。

Q4：个人账号登录不能用了，还有别的选择吗？
Google 给个人用户指的迁移方向是 Antigravity CLI。如果想继续用 Gemini CLI，就换成 API Key：Google 的付费 API Key、Vertex AI，或者第三方服务。组织的 Code Assist Standard / Enterprise 订阅不受影响。

Q5：Gemini CLI 收费吗？
Gemini CLI 是开源的，工具本身不收费，费用来自模型调用。用 Google 的 Key 按 Google 的计费和额度规则；用第三方服务按服务商的规则。本站按量计费，支持人民币充值，价格以充值页实时显示为准，token 怎么计费可以看《大模型 API 按量计费怎么算》。

Q6：为什么控制台日志里的模型和我选的不一样？
一般是这三种情况之一：Auto 模式把请求路由到了别的模型；子代理、联网搜索等内部功能用了各自的默认模型；CLI 源码里的模型映射在满足条件时改写了模型名（例如 gemini-3.5-flash 换成 gemini-3.8-flash）。想完全固定，就选具体模型而不是 Auto，并确认服务商那边相关模型都能用。

Q7：用第三方 API 跑 Gemini CLI 安全吗？
提示词、代码片段和命令输出都会发给服务商。个人项目、开源项目问题不大；公司代码要先确认内部合规要求。建议按项目分开建令牌、给每个令牌设额度上限，用完或者怀疑泄露时直接删掉重建。

结论

Gemini CLI 在 2026 年还在正常更新，变的是个人用户的入口：Google 账号登录停了，API Key 成了主路。国内想用起来，要做的事并不多：装好 Node.js 20+ 和 @google/gemini-cli；把 GEMINI_API_KEY 和 GOOGLE_GEMINI_BASE_URL 设对，后者只填根地址、不带 /v1beta；再在 settings.json 里固定 gemini-api-key 认证和一个服务商确实有的模型。之后遇到的问题，多半能在上面的报错表里找到对应项。

还没有可用 Gemini 接口的话，可以在本站新系统注册账号，到「令牌」页建一个 sk- 令牌，先用第四节的 curl 命令验证，再接进 Gemini CLI。本站提供 Gemini、Claude、GPT 等 200+ 模型，支持人民币充值，价格以充值页实时显示为准。

信息核对日期：2026-09-29。依据：Gemini CLI 文档（geminicli.com）、GitHub 仓库 google-gemini/gemini-cli 稳定版 v0.61.0 源码、@google/genai SDK 源码、Google 开发者博客 2026-05-19 公告；模型列表取自本站新系统当日的模型清单。