gemini-cli 完全指南：从安装到打造你的终端 AI 助手

终端里的 AI 搭档：gemini-cli 到底是什么

你每天在终端里敲多少命令？查日志、搜文档、改配置、写脚本……遇到不熟悉的命令还得切到浏览器去搜，回来上下文全断了。

gemini-cli 就是来解决这个痛点的。它是一个开源的 AI 代理，直接跑在你的终端里——不打开网页、不切换窗口，在命令行里就能跟 Gemini 模型对话。它能看懂你的代码库、帮你写命令、解释报错、甚至自动执行操作。

说白了，它把你和 AI 之间的交互压缩到一行命令的距离。

它跟 ChatGPT 网页版有什么区别？

区别大了。网页版你得复制粘贴代码、手动描述上下文、再复制结果回来。gemini-cli 直接活在你的项目目录里——它能读取你整个代码库，知道你在哪个目录、有什么文件、当前在做什么。

举个例子：你在调试一个 Node.js 项目，遇到一个诡异的报错。用网页版你得复制报错信息、描述项目结构、贴相关代码。用 gemini-cli，你只需要：

gemini "解释一下这个报错，并给出修复方案"

它已经知道你当前目录下的所有文件，能直接定位到报错行，给出针对性的建议。

它能干什么？

看懂你的代码。加载整个项目目录，问它"这个函数在哪里定义的""这段逻辑有没有 bug""帮我重构这个模块"。它理解你的项目结构，不是瞎猜。

帮你写命令。记不住 find 的复杂参数？直接说"找到最近三天修改过的 .py 文件"，它给你生成命令，你确认后执行。

自动化操作。写个脚本，让它非交互式地处理任务——比如每天自动分析 PR、生成摘要、发到群里。

实时联网。内置 Google 搜索能力，问它"最新的 Python 3.13 有什么新特性"，它能去搜了再回答你。

扩展能力。通过 MCP 协议接入图片生成、视频分析等工具——你在终端里就能让 AI 画图。

为什么免费？

Google 给个人账号提供了免费额度：每分钟 60 次请求，每天 1000 次。对日常开发来说完全够用。如果你需要更高频率，可以升级到付费方案。

谁该用这个工具？

• 日常跟终端打交道的开发者——省掉切窗口查文档的时间
• 需要快速理解陌生代码库的人——接手项目、做 code review 时特别有用
• 写脚本做自动化的人——把 AI 集成到工作流里
• 想试试 Gemini 模型但不想开网页的人——终端就是你的入口

前置条件

你只需要三样东西：

1. 一台装了 Node.js 18+ 的电脑（macOS / Linux / Windows 都行）
2. 一个 Google 账号（用来登录或获取 API Key）
3. 终端能联网

下一章我们就直接上手安装——选一种方式，5 分钟跑起来。

先确认一件事：你的电脑上已经装了 Node.js。没装的话，去 nodejs.org 下载 LTS 版本，装完在终端跑 node --version，看到版本号就说明环境就绪了。

gemini-cli 本质上是一个 npm 包，所以安装方式围绕 Node.js 生态展开。三种方法任选一种，效果完全一样——装好之后你都能在终端敲 gemini 启动它。

---

方法一：npx 直接跑（最快，不占硬盘）

这是最偷懒的方式，连安装都省了：

npx @google/gemini-cli

npx 会自动从 npm 仓库拉取最新版 gemini-cli，缓存到临时目录，然后直接运行。跑完这次，下次再用 npx @google/gemini-cli 还是会检查更新，确保你始终用最新版。

适合场景：只想尝鲜、临时用一次、或者不想污染全局环境。

注意：第一次跑 npx 会下载包体（大约几十 MB），取决于网速，等十几秒到一分钟。如果卡住不动，检查网络或换个 npm 镜像源。

---

方法二：npm 全局安装（推荐，一劳永逸）

如果你打算长期使用，全局安装最省心：

npm install -g @google/gemini-cli

装完后直接敲：

gemini

就能启动。以后要升级，跑：

npm update -g @google/gemini-cli

适合场景：日常开发、频繁使用、想用 gemini 命令而不是 npx @google/gemini-cli。

常见问题：如果你遇到 command not found: gemini，说明 npm 全局安装路径没加到 PATH 里。先跑 npm root -g 查看全局安装目录，比如 /usr/local/lib/node_modules，然后把对应的 bin 目录（通常是 /usr/local/bin）加到 shell 配置文件（.zshrc 或 .bashrc）里：

export PATH="/usr/local/bin:$PATH"

然后 source ~/.zshrc 重新加载配置。

---

方法三：Homebrew 安装（macOS/Linux 用户专属）

如果你习惯用 Homebrew 管理工具，gemini-cli 也进了 Homebrew 官方仓库：

brew install gemini-cli

装完直接 gemini 启动。升级用：

brew upgrade gemini-cli

适合场景：macOS 用户、已经用 Homebrew 管理大量工具、想统一更新。

注意：Homebrew 版本可能比 npm 仓库慢一两天，因为需要经过 Homebrew 的审核流程。如果你追求第一时间用上新功能，建议用 npm 安装。

---

装完验证

不管你用哪种方法，装完后跑：

gemini --version

看到类似 1.0.0 的版本号，就说明安装成功。如果报错，检查上一步的 PATH 问题。

---

额外技巧：指定版本或尝鲜版

gemini-cli 有三个发布渠道：

• latest（稳定版，默认）
• preview（预览版，每周二发布，可能有新功能但未完全验证）
• nightly（每日构建，最前沿但最不稳定）

想装预览版，用 npm 时加 tag：

npm install -g @google/gemini-cli@preview

想装特定版本，比如 1.2.3：

npm install -g @google/gemini-cli@1.2.3

---

真实场景：我该选哪个？

• 第一次接触：直接 npx @google/gemini-cli，零成本试水。
• 决定长期用：npm install -g @google/gemini-cli，然后 gemini 走天下。
• macOS 重度用户：brew install gemini-cli，和 brew 管理习惯一致。

三种方式装出来的东西一模一样，选你顺手的就行。装好之后，下一章我们就开始第一次对话。

三种认证方式，选哪个？

装好 gemini-cli 后，第一件事就是告诉它"你是谁"。gemini-cli 提供了三种认证方式，选哪个取决于你的使用场景和预算。

前置条件：已完成安装（上一章内容），终端能正常执行 gemini 命令。

---

先搞清楚区别

方式	适合谁	免费额度	要不要 Google 账号
Google 登录	个人开发者	60次/分钟，1000次/天	要
API Key	想控制模型版本	1000次/天（混合模型）	要（但不用登录）
Vertex AI	企业/生产环境	按量计费	要（需要 GCP 项目）

一句话总结：个人用选 Google 登录，想折腾模型选 API Key，公司项目选 Vertex AI。

---

方式一：Google 登录（最省事）

这是最推荐的方式，不需要管理任何密钥，登录一次就能用。

gemini

第一次运行，终端会打印一个链接，让你在浏览器里登录 Google 账号。登录成功后，终端自动进入对话模式。

预期结果：浏览器弹出授权页面，确认后终端显示 Welcome to Gemini CLI。

注意：如果你所在的公司买了 Gemini Code Assist 许可证，需要额外设置项目 ID：

export GOOGLE_CLOUD_PROJECT="你的项目ID"
gemini

不设这个变量，免费额度也够用，只是用不了企业级配额。

常见报错：

• Error: Authentication failed → 浏览器授权超时了，重新跑一次 gemini
• 浏览器没自动弹出 → 手动复制终端里的链接到浏览器打开

---

方式二：API Key（适合脚本和 CI/CD）

如果你想把 gemini-cli 集成到自动化脚本里，或者不想每次打开浏览器，用 API Key。

第一步：去 aistudio.google.com/apikey 获取 API Key。登录 Google 账号，点"创建 API 密钥"，复制出来。

第二步：设置环境变量：

export GEMINI_API_KEY="你复制的密钥"

第三步：启动：

gemini

预期结果：直接进入对话，不需要浏览器授权。

实用技巧：把 API Key 写到 .bashrc 或 .zshrc 里，省得每次都要 export：

echo 'export GEMINI_API_KEY="你的密钥"' >> ~/.zshrc
source ~/.zshrc

注意：API Key 有免费额度（每天 1000 次请求），但模型版本是固定的。想换模型？后面第 12 章会讲。

常见报错：

• Error: API key not valid → 密钥复制错了，去 aistudio 重新生成一个
• Error: Quota exceeded → 免费额度用完了，等明天或升级付费

---

方式三：Vertex AI（企业级）

如果你的公司已经在用 Google Cloud，或者你需要更高的请求限制、更好的安全合规，用 Vertex AI。

第一步：在 Google Cloud Console 启用 Vertex AI API，创建服务账号并下载 JSON 密钥文件。

第二步：设置环境变量：

export GOOGLE_API_KEY="你的服务账号密钥"
export GOOGLE_GENAI_USE_VERTEX=true

第三步：启动：

gemini

预期结果：通过 Vertex AI 端点连接，享受企业级配额。

注意：GOOGLE_GENAI_USE_VERTEX=true 这个变量必须设，否则 gemini-cli 默认走 Google 登录或 API Key 的路径。

常见报错：

• Error: Vertex AI API not enabled → 去 Cloud Console 启用 Vertex AI API
• Error: Billing not configured → Vertex AI 需要关联结算账号

---

切换认证方式

三种方式可以随时切换。想从 Google 登录切到 API Key？直接设环境变量再跑 gemini 就行。gemini-cli 会按以下优先级判断：

1. 如果设了 GOOGLE_GENAI_USE_VERTEX=true → 用 Vertex AI
2. 否则如果设了 GEMINI_API_KEY → 用 API Key
3. 否则 → 走 Google 登录流程

实用技巧：如果你同时有多个项目，可以写个脚本切换：

# 用 API Key 启动
alias gemini-key='GEMINI_API_KEY="你的密钥" gemini'

# 用 Google 登录启动
alias gemini-google='unset GEMINI_API_KEY && gemini'

---

真实场景：我该选哪个？

场景一：你是个独立开发者，想快速在终端里问问题、查代码。→ Google 登录，零配置。

场景二：你写了个 CI/CD 脚本，每天自动跑代码审查。→ API Key，不用人盯着浏览器授权。

场景三：你们公司有严格的合规要求，所有 AI 调用必须走 GCP。→ Vertex AI，配合服务账号和 IAM 权限。

场景四：你只是想试试 gemini-cli 好不好用。→ Google 登录，免费额度够你玩一天。

---

下一步

认证搞定后，下一章我们会跑第一个对话，让 Gemini 在终端里回答你的问题。

让终端开口说话

装好 gemini-cli 之后，你肯定想立刻试试它到底能干什么。这一章我们就直接跑起来——在终端里跟 Gemini 聊上第一句。

前提条件

• 已经装好 gemini-cli（上一章的事）
• 已经完成认证（Google 登录、API Key 或 Vertex AI，三种任选一种）
• 终端窗口已经打开

如果你还没认证，先看一眼第 3 章。认证是一次性的，搞定之后就不用再管了。

第一步：直接敲 gemini

gemini

就这么简单。敲完回车，gemini-cli 会启动交互模式。

预期结果：终端会显示一个加载动画，几秒后出现类似这样的提示：

Loading Gemini CLI...
Authenticated as your-email@gmail.com
Type your message, or /help for commands
>

那个 > 就是输入提示符，等着你说话。

第二步：问第一句话

在 > 后面直接打字，按回车发送。

> 用一句话解释什么是量子纠缠

预期结果：Gemini 会开始输出回答。默认是流式输出——文字会一个字一个字地出现在屏幕上，像有人在实时打字。回答结束后，> 提示符会重新出现，等你问下一个问题。

第三步：连续对话

交互模式的好处是可以来回聊。Gemini 会记住上下文，所以你可以追问：

> 刚才说的那个，能举个生活中的例子吗？

它会基于上一轮的对话继续回答，不会失忆。

第四步：退出

聊够了，输入 /exit 或者直接按 Ctrl+C：

> /exit

终端会回到正常的 shell 提示符。

常见问题

报错：Error: No authentication method configured

认证没做。回到第 3 章，选一种方式搞定。

报错：Error: API key not valid

API Key 写错了，或者环境变量没设对。检查一下：

echo $GEMINI_API_KEY

如果输出是空的，说明没设好。重新 export 一次。

等了很久没反应

网络问题。gemini-cli 需要连 Google 的 API。检查一下能不能访问 ai.google.dev。如果你在墙内，可能需要代理。

回答到一半卡住了

按 Ctrl+C 可以中断当前回答，回到 > 提示符重新问。

实用技巧

快速清屏：输入 /clear 可以清掉屏幕上的历史对话，但不会丢失上下文。

查看可用命令：输入 /help 会列出所有内置命令，比如 /model 切换模型、/reset 重置对话。

多行输入：如果问题很长，按 Shift+Enter 换行，写完再按 Enter 发送。

一个真实场景

假设你在写一个 Python 脚本，突然忘了 json.dumps 的参数。不用切浏览器，直接在终端问：

> Python 的 json.dumps 怎么让输出格式更漂亮，带缩进那种

Gemini 会给你代码示例。你甚至可以接着问：

> 帮我写一个函数，读取一个 JSON 文件，格式化后打印出来

它会生成完整代码，你直接复制就能用。整个过程没离开终端。

下一步

你已经跟 Gemini 聊上了。下一章我们会让它真正干活——把整个项目的代码库喂给它，让它帮你理解、调试、重构。

让 AI 看懂你的项目：用 --include-directories 加载代码库

上一章你已经在终端里和 Gemini 聊过天了。但有个问题：你问它“帮我看看这个函数哪里有问题”，它根本不知道你的代码长什么样。默认情况下，gemini-cli 只看到你输入的文字，看不到你项目里的文件。

--include-directories 就是干这个的。它告诉 Gemini：“喂，把这些目录里的文件都读一遍，然后你就能回答关于它们的问题了。”

前置条件

• 已经安装好 gemini-cli（第 2 章）
• 已经完成认证（第 3 章）
• 有一个本地项目目录（随便找个你正在写的项目，或者新建一个测试目录）

第一步：先跑起来看看效果

进入你的项目目录，直接执行：

cd ~/my-project
gemini --include-directories .

. 表示当前目录。Gemini 会扫描当前目录下的所有文件（默认会跳过 node_modules、.git 这些常见忽略目录），然后进入交互模式。

预期结果：你会看到类似这样的输出，然后进入对话模式：

Loaded 47 files from current directory.
Total tokens: ~12,345

数字取决于你的项目大小。如果文件太多，加载时间会长一点，别急。

第二步：只加载特定子目录

整个项目太大？只加载关键部分：

gemini --include-directories ./src ./lib

多个目录用空格隔开。Gemini 会分别扫描这些目录，合并成一个上下文。

预期结果：只加载 src 和 lib 里的文件，test、docs 这些目录不会被扫描。

第三步：问一个需要上下文的问题

加载完代码库后，直接提问：

> 这个项目里有哪些函数调用了 fetch()？

Gemini 会基于它刚读到的所有文件来回答。它知道每个文件的内容、函数定义、变量名——就像它刚通读了你的整个代码库。

预期结果：你会得到一个列表，包含文件名、行号、函数名。如果项目里有 3 个文件用了 fetch，它会全部列出来。

第四步：组合 -p 参数实现脚本化

如果你只想问一次就退出，加上 -p：

gemini --include-directories . -p "列出所有未使用的 import 语句"

这会加载代码库、提问、输出结果、然后退出。适合集成到 CI 脚本或 git hooks 里。

预期结果：终端直接打印出分析结果，没有交互界面。

常见问题与排查

问题：加载了太多文件，上下文窗口不够用

Gemini 的上下文窗口很大（1M tokens），但如果你项目里有几百个文件，还是会超。解决办法：

• 只加载关键目录：--include-directories ./src 而不是整个项目
• 排除不需要的目录：gemini-cli 默认会忽略 node_modules、.git、dist、build 等目录。如果你的项目有特殊目录需要排除，目前不支持自定义排除规则，所以最好手动指定目录

问题：加载速度很慢

大项目第一次扫描确实慢。如果文件数量超过 200 个，建议只加载你关心的子目录。比如你只改 src/components 里的代码，就只加载那个目录。

问题：报错 "No files found"

检查路径是否正确。. 表示当前目录，如果你在项目根目录执行，应该能看到文件。试试绝对路径：

gemini --include-directories /home/user/my-project/src

一个小实战：审查新代码

假设你刚写完一个模块，想让它帮你检查：

cd ~/my-project
gemini --include-directories ./src/new-feature

然后问：

> 这个模块里的错误处理是否完整？有没有遗漏的边界情况？

Gemini 会读取 new-feature 目录下的所有文件，然后基于代码逻辑给出建议。它能看到函数调用链、变量作用域、条件分支——比你自己肉眼扫一遍靠谱得多。

记住一点

--include-directories 不是魔法。它只是把文件内容塞进上下文里让 AI 读取。文件越多，上下文越满，回答质量可能下降（因为 AI 需要处理的信息量太大）。只加载你当前需要讨论的目录，别贪心把整个 monorepo 都塞进去。

把 AI 塞进脚本里

交互式聊天很酷，但真正的生产力在于自动化。你想在 CI/CD 流水线里让 AI 自动审查代码？想在每天凌晨三点让 AI 帮你总结日志？想在 shell 脚本里直接拿到 AI 的回答然后继续处理？这就是 -p 参数干的事。

前置条件：你已经装好了 gemini-cli（第 2 章），并且至少配置了一种认证方式（第 3 章）。随便哪种都行，API Key 最简单，因为不用弹浏览器。

先跑起来：最简单的非交互命令

打开终端，直接敲：

gemini -p "用一句话解释什么是微服务"

你会看到终端直接打印出回答，然后命令结束。没有对话界面，没有欢迎语，没有等待输入——干净利落。

-p 就是 --prompt 的缩写。它告诉 gemini-cli：“别跟我聊天，我给你一句话，你把答案吐出来就完事。”

在 shell 脚本里接住输出

这才是 -p 的真正战场。写个脚本 check_error.sh：

#!/bin/bash
ERROR_LOG=$(tail -n 50 /var/log/app.log)
SUMMARY=$(gemini -p "分析以下日志，找出错误原因和修复建议：$ERROR_LOG")
echo "$SUMMARY"

跑一下：

chmod +x check_error.sh
./check_error.sh

输出直接就是 AI 的分析结果，你可以把它重定向到文件、通过邮件发出去、或者喂给另一个命令。

管道输入：把文件内容喂给 AI

-p 可以跟标准输入配合。比如你有一个 bug_report.txt，想让 AI 分析：

cat bug_report.txt | gemini -p "根据以下内容，列出所有可能的 bug 和修复方案"

或者更直接一点，用文件重定向：

gemini -p "总结这个文件的内容" < README.md

预期结果：AI 会读取文件内容，然后针对你的提示词给出回答。注意，文件内容会作为提示词的一部分发送，所以大文件要注意 token 限制（1M token 基本够用，但别把整个 10GB 日志塞进去）。

跟其它命令组合

非交互模式最爽的地方是可以串在管道里。比如你想让 AI 帮你优化代码：

cat messy_code.py | gemini -p "优化这段 Python 代码，让它更可读，并添加类型注解"

或者从 git diff 里直接生成提交信息：

git diff | gemini -p "根据以下代码变更，生成一个简短的 git commit 信息"

常见报错与排查

报错 1：Error: No prompt provided 你忘了加 -p 参数，或者 -p 后面没跟内容。检查一下命令格式。

报错 2：Error: Authentication required 没配认证。先跑 gemini 交互模式完成登录，或者设置环境变量 GEMINI_API_KEY。

报错 3：输出乱码或截断 中文显示问题？检查终端编码：

export LANG=zh_CN.UTF-8

如果回答太长被截断，可以用 --max-output-tokens 参数调整（默认值取决于模型，一般够用）。

实用技巧

技巧 1：用 -p 配合 --model 指定模型 默认用 gemini-2.5-flash，想用更强的模型：

gemini -p "写一个复杂的排序算法" --model gemini-2.5-pro

技巧 2：控制输出长度 有些场景你只想要简短回答：

gemini -p "这个命令是干什么的：ls -la" --max-output-tokens 100

技巧 3：静默模式 不想看到任何额外信息（比如加载提示），加 --quiet：

gemini -p "1+1等于几" --quiet

输出只有 2，没有别的。

真实场景：自动化代码审查

假设你有个 GitHub Actions 工作流，每次 PR 合并前自动审查代码变更。写个脚本 review_pr.sh：

#!/bin/bash
# 获取当前分支与 main 的差异
DIFF=$(git diff origin/main...HEAD)

# 如果差异为空，直接退出
if [ -z "$DIFF" ]; then
    echo "没有代码变更"
    exit 0
fi

# 让 AI 审查
echo "正在审查代码变更..."
REVIEW=$(gemini -p "作为代码审查者，分析以下代码变更。指出潜在问题、安全漏洞和改进建议：\n\n$DIFF")

# 输出审查结果
echo "=== 代码审查报告 ==="
echo "$REVIEW"

# 如果发现严重问题，退出码设为 1
if echo "$REVIEW" | grep -qi "严重\|安全漏洞\|崩溃"; then
    echo "发现严重问题，审查不通过"
    exit 1
fi

在 CI 里调用：

bash review_pr.sh

如果 AI 发现严重问题，脚本会返回非零退出码，CI 流程就会失败。这就是非交互模式的威力——它让 AI 变成了一个可编程的工具，而不是一个需要你坐在那里聊天的伙伴。

记住一点

-p 模式每次调用都是独立的，AI 不会记住之前的对话。如果你需要上下文，要么把历史信息塞进提示词里，要么用第 11 章的对话检查点功能。但对于大多数自动化场景，一次一问、一次一答正好是你要的。

为什么需要结构化输出

终端里的 AI 回答默认是一大段自然语言文本——读起来没问题，但你想把它塞进脚本、传给另一个程序、或者存到数据库里，就麻烦了。你需要手动解析字符串，写一堆正则或者 split 逻辑，脆弱又容易出错。

--output-format json 就是来解决这个问题的。它让 Gemini 直接吐出 JSON，字段清晰、结构固定，你用 jq 或者任何语言的 JSON 解析库都能直接取数据。

前置条件

• 已经装好 gemini-cli（第 2 章）
• 已经完成认证（第 3 章）
• 能正常发起一次对话（第 4 章）

第一步：加一个参数，输出变 JSON

先跑起来看看效果。随便问个问题，加上 --output-format json：

gemini -p "用 Python 写一个读取 CSV 文件的函数" --output-format json

终端会输出一段 JSON，结构大概长这样：

{
  "response": "```python\nimport csv\n\ndef read_csv(file_path):\n    with open(file_path, 'r') as f:\n        reader = csv.reader(f)\n        return list(reader)\n```\n\n这个函数接收文件路径，返回一个二维列表，每行是 CSV 的一行数据。",
  "model": "gemini-2.5-flash",
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 52,
    "total_tokens": 70
  }
}

关键字段说明：

• response：AI 的文本回答，跟你平时看到的一样
• model：实际使用的模型名
• usage：token 消耗统计，做计费或监控时有用

第二步：用 jq 提取你想要的字段

JSON 输出的真正价值在于管道处理。装一个 jq（macOS 上 brew install jq，Linux 上 apt install jq），然后：

gemini -p "解释一下 Git 的 rebase 和 merge 区别" --output-format json | jq '.response'

输出会去掉外层 JSON，只保留回答文本（带引号）。如果你想要纯文本，加个 -r：

gemini -p "解释一下 Git 的 rebase 和 merge 区别" --output-format json | jq -r '.response'

想只看 token 消耗：

gemini -p "写一个快速排序" --output-format json | jq '.usage'

输出类似：

{
  "prompt_tokens": 12,
  "completion_tokens": 89,
  "total_tokens": 101
}

第三步：在脚本里用 JSON 输出

这是结构化输出最实用的场景。写个脚本，把 AI 的回答存到日志文件，同时记录 token 消耗：

#!/bin/bash
# ask_and_log.sh

QUESTION="$1"
LOG_FILE="ai_answers.jsonl"

RESPONSE=$(gemini -p "$QUESTION" --output-format json)

# 提取回答和 token 数
ANSWER=$(echo "$RESPONSE" | jq -r '.response')
TOKENS=$(echo "$RESPONSE" | jq '.usage.total_tokens')

# 写入日志（JSON Lines 格式，每行一个 JSON 对象）
echo "{\"question\": \"$QUESTION\", \"answer\": \"$ANSWER\", \"tokens\": $TOKENS, \"timestamp\": \"$(date -u +"%Y-%m-%dT%H:%M:%SZ")\"}" >> "$LOG_FILE"

echo "已记录，消耗 $TOKENS tokens"

运行：

chmod +x ask_and_log.sh
./ask_and_log.sh "Docker 和虚拟机有什么区别"

每次执行都会在 ai_answers.jsonl 里追加一行，方便后续用 jq 批量分析。

第四步：结合非交互模式做批量查询

把 JSON 输出和 -p 参数组合，可以批量处理问题列表：

# questions.txt 里每行一个问题
while IFS= read -r question; do
  gemini -p "$question" --output-format json | jq -r '.response'
  echo "---"
done < questions.txt

或者把结果汇总到一个 JSON 数组：

# 用 jq 的 --slurp 把多行 JSON 合并成数组
cat questions.txt | while IFS= read -r q; do
  gemini -p "$q" --output-format json
done | jq -s '.'

-s（--slurp）会把所有输入的 JSON 对象读进一个数组，输出类似：

[
  {
    "response": "第一问的回答...",
    "usage": { "total_tokens": 45 }
  },
  {
    "response": "第二问的回答...",
    "usage": { "total_tokens": 62 }
  }
]

常见问题

输出不是合法的 JSON？

检查一下你的问题是不是太复杂，导致 AI 回答里混入了非 JSON 内容。--output-format json 会让 Gemini 尽量输出纯 JSON，但如果模型截断了回答，最后可能不完整。加个 --max-tokens 参数限制回答长度，或者换个更简单的问题测试。

jq 报错 "parse error: Invalid numeric literal at line 1, column 2"

这通常是因为 gemini-cli 输出了非 JSON 内容（比如错误信息或认证提示）。先不加 jq 直接跑一次，看看原始输出是什么：

gemini -p "test" --output-format json

如果看到的是错误信息而不是 JSON，说明认证有问题或者 API 配额超了。先解决认证问题再试。

我想拿到更细粒度的结构化数据

默认的 JSON 输出只包含回答文本和元数据。如果你需要 AI 返回特定格式的数据（比如一个包含多个字段的对象），可以在问题里明确要求：

gemini -p "给我一个 JSON 对象，包含三个字段：name（字符串）、age（数字）、skills（字符串数组），内容是关于一个叫张三的程序员" --output-format json

Gemini 会在 response 字段里返回你要求的 JSON 字符串。再用一层 jq 解析：

gemini -p "..." --output-format json | jq -r '.response' | jq '.'

实用技巧

• 管道里用 tee 同时查看和保存：gemini -p "..." --output-format json | tee response.json | jq -r '.response'
• 监控 token 消耗：写个定时任务，每天跑一次 gemini -p "hello" --output-format json | jq '.usage.total_tokens'，记录到监控系统
• 配合 --model 参数：不同模型的 token 单价不同，JSON 输出里的 model 字段可以帮你做成本核算

为什么需要流式输出？

上一章我们用 -p 参数让 gemini-cli 在脚本里干活，但有个问题：它要等整个回答生成完才吐出来。如果任务跑 30 秒，你就得干等 30 秒，终端一片死寂。

流式输出（streaming）让 AI 一边生成一边把内容推给你。对长时间任务——比如分析大代码库、生成文档、监控日志——这体验差太多了。你不需要等全部完成，看到前几行就能判断方向对不对，甚至可以在中途打断。

gemini-cli 的 stream-json 模式更进一步：它把每个输出块都包装成 JSON 格式，方便脚本逐行解析。这意味着你可以在 CI/CD 流水线里实时监控 AI 的进度。

前置条件

• 已完成第 4 章的基本认证（Google 登录或 API Key）
• 能正常执行 gemini -p "hello" 并拿到回答
• 有一个可运行的脚本环境（bash、Python 都行）

第一步：体验流式输出

先跑一个最简单的流式命令，感受区别：

gemini -p "用中文写一段 200 字的关于云计算的文章" --stream

加上 --stream 参数后，你会看到文字逐段出现，而不是一次性打印完。注意观察终端：每生成一小段，它就立刻显示出来。

对比不加 --stream 的效果：

gemini -p "用中文写一段 200 字的关于云计算的文章"

后者会卡住几秒，然后整段文字突然冒出来。

第二步：用 stream-json 获取结构化流

--stream 只是让输出更流畅，但如果你要在脚本里处理这些流数据，需要 stream-json 模式：

gemini -p "列出 5 个常用的 Linux 命令并说明用途" --stream-json

输出不再是纯文本，而是每行一个 JSON 对象。大概长这样：

{"type":"content","text":"1."}
{"type":"content","text":" ls"}
{"type":"content","text":" - 列出目录内容"}
{"type":"content","text":"\n"}
{"type":"content","text":"2."}
...
{"type":"done","timestamp":"2024-01-15T10:30:00Z"}

每个 type 为 "content" 的行代表 AI 生成的一个文本片段。最后一行 type 为 "done" 表示生成完毕。

第三步：在脚本中逐行处理流数据

这才是 stream-json 的真正用途。写一个 bash 脚本来实时监控 AI 的生成进度：

#!/bin/bash
# monitor_stream.sh

echo "开始生成内容..."
gemini -p "详细解释 Docker 容器与虚拟机的区别，不少于 500 字" --stream-json | while IFS= read -r line
do
    # 解析 JSON 行
    type=$(echo "$line" | python3 -c "import sys,json; print(json.load(sys.stdin).get('type',''))" 2>/dev/null)
    text=$(echo "$line" | python3 -c "import sys,json; print(json.load(sys.stdin).get('text',''))" 2>/dev/null)
    
    if [ "$type" = "content" ]; then
        # 实时输出文本，不换行
        echo -n "$text"
    elif [ "$type" = "done" ]; then
        echo ""
        echo "--- 生成完成 ---"
    fi
done

跑一下：

chmod +x monitor_stream.sh
./monitor_stream.sh

你会看到文字像打字机一样逐字出现。如果中途想取消，按 Ctrl+C 即可。

注意：这个脚本依赖 python3 来解析 JSON。如果你的系统没有 Python，可以用 jq：

gemini -p "解释 Kubernetes 的核心概念" --stream-json | while IFS= read -r line
do
    type=$(echo "$line" | jq -r '.type // empty' 2>/dev/null)
    text=$(echo "$line" | jq -r '.text // empty' 2>/dev/null)
    if [ "$type" = "content" ]; then
        echo -n "$text"
    fi
done

第四步：监控长时间任务——实战场景

假设你要让 AI 分析一个大型项目的目录结构并生成文档。这个任务可能耗时 1-2 分钟。用流式输出，你可以实时看到进度：

gemini --include-directories /path/to/your/project \
  -p "分析这个项目的目录结构，为每个模块写一段说明文档，输出 Markdown 格式" \
  --stream-json > project_docs_stream.json

但这样只是把 JSON 存到文件里，你看不到进度。改进一下：同时显示进度并保存结果：

#!/bin/bash
# stream_and_save.sh

OUTPUT_FILE="project_docs.json"
echo "开始分析项目，结果将保存到 $OUTPUT_FILE"
echo "按 Ctrl+C 可随时中断"

gemini --include-directories /path/to/your/project \
  -p "分析这个项目的目录结构，为每个模块写一段说明文档，输出 Markdown 格式" \
  --stream-json 2>&1 | tee "$OUTPUT_FILE" | while IFS= read -r line
do
    text=$(echo "$line" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('text',''))" 2>/dev/null)
    if [ -n "$text" ]; then
        # 显示进度指示
        echo -n "."
    fi
done

echo ""
echo "完成！结果已保存到 $OUTPUT_FILE"

跑这个脚本，你会看到终端不断输出 . 号，每个点代表 AI 生成了一段内容。任务完成后，project_docs.json 里存着完整的流式 JSON 记录。

第五步：用 Python 解析流式 JSON 做更复杂的处理

如果你需要更精细的控制——比如实时统计字数、检测关键词、或者把流数据转发到 WebSocket——用 Python 更顺手：

#!/usr/bin/env python3
# stream_processor.py

import subprocess
import json
import sys

def process_stream(prompt):
    cmd = ["gemini", "-p", prompt, "--stream-json"]
    
    process = subprocess.Popen(
        cmd,
        stdout=subprocess.PIPE,
        stderr=subprocess.PIPE,
        text=True,
        bufsize=1  # 行缓冲，确保实时读取
    )
    
    total_chars = 0
    keyword_count = 0
    keywords = ["容器", "虚拟机", "Docker"]
    
    print(f"监控关键词: {keywords}")
    print("开始流式处理...\n")
    
    for line in process.stdout:
        try:
            data = json.loads(line.strip())
            if data.get("type") == "content":
                text = data.get("text", "")
                total_chars += len(text)
                
                # 实时检测关键词
                for kw in keywords:
                    if kw in text:
                        keyword_count += text.count(kw)
                
                # 实时输出文本
                print(text, end="", flush=True)
                
            elif data.get("type") == "done":
                print(f"\n\n--- 统计信息 ---")
                print(f"总字符数: {total_chars}")
                print(f"关键词出现次数: {keyword_count}")
                
        except json.JSONDecodeError:
            # 忽略非 JSON 行（比如错误信息）
            pass
    
    process.wait()

if __name__ == "__main__":
    prompt = "详细解释 Docker 容器与虚拟机的区别，不少于 300 字"
    process_stream(prompt)

跑一下：

python3 stream_processor.py

你会看到文本实时输出，最后还会打印统计信息。这个脚本可以直接嵌入到 CI/CD 流水线里，比如在 PR 审查时实时监控 AI 的分析进度。

常见问题

输出乱码或格式不对

stream-json 的每一行都是完整的 JSON 对象，但如果你用 echo 直接打印，可能会丢失换行符。始终用 while read 逐行处理，不要用 cat 或 xargs。

流中断了怎么办

网络波动或 API 限流可能导致流中断。stream-json 的最后一个 JSON 行 type 会是 "error" 而不是 "done"。在脚本里加个判断：

if [ "$type" = "error" ]; then
    echo ""
    echo "错误: $(echo "$line" | jq -r '.text')"
    exit 1
fi

性能问题

如果 AI 生成速度很快，while read 逐行处理可能成为瓶颈。这时可以用 jq --stream 批量处理，但大多数场景下逐行处理完全够用。

记住一点

--stream 和 --stream-json 的区别：前者适合人眼看，后者适合机器读。在脚本和自动化任务里，永远用 --stream-json，这样你既能实时监控，又能精确解析每个输出块。

让 AI 真正动手：Google 搜索、文件操作与 Shell 命令

前几章你学会了怎么跟 Gemini 聊天、怎么让它看你的代码。但 AI 光会聊天不够——它得能帮你干活。这一章就让 Gemini 真正接入你的系统：上网查资料、读写文件、执行 Shell 命令。

这三个内置工具默认就开着，不用额外配置。你只需要知道怎么触发它们。

先确认你的环境

确保 gemini-cli 已经装好并且能正常运行：

gemini --version

如果没装，先跑：

npm install -g @google/gemini-cli

认证方式随便选，API Key 或 Google 登录都行。本章所有例子都基于交互模式。

工具一：Google 搜索——让 AI 获取实时信息

Gemini 的训练数据有截止日期，问"今天天气怎么样"它答不上来。但加上 Google 搜索能力，它就能实时查。

直接问一个需要实时信息的问题：

gemini

进入交互模式后输入：

今天北京天气怎么样？帮我查一下

你会看到输出里出现类似 [Grounding] 或 [Search] 的标记，后面跟着搜索结果摘要。Gemini 会基于这些结果给你答案。

原理很简单：当 Gemini 判断需要实时信息时，它会自动调用 Google Search 工具。你不需要加特殊参数。

试试这些场景：

2024年诺贝尔文学奖得主是谁？
Node.js 最新 LTS 版本是多少？
帮我搜一下 "gemini-cli GitHub" 的最新 issue

每个回答底部都会显示信息来源。你可以直接点开链接确认。

常见问题：如果搜索没触发，可能是你的问题太模糊。明确说"帮我搜一下"或"查一下"能提高触发概率。

工具二：文件操作——读写项目文件

这个工具让 Gemini 能直接读写你当前目录下的文件。不用复制粘贴代码，它自己就能打开、修改、保存。

先创建一个测试文件：

echo "这是一个测试文件" > test.txt

然后在 gemini 交互模式里输入：

帮我读取 test.txt 的内容

Gemini 会返回文件内容。接着试试修改：

在 test.txt 末尾加一行 "第二行内容"

再读一次确认：

再读一遍 test.txt

你应该看到两行内容了。

真实场景：假设你在写一个 Python 脚本，想加个函数：

帮我打开 app.py，在文件末尾加一个函数，功能是读取 config.json 并返回配置字典

Gemini 会读取 app.py 现有内容，理解上下文，然后追加代码。你只需要检查一下改得对不对。

文件操作支持哪些动作？

• 读取文件内容
• 写入/覆盖文件
• 追加内容到文件末尾
• 创建新文件
• 列出目录内容

注意：Gemini 只能操作当前工作目录及其子目录的文件。想访问上级目录？不行，这是安全限制。

工具三：Shell 命令——直接在终端里执行

这是最强大的工具。Gemini 可以执行 Shell 命令并返回结果。你只需要描述你想干什么。

先试试简单的：

帮我看看当前目录下有哪些文件

Gemini 会执行 ls 或 dir（取决于你的系统），然后把结果告诉你。

再来点实用的：

帮我查一下 3000 端口被哪个进程占用了

它会执行 lsof -i :3000 或 netstat -an | grep 3000，然后告诉你结果。

危险操作怎么办？ Gemini 在执行可能造成破坏的命令前会先问你。比如：

帮我删除所有 .log 文件

它会回复类似："我建议执行 rm *.log，这会删除当前目录下所有 .log 文件。确认执行吗？(y/n)"

你输入 y 它才执行。

实用例子：一键部署

帮我执行以下步骤：
1. git pull
2. npm install
3. npm run build
4. pm2 restart app

Gemini 会按顺序执行每条命令，并在每一步告诉你结果。如果某一步出错，它会停下来告诉你哪里出了问题。

安全提醒：虽然 Gemini 会确认危险操作，但你还是要留个心眼。永远不要让它执行你不理解的命令。特别是 rm -rf / 这种毁灭性操作——Gemini 会拒绝执行，但别去试。

三个工具一起用：一个真实场景

假设你在调试一个 Node.js 应用，日志显示数据库连接失败。你可以这样跟 Gemini 对话：

你：帮我查一下 MongoDB 默认端口是多少
AI：[搜索] MongoDB 默认端口是 27017

你：帮我看看 27017 端口有没有在监听
AI：[执行命令] lsof -i :27017 → 没有进程在监听

你：检查一下 mongod 进程是否在运行
AI：[执行命令] ps aux | grep mongod → mongod 没有运行

你：帮我启动 MongoDB
AI：执行 sudo systemctl start mongod？(y/n)
你：y
AI：MongoDB 已启动。需要我帮你检查应用日志吗？

你：好，读取 app.log 的最后 20 行
AI：[读取文件] 显示最后 20 行日志，没有新的连接错误

整个过程你只打字，Gemini 帮你搜索、执行命令、读文件。这就是三个工具配合的效果。

关闭某个工具（如果你不想要）

默认三个工具全开。如果你想禁用某个（比如不想让 AI 执行 Shell 命令），启动时加参数：

gemini --no-shell-tools

其他选项：

gemini --no-search-tools    # 禁用搜索
gemini --no-file-tools      # 禁用文件操作

可以组合使用：

gemini --no-shell-tools --no-file-tools

常见报错与排查

"Permission denied"：Gemini 执行命令时用的是你的用户权限。如果某个命令需要 sudo，它会提示你手动输入密码（它不会自动用 sudo）。

"File not found"：检查文件路径。Gemini 只能访问当前目录及子目录。用绝对路径也不行。

搜索没反应：确认你的网络能访问 Google。某些网络环境可能被屏蔽。

命令执行超时：长时间运行的命令（比如 npm install）可能会超时。建议在 gemini 外面先跑完，再回来继续对话。

下一步

这三个工具是 gemini-cli 的核心能力。学会它们，你就能让 AI 真正帮你干活——不只是回答问题，而是操作你的系统。下一章我们会讲怎么用 GEMINI.md 文件定制 AI 的行为，让它更懂你的项目。

为什么需要 GEMINI.md

每次你问 gemini-cli 一个项目相关的问题，它都对你的项目一无所知。它不知道你用的是什么框架、代码风格偏好、测试要求——除非你每次都在提示词里重复一遍。

GEMINI.md 就是解决这个问题的。把它放在项目根目录，里面写清楚你希望 AI 怎么理解这个项目。每次对话开始，gemini-cli 会自动读取这个文件，把它当作"项目说明书"塞进上下文。

前置条件

• 已安装 gemini-cli（第 2 章）
• 已完成认证（第 3 章）
• 有一个项目目录，你想让 AI 理解这个项目

第一步：创建 GEMINI.md

进到你的项目根目录，直接创建文件：

cd /path/to/your/project
touch GEMINI.md

就这么简单。文件名必须大写、全大写、带点 md。gemini.md 不行，Gemini.md 也不行。必须是 GEMINI.md。

第二步：写点什么进去

打开文件，写你希望 AI 知道的东西。没有固定格式，纯文本 Markdown 就行。举个例子：

# 项目上下文

这是一个 Next.js 14 项目，使用 App Router。
UI 组件库用的是 shadcn/ui。
状态管理用 Zustand。
API 路由在 /app/api 下。

# 代码规范

- 组件用 TypeScript，文件名用 PascalCase
- 工具函数用 TypeScript，文件名用 camelCase
- 测试文件放在 __tests__ 目录，用 Vitest
- 不要用 any 类型，用 unknown 代替

# 常见任务

## 添加新页面
在 /app 下创建目录，加 page.tsx 和 layout.tsx

## 添加 API 路由
在 /app/api 下创建目录，加 route.ts

## 修改数据库模型
先改 prisma/schema.prisma，然后运行 npx prisma migrate dev

写完后保存。现在 gemini-cli 每次在这个目录下运行，都会自动加载这些内容。

第三步：验证它生效了

在项目目录下跑个简单对话：

gemini -p "这个项目用什么框架？"

如果 GEMINI.md 加载成功，它会回答"Next.js 14"。如果没生效，它会说"我不知道"或者瞎猜。

你也可以加 --verbose 参数看它到底加载了什么：

gemini --verbose -p "这个项目用什么框架？"

输出里会有一行类似 Loaded context from /path/to/your/project/GEMINI.md。

常见问题

GEMINI.md 没生效

检查三点：

1. 文件名是不是 GEMINI.md（全大写）
2. 文件是不是在项目根目录（就是你运行 gemini 命令的目录）
3. 文件有没有读取权限

ls -la GEMINI.md
# 应该显示 -rw-r--r--

文件太大怎么办

GEMINI.md 没有大小限制，但 Gemini 模型有上下文窗口（1M token）。如果你的文件太长，AI 可能记不住后面的内容。保持文件在几百行以内，只写真正重要的上下文。

多个项目共用一套规则

不想每个项目都写一遍？用符号链接：

# 先在一个地方写好通用规则
mkdir -p ~/.config/gemini
cp /path/to/project/GEMINI.md ~/.config/gemini/default.md

# 然后在每个项目里链接它
ln -s ~/.config/gemini/default.md /path/to/other/project/GEMINI.md

这样改一个文件，所有项目都同步更新。

实战技巧

放代码片段

GEMINI.md 里可以放你常用的代码模式，AI 会照着写：

# API 响应格式
所有 API 返回格式：
{
  success: boolean,
  data: T | null,
  error: string | null
}

放项目术语

团队有自己的一套叫法？写进去：

# 术语
- "用户卡片" = UserProfileCard 组件
- "数据层" = 所有以 use 开头的 hooks
- "后端" = /app/api 下的路由

放安全提醒

# 安全
- 不要在代码里硬编码 API key
- 所有用户输入必须经过 zod 验证
- 敏感操作需要管理员权限检查

一个完整例子

假设你在维护一个电商项目，GEMINI.md 可以写成这样：

# ShopEase 电商平台

## 技术栈
- 前端：React 18 + TypeScript + Tailwind CSS
- 后端：Node.js + Express + Prisma
- 数据库：PostgreSQL
- 缓存：Redis

## 目录结构
/src
  /components    # 可复用组件
  /pages         # 页面组件
  /api           # API 路由
  /lib           # 工具函数
  /types         # TypeScript 类型定义

## 命名规范
- 组件文件：PascalCase.tsx
- 工具函数：camelCase.ts
- API 路由：kebab-case

## 数据库操作
所有数据库查询必须通过 Prisma Client：
import { prisma } from '@/lib/prisma'

## 错误处理
API 错误统一返回：
{
  error: string,
  code: number,
  details?: unknown
}

然后你就可以问：

gemini -p "帮我写一个获取用户订单列表的 API"

AI 会按照你 GEMINI.md 里定义的规范来写：用 Prisma、返回统一错误格式、路由放在 /api 下。不用你再重复这些背景信息。

什么时候用，什么时候不用

用 GEMINI.md 的场景：

• 项目有特定技术栈
• 团队有代码规范
• 你想让 AI 输出风格统一
• 每次对话都要重复说同样的背景信息

不用 GEMINI.md 的场景：

• 临时问个通用问题（"Python 怎么读取 CSV"）
• 项目太简单，不需要额外上下文
• 你只是测试 gemini-cli 功能

记住一点：GEMINI.md 是给 AI 看的项目说明书，不是给人类看的 README。写清楚 AI 需要知道的东西就够了，项目历史、贡献指南这些人类才关心的东西不用放进去。

对话检查点：保存和恢复复杂会话

调试到一半，AI 帮你分析了三页日志，突然终端崩了。或者你正在审查一个大型 PR，已经问了十几个上下文相关的问题，想明天继续。没有检查点，一切重来。

gemini-cli 内置了会话保存和恢复功能。它把整个对话——包括历史、上下文、甚至你加载的文件路径——写到一个 JSON 文件里。下次启动时读回来，AI 就像没断过一样。

前置条件

• 已安装 gemini-cli（第 2 章）
• 已完成认证（第 3 章）
• 至少跑过一次交互式对话（第 4 章）

第一步：保存当前会话

在交互模式下，直接按 Ctrl+S（macOS 也是 Ctrl+S，不是 Cmd+S）。

终端会提示你输入文件名：

Save current session as: my-debug-session

按回车，gemini-cli 会在当前目录生成一个 my-debug-session.gemini-session.json 文件。

预期结果：文件内容类似这样（简化版）：

{
  "sessionId": "abc123",
  "model": "gemini-2.5-flash",
  "messages": [
    {"role": "user", "content": "帮我看看这个错误日志"},
    {"role": "assistant", "content": "这个错误是因为..."}
  ],
  "context": {
    "includeDirectories": ["./src"],
    "customContext": "项目使用 React 18"
  },
  "savedAt": "2025-03-21T10:30:00Z"
}

注意：文件名不要加空格，gemini-cli 会帮你自动补全 .gemini-session.json 后缀。如果你输入了完整路径，比如 ~/sessions/project-x，它会存到指定位置。

第二步：恢复会话

下次想继续时，用 --session 参数启动：

gemini --session my-debug-session.gemini-session.json

或者只写文件名前缀（自动补全后缀）：

gemini --session my-debug-session

预期结果：对话直接恢复到上次中断的位置。你可以继续问"那这个错误怎么修复？"，AI 还记得之前讨论的上下文。

第三步：在非交互模式下使用检查点

检查点不只在交互模式有用。你可以在脚本里先保存一个会话，然后分多次恢复并提问。

先创建一个会话并保存：

echo "分析项目结构" | gemini -p --save-session analysis

然后恢复它并追加问题：

gemini --session analysis -p "刚才的分析基础上，列出所有 API 端点"

预期结果：第二次提问时，AI 知道"刚才的分析"指的是什么，不会当成独立问题。

常见问题

Q: 保存时提示 "Session file already exists"

默认不会覆盖已有文件。如果你想覆盖，用 --force 参数：

# 保存时覆盖
# 按 Ctrl+S 后输入同名文件，会提示是否覆盖，选 y

或者在命令行指定：

gemini --save-session my-session --force

Q: 恢复时提示 "Session file not found"

检查文件路径。gemini-cli 默认在当前目录找，如果你存到了别处，给完整路径：

gemini --session ~/projects/my-session.gemini-session.json

Q: 恢复后 AI 回答很奇怪

检查点保存的是消息历史，不保存模型状态。如果你换了模型版本（比如从 flash 切到 pro），AI 的回复风格可能不同。但上下文信息是完整的。

Q: 会话文件太大

如果你加载了大型代码库（--include-directories），会话文件里会包含文件内容的摘要。默认情况下，gemini-cli 只保存消息历史，不保存原始文件内容。恢复时会重新读取文件。如果你担心文件大小，可以手动删除会话文件中的 context 字段（但会丢失目录上下文）。

实用技巧

1. 命名规范：用 项目名-日期-用途 格式，比如 pr-review-0321、bug-debug-session。方便后续查找。

2. 配合 GEMINI.md：如果你在项目根目录放了 GEMINI.md 自定义上下文，恢复会话时确保这个文件还在。检查点只保存消息历史，不保存 GEMINI.md 内容。

3. 批量保存：在长时间调试中，每隔一段时间按 Ctrl+S 保存一次。gemini-cli 不会自动保存，全靠手动。

4. 清理旧会话：会话文件是纯文本 JSON，可以直接删除。定期清理 rm *.gemini-session.json 避免堆积。

真实场景：跨天代码审查

假设你正在审查一个大型 PR，已经问了 20 个问题，AI 帮你分析了 5 个文件。下班前：

1. 按 Ctrl+S，输入 pr-review-0321
2. 第二天到公司，运行 gemini --session pr-review-0321
3. 直接问"昨天我们分析到第三个文件，继续看第四个"

AI 会无缝衔接，就像你从来没离开过。

为什么需要手动选模型？

gemini-cli 默认会给你挑一个"最合适"的模型，通常是 gemini-2.5-flash。但实际场景里，你经常需要自己指定：

• 写复杂代码、做深度推理时，想要 pro 版本更强的能力
• 跑批量脚本、简单问答时，用 flash 更快更省配额
• 测试新功能时，想试试 preview 或 nightly 通道的模型

这一章就讲怎么手动控制模型，以及不同模型到底差在哪。

前置条件

• 已安装 gemini-cli（第 2 章）
• 已完成认证（第 3 章）
• 能正常发起对话（第 4 章）

先看看当前用的什么模型

直接问它：

gemini -p "你现在用的是哪个模型？"

它会告诉你当前模型名称。默认情况下，如果你用 Google 登录，它会用最新的 gemini-2.5-flash；如果用 API Key，也是 flash 系列。

手动指定模型：--model 参数

核心参数就一个：--model。后面跟模型名称。

gemini --model gemini-2.5-pro

这会启动交互模式，但用的是 pro 模型。你可以先跑起来，然后随便问个问题测试：

gemini --model gemini-2.5-pro -p "1+1等于几？用中文回答"

预期结果：和 flash 的回答一样，但背后用的是更强的推理模型。

当前可用的模型列表

截至 2025 年，gemini-cli 支持的主要模型：

模型名称	适用场景	特点
gemini-2.5-flash	日常问答、代码补全、快速原型	速度快，配额消耗低
gemini-2.5-pro	复杂推理、长文档分析、代码审查	推理能力强，1M token 上下文
gemini-2.0-flash	兼容旧项目	稳定但功能略少
gemini-2.0-pro	旧版 pro	已逐步被 2.5 取代

注意：模型名称会随 Google 更新而变化。想获取最新列表，直接问：

gemini -p "列出你现在能用的所有模型名称"

在非交互模式中指定模型

写脚本时，模型选择尤其重要。批量任务用 flash 省配额，关键任务用 pro 保质量。

# 快速分析：用 flash
gemini -p "总结这个目录的结构" --include-directories . --model gemini-2.5-flash

# 深度审查：用 pro
gemini -p "审查这个文件的代码质量，给出改进建议" --include-directories ./src --model gemini-2.5-pro

模型与认证方式的关系

不同认证方式能用的模型范围不一样：

Google 登录（OAuth）：

• 能用所有公开模型
• 自动获得最新模型
• 配额：60 次/分钟，1000 次/天

API Key：

• 能用你账户下授权的模型
• 免费层：每天 1000 次请求（flash 和 pro 混合）
• 付费层：按量计费，无上限

Vertex AI：

• 取决于你的 GCP 项目配置
• 可以访问企业级模型和自定义模型

如果你用 API Key 但指定了不支持的模型，会报错：

Error: Model 'gemini-2.5-pro' is not supported with your API key.

这时候换成 flash 试试，或者升级你的 API 配额。

实战场景：根据任务自动切换模型

写个简单的 shell 函数，让脚本自动判断用哪个模型：

#!/bin/bash

analyze_code() {
  local file=$1
  local size=$(wc -l < "$file")
  
  if [ "$size" -gt 500 ]; then
    # 大文件用 pro
    gemini -p "分析 $file 的架构和潜在问题" --include-directories . --model gemini-2.5-pro
  else
    # 小文件用 flash
    gemini -p "分析 $file 的代码质量" --include-directories . --model gemini-2.5-flash
  fi
}

analyze_code "src/main.py"

常见问题

Q：指定了模型但没生效？ 检查参数拼写。--model 不是 -m，也不是 --model-name。正确的：

gemini --model gemini-2.5-pro -p "test"

Q：pro 模型回答更慢？ 正常。pro 模型推理时间更长，尤其处理长上下文时。耐心等几秒。

Q：怎么知道当前模型支持哪些功能？ 直接问它：

gemini --model gemini-2.5-pro -p "你支持哪些内置工具？"

Q：能不能用 nightly 或 preview 通道的模型？ 这些是发布通道，不是模型名称。要体验最新模型，先切换到 preview 版本：

npm install -g @google/gemini-cli@preview

然后 gemini-cli 会自动使用该通道的最新模型。

小结

• --model 参数直接指定模型名称
• flash 系列：快、省配额，适合日常和批量任务
• pro 系列：强、慢，适合复杂推理和长文档
• 不同认证方式能用的模型范围不同
• 脚本里可以根据文件大小、任务复杂度动态选模型

下一章，我们会用 MCP 服务器给 AI 接入图片生成能力，让 gemini-cli 不仅能写代码，还能画图。

先搞清楚 MCP 是什么

MCP（Model Context Protocol）是 AI 模型和外部服务之间的"万能插头"。装了 MCP 服务器，Gemini CLI 就能调用原本没有的能力——比如生成图片、操作数据库、发邮件。

这一章我们拿图片生成当例子。装一个 MCP 图片生成服务器，让 Gemini 在终端里直接画图。

前置条件

• 已安装 gemini-cli（第 2 章）
• 已完成认证（第 3 章）
• 能正常对话（第 4 章）
• 系统装了 Node.js 18+（检查：node --version）

第一步：装一个 MCP 图片生成服务器

Google 官方提供了一个 MCP 示例服务器，能调用 Imagen 生成图片。先把它拉到本地：

git clone https://github.com/GoogleCloudPlatform/vertex-ai-creative-studio.git
cd vertex-ai-creative-studio/experiments/mcp-genmedia

这个仓库里有个 mcp-genmedia 目录，里面就是我们要的 MCP 服务器。

第二步：安装依赖并配置认证

npm install

装完后，需要设置 Google Cloud 认证才能调用 Imagen API。如果你已经配过 gcloud 认证，直接：

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-key.json"

没有服务账号？去 Google Cloud Console 创建一个，给 Vertex AI User 角色，下载 JSON 密钥。

第三步：启动 MCP 服务器

node server.js

如果一切正常，终端会输出类似：

MCP server running on stdio

别关这个终端。MCP 服务器通过标准输入输出和 gemini-cli 通信，必须保持运行。

第四步：告诉 gemini-cli 用这个 MCP 服务器

新开一个终端窗口，启动 gemini-cli 时带上 MCP 配置：

gemini --mcp-servers '{"genmedia": {"command": "node", "args": ["/absolute/path/to/mcp-genmedia/server.js"]}}'

路径必须写绝对路径。写相对路径会报 ENOENT 错误。

第五步：让 Gemini 画图

现在在 gemini-cli 里输入：

帮我生成一张「一只戴着墨镜的猫在沙滩上喝椰子水」的图片

Gemini 会调用 MCP 服务器的 generate_image 工具，返回图片的 URL 或本地路径。

如果 Gemini 说"我没有这个能力"，检查 MCP 服务器是否还在运行，以及路径是否正确。

常见报错与排查

报错：MCP server connection failed

• 确认 MCP 服务器进程没挂
• 检查路径是不是绝对路径
• 看看 MCP 服务器终端有没有报错日志

报错：Permission denied

• 服务账号密钥文件权限不对：chmod 600 your-key.json
• 或者服务账号没有 Vertex AI User 角色

报错：Model not found

• Imagen API 只在特定区域可用，确认你的 Google Cloud 项目区域支持 Imagen

Gemini 说"我试试"但没结果

• 手动在 MCP 服务器终端敲回车，看有没有报错输出
• 有些 MCP 服务器需要额外环境变量，检查 README

实用技巧

一次配多个 MCP 服务器

gemini --mcp-servers '{
  "genmedia": {"command": "node", "args": ["/path/to/genmedia/server.js"]},
  "database": {"command": "python", "args": ["/path/to/db-mcp/server.py"]}
}'

把 MCP 配置写进别名

在 ~/.zshrc 或 ~/.bashrc 里加一行：

alias gemini-mcp='gemini --mcp-servers '\''{"genmedia": {"command": "node", "args": ["/path/to/server.js"]}}'\'

下次直接敲 gemini-mcp 就行。

MCP 服务器不止图片生成

• mcp-genmedia 还支持视频生成（Veo）、音乐生成（Lyria）
• 社区有大量现成 MCP 服务器：数据库查询、文件系统操作、浏览器自动化
• 自己写一个 MCP 服务器也不难——只要实现 stdio 通信协议

完整小例子：一次对话生成三张图

启动 gemini-cli 并连上 MCP 后，直接输入：

生成三张不同风格的猫图片：
1. 赛博朋克风格的猫，霓虹灯光
2. 水墨画风格的猫，黑白
3. 像素风格的猫，8-bit 游戏风
每张图保存到当前目录，文件名用风格命名

Gemini 会依次调用 MCP 服务器的图片生成工具，并把结果存到本地。整个过程在终端完成，不用打开浏览器。

自动化代码审查与 PR 总结

这一章把前面学的所有东西串起来——用 gemini-cli 写一个真正的自动化工作流。目标：每次有人提 PR，自动跑代码审查、生成总结、贴到 PR 评论区。全程不用手动复制粘贴。

先确认你手头有这些：

• gemini-cli 已安装并认证（第 2、3 章）
• 一个 GitHub 仓库（你有写权限）
• GitHub CLI（gh）已安装并登录
• 一个 GitHub Personal Access Token（有 repo 权限）

第一步：写一个 PR 审查脚本

先创建一个脚本文件 review-pr.sh：

#!/bin/bash
# 用法: ./review-pr.sh <PR编号>

PR_NUMBER=$1
REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)

# 获取 PR 的 diff
gh pr diff $PR_NUMBER > /tmp/pr_diff_$PR_NUMBER.diff

# 获取 PR 的标题和描述
PR_INFO=$(gh pr view $PR_NUMBER --json title,body)

# 把 diff 喂给 gemini-cli 做审查
cat /tmp/pr_diff_$PR_NUMBER.diff | gemini -p "
你是一个代码审查专家。请审查以下 PR 的 diff，输出格式如下：

## 审查结果

### 总体评价
[一句话总结这个 PR 的质量]

### 发现的问题
- [问题1] (严重程度: 高/中/低)
- [问题2] (严重程度: 高/中/低)

### 改进建议
- [建议1]
- [建议2]

### 安全风险
[如果有安全相关的问题，在这里列出]

PR 信息: $PR_INFO
" --output-format text > /tmp/review_$PR_NUMBER.md

给执行权限：

chmod +x review-pr.sh

跑一下试试：

./review-pr.sh 3

如果 PR 编号是 3，你会看到 /tmp/review_3.md 里生成了审查报告。先别急着贴到 GitHub，我们还要加一个总结功能。

第二步：生成 PR 总结

审查报告有了，但太长。再写一个脚本 summarize-pr.sh，把审查结果浓缩成几句话：

#!/bin/bash
PR_NUMBER=$1

cat /tmp/review_$PR_NUMBER.md | gemini -p "
把以下代码审查报告总结成 3-5 句话，适合贴在 PR 评论区。重点说：
1. 这个 PR 改了啥
2. 有没有严重问题
3. 整体质量如何

报告内容：
" --output-format text > /tmp/summary_$PR_NUMBER.md

跑一下：

./summarize-pr.sh 3

打开 /tmp/summary_3.md，应该只有几行字。如果内容太长，说明 prompt 不够精确，可以加一句“每句话不超过 20 个字”。

第三步：自动贴到 PR 评论区

把审查报告和总结一起贴回去。新建 post-review.sh：

#!/bin/bash
PR_NUMBER=$1

# 先跑审查和总结
./review-pr.sh $PR_NUMBER
./summarize-pr.sh $PR_NUMBER

# 组装评论内容
echo "## 🤖 Gemini CLI 自动审查

### 快速总结
$(cat /tmp/summary_$PR_NUMBER.md)

### 完整审查报告
$(cat /tmp/review_$PR_NUMBER.md)
" > /tmp/comment_$PR_NUMBER.md

# 贴到 PR
gh pr comment $PR_NUMBER --body-file /tmp/comment_$PR_NUMBER.md

echo "✅ 审查结果已贴到 PR #$PR_NUMBER"

跑一次完整的：

./post-review.sh 3

打开浏览器，去 GitHub 上看 PR #3 的评论区——应该能看到一条带“🤖 Gemini CLI 自动审查”标题的评论。

第四步：用 GitHub Actions 自动化

手动跑脚本还是麻烦。把它变成自动触发——每次有人提 PR，Action 自动跑。

在仓库里创建 .github/workflows/pr-review.yml：

name: PR Review with Gemini CLI

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # 拉取完整 git 历史，否则 diff 可能不完整

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Gemini CLI
        run: npm install -g @google/gemini-cli

      - name: Run code review
        env:
          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
        run: |
          PR_NUMBER=${{ github.event.pull_request.number }}
          gh pr diff $PR_NUMBER > /tmp/pr_diff.diff
          cat /tmp/pr_diff.diff | gemini -p "
          你是一个代码审查专家。审查以下 PR diff，输出格式：
          ## 审查结果
          ### 总体评价
          ### 发现的问题
          ### 改进建议
          " --output-format text > /tmp/review.md

      - name: Post review comment
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          PR_NUMBER=${{ github.event.pull_request.number }}
          gh pr comment $PR_NUMBER --body-file /tmp/review.md

注意几个坑：

• GEMINI_API_KEY 必须在 GitHub 仓库的 Settings > Secrets and variables > Actions 里添加。去 aistudio.google.com 生成一个 key，然后粘贴进去。
• GITHUB_TOKEN 是 GitHub 自动生成的，不用手动配，但权限默认只有读。要让 Action 能写评论，去仓库 Settings > Actions > General > Workflow permissions，改成“Read and write permissions”。
• fetch-depth: 0 很重要。默认只拉最新一次提交，gh pr diff 会拿不到完整 diff。

提交这个文件到仓库：

git add .github/workflows/pr-review.yml
git commit -m "Add automated PR review workflow"
git push

现在去提一个新 PR，等一两分钟，刷新页面——评论区应该自动出现审查结果。

第五步：加一个质量门禁（可选）

如果审查发现严重问题，直接阻止合并。在 Action 里加一步：

      - name: Check for critical issues
        run: |
          if grep -q "严重程度: 高" /tmp/review.md; then
            echo "❌ 发现严重问题，PR 被阻止"
            exit 1
          fi
          echo "✅ 没有严重问题"

把这个加到 Post review comment 后面。如果审查报告里出现“严重程度: 高”，Action 会失败，PR 的合并按钮会变灰。

常见问题

Action 报错 gh: command not found GitHub Actions 的 ubuntu-latest 镜像自带 gh，但如果你用其他镜像，需要手动安装：

- name: Install GitHub CLI
  run: |
    type -p curl >/dev/null || sudo apt-get install curl -y
    curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
    echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
    sudo apt-get update
    sudo apt-get install gh -y

审查结果太啰嗦 在 prompt 里加限制：“每类问题最多列出 3 条”“每条建议不超过 50 字”。或者用 --output-format json 解析后自己格式化。

API 配额不够 免费版每天 1000 次请求。如果团队 PR 多，考虑用 Vertex AI 认证（第 3 章），或者加一个频率限制：只在 PR 刚打开时审查一次，后续更新不重复跑。

现在你有了一个全自动的代码审查机器人。下次团队里有人提 PR，Gemini 会自动看代码、写总结、贴评论——你只需要等着看结果。

问题 1：安装时报错 npm ERR! code EACCES 或权限不足怎么办？

这通常是因为全局安装 npm 包时缺少写入权限。推荐使用以下方法之一解决：

• 使用 npx 直接运行（无需安装）：

  npx @google/gemini-cli

• 使用 Homebrew 安装（macOS/Linux）：

  brew install gemini-cli

• 配置 npm 全局路径（避免使用 sudo）：

  npm config set prefix ~/.npm-global
  echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
  source ~/.bashrc
  npm install -g @google/gemini-cli

问题 2：运行 gemini 命令后提示“未登录”或“认证失败”怎么办？

Gemini CLI 需要先完成身份认证才能使用。根据你的场景选择一种方式：

• 个人开发者（推荐）：直接运行 gemini，首次启动时会弹出浏览器窗口，用你的 Google 账号登录即可自动完成 OAuth 认证。
• 使用 API Key：在 Google AI Studio 获取密钥，然后设置环境变量：

  export GEMINI_API_KEY="你的API密钥"
  gemini

• 企业用户（Vertex AI）：确保已配置 Google Cloud 项目并启用 Vertex AI API：

  export GOOGLE_API_KEY="你的密钥"
  export GOOGLE_GENAI_USE_VERTEX_AI=true
  gemini

问题 3：如何切换不同的发布通道（稳定版/预览版/每日构建版）？

Gemini CLI 提供三个发布通道，通过 npm 标签区分：

• 稳定版（stable）：每周二 UTC 20:00 发布，经过完整测试，适合日常使用。

  npm install -g @google/gemini-cli@latest

• 预览版（preview）：每周二 UTC 23:59 发布，包含新功能但可能有未修复的问题，适合尝鲜和测试。

  npm install -g @google/gemini-cli@preview

• 每日构建版（nightly）：每天 UTC 00:00 发布，基于最新代码，可能存在不稳定因素。

  npm install -g @google/gemini-cli@nightly

问题 4：在受限环境（如公司内网）无法直接安装 npm 包怎么办？

推荐使用 Anaconda 创建隔离环境来安装：

# 创建并激活新环境
conda create -y -n gemini_env -c conda-forge nodejs
conda activate gemini_env

# 在环境内全局安装 Gemini CLI
npm install -g @google/gemini-cli

如果连 conda 也无法使用，可以尝试：

• 在另一台能联网的机器上通过 npm pack @google/gemini-cli 下载离线包，然后传输到目标机器用 npm install -g ./gemini-cli-*.tgz 安装。
• 或者使用 Docker 容器运行。

问题 5：Gemini CLI 和 ChatGPT CLI、Claude CLI 相比有什么优势？

主要差异体现在以下几点：

• 免费额度慷慨：个人 Google 账号即可享受每分钟 60 次、每天 1000 次请求的免费额度，无需绑定信用卡。
• 超长上下文窗口：支持 100 万 token 的上下文，可以一次性处理大型代码库或长文档。
• 内置实用工具：自带 Google 搜索验证、文件操作、Shell 命令执行、网页抓取等功能，无需额外配置。
• MCP 协议扩展：支持 Model Context Protocol，可以接入 Imagen 图像生成、Veo 视频生成等第三方能力。
• GitHub 深度集成：提供官方 GitHub Action，可自动进行 PR 审查、Issue 分类等。

问题 6：如何让 Gemini CLI 记住项目特定的上下文或行为规则？

可以在项目根目录创建 GEMINI.md 文件，写入你希望 Gemini 遵循的规则或背景信息。例如：

# 项目规范
- 代码风格：使用 2 空格缩进，行尾加分号
- 测试框架：Jest
- 数据库：PostgreSQL 15

Gemini CLI 会自动读取该文件并将其作为对话的初始上下文。这类似于 .cursorrules 或 .clinerules 文件，但专为 Gemini 设计。

问题 7：运行 gemini 后界面卡住或没有响应怎么办？

常见原因和解决方法：

• 首次启动需要浏览器认证：确保终端有权限打开浏览器。如果使用 SSH 或无图形界面，请改用 API Key 方式认证（见问题 2）。
• 网络代理问题：如果使用公司网络，尝试设置代理：

  export HTTP_PROXY=http://你的代理地址:端口
  export HTTPS_PROXY=http://你的代理地址:端口
  gemini

• Node.js 版本过低：Gemini CLI 需要 Node.js 18 或更高版本。检查版本：

  node --version

  如果版本过低，使用 nvm install 20 升级。

问题 8：如何将 Gemini CLI 集成到 CI/CD 流水线或脚本中？

Gemini CLI 支持非交互式运行，非常适合自动化场景：

# 在脚本中直接执行命令
gemini "检查这个目录下所有 .js 文件是否有语法错误" --non-interactive

# 配合 GitHub Action 使用
# 在 .github/workflows 中配置：
# - uses: google-github-actions/run-gemini-cli@v1
#   with:
#     prompt: "Review this PR for potential bugs"

注意：在 CI 环境中，建议使用 API Key 认证（设置 GEMINI_API_KEY 环境变量），避免 OAuth 交互流程。