Gemini CLI 国内网络怎么用：安装、代理与认证

我家大橘 技术创作者 2026-11-01 14 阅读

Gemini CLI 是终端里的 Gemini 编程代理，可安装、配置认证并执行代码任务。

2026 年 6 月 18 日后，官方把个人免费访问及 Google AI Pro、Ultra 账户迁到了 Antigravity CLI；Gemini CLI 现在主要面向 Gemini Code Assist Standard、Enterprise、Code Assist for GitHub on Google Cloud，以及仍可用的付费 API 或 Vertex AI 凭据。这个调整发生在 2026 年，值得现在重新核对：很多旧教程仍按“个人 Google 账号直接登录 Gemini CLI”操作。

下文涉及官方功能、账户范围与命令时均以 Gemini CLI 官方仓库为准；网络现象来自社区教程，明确标为社区记录，不把社区经验写成官方保证。

先选对工具：免费个人用户先别装错

Gemini CLI 与 Antigravity CLI、Gemini API CLI 不是同一个产品。Antigravity CLI 是交互式多代理编程终端，面向 Gemini 4 Argon 及更新模型，也承接免费个人访问和 Google AI Pro、Ultra 账户；Gemini API CLI 是无状态的 API 命令行工具，主要给脚本、CI 和其他代理调用 Gemini API；Gemini CLI 才是当前仓库维护的终端代理。

需求 应选工具 入口
个人免费使用 Google AI、Pro 或 Ultra Antigravity CLI（agy） https://github.com/google-gemini/gemini-cli
脚本或 CI 直接调用 Gemini API Gemini API CLI（gemini-api） https://github.com/google-gemini/gemini-cli
Gemini Code Assist 企业工作流 Gemini CLI（gemini） https://github.com/google-gemini/gemini-cli

如果只是看到“Gemini CLI 国内怎么用”的搜索结果，安装前应先确认账户属于哪一类。若没有 Code Assist 企业许可，也没有仍可用的付费 API 或 Vertex AI 凭据，先按官方说明迁往 Antigravity CLI，继续折腾 gemini 命令不会自动获得免费个人额度。

开始前只检查三项

  1. 准备可用凭据：企业用户准备 Gemini Code Assist Standard、Enterprise 或 Code Assist for GitHub on Google Cloud 账户；其他用户准备官方仍支持的付费 API 或 Vertex AI 凭据。进入 Gemini CLI 官方仓库，查看页面顶部 “Which Google CLI do you need?”，确认所选工具与账户一致。

  2. 检查 Node.js：终端执行 node -v，确认输出的是可用的 Node.js 版本。若没有输出，先安装 Node.js，再重新运行同一命令；不要把“浏览器能打开网页”当作终端运行环境正常的证据。

  3. 确认本地代理入口：打开实际使用的代理客户端，在“设置”页记录 HTTP 代理端口和 SOCKS 代理端口。社区配置记录中出现过 7890、7897 等端口，但端口由客户端决定，必须以本机页面显示值为准，不能照抄示例端口。

这里不要求读者先研究复杂分流规则。认证阶段只需要确认两件事：代理客户端已选到可用节点；终端或 TUN 模式能够转发 Google 服务流量。不同客户端的节点名称和界面布局不同，本文不绑定某一款代理客户端。

三步完成安装与首次启动

1. 用 npm 安装

官方仓库给出的全局安装命令是：

npm install -g @google/gemini-cli

这条命令适用于已经配置好 Node.js 与 npm 的环境。若希望先试用、不写入全局目录，官方也提供免安装方式：

npx @google/gemini-cli

两者只选一种：日常长期使用选全局安装；临时检查选 npx。不要在排查网络时同时执行两种入口，否则可能出现“其中一个正常、另一个仍失败”的误判。

macOS 或 Linux 用户也可以使用官方列出的 Homebrew 路径：

brew install gemini-cli

Homebrew、npm 和 npx 属于不同安装渠道，不要同时安装多个版本。排查前先确定当前实际调用的是哪一个入口。

2. 先让终端具备代理路径

浏览器能打开 Google 页面，不代表终端也会自动使用同一代理。社区教程记录过两个典型现象：“认证 Loading”和“网络连接失败”；其解释是浏览器可能读取系统代理，而终端通常只读取 HTTP_PROXY、HTTPS_PROXY、ALL_PROXY 等环境变量。

优先在代理客户端中开启 TUN 模式，让系统流量统一经过代理；然后在“代理”页面确认当前选中的节点可用。不想使用 TUN 模式时，则应给终端设置上述代理变量，并保证变量值中的端口与客户端“设置”页一致。

具体操作路径：代理客户端 → 设置 → 开启 TUN 模式 → 返回 代理 → 选择可用节点。不同客户端名称可能略有差异；TUN 的作用是接管终端流量，而不只是接管浏览器。

3. 启动并完成认证

安装完成后，在终端运行：

gemini

随后按终端提示选择登录方式。企业 Code Assist 用户应完成组织授权；使用 API 凭据或 Vertex AI 的用户，应在提示中选择对应认证方式。认证完成后，再进入实际项目目录执行 gemini，避免把首次启动和项目文件操作混在一起。

常见卡点：别把下载失败和认证失败混为一谈

卡点一：安装包下载很慢或连接中断。

这是 npm 仓库或 GitHub 访问路径的问题，还没有进入 Gemini 认证。先在代理客户端“日志”页确认节点可访问，再让终端使用同一路径；重新执行官方安装命令。社区教程常把终端代理问题归因于“浏览器与终端走的线路不同”，这一判断适合排查方向，但不是官方对某个地区的可用性承诺。

卡点二：启动后停在“认证 Loading”。

社区教程记录的原话是“认证 Loading”或“网络连接失败”。先检查代理客户端“日志”页是否出现请求记录，再检查终端的 HTTP_PROXY、HTTPS_PROXY、ALL_PROXY 是否指向真实端口。若使用 TUN 模式，确认它已开启且规则没有把 Google 域名分到 DIRECT；随后退出 gemini 并重新启动，不要反复创建多个登录进程。

卡点三：终端能打开登录页，但回调失败。

这通常意味着浏览器与终端并非同一网络路径。优先启用 TUN 模式，并确认浏览器没有使用另一套独立代理配置。企业账户还需确认组织已经为该用户启用 Code Assist；个人免费账号则不属于当前 Gemini CLI 的主要支持范围。

卡点四：按旧教程配置 AI Studio Key 后仍无法使用。

官方仓库已明确写出，个人免费访问和 Google AI Pro、Ultra 已迁往 Antigravity CLI。旧文章中的 API Key 流程不能证明当前账户拥有 Gemini CLI 权限。先按官方工具选择表确认账户类型，再处理凭据。

怎么算已经配置成功

至少应同时出现三个可观察结果：

  1. 终端执行 gemini 后进入交互界面，而不是立即报网络或认证错误。
  2. 认证流程能够完成；企业用户显示的账户或项目范围与所属组织一致。
  3. 在一个专门创建的测试目录中发出简单任务，并收到正常响应。首次验证不要直接对重要仓库执行文件修改。

若只能打开登录网页但无法完成回调，仍不算配置成功；若 gemini 启动正常但调用模型报权限错误，则应回到账户范围检查，而不是继续更换代理节点。

官方入口与延伸阅读

# AI# 知识

评论区

0 条评论

登录后可评论。

我家大橘 14 阅读