google-gemini/gemini-cli · 上手攻略

• 仓库：google-gemini/gemini-cli
• 链接：https://github.com/google-gemini/gemini-cli
• 分类：ai
• 作者：Jay
• 更新：2026-07-11

这是什么

gemini-cli 是 Google 官方开源的终端 AI Agent 工具，将 Gemini 模型的能力直接带入命令行。简单说：你在终端里敲自然语言，Gemini 替你读写文件、跑 shell 命令、搜网页、执行代码。零配置，开箱即用，免费额度可观（个人 Google 账号 60 请求/分钟，1000 请求/天）。

完全开源（Apache-2.0），不绑死在 Google 生态——你也可以接自己的 API Key 走付费路线。

解决什么问题

• 本地代码库问答：不问 ChatGPT，直接在终端里对本地代码库发问
• Git 工作流加速：git diff 是什么、昨天改了什么、一个 rebase 怎么搞，用自然语言搞定
• 多步自动化任务：发 PR 查询、处理 issue、生成文件，一条命令搞定
• MCP 扩展：通过 Model Context Protocol 接入任意 MCP 服务器，Gemini 的工具集可自定义
• Google Search grounding：Gemini 的回答可实时接地气到 Google 搜索结果，不瞎编
• 跨平台：macOS、Windows、Linux 都能跑，Node.js 环境即可

快速安装

系统要求

安装方式（三选一）

# 方式 1：npx（无需安装，临时运行）
npx @google/gemini-cli

# 方式 2：npm 全局安装
npm install -g @google/gemini-cli

# 方式 3：Homebrew（macOS/Linux）
brew install gemini-cli

提示：Gemini CLI 在 Google Cloud Shell 和 Cloud Workstations 上预装了，可直接跑。

发布频道

# 稳定版（每周二 UTC 20:00 发布，推荐）
npm install -g @google/gemini-cli        # 默认即 stable
npm install -g @google/gemini-cli@latest # 显式 stable

# 预览版（每周二 UTC 23:59 发布，未完全测试）
npm install -g @google/gemini-cli@preview

# 每日构建（每天 UTC 00:00，自动取 main 分支）
npm install -g @google/gemini-cli@nightly

核心用法

认证配置（三选一）

方式 1：Google 个人账号（最推荐，免费额度高）

gemini
# 按提示登录 Google 账号即可
# 免费额度：60 请求/分钟，1000 请求/天
# 自动使用 Gemini 3 模型 + 1M token 上下文

方式 2：AI Studio API Key（适合开发者）

# 从 https://aistudio.google.com/apikey 获取 Key
export GEMINI_API_KEY="YOUR_API_KEY"
gemini
# 免费额度：1000 请求/天（Gemini 3 flash + pro 混合）

方式 3：Google Cloud（企业用户）

export GOOGLE_API_KEY="YOUR_API_KEY"
export GOOGLE_GENAI_USE_VERTEXAI=true
gemini
# 适合企业团队，有更高限额和安全合规功能

基础交互

# 进入交互式对话
gemini

# 指定目录扫描（注意逗号后不能有空格）
gemini --include-directories ../lib,../docs

# 指定模型
gemini -m gemini-2.5-flash

# 简单文本问答（非交互式）
gemini -p "Explain the architecture of this codebase"

# 结构化 JSON 输出（适合脚本解析）
gemini -p "Explain the architecture of this codebase" --output-format json

# 流式 JSON 事件（适合监控长时任务）
gemini -p "Run tests and deploy" --output-format stream-json

实战例子

# 在当前目录启动 Gemini 帮你写代码
cd new-project/
gemini
> Write me a Discord bot that answers questions using a FAQ.md file

# 对代码库发问（无需复制粘贴）
git clone https://github.com/google-gemini/gemini-cli
cd gemini-cli
gemini
> Give me a summary of all of the changes that went in yesterday

MCP 扩展

Gemini CLI 支持 MCP 协议，可接入任意 MCP 服务器，例如接入 Google Cloud 的媒体生成（MCP for Imagen、Veo、Lyria）：

# 参考 https://github.com/GoogleCloudPlatform/vertex-ai-creative-studio/tree/main/experiments/mcp-genmedia

自定义上下文文件（GEMINI.md）

在项目根目录放 GEMINI.md，Gemini CLI 启动时自动加载，为该项目提供持久上下文：

# 项目根目录
echo "# My Project Context" > GEMINI.md
gemini

GitHub Action 集成

Gemini CLI 有官方 GitHub Action，可用于自动化 PR 审核、Issue 分类等：

# 参考：https://github.com/google-github-actions/run-gemini-cli

典型适用场景

1. 开发者日常：不切出终端就能问代码、查文档、调试问题
2. Code Review 加速：把 PR diff 丢给 Gemini，先过一遍基础问题再人工审
3. Git 历史探索："这个函数上次改是什么时候，为什么改"，用自然语言查 git 历史
4. 一次性任务脚本：需要写个临时脚本处理数据，用 Gemini 边聊边写
5. Claude Code 备选：如果你不需要 Claude Code 的 Agent 深度操作，只需要轻量终端 AI 助手，Gemini CLI 更轻

坑与注意

1. 系统要求较新：macOS 要求 15+，Windows 要求 24H2+，旧系统用户可能无法安装
2. Node.js 20+ 强制：老系统上可能需要先升级 Node
3. 重度使用建议 16GB RAM：官方明确说 4GB 只能做轻度会话，大代码库场景容易爆
4. 免费额度是按请求数而非 token 数：个人账号 1000 次/天，对高频用户可能不够
5. Google Search grounding 需要联网：离线场景功能受限
6. preview/nightly 版本不稳定：生产环境建议用 stable，不确定版本建议显式 @latest
7. MCP 生态仍在完善：部分 MCP 服务器配置较复杂，需要参考具体服务器文档

与同类对比

Gemini CLI 最大优势：免费额度高 + 1M token 上下文 + MCP 可扩展。如果你的需求是"在终端里问问问题"，不需要 Claude Code 那种"替我做修改"的深度 Agent 能力，gemini-cli 是更轻量的选择。

一句话推荐

零配置、开箱即用、免费额度厚道——如果你在终端里花大量时间，gemini-cli 是目前门槛最低、质量最高的免费 AI 助手，还能通过 MCP 不断扩展能力边界。