1. Gemini CLI 装完却卡在登录先看清这条链路Gemini CLI 是 Google 推出的命令行 AI 工具能在终端里直接读代码库、跑 Git 操作、生成原型对个人开发者来说免费额度够用。但很多人npm install -g google/gemini-cli敲完gemini一启动就卡住要么登录页面转圈要么直接甩一句缺少GOOGLE_CLOUD_PROJECT环境变量。这篇就把 Node.js 到环境变量、登录报错整条链路拆开讲顺带用 TaoToken 统一 Key/API 通道做一次请求验证确认你的调用是真的跑通了而不是“看起来启动了”。适合谁看刚接触 Gemini CLI 的新手、Node.js 环境没配利索的 Windows/macOS 用户、以及被GOOGLE_CLOUD_PROJECT报错卡住的人。核心检索词就三个Gemini CLI 安装、GOOGLE_CLOUD_PROJECT 环境变量、Node.js/npm 环境。下面按“先装好、再登录、最后验证”的顺序走每一步都给可复制的命令。先说清楚一个前提Gemini CLI 本身是 Google 官方工具登录走的是 Google 账号授权。如果你所在网络环境访问 Google 服务不稳定登录环节会直接失败这不是 CLI 的 bug而是网络链路问题。本文不涉及任何网络工具的具体配置只讲 CLI 自身的安装、环境变量和排错逻辑。真正要跑通调用除了官方登录也可以用 TaoToken 这类统一 API 通道来验证请求是否通后面第 4 节会给对照动作。安装前先确认 Node.js 版本。Gemini CLI 要求 Node.js 18 或更高推荐用 nvm 管理版本避免全局版本冲突。Windows 上用node -v和npm -v各查一次版本低于 18 就先升级。这一步看着简单但实测下来很多“装完启动报错”的根因就是 Node 版本太老npm 拉下来的包和运行时对不上。2. Node.js 与 npm 环境准备Gemini CLI 安装前置检查这一节把安装链路彻底走一遍重点解决“npm 全局装完却找不到命令”和“Node 版本不匹配”两类问题。先确认环境再装包最后验证命令是否进 PATH。第一步查 Node 和 npm 版本。打开终端Windows 用 cmd 或 PowerShellmacOS 用 Terminal输入node -v npm -v正常输出类似v20.11.0和10.2.4。如果node -v报“不是内部或外部命令”说明 Node.js 没装或没进 PATH去 Node 官网下 LTS 版本重装安装时勾选“Add to PATH”。如果版本低于 18用 nvm 升级nvm install 20 nvm use 20nvm 在 Windows 上用 nvm-windowsmacOS/Linux 用官方脚本装。装完再node -v确认切到 20。第二步全局安装 Gemini CLInpm install -g google/gemini-cli这里最常见的坑是权限。macOS/Linux 上如果报EACCES别急着sudo先配 npm 全局目录mkdir -p ~/.npm-global npm config set prefix ~/.npm-global export PATH~/.npm-global/bin:$PATH然后把export PATH那行写进~/.bashrc或~/.zshrcsource一下再重装。Windows 上一般不会有权限问题但如果 npm 全局目录没进 PATH装完gemini会提示“不是内部或外部命令”。用npm config get prefix查全局目录把那个路径加进系统环境变量 Path。第三步验证安装gemini --version能打印版本号就说明命令进 PATH 了。如果这一步失败回到上一步查 PATH别往下走。第四步启动前先想清楚登录方式。Gemini CLI 首次启动会让你选主题和登录方式选 Google 账号登录会跳浏览器授权。如果网络访问 Google 不稳定这一步会卡住。这时候有两个选择一是换网络环境重试官方登录二是用 TaoToken 的统一 API 通道来验证 CLI 的请求链路是否通具体在第 4 节展开。这里插一句环境变量的通用写法。Windows cmd 用setPowerShell 用$env:macOS/Linux 用export。临时变量只在当前终端窗口有效关掉就没了要永久生效得写进系统环境变量或 shell 配置文件。后面GOOGLE_CLOUD_PROJECT和代理相关变量都遵循这个规则别设完临时变量换个窗口又懵了。装完先别急着登录把gemini --version和node -v两条命令的输出记下来后面排错时对照用。环境这层稳了登录报错才好定位。3. GOOGLE_CLOUD_PROJECT 环境变量配置与可复制片段GOOGLE_CLOUD_PROJECT报错是 Gemini CLI 最高频的坑之一。授权成功后 CLI 提示“缺少 GOOGLE_CLOUD_PROJECT 环境变量”本质是它需要一个 Google Cloud 项目 ID 来绑定配额和计费。官方说法是企业/组织 Workspace 账号、或之前注册过 Code Assist 许可证的账号可能自动带上项目普通个人账号往往需要手动指定。解决路径分三步建项目、拿项目 ID、配环境变量。第一步进 Google Cloud Console 建项目。登录后新建一个项目名字随意建完在项目选择器里找到它复制“项目 ID”。注意是项目 ID不是项目名称ID 通常是小写字母加数字加连字符。第二步启用 Gemini for Google Cloud API。在 Console 里搜 “Gemini for Google Cloud”点启用。这一步不做后面 CLI 调用会报权限或配额错误。第三步配环境变量。Windows cmd 临时设置set GOOGLE_CLOUD_PROJECTyour-project-idPowerShell$env:GOOGLE_CLOUD_PROJECTyour-project-idmacOS/Linuxexport GOOGLE_CLOUD_PROJECTyour-project-id把your-project-id换成你复制的真实 ID。临时变量关窗口就失效要永久生效Windows 在“系统属性 → 环境变量”里新建用户变量macOS/Linux 写进~/.zshrc或~/.bashrc。如果你同时用 TaoToken 做统一通道验证可以配一份 settings 片段把 Base URL、Key、Model ID 三件套写清楚。以 Gemini CLI 支持的配置目录为例在用户目录下建~/.gemini/settings.json{ projectId: your-project-id, apiBaseUrl: https://taotoken.net/api, apiKey: sk-your-taotoken-key, model: gemini-2.0-flash }注意apiBaseUrl填 TaoToken 的 API 地址https://taotoken.net/apiKey 在 TaoToken 控制台的 API Keys 页面生成Model ID 按你实际要调的模型填。这份 JSON 里的字段名以你本地 CLI 版本实际支持的为准改完保存。配完环境变量重启终端再echo %GOOGLE_CLOUD_PROJECT%Windows或echo $GOOGLE_CLOUD_PROJECTmacOS/Linux确认变量读到了。读不到就检查是不是写错了 shell 配置文件或者没重启终端。这一步的坑在于项目 ID 复制错、API 没启用、环境变量写进错误的配置文件。三个都排查一遍GOOGLE_CLOUD_PROJECT报错基本能消。4. 验证请求是否跑通用 TaoToken 统一 Key/API 通道对照装好、配好环境变量不代表调用真的通了。很多人gemini启动后看着正常一提问就报reading choices或 401说明请求根本没到模型。这一节给一套对照验证动作用 TaoToken 统一 Key/API 通道确认链路。先明确三件套Base URL、Key、Model ID。Base URL 用https://taotoken.net/apiKey 在 TaoToken 控制台 API Keys 页面生成Model ID 按你要调的模型填。这三样缺一不可且要和配置文件里的字段对齐。验证第一步用 curl 直接打一次 API绕开 CLI确认 Key 和通道本身是通的curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-your-taotoken-key \ -H Content-Type: application/json \ -d { model: gemini-2.0-flash, messages: [{role: user, content: ping}] }返回里有choices字段和内容说明 Key、Base URL、Model ID 三件套正确通道通。如果返回 401是 Key 错或没带Bearer返回 404是 Base URL 或路径错返回reading choices相关错误多半是响应结构没解析对检查 Model ID 是否被支持。验证第二步回到 Gemini CLI用同一套配置启动gemini启动后随便问一句比如“列出当前目录文件”。如果 CLI 能正常返回说明 CLI 侧的配置和通道都通了。如果 CLI 报错但 curl 通问题在 CLI 配置字段名或路径对照第 3 节的 settings 片段逐项核对。验证第三步看日志。Gemini CLI 一般会在用户目录下写日志报错时先看日志里的 HTTP 状态码和请求 URL。401 查 Keylocal proxy failed查本地网络或代理配置reading choices查响应解析和 Model ID。这套对照的价值在于把“CLI 问题”和“通道问题”分开。curl 通、CLI 不通就是 CLI 配置问题curl 也不通就是 Key 或通道问题。别一上来就重装 CLI先定位层。如果你长期做编码或 Agent 类任务可以考虑 TaoToken 的 Coding Plan把 Key 和额度统一管理省得每次换工具都重新配。验证模型是否可用也可以直接用模型对话页面快速试一次确认模型 ID 没写错。5. 登录失败与常见报错排查清单这一节把真实报错和对应动作列清楚照着查。报错一401 Unauthorized。含义是 Key 无效或没带认证头。排查确认Authorization: Bearer sk-xxx格式正确Key 没多空格没用到过期 Key。用第 4 节 curl 复测401 就重新生成 Key。报错二local proxy failed。含义是本地网络或代理配置让请求出不去。排查确认终端代理变量和系统代理一致端口没写错关掉代理直连试一次如果公司网络有限制换网络环境。注意代理变量是临时的换窗口要重设。报错三reading choices或响应解析失败。含义是返回结构不是预期的choices数组。排查确认 Model ID 被通道支持Base URL 路径带对/v1/chat/completions请求体 JSON 没语法错。用 curl 看原始返回别只看 CLI 的报错文案。报错四OAuth 登录卡住或授权后无响应。含义是浏览器授权回调没回来。排查确认默认浏览器能正常打开授权页授权后别关终端网络访问 Google 不稳定时这一步最容易卡换网络重试如果反复失败改用 API Key 方式走统一通道绕开 OAuth。报错五GOOGLE_CLOUD_PROJECT缺失。排查项目 ID 是否复制正确、API 是否启用、环境变量是否写进当前 shell 的配置文件、终端是否重启。四条逐一确认。报错六gemini: command not found。排查npm 全局目录是否进 PATHnpm config get prefix的输出路径是否在 PATH 里重装后是否重开终端。排查顺序建议先 curl 验通道再看 CLI 配置最后查网络和 OAuth。别跳步跳步容易在错误层反复折腾。踩过的坑里最常见的就是把通道问题当成 CLI 问题重装好几遍没用。6. 装好之后把 Key 和通道固定下来Gemini CLI 装好只是开始真正省心的是把 Key、Base URL、Model ID 固定成一份配置换工具、换机器都能复用。TaoToken 的 API Keys 页面可以统一管理 Key接入文档里有各工具的配置示例照着改字段就行。如果你主要做长期编码或 Agent 任务Coding Plan 能把额度集中管理比每次单独配 Key 稳。验证模型是否可用模型对话页面点一下就能试不用每次开终端。装完这一套GOOGLE_CLOUD_PROJECT和登录报错基本不会再拦你剩下的就是拿它干活了。