安装、认证和第一次启动
Gemini CLI 起步流程：安装方式、认证选择、第一次运行和低风险只读任务。
Gemini CLI 上手不要先追复杂配置。第一目标是：确认本机能启动、认证能通过、能在一个项目里完成低风险只读任务。
第一次启动的目标不是证明它“能改代码”，而是证明它能在你的环境里稳定读取上下文、遵守只读边界，并把下一步说清楚。
安装前检查
先用 node --version 和 npm --version 确认 Node 环境。
Gemini CLI 是 Node/npm 生态里的 CLI。官方常见入口包括 npx（临时运行 npm 包的命令）和全局安装。
起步时还要顺手看三件事：
| 检查项 | 为什么要看 |
|---|---|
node --version | Node 过旧或来源混乱会导致 CLI 和依赖报错 |
npm config get prefix | 全局安装后 gemini 是否能进 PATH |
| 当前网络 / 代理 | 登录、证书、npm 安装和 web 工具都会受影响 |
运行方式
临时运行（不写入全局 node_modules）：
npx @google/gemini-cli全局安装（每次直接 gemini 启动）：
npm install -g @google/gemini-cli@latest
gemini全局安装适合长期使用；npx 适合临时体验或确认环境。两者背后都是同一个官方包 @google/gemini-cli，按官方 安装页 的当前推荐为准。
认证方式怎么选
常见认证入口有三类：
- Google 登录：适合个人体验 Gemini Code Assist 能力。免费层每天约 1000 次模型请求，Gemini CLI 自动选模型。
- Gemini API Key：适合脚本、第三方工具和轻量自动化（headless，无人值守环境）。注意 Free 层每天 250 次且只能用 Flash 模型——要用 Pro / Auto 必须切付费。
- Vertex AI：适合企业、云项目、统一账单和 IAM（Identity and Access Management，身份与访问管理）治理。Express 模式免费但 90 天后必须 enable billing。
如果只是第一次学习，先用官方默认登录流程即可。要进入 CI、GitHub Action 或第三方 agent 集成时，再使用 API key 或 Vertex AI。
| 使用场景 | 更适合的认证入口 |
|---|---|
| 本机交互体验 | Google 登录 |
| 简单脚本和 headless | Gemini API Key |
| 企业项目、统一账单、IAM | Vertex AI |
| GitHub Action | Secret / Workload Identity / 项目级认证策略 |
第一次启动
进入一个低风险目录：
可以新建 gemini-cli-test 目录，进入后运行 gemini。
第一次不要让它修改文件，先问只读问题：
第一次 prompt 可以是：请只读分析当前目录，说明这里有哪些文件、你能看到什么、下一步建议我怎么组织项目。
如果当前目录为空，可以让它生成一个计划，不要直接生成大量文件。
第一次启动后看什么
启动成功不等于配置完成。先检查这几个信号：
- 它是否能说清当前目录里有什么。
- 它是否遵守"只读、不修改"的要求。
- 它是否会主动说明需要哪些文件和验证命令。
- 它是否把认证、配额或网络问题直接暴露出来。
- 它是否把不确定的地方标出来，而不是硬猜。
跑通第一条只读任务后，立即用 /init 让 Gemini CLI 自动生成首份 GEMINI.md。它会扫描项目结构、入口文件、检查命令，写一份初稿放在项目根目录。你只需要补"禁止触碰的文件 / 团队协作边界"等人类才知道的规则，比从零写更省事。详见 GEMINI.md 篇。
在真实项目里第一条 prompt
进入真实项目后建议这样开始：
进入真实项目后的第一条 prompt 建议是：请先只读扫描当前项目，不要修改文件，不要执行写入命令。请说明项目技术栈、入口文件、测试命令、构建命令和潜在风险。
这个 prompt 的关键不是措辞，而是边界：只读、不修改、不执行写入命令、先产出判断。
常见起步问题
geminicommand not found：检查全局 npm bin 是否在PATH。- 登录失败：先看账号地区、组织 entitlement、
GOOGLE_CLOUD_PROJECT环境变量。 - 429：说明请求或配额触顶，先降低频率。
- CI 里不进交互模式：检查
CI或CI_前缀环境变量。
第一次成功标准
第一次成功不是“能打开欢迎界面”，而是完成一条只读任务，并能看到当前目录、认证状态、模型或配额提示、下一步建议。建议把这次结果截图或记录下来，作为后续排障基线。
如果后续换了 Node、npm prefix、代理、账号或 Cloud project，先和这条基线对比。
认证基线
第一次启动后要知道自己用的是哪条认证链路。Google 登录、Gemini API Key、Vertex AI、Cloud Shell 和 GitHub Action secret 的排错路径不同。比如 API key 更适合 headless 和脚本，Vertex AI 更适合企业项目和 IAM，Google 登录更适合个人交互体验。
教程里不要把一种认证方式的 UI、配额和隐私边界写成所有读者都会看到的结果。每篇涉及认证的页面都要说明“以你的账号实际可见为准”。
官方资料
- 官方安装：docs/get-started/installation.mdx
- 官方认证：docs/get-started/authentication.mdx
- Quickstart：docs/get-started/index.md
- 配额与定价：docs/resources/quota-and-pricing.md