Gemini CLI 安装与使用教程（2026 最新）：npm 国内镜像安装、三种登录方式、接第三方 API

想接第三方 API，往下翻到「接第三方 API」。本文所有命令都在 2026 年 10 月 15 日用最新的 Gemini CLI 0.64.0 实测过。

先看这张表：你该用哪种装法

和 Claude Code、Codex 不同，Gemini CLI 没有一键安装脚本，一定要先装 Node.js。

Gemini CLI 是什么

Gemini CLI 是 Google 出的开源 AI 编程助手（Apache 2.0 协议），在终端里用。它能读项目代码、改文件、运行命令，内置 Google 搜索，支持 MCP 扩展，用的是 Google 的 Gemini 模型，上下文窗口有 100 万 token。

它最大的特点是免费额度多：用个人 Google 账号登录，每天最多 1000 次请求，适合轻度使用和尝鲜。

安装前准备

• Node.js 20 或以上。在终端运行 node -v 检查；没装或版本太低，先到 Node.js 官网装一个 LTS 版本（建议 22）。
• 官方推荐的系统：macOS 15+、Windows 11 24H2+、Ubuntu 20.04+。内存建议 4 GB 以上，项目大、会话长的话 16 GB 更舒服。
• 想清楚怎么登录：Google 账号、Gemini API Key、Vertex AI 三选一。另一个办法是接兼容 Gemini 接口的第三方服务，见下文。

安装

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

我们实测 2 秒装完，装好后大约占 100 MB：

added 7 packages in 2s

装的过程中出现 npm WARN deprecated node-domexception 或 npm WARN deprecated glob 这类警告，可以忽略，官方说明这些只是依赖包的提示，不影响使用。

关于 Homebrew：官方文档仍然写着 brew install gemini-cli，但我们 10 月 15 日查到，Homebrew 已在 2026 年 6 月 18 日把 gemini-cli 标为弃用，版本停在 0.46.0，而 npm 上已经是 0.64.0，差了将近 20 个版本。所以 Mac 用户也建议用 npm 装。

装完检查

打开一个新终端窗口：

gemini --version

0.64.0

然后进入你的项目文件夹，运行 gemini 启动。

三种登录方式和免费额度

第一次运行 gemini 会让你选登录方式，之后随时可以在对话里输入 /auth 更换：

用 API Key 的话，到 Google AI Studio 创建密钥，然后设置环境变量：

export GEMINI_API_KEY="你的密钥"

想长期生效，写进 ~/.gemini/.env 文件里，见下一节的写法。

接第三方 API

Gemini CLI 可以把请求发到兼容 Gemini 原生接口的第三方服务。需要两个设置：服务商的地址和密钥，以及把登录方式指定成「API Key」。以 api.foo 为例：

1. 新建（或编辑）~/.gemini/.env，写入地址和密钥。Windows 是 C:\Users\你的用户名\.gemini\.env：

GEMINI_API_KEY="sk-你的密钥"
GOOGLE_GEMINI_BASE_URL="https://api.foo"

2. 编辑 ~/.gemini/settings.json（Windows 是 C:\Users\你的用户名\.gemini\settings.json），指定用 API Key 登录：

{
  "security": {
    "auth": {
      "selectedType": "gemini-api-key"
    }
  }
}

文件里已经有别的设置的话，只把 security 这一段合并进去，注意逗号。

3. 重新运行 gemini。

第 2 步不能省。我们实测，只设了地址和密钥、没指定登录方式时，用 gemini -p 运行，Gemini CLI 0.64.0 直接报错：

Invalid auth method selected.

加上第 2 步后，用一把故意写错的密钥测试，请求到达了 api.foo，并收到了 api.foo 返回的报错。说明地址和登录方式都配对了，换上正确的密钥就能用：

_ApiError: {"error":{"code":"","message":"无效的令牌 (request id: …)","type":"new_api_error"}}
  status: 401

几点说明：

• 地址只写到域名，Gemini CLI 会自己在后面加 /v1beta/...。
• 最好指定一个模型。默认的「Auto」模式在每次回答前，会先用一个小模型（官方文档写的是 gemini-2.5-flash-lite）判断这个任务该用 Pro 还是 Flash，这也会产生一次请求。接第三方服务时，可以用 /model 手动选一个模型，或者启动时加 -m 模型名，比如 gemini -m gemini-3-pro-preview。模型名以服务商支持的为准。
• 用了 Auto 模式，终端里又出现 [Routing] NumericalClassifierStrategy failed 这一行，说明那次「判断」的请求失败了，常见原因是服务商没开那个小模型。Gemini CLI 会接着发正式请求，一般不影响使用。指定模型后这一行就不会再出现。

上手：常用操作

常见报错与解决办法

1. command not found: gemini

npm 的全局目录不在 PATH 里。运行 npm config get prefix，把显示的目录下的 bin（Windows 是这个目录本身）加进 PATH，然后重新打开终端。用 nvm 装的 Node.js 一般不会遇到这个问题。

2. Invalid auth method selected.

最常见于接第三方 API 时：设置了 GOOGLE_GEMINI_BASE_URL，但没指定登录方式。按上文「接第三方 API」第 2 步，在 settings.json 里写上 "selectedType": "gemini-api-key"。

3. Gemini CLI is not running in a trusted directory

Gemini CLI is not running in a trusted directory. To proceed, either use `--skip-trust`, set the `GEMINI_CLI_TRUST_WORKSPACE=true` environment variable, or trust this directory in interactive mode.

用 gemini -p 跑脚本时，当前文件夹还没被你「信任」过。确认这个文件夹里的代码没问题后，先运行一次 gemini 交互模式，按提示信任它；或者在命令前加 GEMINI_CLI_TRUST_WORKSPACE=true。

4. Your current account is not eligible … not currently available in your location

用 Google 账号登录时，你所在的地区不在 Gemini CLI 的支持范围内。可以改用 API Key 或第三方服务。

5. You must be a named user on your organization's Gemini Code Assist Standard edition subscription

个人账号却设置了 GOOGLE_CLOUD_PROJECT 或 GOOGLE_CLOUD_PROJECT_ID 环境变量，Gemini CLI 就会按企业订阅来检查。从 ~/.zshrc、~/.bashrc 和 .env 文件里删掉这两个变量，重开终端。

6. UNABLE_TO_GET_ISSUER_CERT_LOCALLY

公司网络在检查 HTTPS 流量，Node.js 不认公司的证书。先试 export NODE_USE_SYSTEM_CA=1，让 Node.js 用系统自带的证书库；不行再用 NODE_EXTRA_CA_CERTS 指向公司根证书文件。

7. 401、无效的令牌

请求到了服务商，但密钥不对：复制漏了、多了空格，或者用错了别家的密钥。检查 ~/.gemini/.env 里的 GEMINI_API_KEY。

还有两个容易忽略的地方：

• 系统环境里已经有同名变量时，.env 里的不会生效。比如 ~/.zshrc 里以前 export 过别的 GEMINI_API_KEY，Gemini CLI 用的是那个。
• Gemini CLI 只读找到的第一个 .env。它先从当前文件夹往上找，项目里的 .env 会挡住 ~/.gemini/.env。

更新与卸载

更新：

gemini update

或者重新安装最新版：npm install -g @google/gemini-cli@latest。官方还有 preview（每周预览版）和 nightly（每日构建）两个渠道，分别用 @preview、@nightly 安装，一般用默认的稳定版就好。

卸载：

# npm 安装的
npm uninstall -g @google/gemini-cli

# 只用 npx 运行过的：清掉 npx 缓存
rm -rf "$(npm config get cache)/_npx"

# Homebrew 安装的
brew uninstall gemini-cli

你的设置、登录信息和对话记录在用户目录的 .gemini 文件夹里，卸载不会删除。想彻底清干净就删掉这个文件夹。

相关阅读

• Claude Code 安装教程：Mac、Windows、Linux 三种装法与国内常见问题
• Codex 安装与使用教程：一键安装、npm 国内镜像、config.toml 接第三方 API
• CC Switch 下载安装与配置教程