Gemini CLI实战指南：从安装配置到自动化工作流
1. 从零到一：为什么你需要一个Gemini CLI速查手册
如果你和我一样，每天都在和代码、终端、以及各种AI工具打交道，那你肯定明白一个道理：效率就是生命。当Google的Gemini API开放后，我第一时间就试用了官方的@google/gemini-cli工具。它确实强大，能让你直接在终端里调用Gemini模型，读文件、分析代码、甚至执行一些自动化任务，感觉像是给命令行装上了AI大脑。但问题也随之而来：它的命令、参数、配置选项散落在文档各处，每次想用个高级功能都得去翻找，更别提那些隐藏的快捷键和配置技巧了。这种割裂的体验，让我决定停下来，花时间把所有的功能点、使用技巧和踩过的坑系统地梳理一遍。于是，就有了这份我称之为“从零到英雄”的Gemini CLI速查手册。这不是一份冷冰冰的官方文档复刻，而是我作为一个重度命令行用户，在真实项目场景中反复使用、测试、优化后沉淀下来的实战指南。无论你是想快速上手，还是已经用过但想挖掘更深层的自动化潜力，这份手册都能让你少走弯路，把时间花在真正创造价值的事情上。
2. 环境准备与核心概念解析
2.1 安装方式的选择与背后的考量
安装gemini-cli最常见的方式是通过npm。这里有几个选择，每个选择背后都有不同的使用场景。
# 方式一：全局安装（最常用） npm install -g @google/gemini-cli全局安装是最直接的方式，安装后你可以在系统的任何终端窗口直接使用gemini命令。这适合将其作为日常开发工具链的一部分。但这里有个细节需要注意：由于是全局安装，它的版本是统一的。如果你同时在维护多个项目，而某个旧项目依赖gemini-cli的特定旧版本，全局安装可能会带来冲突。
# 方式二：使用npx临时运行（最灵活） npx @google/gemini-clinpx是npm自带的包运行器。这条命令会检查本地是否安装了@google/gemini-cli，如果没有，它会自动从网络下载最新版本并运行，运行完毕后不会将其持久化安装在你的电脑上。这种方式特别适合“尝鲜”或一次性任务。比如，你只是想临时用一下某个功能，或者在不常用的机器上操作，用npx可以避免污染全局环境。我个人的习惯是，在决定长期使用某个工具前，先用npx跑几次，确认它真的有用，再进行全局安装。
注意：无论是哪种安装方式，你都需要一个可用的Google AI Studio API密钥。首次运行
gemini命令时，CLI会引导你进行配置。请务必妥善保管你的API密钥，不要将其提交到代码仓库中。
2.2 理解Gemini CLI的核心工作模式
与OpenAI的ChatGPT网页版不同，gemini-cli不是一个持续的聊天会话界面。它的核心设计哲学是“任务驱动”和“上下文感知”。你可以把它想象成一个超级增强版的命令行工具，它不仅能执行命令，还能理解你当前的工作环境（比如目录里的文件），并基于此给出智能建议或直接操作。
它主要支持两种交互模式：
- 交互式CLI模式：直接输入
gemini命令进入。你会看到一个提示符，可以像聊天一样输入自然语言或特定命令。这对于探索性工作、复杂问题分解非常有用。 - 单次命令模式：使用
gemini -p “你的问题”。这适合集成到脚本中，或者快速执行一个明确的任务，比如“总结当前目录下所有.py文件的主要函数”。
理解这两种模式，是高效使用它的基础。交互模式用于探索和复杂对话，单次命令模式用于自动化和流水线。
3. 基础与中级命令实战详解
3.1 文件系统操作：让AI“看见”你的代码
gemini-cli最强大的功能之一就是能直接读取和分析你的本地文件。这不再是简单的“复制粘贴代码块”，而是让模型拥有了项目的完整上下文。
基础文件读取：
# 在交互式CLI中，你可以直接使用工具 ReadFile ./src/index.js # 或者更酷的，用自然语言 “读取并分析当前目录下的package.json文件”当你使用ReadFile工具时，CLI不仅仅是把文件内容扔给模型。它会连同文件的路径、类型（根据扩展名）一起作为上下文提供，这使得模型的分析可以更精准。例如，它知道.js文件是JavaScript，可能会关注ES模块语法或React组件。
文件夹读取与智能过滤：
ReadFolder ./my-project这是重量级功能。ReadFolder会递归读取指定目录下的所有文件。但这里有一个至关重要的实操心得：它内置了“Git-aware”的智能过滤。这意味着它会自动忽略像node_modules/、dist/、.git/、.env这类在版本控制和构建中产生的、通常不包含核心业务逻辑的目录和文件。这个设计非常贴心，避免了将大量无关的、可能敏感的（如.env）或庞大的（如依赖包）数据塞给模型，既节省了token，也保护了隐私，还提升了分析速度。
注意事项：虽然过滤很智能，但在处理包含大量非标准构建输出或配置的遗留项目时，你可能需要检查是否有关键文件被意外忽略了。模型的分析质量，直接取决于它“看到”的内容是否完整。
3.2 对话与记忆管理：打造持续的学习伙伴
和网页版聊天不同，终端会话容易丢失。gemini-cli提供了会话保存和记忆功能，让你能延续讨论。
/chat save refactor-plan这条命令会将当前整个对话上下文（包括你之前读入的文件、问过的问题、得到的回答）保存为一个带标签（如refactor-plan）的快照。之后，你可以随时通过/chat resume refactor-plan回来继续。这对于需要多天进行的代码重构设计、技术方案评审等长周期任务极其有用。
更高级的是/memory命令。你可以手动/memory add “本项目使用React 18和TypeScript 5”，将一些关键约束或背景信息加入模型的“长期记忆”。此后，在同一会话中，模型的所有回答都会考虑到这条信息。/memory refresh命令则会重新扫描项目根目录下的GEMINI.md文件（如果存在），将其内容加载为记忆。你可以把项目最重要的架构决策、编码规范、待办事项写在GEMINI.md里，让AI助手从一开始就了然于胸。
3.3 模型切换与配置：为任务选择合适的大脑
Gemini提供了不同规格的模型，适应不同场景。
--model gemini-1.5-flash # 切换到Flash模型 --model gemini-1.5-pro # 切换到Pro模型如何选择？这是我的经验法则：
- gemini-1.5-flash：速度极快，成本最低。适合需要快速响应的任务，比如简单的代码语法检查、单文件解释、生成一些模板代码或简单的shell命令。对于大多数日常的、交互式的问答，Flash模型是性价比最高的选择。
- gemini-1.5-pro：能力最强，支持更长的上下文，推理和分析能力更深入。适合复杂的、需要多步推理的任务，比如系统架构设计、跨多个文件的代码逻辑梳理、算法优化、从需求描述生成详细技术方案等。当你觉得Flash的回答过于浅显或需要处理非常复杂的上下文时，就切换到Pro。
在交互式CLI中，你可以随时用--model命令切换，实时感受两者的差异。对于自动化脚本，你可以在命令开始时指定模型，确保任务由最合适的“大脑”处理。
4. 高级工作流与集成技巧
4.1 Shell命令的无缝执行与沙盒安全
gemini-cli允许你直接在对话中执行Shell命令，这是实现“AI驱动自动化”的关键桥梁。
# 在CLI中，以感叹号开头直接执行shell命令 !ls -la !git log --oneline -5 !find . -name “*.ts” -type f想象一个场景：你让AI分析项目结构，它建议你“查看最近5次提交记录以了解改动背景”。你不需要手动切出终端，只需在AI的对话中让它执行!git log --oneline -5，结果会直接返回到对话上下文中，AI可以基于这个结果继续分析。这种无缝衔接极大地提升了效率。
但执行任意Shell命令存在安全风险。为此，gemini-cli引入了沙盒（Sandbox）模式。
# 启动CLI时即启用沙盒 gemini --sandbox # 或在会话中通过环境变量控制 export GEMINI_SANDBOX=docker沙盒模式会将所有!命令的执行隔离在一个容器（Docker/Podman）或受限环境（如macOS的sandbox-exec）中。这意味着即使AI被诱导执行了rm -rf /这样的危险命令，也只会影响沙盒环境，不会伤及你的宿主机。对于处理不受信任的项目代码或进行高风险实验时，务必启用沙盒模式。你可以通过export GEMINI_SANDBOX=docker来指定使用Docker作为沙盒后端。
4.2 与MCP服务器的深度集成
MCP（Model Context Protocol）是一个新兴的协议，旨在标准化AI模型与外部工具、数据源之间的连接。gemini-cli支持MCP，这将它从一个孤立的工具变成了一个可扩展的集成中心。
/mcp list # 查看当前已连接的MCP服务器通过MCP，gemini-cli可以连接数据库、JIRA、GitHub、内部API等几乎任何数据源。例如，连接一个“天气预报MCP服务器”后，你可以直接问：“基于我当前的行程（从MCP读取）和北京的天气（从天气MCP读取），我应该带什么衣服？” AI可以调用多个MCP工具来组合回答。
配置MCP服务器通常在settings.json中完成：
{ “mcpServers”: { “my-postgres-db”: { “command”: “npx”, // 启动MCP服务器的命令 “args”: [“@modelcontextprotocol/server-postgres”, “postgresql://user:pass@localhost/db”], “env”: { “PGPASSWORD”: “secret” } } } }实操心得：MCP的潜力在于打破数据孤岛。对于企业内部，可以开发连接内部知识库、监控系统、CMDB的MCP服务器，让Gemini CLI成为获取公司内部信息的统一智能入口。这部分的配置稍复杂，但一旦打通，效率提升是指数级的。
4.3 配置管理与故障排查
随着使用深入，你会需要一份稳定的配置。所有用户配置都位于~/.gemini/settings.json（全局）或项目目录下的.gemini/settings.json（项目特定）。
一份功能丰富的配置示例：
{ “model”: “gemini-1.5-pro”, // 默认模型 “sandbox”: “docker”, // 默认沙盒引擎 “checkpointing”: { “enabled”: true }, // 启用检查点，方便回滚复杂操作 “fileFiltering”: { // 自定义文件过滤规则 “exclude”: [“*.log”, “*.tmp”, “coverage/“] }, “bugCommand”: “echo ‘Bug found!’ | mail -s ‘Gemini CLI Issue’ team@example.com” // 自定义/bug命令行为 }故障排查是必备技能：
- 命令不生效：首先检查你是否在交互模式（
gemini）下单次命令模式（gemini -p）。某些命令如/chat save仅在交互模式下有效。 - 模型无响应或报错：运行
gemini --version检查CLI版本。运行/about查看当前模型和配置。最常见的问题是API密钥失效或网络连接问题。可以尝试设置export DEBUG=1后重新运行命令，查看详细的网络请求日志。 - 沙盒启动失败：如果使用
--sandbox失败，请确保Docker或Podman已在后台运行。在macOS上使用sandbox-exec可能需要额外的权限配置。 - 文件读取失败：检查文件路径是否正确，以及当前用户是否有读取权限。注意在Windows系统上，路径分隔符和转义字符可能与示例不同。
5. 专家级自动化与定制化方案
5.1 构建自动化脚本与流水线
gemini-cli的真正威力在于脱离交互，嵌入自动化流程。结合Shell脚本或Makefile，你可以打造强大的AI辅助工作流。
示例：每日代码审查助手脚本
#!/bin/bash # daily-code-review.sh REVIEW_DIR=“./src“ OUTPUT_FILE=“code_review_$(date +%Y%m%d).md“ # 1. 让AI分析当天修改的所有文件（通过git diff） git diff --name-only HEAD~1 HEAD | grep ‘.js$|.ts$|.py$’ | xargs -I {} echo “@{}” > files_to_review.txt # 2. 调用gemini-cli进行审查 echo “请对以下列表中的代码文件进行简要审查，重点检查潜在bug、代码风格不一致和性能问题：” > prompt.txt cat files_to_review.txt >> prompt.txt gemini -p “$(cat prompt.txt)” --model gemini-1.5-pro > “$OUTPUT_FILE“ # 3. 可选：将报告发送到团队频道 # curl -X POST -H ‘Content-Type: application/json’ -d “{\“text\“: \“代码审查报告已生成: $(cat $OUTPUT_FILE)\“}” $WEBHOOK_URL echo “代码审查完成，报告已保存至 $OUTPUT_FILE“这个脚本每天自动提取变更文件，交给Gemini Pro模型进行审查，并生成报告。你可以把它加入Cron任务，实现每日自动化代码质量巡检。
5.2 利用检查点实现复杂操作的回滚
对于由AI驱动的、多步骤的文件写入或重构操作，一旦出错可能难以手动恢复。gemini-cli的检查点（Checkpointing）功能就是为此而生。
# 在settings.json中启用 { “checkpointing”: { “enabled”: true } } # 执行一系列可能修改文件的操作后，系统会自动或手动创建检查点 # 查看可恢复的检查点 /restore # 恢复到某个特定时间点的状态 /restore 2025-06-22T10-00-00_000Z-my-file.txt-write_file其原理是在执行任何文件写入操作前，先备份原文件。检查点文件包含了足够的信息来撤销更改。这是一个非常重要的安全网，尤其是在你允许AI直接修改生产代码或配置文件之前。我建议在所有涉及文件写入的自动化脚本中，强制启用检查点功能。
5.3 开发自定义扩展
虽然gemini-cli本身功能强大，但总有满足不了的特殊需求。这时，你可以开发自己的扩展。扩展会被自动从以下位置加载：
<workspace>/.gemini/extensions<home>/.gemini/extensions
一个扩展本质上是一个符合其接口规范的Node.js模块。例如，你可以写一个扩展，增加一个/deploy-to-staging命令，这个命令封装了连接你的云服务器、拉取代码、重启服务等一系列操作。然后，你就可以在CLI里直接用自然语言说：“请将当前功能部署到预发布环境”，AI在理解你的意图后，可以直接调用你这个自定义扩展来完成部署。
开发扩展的要点：
- 仔细阅读
gemini-cli的官方开发文档，了解扩展接口。 - 确保扩展脚本是安全和幂等的。
- 在扩展中做好详细的日志记录，便于调试。
6. 性能调优、安全与最佳实践
6.1 成本控制与Token优化
使用Gemini API是会产生费用的（尽管Gemini 1.5 Flash的成本极低）。在自动化高频使用时，成本需要关注。
优化策略：
- 精准使用上下文：避免使用
ReadFolder ./读取整个大项目。而是通过@src/utils/或@package.json等方式，精准引入AI完成任务所必需的最小文件集合。 - 善用总结与压缩：对于漫长的对话，使用
/compress命令。它会让模型将之前的对话上下文总结成一个简短的摘要，然后用这个摘要替代原有的冗长历史，从而极大地节省后续交互的token消耗，同时不丢失关键信息脉络。 - 模型分级使用：在脚本中实施“漏斗策略”。先用快速的Flash模型进行初步筛选、格式化或简单问答。只有当Flash模型无法处理或信心不足时，才将任务传递给更强大也更贵的Pro模型。
- 监控用量：定期使用
/stats model命令查看不同模型的使用情况，做到心中有数。
6.2 安全红线与隐私保护
将AI引入本地开发环境，安全是重中之重。
- API密钥安全：永远不要将API密钥硬编码在脚本或提交到版本库。使用环境变量（如
GEMINI_API_KEY）或系统的密钥管理工具（如macOS的Keychain）。 - 敏感信息过滤：
gemini-cli默认会过滤.env、*secret*、*key*等文件，但这不是万无一失的。最佳实践是，永远不要在有真实敏感数据（生产数据库凭证、私钥）的项目目录中运行AI分析命令。可以建立一个剥离了敏感信息的“开发样本”目录供AI使用。 - 沙盒即标准：对于任何来自外部或不受信任的源代码，在运行AI分析或执行AI生成的命令时，必须启用
--sandbox模式。这应该成为一条团队纪律。 - 审查AI的输出：尤其是当AI建议你执行
!开头的Shell命令，或直接生成代码修改时，务必人工审查后再确认执行。AI可能会产生看似合理但存在安全隐患的建议（例如，建议一个存在已知漏洞的依赖包版本）。
6.3 融入团队工作流的最佳实践
要让gemini-cli在团队中发挥最大价值，而不仅仅是个人玩具，需要一些规范。
- 统一配置共享：在项目根目录创建
.gemini/settings.json文件，并提交到版本库。里面可以配置团队统一的文件过滤规则、默认模型（如规定代码审查用Pro，日常问答用Flash）、以及团队内部的MCP服务器地址。这能确保所有成员有一致的体验和安全基线。 - 创建项目知识库：鼓励团队成员将项目特有的架构决策、业务逻辑复杂点、常见陷阱等内容，以清晰的结构写入项目根目录的
GEMINI.md文件。这样，任何新成员（或AI）在接入项目时，通过/memory refresh就能快速掌握背景知识，提问和回答的质量都会大幅提高。 - 建立常用命令集：团队可以维护一个共享的“Gemini CLI命令手册”，记录下针对本项目常用的高效命令模板。例如：“如何为新的API端点生成集成测试？”、“如何分析本次发布的代码变更影响范围？”。
- 设立审查机制：对于AI生成的、将要并入主分支的代码，必须经过与人工编写代码同等严格（甚至更严格）的代码审查。重点审查逻辑正确性、安全性和是否符合项目规范。
我个人在实际使用中最大的体会是，gemini-cli不是一个用来替代思考的“答案机器”，而是一个能力倍增器。它最适合的场景是处理那些你知道怎么做但做起来很繁琐的事（比如阅读大量日志找错误模式），或者为你提供探索新问题域的起点和灵感。把它集成到你的终端工作流里，就像多了一位不知疲倦、知识渊博的结对编程伙伴。关键是要明确它的边界，用好它的长处，并用严格的安全和实践规范来驾驭它。