Gemini CLI 小贴士与技巧

本指南涵盖了约30条高效使用 Gemini CLI 进行代理式编码的专业技巧

Gemini CLI 是一款开源的 AI 助手，它将 Google 的 Gemini 模型的强大功能直接引入您的 终端。它作为一个对话式的“代理”命令行工具运行——这意味着它可以对您的请求进行推理、选择工具（例如执行 shell 命令或编辑文件），并执行多步骤计划来帮助您完成开发 工作流。

从实际应用来看，Gemini CLI 就像一位功能强大的结对编程伙伴和命令行助手。它在编码任务、调试、内容生成，甚至系统自动化方面表现出色，所有这些都通过自然语言提示来实现。在深入探讨专业技巧之前，让我们先快速回顾一下如何设置并运行 Gemini CLI。

目录

• 入门
• 技巧 1：使用 GEMINI.md 维持持久上下文
• 技巧 2：创建自定义斜杠命令
• 技巧 3：用您自己的 MCP 服务器扩展 Gemini
• 技巧 4：利用记忆添加与回忆
• 技巧 5：使用检查点和 /restore 作为撤销按钮
• 技巧 6：阅读 Google 文档、表格等。
• 技巧 7：用 @ 引用文件和图片以提供明确上下文
• 技巧 8：即时创建工具（让 Gemini 构建辅助工具）
• 技巧 9：使用 Gemini CLI 进行系统故障排除与配置
• 技巧 10：YOLO 模式——自动批准工具操作（谨慎使用）
• 技巧 11：无头与脚本模式（在后台运行 Gemini CLI）
• 技巧 12：保存并恢复聊天会话
• 技巧 13：多目录工作区——一个 Gemini，多个文件夹
• 技巧 14：在 AI 的帮助下整理和清理文件
• 技巧 15：压缩长对话以保持在上下文范围内
• 技巧 16：通过 ! 直通 shell 命令（与您的终端对话）
• 技巧 17：将每个 CLI 工具视为潜在的 Gemini 工具
• 技巧 18：利用多模态 AI——让 Gemini 能够查看图像等
• 技巧 19：为稳定性定制 $PATH（以及工具可用性）
• 技巧 20：通过令牌缓存和统计跟踪并减少令牌消耗
• 技巧 21：使用 /copy 快速复制到剪贴板
• 技巧 22：掌握 Ctrl+C 用于 shell 模式及退出
• 技巧 23：使用 settings.json 自定义 Gemini CLI
• 技巧 24：利用 IDE 集成（VS Code）获取上下文与差异比较
• 技巧 25：使用 Gemini CLI GitHub Action 自动化仓库任务
• 技巧 26：启用遥测以获取洞察与可观测性
• 技巧 27：关注路线图（后台代理等功能）
• 技巧 28：用 Extensions 扩展 Gemini CLI
• 额外乐趣：柯基模式彩蛋 🐕

入门

安装： 你可以通过 npm 安装 Gemini CLI。要进行全局安装，使用以下命令：

npm install -g @google/gemini-cli

或者使用 npx 直接运行而无需安装：

npx @google/gemini-cli

Gemini CLI 支持所有主流平台（基于 Node.js 和 TypeScript 构建）。安装完成后，在终端中直接运行 gemini 命令即可启动交互式 CLI。

认证： 首次使用时，你需要先对 Gemini 服务进行身份验证。你有两种选择：(1) Google 账号登录（免费层级） —— 这种方式允许你免费使用 Gemini 2.5 Pro，且享有较为宽松的使用限制（约每分钟 60 次请求、每天 1,000 次请求day）。启动时，Gemini CLI 会提示你使用 Google 账号登录（无需绑定支付信息required）。(2) API 密钥（付费或更高层级访问） —— 你可以从 Google AI Studio 获取 API 密钥，并设置环境变量 GEMINI_API_KEY 来使用它it。使用 API 密钥可以获得更高的配额以及企业级数据使用保护；在付费或计费模式下，提示内容不会用于模型训练，但日志可能会被保留以确保safety。

例如，将以下内容添加到你的 shell 配置文件中：

export GEMINI_API_KEY="YOUR_KEY_HERE"

基本用法： 要开始一个交互式会话，只需不带任何参数地运行 gemini 命令。你会看到 gemini> 提示符，可以在其中输入请求或命令。例如：

$ gemini
gemini> 使用 SQLite 创建一个 React 食谱管理应用

随后，Gemini CLI 将自动创建文件、安装依赖项、运行测试等，以完成你的请求。如果你更倾向于一次性调用（非交互式），可以使用 -p 标志并附带提示，例如：

gemini -p "总结附件文件的主要要点。@./report.txt"

这将输出一条响应并退出exit。你也可以将输入通过管道传递给 Gemini CLI：例如，echo "数到 10" | gemini 会通过 stdin 将提示发送给工具。

CLI 界面： Gemini CLI 提供了一个功能丰富的类似 REPL 的界面。它支持 斜杠命令（以 / 开头的特殊命令，用于控制会话、工具和设置）和 感叹号命令（以 ! 开头，可直接执行 shell 命令）。我们将在下面的高级技巧中详细介绍这些功能。默认情况下，Gemini CLI 处于安全模式，任何可能修改系统的行为（如写入文件、执行 shell 命令等）都会要求你确认。当建议执行某项工具操作时，你会看到差异对比或具体命令，并会被提示是否批准或拒绝（Y/n）。这样可以确保 AI 不会在未经你同意的情况下做出不必要的更改。

掌握了基础知识后，让我们来探索一系列高级技巧和隐藏功能，帮助你充分发挥 Gemini CLI 的潜力。每个技巧都先给出一个简单的示例，然后深入讲解其细节和注意事项。这些技巧融合了工具开发者（如 Taylor Mullen）和 Google 开发者关系团队的建议与洞见，同时也参考了社区的广泛经验，旨在为 Gemini CLI 的高级用户提供一份权威指南。

技巧 1：使用 GEMINI.md 实现持久上下文

快速用例： 避免在每次提示中重复相同的内容。通过创建 GEMINI.md 文件，提供项目特定的背景信息或指令，让 AI 始终掌握重要的上下文知识，而无需每次都告知它time。

在进行项目开发时，你通常会有一些全局性的细节——比如编码规范、项目架构或关键事实——希望 AI 在处理任务时能够始终牢记。Gemini CLI 允许你将这些内容编码到一个或多个 GEMINI.md 文件中。只需在项目目录中创建 .gemini 文件夹（如果尚未存在），然后添加一个名为 GEMINI.md 的 Markdown 文件，写入你希望 AI 持续记住的备注或说明即可。例如：

# 项目凤凰 - AI 助手

- 所有 Python 代码必须遵循 PEP 8 风格规范。  
- 使用 4 个空格进行缩进。  
- 用户正在构建数据管道；建议优先使用函数式编程范式。

将此文件放置在项目根目录中（或放在子目录中以提供更细粒度的上下文）。现在，每当您在该项目中运行 gemini 时，它会自动将这些指令加载到 上下文 中。这意味着模型将始终被这些指令预置，从而避免了每次提示都需要重复添加相同指导语的麻烦。

工作原理： Gemini CLI 使用一种分层的上下文加载系统。它会将全局上下文（来自 ~/.gemini/GEMINI.md，可用于跨项目的默认设置）与您的项目特定的 GEMINI.md，甚至子文件夹中的上下文文件相结合。越具体的文件会覆盖越通用的文件。您可以随时通过以下命令查看已加载的上下文：

/memory show

这将显示 AI 看到 的完整组合上下文。如果您对 GEMINI.md 进行了更改，请使用 /memory refresh 来重新加载上下文，而无需重启会话。

实用技巧： 使用 /init 斜杠命令快速生成一个初始的 GEMINI.md 文件。在新项目中运行 /init 会创建一个包含技术栈检测信息、项目摘要等内容) 的模板上下文文件。随后您可以编辑并扩展该文件。对于大型项目，可以考虑将上下文拆分为多个文件，并使用 @include 语法将其导入到 GEMINI.md 中。例如，您的主 GEMINI.md 可以包含类似 @./docs/prompt-guidelines.md 的行，以引入额外的上下文文件。这样可以使您的指令保持整洁有序。

通过精心设计的 GEMINI.md，您实际上为 Gemini CLI 提供了关于项目需求和规范的“记忆”。这种持久性上下文能够带来更相关的响应，并减少反复调整提示的需求。

技巧 2：创建自定义斜杠命令

快速用例： 通过定义您自己的斜杠命令来加速重复性任务。例如，您可以创建一个 /test:gen 命令，根据描述生成单元测试，或者创建一个 /db:reset 命令，用于删除并重新创建测试数据库。这可以通过针对您工作流程量身定制的一行命令来扩展 Gemini CLI 的功能。

Gemini CLI 支持自定义斜杠命令，您可以在简单的配置文件中定义它们。从底层来看，这些命令本质上是预定义的提示模板。要创建一个命令，您需要在 ~/.gemini/ 目录下创建一个 commands/ 目录，用于存放全局命令；或者在项目的 .gemini/ 文件夹中创建该目录，用于存放项目特定的命令。在 commands/ 目录内，为每个新命令创建一个 TOML 文件。文件名格式决定了命令名称：例如，名为 test/gen.toml 的文件将定义 /test:gen 命令。

我们来看一个例子。假设您希望创建一个根据需求描述生成单元测试的命令。您可以创建 ~/.gemini/commands/test/gen.toml 文件，内容如下：

# 调用方式：/test:gen "测试描述"  
description \= "根据需求生成单元测试。"  
prompt \= """  
您是一位资深的测试工程师。请根据以下需求，使用 Jest 框架编写一份全面的单元测试。

需求：{{args}}  
"""

现在，在重新加载或重启 Gemini CLI 后，您只需输入：

/test:gen "确保登录按钮在成功登录后重定向到仪表板"

Gemini CLI 将识别 /test:gen 命令，并将提示模板中的 {{args}} 替换为您提供的参数（本例中为需求描述）。随后，AI 将按照指示生成相应的 Jest 单元测试结果。description 字段是可选的，但会在您运行 /help 或 /tools 列出可用命令时使用。

这种机制非常强大——实际上，您可以用自然语言对 AI 进行脚本化。社区已经创建了许多有用的自定义命令。例如，Google 的 DevRel 团队分享了一组10 个实用的工作流命令（通过一个开源仓库），展示了如何脚本化常见的流程，比如生成 API 文档、清理数据或搭建样板代码。通过定义自定义命令，您可以将复杂的提示（或一系列提示）封装成可重复使用的快捷方式。

实用技巧： 自定义命令还可以用于强制格式化，或为某些任务赋予 AI 特定的“角色”。例如，您可以创建一个 /review:security 命令，始终在提示前加上“您是一名安全审计员……”以审查代码中的漏洞。这种方法可以确保 AI 在处理特定类型任务时的一致性。

要与团队共享命令，您可以将 TOML 文件提交到项目的仓库中（位于 .gemini/commands 目录下）。拥有 Gemini CLI 的团队成员在参与该项目时，将自动获取这些命令。这是一种在团队中标准化 AI 辅助工作流的好方法。

小贴士 3：通过自定义 MCP 服务器扩展 Gemini

快速用例： 假设你希望 Gemini 能够与某个外部系统或自定义工具进行交互，而这些工具并未内置在 Gemini 中——例如查询专有数据库，或者与 Figma 设计集成。你可以通过运行一个自定义的 模型上下文协议（MCP）服务器，并将其接入 Gemini 的 CLI 来实现。MCP 服务器允许你为 Gemini 添加新的工具和能力，从而有效 扩展该智能体的功能。

Gemini CLI 默认自带多个 MCP 服务器（例如支持 Google 搜索、代码执行沙箱等），同时你也可以添加自己的 MCP 服务器。MCP 服务器本质上是一个外部进程（可以是本地脚本、微服务，甚至云端端点），它遵循一套简单的协议，用于为 Gemini 处理特定任务。正是这种架构设计使得 Gemini CLI 具备极高的 可扩展性（参考链接）。

MCP 服务器示例： 社区及 Google 官方提供的一些 MCP 集成包括 Figma MCP（用于从 Figma 获取设计详情）、剪贴板 MCP（用于读取或写入系统剪贴板）等。事实上，在一次内部演示中，Gemini CLI 团队展示了一个“Google 文档 MCP”服务器，可以直接将内容保存到 Google 文档中（参考链接）。其核心思想是，当 Gemini 需要执行内置工具无法完成的操作时，便可以委托给你的 MCP 服务器来处理。

如何添加一个 MCP 服务器： 你可以通过 settings.json 文件或直接使用 CLI 来配置 MCP 服务器。若想快速设置，可以尝试以下 CLI 命令：

gemini mcp add myserver --command "python3 my_mcp_server.py" --port 8080

这条命令会注册一个名为 “myserver”的服务器，Gemini CLI 将通过执行指定的命令（此处为 Python 脚本）并在 8080 端口上启动该服务器。相应地，在 ~/.gemini/settings.json 文件中，将会新增一条关于 mcpServers 的配置项，如下所示：

"mcpServers": {
  "myserver": {
    "command": "python3",
    "args": ["-m", "my_mcp_server", "--port", "8080"],
    "cwd": "./mcp_tools/python",
    "timeout": 15000
  }
}

这段配置（基于官方文档）告诉 Gemini 如何启动 MCP 服务器以及其工作目录。一旦服务器运行起来，它所提供的工具就会对 Gemini CLI 可用。你可以通过斜杠命令列出所有 MCP 服务器及其工具：

/mcp

这将显示所有已注册的服务器及其暴露的工具名称。

MCP 的强大之处： MCP 服务器能够提供 丰富且多模态的结果。例如，通过 MCP 提供的工具返回一张图片或一个格式化的表格，作为对 Gemini CLI 的响应（参考链接）。此外，MCP 还支持 OAuth 2.0 认证，因此你可以通过 MCP 工具安全地连接到各类 API（如 Google API、GitHub 等），而无需暴露任何凭据（参考链接）。简而言之，只要你能编写代码实现某项功能，就可以将其封装为 MCP 工具，从而使 Gemini CLI 成为一个协调多种服务的中枢平台。

默认工具与自定义工具： 默认情况下，Gemini CLI 自带的工具已经覆盖了相当广泛的功能（如读取文件、网络搜索、执行 Shell 命令等），但借助 MCP 服务器，你还可以进一步拓展其能力。一些高级用户已经创建了用于对接内部系统的 MCP 服务器，或者执行特定的数据处理任务。例如，你可以构建一个 database-mcp 服务器，提供 /query_db 工具，用于在公司数据库上执行 SQL 查询；或者开发一个 jira-mcp 服务器，以自然语言方式创建 Jira 工单。

在创建自定义 MCP 服务器时，请务必注意安全性：默认情况下，自定义的 MCP 工具需要用户确认才能执行，除非你将其标记为可信。你可以通过设置 trust: true 来使整个服务器的所有工具自动获得批准，或者仅对特定的安全工具进行白名单授权，而将危险工具列入黑名单（参考链接）。

总而言之，MCP 服务器开启了无限的集成可能性。它是 Gemini CLI 的一项高级功能，能够将你的 AI 助手与所需的任何系统无缝连接起来。如果你有兴趣构建自己的 MCP 服务器，不妨查看官方的 MCP 指南 以及社区中的相关示例。

小贴士 4：善用记忆添加与调取

快速应用场景： 通过将重要信息添加到 AI 的长期记忆中，使其随时可用。例如，在确定了数据库端口或 API Token 后，你可以执行以下命令：

/memory add "我们的预发布 RabbitMQ 服务运行在 5673 端口"

这会将该信息存储起来，这样你（或 AI）就不会在后续使用时忘记它[1]。之后，你可以随时使用 /memory show 命令查看所有已存储的记忆内容。

/memory 命令提供了一种简单而强大的持久化记忆机制。当你使用 /memory add <text> 时，指定的文本会被追加到项目的全局上下文中（实际上，它会被保存到全局的 ~/.gemini/GEMINI.md 文件中，或者项目的 GEMINI.md 文件中[2]）。这有点像做一张便签并将其固定在 AI 的虚拟公告板上。一旦添加，AI 在未来的每次交互中，无论是在哪个会话里，都会始终看到这条便签内容，因为它会出现在提示词的上下文中。

举个例子：你在调试一个问题时发现了一个不太明显的关键点——“配置标志 X_ENABLE 必须设置为 true，否则服务无法启动”。如果你将这一信息添加到记忆中，那么在后续讨论相关问题时，AI 不会忽略这个关键细节——因为它已经在上下文中了。

/memory 命令的用法：

• /memory add "<text>" —— 将事实或备注添加到记忆中（持久化上下文）。此操作会立即将新条目更新到 GEMINI.md 文件中。

• /memory show —— 显示记忆中的全部内容（即当前加载的上下文文件的合并内容）。

• /memory refresh —— 从磁盘重新加载上下文。如果在 Gemini CLI 外部手动编辑了 GEMINI.md 文件，或者有多人协作编辑该文件时，此命令非常有用。

由于记忆是以 Markdown 格式存储的，你也可以直接手动编辑 GEMINI.md 文件来整理或组织信息。不过，/memory 命令主要是为了方便对话过程中使用，避免你需要每次都打开编辑器。

进阶小技巧： 这一功能非常适合用于记录决策过程。比如，在聊天过程中你决定采用某种方案或规则（如使用某个特定的库，或约定一种代码风格），就可以将其添加到记忆中。这样，AI 在后续对话中就会记住这一决定，从而避免出现前后矛盾的情况。尤其在持续数小时甚至数天的长会话中，这种方法非常实用——通过保存关键点，可以有效缓解模型在长时间对话中容易遗忘早期上下文的问题。

此外，你还可以利用它来记录个人笔记。由于 ~/.gemini/GEMINI.md（全局记忆）会在所有会话中被加载，因此你可以将一些通用的偏好或信息放在这里。例如：“用户的姓名是 Alice。请以礼貌的方式交流，避免使用俚语。”这相当于为 AI 配置其个性或全局知识。不过需要注意的是，全局记忆适用于所有项目，因此不要将项目-specific 的信息混入其中。

总之，记忆添加与调取 功能有助于 Gemini CLI 维持对话状态。你可以把它看作一个随着项目进展不断增长的知识库。通过它，你可以避免重复说明同一内容，也能提醒 AI 记住那些原本可能需要从头再探索的事实。

小贴士 5：使用检查点功能和 /restore 命令作为撤销按钮

快速用例： 如果 Gemini CLI 对你的文件进行了一系列你不满意的操作，你可以立即回滚到之前的状态。在启动 Gemini 时（或在设置中）启用检查点功能，并使用 /restore 命令来撤销更改，就像轻量级的 Git revert 一样。/restore 会将你的工作区恢复到已保存的检查点；根据检查点的捕获方式，对话状态可能会受到影响。

Gemini CLI 的 检查点功能 就像一个安全网。启用后，CLI 会在每次执行可能修改文件 的工具之前，自动为项目文件拍摄快照。如果出现问题，你就可以回退到上一个已知的良好状态。这实际上就是对 AI 操作的一种版本控制，而无需每次都手动提交到 Git。

使用方法： 你可以通过在启动 CLI 时添加 --checkpointing 标志来开启检查点功能：

gemini --checkpointing

或者，你也可以将其设为默认选项，在配置文件中的 settings.json 中添加 "checkpointing": { "enabled": true }。一旦启用，你会发现每次 Gemini 即将写入文件时，都会显示类似“已保存检查点”的提示。

如果你随后发现 AI 所做的编辑存在问题，你有两种选择：

• 运行 /restore list（或仅运行 /restore 而不带参数），查看带有时间戳和描述的最近检查点列表。

• 运行 /restore <id> 来回滚到特定的检查点。如果你省略 ID 并且只有一个待处理的检查点，它将按默认 恢复该检查点。

例如：

/restore

Gemini CLI 可能会输出：

0: [2025-09-22 10:30:15] 在运行 'apply_patch' 之前
1: [2025-09-22 10:45:02] 在运行 'write_file' 之前

然后你可以执行 /restore 0，将所有文件更改（甚至对话上下文）恢复到该检查点时的状态。这样，你就可以“撤销”一次错误的代码重构或其他任何由 Gemini 做出 的更改。

恢复的内容： 检查点会捕获你的工作目录状态（所有 Gemini CLI 允许修改的文件）以及工作区文件（对话状态也可能根据检查点的捕获方式一并回滚）。当你执行恢复时，它会用旧版本覆盖文件，并将对话记忆重置为该快照。这就像是让 AI 代理时光倒流，回到它犯错之前的那一刻。需要注意的是，它不会撤销外部副作用（例如，如果 AI 执行了数据库迁移，则无法撤销），但文件系统和聊天上下文中的内容都可以被恢复。

最佳实践： 对于非简单的任务，建议始终开启检查点功能。它的开销很小，却能带来安心感。如果你发现不需要检查点（一切顺利），随时可以清除它，或者直接让下一个检查点覆盖掉。开发团队特别推荐在进行多步骤的代码编辑 之前使用检查点功能。不过，对于关键项目，仍然应该以正规的版本控制（Git）作为主要的安全保障网——可以将检查点视为一种方便的快速撤销手段，而非完整的版本控制系统。

总之，借助 /restore 命令，你可以更放心地使用 Gemini CLI。你可以让 AI 尝试大胆的改动，同时知道在需要时有一个“哎呀，糟了！”按钮可以帮你回退。

小贴士 6：读取 Google 文档、表格等。配置好 Workspace MCP 服务器后，只需粘贴文档/表格的链接，MCP 就会根据权限将其抓取下来。

快速用例： 假设你有一个 Google 文档或表格，里面包含一些规格说明或数据，你想让 AI 使用这些内容。这时不必手动复制粘贴，直接提供链接即可；只要配置了 Workspace 的 MCP 服务器，Gemini CLI 就能自动抓取并读取该文件。

例如：

总结这份设计文档中的需求：https://docs.google.com/document/d/<id>

Gemini 会提取该文档的内容，并将其融入到回复中。同样地，它也能通过链接读取 Google 表格或云端硬盘中的文件。

工作原理： 这些功能通常通过 MCP 集成 实现。Google 的 Gemini CLI 团队已经开发（或正在开发）针对 Google Workspace 的连接器。一种常见的方式是运行一个小型的 MCP 服务器，利用 Google 的 API（如 Docs API、Sheets API 等），在接收到 URL 或 ID 时获取文档内容。配置完成后，你可以使用斜杠命令，比如 /read_google_doc，或者启用自动检测功能，当识别到 Google 文档链接时，就会调用相应工具进行抓取。

例如，在 Agent Factory 播客的演示中，团队就使用了一个 Google 文档 MCP，将摘要直接保存到了文档中[1]——这也意味着他们首先能够读取文档内容。实际操作中，你可能会这样输入：

@https://docs.google.com/document/d/XYZ12345

在 URL 前加上 @ 符号（上下文引用语法），会提示 Gemini CLI 去抓取该资源。如果已配置了 Google 文档集成，文档内容就会像本地文件一样被引入，随后 AI 可以对其进行摘要总结、回答相关问题，或在对话中进一步使用。

类似地，如果你粘贴一个 Google 云端硬盘的 文件链接，经过正确配置的云端硬盘工具就可以下载或打开该文件（前提是已设置好权限和 API 访问）。而对于 Google 表格，可以通过一个运行查询或读取单元格区域的 MCP 来实现，这样你就可以询问：“这个表格[链接]中预算列的总和是多少？”然后让 AI 自动计算出来。

如何设置： 截至目前，Google Workspace 的集成可能还需要一些手动配置（例如获取 API 凭证、运行 MCP 服务器等），具体可参考 Kanshi Tanaike 的示例。建议关注官方的 Gemini CLI 仓库和社区论坛，看看是否有现成的扩展可用——比如官方的 Google 文档 MCP 未来可能会以插件形式发布。如果你愿意动手，也可以参照关于如何在 MCP 服务器中使用 Google API 的指南来编写自己的集成[2]。通常需要处理 OAuth 流程（Gemini CLI 已经支持 MCP 服务器的 OAuth 授权），然后再暴露诸如 read_google_doc 之类的工具。

使用技巧： 当这些工具配置好后，使用起来非常简单：只需在提示中提供链接，AI 就会自动调用相应工具进行抓取；或者直接使用斜杠命令，如 /doc open <URL>。你可以通过运行 /tools 查看当前可用的命令列表——Gemini CLI 会列出所有工具和自定义命令[3]。

总之，Gemini CLI 能够突破本地文件系统的限制，无论是 Google 文档、表格、云端硬盘，还是其他外部内容，都可以通过引用方式引入。这一技巧不仅省去了手动复制粘贴的麻烦，还能保持对话的自然流畅性：只需指向所需的文档或数据集，AI 就会自动获取所需信息。这使得 Gemini CLI 成为一名真正的 知识助手，帮助你充分利用手头的所有信息，而不仅仅是本地磁盘上的文件。

（注：访问私有文档当然需要 CLI 具备相应的权限。请务必确保任何集成都符合安全和隐私要求。在企业环境中，设置此类集成可能还需要额外的身份验证步骤。）

小贴士 7：使用 @ 引用文件和图片，明确提供上下文

快速用例： 不必再用语言描述文件内容或图片，直接让 Gemini CLI 直接读取它们即可。通过 @ 语法，你可以将文件、目录或图片附加到提示中。这能确保 AI 看到这些文件中的确切内容作为 上下文。例如：

给我解释这段代码：@./src/main.js

这会将 src/main.js 的内容包含在提示中（不超过 Gemini 的上下文大小限制），这样 AI 就可以阅读并解释它 等。这种 @ 文件引用 是 Gemini CLI 对开发者来说最强大的功能之一。它消除了歧义——你不是让模型依靠记忆或猜测来理解文件，而是直接把文件交到它手中进行阅读。你可以将其用于源代码、文本文档、日志等。同样地，你也可以引用 整个目录：

将 @./utils/ 中的代码重构为使用 async/await。

通过添加以斜杠结尾的路径，Gemini CLI 会递归地包含该 目录 中的文件（在合理范围内，同时尊重忽略文件和大小限制）。这对于多文件的重构或分析非常有用，因为 AI 可以将所有相关模块放在一起考虑。

更令人印象深刻的是，你还可以在提示中引用 像图片这样的二进制文件。Gemini CLI（利用 Gemini 模型的多模态能力）能够理解图像。例如：

描述一下这张截图里有什么：@./design/mockup.png

图像会被输入到模型中，AI 可能会回答类似“这是一个登录页面，有一个蓝色的登录按钮和一个页眉图片” 等。你可以想象它的用途：审查 UI 原型图、整理照片（我们将在后面的技巧中看到），或者从图像中提取文字（Gemini 也能进行 OCR）。

关于如何有效使用 @ 引用的一些注意事项：

• 文件限制： Gemini 2.5 Pro 拥有超大的上下文窗口（最多 100 万 token)，因此你可以包含相当大的文件或大量文件。不过，极大型文件可能会被截断。如果某个文件非常庞大（比如有数十万行），建议先对其进行摘要处理，或将其拆分成若干部分。Gemini CLI 会在引用过大或因大小原因跳过部分内容时发出警告。

• 自动忽略： 默认情况下，Gemini CLI 会尊重你的 .gitignore 和 .geminiignore 文件，在引入目录 上下文 时予以忽略。因此，如果你使用 @./ 引用项目根目录，它不会将巨大的被忽略文件夹（如 node_modules）一股脑塞入提示中。你可以通过 .geminiignore 自定义忽略模式，其工作方式与 .gitignore 类似。

• 显式与隐式上下文： Gemini CLI 的创建者泰勒·穆伦强调，应使用 @ 进行 显式上下文注入，而不是依赖模型的记忆或自己对内容进行总结。这样做更加精准，能确保 AI 不会产生幻觉。只要可能，就应使用 @ 引用来指向事实来源（代码、配置文件、文档）。这种做法可以显著提高准确性。

• 链式引用： 你可以在一个提示中包含多个文件，例如：

比较 @./foo.py 和 @./bar.py，并告诉我它们的区别。

CLI 会同时包含这两个文件。只需注意 token 限制；多个大文件可能会占用大量上下文窗口。

使用 @ 实质上就是让你 即时向 Gemini CLI 输入知识。它将 CLI 变成一个能够处理文本和图像的多模态阅读器。作为一名高级用户，养成利用这一功能的习惯吧——通常比让 AI 做“打开文件 X 并执行 Y”之类的事情更快、更可靠（因为 AI 可能会自行决定是否执行）。相反，你明确地把它交给 AI 来处理。

小贴士 8：即时创建工具（让 Gemini 构建辅助程序）

快速用例： 如果手头的任务可以通过一个小脚本或实用工具来简化，你可以直接在当前会话中让 Gemini CLI 为你生成这个工具。例如，你可以说：“写一个 Python 脚本，解析此文件夹中的所有 JSON 文件，并提取错误字段。”Gemini 会生成相应的脚本，随后你就可以通过 CLI 直接执行它。本质上，你可以在工作过程中 动态扩展工具集。

Gemini CLI 并不局限于其预置的工具；当需要时，它还能利用自身的编码能力临时构建新工具。这种情况往往以隐式方式发生：如果你请求完成一项复杂任务，AI 可能会建议先创建一个包含代码的临时文件，再运行该文件。当然，作为用户，你也可以明确引导这一过程：

• 创建脚本： 你可以提示 Gemini 使用你选择的语言编写脚本或程序。它很可能会使用 write_file 工具来生成文件。例如：

生成一个 Node.js 脚本，读取当前目录下的所有 `.log` 文件，并报告每个文件的行数。

Gemini CLI 会草拟代码，在你确认后将其写入文件（如 script.js）。之后，你可以通过 ! shell 命令（例如 !node script.js）来运行它，或者直接让 Gemini CLI 执行——如果 AI 认为这是计划的一部分，它甚至可能自动调用 run_shell_command 来运行刚刚生成的脚本。

• 通过 MCP 创建临时工具： 在更高级的场景中，AI 甚至可能建议启动一个 MCP 服务器来处理某些特定任务。比如，如果你的指令涉及大量文本处理，而这些任务更适合用 Python 完成，Gemini 就可以生成一个简单的 Python MCP 服务器并运行它。虽然这种情况较为少见，但它充分展示了 AI 能够即时搭建新的“代理”。Gemini CLI 团队的一张幽默幻灯片曾提到“什么都能用 MCP 服务器搞定，甚至连名为 LROwn 的都行”——暗示你可以让 Gemini 运行自身或其他模型的实例，不过这更多是一种技巧性玩法，而非实际用途。

这里的关键优势在于 自动化。你无需停下来手动编写辅助脚本，而是可以让 AI 在工作流程中直接完成这项任务。这就像是拥有一位能够按需创建工具的助手。对于数据转换、批量操作，或是内置工具无法直接支持的一次性计算任务而言，这种方式尤为有用。

注意事项与安全性： 当 Gemini CLI 为新工具编写代码时，你仍应在运行前仔细审查。借助 /diff 视图（Gemini 会在你批准写入文件之前显示文件差异对比），你可以逐行检查代码，确保其符合预期，且不存在恶意或破坏性内容（除非你的指令明确要求，否则 AI 不应生成有害代码；但如同任何由 AI 生成的代码一样，尤其是那些会删除或修改大量数据的脚本，务必再次核对逻辑）。

示例场景： 假设你有一个 CSV 文件，想要以复杂的方式对其进行筛选。你让 Gemini CLI 来完成这项任务，它可能会回应：“我将编写一个 Python 脚本来解析 CSV 并应用筛选条件。”随后，它会创建 filter_data.py 文件。在你确认并运行该脚本后，便得到所需结果，而这个脚本此后可能就不再需要了。这种临时性的工具生成正是高效之举——它表明 AI 能够自主扩展自身能力。

进阶提示： 如果你觉得某个脚本在当前场景之外也很有用，不妨将其提升为永久可用的工具或命令。例如，如果 AI 生成了一个优秀的日志处理脚本，你日后可以将其转化为自定义的斜杠命令（小贴士 #2），以便随时复用。Gemini 的生成式能力与扩展机制相结合，使得你的工具集能够在使用 CLI 的过程中不断进化。

总之，不要局限于 Gemini 自带的功能。把它当作一位初级开发者，能够迅速编写新程序，甚至搭建小型服务器来帮助解决问题。这种方法正体现了 Gemini CLI 的“代理式”理念——它会自行判断需要哪些工具，即便必须当场编写代码也毫不迟疑。

小贴士 9：使用 Gemini CLI 进行系统排查与配置

快速用例： 您可以在代码项目之外运行 Gemini CLI，以协助处理常规的系统任务——可以把它看作您操作系统的智能助手。例如，如果您的 shell 行为异常，您可以打开 Gemini 并在主目录下询问：“修复我的 .bashrc 文件，它似乎有错误。”Gemini 那么会为您打开并编辑该配置文件。

本小贴士强调了 Gemini CLI 并不局限于代码项目——它是您整个开发环境的 AI 助手。许多用户已经利用 Gemini 来自定义他们的开发环境或修复机器上的问题：

• 编辑 dotfiles： 您可以通过引用（@~/.bashrc）加载您的 shell 配置文件（.bashrc 或 .zshrc），然后让 Gemini CLI 对其进行优化或故障排除。例如：“我的 PATH 没有正确识别 Go 二进制文件，你能帮我修改 .bashrc 来解决这个问题吗？”AI 可以插入正确的 export 语句，并在保存更改前显示差异对比供您确认。

• 诊断错误： 如果您在终端或应用程序日志中遇到难以理解的错误信息，可以直接复制并输入到 Gemini CLI 中。它会分析错误消息，并常常给出解决问题的建议。这类似于使用 StackOverflow 或 Google 的方式，但不同的是，AI 会直接针对您的具体情况提供指导。例如：“当我运行 npm install 时，出现了 EACCES 权限错误——该如何解决？”Gemini 可能会判断这是 node_modules 目录权限的问题，并指导您更改目录所有者或使用合适的 Node.js 版本管理工具。

• 无需项目即可运行： 默认情况下，如果您在没有 .gemini 上下文的目录中运行 gemini，只是意味着未加载特定于项目的上下文——但这并不妨碍您充分利用 CLI 的功能。这对于临时性的系统排查任务非常有用。即使没有可供参考的代码文件，您仍然可以通过它执行 Shell 命令或获取网络信息。本质上，您可以将 Gemini CLI 视为一个由 AI 驱动的终端，不仅能与您对话，还能替您完成实际操作。

• 工作站自定义： 想更改某个设置或安装新工具吗？您可以直接询问 Gemini CLI：“在我的系统上安装 Docker”或“配置 Git 使用 GPG 签名提交”。CLI 会尝试执行这些步骤，可能会从网上搜索相关说明（借助搜索工具），然后自动运行相应的 Shell 命令。当然，在执行之前请务必仔细查看并确认每一条命令——不过，对于多步骤的配置流程，这种方式确实能够节省大量时间。举个真实的例子：一位用户让 Gemini CLI “将我的 macOS Dock 设置为自动隐藏，并取消延迟”，AI 很快就成功执行了所需的 defaults write 命令。

不妨把这种模式想象成将 Gemini CLI 当作一个 智能 Shell 来使用。事实上，您还可以将其与小贴士 16（Shell 透传模式）结合使用——有时您可能需要进入 ! Shell 模式来验证某些内容，随后再切换回 AI 模式，让 AI 分析输出结果。

注意事项： 在执行系统级别的任务时，请对那些具有广泛影响的命令保持谨慎，比如 rm -rf 或系统配置更改。Gemini CLI 通常会要求您确认，并且不会在您未看到的情况下擅自执行任何操作。但作为高级用户，您应当清楚正在做出哪些更改。如果不确定，可以在执行前让 Gemini 解释相关命令的作用，例如：“请解释一下 defaults write com.apple.dock autohide-delay -float 0 是做什么的”——只要您这样提问，它就会主动为您解释，而不会直接执行。

故障排除小技巧： 另一个实用的功能是利用 Gemini CLI 解析日志或配置文件，查找潜在问题。例如：“扫描这份 Apache 配置文件，看看有没有错误”（通过 @httpd.conf 引入），或者“查看昨日下午 2 点左右的 syslog 日志，找出其中的错误”（如果有权限访问 /var/log/syslog）。这就像是拥有了一位技术管理员随时待命一样。它甚至能够根据常见错误模式推测崩溃原因或提出修复方案。

总之，请不要犹豫，随时将 Gemini CLI 作为您的环境问题助手。它旨在加速您的所有工作流——不仅仅是编写代码，还包括维护您所使用的开发环境。许多用户反馈称，借助 Gemini 的帮助自定义开发环境，仿佛拥有一位随时待命的技术伙伴，专门负责处理繁琐或复杂的配置步骤。

小贴士 10：YOLO 模式——自动批准工具操作（请谨慎使用）

快速用例： 如果你对自己的判断很有信心（或者想大胆尝试一下），可以让 Gemini CLI 直接执行工具操作，而无需每次都征求你的确认。这就是 YOLO 模式（You Only Live Once，即“人生只有一次”）。你可以通过 --yolo 标志启用该模式，也可以在 会话 中按下 Ctrl+Y 来切换。在 YOLO 模式下，一旦 AI 决定调用某个工具（比如运行 Shell 命令或写入文件），它就会立即执行，而不会弹出“是否批准？(y/n)”的提示。

为什么要使用 YOLO 模式？ 主要是为了提升效率和便利性，前提是你完全信任 AI 的决策。经验丰富的用户可能会在进行大量重复且安全的操作时开启 YOLO 模式。例如，如果你让 Gemini 连续生成 10 个不同的文件，每次都要手动批准会大大降低效率；而启用 YOLO 模式后，这些文件就能自动全部创建完成。另一个场景是在完全自动化的脚本或 CI 流水线中使用 Gemini CLI——你可以通过 --yolo 参数以无头模式运行，这样就不会因为等待确认而中断流程。

要从一开始就以 YOLO 模式启动 CLI，可以使用以下命令：

gemini --yolo

或者简写为 gemini -y。CLI 会显示一些提示信息（比如不同的命令行提示符或通知），表明自动批准功能已开启。在交互式会话中，你随时可以通过按 Ctrl+Y 来切换该模式——CLI 通常会在底部显示类似“YOLO 模式已启用（所有操作将自动批准）”的消息。

重要警告： YOLO 模式功能强大，但也非常危险。Gemini 团队自己就将其定位为“勇敢用户的专属功能”，这意味着你需要清楚地认识到，AI 可能会在未经询问的情况下执行潜在的危险命令。在正常模式下，如果 AI 决定运行 rm -rf /（最糟糕的情况），你会毫不犹豫地拒绝。但在 YOLO 模式下，这条命令会立即执行，很可能导致系统瘫痪。尽管这种极端错误发生的概率很低（AI 的系统提示中包含了安全准则），但确认机制的存在正是为了防止任何意外操作的发生。而 YOLO 模式则去除了这道安全屏障。

使用 YOLO 模式的最佳实践： 如果你希望兼顾便利性和安全性，可以考虑对特定命令设置白名单。例如，你可以在配置中指定某些工具或命令模式无需确认，比如允许所有 git 命令或只读操作自动执行。事实上，Gemini CLI 支持针对特定命令跳过确认的配置：例如，你可以设置 "tools.shell.autoApprove": ["git ", "npm test"]，使这些命令始终自动执行。这样一来，你就无需全局启用 YOLO 模式，而只需对安全的命令选择性地使用 YOLO。另一种方法是，在启用 YOLO 模式时将 Gemini 运行在一个沙盒或容器中，这样即使它执行了异常操作，也能有效隔离对主机系统的干扰（Gemini 提供了 --sandbox 标志，可将工具运行在 Docker 容器 中）。

许多高级用户会频繁地开关 YOLO 模式：在进行一系列简单的文件编辑或查询时开启，而在执行关键操作前关闭。你也可以利用快捷键快速切换。

总之，YOLO 模式虽然消除了繁琐的确认步骤，却也牺牲了必要的监督机制。这是一个适合专业人士使用的高级功能，但必须谨慎、明智地使用。它真正考验的是你对 AI 的信任程度（或者说是鲁莽程度！）。如果你刚接触 Gemini CLI，建议暂时不要使用 YOLO 模式，直到你充分理解它的工作方式和潜在风险。如果一定要使用，请务必加强版本控制和备份措施，以防万一。

（安慰你一句：其实很多人都有过类似的“惨痛”经历——社区里常有人开玩笑说：“我一不小心开了 YOLO，结果 Gemini 干了件离谱的事。”所以，用吧，不过……毕竟人生只有一次嘛。）

小贴士 11：无头模式与脚本模式（在后台运行 Gemini CLI）

快速用例： 您可以通过以 无头模式 运行 Gemini CLI，将其用于脚本或自动化任务。这意味着您可以通过命令行参数或环境变量提供一个提示（甚至是一整段对话），Gemini CLI 会生成输出并退出。这非常适合与其他工具集成，或按计划触发 AI 任务。

例如，如果您想在不打开 REPL 的情况下获取一次性回答，您已经知道可以使用 gemini -p "...prompt..."。这实际上就是无头模式的用法：它会打印模型的回答并返回到 shell。不过，您还可以做更多：

• 覆盖系统提示： 如果您希望以自定义的系统角色或指令集（不同于默认设置）来运行 Gemini CLI，可以使用环境变量 GEMINI_SYSTEM_MD。通过设置该变量，您可以告诉 Gemini CLI 忽略其内置的系统提示，并使用您提供的文件 代替。例如：

export GEMINI_SYSTEM_MD="/path/to/custom_system.md"
gemini -p "Perform task X with high caution"

这将加载您的 custom_system.md 作为系统提示（即 AI 遵循的角色和规则），然后再执行 提示。或者，如果您设置 GEMINI_SYSTEM_MD=true，CLI 会在当前项目的 .gemini 目录 中查找名为 system.md 的文件。这一功能非常高级——它本质上允许您用自定义指令 替换 CLI 的内置“大脑”，一些用户会将其用于特定的工作流（比如模拟特定角色或执行极其严格的政策）。请谨慎使用，因为替换核心提示可能会影响工具的使用（核心提示包含 AI 如何选择和使用 工具)。

• 通过 CLI 直接输入提示： 除了 -p 之外，还有 -i（交互式提示），它会启动一个会话并附带初始提示，然后保持会话打开。例如：gemini -i "Hello, let's debug something" 会打开 REPL，并且已经向模型问好。如果您希望在启动时立即提出第一个问题，这个选项就很有用。

• 使用 shell 管道进行脚本编写： 您不仅可以将文本，还可以将文件或命令输出通过管道传递给 Gemini。例如：gemini -p "Summarize this log:" < big_log.txt 会将 big_log.txt 的内容插入到提示中（位于“Summarize this log:”之后）。或者您也可以这样操作：some_command | gemini -p "Given the above output, what went wrong?"。这种技术可以让 Unix 工具与 AI 分析相结合。从无头的角度来看，这是一种单次执行的操作。

• 在 CI/CD 中运行： 您可以将 Gemini CLI 集成到构建流程中。例如，CI 流水线可能会先运行测试，然后使用 Gemini CLI 自动分析失败的测试输出并发布评论。通过使用 -p 标志和环境认证，这一过程可以被脚本化。（当然，要确保环境中具备所需的 API 密钥或认证信息。）

还有一个无头技巧：--format=json 标志（或配置设置）。如果进行相应配置，Gemini CLI 可以将响应以 JSON 格式输出，而不是人类可读的文本 文档. 这对于程序化消费非常有用——您的脚本可以解析 JSON 来获取答案或任何工具操作的详细信息。

为什么无头模式很重要： 它将 Gemini CLI 从一个交互式助手转变为其他程序可以调用的 后端服务 或实用工具。您可以安排一个 cron 作业，每晚运行一次 Gemini CLI 提示（想象一下利用 AI 逻辑生成报告或清理某些内容）。您也可以在 IDE 中设置一个按钮，用于触发针对特定任务的无头模式运行。

示例： 假设您想要每天获取某个新闻网站的摘要。您可以编写如下脚本：

gemini -p "Web-fetch \"https://news.site/top-stories\" and extract the headlines, then write them to headlines.txt"

加上 --yolo 参数，这样就不会再询问是否确认写入文件。这将使用网页抓取工具获取页面内容，并使用文件写入工具保存标题。整个过程完全自动，无需人工干预。一旦将 Gemini CLI 视为可脚本化的组件，其应用场景便无穷无尽。

总结： 无头模式 能够实现自动化。它是 Gemini CLI 与其他系统之间的桥梁。掌握无头模式意味着您可以扩展 AI 的使用范围——不仅限于您亲自在终端中输入指令时，即使您不在身边，AI 代理也能为您完成工作。

（小贴士：对于真正长时间运行且无需交互的任务，您还可以研究 Gemini CLI 的“计划”模式，以及它如何在无需干预的情况下生成多步计划。不过，这些属于超出本篇范围的高级主题。在大多数情况下，通过无头模式精心设计的单个提示就能完成很多工作。）

小贴士 12：保存与恢复聊天会话

快速用例： 如果你已经用 Gemini CLI 调试一个问题一个小时，现在需要暂停一下，也不必担心丢失对话上下文。使用 /chat save <名称> 命令即可保存当前会话。稍后（甚至在重新启动 CLI 后），你可以通过 /chat resume <名称> 继续之前中断的对话off。这样一来，长时间的对话就可以随时暂停并无缝继续。

Gemini CLI 实际上内置了一个聊天会话管理器。你需要掌握的命令有：

• /chat save <标签> —— 将当前对话状态以你提供的标签/名称保存起来provide。这个标签就像是该会话的文件名或键。如果你想多次保存，可以随意覆盖已有的标签。（建议使用描述性强的名称，例如 chat save fix-docker-issue。）

• /chat list —— 列出所有已保存的会话（即你曾经使用的标签used）。这有助于你回忆起之前保存时所取的名称。

• /chat resume <标签> —— 恢复指定标签的会话，完整还原保存时的对话上下文和历史记录saved。仿佛你从未离开过一样。之后你可以从那个点继续对话。

• /chat share —— （保存到文件）这个功能很有用，因为它允许你将整个聊天内容分享给他人，让对方可以继续之前的会话，几乎就像协作一样。

从技术实现上看，这些会话很可能存储在 ~/.gemini/chats/ 或类似目录中，其中包含了对话消息以及相关状态信息。这一特性在以下场景中尤为实用：

• 长时间调试会话： 有时与 AI 的调试过程会涉及多轮反复交流。如果一时无法解决，不妨先保存会话，稍后再回来继续（也许换个思路会有新灵感）。AI 仍然会“记住”之前的所有内容，因为完整的上下文会被重新加载。

• 跨日任务： 如果你将 Gemini CLI 用作项目助手，可能会为“重构模块 X”开启一个持续数天的会话。每天只需恢复该特定会话，就能保持上下文不被重置。与此同时，你还可以单独保存另一个关于“编写文档”的会话。切换工作场景时，只需保存当前会话并恢复另一个即可。

• 团队交接： 这种方式目前还比较实验性，但从理论上讲，你可以将已保存的聊天内容分享给同事（保存的文件通常是可移植的）。对方只需将其放入自己的 .gemini 目录并恢复会话，就能看到相同的上下文。当然，更实际、更简单的协作方式是直接复制日志中的相关问答，并使用共享的 GEMINI.md 或提示模板，不过值得注意的是，会话数据确实可以由你自行保存。

使用示例：

/chat save api-upgrade

（会话以 “api-upgrade” 为名称保存）

/quit

（稍后重新打开 CLI）

$ gemini
gemini> /chat list

（显示：api-upgrade）

gemini> /chat resume api-upgrade

此时，模型会以最后一次交互的状态欢迎你。你可以向上滚动查看，确认之前的全部消息都已恢复。

进阶提示： 保存聊天时，请使用有意义的标签[medium.com/@ferreradaniel/gemini-cli-free-ai-tool-upgrade-5-new-features-you-need-right-now-04cfefac5e93#:~:text=Naming%20conventions%20to%20keep%20projects,organized)。不要只用 /chat save session1 这样的通用命名，而应根据主题取名，比如 /chat save memory-leak-bug。这样在后续通过 /chat list 查看时，就能更快找到所需的会话。目前官方并未明确限制可保存的会话数量，但为了便于管理，偶尔清理一下旧的会话也是个好主意。

这一功能让 Gemini CLI 变成了一个持久可用的智能助手。你在对话中获得的知识不会丢失，随时可以暂停再继续。相比一些关闭后就会遗忘上下文的其他 AI 接口，这无疑是一个显著的优势。对于高级用户来说，这意味着你可以与 AI 同时进行多条并行的工作线程。就像你会为不同任务打开多个终端标签页一样，也可以保存多个聊天会话，并在任何时候恢复所需的那个。

小贴士 13：多目录工作区——一个 Gemini，多个文件夹

快速用例： 你的项目是否分散在多个仓库或目录中？你可以一次性启动 Gemini CLI，并让它同时访问所有这些目录，从而形成一个统一的工作空间。例如，如果你的前端和后端分别位于不同的文件夹中，你可以将两者都包含进来，这样 Gemini 就可以在两个目录中编辑或引用文件。

使用多目录模式有两种方式：

• 启动参数： 在启动 Gemini CLI 时使用 --include-directories（或 -I）参数。例如：

gemini --include-directories "../backend:../frontend"

假设你从某个 scripts 目录运行该命令，并希望包含两个同级文件夹。你需要提供一个以冒号分隔的路径列表。Gemini CLI 会将这些目录视为一个大型工作空间的一部分。

• 持久化设置： 你可以在 settings.json 中定义 "includeDirectories": ["path1", "path2", [...]](https://www.philschmid.de/gemini-cli-cheatsheet#:~-text=,61AFEF%22%2C%20%22AccentPurple). 如果你希望始终加载某些常用目录（例如多个项目共用的库文件夹），这种方式非常有用。路径可以是相对路径或绝对路径。路径中允许使用环境变量（如 ~/common-utils），具体请参阅 此处。

当多目录模式启用时，CLI 的上下文和工具会考虑所有已包含目录中的文件。执行 > /directory show 命令会列出当前工作空间中包含哪些目录。你也可以在会话期间动态添加目录，使用 /directory add [<path>](https://medium.com/@ferreradaniel/gemini-cli-free-ai-tool-upgrade-5-new-features-you-need-right-now-04cfefac5e93#:~-text=How%20to%20add%20multiple%20directories,step) 命令，它会即时加载该目录（并可能像启动时一样扫描其上下文信息）。

为什么要使用多目录模式？ 在微服务架构或模块化代码库中，通常一段代码位于一个仓库，另一段代码则位于另一个仓库。如果只在其中一个仓库中运行 Gemini，它就无法“看到”其他部分。通过将它们合并在一起，你可以实现跨项目的推理。例如，你可以问：“更新前端的 API 客户端，使其与后端的新 API 端点保持一致。”Gemini 可以同时打开后端文件夹查看 API 定义，并打开前端代码进行相应修改。如果没有多目录模式，你就只能逐一处理，手动传递信息。

示例： 假设你有一个 client/ 和一个 server/ 目录。你可以这样启动：

cd client
gemini --include-directories "../server"

现在在 gemini> 提示符下，输入 > !ls，你会看到它可以列出 client 和 server 目录中的文件（可能会显示为独立的路径）。你还可以执行：

并排打开 server/routes/api.py 和 client/src/api.js，比较函数名。

AI 将同时访问这两个文件。或者你可以说：

API 发生了变化：`/users/create` 端点现在变成了 `/users/register`。请相应地更新后端和前端。

它能够同时生成后端路由的补丁，并调整前端的 fetch 请求。

在底层，Gemini 会合并这些目录的文件索引。如果每个目录都非常大，可能会有一些性能方面的考量，但通常情况下，它能很好地处理多个中小型项目。相关文档指出，这实际上创建了一个具有多个根目录的工作空间。

小贴士： 即使你不经常使用多目录模式，也应知道，你仍然可以在提示中通过绝对路径引用文件系统中的文件（如 @/path/to/file）。然而，如果没有启用多目录模式，Gemini 可能没有权限编辑这些文件，也无法主动加载它们的上下文信息。而多目录模式会正式将这些文件纳入作用域，使它能够意识到整个集合中的所有文件，从而支持跨整个集合的搜索或代码生成等任务。

移除目录： 如果需要，可以使用 /directory remove <path>（或其他类似命令）将某个目录从工作空间中移除。这种情况较少见，但如果你不小心包含了某个目录，就可以将其移除。

总之，多目录模式能够统一你的开发上下文。对于多仓库项目或任何代码被拆分的情况，这都是必不可少的功能。它让 Gemini CLI 更像一个打开了整个解决方案的 IDE。作为专业用户，这意味着你的项目没有任何部分会超出 AI 的覆盖范围。

小贴士 14：借助 AI 整理并清理你的文件

快速用例： 厌倦了杂乱的 Downloads 文件夹或无序的项目资源？你可以让 Gemini CLI 扮演一位智能整理者。只需向它提供一个目录的概览，它就能对文件进行分类，甚至在你确认后将它们移动到子文件夹中。例如：“清理我的 Downloads：把图片移到 Images 文件夹，PDF 文件移到 Documents，然后删除临时文件。”

由于 Gemini CLI 能够读取文件名、文件大小，甚至预览文件内容，因此它可以基于这些信息做出明智的文件整理决策。社区开发的一款名为 “Janitor AI” 的工具就很好地展示了这一点：它通过 Gemini CLI 来区分重要文件和垃圾文件，并按类别进行归类。具体流程是先扫描目标目录，利用 Gemini 对文件名、元数据（必要时还包括文件内容）的分析结果，再将文件移至相应类别。值得注意的是，该工具并不会自动删除垃圾文件，而是将其移动到 Trash 文件夹中，供你审核后再做决定。

以下是你可以手动使用 Gemini CLI 复现类似工作流的方法：

1. 浏览目录内容： 使用提示让 Gemini 列出所有文件，并按类别进行划分。例如：

列出当前目录下的所有文件，并将其归类为“图片”、“视频”、“文档”、“压缩包”或其他。

Gemini 可能会先使用 !ls 或类似的命令获取文件列表，然后根据文件名和扩展名进行分析，从而生成分类结果。

1. 规划整理方案： 向 Gemini 询问它建议如何重新组织这些文件。例如：

为这些文件提出一个新的文件夹结构。我希望按文件类型分开（图片、视频、文档等）。同时，请识别出任何重复或不必要的文件。

AI 可能会给出如下计划：“创建以下文件夹：Images/、Videos/、Documents/、Archives/。将 X.png 和 Y.jpg 移至 Images/；将 A.mp4 移至 Videos/；等等。文件 temp.txt 看起来并不需要（可能是临时文件）。”

1. 执行移动操作并确认： 接着你可以指示它按照计划执行操作。它可能会使用 mv 等 Shell 命令逐个移动文件。由于这会直接修改你的文件系统，因此每一步都会弹出确认提示（除非你选择直接执行）。请仔细核对并批准这些操作。完成之后，你的目录就会按照建议整齐地组织起来。

在整个过程中，Gemini 的自然语言理解能力至关重要。它能够推理判断，比如根据文件名推断 IMG_001.png 是一张图片，而 presentation.pdf 则是一份文档，即使文件名并未明确标注。它甚至还能利用自身的视觉能力打开图片，查看其中的内容——例如区分截图、照片和图标——并据此为文件命名或排序相应地。

根据内容重命名文件： 一个非常神奇的应用场景是让 Gemini 根据文件内容为其重命名，使其更具描述性。开发者社区的文章《7 个令人惊叹的 Gemini CLI 技巧》提到，Gemini 可以扫描图像并根据其内容自动重命名内容。例如，如果文件名为 IMG_1234.jpg，但 AI 发现这是一张登录界面的截图，那么它可能会将其重命名为 login_screen.jpg。为此，你可以这样提问：

请查看这里的每一张 .png 图片，根据其内容为其重命名，使其更具描述性。

Gemini 会通过视觉工具打开每张图片，生成描述，然后提出类似 mv IMG_1234.png login_screen.png 的操作。这种方法可以显著改善资产的组织性，尤其适用于设计或照片相关的文件夹。

两步法： 在 Janitor AI 的讨论中提到，可以采用两步流程：首先进行粗略分类（重要文件、垃圾文件和其他），然后再进一步细化分组。你可以模仿这种做法：先将那些很可能可以删除的文件（比如大型安装程序 .dmg 文件或重复文件）与需要保留的文件分开，然后再专注于整理后者。务必仔细检查 AI 标记为“垃圾”的文件；它的判断未必完全准确，因此仍需人工监督。

安全提示： 当让 AI 执行文件移动或删除操作时，一定要事先做好备份，或者至少准备好恢复原状（使用 /restore 命令或你自己的备份）。建议先进行一次“模拟运行”：让 Gemini 打印出它本应执行的整理命令，但不实际执行，以便你审查。例如：“请列出完成此计划所需的 mv 和 mkdir 命令，但暂时不要执行。”在仔细核对命令清单后，你可以选择复制粘贴执行，或者直接指示 Gemini 继续推进。

这正是利用 Gemini CLI 完成“非显而易见”任务的一个绝佳例子——它不仅仅是编写代码，更是运用 AI 智能进行系统维护和整理。这不仅能节省时间，还能为混乱的局面带来一丝秩序。毕竟作为开发者，我们往往会积累大量杂物（日志、旧脚本、下载文件），而一位 AI 清洁工无疑会派上大用场。

小贴士 15：压缩长对话以保持上下文连贯

快速用例： 如果你已经与 Gemini CLI 对话了很长时间，可能会遇到模型上下文长度的限制，或者觉得整个会话变得过于冗长而难以管理。这时可以使用 /compress 命令来总结当前的对话内容，用一段简洁的摘要取代完整的聊天历史。这样既能为后续讨论腾出空间，又不必从头开始。

大型语言模型都有固定的上下文窗口（Gemini 2.5 Pro 的上下文窗口非常大，但并非无限）。一旦超出这个范围，模型可能会忘记之前的对话内容，或导致回答失去连贯性。/compress 功能本质上就是由 AI 自动生成的一份会话“简版概要”，能够保留关键信息。

工作原理： 当你输入 /compress 后，Gemini CLI 会将整个对话内容（不包括系统上下文）生成一个摘要，然后用这条摘要作为一条单独的系统或助手消息替换掉原有的聊天历史。这样一来，重要的细节得以保留，而逐字逐句的对话则被省略。系统还会提示你已进行压缩。例如，执行 /compress 后，你可能会看到如下内容：

--- 对话已压缩 ---
讨论摘要：用户和助手一直在调试应用程序中的内存泄漏问题。关键点：问题很可能出在 DataProcessor.js 文件中，对象未能正确释放。助手建议添加日志记录，并指出可能存在一个无限循环。用户正准备测试修复方案。
--- 摘要结束 ---

从那之后，模型处理之前内容时所依赖的上下文就只有这条摘要（再加上新收到的消息）。只要摘要准确地抓住了核心要点，通常就足以支持后续的对话。

何时压缩： 最好是在达到上下文限制之前就主动压缩。如果你发现会话已经很长（几百轮对话，或者上下文中包含大量代码），就可以提前进行压缩。速查表中提到有一个自动压缩的设置选项（例如，当上下文占用超过最大容量的 60% 时自动压缩 max)。如果启用了该选项，Gemini 会在必要时自动压缩，并通知你。如果没有启用自动压缩功能，那么手动使用 /compress 就是你的好帮手。

压缩后的操作： 压缩后，你可以像往常一样继续对话。如果需要，可以在超长会话中多次压缩。不过每次压缩都会损失一些细节，因此不要无故频繁压缩——否则你可能会对复杂的讨论只剩下非常简略的记忆。不过总体来说，AI 自身的总结能力相当不错，能够很好地保留关键事实；当然，如果你觉得某些内容很重要，也可以自己再补充说明一下。

上下文窗口示例： 举个例子：假设你通过引用多个文件导入了一个庞大的代码库，此时上下文已经达到 100 万 tokens（即上限）。如果你想切换到项目的另一部分，与其重新开始一个新的会话、丢失之前的所有理解，不如先进行压缩。摘要会把从代码中提取的知识浓缩起来，比如：“我们加载了模块 A、B、C。A 包含这些函数……B 和 C 之间存在这样的交互关系……”这样，你就可以带着这些抽象化的知识继续讨论新的问题了。

记忆与压缩的区别： 需要注意的是，压缩并不会将信息保存到长期记忆中，它只是针对当前会话的本地操作。如果你有一些绝对不能丢失的重要信息，可以参考小贴士 4（将内容添加到 /memory 中）——因为存储在记忆中的条目不会被压缩影响（它们会被重新插入到上下文中，毕竟这些内容原本就在 GEMINI.md 文件里）。压缩更多是用于处理临时性的聊天内容。

一个小提醒： 压缩之后，AI 的回复风格可能会略有变化，因为它实际上是在面对一条带有摘要的新“对话”。它可能会重新自我介绍，或者改变语气。你可以明确指示它：“请从这里继续……（我们刚刚进行了压缩）”，以使对话更加顺畅。不过在实际使用中，AI 通常能够很好地延续之前的语境。

总之，当会话变得过长时，记得使用 /compress 命令，以保持对话的效率和相关性。它可以帮助 Gemini CLI 更专注于整体的大方向，而不是纠结于每一条细枝末节的聊天记录。这样一来，你就可以进行长时间的调试或深入的设计讨论，而不用担心 AI 的“思维纸张”不够用。

小贴士 16：通过 ! 直通 Shell 命令（与你的终端对话）

快速用例： 在 Gemini CLI 会话的任何时刻，你都可以通过在命令前加上 ! 来直接运行 Shell 命令。例如，如果你想查看 Git 状态，只需输入 !git status，它就会在你的 终端 中执行。这样你就无需切换窗口或上下文——你仍然停留在 Gemini CLI 中，只是在告诉它：“让我快速运行一下这个命令。”

本小贴士介绍的是 Gemini CLI 中的 Shell 模式。使用方式有两种：

• 单条命令： 只需在提示符前加上 !，后接任意命令及参数即可。该命令会在当前工作目录下执行，并将输出 内联 显示。例如：

!ls -lh src/

会列出 src 目录下的文件，输出效果与普通终端一致。命令执行完毕后，Gemini 的提示符会恢复，你可以继续聊天或输入其他命令。

• 持久 Shell 模式： 如果你只输入 ! 并按下回车键，Gemini CLI 会切换到一个子模式，在这里你会看到一个 Shell 提示符（通常显示为 shell> 或类似形式）。此时你可以交互式地输入多条 Shell 命令。这实际上就是在 CLI 内部开启了一个迷你 Shell。退出此模式的方法是再次输入空行的 !（或 exit）。例如：

!
shell> pwd
/home/alice/project
shell> python --version
Python 3.x.x
shell> !

在最后一个 ! 之后，你便回到了正常的 Gemini 提示符。

为什么这很有用？ 因为开发工作往往兼具操作与询问两种需求。你可能正在与 AI 讨论某个问题，突然意识到需要编译代码或运行测试来验证结果。这时，你不必中断对话，而是可以快速完成这些操作，再将结果反馈给聊天窗口。事实上，Gemini CLI 经常会自动为你执行此类操作——比如当你请求修复测试时，它可能会自动运行 !pytest，举例). 不过作为用户，你也可以完全手动控制这一过程。

示例：

• 当 Gemini 建议了代码修复方案后，你可以运行 !npm run build 来检查是否能成功编译，然后复制错误信息并请 Gemini 协助解决。

• 如果你想用 vim 或 nano 打开文件，可以直接使用 !nano filename 来启动编辑器（不过需要注意的是，由于 Gemini CLI 自身有界面，直接在其中使用交互式编辑器可能会有些不便——最好还是利用内置的编辑器集成功能，或者将内容复制到外部编辑器中）。

• 你还可以通过 Shell 命令收集信息供 AI 使用：例如，!grep TODO -R . 可以查找项目中所有的待办事项，随后你可以让 Gemini 帮助你处理这些待办项。

• 或者干脆用于环境管理任务：如需安装某个包，可以直接运行 !pip install some-package 等命令，而无需离开 CLI。

无缝衔接： 一个很酷的地方在于，对话可以直接引用命令的输出。比如，你可以先运行 !curl http://example.com 获取一些数据，查看输出结果后，立即对 Gemini 说：“把上面的输出格式化成 JSON。”由于输出已经打印在聊天窗口中，AI 能够在上下文中直接处理它（前提是输出不太大）。

将终端作为默认 Shell： 如果你发现自己总是要在命令前加上 !，其实可以将 Shell 模式设置为默认持续开启。一种方法是使用特定工具模式启动 Gemini CLI（即设定默认工具）。更简单的方式是：如果你计划频繁执行手动命令，偶尔才与 AI 对话，那么可以在会话开始时直接进入 Shell 模式（输入 ! 后不加任何内容）。之后，当你想提问时，随时可以退出 Shell 模式。这样一来，Gemini CLI 几乎就变成了一个自带 AI 的常规终端。

与 AI 规划的结合： 有时 Gemini CLI 本身会建议你运行某个 Shell 命令。如果你同意执行，其效果就等同于手动输入 !命令。了解这一点后，你就知道随时可以介入。如果 Gemini 卡住了，或者你想尝试不同的做法，就不必等待它提出建议——你可以直接动手操作，然后再继续对话。

总之，! 的直通功能意味着 你无需为了执行 Shell 任务而离开 Gemini CLI。它模糊了与 AI 聊天和在系统上执行命令之间的界限。对于高级用户来说，这无疑极大地提升了效率——你的 AI 和终端合二为一，成为一个连续的工作环境。

小贴士 17：将每个命令行工具都视作潜在的 Gemini 工具

快速用例： 请意识到，Gemini CLI 可以将你系统上安装的 任何 命令行工具作为其解决问题的一部分来调用。AI 拥有对 shell 的访问权限，因此无论你是否安装了 cURL、ImageMagick、git、Docker 或其他工具，Gemini 都能在适当的时候调用它们。换句话说，你的整个 $PATH 就是 AI 的工具箱。这极大地扩展了它的能力——远远超出了其内置工具的范围。

例如，假设你问：“把这个文件夹里的所有 PNG 图片转换成 WebP 格式。” 如果你已经安装了 ImageMagick 的 convert 工具，Gemini CLI 很可能会规划出这样的方案：使用一个 shell 循环，对每个文件执行 convert 命令。事实上，早期的一篇博客示例就展示了这一点：用户请求批量转换图片，Gemini 就直接执行了一条包含 convert 工具的 shell 一行命令。

另一个场景：“把我的应用部署到 Docker 上。” 如果系统中存在 Docker CLI，AI 就可以根据需要调用 docker build 和 docker run 等步骤。再比如，“用 FFmpeg 从 video.mp4 中提取音频”——它同样可以构建出相应的 ffmpeg 命令。

这条小贴士的核心在于一种思维方式：Gemini 并不局限于其内置的功能（尽管这些功能本身已经非常丰富）。它能够自行判断如何利用你系统中已有的其他程序来达成目标。它熟悉常见的语法，并且在需要时还能读取帮助文档（比如调用某个工具的 --help 参数）。唯一的限制是安全性：默认情况下，对于它生成的任何 run_shell_command 命令，Gemini 都会先请求确认。但随着你逐渐熟悉并信任它，也可以允许某些无害的命令自动执行（参见 YOLO 或 allowed-tools 配置）。

请注意环境的影响： “能力越大，责任越大。” 既然任何 shell 工具都可以被调用，你就应该确保自己的 $PATH 中没有那些你不希望 AI 无意间运行的内容。这就引出了小贴士 19（自定义 PATH）：有些用户会为 Gemini 创建一个受限的 $PATH，这样它就无法直接调用一些可能破坏系统的命令，或者避免递归调用 gemini 而导致循环。也就是说，默认情况下，只要 $PATH 中有 gcc、terraform 或其他工具，Gemini 就有可能调用它们。当然，它并不会随意这么做——只有当任务确实需要时才会这样做——但这确实是存在的可能性。

思维链示例： 假设你让 Gemini CLI：“搭建一个能提供当前目录内容的基本 HTTP 服务器。” AI 可能会想到：“我可以使用 Python 自带的服务器来实现这一点。” 接着它就会发出 !python3 -m http.server 8000 这样的指令。就这样，它利用系统自带的 Python 工具启动了一个服务器。这是一个很安全的例子。再比如：“查看这个 Linux 系统的内存使用情况。” AI 可能会使用 free -h 命令，或者直接读取 /proc/meminfo 文件。实际上，它就是在像一名系统管理员那样，利用现有的命令完成任务。

所有工具都是 AI 的延伸： 这听起来有些未来感，但你可以把任何命令行程序都看作是 AI 可以调用的“函数”，从而扩展自身的功能。如果需要解数学题，它可以调用 bc（计算器）；如果要处理图片，它可以调用图像处理工具；如果要查询数据库，只要安装了对应的 CLI 客户端并且提供了凭据，它就能直接使用。可能性是极其广泛的。在其他 AI 代理框架中，这种机制被称为“工具使用”，而 Gemini CLI 则设计得非常信任其代理，允许它自主决定使用哪种工具。

可能出现的问题： 当然，也存在另一种情况：如果 AI 对某个工具的理解出现偏差，或者产生了错误的认知，它可能会尝试调用不存在的命令，或者使用错误的参数，从而导致报错。不过这通常不是什么大问题——你会看到错误信息，并可以及时纠正或进一步澄清。事实上，Gemini CLI 的系统提示语本身就引导它先进行“试运行”（即仅提出命令而不立即执行），而不是盲目地直接执行。因此，你往往有机会发现并修正这些问题。随着时间的推移，开发团队也在不断改进工具选择的逻辑，以减少这类误判。

总结来说，你应该把 Gemini CLI 视为一把非常大的瑞士军刀——它不仅拥有内置的各种“刀刃”，还囊括了你操作系统中的所有工具。对于那些标准的操作，你无需专门指导它如何使用；通常它自己就能知道，或者通过查阅相关文档找到答案。这种方式显著提升了你能完成的任务的复杂度和多样性。它就像一位精通各种常用程序的初级开发人员或 DevOps 工程师，随时准备为你效劳。

作为高级用户，你甚至可以专门安装一些额外的 CLI 工具，以赋予 Gemini 更多的能力。例如，如果你安装了云服务的 CLI（如 AWS CLI、GCloud CLI 等），理论上，在收到相应指令后，Gemini 就可以利用这些工具来管理云端资源。不过，请务必确保你清楚并信任它所执行的命令，尤其是涉及强大功能的工具（比如你肯定不希望它无意间创建大量的云实例）。只要合理使用，这种“一切皆可为 Gemini 工具”的理念，就能让你的环境与 Gemini 更加紧密地融合，从而使它的能力呈指数级增长。

小贴士 18：利用多模态 AI —— 让 Gemini 看得见图片及其他内容

快速用例： Gemini CLI 不仅限于处理文本，它具备多模态能力。这意味着只要提供图片、图表甚至 PDF 文件，它就能进行分析。你可以充分利用这一点。例如，你可以说：“这是一张错误对话框的截图，@./error.png——帮我排查一下问题。”AI 会“看到”这张图片，并据此给出回应。

Google 的 Gemini 模型（以及其前身 Codey 版本的 PaLM2）最突出的特点之一就是对图像的理解能力。在 Gemini CLI 中，如果你用 @ 引用一张图片，模型就会接收到该图像的数据。它可以输出描述、分类结果，或者基于图像内容进行推理。我们之前已经讨论过根据内容重命名图片（小贴士 14）和描述截图（小贴士 7）。但让我们再来看看其他更具创意的应用场景：

• UI/UX 反馈： 如果你是开发者，正在与设计师合作，可以直接上传 UI 图片，请 Gemini 提供建议或生成代码。“看看这个 UI 原型图 @mockup.png，为它生成一个 React 组件结构。”它能够识别图片中的各个元素（如页眉、按钮等），并给出相应的代码框架。

• 整理图片： 除了重命名之外，你可能有一堆杂乱无章的图片，想要按内容归类。“把 ./photos/ 文件夹里的图片按主题（如日落、山脉、人物）分到不同的子文件夹中。”AI 可以逐一查看每张照片，并将其归入相应类别。这类似于一些相册应用利用 AI 实现的功能——现在你也可以通过 Gemini 和自己的脚本轻松完成。

• OCR 与数据提取： 如果你有一张包含错误信息的截图，或者一张文档的照片，Gemini 往往可以直接从中读取文字。比如：“从 invoice.png 中提取文本，并将其整理成结构化格式。”正如 Google Cloud 博客中的示例所示，Gemini CLI 能够处理一组发票图片，并输出包含发票信息的表格。链接。本质上，它结合了 OCR 技术和语义理解，从发票图片中提取出发票编号、日期和金额等关键信息。这是一种高级用法，但在背后拥有多模态模型的支持下，完全可行。

• 解读图表或图形： 如果你有一张图表的截图，可以问：“请解释一下这张图表的关键洞察 @chart.png。”它可能会解读坐标轴的意义和趋势变化。虽然准确度可能有所差异，但这仍然是一项非常实用的功能。

要让这些操作更高效：当你使用 @image.png 引用图片时，确保图片不要太大（尽管模型可以处理相当大的图像）。CLI 会将图片编码后发送给模型，而模型的响应可能包括描述或其他进一步的操作。你还可以在同一条指令中混合使用文本和图片引用。

非图像模态： CLI 和模型理论上也能处理 PDF 和音频文件，只需借助相关工具进行转换即可。例如，如果你输入 @report.pdf，Gemini CLI 可能会在后台调用 PDF 转文本工具来提取内容并进行总结。同样，如果你输入 @audio.mp3 并请求生成文字稿，它可能会使用语音转文本工具（如语音识别功能）。一份 Cheat Sheet 表明，引用 PDF、音频和视频文件是被支持的链接，这很可能依赖于内部工具或 API 的调用。因此，“把这段采访录音转录成文字：@interview.wav”这一需求实际上是可以实现的（如果目前还不能，未来也很有可能，因为 Google 已经提供了相关的语音转文本 API）。

丰富输出： 多模态特性还意味着，如果集成适当，AI 完全可以在响应中返回图片（尽管在 CLI 中通常不会直接显示图片，而是保存为文件或输出 ASCII 艺术等）。MCP 功能说明指出，工具确实可以返回图片链接。例如，一个 AI 绘图工具可以生成一张图片，而 Gemini CLI 则可以呈现出来（可能是打开图片，也可能是提供下载链接）。

重要提示： 由于 CLI 本身是基于文本的界面，你在终端中并不会直接“看到”图片（除非它支持 ASCII 预览）。你只会得到对图片的分析结果。因此，这更多是关于读取和理解图片，而非展示图片。如果你使用的是 VS Code 集成版，聊天窗口中则可能会显示图片。

总之，在使用 Gemini CLI 时，别忘了其中的“视觉”部分——在许多情况下，它对视觉信息的处理能力丝毫不逊于对文本信息的处理能力。这为你打开了诸如可视化调试、设计辅助、从截图中提取数据等工作流，所有这些都可以通过同一个工具完成。这是 Gemini CLI 相较于其他 CLI 工具的一大优势。随着模型的不断进步，这种多模态支持将会越来越强大，因此掌握并善用这一技能无疑具有长远的价值。

小贴士 19：自定义 $PATH（以及工具可用性）以提升稳定性

快速使用场景： 如果你发现 Gemini CLI 经常混淆或调用了错误的程序，不妨尝试为其设置一个定制化的 $PATH。通过限制或排序可用的可执行文件，可以防止 AI 调用你本意之外的同名脚本。本质上，这相当于将它的工具访问权限隔离在一组已知可靠的工具范围内。

对于大多数用户来说，这并不是问题，但对于拥有大量自定义脚本或多种工具版本的专业用户而言，这种做法可能会很有帮助。开发者提到的一个原因是避免出现无限循环或奇怪的行为[1]。例如，如果 gemini 命令本身就在 $PATH 中，失控的 AI 可能会从 Gemini 内部递归地调用 gemini（虽然这种情况很罕见，但理论上是可能的）。或者你可能有一个名为 test 的命令与某些内容冲突，AI 就有可能调用到错误的那个。

如何为 Gemini 设置 $PATH： 最简单的方式是在启动时直接指定：

PATH=/usr/bin:/usr/local/bin gemini

这样会以仅包含这两个目录的受限 $PATH 来运行 Gemini CLI。你可以排除那些存放实验性或危险脚本的目录。另外，也可以创建一个小型的 Shell 脚本包装器，先清理或调整 $PATH，然后再执行 gemini。

另一种方法是通过环境变量或配置显式禁用某些工具。比如，如果你绝对不希望 AI 使用 rm 或其他破坏性工具，理论上可以在安全的 $PATH 中创建一个什么都不做的空占位符 rm 别名（不过这可能会影响正常操作，所以未必可行）。更好的办法是在设置中使用 排除列表。你可以在扩展插件或 settings.json 文件中排除特定工具名称[2]。例如：

"excludeTools": ["run_shell_command"]

这个极端的例子会阻止所有 shell 命令的执行，使 Gemini 变成只读模式。更精细的做法是跳过某些操作的确认提示；类似地，你还可以这样配置：

"tools": {
  "exclude": ["apt-get", "shutdown"]
}

（此语法仅为示例，请参考官方文档获取准确用法。）

其核心思想在于，通过控制运行环境，可以降低 AI 在不该使用某个工具时误操作的风险。这就像是给家里的插座装上安全盖一样。

防止无限循环： 有用户遇到过这样的情况：Gemini 不断读取自己的输出或重复读取文件[3]。自定义 $PATH 并不能直接解决逻辑上的循环问题，但原因之一可能是 AI 调用了一个会触发自身行为的命令。确保它不会意外生成另一个 AI 实例（比如调用 bard 或 gemini 命令，如果它真的这么想的话），这一点非常重要。将这些命令从 $PATH 中移除（或在该会话中将其重命名）就能有所帮助。

通过沙箱实现隔离： 除了调整 $PATH 之外，另一种选择是使用 --sandbox 模式（该模式利用 Docker 或 Podman 在隔离的环境中运行工具[4]）。在这种情况下，AI 的所有操作都被限制在一个由沙箱镜像提供的工具集内。你可以提供一个预先配置好所需工具的 Docker 镜像。这种方法虽然较为“重型”，但非常安全。

针对特定任务的自定义 PATH： 你可能需要为不同的项目设置不同的 $PATH 配置。例如，在某个项目中，你希望它使用特定版本的 Node.js 或本地工具链。通过在启动 gemini 时指定指向这些版本的 $PATH，就可以确保 AI 使用正确的工具。本质上，你可以把 Gemini CLI 当作普通用户来对待——它会使用你赋予它的任何环境。因此，如果你需要它选择 gcc-10 而不是 gcc-12，只需相应地调整 $PATH 或 CC 环境变量即可。

总结： 设置安全护栏。 作为高级用户，你有能力对 AI 的运行条件进行精细化调整。如果你发现某种不良行为模式与工具使用有关，那么调整 $PATH 就是一个快速有效的解决方案。对于日常使用，你可能并不需要这样做，但如果将 Gemini CLI 集成到自动化流程或 CI/CD 管道中，建议为其提供一个受控的环境。这样一来，你就能清楚地知道它能够做什么、不能做什么，从而提高系统的可靠性。

---

小贴士 20：通过令牌缓存和统计信息跟踪并减少令牌消耗

如果你经常进行长时间的对话，或者反复上传相同的大型文件，可以通过启用令牌缓存并监控使用情况来降低成本和延迟。只要使用 API 密钥或 Vertex AI 认证，Gemini CLI 就会自动复用之前发送过的系统指令和上下文，从而使后续请求更加经济高效。你可以在 CLI 中实时查看节省下来的资源。

使用方法

请使用支持缓存功能的身份验证模式。令牌缓存功能在使用 Gemini API 密钥或 Vertex AI 进行身份验证时可用，而目前 OAuth 登录则不支持此功能[5]。你可以查阅相关文档了解详细信息。

检查你的使用情况和缓存命中率。在会话期间运行 stats 命令，它会显示总令牌数，并在缓存生效时显示 cached 字段：

/stats

该命令的说明及其缓存报告行为已在命令参考和常见问题解答中记录[6]。你还可以在脚本中捕获指标数据。在无头模式下运行时，输出 JSON 格式的数据，并解析其中的 stats 块，该块包含了每个模型的 tokens.cached 数据：

gemini -p "Summarize README" --output-format json

无头模式指南中也详细描述了包含缓存令牌计数的 JSON 架构[7]。此外，你还可以将会话摘要保存到文件中，以便用于 CI 流程或预算跟踪：

gemini -p "Analyze logs" --session-summary usage.json

此标志已在变更日志中列出[8]。使用 API 密钥或 Vertex 认证时，CLI 会自动复用先前发送的上下文，从而减少后续请求中的令牌用量。保持 GEMINI.md 和大型文件引用在多次交互中不变，可以提高缓存命中率，你将在统计信息中看到相应的缓存令牌数量。

小贴士 21：使用 /copy 快速复制到剪贴板

快速应用场景： 立即将 Gemini CLI 的最新回答或代码片段复制到系统剪贴板，且不带任何多余的格式或行号[注]（https://google-gemini.github.io/gemini-cli/docs/cli/commands.html#:~:text=,for%20easy%20sharing%20or%20reuse）。这对于将 AI 生成的代码快速粘贴到编辑器中，或将结果分享给同事来说非常方便。

当 Gemini CLI 提供答案时（尤其是多行代码块），你通常希望将其复用到其他地方。而 /copy 斜杠命令就能轻松实现这一点——它会将 CLI 最后一次输出的内容直接复制到你的剪贴板。与手动选择不同，后者可能会连同行号或提示文本一起选中，而 /copy 只会抓取原始响应内容。例如，如果 Gemini 刚刚生成了一段 50 行的 Python 脚本，只需输入 /copy，整段脚本就会被放入剪贴板，随时可以粘贴——无需再滚动并手动选择文本。在底层实现上，Gemini CLI 会根据你的操作系统调用相应的剪贴板工具（如 macOS 上的 pbcopy、Windows 上的 clip）。执行该命令后，你通常会看到一条确认消息，随后就可以将复制的内容粘贴到任何需要的地方。

工作原理： /copy 命令要求你的系统已安装并可用剪贴板工具[注]（https://google-gemini.github.io/gemini-cli/docs/cli/commands.html#:~:text=,clip）。在 macOS 和 Windows 上，所需的工具（分别为 pbcopy 和 clip）通常已经预装好。而在 Linux 上，你可能需要安装 xclip 或 xsel 才能让 /copy[注]（https://google-gemini.github.io/gemini-cli/docs/cli/commands.html#:~:text=,clip）正常工作。确保这些工具已安装后，你可以在 Gemini CLI 输出答案之后随时使用 /copy。它会捕获整个最后一次响应（即使内容很长），并自动去除 CLI 在屏幕上显示的内部编号和格式化信息。这样一来，在转移内容时就无需处理那些不必要的干扰项。虽然这只是一个小功能，但在迭代代码或整理由 AI 生成的报告时，却能节省大量时间。

进阶提示： 如果发现 /copy 命令无法正常工作，请务必检查你的剪贴板工具是否已安装且可访问。例如，Ubuntu 用户应运行 sudo apt install xclip 来启用剪贴板[复制功能]（https://google-gemini.github.io/gemini-cli/docs/cli/commands.html#:~:text=,clip）。一旦设置完毕，借助 /copy，你便能毫无障碍地分享 Gemini 的输出——复制、粘贴，即可完成。

小贴士 22：掌握 Ctrl+C 进行 Shell 模式切换与退出

快速应用场景： 仅需轻轻一按键盘，即可干净利落地中断 Gemini CLI 的当前操作或退出 Shell 模式；而快速双击则可彻底退出 CLI——这都要归功于多功能的 Ctrl+C [快捷键]（https://www.howtouselinux.com/post/the-complete-google-gemini-cli-cheat-sheet-and-guide#:~:text=Shortcut%20Description%20,Press%20twice%20to%20confirm）。当你需要停止或退出时，它能让你立即掌控局面。

Gemini CLI 的运行方式类似于 REPL，因此掌握如何中断操作至关重要。单次按下 Ctrl+C 会取消当前正在进行的操作，或清除你正在输入的内容，相当于一个“终止”[命令]（https://www.howtouselinux.com/post/the-complete-google-gemini-cli-cheat-sheet-and-guide#:~:text=Shortcut%20Description%20,Press%20twice%20to%20confirm）。例如，如果 AI 正在生成一段较长的回答，而你已经看够了，只需按下 Ctrl+C，生成过程便会立即停止。如果你已经开始输入提示但又想放弃，Ctrl+C 会清空输入行，让你能够重新开始[注]（https://www.howtouselinux.com/post/the-complete-google-gemini-cli-cheat-sheet-and-guide#:~:text=Shortcut%20Description%20,Press%20twice%20to%20confirm）。此外，如果你正处于 Shell 模式（通过输入 ! 来运行 Shell 命令激活），单次按下 Ctrl+C 就会退出 Shell 模式，返回到正常的 Gemini 提示符（它会向正在[运行]的 Shell 进程发送中断信号[注]（https://milvus.io/ai-quick-reference/how-do-i-use-gemini-cli-for-shell-command-generation#:~:text=The%20shell%20integration%20also%20includes,where%20you%20can%20generate%20commands）。如果某个 Shell 命令卡住了，或者你只是想回到 AI 模式，这个功能就显得格外实用。

连续两次按下 Ctrl+C 则是退出 Gemini CLI[完全]的快捷方式（https://www.howtouselinux.com/post/the-complete-google-gemini-cli-cheat-sheet-and-guide#:~:text=Shortcut%20Description%20,Press%20twice%20to%20confirm）。你可以把它理解为：“按一次 Ctrl+C 取消当前操作，再按一次 Ctrl+C 即可退出。”第二次按键会指示 CLI 终止会话（你会看到告别消息或程序直接关闭）。相比输入 /quit 或直接关闭终端窗口，这种方式更为快捷，允许你仅通过键盘就优雅地关闭 CLI。需要注意的是，如果仍有未清除的输入或正在进行的操作，单次 Ctrl+C 并不会退出——只有在提示符处于空闲状态时，第二次按键才能真正[退出]（https://www.howtouselinux.com/post/the-complete-google-gemini-cli-cheat-sheet-and-guide#:~:text=Shortcut%20Description%20,Press%20twice%20to%20confirm）。这种设计可以防止你在只想停止当前输出时误操作导致会话意外关闭。

进阶提示： 在 Shell 模式下，你也可以按下 Esc 键来退出 Shell 模式，返回到 Gemini 的聊天模式，而无需终止整个[CLI]（https://milvus.io/ai-quick-reference/how-do-i-use-gemini-cli-for-shell-command-generation#:~:text=The%20shell%20integration%20also%20includes,where%20you%20can%20generate%20commands）。当然，如果你更倾向于正式退出，始终可以使用 /quit 命令来干净地结束会话。最后，Unix 用户还可以在空提示符下使用 Ctrl+D（EOF）来退出——Gemini CLI 会在必要时提示你进行确认[注]（https://www.howtouselinux.com/post/the-complete-google-gemini-cli-cheat-sheet-and-guide#:~:text=Shortcut%20Description%20,Press%20twice%20to%20confirm）。不过，在大多数情况下，熟练掌握 Ctrl+C 的单次与双次操作，才是保持控制的最快方法。

小贴士 23：使用 settings.json 自定义 Gemini CLI

快速用例： 通过编辑 settings.json 配置文件，根据个人偏好或项目规范调整 CLI 的行为和外观，而不是一直使用通用的默认设置。这样可以在所有会话中强制应用主题、工具使用规则或编辑器模式等设置。

Gemini CLI 具有高度可配置性。你可以在主目录（~/.gemini/）或项目文件夹（仓库内的 .gemini/）中创建一个 settings.json 文件，以覆盖默认的设置。几乎 CLI 的每个方面都可以在这里进行调整——从视觉主题到工具权限。CLI 会合并来自多个层级的设置：系统范围的默认值、用户设置以及项目特定的设置（项目设置会覆盖用户设置）。例如，你可能全局偏好深色主题，但某个特定项目可能需要更严格的工具沙箱隔离；这时可以通过在不同层级使用不同的 settings.json 文件来实现。

在 settings.json 中，选项以 JSON 键值对的形式指定。以下是一个示例片段，展示了一些有用的自定义设置：

{
"theme": "GitHub",
"autoAccept": false,
"vimMode": true,
"sandbox": "docker",
"includeDirectories": ["../shared-library", "~/common-utils"],
"usageStatisticsEnabled": true
}

在这个例子中，我们将主题设置为“GitHub”（一种流行的配色方案），禁用 autoAccept（使 CLI 在运行可能产生变更的工具前始终询问），启用 Vim 键绑定用于输入编辑器，并强制使用 Docker 进行工具沙箱隔离。我们还向工作区上下文中添加了一些目录（includeDirectories），以便 Gemini 默认就能看到共享路径中的代码。最后，我们将 usageStatisticsEnabled 保持为 true，以收集基本的使用统计信息（这些数据会用于遥测，前提是已启用）。还有许多其他可用设置——比如定义自定义颜色主题、调整令牌限制，或者对特定工具进行白名单/黑名单管理——所有这些都在配置指南中详细说明。通过定制这些设置，你可以确保 Gemini CLI 能够以最适合你工作流的方式运行（例如，有些开发者为了提高效率总是开启 vimMode，而另一些人则更喜欢默认编辑器）。

编辑设置的一个便捷方式是使用内置的设置 UI。在 Gemini CLI 中运行 /settings 命令，它将打开一个交互式的配置编辑器。这个界面允许你浏览和搜索带有描述的设置，并通过验证输入来避免 JSON 语法错误。你可以通过友好的菜单调整颜色、切换诸如 yolo（自动批准）之类的功能、修改检查点机制（文件保存/恢复行为）等。更改会保存到你的 settings.json 中，其中一些会立即生效（另一些则可能需要重启 CLI）。

进阶提示： 为不同的需求维护单独的项目特定 settings.json 文件。例如，在团队项目中，你可以设置 "sandbox": "docker" 和 "excludeTools": ["run_shell_command"] 来锁定危险操作，而在个人项目中则可能允许直接执行 shell 命令。Gemini CLI 会自动在你的项目目录树中找到最近的 .gemini/settings.json 文件，并将其与你的全局 ~/.gemini/settings.json 合并。此外，别忘了你还可以快速调整视觉偏好：尝试使用 /theme 命令交互式地切换主题，无需编辑文件，这非常适合找到一个舒适的外观。一旦找到满意的主题，就可以将其写入 settings.json 使其永久生效。

小贴士 24：利用 IDE 集成（VS Code）获取上下文与差异对比

快速用例： 通过将 Gemini CLI 与 VS Code 深度集成，大幅提升工作效率——CLI 会自动识别您正在编辑的文件，甚至会在 VS Code 的差异对比编辑器中为您打开 AI 提出的代码更改建议（https://developers.googleblog.com/en/gemini-cli-vs-code-native-diffing-context-aware-workflows/?source=post_page-----26afd3422028---------------------------------------#:~:text=,working%20on%20at%20the%20moment）。这样一来，AI 助手与您的开发工作区之间便形成了无缝衔接的工作流。

Gemini CLI 的强大功能之一就是它与 Visual Studio Code 的 IDE 集成。只需在 VS Code 中安装官方的 Gemini CLI Companion 扩展并完成连接，Gemini CLI 就能“感知”您的编辑器上下文（https://developers.googleblog.com/en/gemini-cli-vs-code-native-diffing-context-aware-workflows/?source=post_page-----26afd3422028---------------------------------------#:~:text=,working%20on%20at%20the%20moment）。具体来说，当连接成功后，Gemini CLI 能够了解您当前打开的文件、光标位置以及选中的文本内容。这些信息会被纳入 AI 的上下文中。因此，如果您询问“请解释这个函数”，Gemini CLI 可以直接基于您高亮显示的部分给出相关解答，而无需您手动复制粘贴代码到提示框中。该集成最多会共享您最近打开的 10 个文件，同时传递选区和光标信息，从而让模型对您的工作空间有更全面的理解（https://gemini-cli.xyz/docs/en/ide-integration#:~:text=,reject%20the%20suggested%20changes%20seamlessly）。

另一个巨大优势是代码更改的 原生差异对比 功能。当 Gemini CLI 建议对您的代码进行修改时（例如，“重构这个函数”并生成补丁），它可以自动在 VS Code 的差异查看器中打开这些更改（https://developers.googleblog.com/en/gemini-cli-vs-code-native-diffing-context-aware-workflows/?source=post_page-----26afd3422028---------------------------------------#:~:text=%2A%20Native%20in,the%20code%20right%20within%20this）。您将在 VS Code 中看到并排显示的差异对比，清晰地展示出建议的改动。随后，您可以借助 VS Code 熟悉的界面来审阅这些更改，进行必要的手动调整，甚至只需点击一下即可接受整个补丁。CLI 和编辑器始终保持同步——如果您在 VS Code 中接受了差异对比，Gemini CLI 也会相应更新会话状态，继续基于已应用的更改开展后续操作。这种紧密的闭环意味着您不再需要将代码从终端复制到编辑器中；AI 的建议可以直接融入您的开发环境。

如何设置： 如果您在 VS Code 的集成终端中启动 Gemini CLI，它通常会自动检测到 VS Code，并提示您安装或连接扩展（https://medium.com/google-cloud/gemini-cli-tutorial-series-part-10-gemini-cli-vs-code-integration-26afd3422028#:~:text=Press%20enter%20or%20click%20to,view%20image%20in%20full%20size）。您同意后，CLI 会自动执行 /ide install 命令完成安装。如果未出现提示（或者您稍后再启用此功能），只需打开 Gemini CLI 并运行命令 /ide install，系统便会为您下载并安装 “Gemini CLI Companion” 扩展（https://developers.googleblog.com/en/gemini-cli-vs-code-native-diffing-context-aware-workflows/?source=post_page-----26afd3422028---------------------------------------#:~:text=2%3A%20One,install%20the%20necessary%20companion%20extension）。接下来，运行 /ide enable 建立连接（https://developers.googleblog.com/en/gemini-cli-vs-code-native-diffing-context-aware-workflows/?source=post_page-----26afd3422028---------------------------------------#:~:text=3%3A%20Toggle%20integration%3A%20After%20the,can%20easily%20manage%20the%20integration），CLI 会提示您已成功关联 VS Code。您也可以随时通过 /ide status 命令检查当前状态，确认是否已连接，并查看正在跟踪的编辑器及文件列表（https://gemini-cli.xyz/docs/en/ide-integration#:~:text=Checking%20the%20Status）。此后，Gemini CLI 将自动从 VS Code 获取上下文信息（如打开的文件和选区），并在需要时自动在 VS Code 中打开差异对比视图。这相当于将 Gemini CLI 变成了一个驻留在终端中的 AI 配对程序员，能够完全感知您的 IDE 状态并实时提供帮助。

目前，VS Code 是这一集成的主要支持编辑器（https://gemini-cli.xyz/docs/en/ide-integration#:~:text=better%20and%20enables%20powerful%20features,editor%20diffing）。虽然其他支持 VS Code 扩展的编辑器，比如 VSCodium 或某些 JetBrains IDE 通过插件也可能兼容，但官方目前仅支持 VS Code。不过，该设计是开放的——存在一套 IDE Companion 规范，可用于开发与其他编辑器的类似集成（https://gemini-cli.xyz/docs/en/ide-integration#:~:text=better%20and%20enables%20powerful%20features,editor%20diffing）。因此，未来我们或许会看到社区开发的插件为 IntelliJ、Vim 等 IDE 提供一流的原生支持。

进阶小技巧： 连接完成后，您可以在 VS Code 的命令面板中直接控制 Gemini CLI，无需离开编辑器（https://gemini-cli.xyz/docs/en/ide-integration#:~:text=,Ctrl%2BShift%2BP）。例如，按下 Ctrl+Shift+P（Mac 上为 Cmd+Shift+P），然后尝试以下命令：“Gemini CLI: Run”（在终端中启动一个新的 CLI 会话）、“Gemini CLI: Accept Diff”（批准并应用当前的差异对比）或“Gemini CLI: Close Diff Editor”（拒绝更改，https://gemini-cli.xyz/docs/en/ide-integration#:~:text=,Ctrl%2BShift%2BP）。这些快捷键可以进一步简化您的工作流程。另外，请记住，您并不总是需要手动启动 CLI——一旦启用了集成，Gemini CLI 就会成为 VS Code 内部的一位 AI 合作开发者，时刻关注上下文，并在您编写代码时随时提供协助。

小贴士 25：使用 Gemini CLI GitHub Action 自动化仓库任务

快速用例： 让 Gemini 在 GitHub 上发挥作用——通过 Gemini CLI GitHub Action 自主对仓库中的新问题进行分类，并审查拉取请求，充当一位能够处理日常开发工作的 AI 团队成员任务。

Gemini CLI 并不仅限于交互式终端会话；它还可以通过 GitHub Actions 在 CI/CD 管道中运行。Google 已经提供了一个现成的 Gemini CLI GitHub Action（目前处于测试阶段），可集成到你的仓库 工作流 中。这相当于在 GitHub 项目中部署了一个 AI 代理，它会在后台运行，由仓库的 事件 触发。例如，当有人打开一个 新问题 时，Gemini Action 可以自动分析问题描述，添加相关标签，甚至为其设置优先级或建议是否存在重复项（这就是“智能问题分类”工作流）。而当有 拉取请求 被提交时，该 Action 会启动 AI 代码审查——它会在 PR 中留下评论，指出代码质量、潜在 bug 或风格上的 改进。这样一来，维护者无需人工查看，就能立即获得关于该 PR 的反馈。最酷的功能或许是 按需协作：团队成员可以在问题或 PR 的评论中提及 @gemini-cli，并给出指令，比如“@gemini-cli 请为这段代码编写单元测试”。Action 会捕捉到这一指令，Gemini CLI 就会尝试完成请求（例如，添加包含新测试的提交，实例）。这就像是在你的仓库里住着一位 AI 助手，随时准备响应需求去完成琐事。

设置 Gemini CLI GitHub Action 非常简单。首先，确保你本地安装了 Gemini CLI 0.1.18 或更高版本（这样可以保证与 Action 的兼容性）。然后，在 Gemini CLI 中运行特殊命令：/setup-github。此命令会在你的仓库中生成所需的工作流文件（如有需要，还会引导你完成身份验证）。具体来说，它会在 .github/workflows/ 目录下添加 YAML 格式的工作流文件（用于问题分类、PR 审查等）。你需要将 Gemini API 密钥添加到仓库的密钥配置中（命名为 GEMINI_API_KEY），以便 Action 能够使用 Gemini API。一旦完成这些步骤并提交工作流文件，GitHub Action 就会开始运行——从那时起，Gemini CLI 将根据这些工作流自主响应新的问题和 PR。

由于这个 Action 实际上是以自动化方式运行 Gemini CLI，因此你可以像自定义 CLI 一样对其进行个性化配置。默认设置提供了三个工作流（问题分类、PR 审查以及基于提及触发的助手），它们都是 完全开源且可编辑的链接。你可以调整 YAML 文件来改变 AI 的行为，甚至添加新的工作流。例如，你可以创建一个夜间工作流，让 Gemini CLI 扫描仓库中的过时依赖项，或者根据最近的代码变更更新 README 文件——可能性几乎是无限的。这里的关键优势在于，可以将繁琐或耗时的任务交给 AI 代理来完成，从而让人类开发者专注于更复杂的难题。而且由于它运行在 GitHub 的基础设施上，无需人工干预——真正做到了“一次设置，无需操心”的 AI 辅助工具。

进阶提示： 为了保持透明度，请密切关注 GitHub Actions 日志中的 Action 输出。Gemini CLI Action 的日志会显示它执行了哪些提示词，以及进行了哪些更改或提出了哪些建议。这不仅有助于建立信任，还能帮助你进一步优化其行为。此外，团队还在 Action 中内置了企业级的安全保障措施——例如，你可以要求 AI 在工作流中尝试运行的所有 Shell 命令都必须事先由 你 列入白名单。因此，即使是在重要的项目中，也完全可以放心使用。如果你利用 Gemini CLI 构建了很棒的自定义工作流，不妨将其贡献回社区——该项目非常欢迎大家在仓库中提出新想法！

小贴士 26：启用遥测以获取洞察与可观测性

快速用例： 通过开启 Gemini CLI 内置的 OpenTelemetry 仪器仪表功能，深入了解 Gemini CLI 的使用情况和性能表现——监控 AI 会话的指标、日志和跟踪信息，从而分析使用模式或排查 问题。对于喜欢度量和优化的开发者而言，Gemini CLI 提供了一项可观测性功能，能够揭示其内部运行状况。借助 OpenTelemetry (OTEL)，Gemini CLI 可以输出关于您的 会话 的结构化遥测数据。这些数据包括指标（例如使用的令牌数量、响应延迟）、操作日志，甚至工具调用的跟踪记录。启用遥测后，您可以回答诸如以下问题：我最常使用哪个自定义命令？本周 AI 在这个项目中编辑了多少次文件？当我让 CLI 运行测试时，平均响应时间是多少？ 这类数据对于理解使用模式和 性能 至关重要。团队可以利用这些数据来了解开发者如何与 AI 助手交互，以及可能存在的瓶颈所在。

默认情况下，遥测是 关闭 的（Gemini 非常注重隐私和性能）。您可以通过在 settings.json 中设置 "telemetry.enabled": true 或使用 --telemetry 标志启动 Gemini CLI 来选择启用。此外，您还可以选择遥测数据的 目标：它可以被记录在 本地，也可以发送到 Google Cloud 等后端系统。为了快速上手，您可以将 "telemetry.target": "local" 设置为本地目标——这样，Gemini 会将遥测数据写入本地文件（默认）或您通过 ["outfile"](https://google-gemini.github.io/gemini-cli/docs/cli/telemetry.html#:~:text=disable%20telemetry%20,file%20path) 指定的自定义路径。本地遥测包含可解析的 JSON 日志，您也可以将其导入其他工具中。若需更强大的监控功能，则可将目标设置为 "target": "gcp"（Google Cloud），甚至与其他兼容 OpenTelemetry 的系统（如 Jaeger 或 Datadog）集成。事实上，Gemini CLI 对 OTEL 的支持是供应商无关的——您可以将数据导出到几乎任何您偏好的可观测性堆栈中（Google Cloud Operations、Prometheus 等 等等）。Google 为 Cloud 用户提供了便捷途径：如果您指向 GCP，CLI 可直接将数据发送至您项目的 Cloud Logging 和 Cloud Monitoring，您可以在其中使用常规的仪表板和告警 工具。

那么，您可以获得哪些洞察呢？遥测会捕获工具执行、错误以及重要里程碑等事件，还会记录诸如提示处理时间和每个 提示 的令牌计数等指标。在使用分析方面，您可以汇总团队中每个斜杠命令的使用次数，或者代码生成被调用的频率。在性能监控方面，您可以追踪响应是否变慢，这可能表明已达到 API 速率限制或模型发生了变化。而在调试方面，您可以查看工具抛出的错误或异常（例如 run_shell_command 失败）及其上下文信息。所有这些数据都可以可视化——只要将其发送到像 Google Cloud Monitoring 这样的平台即可。例如，您可以创建一个“每日令牌使用量”或“工具 X 错误率”的仪表板。这实际上为您打开了一扇窥探 AI “大脑”及您使用情况的窗口，尤其在企业环境中，有助于确保一切平稳运行 顺畅。

启用遥测确实会带来一定的开销（额外的数据处理），因此您可能不会在个人使用时一直保持开启状态。不过，它非常适合用于会话调试或间歇性的健康检查。一种做法是在 CI 服务器或团队共享环境中启用遥测以收集统计信息，而在本地则仅在需要时才开启。请记住，您可以随时动态切换遥测的开关：如有必要，更新设置并使用 /memory refresh 重新加载，或通过 --telemetry 标志重启 Gemini CLI。此外，所有遥测数据均受您控制——它会尊重您为端点和凭据设置的环境变量，因此数据只会流向您指定的位置。这一功能将 Gemini CLI 从一个黑盒转变为一座观测台，照亮 AI 代理与您的世界之间的交互方式，从而帮助您不断改进这种交互。

专家提示： 如果您只想快速查看当前会话的统计信息（而无需完整的遥测功能），可以使用 /stats 命令。它会在 CLI 中直接输出令牌使用量和会话时长等指标。这是一种轻量级的方式，可让您立即获取相关数字。然而，对于长期或多会话的分析，遥测才是更合适的选择。如果您将遥测数据发送到云项目，请考虑设置仪表板或告警规则（例如，当错误率激增或令牌使用量达到阈值时发出告警），这样可以主动发现团队中 Gemini CLI 使用过程中可能出现的问题。

小贴士 27：关注路线图（后台代理等功能）

快速用例： 随时了解 Gemini CLI 即将推出的新功能——通过关注公开的 Gemini CLI 路线图，您可以在重大计划中的增强功能（例如用于长时间运行任务的 后台代理）正式发布之前就知晓相关信息，从而提前规划并提供反馈。

Gemini CLI 正在快速发展，新版本频繁发布，因此及时了解未来的规划是非常明智的。Google 在 GitHub 上维护着一个 公开的路线图，详细列出了近期的重点方向和目标功能。这实际上是一份动态更新的文档及相关的议题列表，您可以从中了解到开发团队正在推进的工作以及后续的开发计划。例如，路线图中令人期待的一项内容就是对 后台代理 的支持——即能够启动在后台持续运行、自动执行任务或以异步方式处理工作的代理程序。根据路线图的相关讨论，这些后台代理将使您无需占用交互式会话，即可将耗时较长的任务交由 Gemini CLI 处理。比如，您可以启动一个后台代理来监控项目中的特定事件，或定期执行某些任务，既可以在本地机器上运行，也可以部署到 Cloud Run 等服务上。这项功能旨在“直接从 CLI 中实现长时间运行的自主任务和主动协助”，从而进一步扩展 Gemini CLI 的实用性，而不仅仅局限于按需查询。

通过持续关注路线图，您还能了解到其他计划中的新特性，例如新的工具集成、对更多 Gemini 模型版本的支持、用户界面与体验的改进等。路线图通常按“领域”（如“可扩展性”“模型”“后台”等）进行组织，并常标注里程碑（例如预计完成的季度）。虽然这并不意味着某项功能一定会在指定时间落地，但它能很好地反映团队的优先级。由于该项目是开源的，您还可以深入查看每个路线图条目所关联的 GitHub 议题，以了解设计方案和进展状况。对于依赖 Gemini CLI 的开发者来说，这种透明度意味着您可以提前预见到变化——也许某个 API 即将新增一项您需要的功能，或者即将发生一项可能影响您的破坏性变更，从而做好准备。

关注路线图其实非常简单：只需将 GitHub 项目板或标记为“Roadmap”的议题收藏起来，定期查看即可。一些重大更新（如 Extensions 功能的引入或 IDE 集成）都是先在路线图中有所暗示，随后才正式公布，因此您能够抢先一步掌握信息。此外，Gemini CLI 团队也经常鼓励社区对这些未来功能提出反馈意见。如果您对后台代理等功能有自己的想法或使用场景，通常可以直接在相关议题或讨论帖中留言，从而影响其开发方向。

进阶提示： 由于 Gemini CLI 是开源项目（采用 Apache 2.0 许可证），您不仅可以关注路线图，还可以积极参与其中！维护者非常欢迎贡献，尤其是针对与路线图一致的事项。如果您特别关注某项功能，不妨考虑在该功能进入预览阶段时参与代码开发或测试工作。至少，当您需要的功能尚未列入路线图时，也可以提交功能请求。路线图页面本身还提供了关于如何提出改进建议的指导说明。积极参与项目不仅能帮助您及时了解最新动态，还能让您参与到自己所使用的工具的设计与优化过程中。毕竟，Gemini CLI 本身就是以社区参与为核心构建的，许多近期的功能（如部分扩展和工具）最初都源于社区的建议。

小贴士 28：通过“扩展”拓展 Gemini CLI

快速用例： 通过安装即插即用的 扩展，为 Gemini CLI 增加新功能——例如，与您喜爱的数据库或云服务集成——从而在无需您过多操劳的情况下扩展 AI 的工具集。这就好比为您的命令行界面安装应用程序，教会它新的技能。

扩展是 2025 年底推出的一项颠覆性功能：它们允许您以模块化的方式 自定义和扩展 Gemini CLI 的功能。简单来说，扩展就是一个包含配置（以及可选代码）的集合，用于将 Gemini CLI 与外部工具或服务连接起来。例如，Google 推出了针对 Google Cloud 的一系列扩展：有一个可以帮助将应用部署到 Cloud Run，一个用于管理 BigQuery，还有一个用于分析应用安全性，等等。此外，合作伙伴和社区开发者也构建了涵盖各种领域的扩展，包括 Dynatrace（监控）、Elastic（搜索分析）、Figma（设计资源）、Shopify、Snyk（安全扫描）、Stripe（支付）等，而且这个列表还在不断增长。通过安装合适的扩展，您可以立即赋予 Gemini CLI 使用特定领域工具的能力。其妙处在于，这些扩展自带预定义的 “操作手册”，指导 AI 如何有效使用这些新工具。这意味着一旦安装完毕，您就可以让 Gemini CLI 执行相关任务，它会自动调用正确的 API 或命令，仿佛这些知识早已内置一般。

使用扩展非常简单。CLI 提供了一个专门用于管理扩展的命令：gemini extensions install <URL>。通常，您只需提供扩展的 GitHub 仓库 URL 或本地路径，CLI 就会自动获取并安装该扩展。例如，要安装官方扩展，您可以运行：gemini extensions install https://github.com/google-gemini/gemini-cli-extension-cloud-run。几秒钟内，扩展就会被添加到您的环境中（存储在 ~/.gemini/extensions/ 或项目目录下的 .gemini/extensions/ 文件夹中）。您可以通过在 CLI 中运行 /extensions 来查看已安装的扩展，该命令会列出当前激活的扩展。从那时起，AI 就拥有了新的工具可供使用。如果是一个 Cloud Run 扩展，您可以说“将我的应用部署到 Cloud Run”，Gemini CLI 确实能够执行这一操作（通过扩展提供的工具调用底层的 gcloud 命令）。本质上，扩展是对 Gemini CLI 功能的一次原生扩展，而您只需选择自己需要的那些即可。

围绕扩展形成了一个 开放的生态系统。Google 设有官方扩展页面，列出了可用的扩展。由于该框架是开放的，任何人都可以创建并分享自己的扩展。如果您有一个特定的内部 API 或工作流，完全可以为其构建一个扩展，以便 Gemini CLI 能够协助处理。编写扩展其实并不复杂：您通常只需创建一个目录（比如 my-extension/），并在其中放置一个名为 gemini-extension.json 的文件，描述要添加哪些工具或上下文。您可以定义新的斜杠命令，或者指定 AI 可以调用的远程 API。无需修改 Gemini CLI 的核心代码——只需将您的扩展放入即可。CLI 本身的设计就支持在运行时加载这些扩展。许多扩展的核心就是添加自定义的 MCP 工具（模型上下文协议服务器或函数），供 AI 使用。例如，一个扩展可以通过对接外部翻译 API 来新增 /translate 命令；一旦安装，AI 就知道如何使用 /translate。其关键优势在于 模块化：您只需安装所需的扩展，保持 CLI 的轻量化，同时又具备集成几乎任何内容的能力。

除了 install 命令之外，您还可以通过类似的 CLI 命令来更新或移除扩展（如 gemini extensions update，或者直接删除对应的文件夹）。建议定期检查您正在使用的扩展是否有更新，因为它们可能会获得改进。未来，CLI 有可能推出类似“扩展市场”的界面，但目前探索 GitHub 仓库和官方目录仍然是发现新扩展的最佳方式。发布之初比较流行的扩展包括用于构建生成式 AI 应用的 GenAI Genkit 扩展，以及覆盖 CI/CD、数据库管理等功能的多种 Google Cloud 扩展。

进阶提示： 如果您正在构建自己的扩展，不妨先参考现有的示例。官方文档提供了 扩展指南，其中包含了扩展的架构和功能。创建私有扩展的一个简单方法是利用 GEMINI.md 中的 @include 功能注入脚本或上下文，但完整的扩展则能提供更多能力（比如打包工具）。此外，由于扩展可以包含上下文文件，您还可以借此预加载领域知识。设想这样一个扩展：它针对贵公司内部的 API 编写了摘要，并提供了一个调用该 API 的工具——这样一来，AI 就能理解如何处理与该 API 相关的请求。简而言之，扩展开启了一个全新的世界，让 Gemini CLI 能够与任何系统无缝对接。请持续关注扩展市场的新动态，并且不要犹豫，将您开发的实用扩展分享给社区——您或许就能帮助成千上万的开发者。

额外乐趣：柯基模式彩蛋 🐕

最后，这不是一条提高效率的技巧，而是一个有趣的彩蛋——在 Gemini CLI 中尝试输入命令 */corgi*。这会切换到 “柯基模式”，让一只可爱的柯基动画在你的 终端! 虽然它并不能让你写得更好，但确实能在漫长的编码过程中调剂一下心情。你会在 CLI 界面中看到一段用 ASCII 艺术绘制的柯基奔跑动画。如果想关闭它，只需再次运行 /corgi 即可。

这个纯粹为了好玩的功能是团队特意加入的（没错，甚至还为此展开了一个半开玩笑的 讨论——有人质疑是否值得花开发时间来做柯基模式）。这也说明开发者们在工具中藏了些许趣味。所以，当你需要短暂休息或找点乐子时，不妨试试 /corgi 吧。🐕🎉

（传闻可能还有其他彩蛋或模式——谁知道呢？也许会有类似 /partyparrot 的功能。不过，使用手册或帮助命令里已经列出了 /corgi，所以它并不是什么秘密，只是平时不太常被用到而已。现在你也是其中的一员啦！）

---

总结：

我们已经涵盖了 Gemini CLI 的一系列实用技巧和功能。从通过 GEMINI.md 设置持久化上下文，到编写自定义命令、使用 MCP 服务器等高级工具，再到利用多模态输入和自动化工作流，这款 AI 命令行助手能做的事情非常多。作为一名外部开发者，你可以将 Gemini CLI 融入日常开发流程中——它就像你终端里的得力助手，既能处理繁琐的任务、提供洞察，还能帮你排查环境问题。

Gemini CLI 目前仍在快速迭代中（作为开源项目，还得到了社区贡献的支持），因此新的功能和改进层出不穷。只要熟练掌握本指南中的进阶技巧，你就能充分发挥这款工具的潜力。关键并不只是简单地调用一个 AI 模型，而是要将 AI 深度融入到你的开发与软件管理流程中。

祝你使用 Gemini CLI 编码愉快，并尽情探索这个“终端里的 AI 助手”能带你走多远吧！

现在你手中就握着一把 AI 版的瑞士军刀——善加利用，它一定会让你成为更高效（或许也更快乐）的开发者！

Gemini CLI 快速上手指南

Gemini CLI 是一款由 Google 开源的终端 AI 助手，它将 Gemini 模型的强大能力直接带入命令行。作为一个“代理式”（Agentic）编程工具，它能够理解自然语言指令，自主规划多步骤任务（如编写代码、运行 Shell 命令、编辑文件），是开发者的超级结对编程伙伴。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：支持所有主流平台（Linux, macOS, Windows）。
• 运行时依赖：已安装 Node.js (推荐 LTS 版本) 和 npm。
  • 检查安装：node -v 和 npm -v
• 网络环境：由于需要连接 Google 服务，请确保网络通畅。
  • 提示：国内用户若遇到连接问题，可配置系统级代理或使用符合当地法规的网络加速方案。目前官方暂未提供专用的中国镜像源。
• 账号准备：
  • 免费方案：拥有 Google 账号（用于登录获取免费额度，约 60 次请求/分钟）。
  • 付费/高阶方案：拥有 Google AI Studio API Key（适用于企业级需求或更高配额）。

安装步骤

您可以通过 npm 全局安装，或使用 npx 免安装运行。

方式一：全局安装（推荐）

将工具安装到系统中，以便在任何目录下直接使用 gemini 命令。

npm install -g @google/gemini-cli

方式二：临时运行（无需安装）

适合快速体验或在受限环境中使用。

npx @google/gemini-cli

认证配置

首次运行时，您需要完成身份验证：

1. Google 账号登录（免费）： 运行 gemini 后，终端会提示您通过浏览器使用 Google 账号登录。此方式无需配置密钥，适合个人开发者日常使用。

2. API Key 配置（可选）： 如果您拥有 API Key，可以通过设置环境变量来使用：

   # Linux/macOS (添加到 ~/.bashrc 或 ~/.zshrc)
   export GEMINI_API_KEY="YOUR_KEY_HERE"
   
   # Windows PowerShell
   $env:GEMINI_API_KEY="YOUR_KEY_HERE"
   

基本使用

安装完成后，即可在终端启动交互式会话。

1. 启动交互式模式

在终端输入以下命令启动：

gemini

您将看到 gemini> 提示符。此时可以直接输入自然语言指令，例如让 AI 创建一个项目：

gemini> Create a React recipe management app using SQLite

Gemini CLI 会自动分析需求，创建文件、安装依赖并运行测试。在执行修改文件或运行命令等操作前，它会显示差异（Diff）或命令详情，并等待您确认（输入 Y 批准或 n 拒绝），确保操作安全。

2. 单次指令模式（非交互式）

如果您只需要执行单个任务并立即退出，可以使用 -p 参数：

gemini -p "Summarize the main points of the attached file. @./report.txt"

3. 管道输入

您也可以将其他命令的输出传递给 Gemini CLI：

echo "Count to 10" | gemini

4. 常用快捷操作

• 引用文件：在对话中使用 @ 符号引用具体文件或图片，例如 @./src/main.py 或 @./diagram.png，为 AI 提供明确的上下文。
• 执行 Shell 命令：使用 ! 前缀直接在终端执行系统命令，例如 !ls -la。
• 持久化上下文：在项目根目录创建 .gemini/GEMINI.md 文件，写入项目规范（如代码风格、架构说明），AI 会在每次对话中自动读取这些背景知识，无需重复提示。