深色模式
Gemini CLI 安装与配置教程：Windows、macOS、Linux、API Key 和 429 排错（2026）
Gemini CLI 适合在终端里阅读项目、解释代码、生成修改建议和执行受控的开发任务。安装命令、登录方式和模型权限会随官方版本变化，本文提供一套可复用的核验流程：先确认 Node.js 与官方包，再选择登录或 API Key，最后用最小请求验证额度和权限。
发布前请打开 Gemini CLI 官方仓库 和 Gemini API 文档，以当前 README、模型目录和账号页面为准。
需要兼容多模型的终端入口？
可以查看 ZeoGPT 注册入口，登录后核对当前是否提供 Gemini、Codex 或其他编程 Agent。ZeoGPT 是独立第三方服务，不是 Google 或 Gemini 官方；模型、额度、日志、价格和数据规则以实时页面与服务条款为准。
安装前准备
准备一台能运行 Node.js 的 Windows、macOS 或 Linux 电脑，并确认：
- Node.js 版本满足官方仓库当前要求；
- 终端能运行
node和npm； - 项目目录已经用 Git 或其他方式备份；
- 不把含密码、API Key 或客户数据的目录直接交给 CLI 读取；
- 登录账号、API Key 和项目权限属于你自己。
检查版本：
bash
node --version
npm --version如果版本太旧，先按 Node.js 官方方式升级，再安装 CLI。不要为了绕过版本检查强行使用旧包；命令能运行不代表模型和工具可用。
安装 Gemini CLI
官方包名和安装方式可能更新，当前常见方式是通过 npm 安装：
bash
npm install -g @google/gemini-cli
gemini --version如果全局目录没有加入 PATH，Windows 可以重新打开 PowerShell；macOS/Linux 可以检查 npm 的 global bin 路径。遇到 command not found 或“不是内部或外部命令”，先解决 PATH，不要重复安装一堆同名包。
需要固定版本时，可以记录 npm list -g @google/gemini-cli 的版本和 Node.js 版本，便于团队复现。生产团队不要让 CLI 自动升级到未经测试的版本。
首次运行：登录与 API Key 两条路线
进入项目目录运行：
bash
gemini如果终端提示浏览器登录，按官方页面完成授权，并确认登录的是正确 Google 账号。若团队使用 API Key，则在当前终端配置环境变量：
Windows PowerShell：
powershell
$env:GEMINI_API_KEY = "你的 API Key"
geminimacOS/Linux：
bash
export GEMINI_API_KEY="你的 API Key"
gemini不同版本可能使用 GOOGLE_API_KEY、登录凭据或项目选择器。以 CLI 当前提示和官方 README 为准；不要同时设置多个变量后猜测到底用了哪一个。生产环境用系统 Secret、CI Secret 或云平台密钥服务保存 Key，不要写进项目文件。
第一次任务建议这样做
先让 CLI 读取一个不含敏感信息的小目录，明确它只能分析还是允许修改：
text
先不要修改文件。请列出当前目录的主要文件、语言和可能的构建命令。
如果某一步需要执行命令，先说明命令和目的，等待我确认。确认目录范围后，再逐步要求：
- 解释一个函数并指出边界条件；
- 为已有测试补充一个失败用例；
- 生成补丁但不自动提交；
- 执行构建并只报告失败原因。
把“阅读、计划、修改、运行测试”分成几轮，比一开始让 CLI 自由操作整个硬盘更容易审查。
常见报错排查
| 现象 | 优先检查 | 处理办法 |
|---|---|---|
command not found | Node.js、npm PATH、全局安装位置 | 重开终端，检查 global bin，确认包名 |
| 登录循环或授权失败 | 浏览器账号、组织策略、缓存会话 | 清理旧会话，确认账号和官方授权页 |
| 401 / invalid key | 环境变量、Key 是否撤销 | 只保留一个变量，重新创建并重启终端 |
| 403 / permission denied | 项目、地区、模型和组织权限 | 在 AI Studio/Cloud 控制台核对项目与 API 是否启用 |
| 429 / quota exceeded | RPM、TPM、并发、免费层或账单 | 降低并发，缩短上下文，查看 Usage 和 Rate limits |
| 模型不存在 | 旧模型别名或账号未开放 | 从当前模型目录复制精确 ID |
| 修改了不该改的文件 | 工作目录范围过大 | 先备份，使用 Git 分支，限制工具权限 |
429 不一定是网络问题。连续重试会让情况更糟，应该先减少并发和上下文，等待退避时间后再测试。400 则优先检查参数和请求结构；401/403 应先解决凭据和权限。
API Key 安全清单
- 不在终端录屏、Issue、聊天记录或公开仓库中显示 Key；
- 不把
.env、凭据目录和客户文件交给 CLI 自动读取； - 开发、测试和生产使用不同项目或 Key；
- 给 CLI 使用的目录设置明确边界，敏感目录不放在工作区；
- 发现泄露后立即撤销旧 Key，并检查 Usage 与账单；
- 让 CLI 生成补丁后人工审查，再运行测试和部署。
Gemini CLI 与 Gemini API 的关系
CLI 是开发工具，API 是程序接口。CLI 的登录、额度、模型和本地工具权限，不等于你的后端 API 项目权限。需要在程序里调用 Gemini 时，应阅读本站的 Gemini API Key 与 400/429 排错教程，并在官方模型页面确认实际 model ID。
需要把不同模型接进同一工作流时，可以参考 MCP 多工具配置教程，但每个客户端的配置文件和权限边界仍要单独核对。
常见问题
Gemini CLI 能直接使用 ChatGPT 或 GPT-6 吗？
不能把其他提供商的模型 ID 直接填到 Gemini CLI。跨模型工作流要使用对应客户端或兼容网关的明确配置，并分别管理凭据、额度和数据政策。
免费额度用完后怎么办？
打开 AI Studio 或 Cloud 控制台查看当前项目的 Usage、Rate limits 和 Billing。不同模型、地区和账号的规则可能不同，不要把旧文章里的固定次数当成今天的承诺。
CLI 会自动上传整个项目吗？
取决于当前版本、命令和你授权的工具范围。运行前先读官方说明，限制工作目录，不要把密钥、客户资料和内部代码放在可读取范围内。