Gemini CLI 保姆级部署教程：Google 开源终端 AI 编程助手从零到一完整搭建

Gemini CLI 是 Google 官方开源的终端 AI 编程 Agent，截至本文写作时在 GitHub 上收获约 10.9 万 Star，main 分支几乎每天都有提交。它跑在你的终端里，能读代码库、写文件、跑命令、查网页、调 MCP 工具，是 Google 官方对标 Claude Code 的开源终端工具。

重要提示（README 原文）：从 2026 年 6 月 18 日起，Gemini CLI 的免费个人额度和 Google AI Pro / Ultra 订阅已迁移到 Antigravity CLI。现在这个仓库主要面向有 Gemini Code Assist Standard / Enterprise 企业许可的组织，以及用 legacy paid API / Vertex 密钥的开发者。本文按官方 README 给出的安装与配置方式撰写，同时如实标注这一变化。

一、项目介绍与适用场景

Gemini CLI 是一个终端 TUI 形态的 AI Agent：你在项目目录敲 gemini，进入对话界面，用自然语言下任务，它读你的代码、改文件、跑命令。适合：

企业用户：已经买了 Gemini Code Assist Standard / Enterprise，需要在终端里用。
API 开发者：想用 Gemini API Key 按量付费，在终端里直接调 Gemini 模型。
Google Cloud 用户：走 Vertex AI 接入，享受企业级安全合规和更高配额。
CI/CD 场景：用 headless 模式把 Gemini 嵌进脚本和流水线。

二、核心功能逐条拆解

代码理解与生成：查询和编辑大型代码库；用多模态能力从 PDF / 图片 / 草图生成新应用。
自动化运维：查 PR、处理复杂 rebase、跑脚本。
MCP 扩展：通过 MCP 服务器接 Imagen、Veo、Lyria 等 Google 官方工具。
Headless 脚本模式：gemini -p "..." 零交互执行，--output-format json 拿结构化输出。
GEMINI.md 上下文文件：在项目里放 GEMINI.md 写项目约定，Gemini CLI 自动加载。
Checkpointing：保存和恢复对话。
Token 缓存：优化 token 用量。
沙箱与信任目录：按目录配置执行策略。
三档发布渠道：stable（每周二晚）、preview（每周二新功能）、nightly（每日）。

三、全套官方链接

类型	链接
GitHub 仓库	https://github.com/google-gemini/gemini-cli
官方文档	https://www.geminicli.com/docs/
npm 包	https://www.npmjs.com/package/@google/gemini-cli
License	Apache-2.0

四、硬件与环境前置要求

Gemini CLI 是 Node.js 包，资源占用极小：

操作系统：任意能跑 Node.js 的系统（macOS / Linux / Windows）。
Node.js：Node 18+。
账号：企业 Code Assist 许可、Gemini API Key、或 Vertex AI 凭证三选一。
网络：调 Google API 需能访问 Google 服务。

五、多平台安装步骤

5.1 无需安装（npx）

官方 README 原文：

npx @google/gemini-cli

5.2 npm 全局安装

npm install -g @google/gemini-cli

5.3 Homebrew（macOS / Linux）

brew install gemini-cli

5.4 MacPorts（macOS）

sudo port install gemini-cli

5.5 Conda（受限环境）

官方 README 原文：

conda create -y -n gemini_env -c conda-forge nodejs
conda activate gemini_env
npm install -g @google/gemini-cli

5.6 发布渠道选择

官方 README 给出三档：

npm install -g @google/gemini-cli@latest   # 稳定版（每周二 UTC 20:00）
npm install -g @google/gemini-cli@preview  # 预览版（每周二新功能）
npm install -g @google/gemini-cli@nightly  # 每日版（main 分支最新）

六、配置文件全部参数解释

6.1 三种认证方式（全部来自官方 README）

方式一：Google 账号 OAuth 登录（企业 Code Assist 用户）：

export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
gemini

方式二：Gemini API Key（官方推荐给需要指定模型或付费的开发者）：

# 从 https://aistudio.google.com/apikey 拿 Key
export GEMINI_API_KEY="YOUR_API_KEY"
gemini

方式三：Vertex AI（企业团队和生产负载）：

export GOOGLE_API_KEY="YOUR_API_KEY"
export GOOGLE_GENAI_USE_VERTEXAI=true
gemini

6.2 常用 CLI 参数

参数	作用	示例
（无参数）	进入交互式 TUI	`gemini`
`--include-directories ../lib,../docs`	多目录纳入上下文	`gemini --include-directories ../lib`
`-m gemini-2.5-flash`	指定模型	`gemini -m gemini-2.5-flash`
`-p "问题"`	非交互单轮提问	`gemini -p "解释这个代码库架构"`
`--output-format json`	结构化 JSON 输出	`gemini -p "..." --output-format json`
`--output-format stream-json`	流式 JSON 事件	`gemini -p "跑测试部署" --output-format stream-json`

6.3 MCP 服务器配置

在 ~/.gemini/settings.json 里配置 MCP 服务器，启动后就能在对话里用 @github 列出我的 PR 这类指令。

七、启动、后台与日常使用

7.1 启动

cd your-project
gemini

首次启动会引导你选认证方式。预期：进入 TUI 对话界面。

7.2 Headless 脚本模式

gemini -p "解释这个代码库的架构" --output-format json | jq .

可直接接进 CI/CD 流水线。

7.3 修改端口

Gemini CLI 是客户端，不监听端口；走 Vertex 或本地代理时改对应环境变量。

八、功能实操教程

第 1 步：用 npm install -g @google/gemini-cli 装好。

第 2 步：从 https://aistudio.google.com/apikey 拿一个 API Key，export GEMINI_API_KEY=...。

第 3 步：cd 到一个真实项目，敲 gemini。

第 4 步：在输入框里写「给我总结一下昨天的改动都进了哪些 PR」。它会读 git log、调 API 查 PR。

第 5 步：试指定模型：gemini -m gemini-2.5-flash 启动，看速度差异。

第 6 步：试 headless：gemini -p "列出所有 TODO 注释"。零交互输出，可接 jq 处理。

第 7 步：在项目根建 GEMINI.md，写「本仓库用 pnpm，提交前必须跑 pnpm lint」。下次启动 gemini 它会自动读这份约定。

九、全套报错故障排查

报错 1： gemini: command not found 原因分析：npm 全局 bin 不在 PATH。解决方案：npm config get prefix 看全局目录，确保 $(npm config get prefix)/bin 在 PATH。

报错 2： 启动后提示认证失败。原因分析：没 export API Key 或 Key 过期。解决方案：重新 export GEMINI_API_KEY=...；确认 Key 在 https://aistudio.google.com/apikey 有效。

报错 3： 走 Vertex 报 403。原因分析：没设 GOOGLE_GENAI_USE_VERTEXAI=true 或项目权限不对。解决方案：三个环境变量一起 export：GOOGLE_API_KEY、GOOGLE_GENAI_USE_VERTEXAI=true、GOOGLE_CLOUD_PROJECT。

报错 4： 调用超时。原因分析：网络访问 Google API 不通。解决方案：检查代理；国内网络需要走能访问 Google 的通道。

报错 5： 免费额度用完了。原因分析：README 明确——免费个人额度已迁移到 Antigravity CLI。解决方案：按官方提示改用 Antigravity CLI，或买 Code Assist 企业版 / 走付费 API。

十、升级、回滚与卸载

升级：npm install -g @google/gemini-cli@latest 或 brew upgrade gemini-cli。

备份建议：配置在 ~/.gemini/（含 settings.json、MCP 配置、对话历史），整个目录打包。

回滚：npm install -g @google/gemini-cli@具体旧版本号。

卸载：npm uninstall -g @google/gemini-cli；按官方卸载指南 https://www.geminicli.com/docs/resources/uninstall 清理残留。

十一、商用许可与合规风险提示

Gemini CLI 采用 Apache-2.0，可自由商用、二次开发。但有几点必须注意：

官方定位已转向企业：README 明确写「Designed for Gemini Code Assist Standard / Enterprise licenses」，免费个人版已迁到 Antigravity CLI。个人用户现在装它，要么买企业版，要么走付费 API。
模型 API 费用：Google 按 token 计费，团队大量使用要做预算；Vertex AI 走企业级合规。
数据合规：把公司代码喂给 Google API 时，确认你的 Google Cloud 合同里数据是否用于训练；敏感代码走 Vertex AI 企业承诺条款。
MCP 扩展：官方提供的 Imagen / Veo / Lyria 扩展另有计费，单独看对应产品条款。

参考链接

GitHub 仓库：https://github.com/google-gemini/gemini-cli
官方文档：https://www.geminicli.com/docs/
安装指南：https://www.geminicli.com/docs/get-started/installation
认证指南：https://www.geminicli.com/docs/get-started/authentication
npm 包：https://www.npmjs.com/package/@google/gemini-cli