Gemini CLI 最反常识的地方是：它装起来只要一条 npm 命令，但装完大概率用不了。官方仓库第一行就写着「Enterprise Code Assist only」，只面向 Google Cloud 上的企业 Code Assist 许可证。免费个人访问和 Google AI Pro / Ultra，已经在 2026 年 6 月 18 日移到 Antigravity CLI 了。所以这篇 Gemini CLI 安装和使用教程要先把话说在前面：终端里敲命令之前，先确认自己手上有企业 Code Assist 许可证，或者一张能付费的 Gemini API key。
对做出海站的人来说，这件事卡的不是技术，是顺序。先看手上有什么账号，再决定装哪个 CLI。顺序反了，一晚上就耗在装环境、登录、排错上，最后发现卡在资质这一关。至于账号在你所在地区能不能正常开通和使用，以官方说明为准。
- 是什么：开源终端 AI 智能体，把 Gemini 的能力直接放进终端，Apache 2.0 许可证。
- 官方定位：企业 Code Assist 专用，免费个人访问和 Google AI Pro / Ultra 已经迁到 Antigravity CLI。
- 怎么装：npx 直接跑，或 npm 全局安装，macOS / Linux 还能用 Homebrew、MacPorts，受限环境用 Anaconda 建环境。
- 要多少钱：仓库里没有价格和免费额度，API 侧分 Free、Tier 1、Tier 2、Tier 3 四档，Tier 1 要绑有效结算账号。
它是什么、谁能用、怎么一步步装上、登录时设哪个变量、钱按什么算、报错往哪里回查，下面一节一节说。
本文目录
Gemini CLI 到底是什么，和 Antigravity CLI、Gemini API CLI 怎么分
Gemini CLI 是一个开源的终端 AI 智能体，把 Gemini 直接带进终端。你敲命令的那个窗口，就是它干活的地方，不用开浏览器，也不用切编辑器。
容易搞混的地方在于，Google 现在有三个名字相近的 CLI，官方仓库把它们分开定位，各自管一段人群。
三个 CLI 各管一段
Gemini CLI，命令是 gemini，面向拥有 Gemini Code Assist Standard 或 Enterprise 许可证的组织，以及 Google Cloud 上的 Code Assist for GitHub，另外加遗留的付费 API key 和 Vertex key。
Antigravity CLI，命令是 agy，是一个交互式多 agent 编码终端，用在 Gemini 4 Argon 及以上、免费账号或 Google AI Pro & Ultra 账号、以及 Google Cloud 上。
Gemini API CLI，命令是 gemini-api，是无状态的 API 命令行工具，不是一个编码 harness。它给 agent、脚本和 CI 提供直接调 Gemini 模型的命令，能跑模型、做媒体生成、分析文件、管托管 agent，但它不负责帮你改代码库这件事。
三个名字放在一排看，区别就清楚了：要企业许可证的是 Gemini CLI，免费和订阅账号走 Antigravity CLI，写脚本自动化调接口的是 Gemini API CLI。这几个工具和 Cursor、Claude Code、Codex、Copilot 之间怎么选，那篇对比讲得更细：Cursor、Claude Code、Codex、Copilot 怎么选。
它能干的活
官方列的功能有这么几类：查询和编辑大型代码库；用多模态能力从 PDF、图片、草图生成新应用；用自然语言调试排错；自动化运维任务，比如查 pull request 或者处理复杂的 rebase；用 MCP server 接新能力，包括接 Imagen、Veo、Lyria 做媒体生成；在脚本里非交互运行，接进工作流自动化。
这几件里，前两件对做独立站的人最实用。改一套主题或者插件目录，让它顺着自然语言指令去查、去改，比一个文件一个文件翻省事。从草图生成应用这条，用来做小工具原型也够。
开源与许可证
Gemini CLI 是完全开源的，Apache 2.0 许可证。仓库当前 Star 数 109k，Fork 数 14.9k。许可证宽松，意味着你可以读源码、改源码、做二次开发，商用也没有额外授权费用。开源不等于免费额度，这两件事得分开看。
装之前先确认：你有没有它的使用资格
官方在安装说明的第一行就把使用范围圈死了，只给两种东西：企业版 Code Assist 许可证，也就是 Standard 或 Enterprise，以及 Google Cloud 上的 Code Assist for GitHub。有这些权限的人装完，访问权限不变；没有的，就得走 API key 或 Vertex AI 那条付费路。
没有免费档，个人访问已经迁走
官方仓库写得明白，没有免费档，也不含 Google AI 套餐。免费的个人访问，以及 Google AI Pro 和 Ultra 这两个订阅档（走 Google One 的），已经在 2026 年 6 月 18 日移到 Antigravity CLI。
时间点要看清。迁移之前写的 Gemini CLI 教程，讲的是另一套账号体系，照着做到登录那一步会卡住。现在同一个 Google 账号登进去，个人订阅那部分额度是给 Antigravity CLI 用的。
不针对 Gemini 4 及以上优化，也别拿它做基准测试
官方写明，Gemini CLI 没有针对 Gemini 4 系列做优化，比如 Gemini 4 Argon，后续代际也没有。所以拿它跑新模型的活，不是这套工具的长处。
同一个原因带出第二条：官方明确说不要用 Gemini CLI 给 Gemini 模型做基准测试。理由是 harness 没有针对 Gemini 4 及以上调过，跑出来的分数不具代表性。要评模型，换专门的评测环境。
三条官方认证路径先对号
官方给了三种认证方式：用 Google 账号做 OAuth 登录；用 Gemini API Key，定位是需要特定模型控制或付费档访问的开发者；用 Vertex AI，定位是企业团队和生产负载。
选哪条看手上有什么。有组织发的付费 Code Assist 许可证，走第一条；自己买 API 用量，走第二条；已经在 Google Cloud 上跑生产，走第三条。三条的变量怎么设，后面第 4 节分开讲。
手上没有企业许可证，先看这两个替代品
核对完发现自己既没有企业许可证，也暂时不想开付费 API，那就别在 Gemini CLI 上耗时间。Codex 的路子可以看这篇：Codex AI编程工具测评。OpenCode 本体是免费的，适合先练手：OpenCode 本体免费。
分步装：Windows、macOS、Linux 各走哪条命令
Gemini CLI 走 npm 生态，所以顺序是先有 Node.js，再谈装 CLI。官方还给了推荐系统规格和更细的指南，入口是「Gemini CLI installation, execution, and releases」那一页。
第 1 步：装 Node.js，Windows 优先拿 .msi
Node.js 是免费、开源、跨平台的 JavaScript 运行时，拿来跑服务器、命令行工具和脚本都行。官方下载页当前给的是 v26.13.0 LTS，二进制、安装包和源码都在 nodejs.org/en/download/ 这个地址。
- 打开下载页，选对应系统的安装包。
- Windows 上尽量用 Windows Installer，也就是 .msi，做系统级安装。
- 只能用 .zip 或 .7z 做系统级安装时，把它解压到一个不可信用户写不进去的目录。
- 装完在终端敲 node -v，看有没有版本号输出。
这是第一步的原因很简单：CLI 本身是 npm 包，Node 不在，后面所有命令都跑不动。Windows 上那句「不可信用户不可写」，说的是安装目录的权限，别的已认证用户能往里写文件，就等于给了别人改你运行环境的入口。
出问题回查两件事：node -v 有没有输出；安装目录的权限是不是被放开过。下载目录里还有 SHASUMS256.txt.asc，带文件的 SHA 校验和和发布者 PGP 签名，介意完整性的可以校验一次。
第 2 步：五条安装路径，选一条走
- npx，免安装直接跑，适合只想试一次的。
- npm install -g @google/gemini-cli，全局安装，最通用的一条。
- brew install gemini-cli，macOS 和 Linux 上用 Homebrew。
- sudo port install gemini-cli，macOS 上用 MacPorts。
- 受限环境用 Anaconda：先 conda create -y -n gemini_env -c conda-forge nodejs 建环境，再在这个环境里用 npm 全局装。
这五条不是让你全装一遍。有 npm 就用第二条；macOS 上用 Homebrew 更省事；公司电脑装不了全局包，就退回 npx 或者 conda 环境。为什么会有五条，是因为受限环境和系统级安装各有各的适用面，官方干脆都列出来。
出问题回查两点：命令是不是在你要用的那个 shell 里执行的，比如在 PowerShell 里敲了 zsh 的写法；是不是被系统包管理器拦了，公司电脑常见。
第 3 步：验证装没装上
装完直接敲 gemini，能进交互界面就算通了。进不去，先看 PATH 里有没有全局 bin 目录。npm 全局装的包会落到一个固定目录，那个目录不在 PATH 里，命令就等于不存在。
想先不打扰它，用 gemini -p 加一句简单提问，看有没有文本返回。这个动作后面配 key 的时候还能用一次。
第 4 步：更新跟哪个通道
官方给三个发布通道。稳定版每周二 UTC 20:00 发布，是上周预览版的完整晋升加上 bug 修复和验证，用 latest 标签。预览版每周二 UTC 23:59 发布，未经完整审查，可能带回归或者其他未解决的问题。每日构建版每天 UTC 00:00 发布，来自 main 分支，应当假定里面有待验证的东西和问题。
日常做站跟 latest 就够了。预览版和每日构建适合要试新功能、能自己承担回滚成本的人。跟错通道拿到的是没审过的版本，出了问题也不好判断是环境还是版本。
更新之后不对劲，回查顺序是：先确认当前装的是哪个 tag，再看自己是全局包还是 npx 临时拉的，两者走的是不同路径，混着用会拿到两个版本。
登录授权：三种方式各要设哪个环境变量
装完第一次运行 gemini，它会让你选认证方式。三种方式的区别，说到底是你在告诉它，这次请求挂到哪个账号、哪个项目上。
方式一：Google 账号 OAuth
走 Google 账号这条路，先设项目 ID 再启动。在终端执行 export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"，把 YOUR_PROJECT_ID 换成自己的项目 ID，然后运行 gemini，按提示走浏览器登录。
用的是组织发的付费 Code Assist 许可证，这一步别跳。官方专门提醒过，用组织的付费许可证时要记得设 Google Cloud Project，不设的话登录过去挂的项目不对，额度也对不上。
方式二：Gemini API Key
从 aistudio.google.com/apikey 取 key，设成环境变量 GEMINI_API_KEY，再运行 gemini。官方推荐用环境变量配 key，客户端库会自动检测并使用。
有一个容易踩的点：GEMINI_API_KEY 和 GOOGLE_API_KEY 两个都设的时候，GOOGLE_API_KEY 优先。别让一个留在配置文件里没删的旧变量，把你的新 key 顶掉。
方式三：Vertex AI
从 Google Cloud Console 取 key，设 GOOGLE_API_KEY，同时把 GOOGLE_GENAI_USE_VERTEXAI 设成 true。这条是给企业团队和生产负载用的，个人做站一般用不到。
key 必须加限制，不加会被拒
这条现在比什么都重要。2026 年 5 月 28 日起，在 Google AI Studio 新建的 API key 自动就是授权 key，直接绑 Google Cloud 服务账号，请求以那个服务账号的身份处理，默认限制在 Generative Language API 上。
标准 key 如果没加限制，Gemini API 会直接拒绝它的请求；加了显式限制的标准 key 继续能用。官方另外公告过，从 2026 年 6 月 19 日起停止接受未加限制的 key 请求，理由是防未授权使用和账单风险。
加限制的动作在 AI Studio 里做：API Keys 页面找到标着 Unrestricted 的 key，鼠标移到那个标签上点 Add restrictions，选 Restrict to Gemini API only，点 Restrict key 确认。还要知道一点，AI Studio 只显示未加限制、或者限制到 Gemini API 的 key；你之前把 key 限制到别的 API 上，在这个页面里看不到，别以为 key 丢了。
还有一个方向相反的坑。如果这把 key 同时给别的 Google API 用（官方标注不推荐），你在 Cloud 控制台给它加上限制之后，它发的 Gemini API 请求反而会失败。
拿不到创建权限怎么办
Create API key 按钮点不动，提示「You do not have permission to create a key in this project」，说明缺 IAM 权限。加限制这个动作本身也需要项目上的 apikeys.keys.update 权限，它在 API Keys Admin 或 Editor 这类角色里。
处理顺序是：先找项目或组织的管理员，让他给你一个包含这些权限的角色，比如 Project Editor；管理员那边走不通，就建一个不与组织关联的新 Google Cloud 项目，在新项目里生成 key。
在 AI Studio 导入已有项目的路是这样：打开 AI Studio，从左侧面板进 Dashboard 选 Projects，点 Import projects，搜到要用的项目选中，点 Import。导入之后到 API Keys 页面，在这个项目里建 key。导入进来的项目可能要过项目验证才能用免费档，也可以直接设结算走付费档。
第一次配这些变量容易乱，入门的顺序在那篇里理过一遍：AI教程入门步骤。
装完怎么用：常用命令和配置放哪
五个最常用的参数
直接敲 gemini，它在当前目录启动。这是最常用的形态，先 cd 到项目根目录再敲。
- gemini --include-directories ../lib,../docs，一次带进多个目录，适合代码和文档分开放的项目。
- gemini -m gemini-2.5-flash，指定模型。
- gemini -p "Explain the architecture of this codebase"，非交互跑一句，拿纯文本回复，可以塞进脚本。
- 在上面这条后面加 --output-format json，拿到结构化结果。
- 要实时事件流就用 --output-format stream-json，出来的是按行分隔的 JSON 事件。
后面两个参数是给自动化用的。-p 加 json，适合把结果直接丢给下一步处理；stream-json 适合一边跑一边看进度。手工改代码的时候用不上它们。
斜杠命令和上下文文件
交互界面里用斜杠命令。官方文档的 Commands Reference 列了所有斜杠命令，比如 /help 看帮助、/chat 管会话。上下文靠 GEMINI.md 这个文件，官方叫 Context Files，你把项目约定、目录结构、哪几个文件不要动写进去，它每次都会读。另外还有 Checkpointing 和 Token Caching 两项，怎么开看官方文档的对应页。
扩展只走官方口
MCP server 配在 ~/.gemini/settings.json 这个文件里，用来给 Gemini CLI 加自定义工具。这是官方给的入口，配之前先把结构照文档抄一遍，别自己发明字段。Custom Extensions 和 IDE Integration 也各有官方入口，其中 IDE Integration 是 VS Code 的配套。
这里要克制一点。每接一个 MCP server，都是把外部的东西接进你的终端，它能读到什么、能执行什么，你自己得清楚。官方文档列出的工具入口还包括 Built-in Tools Overview、File System Operations、Shell Commands、Web Fetch & Search，先把内置的用熟，再考虑加。
出问题用 /bug 直接报
遇到说不清的问题，在 CLI 里敲 /bug，它会带着上下文把问题报出去。这比事后自己复述环境省事，也更容易被复现。
想先看看同类工具是怎么组织的，Claude Code 那篇可以对照着读：Claude Code 使用教程。
数字和限制：装它要花多少钱、卡在哪几道门槛
Gemini CLI 仓库里没有价格表，也没有免费额度数字。真正决定你花多少钱的，是你在 API 侧挂到哪个档位。Gemini API 按四个档位走，档位由资质条件决定，账单上限和花费速率限制跟着档位走。
| 档位 | 资质条件 | 账单档上限 | 每 10 分钟花费速率限制 |
|---|---|---|---|
| Free | 活跃项目或免费试用，部分项目需要验证 | 无账单档 | N/A |
| Tier 1 | 设置并关联有效结算账号 | $250 | $10 |
| Tier 2 | 已付费 $100 且距首次成功付款 3 天 | $2,000 | $200 |
| Tier 3 | 已付费 $1,000 且距首次成功付款 30 天 | $20,000 至 $100,000+ | $200 |
不绑结算账号就停在 Free 档，花费速率那一栏是 N/A，也就是没有这一项；绑了有效结算账号才进 Tier 1，才有按 10 分钟窗口滚动计算的花费上限。Tier 2 和 Tier 3 的资质看的是项目关联账单账号在 Google Cloud 服务上的累计总花费，不只是 Gemini API 这一项。从 Free 升到付费档必须先在 AI Studio 设置结算，Free 到 Tier 1 通常立即生效，后续档位升级在 10 分钟内生效。满足资格标准通常就够，极少数情况下升级申请会因为审核中发现的别的问题被拒。
还有三件事要知道。速率限制按项目算，不按 API key 算，同一个项目里开十把 key 也不会把额度摊薄。每日请求数（RPD）配额在太平洋时间午夜重置。实验性和预览版模型的速率限制更严格，正式模型和预览模型不能按一个标准算。
key 的安全有四条硬规矩。不要把 key 提交进 Git 这类源码管理；不要把 key 硬编码进网页或移动客户端，编译进客户端的 key 是能被抠出来的；从环境变量读，不要从配置文件读；生产环境把 key 放进 Google Cloud Secret Manager 这类密钥库，同时在 Cloud 控制台设账单提醒，用量或费用冲高时能收到通知。前两条官方写的是禁止，后两条是推荐做法，四条一起做才算配完。
如果你只是想在编辑器里用 AI 补全、不想折腾 API 计费，个人免费的通义灵码是另一个方向：通义灵码个人免费。
免费额度够不够做出海内容：官方口径下的答案
先纠正一个前提：Gemini CLI 本身没有免费档
把 Gemini CLI 当成一个有免费额度的工具，这个前提就错了。官方口径是没有免费档，也不含 Google AI 套餐，免费个人访问已经移到 Antigravity CLI。所以问「它的免费额度够不够撑内容生产」，问的是另一套账号体系。
走 API key 的话，Free 档没有花费速率这一项
绕开 CLI 直接用 Gemini API，Free 档的花费速率限制是 N/A，也就是没有这一项，同一栏要进付费档才开始有数字。这个差别对做内容的人有实际意义：Free 档没有花费上限，不等于能一直跑，它还有另外几个维度卡着。
用量是对每个限制分别评估的，超过任何一个都会触发速率限制错误。官方举的例子是 RPM 限制 20 的时候，一分钟内发 21 个请求就报错，哪怕 TPM 和其他限制都没超。
具体数值要看你自己的 AI Studio
各模型具体的 RPM、TPM、RPD 数值，官方速率限制页上没有一个个列，写的是这些限制取决于多种因素，并指向 AI Studio 里看当前生效的那一组。你登进自己的 AI Studio，看到的那组才是当下管着你账号的。
官方另外声明了两件事，一起记住：列出的速率限制不保证，实际容量会变化；申请提高速率限制不承诺一定能批，会尽力审核。
结论：按付费档做预算
想把 Gemini CLI 长期接进内容生产流程，按 Tier 1 的账单上限做预算，别按免费规划。这不是说一定要花满，是说做成本表的时候，别把一个不存在的免费档算进去。真要压开支，方向是缩上下文、缩输出、把能攒的批量任务攒起来跑，而不是等免费额度。
常见误区和排查：装不上、报错、额度超了分别查什么
误区一：以为还有免费个人额度
这条路已经关了。依据是官方仓库写明没有免费档，免费个人访问转到了 Antigravity CLI，同一个 Google 账号登进去拿到的是另一套东西。
误区二：拿它给 Gemini 模型做基准测试
跑出来的分数不能用来下判断。官方说得很直接：harness 没有针对 Gemini 4 及以上调优，分数不具代表性。
报错 429 RESOURCE_EXHAUSTED
这是命中基于花费的速率限制。处理顺序是先等一小段时间重试，再把昂贵请求的速率降下来，比如换更小的上下文窗口、让输出短一点，正常使用中持续命中才去申请提高速率限制。
报错 503
这个跟配额无关。Google 自己的说明里写着，503 表示服务暂时过载、处理不了请求。等一会儿再试，先别去改 key 和项目配置，改完反而分不清是哪一步起的作用。
Create API key 按钮是灰的
缺 IAM 权限，提示会直接写「You do not have permission to create a key in this project」。处理顺序前面写过：找管理员要 Project Editor 这类角色，走不通就建一个不与组织关联的新项目。
导入的项目用不了免费档
可能是项目没过验证。导入进 AI Studio 的项目，以及 AI Studio 之外创建的项目，都可能需要项目验证才能用免费档；另一条路是直接设结算走付费档。
AI Studio 里看不到某把 key
属于正常现象。AI Studio 只显示未加限制、或者限制到 Gemini API 的 key。限制到别的 API 上的 key 在这个页面里不出现，要去 Cloud 控制台的凭据页看。
用 AI 帮你整理安装清单和额度对照表
装完之后最容易乱的是三样东西：一堆安装命令分不清哪条对应哪个系统，三种认证方式的变量记混，四个档位的条件看不明白。这三件事都可以先交给 AI 整理出一版，你再核对。
AI 能帮的活有这么几步。一，把官方 README 里的安装命令按 Windows、macOS、Linux 分组，标出 npx、npm、Homebrew、MacPorts、Anaconda 五条路径。二，把三种认证方式和各自要设的环境变量整理成对照表。三，把速率限制的几个维度和四个档位整理成表格，对着自己的用量看。四，把 key 的安全规则整理成一份检查清单，覆盖不提交 Git、不硬编码进客户端、用环境变量、用 Secret Manager、设账单提醒。猎者出海的AI Agent 能接的就是这段，整理资料、对照官方文档，把散在几个页面里的条款归到一张表上，判断还是人来下。
三条提示词可以直接抄，这是本文给的示例，不是官方模板：
- 「下面这段是 Gemini CLI 官方 README 的安装部分，请按 Windows、macOS、Linux 三类系统把安装命令分组，每条命令后面用一句话说明它做了什么，不要补充原文没有的命令。」
- 「请把 Gemini CLI 的三种认证方式整理成三列表格：认证方式、需要设置的环境变量、官方原文里写的适用对象。只用手头这段原文，原文没写的格子留空。」
- 「请把 Gemini API 速率限制的四个用量档位整理成表格，列出资质条件、账单档上限、每 10 分钟花费速率限制三列，数字原样保留，不要换算单位。」
有三件事必须人自己做，AI 替不了。先说最关键的，去 Google AI Studio 的 API Keys 页面看自己的 key 是不是标着 Unrestricted，标了就点 Add restrictions 选 Restrict to Gemini API only。还有个事儿，去 AI Studio 的 Projects 页面看当前是哪个用量档位，据此判断要不要先设置结算。最后，在终端里跑一次 gemini -p 加一句简单提问，看有没有正常返回文本，返回正常了再去配 MCP 和自定义命令。
别指望 AI 一步做到位。它给的是初稿，最后那一下点鼠标、敲命令、看返回值的还是你。
常见问题
Gemini CLI 还有免费额度吗
没有了。官方写明没有免费档，也不含 Google AI 套餐，免费个人访问已经移到 Antigravity CLI。想继续用，走企业 Code Assist 许可证或者付费 API key。
Gemini CLI 和 Antigravity CLI 怎么选
手上有企业 Code Assist 许可证，用 Gemini CLI。要 Gemini 4 Argon 及以上、用的是免费账号或 Google AI Pro & Ultra 账号，或者跑在 Google Cloud 上，用 Antigravity CLI。
Gemini CLI 和 Gemini API CLI 有什么区别
Gemini CLI 是终端编码 agent，能读能改代码库。Gemini API CLI 是无状态的 API 命令行工具，不是编码 harness，主要给 agent、脚本和 CI 直接调模型。
怎么卸载 Gemini CLI
官方有单独的 Uninstall Guide，按上面的步骤走。卸载前先确认有没有别的项目在共用那个全局 npm 包目录。
API key 泄露了怎么办
按顺序处理：先生成新 key，再用新 key 部署代码，然后停用或删除泄露的那把，最后审计用量。新 key 完全生效之前不要删旧的，不然应用会中断。
每日配额什么时候重置
太平洋时间午夜。不是按你自己电脑上的零点算，跨时区的读者要换算一下。
回到最开始那个问题：Gemini CLI 现在是给企业 Code Assist 用的一套终端工具，不是谁都能白用。装之前先看资质，装的时候盯住 Node.js 和安装路径，装完把 key 限制好、把档位摸清楚。猎者出海的AI Agent 只能帮你把散在几个页面里的条款整理到一张表上，账最后还是得自己看。
发表评论