Gemini CLI 入门：安装、登录与代理设置

Gemini CLI 是 Google 开源的终端 AI 工具，定位与 Codex CLI、Claude Code 相同：在终端里读代码、改文件、跑命令。对国内用户来说，它比另外两者多一道门槛——除了终端代理之外，还要满足 Gemini 本身的地区要求。本文按「准备 → 安装 → 代理 → 登录 → 第一个任务 → 常见错误」的顺序展开，所有命令可直接复制。如果你还没用过 Gemini 网页版，建议先看 Gemini 使用教程 确认账号地区没有问题。

准备工作

项目	要求	检查命令
Node.js	较新的 LTS 版本（以官方说明为准）	node -v
npm	随 Node 安装	npm -v
操作系统	macOS、Linux、Windows（PowerShell 或 WSL）	—
账号	地区受支持的 Google 账号，或 Gemini API Key	—
网络	终端可通过代理访问 Google 服务	见下文

Node 版本过低时，用 nvm 或 fnm 安装 LTS 版本，不要在系统 Node 上强行升级。

第一步：安装

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

看到版本号即安装成功。国内直连 npm 较慢，可以先按下一步配好终端代理再安装，或临时使用镜像源。遇到 EACCES 权限错误，把 npm 全局目录改到用户目录下，不要用 sudo：

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

第二步：配置终端代理

这一步在登录之前做。图形客户端的「系统代理」对 Node.js 程序无效，必须显式导出变量，端口以客户端实际显示为准，下面以 7890 为例。

macOS / Linux：

export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export ALL_PROXY=socks5://127.0.0.1:7890
export NO_PROXY=localhost,127.0.0.1

Windows PowerShell：

$env:HTTP_PROXY = "http://127.0.0.1:7890"
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
$env:ALL_PROXY = "socks5://127.0.0.1:7890"
$env:NO_PROXY = "localhost,127.0.0.1"

验证代理是否生效：

curl -sS -o /dev/null -w "%{http_code} %{time_total}s\n" https://generativelanguage.googleapis.com/

返回 4xx 状态码且耗时一两秒，说明终端已经走代理（未带密钥被拒绝是正常的）；长时间无响应则代理没有生效。另一种方式是在客户端开启 TUN 模式接管全部流量，此时不需要变量，但两种方式不要同时用。TUN 模式的开启步骤与 Codex CLI 完全相同，见 Codex CLI 代理设置。

第三步：登录

在项目目录运行：

gemini

首次运行会进入初始化流程，按以下步骤完成：

1. 选择界面主题，直接回车使用默认即可。
2. 选择登录方式，个人用户选 Google 账号登录。
3. 终端会打开浏览器跳转到 Google 授权页，用地区受支持的账号登录并同意授权。
4. 授权成功后浏览器显示完成提示，回到终端即可看到对话界面。
5. 如果浏览器没有自动打开，复制终端里显示的授权链接手动打开。

三种登录方式的区别：

方式	适用人群	注意事项
Google 账号登录	个人用户，使用免费额度	浏览器与终端需走同一节点，完成授权回调
Gemini API Key	需要稳定配额或自动化场景	在 Google AI Studio 生成，通过环境变量注入
Vertex AI	企业或已有 Google Cloud 项目	需要额外配置项目与凭据

使用 API Key 时，在当前会话注入后再启动：

export GEMINI_API_KEY=your_key_here
gemini

PowerShell 写法是 $env:GEMINI_API_KEY = "your_key_here"。不要把 Key 写进项目文件或提交到仓库。免费额度与各登录方式的限制以官方页面为准。

第四步：第一个任务

登录成功后进入交互界面。推荐先跑一个只读任务，观察它的工作方式：

阅读这个项目的 README 与目录结构，总结它的用途，并列出三个可以改进的地方

它会列出读取的文件、给出分析并等待下一步指令。涉及修改文件或执行命令时会请求确认，熟悉之前保持确认模式。在交互界面中可以输入 /help 查看可用命令，/quit 退出。

常见错误对照

错误或现象	原因	处理
command not found: gemini	npm 全局 bin 目录不在 PATH	加入 npm config get prefix 下的 bin 目录
登录时提示地区不支持	节点出口不在支持列表	换日本、新加坡或美国节点
浏览器授权成功，终端仍在等待	浏览器与终端走了不同出口	统一节点后重新登录
fetch failed / ETIMEDOUT	终端未走代理	导出变量或开启 TUN，用 curl 验证
任务中途断开	节点长连接不稳	换专线节点，避开晚高峰
429 或配额提示	免费额度用尽或频率过高	等待重置，或改用 API Key
Node 版本报错	版本过低	升级到 LTS

地区与账号相关的深入排查见 Gemini 网络错误排查指南。终端工具对长连接的共性要求与 Claude Code 一致，可以对照 Claude Code 入门教程 中的代理一节。

选节点：地区与长连接同时满足

Gemini CLI 对机场的要求是网页版与终端工具两套标准的叠加：

• 地区在支持列表内，且与 Google 账号地区一致（Gemini 的要求）。
• 能维持几十分钟的长连接、不限制并发（终端工具的要求）。
• 出口 IP 相对固定，授权回调与后续请求用同一出口。
• 晚高峰丢包低，否则流式输出会频繁卡顿。

满足这些条件的品牌可以在 Gemini 机场推荐 栏目查看。站内测试中，极连云 对 AI 服务做了专门分流且受支持地区节点较全，宇宙云 的 IEPL 专线在长连接上更稳，专线机场推荐的原理见 IEPL 与 IPLC 的区别。更多终端 AI 工具的使用说明见 AI 编程工具专题。