01 快速入门：订阅与安装到 CLI 上手

1.1 概览：Gemini 是什么？

官网地址：https://deepmind.google/models/gemini

Google Gemini 是 Google 推出的 原生多模态大模型与 AI 能力平台。 我们不应把 Gemini 简单理解为“聊天版 AI”，它更像是 嵌入在搜索、办公、开发与操作系统中的通用智能引擎。与传统只处理文本的模型不同，Gemini 从设计之初就是多模态的，它可以 同时理解文本、图片、音频、视频和代码，并在这些模态之间进行推理与协作，这使得 Gemini 不只是“回答问题”，而是能够 分析复杂输入、整合上下文，并给出可执行的结果。

在实际使用中，可以把 Gemini 当成一个“系统级 AI 助手”，例如：

• 对搜索结果进行总结、对比和推理，而不只是返回链接
• 在 Docs / Sheets 中协助写作、整理数据和生成内容
• 理解图片、截图或图表并给出解释
• 辅助代码阅读、生成与调试
• 在移动设备上完成本地智能任务（如 Pixel 手机上的 AI 功能）

用户只需要用自然语言描述目标，Gemini 就可以结合上下文、多模态输入以及 Google 生态中的工具，给出可直接使用的智能结果，它更像是 Google 正在打造的 下一代通用智能中枢，而不只是一个独立的 AI 产品。

1.2 账号与环境准备（Gemini 3 Pro）

注意：学生优惠在美区延长至 1 月 31 日，之后就没有了。

博主成功订阅了免费一年使用Gemini 3 Pro的服务，这里大致讲解注册流程：

Step1：需要魔法，地区米国。gmail注册谷歌新账户，登录新注册的账号（在管理个人信息处），补充邮箱地址，验证自己的年龄（可以先改年龄为2008年-再改为18~25周岁触发验证-，这里由于验证不通过，屏蔽地址了，有需要的联系博主。

Step3：清除cookies，无痕模式下搜索进入Gemini for students ，地址为 https://gemini.google/us/students/?hl=en ，看看是否能够触发验证。

Step4：然后根据提示验证即可，这里可能需要绑定信用卡（具体操作方式大家都懂的😁）

Step5：如果出现如下界面，说明订阅成功了

同时在谷歌订阅信息里面也可以看到订阅成功以及过期日期：https://myaccount.google.com/payments-and-subscriptions

---

1.3 Gemini 安装指南

至此，相信读者们已经成功注册并订阅了 Gemini 3 Pro，那么问题来了：Gemini 到底如何“安装”和“使用”？ 根据使用场景不同，Gemini 的“安装方式”主要分为以下几类：

• Web 端直接使用（零安装）
• Gemini CLI（命令行工具，推荐）
• 通过 NPM / SDK 集成到项目中

下面我们逐一说明。

1.3.1 系统与环境要求

在安装 Gemini CLI 或使用 SDK 之前，请先确认系统与环境满足以下条件：

项目	要求
操作系统	macOS / Linux / Windows（含 WSL）
Node.js	>= 18.x（推荐 LTS）
网络环境	可访问 Google 服务
Google 账号	已开通 Gemini（3 / 3 Pro）

1.3.2 Mac / Linux / WSL 安装

Gemini 官方提供了 Gemini CLI，可以在终端中直接与 Gemini 对话、分析代码或处理任务。

Step 1：全局安装 Gemini CLI

npm install -g @google/gemini-cli

安装完成后，验证是否成功：

gemini --version

若能正常输出版本号，说明安装成功

---

Step 2：首次使用时，需要进行登录授权，直接输入 gemini 命令，这里选择第一种使用谷歌账号登录的方式，该命令会自动打开浏览器，按指引登录即可。

1.3.3 Windows 安装

Windows 用户有 两种推荐方案：

---

方案一：WSL（强烈推荐）：

如果你是开发者，WSL = 最佳选择。

1. 安装 WSL（Ubuntu）
2. 在 WSL 中安装 Node.js
3. 按照 前面npm安装步骤 执行即可

这种方式稳定、兼容性最好。

---

方案二：原生 Windows（PowerShell）：

也可以在 Windows PowerShell / Windows Terminal 中直接安装：

npm install -g @google/gemini-cli

注意事项：

• 确保 Node.js 已加入 PATH
• 建议使用 PowerShell 7+
• 网络环境需可访问 Google

登录授权步骤同样使用：

gemini

---

1.3.4 NPM 安装（项目集成）

如果你希望 在代码中直接调用 Gemini，可以通过 NPM SDK 集成。首先安装 SDK

npm install @google/generative-ai

Node.js 调用 Gemini示例如下：

import { GoogleGenerativeAI } from "@google/generative-ai";

const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY);
const model = genAI.getGenerativeModel({ model: "gemini-1.5-pro" });

const result = await model.generateContent("用一句话解释什么是多模态模型");
console.log(result.response.text());

API Key 获取地址：https://aistudio.google.com/app/apikey

---

1.3.5 版本更新

Gemini CLI 更新非常简单：

npm update -g @google/gemini-cli

或强制更新：

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

查看当前版本：

gemini --version

---

1.3.6 使用建议（踩坑经验）

• CLI 更适合开发者 / 运维 / 日常提效
• Web 端更适合内容创作、多模态体验
• API 适合产品化与自动化

学生订阅到期后，CLI 仍可使用，只是不能使用Gemini 3 ，终端输入model命令，可以看到最新版支持如下：

1.4 Gemini 快速入门（CLI 实战）

前面讲的可能都比较偏概念化，这里实际的来操作演示，效果可能更好。

1.4.1 初始化与授权登录

1.4.1.1 创建项目

初次使用，我们可以进入项目的根目录，这里为了方便演示，我新建了一个 html-project 的文件夹，然后执行 gemini 命令如下：

mkdir html-project
cd html-project
gemini

1.4.1.2 登录与授权流程

运行后，会提示登录方式，这里选择使用谷歌账号登录：

页面授权成功：

终端也提示授权成功：

1.4.2 用一句话完成一个真实需求

接下来，我们可以开发任务，例如：帮我创建一个静态的页面，打开后，是星空的动态效果。

可以看到，Gemini 在执行任务时，会先提示用户计划是否有问题：

我这里使用它认为合理的 plan 并确认，接着需要我们需要同意操作权限，这里根据自己的需求去选择：

打开生成的HTML，可以看到如下效果，效果还是挺不错的。

但是到这里，大家可能会有一个疑问，这些新增和改动的代码看上去太麻烦了，不可能一直使用终端，其实Claude Code支持多种使用形态，这里继续讲解。

1.4.3 查看用量

只需要使用stats命令即可查看用量：

1.5 Gemini 的多种使用形态

1.5.1 Web 端 / 移动端（零门槛使用）

1.5.1.1 Gemini Web（官方入口）

定位：聊天、多模态理解、内容创作

适合人群：普通用户 / 内容创作者

访问地址：https://gemini.google.com/

1.5.1.2 Gemini 手机 App（iOS / Android）

能力：文字 / 语音 / 图片输入，多模态实时交互

说明：App Store / Google Play 搜索「Gemini」

帮助中心： https://support.google.com/gemini/?hl=zh-Hans

1.5.1.3 Google Search AI 模式

定位：搜索即 AI，总结 + 推理 + 对话

入口： https://www.google.com/（部分地区搜索结果中显示 AI Mode）

---

1.5.2 命令行形态（Gemini CLI）

定位：终端里的 AI 助手

典型用途： 写代码 / 改代码、 总结项目 / 文档、自动化脚本

官方文档： https://developers.google.cn/gemini-code-assist/docs/gemini-cli

---

1.5.3 API / SDK（工程化与产品集成）

1.5.3.1 Gemini API

定位：将 Gemini 集成进你自己的产品

能力：文本 / 图片 / 视频 / 音频、长上下文、函数调用 / 工具调用

官方文档： https://ai.google.dev/gemini-api/docs

1.5.3.2 Google AI Studio（Playground）

• 定位：Prompt 调试 + API Key 管理
• 入口： https://ai.google.dev/aistudio
• API 快速入门： https://ai.google.dev/gemini-api/docs/quickstart

---

1.5.4 Tools / Agents（智能体能力）

定位：让 Gemini 不只是“回答”，还能“执行”

支持能力：Search、Code Execution、Tool / Function Calling

官方文档： https://ai.google.dev/gemini-api/docs/tools

Agent 构建官方博客： https://developers.googleblog.com/en/building-agents-google-gemini-open-source-frameworks/

---

1.5.5 Antigravity（Agent-First AI IDE）

Antigravity 是 Google 在 Gemini 3 时代推出的 Agent-First 智能开发环境，本质上是一个「让 AI 代理自动写代码、跑命令、操作项目」的 IDE。

• 定位：AI 协同开发 / 代理驱动开发
• 适合人群：高级开发者 / Agent 玩家
• 官网入口： https://antigravity.google/

Antigravity 官方文档： https://antigravity.google/docs/home

Antigravity 官方 Codelab：https://codelabs.developers.google.com/getting-started-google-antigravity

---

1.5.6 自动化 / 工作流 / 第三方集成

自动化平台集成

• 场景：n8n、GitHub Actions、CI / CD
• 方式：通过 Gemini API / CLI 接入

Google Workspace 集成

• 方式：Apps Script、Docs / Sheets / Gmail 自动化
• 思路：Gemini API + GAS

---

1.5.7 实时多模态（Live API）

定位：实时音视频 + 语言交互

适合场景：实时助手、机器人、语音对话系统

官方介绍： https://developers.googleblog.com/zh-hans/gemini-2-0-level-up-your-apps-with-real-time-multimodal-interactions/

---

1.5.8 第三方平台 / IDE / 插件生态

VS Code / Cursor 等 IDE都支持gemini插件了，例如IDEA：

1.5.9 小结

使用形态	核心入口
Web / App	https://gemini.google.com/
CLI	https://developers.google.cn/gemini-code-assist/docs/gemini-cli
API / SDK	https://ai.google.dev/gemini-api/docs
Tools / Agents	https://ai.google.dev/gemini-api/docs/tools
AI IDE	https://antigravity.google/
实时多模态	Gemini Live API

1.6 小结

通过本文，我们从零开始，详细解锁了 Google Gemini 3 Pro 的免费订阅权益，并一步步完成了从环境配置、CLI 安装到实战调用的全过程。

Gemini 3 Pro 的发布，不仅仅是 Google 在大模型参数上的竞赛，更标志着 AI 开发范式的转变：

• 从 Chat 到 Agent：我们不再仅仅是和 AI“聊天”，而是通过 CLI 和 SDK 让 AI 成为能读写文件、执行命令的 Agent（智能体）。
• 多模态原生：文本、代码、图片、视频不再是割裂的输入，Gemini 将它们融为一体，为开发者提供了更广阔的想象空间。
• 生态闭环：配合 Google 的 Workspace、Antigravity IDE 以及 Android 生态，Gemini 正在成为真正的“系统级智能中枢”。

AI 的技术迭代日新月异，工具只是手段，如何利用这些工具去创造价值，才是我们需要持续探索的方向，希望本文能帮大家顺利搭上 Gemini 的快车，谢谢阅读，本文完！

---

02 速查索引：官方文档导航（CLI）

在上一篇博客中，博主已经对 Gemini 做了一次系统性的入门介绍，从 免费订阅方式、CLI 安装 到 Agent 开发的基本流程，帮助大家快速上手这一新一代 AI 工具链。

• 《Gemini 3 完整指南（一）：免费订阅、CLI 安装到 Agent 开发一次搞懂》

随着 Gemini CLI 与 Gemini 3 能力的不断完善，其官方文档内容也愈发丰富。但对于不少同学来说，官方文档模块较多、结构较为分散，在实际查阅时往往不容易快速定位到所需内容。因此，本文并不重复讲解具体用法，而是基于 Gemini 官方文档，对其内容进行系统梳理与分类汇总，并附上直达链接，帮助大家：

• 快速了解 Gemini CLI 的整体能力边界
• 按功能模块精准定位官方文档
• 在学习与实战过程中减少无效搜索成本

无论你是刚接触 Gemini 的新手，还是已经在使用 Gemini CLI 进行开发的工程师，都可以将本文作为一份 Gemini 官方文档导航索引 / 速查手册 来使用。

2.1 目录导航

2.1.1 概览

标题	中文标题	链接
Introduction	简介	https://geminicli.com/docs/
Architecture Overview	架构概览	https://geminicli.com/docs/architecture/
Contribute guide	贡献指南	https://geminicli.com/docs/contributing/

---

2.1.2 快速开始

标题	中文标题	链接
Gemini CLI Quickstart	Gemini CLI 快速入门	https://geminicli.com/docs/get-started/
Gemini 3 on Gemini CLI	在 Gemini CLI 中使用 Gemini 3	https://geminicli.com/docs/get-started/gemini-3/
Authentication	身份认证	https://geminicli.com/docs/get-started/authentication/
Configuration	配置	https://geminicli.com/docs/get-started/configuration/
Installation	安装	https://geminicli.com/docs/get-started/installation/
Examples	示例	https://geminicli.com/docs/get-started/examples/

---

2.1.3 CLI（命令行工具）

标题	中文标题	链接
Introduction	介绍	https://geminicli.com/docs/cli/
Commands	命令	https://geminicli.com/docs/cli/commands/
Checkpointing	检查点机制	https://geminicli.com/docs/cli/checkpointing/
Custom commands	自定义命令	https://geminicli.com/docs/cli/custom-commands/
Enterprise	企业版	https://geminicli.com/docs/cli/enterprise/
Headless mode	无头模式	https://geminicli.com/docs/cli/headless/
Keyboard Shortcuts	键盘快捷键	https://geminicli.com/docs/cli/keyboard-shortcuts/
Model selection	模型选择	https://geminicli.com/docs/cli/model/
Sandbox	沙盒	https://geminicli.com/docs/cli/sandbox/
Session Management	会话管理	https://geminicli.com/docs/cli/session-management/
Agent Skills	智能体技能	https://geminicli.com/docs/cli/skills/
Settings	设置	https://geminicli.com/docs/cli/settings/
Telemetry	遥测	https://geminicli.com/docs/cli/telemetry/
Themes	主题	https://geminicli.com/docs/cli/themes/
Token caching	Token 缓存	https://geminicli.com/docs/cli/token-caching/
Trusted Folders	受信任文件夹	https://geminicli.com/docs/cli/trusted-folders/
Tutorials	教程	https://geminicli.com/docs/cli/tutorials/
Uninstall	卸载	https://geminicli.com/docs/cli/uninstall/
System Prompt Override	系统提示词覆盖	https://geminicli.com/docs/cli/system-prompt/

---

2.1.4 核心

标题	中文标题	链接
Introduction	介绍	https://geminicli.com/docs/core/
Tools API	工具 API	https://geminicli.com/docs/core/tools-api/
Memory Import Processor	记忆导入处理器	https://geminicli.com/docs/core/memport/
Policy engine	策略引擎	https://geminicli.com/docs/core/policy-engine/

---

2.1.5 工具

标题	中文标题	链接
Introduction	介绍	https://geminicli.com/docs/tools/
File system	文件系统	https://geminicli.com/docs/tools/file-system/
Shell	Shell 工具	https://geminicli.com/docs/tools/shell/
Web fetch	Web 抓取	https://geminicli.com/docs/tools/web-fetch/
Web search	Web 搜索	https://geminicli.com/docs/tools/web-search/
Memory	记忆	https://geminicli.com/docs/tools/memory/
Todo	待办事项	https://geminicli.com/docs/tools/todos/
MCP servers	MCP 服务器	https://geminicli.com/docs/tools/mcp-server/

---

2.1.6 扩展

标题	中文标题	链接
Introduction	介绍	https://geminicli.com/docs/extensions/
Getting started with extensions	扩展快速开始	https://geminicli.com/docs/extensions/getting-started-extensions/
Extension releasing	扩展发布	https://geminicli.com/docs/extensions/extension-releasing/

---

2.1.7 Hooks（钩子）

标题	中文标题	链接
Introduction	介绍	https://geminicli.com/docs/hooks/
Writing hooks	编写钩子	https://geminicli.com/docs/hooks/writing-hooks/
Hooks reference	钩子参考	https://geminicli.com/docs/hooks/reference/
Best Practices	最佳实践	https://geminicli.com/docs/hooks/best-practices/

---

2.1.8 IDE 集成

标题	中文标题	链接
Introduction	介绍	https://geminicli.com/docs/ide-integration/
IDE Companion Spec	IDE 伴随规范	https://geminicli.com/docs/ide-integration/ide-companion-spec/

---

2.1.9 开发

标题	中文标题	链接
NPM	NPM	https://geminicli.com/docs/npm/
Releases	发布版本	https://geminicli.com/docs/releases/
Integration tests	集成测试	https://geminicli.com/docs/integration-tests/
Issue and pr automation	Issue 与 PR 自动化	https://geminicli.com/docs/issue-and-pr-automation/

2.2 小结

本文围绕 Gemini 官方文档，按照其整体结构对相关内容进行了系统整理，涵盖了从 快速入门、CLI 核心能力，到 Tools、Hooks、扩展机制、IDE 集成 以及 开发与发布相关内容 等多个方面。希望本文能帮助到大家，欢迎点赞、收藏或留言交流，本文完！

---

03 CLI 实战：命令、自定义命令、无头模式与效率设置

在完成了基础安装、配置与整体能力概览之后，接下来真正影响使用效率的，往往不是“能不能用”，而是“会不会用、能不能用得顺手、能不能把它接入自己的工作流”。因此本文将把重点放在 Gemini CLI 的交互命令体系与工程化用法上，围绕三条主线展开：

1. CLI 内置命令（/、@、!）：分别对应会话/配置管理、上下文注入、以及与本地 shell 的交互能力，理解它们的边界能大幅提升日常使用体验。
2. 自定义命令：把高频提示沉淀成可复用的“个人快捷方式”，并掌握 {{args}}、!{...}、@{...} 等关键语法，搭建自己的命令库。
3. 无头模式（Headless）：将 Gemini CLI 从“交互式工具”升级为“脚本接口”，可用于自动化任务、批处理、CI/CD 流水线与工程集成。

3.1 CLI 命令

Gemini CLI 支持多个内置命令，帮助你管理会话、自定义界面，并控制其行为，这些命令以前置的正斜杠（/）、at 符号（@）或感叹号（!）开头。

3.1.1 斜杠命令（/）

斜杠命令提供对 CLI 本身的元层级控制，内置命令汇总如下：

命令	子命令	说明（含用法 / 行为 / 备注）
/bug	-	提交 Gemini CLI 的问题，默认提交到 GitHub 仓库；/bug <title> 中的文本作为 bug 标题；默认行为可通过 .gemini/settings.json 中的 advanced.bugCommand 修改
/chat	-	保存与恢复对话历史，用于交互式分支或在后续会话中恢复；聊天按项目隔离
/chat	save	保存当前对话历史；用法：/chat save <tag>；默认保存路径：Linux/macOS ~/.gemini/tmp/<project_hash>/，Windows C:\Users\<User>\.gemini\tmp\<project_hash>\；聊天仅能在同一项目中访问
/chat	resume	从已保存的标签恢复对话；用法：/chat resume <tag>；只能恢复当前项目内的聊天
/chat	list	列出当前项目中可用于恢复的聊天标签；不会显示其他项目的聊天
/chat	delete	删除已保存的聊天检查点；用法：/chat delete <tag>
/chat	share	将当前对话导出为 Markdown 或 JSON；用法：/chat share file.md / file.json；未指定文件名则自动生成
/clear	-	清空终端屏幕的可见会话历史与回滚内容；快捷键：Ctrl+L；底层会话数据可能仍保留
/compress	-	使用摘要替换整个聊天上下文，以节省后续任务的 token
/copy	-	复制 Gemini CLI 最后一条输出到剪贴板；本地使用系统剪贴板工具，远程（SSH/WSL）使用 OSC 52；Linux 需 xclip/xsel，macOS 使用 pbcopy，Windows 使用 clip
/directory / /dir	-	管理工作区目录以支持多目录
/directory	add	添加目录到工作区；用法：/directory add <path1>,<path2>；支持绝对路径、相对路径和主目录引用；沙盒配置下需使用 --include-directories
/directory	show	显示通过 /directory add 或 --include-directories 添加的所有目录
/editor	-	打开用于选择受支持编辑器的对话框
/extensions	-	列出当前 Gemini CLI 会话中已启用的扩展
/help / /?	-	显示 Gemini CLI 的帮助信息，包括可用命令及其用法
/mcp	-	管理已配置的 Model Context Protocol (MCP) 服务器；不带子命令时默认等同于 list
/mcp	list / ls	列出已配置的 MCP 服务器与工具
/mcp	desc	列出 MCP 服务器与工具，并附带描述
/mcp	schema	列出 MCP 服务器与工具，并附带描述和 schema
/mcp	auth	与支持 OAuth 的 MCP 服务器进行身份验证；用法：/mcp auth <server-name>；不指定名称则列出所有支持 OAuth 的服务器
/mcp	refresh	重启所有 MCP 服务器并重新发现其可用工具
/model	-	打开对话框以选择 Gemini 模型
/memory	-	管理从 GEMINI.md 文件加载的分层指令记忆
/memory	add	将文本添加到 AI 的记忆中；用法：/memory add <text>
/memory	show	显示从所有 GEMINI.md 文件加载的分层记忆的完整拼接内容，用于检查模型指令上下文
/memory	refresh	重新加载所有配置位置中的 GEMINI.md 文件，并用最新内容更新模型
/memory	list	列出用于分层记忆的所有 GEMINI.md 文件路径
/restore	-	将项目文件恢复到工具执行前的状态；用法：/restore [tool_call_id]；需在 settings 中启用检查点功能
/resume	-	打开交互式会话浏览器，浏览、搜索、排序、删除并恢复自动保存的对话；所有聊天都会自动保存
/settings	-	打开设置编辑器以查看和修改 Gemini CLI 设置；等同于编辑 .gemini/settings.json，并提供校验与引导
/skills	-	（实验性）管理 Agent Skills，提供按需的专业能力与工作流
/skills	list	列出所有已发现的技能及其启用/禁用状态
/skills	enable	启用指定技能；用法：/skills enable <name>
/skills	disable	禁用指定技能；用法：/skills disable <name>
/skills	reload	从所有层级刷新已发现的技能列表
/stats	-	显示当前会话的统计信息，包括 token 使用量、缓存 token 节省（如可用）与会话时长
/theme	-	打开对话框以更改 Gemini CLI 的视觉主题
/auth	-	打开对话框以更改身份验证方式
/about	-	显示版本信息；提交问题时建议附带
/tools	-	显示当前可用的工具列表；用法：/tools [desc]
/tools	desc / descriptions	显示每个工具的详细描述
/tools	nodesc / nodescriptions	隐藏工具描述，仅显示工具名称
/privacy	-	显示隐私声明，并允许选择是否同意数据收集
/quit / /exit	-	退出 Gemini CLI
/vim	-	启用或关闭 Vim 模式；支持 NORMAL / INSERT 模式、计数、重复命令；偏好会持久化到 ~/.gemini/settings.json
/init	-	分析当前目录并生成定制化的 GEMINI.md，用于提供项目上下文说明

3.1.2 At 命令（@）

At 命令用于 将文件或目录的内容作为你给 Gemini 的提示的一部分包含进来@<path_to_file_or_directory>。这些命令包含基于 git 的过滤能力。

说明： 将指定文件或多个文件的内容注入到你的当前提示中，这对于询问特定代码、文本或文件集合非常有用。

示例：

• @path/to/your/file.txt Explain this text.
• @src/my_project/ Summarize the code in this directory.
• What is this file about? @README.md

详情：

• 如果提供的是单个文件的路径，则会读取该文件的内容。
• 如果提供的是目录路径，则命令会尝试读取该目录及其所有子目录内文件的内容。
• 路径中的空格应使用反斜杠转义（例如，@My\ Documents/file.txt）。
• 该命令在内部使用 read_many_files 工具。内容会被获取并插入到你的查询中，然后再发送给 Gemini模型。

---

基于 Git 的过滤： 默认情况下，git 忽略的文件（如node_modules/、dist/、.env、.git/）会被排除。此行为可通过 context.fileFiltering 设置进行更改。

文件类型： 该命令面向基于文本的文件，虽然它可能会尝试读取任意文件，但二进制文件或非常大的文件可能会被底层的 read_many_files 工具跳过或截断，以确保性能与相关性。工具会指示是否有文件被跳过。

输出： CLI 将显示一条工具调用消息，表明使用了 read_many_files，并附带一条详细说明状态与已处理路径的消息。

@（单独的 at 符号）： 如果你输入单独的 @ 符号且不带路径，查询会原样传递给 Gemini 模型，如果你正在提示中专门谈论 @ 符号本身，这可能会很有用。

---

@ 命令的错误处理

• 如果在 @ 之后指定的路径不存在或无效，将显示错误消息，并且查询可能不会发送给 Gemini 模型，或者它会在不包含文件内容的情况下被发送。
• 如果 read_many_files 工具遇到错误（例如权限问题），也会被报告。

3.1.3 Shell 模式与透传命令（!）

! 前缀让你可以在 Gemini CLI 内直接与系统 shell 交互。

说明： 使用 bash 在 Linux/macOS 上或在 Windows 上使用 powershell.exe -NoProfile -Command 执行给定的 <shell_command>（除非你覆盖 ComSpec）。命令的任何输出或错误都会显示在终端中。

示例：

• !ls -la（执行 ls -la 并返回 Gemini CLI）
• !git status（执行 git status 并返回 Gemini CLI）

---

单独输入 ! 会切换 shell 模式。

• 进入 shell 模式： 激活时，shell 模式会使用不同的配色以及一个 “Shell Mode Indicator”。在 shell 模式下，你输入的文本会被直接解释为 shell 命令。
• 退出 shell 模式： 退出后，界面会恢复其标准外观，并恢复正常的 Gemini CLI 行为。

注意： 在 shell 模式下执行的命令具有与直接在终端中运行相同的权限与影响。

环境变量： 当命令通过 ! 或在 shell 模式中执行时，子进程的环境中会设置 GEMINI_CLI=1 环境变量。这使脚本或工具能够检测它们是否正在从Gemini CLI 内部运行。

3.2 自定义命令

自定义命令让你可以将最喜欢或最常用的提示保存并复用，作为 Gemini CLI 中的个人快捷方式。你可以创建特定于单个项目的命令，也可以创建在所有项目中全局可用的命令，从而简化工作流并确保一致性。

3.2.1 文件位置与优先级

Gemini CLI 会从两个位置发现命令，并按特定顺序加载：

1. 【用户命令（全局）】： 位于 ~/.gemini/commands/。这些命令在你所工作的任何项目中都可用。
2. 【项目命令（本地）】： 位于 <your-project-root>/.gemini/commands/。这些命令特定于当前项目，并可以纳入版本控制以便与你的团队共享。

如果项目目录中的命令与用户目录中的命令同名，则 始终使用项目命令。 这使项目能够用项目特定版本覆盖全局命令。

3.2.2 命名与命名空间

命令的名称由其相对于 commands 目录的文件路径决定，子目录用于创建带命名空间的命令，路径分隔符（/ 或 \）会被转换为冒号（:）。

• 位于 ~/.gemini/commands/test.toml 的文件会变成命令 /test。
• 位于 <project>/.gemini/commands/git/commit.toml 的文件会变成带命名空间的
  命令 /git:commit。

TOML 文件格式（v1）:

命令定义文件必须使用 TOML 格式编写，并使用.toml 文件扩展名。

必填字段:

• prompt（String）：执行命令时将发送给 Gemini 模型的提示，它可以是单行或多行字符串。

可选字段：

• description（String）：对命令作用的简短单行描述，这段文本会显示在 /help 菜单中你的命令旁边。如果你省略此字段，将从文件名生成一个通用描述。

3.2.3 处理参数

自定义命令支持两种强大的参数处理方法，CLI 会根据命令 prompt 的内容自动选择正确的方法。

3.2.3.1 使用 {{args}} 的上下文感知注入

如果你的 prompt 包含特殊占位符 {{args}}，CLI 会将该占位符替换为用户在命令名之后输入的文本。这种注入的行为取决于它被使用的位置：

---

A. 原样注入（在 shell 命令之外）

当在 prompt 主体中使用时，参数会按用户输入的原样精确注入，例如示例（git/fix.toml）：

# Invoked via: /git:fix "Button is misaligned"

description = "Generates a fix for a given issue."
prompt = "Please provide a code fix for the issue described here: {{args}}."

模型接收到：Please provide a code fix for the issue described here: "Button is misaligned".

---

B. 在 shell 命令中使用参数（在 !{…} 块内）

当你在 shell 注入块（!{...}）中使用 {{args}} 时，参数会在替换前自动进行 shell 转义。这让你可以安全地将参数传给 shell 命令，确保生成的命令在语法上正确且安全，同时防止命令注入漏洞。例如（/grep-code.toml）：

prompt = """
Please summarize the findings for the pattern `{{args}}`.

Search Results:
!{grep -r {{args}} .}
"""

当你运行 /grep-code It's complicated：

1. CLI 看到 {{args}} 同时用于 !{...} 之外和之内。
2. 在外部：第一个 {{args}} 被原样替换为 It's complicated。
3. 在内部：第二个 {{args}} 被替换为转义后的版本（例如在 Linux 上："It\'s complicated"）。
4. 执行的命令是 grep -r "It's complicated" .。
5. CLI 会提示你在执行前确认这一条精确且安全的命令。
6. 最终提示会被发送。

3.2.3.2 默认参数处理

处理方式：

• 如果 prompt 不 包含特殊占位符 {{args}}，CLI 会使用默认行为来处理参数。
• 如果为命令提供了参数（例如 /mycommand arg1），CLI 会将你输入的完整命令追加到 prompt 末尾，并用两个换行分隔，这使模型能够同时看到原始指令以及你刚提供的具体参数。
• 如果 不 提供任何参数（例如 /mycommand），prompt 会按原样发送给模型，不会追加任何内容。

---

示例（changelog.toml）： 该示例展示了如何通过为模型定义角色、解释用户输入的位置，并指定期望的格式与行为来创建一个健壮的命令。

# In: <project>/.gemini/commands/changelog.toml
# Invoked via: /changelog 1.2.0 added "Support for default argument parsing."

description = "Adds a new entry to the project's CHANGELOG.md file."
prompt = """
# Task: Update Changelog

You are an expert maintainer of this software project. A user has invoked a command to add a new entry to the changelog.

**The user's raw command is appended below your instructions.**

Your task is to parse the `<version>`, `<change_type>`, and `<message>` from their input and use the `write_file` tool to correctly update the `CHANGELOG.md` file.

## Expected Format
The command follows this format: `/changelog <version> <type> <message>`
- `<type>` must be one of: "added", "changed", "fixed", "removed".

## Behavior
1. Read the `CHANGELOG.md` file.
2. Find the section for the specified `<version>`.
3. Add the `<message>` under the correct `<type>` heading.
4. If the version or type section doesn't exist, create it.
5. Adhere strictly to the "Keep a Changelog" format.
"""

当运行 /changelog 1.2.0 added "New feature" 时，发送给模型的最终文本将是原始 prompt，后接两个换行以及输入的命令。

3.2.3.3 使用 !{…} 执行 shell 命令

可以通过在prompt 中直接执行 shell 命令并注入其输出来让命令变得动态，这非常适合从本地环境中收集上下文，比如读取文件内容或检查Git 状态。

当自定义命令尝试执行 shell 命令时，Gemini CLI 现在会在继续之前提示确认，这是一项安全措施，确保只运行预期的命令。

---

工作原理：

1. 注入命令： 使用 !{...} 语法。
2. 参数替换： 如果 {{args}} 出现在块内，它会自动进行 shell 转义。
3. 健壮解析： 解析器能正确处理复杂的 shell 命令，包括带有嵌套花括号的内容，例如 JSON 负载。注意： !{...} 内部的内容必须花括号平衡（{ 与 }）。如果你需要执行包含不平衡花括号的命令，可以考虑将其包装在外部脚本文件中，并在 !{...} 块内调用该脚本。
4. 安全检查与确认： CLI 会对最终解析后的命令执行安全检查（在参数被转义并替换之后）。会弹出一个对话框，显示将要执行的确切命令。
5. 执行与错误报告： 命令会被执行。如果命令失败，被注入到 prompt 的输出将包含错误消息
   （stderr），并在末尾附带状态行，例如 [Shell command exited with code 1]。这有助于模型理解失败的上下文。

---

示例（git/commit.toml）：

此命令获取暂存区的 git diff，并用它来让模型撰写一个
提交消息。

# In: <project>/.gemini/commands/git/commit.toml
# Invoked via: /git:commit

description = "Generates a Git commit message based on staged changes."

# The prompt uses !{...} to execute the command and inject its output.
prompt = """
Please generate a Conventional Commit message based on the following git diff:

```diff
!{git diff --staged}
```

"""

当你运行 /git:commit 时，CLI 会先执行 git diff --staged，然后用该命令的输出替换 !{git diff --staged}，再发送最终完整的 prompt 给模型。

3.2.3.4 使用 @{…} 注入文件内容

你可以使用 @{...} 语法将文件内容或目录列表直接嵌入到 prompt 中。这对于创建针对特定文件操作的命令非常有用。

工作原理：

• 文件注入：@{path/to/file.txt} 会被替换为 file.txt 的内容。
• 多模态支持：如果路径指向受支持的图像（例如 PNG、JPEG）、PDF、音频或视频文件，它将被正确编码并作为多模态输入注入。其他二进制文件会被妥善处理并跳过。
• 目录列表：@{path/to/dir} 会被遍历，目录及其所有子目录中的每个文件都会被插入到 prompt 中。这会在启用时遵循 .gitignore 与 .geminiignore。
• 工作区感知：命令会在当前目录以及其他工作区目录中搜索该路径。只要位于工作区内，也允许使用绝对路径。
• 处理顺序：使用 @{...} 的文件内容注入会在shell 命令（!{...}）与参数替换（{{args}}）之前处理。
• 解析：解析器要求 @{...} 内部（路径）花括号平衡（{ 与 }）。

---

示例（review.toml）： 此命令注入一个 _固定_ 的最佳实践文件（docs/best-practices.md）的内容，并使用用户参数为评审提供上下文。

# In: <project>/.gemini/commands/review.toml
# Invoked via: /review FileCommandLoader.ts

description = "Reviews the provided context using a best practice guide."
prompt = """
You are an expert code reviewer.

Your task is to review {{args}}.

Use the following best practices when providing your review:

@{docs/best-practices.md}
"""

当你运行 /review FileCommandLoader.ts 时，@{docs/best-practices.md}占位符会被替换为该文件的内容，而 {{args}} 会被替换为你提供的文本，然后最终 prompt 会被发送给模型。

---

3.2.4 一个“纯函数”重构命令示例

接下来创建一个全局命令，让模型重构一段代码。

1. 创建文件与目录：

首先，确保用户命令目录存在，然后创建一个 refactor 子目录用于组织，并创建最终的 TOML 文件。

mkdir -p ~/.gemini/commands/refactor
touch ~/.gemini/commands/refactor/pure.toml

2. 将内容添加到文件中：

在编辑器中打开 ~/.gemini/commands/refactor/pure.toml 并添加以下内容，包含了可选的 description 作为最佳实践。

# In: ~/.gemini/commands/refactor/pure.toml
# This command will be invoked via: /refactor:pure

description = "Asks the model to refactor the current context into a pure function."

prompt = """
Please analyze the code I've provided in the current context.
Refactor it into a pure function.

Your response should include:
1. The refactored, pure function code block.
2. A brief explanation of the key changes you made and why they contribute to purity.
"""

3. 运行命令：

现在可以在 CLI 中运行你的命令了，首先，可能会添加一个文件到上下文中，然后调用命令：

> @my-messy-function.js
> /refactor:pure

然后 Gemini CLI 会执行你 TOML 文件中定义的多行 prompt。

3.3 无头模式

无头模式允许你从 命令行脚本 与 自动化工具 中以编程方式 运行 Gemini CLI，而不需要任何交互式 UI，这非常适合脚本编写、自动化、CI/CD 流水线，以及构建 AI 驱动的工具。

无头模式为 Gemini CLI 提供了一个无头接口，它可以：

• 通过命令行参数或 stdin 接受提示
• 返回结构化输出（文本或 JSON）
• 支持文件重定向与管道
• 支持自动化与脚本工作流
• 提供一致的退出码以便进行错误处理

3.3.1 基本用法

---

直接提示：使用 --prompt（或 -p）标志以无头模式运行

gemini --prompt "What is machine learning?"

---

Stdin 输入：从终端将输入通过管道传给 Gemini CLI

echo "Explain this code" | gemini

---

与文件输入组合：从文件读取并用 Gemini 处理

cat README.md | gemini --prompt "Summarize this documentation"

3.3.2 输出格式

3.3.2.1 文本输出

---

文本输出（默认）：标准的人类可读输出

gemini -p "What is the capital of France?"

响应格式：

The capital of France is Paris.

3.3.2.2 JSON 输出

---

JSON 输出：返回结构化数据，包括响应、统计信息与元数据。该格式非常适合用于程序化处理与自动化脚本。

---

响应架构：JSON 输出遵循以下高层结构

{
  "response": "string", // The main AI-generated content answering your prompt
  "stats": {
    // Usage metrics and performance data
    "models": {
      // Per-model API and token usage statistics
      "[model-name]": {
        "api": {
          /* request counts, errors, latency */
        },
        "tokens": {
          /* prompt, response, cached, total counts */
        }
      }
    },
    "tools": {
      // Tool execution statistics
      "totalCalls": "number",
      "totalSuccess": "number",
      "totalFail": "number",
      "totalDurationMs": "number",
      "totalDecisions": {
        /* accept, reject, modify, auto_accept counts */
      },
      "byName": {
        /* per-tool detailed stats */
      }
    },
    "files": {
      // File modification statistics
      "totalLinesAdded": "number",
      "totalLinesRemoved": "number"
    }
  },
  "error": {
    // Present only when an error occurred
    "type": "string", // Error type (e.g., "ApiError", "AuthError")
    "message": "string", // Human-readable error description
    "code": "number" // Optional error code
  }
}

示例用法：

gemini -p "What is the capital of France?" --output-format json

响应：

{
  "response": "The capital of France is Paris.",
  "stats": {
    "models": {
      "gemini-2.5-pro": {
        "api": {
          "totalRequests": 2,
          "totalErrors": 0,
          "totalLatencyMs": 5053
        },
        "tokens": {
          "prompt": 24939,
          "candidates": 20,
          "total": 25113,
          "cached": 21263,
          "thoughts": 154,
          "tool": 0
        }
      },
      "gemini-2.5-flash": {
        "api": {
          "totalRequests": 1,
          "totalErrors": 0,
          "totalLatencyMs": 1879
        },
        "tokens": {
          "prompt": 8965,
          "candidates": 10,
          "total": 9033,
          "cached": 0,
          "thoughts": 30,
          "tool": 28
        }
      }
    },
    "tools": {
      "totalCalls": 1,
      "totalSuccess": 1,
      "totalFail": 0,
      "totalDurationMs": 1881,
      "totalDecisions": {
        "accept": 0,
        "reject": 0,
        "modify": 0,
        "auto_accept": 1
      },
      "byName": {
        "google_web_search": {
          "count": 1,
          "success": 1,
          "fail": 0,
          "durationMs": 1881,
          "decisions": {
            "accept": 0,
            "reject": 0,
            "modify": 0,
            "auto_accept": 1
          }
        }
      }
    },
    "files": {
      "totalLinesAdded": 0,
      "totalLinesRemoved": 0
    }
  }
}

3.3.2.3 流式JSON输出

以换行分隔的 JSON（JSONL）形式返回实时事件。每个重要动作（初始化、消息、工具调用、结果）都会在发生时立即输出，该格式非常适合用于监控长时间运行的操作、构建带实时进度的 UI，以及创建对事件作出响应的自动化流水线。

何时使用流式 JSON？

当你需要以下能力时使用 --output-format stream-json：

• 实时进度监控 - 随时查看工具调用与响应的发生
• 事件驱动自动化 - 对特定事件作出反应（例如工具失败）
• 实时 UI 更新 - 构建界面以实时展示 AI 代理活动
• 详细执行日志 - 捕获完整交互历史与时间戳
• 流水线集成 - 将事件流发送到日志/监控系统

---

流式格式会发出 6 种事件类型：

1. init - 会话开始（包含 session_id、model）
2. message - 用户提示与助手响应
3. tool_use - 工具调用请求与参数
4. tool_result - 工具执行结果（success/error）
5. error - 非致命错误与警告
6. result - 最终会话结果与聚合统计信息

---

基本用法

# Stream events to console
gemini --output-format stream-json --prompt "What is 2+2?"

# Save event stream to file
gemini --output-format stream-json --prompt "Analyze this code" > events.jsonl

# Parse with jq
gemini --output-format stream-json --prompt "List files" | jq -r '.type'

示例输出：每一行都是一个完整的 JSON 事件

{"type":"init","timestamp":"2025-10-10T12:00:00.000Z","session_id":"abc123","model":"gemini-2.0-flash-exp"}
{"type":"message","role":"user","content":"List files in current directory","timestamp":"2025-10-10T12:00:01.000Z"}
{"type":"tool_use","tool_name":"Bash","tool_id":"bash-123","parameters":{"command":"ls -la"},"timestamp":"2025-10-10T12:00:02.000Z"}
{"type":"tool_result","tool_id":"bash-123","status":"success","output":"file1.txt\nfile2.txt","timestamp":"2025-10-10T12:00:03.000Z"}
{"type":"message","role":"assistant","content":"Here are the files...","delta":true,"timestamp":"2025-10-10T12:00:04.000Z"}
{"type":"result","status":"success","stats":{"total_tokens":250,"input_tokens":50,"output_tokens":200,"duration_ms":3000,"tool_calls":1},"timestamp":"2025-10-10T12:00:05.000Z"}

文件重定向：将输出保存到文件或通过管道传给其他命令：

# Save to file
gemini -p "Explain Docker" > docker-explanation.txt
gemini -p "Explain Docker" --output-format json > docker-explanation.json

# Append to file
gemini -p "Add more details" >> docker-explanation.txt

# Pipe to other tools
gemini -p "What is Kubernetes?" --output-format json | jq '.response'
gemini -p "Explain microservices" | wc -w
gemini -p "List programming languages" | grep -i "python"

3.3.3 配置选项

无头使用的关键命令行选项：

Option	Description	Example
--prompt, -p	以无头模式运行	gemini -p "query"
--output-format	指定输出格式（text、json）	gemini -p "query" --output-format json
--model, -m	指定 Gemini 模型	gemini -p "query" -m gemini-2.5-flash
--debug, -d	启用调试模式	gemini -p "query" --debug
--include-directories	包含额外目录	gemini -p "query" --include-directories src,docs
--yolo, -y	自动批准所有操作	gemini -p "query" --yolo
--approval-mode	设置批准模式	gemini -p "query" --approval-mode auto_edit

3.3.4 示例

代码审查

cat src/auth.py | gemini -p "Review this authentication code for security issues" > security-review.txt

---

生成提交消息

result=$(git diff --cached | gemini -p "Write a concise commit message for these changes" --output-format json)
echo "$result" | jq -r '.response'

---

API 文档

result=$(cat api/routes.js | gemini -p "Generate OpenAPI spec for these routes" --output-format json)
echo "$result" | jq -r '.response' > openapi.json

---

批量代码分析

for file in src/*.py; do
    echo "Analyzing $file..."
    result=$(cat "$file" | gemini -p "Find potential bugs and suggest improvements" --output-format json)
    echo "$result" | jq -r '.response' > "reports/$(basename "$file").analysis"
    echo "Completed analysis for $(basename "$file")" >> reports/progress.log
done

---

代码审查

result=$(git diff origin/main...HEAD | gemini -p "Review these changes for bugs, security issues, and code quality" --output-format json)
echo "$result" | jq -r '.response' > pr-review.json

---

日志分析

grep "ERROR" /var/log/app.log | tail -20 | gemini -p "Analyze these errors and suggest root cause and fixes" > error-analysis.txt

---

发布说明生成

result=$(git log --oneline v1.0.0..HEAD | gemini -p "Generate release notes from these commits" --output-format json)
response=$(echo "$result" | jq -r '.response')
echo "$response"
echo "$response" >> CHANGELOG.md

---

模型与工具使用跟踪

result=$(gemini -p "Explain this database schema" --include-directories db --output-format json)
total_tokens=$(echo "$result" | jq -r '.stats.models // {} | to_entries | map(.value.tokens.total) | add // 0')
models_used=$(echo "$result" | jq -r '.stats.models // {} | keys | join(", ") | if . == "" then "none" else . end')
tool_calls=$(echo "$result" | jq -r '.stats.tools.totalCalls // 0')
tools_used=$(echo "$result" | jq -r '.stats.tools.byName // {} | keys | join(", ") | if . == "" then "none" else . end')
echo "$(date): $total_tokens tokens, $tool_calls tool calls ($tools_used) used with models: $models_used" >> usage.log
echo "$result" | jq -r '.response' > schema-docs.md
echo "Recent usage trends:"
tail -5 usage.log

3.4 模型选择（/model 命令）

/model 命令让你可以配置 Gemini CLI 使用的模型，从而更好地控制输出结果。复杂任务与推理使用 Pro模型，高速结果使用 Flash 模型，或使用（推荐的）Auto 设置让系统为任务选择最佳模型。

注意： /model 命令（以及 --model 标志）不会覆盖 sub-agents 使用的模型。因此，即使使用 /model 标志，你也可能会在模型使用报告中看到使用了其他模型。

在 Gemini CLI 中使用以下命令：

/model

运行该命令将打开一个对话框，提供以下选项：

选项	描述	模型
Auto (Gemini 3)	让系统为你的任务选择最佳 Gemini 3 模型	gemini-3-pro-preview (if enabled), gemini-3-flash-preview (if enabled)
Auto (Gemini 2.5)	让系统为你的任务选择最佳 Gemini 2.5 模型	gemini-2.5-pro, gemini-2.5-flash
Manual	选择一个特定模型	Any available model.

我们建议从以上 Auto 选项中选择一个。不过，你也可以选择 Manual，从可用模型中选择一个特定模型。

备注：如果要启用 Gemini 3 Pro 与 Gemini 3 Flash，需要通过 settings命令来启用预览功能，如下图

模型选择最佳实践:

• 默认使用 Auto。 对大多数用户而言，_Auto_ 选项模型提供了速度与性能之间的平衡，会根据任务复杂度自动选择合适的模型。示例：开发 web应用可能包含复杂任务（构建架构与搭建项目脚手架）与简单任务（生成 CSS）的混合。
• 如果结果不符合预期，切换到 Pro。 如果你认为需要模型“更聪明”一些，你可以手动选择 Pro。Pro将提供最高水平的推理与创造力（例如：一个复杂或多阶段的调试任务）。
• 如果需要更快结果，切换到 Flash 或 Flash-Lite。 如果需要快速得到一个简单响应，Flash 或 Flash-Lite 是最佳选择，例如将一个 JSON 对象转换为 YAML 字符串。

3.5 设置（/settings 命令）

/settings命令会打开一个对话框，用于查看和编辑所有 Gemini CLI 设置，包括 UI 体验、键位绑定以及无障碍功能。设置存储在 settings.json 文件中。除了使用 /settings 命令外，还可以在以下位置之一编辑它们：

• 用户设置： ~/.gemini/settings.json
• 工作区设置： your-project/.gemini/settings.json

注意：工作区设置会覆盖用户设置。

以下是所有可用设置的列表，按类别分组，并按它们在 UI 中出现的顺序排列：

3.5.1 通用设置（General）

UI 标签	配置项	说明	默认值
Preview Features (e.g., models)	general.previewFeatures	启用预览功能（例如预览模型）。	false
Vim Mode	general.vimMode	启用 Vim 键位绑定	false
Enable Auto Update	general.enableAutoUpdate	启用自动更新。	true
Enable Prompt Completion	general.enablePromptCompletion	在输入时启用 AI 驱动的提示补全建议。	false
Debug Keystroke Logging	general.debugKeystrokeLogging	启用将按键记录输出到控制台的调试日志。	false
Enable Session Cleanup	general.sessionRetention.enabled	启用自动会话清理	false

---

3.5.2 输出（Output）

UI 标签	配置项	说明	默认值
Output Format	output.format	CLI 输出格式。可以是 text 或 json。	"text"

---

3.5.3 用户界面（UI）

UI 标签	配置项	说明	默认值
Hide Window Title	ui.hideWindowTitle	隐藏窗口标题栏	false
Show Thoughts in Title	ui.showStatusInTitle	在工作阶段于终端窗口标题中显示 Gemini CLI 模型的思考内容	false
Dynamic Window Title	ui.dynamicWindowTitle	使用当前状态图标动态更新终端窗口标题	true
Show Home Directory Warning	ui.showHomeDirectoryWarning	在主目录中运行 Gemini CLI 时显示警告。	true
Hide Tips	ui.hideTips	在 UI 中隐藏有用提示	false
Hide Banner	ui.hideBanner	隐藏应用横幅	false
Hide Context Summary	ui.hideContextSummary	隐藏输入框上方的上下文摘要（GEMINI.md、MCP servers）。	false
Hide CWD	ui.footer.hideCWD	在页脚隐藏当前工作目录路径	false
Hide Sandbox Status	ui.footer.hideSandboxStatus	在页脚隐藏 sandbox 状态指示器	false
Hide Model Info	ui.footer.hideModelInfo	在页脚隐藏模型名称与上下文使用情况	false
Hide Context Window Percentage	ui.footer.hideContextPercentage	隐藏剩余上下文窗口百分比。	true
Hide Footer	ui.hideFooter	在 UI 中隐藏页脚	false
Show Memory Usage	ui.showMemoryUsage	在 UI 中显示内存使用信息	false
Show Line Numbers	ui.showLineNumbers	在聊天中显示行号。	true
Show Citations	ui.showCitations	在聊天中显示生成文本的引用。	false
Show Model Info In Chat	ui.showModelInfoInChat	在聊天中为每个模型轮次显示模型名称。	false
Use Full Width	ui.useFullWidth	使用终端的整个宽度进行输出。	true
Use Alternate Screen Buffer	ui.useAlternateBuffer	为 UI 使用备用屏幕缓冲区，以保留 shell 历史。	false
Incremental Rendering	ui.incrementalRendering	为 UI 启用增量渲染；减少闪烁但可能产生渲染伪影，仅在启用备用缓冲区时支持。	true
Enable Loading Phrases	ui.accessibility.enableLoadingPhrases	在操作期间启用加载短语。	true
Screen Reader Mode	ui.accessibility.screenReader	以纯文本渲染输出，使其对屏幕阅读器更友好	false

---

3.5.4 IDE 集成（IDE）

UI 标签	配置项	说明	默认值
IDE Mode	ide.enabled	启用 IDE 集成模式。	false

---

3.5.5 模型（Model）

UI 标签	配置项	说明	默认值
Max Session Turns	model.maxSessionTurns	单个会话中保留的最大用户 / 模型 / 工具轮次数量；-1 表示无限制。	-1
Compression Threshold	model.compressionThreshold	触发上下文压缩的使用比例（如 0.2、0.3）。	0.5
Skip Next Speaker Check	model.skipNextSpeakerCheck	跳过下一次说话者检查。	true

---

3.5.6 上下文（Context）

UI 标签	配置项	说明	默认值
Memory Discovery Max Dirs	context.discoveryMaxDirs	搜索 memory 的最大目录数。	200
Load Memory From Include Directories	context.loadMemoryFromIncludeDirectories	控制 /memory refresh 是否扫描 include 目录加载 GEMINI.md。	false
Respect .gitignore	context.fileFiltering.respectGitIgnore	搜索时遵循 .gitignore 文件。	true
Respect .geminiignore	context.fileFiltering.respectGeminiIgnore	搜索时遵循 .geminiignore 文件。	true
Enable Recursive File Search	context.fileFiltering.enableRecursiveFileSearch	在 @ 引用补全时启用递归文件搜索。	true
Enable Fuzzy Search	context.fileFiltering.enableFuzzySearch	搜索文件时启用模糊搜索。	true

---

3.5.7 工具（Tools）

UI 标签	配置项	说明	默认值
Enable Interactive Shell	tools.shell.enableInteractiveShell	使用 node-pty 提供交互式 shell；失败时回退到 child_process。	true
Show Color	tools.shell.showColor	在 shell 输出中显示颜色。	false
Auto Accept	tools.autoAccept	自动接受并执行被认为安全的工具调用（如只读操作）。	false
Use Ripgrep	tools.useRipgrep	使用 ripgrep 搜索文件内容，提供更快性能。	true
Enable Tool Output Truncation	tools.enableToolOutputTruncation	启用对大型工具输出的截断。	true
Tool Output Truncation Threshold	tools.truncateToolOutputThreshold	工具输出超过该字符数时截断；-1 禁用。	4000000
Tool Output Truncation Lines	tools.truncateToolOutputLines	截断时保留的行数。	1000
Disable LLM Correction	tools.disableLLMCorrection	禁用基于 LLM 的 edit 工具错误修正；找不到精确匹配时立即失败。	true

---

3.5.8 安全（Security）

UI 标签	配置项	说明	默认值
Disable YOLO Mode	security.disableYoloMode	即使通过标志启用了 YOLO 模式，也强制禁用。	false
Allow Permanent Tool Approval	security.enablePermanentToolApproval	在工具确认对话框中启用“允许用于所有未来会话”。	false
Blocks extensions from Git	security.blockGitExtensions	阻止从 Git 安装并加载 extensions。	false
Folder Trust	security.folderTrust.enabled	是否启用 Folder Trust 的设置标记。	false
Enable Environment Variable Redaction	security.environmentVariable_redaction.enabled	对可能包含机密的环境变量进行脱敏处理。	false

---

3.5.9 实验性功能（Experimental）

UI 标签	配置项	说明	默认值
Agent Skills	experimental.skills	启用 Agent Skills（实验性）。	false
Enable Codebase Investigator	experimental.codebaseInvestigatorSettings.enabled	启用 Codebase Investigator agent。	true
Codebase Investigator Max Num Turns	experimental.codebaseInvestigatorSettings.maxNumTurns	Codebase Investigator 的最大轮次数。	10
Use OSC 52 Paste	experimental.useOSC52Paste	使用 OSC 52 进行粘贴（对远程会话有用）。	false
Enable CLI Help Agent	experimental.cliHelpAgentSettings.enabled	启用 CLI Help Agent。	true
Plan	experimental.plan	启用规划功能（Plan Mode 和工具）。	false

---

3.5.10 Hooks 配置（HooksConfig）

UI 标签	配置项	说明	默认值
Hook Notifications	hooksConfig.notifications	当 hooks 执行时显示视觉指示器。	true

3.6 主题

Gemini CLI 支持多种主题，用于自定义其配色方案与外观。你可以通过 /theme 命令或 "theme": 配置设置来更改主题，以符合你的偏好。

3.6.1 可用主题

Gemini CLI 自带一组预定义主题，你可以在 Gemini CLI 内使用 /theme命令列出它们：

• Dark themes：ANSI、 Atom One、Ayu、Default、 Dracula、 GitHub
• Light themes: ANSI Light、 Ayu Light、 Default Light、 GitHub Light、 Google Code、 Xcode

3.6.2 自定义主题

在你的用户、项目或系统 settings.json文件中添加一个 customThemes 块。每个自定义主题都定义为一个具有唯一名称和一组颜色键的对象。例如：

{
  "ui": {
    "customThemes": {
      "MyCustomTheme": {
        "name": "MyCustomTheme",
        "type": "custom",
        "Background": "#181818",
        ...
      }
    }
  }
}

颜色键:

• Background
• Foreground
• LightBlue
• AccentBlue
• AccentPurple
• AccentCyan
• AccentGreen
• AccentYellow
• AccentRed
• Comment
• Gray
• DiffAdded (optional, for added lines in diffs)
• DiffRemoved (optional, for removed lines in diffs)

还可以通过添加一个嵌套的 text 对象来覆盖单个 UI 文本角色，该对象支持键 primary、secondary、link、accent 和response。当提供 text.response 时，它在渲染聊天中的模型响应时会优先于text.primary。

必填属性：

• name（必须与 customThemes 对象中的键匹配，并且为字符串）
• type（必须是字符串 "custom"）
• Background
• Foreground
• LightBlue
• AccentBlue
• AccentPurple
• AccentCyan
• AccentGreen
• AccentYellow
• AccentRed
• Comment
• Gray

对任意颜色值，你可以使用十六进制代码（例如 #FF0000）或标准 CSS 颜色名称（例如 coral、teal、blue）。参见CSS color names获取支持名称的完整列表。

可以通过向 customThemes 对象添加更多条目来定义多个自定义主题。要从文件加载主题，将settings.json 中的 theme 属性设置为主题文件的路径：

{
  "ui": {
    "theme": "/path/to/your/theme.json"
  }
}

主题文件必须是有效的 JSON 文件，并遵循与在 settings.json 中定义的自定义主题相同的结构。

示例 my-theme.json:

{
  "name": "My File Theme",
  "type": "custom",
  "Background": "#282A36",
  "Foreground": "#F8F8F2",
  "LightBlue": "#82AAFF",
  "AccentBlue": "#61AFEF",
  "AccentPurple": "#BD93F9",
  "AccentCyan": "#8BE9FD",
  "AccentGreen": "#50FA7B",
  "AccentYellow": "#F1FA8C",
  "AccentRed": "#FF5555",
  "Comment": "#6272A4",
  "Gray": "#ABB2BF",
  "DiffAdded": "#A6E3A1",
  "DiffRemoved": "#F38BA8",
  "GradientColors": ["#4796E4", "#847ACE", "#C3677F"]
}

注意： 为了安全，Gemini CLI 只会加载位于你的主目录中的主题文件,如果从主目录之外加载主题，将显示警告，并且主题不会被加载，这是为了防止从不受信任的来源加载可能具有恶意的主题文件。

3.7 快捷键

Gemini CLI 随附一组默认键盘快捷键，用于编辑输入、浏览历史以及控制 UI。

基本控制：

动作	快捷键
确认当前选择或选项。	Enter
关闭对话框或取消当前焦点。	Esc
取消当前请求，或在输入为空时退出 CLI。	Ctrl + C
当输入缓冲区为空时退出 CLI。	Ctrl + D

光标移动：

动作	快捷键
将光标移动到行首。	Ctrl + A Home (no Shift, Ctrl)
将光标移动到行尾。	Ctrl + E End (no Shift, Ctrl)
光标上移一行。	Up Arrow (no Shift, Alt, Ctrl, Cmd)
光标下移一行。	Down Arrow (no Shift, Alt, Ctrl, Cmd)
光标左移一个字符。	Left Arrow (no Shift, Alt, Ctrl, Cmd) Ctrl + B
光标右移一个字符。	Right Arrow (no Shift, Alt, Ctrl, Cmd) Ctrl + F
光标左移一个单词。	Ctrl + Left Arrow Alt + Left Arrow Alt + B
光标右移一个单词。	Ctrl + Right Arrow Alt + Right Arrow Alt + F

编辑

动作	快捷键
从光标删除到行尾。	Ctrl + K
从光标删除到行首。	Ctrl + U
清除输入框中的所有文本。	Ctrl + C
删除前一个单词。	Ctrl + Backspace Alt + Backspace Ctrl + W
删除下一个单词。	Ctrl + Delete Alt + Delete
删除左侧字符。	Backspace Ctrl + H
删除右侧字符。	Delete Ctrl + D
撤销最近一次文本编辑。	Ctrl + Z (no Shift)
重做最近一次被撤销的编辑。	Shift + Ctrl + Z

滚动

动作	快捷键
向上滚动内容。	Shift + Up Arrow
向下滚动内容。	Shift + Down Arrow
滚动到顶部。	Ctrl + Home Shift + Home
滚动到底部。	Ctrl + End Shift + End
向上滚动一页。	Page Up
向下滚动一页。	Page Down

历史与搜索

动作	快捷键
显示历史中的上一条记录。	Ctrl + P (no Shift)
显示历史中的下一条记录。	Ctrl + N (no Shift)
开始在历史中反向搜索。	Ctrl + R
提交选中的反向搜索匹配项。	Enter (no Ctrl)
在反向搜索时接受一个建议。	Tab

导航

动作	快捷键
在列表中将选择上移。	Up Arrow (no Shift)
在列表中将选择下移。	Down Arrow (no Shift)
在对话框选项中向上移动。	Up Arrow (no Shift) K (no Shift)
在对话框选项中向下移动。	Down Arrow (no Shift) J (no Shift)

建议与补全

动作	快捷键
接受内联建议。	Tab Enter (no Ctrl)
移动到上一个补全选项。	Up Arrow (no Shift) Ctrl + P (no Shift)
移动到下一个补全选项。	Down Arrow (no Shift) Ctrl + N (no Shift)
展开内联建议。	Right Arrow
折叠内联建议。	Left Arrow

文本输入

动作	快捷键
提交当前提示。	Enter (no Shift, Alt, Ctrl, Cmd)
插入换行但不提交。	Ctrl + Enter Cmd + Enter Alt + Enter Shift + Enter Ctrl + J
在外部编辑器中打开当前提示。	Ctrl + X
从剪贴板粘贴。	Ctrl + V Cmd + V Alt + V

应用控制

动作	快捷键
切换详细错误信息。	F12
切换完整 TODO 列表。	Ctrl + T
显示 IDE 上下文详情。	Ctrl + G
切换 Markdown 渲染。	Alt + M
在备用缓冲区模式下切换复制模式。	Ctrl + S
为工具调用切换 YOLO（自动批准）模式。	Ctrl + Y
循环切换批准模式：default（提示）、auto_edit（自动批准编辑）以及 plan（只读）。	Shift + Tab
在非备用缓冲区模式下，展开高度受限的响应以显示更多行。	Ctrl + S
从 gemini 输入框聚焦到 shell 输入。	Tab (no Shift)
从 shell 输入框聚焦到 Gemini 输入。	Tab
清空终端屏幕并重绘 UI。	Ctrl + L
重启应用。	R

额外的上下文相关快捷键：

• Option+B/F/M (macOS only): 即使你的终端未配置为用 Option 发送 Meta，也会被解释为 Cmd+B/F/M。
• 空提示下输入 !：进入或退出 shell 模式。
• \（在行尾）+ Enter：插入换行而不离开单行模式。
• 快速按两次 Esc：如果输入提示不为空则清空输入提示，否则浏览并回退先前的交互。
• Up Arrow / Down Arrow：当光标位于单行输入的顶部或底部时，在提示历史中向后或向前导航。
• 在选择对话框中按 Number keys (1-9, multi-digit)：直接跳转到编号的单选项，并在输入完整数字后确认。

3.8 小结

本文围绕 Gemini CLI 的交互方式与工程化使用场景，系统梳理了其核心能力与使用模式，包括内置命令体系（/、@、!）、自定义命令机制，以及无头模式在自动化与脚本中的实际用法。

可以看到，Gemini CLI 的设计重点并不只是“对话”，而是如何将上下文、工具执行与模型能力组合起来，服务于真实的开发与运维流程，理解这些命令与机制后，很多重复性的分析、生成与检查工作都可以被快速复用或自动化。希望本文能帮助到大家，感谢阅读，本文完！

---

04 配置与上下文：settings.json / 环境变量 / 参数 / Context Files

Gemini CLI 提供多种方式来配置其行为，包括环境变量、命令行参数和设置文件，配置按以下优先级顺序应用（较低编号会被较高编号覆盖）：

1. 默认值： 应用内硬编码的默认值。
2. 系统默认文件： 系统范围的默认设置，可被其他设置文件覆盖。
3. 用户设置文件： 当前用户的全局设置。
4. 项目设置文件： 项目特定设置。
5. 系统设置文件： 覆盖所有其他设置文件的系统范围设置。
6. 环境变量： 系统范围或会话特定变量，可能从 .env 文件加载。
7. 命令行参数： 启动 CLI 时传入的值。

4.1 配置文件位置

Gemini CLI 使用 JSON 设置文件进行持久化配置，这些文件有四个位置：

【系统默认文件】： 提供一层系统范围的基础默认设置，这些设置的优先级最低，旨在被用户、项目或系统覆盖设置所覆盖。

操作系统	位置
Linux	/etc/gemini-cli/system-defaults.json
Windows	C:\ProgramData\gemini-cli\system-defaults.json
macOS	/Library/Application Support/GeminiCli/system-defaults.json

---

【用户设置文件】：

• 位置： ~/.gemini/settings.json（其中 ~ 是你的主目录）。
• 作用域： 适用于当前用户的所有 Gemini CLI 会话。用户设置会覆盖系统默认设置。

---

【项目设置文件】：

• 位置： 项目根目录中的 .gemini/settings.json。
• 作用域： 仅当从该特定项目运行 Gemini CLI 时适用。项目设置会覆盖用户设置和系统默认设置。

除了项目设置文件之外，项目的 .gemini 目录还可以包含其他与 Gemini CLI 运行相关的项目特定文件，例如：自定义沙箱配置文件（.gemini/sandbox-macos-custom.sb、.gemini/sandbox.Dockerfile等）。

---

【系统设置文件】： 适用于系统上所有用户的所有 Gemini CLI 会话，系统设置作为覆盖项，优先级高于所有其他设置文件。对企业中的系统管理员控制用户的 Gemini CLI 设置可能很有用。

操作系统	位置
Linux	/etc/gemini-cli/settings.json
Windows	C:\ProgramData\gemini-cli\settings.json
macOS	/Library/Application Support/GeminiCli/settings.json

该路径可通过 GEMINI_CLI_SYSTEM_SETTINGS_PATH 环境变量覆盖。

---

关于设置中的环境变量说明： settings.json 和 gemini-extension.json 文件中的字符串值可以使用 $VAR_NAME 或 ${VAR_NAME} 语法引用环境变量，这些变量会在加载设置时自动解析。例如，如果你有一个环境变量 MY_API_TOKEN，你可以在 settings.json 中这样使用它："apiKey": "$MY_API_TOKEN"。此外，每个扩展都可以在其目录中拥有自己的 .env 文件，并会自动加载。

4.2 settings.json 中的可用设置

4.2.1 general

配置项	类型	说明	默认值	需要重启
general.previewFeatures	boolean	启用预览功能（例如预览模型）。	false	否
general.preferredEditor	string	用于打开文件的首选编辑器。	undefined	否
general.vimMode	boolean	启用 Vim 键绑定。	false	否
general.enableAutoUpdate	boolean	启用自动更新。	true	否
general.enableAutoUpdateNotification	boolean	启用更新通知提示。	true	否
general.checkpointing.enabled	boolean	启用会话检查点以便恢复。	false	是
general.enablePromptCompletion	boolean	启用 AI 驱动的提示补全建议（在输入时）。	false	是
general.retryFetchErrors	boolean	在出现 "exception TypeError: fetch failed sending request" 错误时重试。	false	否
general.debugKeystrokeLogging	boolean	启用将按键记录调试日志输出到控制台。	false	否
general.sessionRetention.enabled	boolean	启用自动会话清理。	false	否
general.sessionRetention.maxAge	string	保留会话的最大时长（例如 "30d"、"7d"、"24h"、"1w"）。	undefined	否
general.sessionRetention.maxCount	number	备选方案：要保留的最大会话数量（最新）。	undefined	否
general.sessionRetention.minRetention	string	最短保留期（安全限制）。	"1d"	否

4.2.2 output

配置项	类型	说明	默认值	取值
output.format	enum	CLI 输出格式。	"text"	"text"、"json"

4.2.3 ui

配置项	类型	说明	默认值	需要重启
ui.theme	string	UI 的配色主题。可用选项请参阅 CLI 主题指南。	undefined	否
ui.customThemes	object	自定义主题定义。	{}	否
ui.hideWindowTitle	boolean	隐藏窗口标题栏。	false	是
ui.showStatusInTitle	boolean	在工作阶段，将模型思考状态显示在终端窗口标题中。	false	否
ui.dynamicWindowTitle	boolean	使用当前状态图标更新终端窗口标题	true	否
ui.showHomeDirectoryWarning	boolean	在主目录中运行 CLI 时显示警告。	true	是
ui.hideTips	boolean	隐藏 UI 中的实用提示。	false	否
ui.hideBanner	boolean	隐藏应用横幅。	false	否
ui.hideContextSummary	boolean	隐藏输入框上方的上下文摘要（GEMINI.md、MCP servers）。	false	否
ui.footer.hideCWD	boolean	在页脚隐藏当前工作目录路径。	false	否
ui.footer.hideSandboxStatus	boolean	在页脚隐藏沙箱状态指示器。	false	否
ui.footer.hideModelInfo	boolean	在页脚隐藏模型名称与上下文使用情况。	false	否
ui.footer.hideContextPercentage	boolean	隐藏剩余上下文窗口百分比。	true	否
ui.hideFooter	boolean	从 UI 中隐藏页脚。	false	否
ui.showMemoryUsage	boolean	在 UI 中显示内存使用信息。	false	否
ui.showLineNumbers	boolean	在聊天中显示行号。	true	否
ui.showCitations	boolean	在聊天中显示生成文本的引用。	false	否
ui.showModelInfoInChat	boolean	在聊天中为每个模型轮次显示模型名称。	false	否
ui.useFullWidth	boolean	使用终端的完整宽度进行输出。	true	否
ui.useAlternateBuffer	boolean	为 UI 使用备用屏幕缓冲区，以保留 shell 历史记录。	false	是
ui.incrementalRendering	boolean	启用 UI 的增量渲染（仅在启用 useAlternateBuffer 时支持）。	true	是
ui.customWittyPhrases	array	操作加载期间显示的自定义俏皮短语。	[]	否
ui.accessibility.enableLoadingPhrases	boolean	在操作期间启用加载短语。	true	是
ui.accessibility.screenReader	boolean	以纯文本渲染输出，使其对屏幕阅读器更友好。	false	是

4.2.4 ide

配置项	类型	说明	默认值	需要重启
ide.enabled	boolean	启用 IDE 集成模式。	false	是
ide.hasSeenNudge	boolean	用户是否已看到 IDE 集成提示。	false	否

4.2.5 privacy

配置项	类型	说明	默认值	需要重启
privacy.usageStatisticsEnabled	boolean	启用使用统计信息收集。	true	是

4.2.6 model

配置项	类型	说明	默认值	需要重启
model.name	string	用于对话的 Gemini 模型。	undefined	否
model.maxSessionTurns	number	会话中要保留的 user / model / tool 轮次最大数量，-1 表示无限制。	-1	否
model.summarizeToolOutput	object	启用或禁用工具输出摘要，并为每个工具配置 token 预算（目前仅 run_shell_command 支持）。	undefined	否
model.compressionThreshold	number	触发上下文压缩的上下文使用比例阈值（例如 0.2、0.3）。	0.5	是
model.skipNextSpeakerCheck	boolean	跳过下一次发言者检查。	true	否

4.2.7 modelConfigs

配置项	类型	说明	默认值
modelConfigs.aliases	object	模型配置的命名预设。可代替模型名称使用，并可通过 extends 从其他别名继承。	内置一组预定义别名（见下方示例）
modelConfigs.customAliases	object	自定义的模型配置命名预设，会与内置别名合并并覆盖同名项。	{}
modelConfigs.customOverrides	array	自定义模型配置覆盖项，会与内置覆盖项合并并追加。	[]
modelConfigs.overrides	array	基于 model（或 alias）匹配应用的配置覆盖项，使用最具体匹配。	[]

modelConfigs.aliases 示例

   {
     "base": {
       "modelConfig": {
         "generateContentConfig": {
           "temperature": 0,
           "topP": 1
         }
       }
     },
     "chat-base": {
       "extends": "base",
       "modelConfig": {
         "generateContentConfig": {
           "thinkingConfig": {
             "includeThoughts": true
           },
           "temperature": 1,
           "topP": 0.95,
           "topK": 64
         }
       }
     },
     "chat-base-2.5": {
       "extends": "chat-base",
       "modelConfig": {
         "generateContentConfig": {
           "thinkingConfig": {
             "thinkingBudget": 8192
           }
         }
       }
     },
     "chat-base-3": {
       "extends": "chat-base",
       "modelConfig": {
         "generateContentConfig": {
           "thinkingConfig": {
             "thinkingLevel": "HIGH"
           }
         }
       }
     },
     "gemini-3-pro-preview": {
       "extends": "chat-base-3",
       "modelConfig": {
         "model": "gemini-3-pro-preview"
       }
     },
     "gemini-3-flash-preview": {
       "extends": "chat-base-3",
       "modelConfig": {
         "model": "gemini-3-flash-preview"
       }
     },
     "gemini-2.5-pro": {
       "extends": "chat-base-2.5",
       "modelConfig": {
         "model": "gemini-2.5-pro"
       }
     },
     "gemini-2.5-flash": {
       "extends": "chat-base-2.5",
       "modelConfig": {
         "model": "gemini-2.5-flash"
       }
     },
     "gemini-2.5-flash-lite": {
       "extends": "chat-base-2.5",
       "modelConfig": {
         "model": "gemini-2.5-flash-lite"
       }
     },
     "gemini-2.5-flash-base": {
       "extends": "base",
       "modelConfig": {
         "model": "gemini-2.5-flash"
       }
     },
     "classifier": {
       "extends": "base",
       "modelConfig": {
         "model": "gemini-2.5-flash-lite",
         "generateContentConfig": {
           "maxOutputTokens": 1024,
           "thinkingConfig": {
             "thinkingBudget": 512
           }
         }
       }
     },
     "prompt-completion": {
       "extends": "base",
       "modelConfig": {
         "model": "gemini-2.5-flash-lite",
         "generateContentConfig": {
           "temperature": 0.3,
           "maxOutputTokens": 16000,
           "thinkingConfig": {
             "thinkingBudget": 0
           }
         }
       }
     },
     "edit-corrector": {
       "extends": "base",
       "modelConfig": {
         "model": "gemini-2.5-flash-lite",
         "generateContentConfig": {
           "thinkingConfig": {
             "thinkingBudget": 0
           }
         }
       }
     },
     "summarizer-default": {
       "extends": "base",
       "modelConfig": {
         "model": "gemini-2.5-flash-lite",
         "generateContentConfig": {
           "maxOutputTokens": 2000
         }
       }
     },
     "summarizer-shell": {
       "extends": "base",
       "modelConfig": {
         "model": "gemini-2.5-flash-lite",
         "generateContentConfig": {
           "maxOutputTokens": 2000
         }
       }
     },
     "web-search": {
       "extends": "gemini-2.5-flash-base",
       "modelConfig": {
         "generateContentConfig": {
           "tools": [
             {
               "googleSearch": {}
             }
           ]
         }
       }
     },
     "web-fetch": {
       "extends": "gemini-2.5-flash-base",
       "modelConfig": {
         "generateContentConfig": {
           "tools": [
             {
               "urlContext": {}
             }
           ]
         }
       }
     },
     "web-fetch-fallback": {
       "extends": "gemini-2.5-flash-base",
       "modelConfig": {}
     },
     "loop-detection": {
       "extends": "gemini-2.5-flash-base",
       "modelConfig": {}
     },
     "loop-detection-double-check": {
       "extends": "base",
       "modelConfig": {
         "model": "gemini-2.5-pro"
       }
     },
     "llm-edit-fixer": {
       "extends": "gemini-2.5-flash-base",
       "modelConfig": {}
     },
     "next-speaker-checker": {
       "extends": "gemini-2.5-flash-base",
       "modelConfig": {}
     },
     "chat-compression-3-pro": {
       "modelConfig": {
         "model": "gemini-3-pro-preview"
       }
     },
     "chat-compression-3-flash": {
       "modelConfig": {
         "model": "gemini-3-flash-preview"
       }
     },
     "chat-compression-2.5-pro": {
       "modelConfig": {
         "model": "gemini-2.5-pro"
       }
     },
     "chat-compression-2.5-flash": {
       "modelConfig": {
         "model": "gemini-2.5-flash"
       }
     },
     "chat-compression-2.5-flash-lite": {
       "modelConfig": {
         "model": "gemini-2.5-flash-lite"
       }
     },
     "chat-compression-default": {
       "modelConfig": {
         "model": "gemini-2.5-pro"
       }
     }
   }

4.3 agents

配置项	类型	说明	默认值	需要重启
agents.overrides	object	覆盖特定 agent 的设置，例如禁用该 agent、设置自定义模型配置或运行配置。	{}	是

4.4 context

配置项	类型	说明	默认值	需要重启
context.fileName	string / string[]	要加载到内存中的上下文文件名，可为单个字符串或字符串数组。	undefined	否
context.importFormat	string	导入 memory 时使用的格式。	undefined	否
context.discoveryMaxDirs	number	搜索 memory 的最大目录数量。	200	否
context.includeDirectories	array	要包含在工作区上下文中的附加目录，缺失的目录将被跳过并给出警告。	[]	否
context.loadMemoryFromIncludeDirectories	boolean	控制 /memory refresh 如何加载 GEMINI.md 文件。	false	否
context.fileFiltering.respectGitIgnore	boolean	搜索时遵循 .gitignore 文件。	true	是
context.fileFiltering.respectGeminiIgnore	boolean	搜索时遵循 .geminiignore 文件。	true	是
context.fileFiltering.enableRecursiveFileSearch	boolean	在提示中补全 @ 引用时启用递归文件搜索功能。	true	是
context.fileFiltering.enableFuzzySearch	boolean	搜索文件时启用模糊搜索。	true	是

4.5 tools

配置项	类型	说明	默认值	需要重启
tools.sandbox	boolean / string	沙箱执行环境；可用 boolean 启用/禁用，或提供沙箱配置文件路径。	undefined	是
tools.shell.enableInteractiveShell	boolean	使用 node-pty 提供交互式 shell 体验（仍支持回退到 child_process）。	true	是
tools.shell.pager	string	用于 shell 输出的分页器命令。	"cat"	否
tools.shell.showColor	boolean	在 shell 输出中显示颜色。	false	否
tools.shell.inactivityTimeout	number	无输出情况下允许 shell 命令运行的最长时间（秒）。	300	否
tools.shell.enableShellOutputEfficiency	boolean	启用 shell 输出效率优化以提升性能。	true	否
tools.autoAccept	boolean	自动接受并执行被认为安全的工具调用（如只读操作）。	false	否
tools.core	array	使用 allowlist 限制内置工具集合（匹配语义与 tools.allowed 镜像）。	undefined	是
tools.allowed	array	可绕过确认对话框的工具名称列表（受信任命令）。	undefined	是
tools.exclude	array	从发现中排除的工具名称。	undefined	是
tools.discoveryCommand	string	用于工具发现的命令。	undefined	是
tools.callCommand	string	调用已发现工具的自定义 shell 命令（stdin 读 JSON，stdout 输出 JSON）。	undefined	是
tools.useRipgrep	boolean	使用 ripgrep 进行文件内容搜索以获得更高性能。	true	否
tools.enableToolOutputTruncation	boolean	启用对较大工具输出的截断。	true	是
tools.truncateToolOutputThreshold	number	工具输出超过该字符数时进行截断，-1 表示禁用。	4000000	是
tools.truncateToolOutputLines	number	截断工具输出时要保留的行数。	1000	是
tools.disableLLMCorrection	boolean	禁用编辑工具的基于 LLM 的错误修正。	true	是
tools.enableHooks	boolean	启用 hooks system 实验（禁用后将完全停用）。	true	是

4.6 mcp

配置项	类型	说明	默认值	需要重启
mcp.serverCommand	string	用于启动 MCP server 的命令。	undefined	是
mcp.allowed	array	允许的 MCP servers 列表。	undefined	是
mcp.excluded	array	排除的 MCP servers 列表。	undefined	是

4.7 useWriteTodos

配置项	类型	说明	默认值
useWriteTodos	boolean	启用 write_todos 工具。	true

4.8 security

配置项	类型	说明	默认值	需要重启
security.disableYoloMode	boolean	禁用 YOLO mode（即使通过 flag 启用）。	false	是
security.enablePermanentToolApproval	boolean	在工具确认对话框中启用 “Allow for all future sessions” 选项。	false	否
security.blockGitExtensions	boolean	阻止从 Git 安装和加载扩展。	false	是
security.folderTrust.enabled	boolean	用于跟踪是否启用 Folder trust 的设置。	false	是
security.environmentVariableRedaction.allowed	array	始终允许（绕过脱敏）的环境变量。	[]	是
security.environmentVariableRedaction.blocked	array	始终脱敏的环境变量。	[]	是
security.environmentVariableRedaction.enabled	boolean	启用对可能包含 secrets 的环境变量进行脱敏。	false	是
security.auth.selectedType	string	当前选择的认证类型。	undefined	是
security.auth.enforcedType	string	要求的认证类型；不匹配时将提示重新认证。	undefined	是
security.auth.useExternal	boolean	是否使用外部认证流程。	undefined	是

4.9 advanced

配置项	类型	说明	默认值	需要重启
advanced.autoConfigureMemory	boolean	自动配置 Node.js 内存限制。	false	是
advanced.dnsResolutionOrder	string	DNS 解析顺序。	undefined	是
advanced.excludedEnvVars	array	要从项目上下文中排除的环境变量。	["DEBUG", "DEBUG_MODE"]	否
advanced.bugCommand	object	bug report 命令的配置。	undefined	否

4.10 experimental

配置项	类型	说明	默认值	需要重启
experimental.enableAgents	boolean	启用本地和远程 subagents（实验性，对 subagents 使用 YOLO mode）。	false	是
experimental.extensionManagement	boolean	启用扩展管理功能。	true	是
experimental.extensionConfig	boolean	启用请求与获取扩展设置。	false	是
experimental.enableEventDrivenScheduler	boolean	在 CLI 会话中启用事件驱动调度器。	true	是
experimental.extensionReloading	boolean	在 CLI 会话中启用扩展加载/卸载。	false	是
experimental.jitContext	boolean	启用 Just-In-Time（JIT）上下文加载。	false	是
experimental.skills	boolean	启用 Agent Skills（实验性）。	false	是
experimental.codebaseInvestigatorSettings.enabled	boolean	启用 Codebase Investigator agent。	true	是
experimental.codebaseInvestigatorSettings.maxNumTurns	number	Codebase Investigator agent 的最大轮次数。	10	是
experimental.codebaseInvestigatorSettings.maxTimeMinutes	number	Codebase Investigator agent 的最长时间（分钟）。	3	是
experimental.codebaseInvestigatorSettings.thinkingBudget	number	Codebase Investigator agent 的思考预算。	8192	是
experimental.codebaseInvestigatorSettings.model	string	Codebase Investigator agent 使用的模型。	"auto"	是
experimental.useOSC52Paste	boolean	使用 OSC 52 序列进行粘贴（适用于远程会话）。	false	否
experimental.cliHelpAgentSettings.enabled	boolean	启用 CLI Help Agent。	true	是
experimental.plan	boolean	启用规划功能（Plan Mode 和 tools）。	false	是

4.11 skills

配置项	类型	说明	默认值	需要重启
skills.disabled	array	已禁用的 skills 列表。	[]	是

4.12 hooksConfig

配置项	类型	说明	默认值
hooksConfig.enabled	boolean	hooks system 的规范开关；禁用时不会执行任何 hooks。	true
hooksConfig.disabled	array	应被禁用的 hook 名称（命令）列表；即使已配置也不会执行。	[]
hooksConfig.notifications	boolean	当 hooks 执行时显示可视化指示器。	true

4.13 hooks

配置项	类型	说明	默认值
hooks.BeforeTool	array	在工具执行前运行的 hooks；可拦截、校验或修改工具调用。	[]
hooks.AfterTool	array	在工具执行后运行的 hooks；可处理结果、记录输出或触发后续动作。	[]
hooks.BeforeAgent	array	在 agent loop 开始前运行的 hooks；可设置上下文或初始化资源。	[]
hooks.AfterAgent	array	在 agent loop 完成后运行的 hooks；可执行清理或总结结果。	[]
hooks.Notification	array	在通知事件（errors、warnings、info）上运行的 hooks；可用于日志或告警。	[]
hooks.SessionStart	array	在会话开始时运行的 hooks；可初始化会话相关资源或状态。	[]
hooks.SessionEnd	array	在会话结束时运行的 hooks；可执行清理或持久化会话数据。	[]
hooks.PreCompress	array	在聊天历史压缩前运行的 hooks；可在压缩前备份或分析对话。	[]
hooks.BeforeModel	array	在发起 LLM 请求前运行的 hooks；可修改 prompts、注入上下文或控制模型参数。	[]
hooks.AfterModel	array	在 LLM 响应之后执行的 hooks；可处理输出、提取信息或记录交互。	[]
hooks.BeforeToolSelection	array	在选择工具之前执行的 hooks；可用于动态过滤或优先排序可用工具。	[]

4.14 admin

配置项	类型	说明	默认值
admin.secureModeEnabled	boolean	若为 true，则禁止使用 YOLO 模式。	false
admin.extensions.enabled	boolean	若为 false，则禁止安装或使用扩展。	true
admin.mcp.enabled	boolean	若为 false，则禁止使用 MCP 服务器。	true
admin.skills.enabled	boolean	若为 false，则禁止使用 agent skills。	true

4.15 mcpServers

配置与一个或多个 Model-Context Protocol (MCP) 服务器的连接，用于发现并使用自定义工具。Gemini CLI 会尝试连接到每个已配置的 MCP 服务器以发现可用工具。如果多个 MCP 服务器
暴露了同名工具，则工具名称会带上你在配置中定义的服务器别名作为前缀（例如，
serverAlias__actualToolName）以避免冲突。

注意：为了兼容性，系统可能会从 MCP 工具定义中移除某些 schema 属性，必须至少提供 command、url 或 httpUrl 之一，如果指定了多个，优先级顺序为先 httpUrl，再 url，最后 command。

配置项	类型	说明	默认值
mcpServers.<SERVER_NAME>	object	指定名称的 MCP 服务器参数配置。	—
mcpServers.<SERVER_NAME>.command	string	通过标准 I/O 启动 MCP 服务器的命令。	undefined
mcpServers.<SERVER_NAME>.args	string[]	传递给启动命令的参数。	undefined
mcpServers.<SERVER_NAME>.env	object	为服务器进程设置的环境变量。	undefined
mcpServers.<SERVER_NAME>.cwd	string	启动服务器时使用的工作目录。	undefined
mcpServers.<SERVER_NAME>.url	string	使用 Server-Sent Events（SSE）通信的 MCP 服务器 URL。	undefined
mcpServers.<SERVER_NAME>.httpUrl	string	使用可流式 HTTP 通信的 MCP 服务器 URL。	undefined
mcpServers.<SERVER_NAME>.headers	object	随请求发送到 url 或 httpUrl 的 HTTP 头映射。	undefined
mcpServers.<SERVER_NAME>.timeout	number	MCP 服务器请求的超时时间（毫秒）。	undefined
mcpServers.<SERVER_NAME>.trust	boolean	信任该服务器并绕过所有工具调用确认。	undefined
mcpServers.<SERVER_NAME>.description	string	服务器的简要描述，用于展示用途。	undefined
mcpServers.<SERVER_NAME>.includeTools	string[]	从该 MCP 服务器中包含的工具名称列表（白名单）；未指定则启用全部工具。	undefined
mcpServers.<SERVER_NAME>.excludeTools	string[]	从该 MCP 服务器中排除的工具名称列表；优先级高于 includeTools。	undefined

4.16 telemetry

为 Gemini CLI 配置日志记录与指标采集。

属性	类型	说明	取值 / 备注
enabled	boolean	是否启用 telemetry。	—
target	string	telemetry 的采集目标位置。	local / gcp
otlpEndpoint	string	OTLP Exporter 的端点。	—
otlpProtocol	string	OTLP Exporter 的协议。	grpc / http
logPrompts	boolean	是否在日志中包含用户 prompt 的内容。	—
outfile	string	当 target 为 local 时，telemetry 写入的文件路径。	—
useCollector	boolean	是否使用外部 OTLP collector。	—

4.17 settings.json 示例

下面是一个具有嵌套结构的 settings.json 文件示例，该结构自v0.3.0 起提供：

{
  "general": {
    "vimMode": true,
    "preferredEditor": "code",
    "sessionRetention": {
      "enabled": true,
      "maxAge": "30d",
      "maxCount": 100
    }
  },
  "ui": {
    "theme": "GitHub",
    "hideBanner": true,
    "hideTips": false,
    "customWittyPhrases": [
      "You forget a thousand things every day. Make sure this is one of ’em",
      "Connecting to AGI"
    ]
  },
  "tools": {
    "sandbox": "docker",
    "discoveryCommand": "bin/get_tools",
    "callCommand": "bin/call_tool",
    "exclude": ["write_file"]
  },
  "mcpServers": {
    "mainServer": {
      "command": "bin/mcp_server.py"
    },
    "anotherServer": {
      "command": "node",
      "args": ["mcp_server.js", "--verbose"]
    }
  },
  "telemetry": {
    "enabled": true,
    "target": "local",
    "otlpEndpoint": "http://localhost:4317",
    "logPrompts": true
  },
  "privacy": {
    "usageStatisticsEnabled": true
  },
  "model": {
    "name": "gemini-1.5-pro-latest",
    "maxSessionTurns": 10,
    "summarizeToolOutput": {
      "run_shell_command": {
        "tokenBudget": 100
      }
    }
  },
  "context": {
    "fileName": ["CONTEXT.md", "GEMINI.md"],
    "includeDirectories": ["path/to/dir1", "~/path/to/dir2", "../path/to/dir3"],
    "loadFromIncludeDirectories": true,
    "fileFiltering": {
      "respectGitIgnore": false
    }
  },
  "advanced": {
    "excludedEnvVars": ["DEBUG", "DEBUG_MODE", "NODE_ENV"]
  }
}

4.18 命令历史记录

CLI 会保留你运行过的 shell 命令历史记录。为避免在不同项目之间发生冲突，该历史记录会存储在你用户主目录下的项目专用目录中。

位置： ~/.gemini/tmp/<project_hash>/shell_history

• <project_hash> 是根据你项目的根路径生成的唯一标识符。
• 历史记录存储在名为 shell_history 的文件中。

4.19 环境变量

环境变量是配置应用程序的常见方式，尤其适用于API key 等敏感信息，或用于可能因环境不同而变化的设置，CLI 会自动从 .env 文件加载环境变量，加载顺序为：

Step 1. 当前工作目录中的 .env 文件。

Step 2. 若未找到，则向上在父目录中搜索，直到找到
.env 文件或到达项目根目录（由 .git 文件夹标识）或
主目录。

Step 3. 若仍未找到，则查找 ~/.env（位于用户主目录中）。

环境变量排除： 某些环境变量（如 DEBUG 和DEBUG_MODE）会被自动排除，不从项目 .env
文件中加载，以防干扰 gemini-cli 的行为。来自.gemini/.env 文件的变量永远不会被排除。你可以使用settings.json 文件中的 advanced.excludedEnvVars 设置来自定义此行为。

4.19.1 变量参数

环境变量	说明	备注 / 示例
GEMINI_API_KEY	你的 Gemini API key，用于访问 Gemini API。	在 ~/.bashrc / ~/.zshrc 或 .env 中设置
GEMINI_MODEL	指定默认使用的 Gemini 模型，覆盖内置默认值。	export GEMINI_MODEL="gemini-3-flash-preview"
GOOGLE_API_KEY	Google Cloud API key；express 模式下使用 Vertex AI 所必需。	export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"
GOOGLE_CLOUD_PROJECT	Google Cloud Project ID；使用 Code Assist 或 Vertex AI 所必需。	export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
GOOGLE_APPLICATION_CREDENTIALS	Google Application Credentials JSON 文件路径。	export GOOGLE_APPLICATION_CREDENTIALS="/path/to/credentials.json"
OTLP_GOOGLE_CLOUD_PROJECT	Telemetry 使用的 Google Cloud Project ID。	export OTLP_GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
GEMINI_TELEMETRY_ENABLED	启用 telemetry（true / 1 启用，其余视为禁用）。	覆盖 telemetry.enabled
GEMINI_TELEMETRY_TARGET	设置 telemetry 目标位置。	local / gcp，覆盖 telemetry.target
GEMINI_TELEMETRY_OTLP_ENDPOINT	设置 telemetry 的 OTLP 端点。	覆盖 telemetry.otlpEndpoint
GEMINI_TELEMETRY_OTLP_PROTOCOL	设置 telemetry 的 OTLP 协议。	grpc / http，覆盖 telemetry.otlpProtocol
GEMINI_TELEMETRY_LOG_PROMPTS	是否记录用户 prompt 到 telemetry。	覆盖 telemetry.logPrompts
GEMINI_TELEMETRY_OUTFILE	当目标为 local 时写入 telemetry 的文件路径。	覆盖 telemetry.outfile
GEMINI_TELEMETRY_USE_COLLECTOR	是否使用外部 OTLP collector。	覆盖 telemetry.useCollector
GOOGLE_CLOUD_LOCATION	Google Cloud Project 的区域（非 express 模式下 Vertex AI 必需）。	export GOOGLE_CLOUD_LOCATION="us-central1"
GEMINI_SANDBOX	settings.json 中 sandbox 的替代方案。	true / false / docker / podman / 自定义命令
GEMINI_SYSTEM_MD	用 Markdown 文件内容替换内置 system prompt。	true 使用 ./.gemini/system.md
GEMINI_WRITE_SYSTEM_MD	将当前内置 system prompt 写入文件。	true 写入 ./.gemini/system.md
SEATBELT_PROFILE	macOS 专用：切换 sandbox-exec profile。	permissive-open / strict / 自定义
DEBUG / DEBUG_MODE	启用详细 debug 日志。	建议在 .gemini/.env 中设置
NO_COLOR	禁用 CLI 中的所有彩色输出。	任意值
CLI_TITLE	自定义 CLI 窗口标题。	字符串
CODE_ASSIST_ENDPOINT	指定 Code Assist server 的端点。	用于开发与测试

4.19.2 环境变量脱敏

为防止敏感信息意外泄露，Gemini CLI 在执行工具（例如shell 命令）时，会自动从环境变量中打码潜在的秘密信息。这种“尽力而为”的打码适用于从系统继承的变量或从 .env 文件加载的变量。

默认打码规则：

• 按名称： 若变量名包含敏感词，如 TOKEN、SECRET、PASSWORD、KEY、AUTH``CREDENTIAL、PRIVATE 或 CERT，则会被打码。
• 按值： 若变量值匹配已知的秘密模式，则会被打码，例如：私钥（RSA、OpenSSH、PGP 等）、证书、包含凭据的 URL、API key 与 token（GitHub、Google、AWS、Stripe、Slack 等）
• 特定黑名单： 某些变量如 CLIENT_ID、DB_URI、DATABASE_URL 和 CONNECTION_STRING 默认总会被打码。

白名单（永不打码）：

• 常见系统变量（例如 PATH、HOME、USER、SHELL、TERM、LANG）。
• 以 GEMINI_CLI_ 开头的变量。
• GitHub Action 特有变量。

你可以在 settings.json 文件中自定义该行为：

• security.allowedEnvironmentVariables: 一个变量名列表，用于
  永不 打码，即使它们匹配敏感模式。
• security.blockedEnvironmentVariables: 一个变量名列表，用于
  总是 打码，即使它们不匹配敏感模式。

{
  "security": {
    "allowedEnvironmentVariables": ["MY_PUBLIC_KEY", "NOT_A_SECRET_TOKEN"],
    "blockedEnvironmentVariables": ["INTERNAL_IP_ADDRESS"]
  }
}

4.20 命令行参数

在运行 CLI 时直接传入的参数可以覆盖该会话中的其他配置。

• --model <model_name> (-m <model_name>):

  • 指定本次会话使用的 Gemini model。
  • 示例：npm start -- --model gemini-3-pro-preview

• --prompt <your_prompt> (-p <your_prompt>):

  • 用于将 prompt 直接传给命令。这会以非交互模式调用 Gemini CLI。
  • 对于脚本示例，使用 --output-format json 标志以获得结构化输出。

• --prompt-interactive <your_prompt> (-i <your_prompt>):

  • 启动交互会话，并将所提供的 prompt 作为初始输入。
  • prompt 会在交互会话中处理，而不是在此之前。
  • 当从 stdin 通过管道传入输入时不可用。
  • 示例：gemini -i "explain this code"

• --output-format <format>:

  • 描述： 指定非交互模式下 CLI 输出的格式。
  • 取值：
    • text:（默认）标准的人类可读输出。
    • json: 机器可读的 JSON 输出。
    • stream-json: 以流式方式输出 JSON，实时发出事件。
  • 注意： 对于结构化输出与脚本编写，请使用 --output-format json 或 --output-format stream-json 标志。

• --sandbox (-s): 为本次会话启用 sandbox 模式。

• --debug (-d): 为本次会话启用 debug 模式，提供更详细的输出。按 F12 打开debug 控制台以查看额外日志。

• --help（或 -h）: 显示命令行参数的帮助信息。

• --yolo: 启用 YOLO 模式，该模式会自动批准所有工具调用。

• --approval-mode <mode>:设置工具调用的批准模式。可用模式：

  • default: 每次工具调用都提示批准（默认行为）

  • auto_edit: 自动批准编辑工具（replace、write_file），其余仍提示

  • yolo: 自动批准所有工具调用（等同于 --yolo）

  • plan: 工具调用只读模式（需要启用实验性 planning）。

    注意： 该模式目前仍在开发中，尚未完全
    可用。

  • 不能与 --yolo 同时使用。新统一方式请使用 --approval-mode=yolo 代替--yolo。

  • 示例：gemini --approval-mode auto_edit

• --allowed-tools <tool1,tool2,...>:

  • 一个以逗号分隔的工具名称列表，将绕过确认对话框。
  • 示例：gemini --allowed-tools "ShellTool(git status)"

• --extensions <extension_name ...> (-e <extension_name ...>):

  • 指定本次会话要使用的扩展列表。若未提供，则使用所有可用扩展。
  • 使用特殊术语 gemini -e none 可禁用所有扩展。
  • 示例：gemini -e my-extension -e my-other-extension

• --list-extensions (-l): 列出所有可用扩展并退出。

• --resume [session_id] (-r [session_id]):

  • 恢复先前的聊天会话。对最近的会话使用 “latest”，提供会话索引编号，或提供完整的会话UUID。
  • 若未提供 session_id，则默认为 “latest”。
  • 示例：gemini --resume 5 或 gemini --resume latest 或 gemini --resume a1b2c3d4-e5f6-7890-abcd-ef1234567890 或 gemini --resume

• --list-sessions:

  • 列出当前项目的所有可用聊天会话并退出。
  • 显示会话索引、日期、消息数量，以及第一条用户消息的预览。
  • 示例：gemini --list-sessions

• --delete-session <identifier>:

  • 通过索引编号或完整会话 UUID 删除特定聊天会话。
  • 请先使用 --list-sessions 查看可用会话、它们的索引与UUID。
  • 示例：gemini --delete-session 3 或 gemini --delete-session a1b2c3d4-e5f6-7890-abcd-ef1234567890

• --include-directories <dir1,dir2,...>:

  • 为多目录支持包含额外目录到工作区。
  • 可以多次指定或使用逗号分隔的值。
  • 最多可添加 5 个目录。
  • 示例：--include-directories /path/to/project1,/path/to/project2 或
    --include-directories /path/to/project1 --include-directories /path/to/project2

• --screen-reader: 启用屏幕阅读器模式，通过调整 TUI 以更好地兼容屏幕阅读器。

• --version: 显示 CLI 的版本。

• --experimental-acp: 以 ACP 模式启动 agent。

• --allowed-mcp-server-names: 允许的 MCP server 名称。

• --fake-responses: 指向包含伪造 model 响应的文件路径，用于测试。

• --record-responses: 指向用于记录 model 响应的文件路径，用于测试。

4.21 上下文文件（Context Files）

Context files 虽然并不严格用于配置 CLI 的 _behavior_，但它们（默认使用 GEMINI.md，也可通过 context.fileName 设置配置）对于配置提供给 Gemini model 的 _instructional context_（也称为“memory”）至关重要。这个强大功能允许你提供项目专用说明、编码风格指南或任何相关背景信息，使 AI 的响应更贴合且更准确地满足你的需求，CLI 还包含 UI 元素，例如页脚中的指示器显示已加载的 context files 数量，以便让你了解当前激活的context。

用途： 这些 Markdown 文件包含你希望 Gemini model 在交互期间知晓的说明、指南或 context，系统被设计为以分层方式管理此 instructional context。

4.21.1 示例 context file 内容

下面是一个概念性示例（例如 GEMINI.md），展示 TypeScript项目根目录中的 context file 可能包含的内容：

## Project: My Awesome TypeScript Library

### General Instructions:

- When generating new TypeScript code, please follow the existing coding style.
- Ensure all new functions and classes have JSDoc comments.
- Prefer functional programming paradigms where appropriate.
- All code should be compatible with TypeScript 5.0 and Node.js 20+.

### Coding Style:

- Use 2 spaces for indentation.
- Interface names should be prefixed with `I` (e.g., `IUserService`).
- Private class members should be prefixed with an underscore (`_`).
- Always use strict equality (`===` and `!==`).

### Specific Component: `src/api/client.ts`

- This file handles all outbound API requests.
- When adding new API call functions, ensure they include robust error handling
  and logging.
- Use the existing `fetchWithRetry` utility for all GET requests.

### Regarding Dependencies:

- Avoid introducing new external dependencies unless absolutely necessary.
- If a new dependency is required, please state the reason.

这个示例展示了你如何提供通用的项目 context、特定的编码规范，甚至关于特定文件或组件的说明。你的 context files 越相关且精确，AI 就越能更好地协助你。强烈建议使用项目专用 context files 来建立约定与 context。

---

分层加载与优先级： CLI 通过从多个位置加载 context files（例如 GEMINI.md）来实现精巧的分层 memory 系统。该列表中越靠下（越具体）的文件内容通常会覆盖或补充越靠上（越通用）的文件内容。可使用 /memory show 命令检查具体的拼接顺序与最终 context。典型加载顺序为：

1. 全局 context file：
   • 位置：~/.gemini/<configured-context-filename>（例如
     用户主目录中的 ~/.gemini/GEMINI.md）。
   • 作用域：为所有项目提供默认说明。
2. 项目根目录及祖先目录的 context files：
   • 位置：CLI 会在
     当前工作目录中搜索配置的 context file，然后在每个父目录中继续搜索，直到
     项目根目录（由 .git 文件夹标识）或用户主目录。
   • 作用域：为整个项目或其重要部分提供相关 context。
3. 子目录 context files（上下文/本地）：
   • 位置：CLI 还会在
     当前工作目录 下方 的子目录中扫描配置的 context file（遵循 node_modules、.git 等常见
     忽略模式）。该搜索的广度默认限制为 200 个目录，但可通过 settings.json 中的
     context.discoveryMaxDirs 设置进行配置。
   • 作用域：为特定组件、模块或子区域提供高度具体的说明。

拼接与 UI 指示： 所有找到的 context files 的内容会被拼接（并带有分隔符以标明其来源与路径）并作为 system prompt 的一部分提供给 Gemini model。CLI 页脚会显示已加载 context files 的数量，让你能快速直观地了解当前激活的 instructional context。

导入内容： 你可以使用 @path/to/file.md 语法导入其他 Markdown 文件，从而模块化你的 context files。更多细节请参见

用于 memory 管理的命令：

• 使用 /memory refresh 强制重新扫描并重新加载所有 context files（来自所有已配置位置）。这会更新 AI 的 instructional context。
• 使用 /memory show 显示当前加载的 combined instructional context，以便你验证层级与正在被 AI 使用的内容。

通过理解并利用这些配置层与 context files 的分层特性，你可以有效管理 AI 的 memory，并将
Gemini CLI 的响应更好地定制为符合你的特定需求与项目。

4.22 沙箱

Gemini CLI 可以在沙箱环境中执行潜在不安全的操作（例如 shell 命令和文件修改），以保护你的系统。

Sandboxing 默认禁用，但你可以通过以下几种方式启用：

• 使用 --sandbox 或 -s 标志。
• 设置 GEMINI_SANDBOX 环境变量。
• 在使用 --yolo 或 --approval-mode=yolo 时默认启用 sandbox。

默认情况下，它使用预构建的 gemini-cli-sandbox Docker image。

对于项目专用的 sandboxing 需求，你可以在项目根目录创建自定义 Dockerfile，路径为.gemini/sandbox.Dockerfile。该 Dockerfile 可以基于基础 sandbox image：

FROM gemini-cli-sandbox

## Add your custom dependencies or configurations here
## For example:
## RUN apt-get update && apt-get install -y some-package
## COPY ./my-config /app/my-config

当存在 .gemini/sandbox.Dockerfile 时，你可以在运行 Gemini CLI 时使用 BUILD_SANDBOX环境变量来自动构建自定义sandbox image：

BUILD_SANDBOX=1 gemini -s

4.23 使用统计

为了帮助我们改进 Gemini CLI，我们会收集匿名化的 usage statistics。该数据帮助我们了解 CLI 的使用方式、识别常见问题，并确定新功能的优先级。

我们收集的内容：

• 工具调用： 我们记录被调用的工具名称、它们是否成功或失败，以及执行耗时。我们不收集传递给工具的参数或任何返回数据。
• API 请求： 我们记录每次请求所使用的 Gemini model、请求耗时，以及是否成功。我们不收集prompts 或响应的内容。
• 会话信息： 我们收集有关 CLI 配置的信息，例如启用的工具与 approval mode。

我们不收集的内容：

• 个人身份信息（PII）： 我们不收集任何个人信息，例如你的姓名、邮箱地址或 API key。
• Prompt 与响应内容： 我们不会记录 prompts 的内容或 Gemini model 的响应内容。
• 文件内容： 我们不会记录由 CLI 读取或写入的任何文件内容。

如何选择退出：

你可以随时通过将 settings.json 文件中 privacy 类别下的usageStatisticsEnabled 属性设置为 false 来选择退出 usage statistics 收集：

{
  "privacy": {
    "usageStatisticsEnabled": false
  }
}

4.24 小结

到这里，Gemini CLI 的整体配置体系就完整串起来了，理解它的关键，并不是记住所有配置项，而是掌握**“在什么场景下，用哪种方式配置”**，读者们可以按下面这个思路来使用 Gemini CLI：

---

一、长期稳定的偏好，用 settings.json

如果某个配置 每天都会用、希望一直生效，那就放进 settings.json：

• 常用模型（model.name）
• UI 行为（主题、是否隐藏 Banner、是否显示上下文信息）
• 是否启用 sandbox
• 工具白名单 / 自动批准策略
• 会话保留策略、上下文压缩策略等

个人使用： 放在 ~/.gemini/settings.json

项目使用 / 团队协作： 放在项目根目录 .gemini/settings.json，让所有人 clone 后即生效

---

二、敏感或环境相关的值，用环境变量

凡是 API Key、Credential、不同机器不一样的配置，都不要写死在配置文件中：

• GEMINI_API_KEY
• GOOGLE_APPLICATION_CREDENTIALS
• Telemetry / Sandbox / Debug 开关
• CI 环境下的特殊参数

推荐做法是：

• 本地：使用 .env 或 shell 配置文件
• 项目：使用 .gemini/.env
• CI/CD：使用平台提供的 Secret / Env 配置

这样既安全，又不会污染仓库。

---

三、只想临时改一次，用命令行参数

只是这一次想换模型、开 debug、跑脚本，不需要动任何配置文件：

• 临时切模型：--model
• 非交互调用：--prompt
• 机器可读输出：--output-format json
• 强制 sandbox / debug / resume 会话

命令行参数始终拥有最高优先级，适合测试、排错和自动化脚本。

---

四、真正提升效果的关键 Context Files（GEMINI.md）

如果希望 Gemini 更懂你的项目，而不仅仅是“能回答问题”，那么一定要使用 GEMINI.md 或自定义 context files：

• 项目背景说明
• 编码规范 / 风格约定
• 目录结构说明
• 工具使用约束
• 团队协作规则

这部分内容会作为 system prompt 注入模型，是影响回答质量最直接、性价比最高的配置手段。

---

五、一句话使用原则

• 默认行为不满意 → settings.json
• 涉及密钥和环境差异 → 环境变量
• 只想改一次 → CLI 参数
• 想让模型“更聪明” → context files

理解并善用这套分层配置机制，就可以把 Gemini CLI 从“能用”，调教到“顺手、可控、可复用”。希望能帮助到大家，感谢阅读，本文完！

---

05 工程化与治理：Checkpoint、Sandbox、Telemetry 与企业最佳实践

本文是进阶篇”，重点整理 Gemini CLI 中更偏工程/企业落地的能力：

• Checkpointing（检查点）：AI 写文件前自动快照，随时回滚
• 企业级集中式配置：系统默认值/覆盖项/用户/工作区的合并与优先级
• 安全治理：工具白名单/黑名单、禁用 YOLO、MCP 工具治理、网络代理、审计遥测
• Sandbox（沙箱）：Docker/Podman/macOS Seatbelt 隔离执行
• OpenTelemetry：日志/指标/Trace 可观测性，成本与治理更透明

---

5.1 Checkpointing（检查点）

原文地址：https://geminicli.com/docs/cli/checkpointing/

一句话解释： 当你允许 Gemini CLI 调用会“改文件”的工具（比如写文件、替换内容）时，它会先自动做一次项目快照，确保你随时能恢复到“改之前”的状态。

这让你可以更大胆地让 AI 做重构/批量修改，因为你知道——随时可撤销。

---

5.1.1 工作原理

当你批准一个会修改文件系统的工具（例如 write_file 或 replace）时，CLI 会自动创建一个“检查点”。检查点包含：

1. Git 快照（影子仓库提交）

   • CLI 会在一个特殊的影子 Git 仓库中创建一次提交
   • 影子仓库位置：~/.gemini/history/<project_hash>
   • 这不会干扰你自己项目的 Git 仓库（你的 .git 不会被动）

2. 对话历史 ：与 agent 的整个对话会被保存（方便恢复上下文）

3. 工具调用信息 ：即将执行的工具调用细节也会被记录（恢复后可重新执行/修改/忽略）

---

5.1.2 数据存放在哪？

所有检查点数据都会存储在本机：

• Git 快照（影子仓库）：~/.gemini/history/<project_hash>
• 对话历史与工具调用 JSON：通常在
  ~/.gemini/tmp/<project_hash>/checkpoints

这也意味着它适合企业环境：不会把你的项目快照上传到远程仓库。

---

5.1.3 启用 Checkpointing

注意：--checkpointing 这个命令行标志已在 0.11.0 移除，现在只能通过 settings.json 开启。

在你的 settings.json 里添加：

{
  "general": {
    "checkpointing": {
      "enabled": true
    }
  }
}

---

5.1.4 使用 /restore 管理检查点

启用后，检查点会自动创建。管理它们用 /restore。

---

1）列出当前项目所有检查点：

/restore

CLI 会列出检查点文件，一般命名类似：

• 2025-06-22T10-00-00_000Z-my-file.txt-write_file

含义通常是：时间戳 + 文件名 + 工具名

---

2）恢复到某个检查点：

/restore <checkpoint_file>

例子：

/restore 2025-06-22T10-00-00_000Z-my-file.txt-write_file

恢复后会发生三件事：

• 项目文件回滚到快照状态
• CLI 内对话历史恢复
• 原始工具调用会再次出现（你可以重新运行/修改/忽略）

---

5.2 面向企业的 Gemini CLI（集中式配置 + 安全治理最佳实践）

企业里最常见的痛点是：

• 大家配置不一致
• 工具权限不可控
• 网络、审计、合规无法统一管理

Gemini CLI 提供了 系统级配置 来解决这些问题。

---

5.2.1 系统设置文件

企业管理中最强大的工具是全局系统设置文件：

• system-defaults.json：系统默认基线（最低优先级）
• settings.json：系统覆盖项（最高优先级，最终裁决）

CLI 会从 4 个文件合并配置（单值设置优先级如下）：

1. 系统默认值（system-defaults.json）
2. 用户设置（~/.gemini/settings.json）
3. 工作区设置（<project>/.gemini/settings.json）
4. 系统覆盖项（settings.json）最高

对数组/对象类型（如 includeDirectories、mcpServers），是“合并”而不是直接覆盖。

---

5.2.2 合并示例

系统默认值（system-defaults.json）：

{
  "ui": {
    "theme": "default-corporate-theme"
  },
  "context": {
    "includeDirectories": ["/etc/gemini-cli/common-context"]
  }
}

用户设置（~/.gemini/settings.json）：

{
  "ui": {
    "theme": "user-preferred-dark-theme"
  },
  "mcpServers": {
    "corp-server": {
      "command": "/usr/local/bin/corp-server-dev"
    },
    "user-tool": {
      "command": "npm start --prefix ~/tools/my-tool"
    }
  },
  "context": {
    "includeDirectories": ["~/gemini-context"]
  }
}

工作区设置（/.gemini/settings.json）：

{
  "ui": {
    "theme": "project-specific-light-theme"
  },
  "mcpServers": {
    "project-tool": {
      "command": "npm start"
    }
  },
  "context": {
    "includeDirectories": ["./project-context"]
  }
}

系统覆盖项（/etc/…/settings.json）：

{
  "ui": {
    "theme": "system-enforced-theme"
  },
  "mcpServers": {
    "corp-server": {
      "command": "/usr/local/bin/corp-server-prod"
    }
  },
  "context": {
    "includeDirectories": ["/etc/gemini-cli/global-context"]
  }
}

最终合并结果（最终真正生效的配置）：

{
  "ui": {
    "theme": "system-enforced-theme"
  },
  "mcpServers": {
    "corp-server": {
      "command": "/usr/local/bin/corp-server-prod"
    },
    "user-tool": {
      "command": "npm start --prefix ~/tools/my-tool"
    },
    "project-tool": {
      "command": "npm start"
    }
  },
  "context": {
    "includeDirectories": [
      "/etc/gemini-cli/common-context",
      "~/gemini-context",
      "./project-context",
      "/etc/gemini-cli/global-context"
    ]
  }
}

结论：

• theme：系统覆盖项最高优先级，强制生效
• mcpServers：对象合并，同名 corp-server 以系统覆盖项为准
• includeDirectories：数组拼接（系统默认 → 用户 → 工作区 → 系统覆盖）

---

5.2.3 系统配置文件的位置（不同系统）

• Linux：/etc/gemini-cli/settings.json
• Windows：C:\ProgramData\gemini-cli\settings.json
• macOS：/Library/Application Support/GeminiCli/settings.json
• 可用环境变量覆盖：GEMINI_CLI_SYSTEM_SETTINGS_PATH

---

5.2.4 企业常用技巧

问题：用户可以自己 export GEMINI_CLI_SYSTEM_SETTINGS_PATH=... 指向别的配置，从而绕开公司策略。

解决：用一个 wrapper 脚本把环境变量写死。

把下面脚本保存为 /usr/local/bin/gemini（并确保它在 PATH 中优先于真实 gemini）：

#!/bin/bash

## Enforce the path to the corporate system settings file.
export GEMINI_CLI_SYSTEM_SETTINGS_PATH="/etc/gemini-cli/settings.json"

## Find the original gemini executable.
REAL_GEMINI_PATH=$(type -aP gemini | grep -v "^$(type -P gemini)$" | head -n 1)

if [ -z "$REAL_GEMINI_PATH" ]; then
  echo "Error: The original 'gemini' executable was not found." >&2
  exit 1
fi

## Pass all arguments to the real Gemini CLI executable.
exec "$REAL_GEMINI_PATH" "$@"

---

5.2.5 工具访问控制（白名单优先 + 禁用 YOLO 模式）

企业安全治理的核心目标：最小权限原则（Least Privilege）。

---

5.2.5.1 coreTools（允许列表）

只允许安全的只读工具（示例：读文件 + 列目录）：

{
  "tools": {
    "core": ["ReadFileTool", "GlobTool", "ShellTool(ls)"]
  }
}

---

5.2.5.2 excludeTools（阻止列表）

例如阻止删除命令：

{
  "tools": {
    "exclude": ["ShellTool(rm -rf)"]
  }
}

风险：黑名单是字符串匹配思路，聪明用户可能绕过。生产环境建议优先使用白名单。

---

5.2.5.3 禁用 YOLO 模式

目的：防止模型在没有明确批准的情况下执行工具。

{
  "security": {
    "disableYoloMode": true
  }
}

---

5.2.6 MCP（自定义工具）治理

如果你们用 MCP server（Model-Context Protocol）接入内部工具，就一定要理解：

• mcpServers 会合并
• 同名 server 的优先级：System > Workspace > User
• 用户无法覆盖 system 定义，但可以新增“新名字”的 server（除非你用 allowed 限制）

---

5.2.6.1 限制 MCP 服务器暴露的工具（includeTools / excludeTools）

推荐 includeTools（只开放必要能力）：

{
  "mcp": {
    "allowed": ["third-party-analyzer"]
  },
  "mcpServers": {
    "third-party-analyzer": {
      "command": "/usr/local/bin/start-3p-analyzer.sh",
      "includeTools": ["code-search", "get-ticket-details"]
    }
  }
}

---

5.2.6.2 更安全的企业模式（system 中同时定义 + 加 allowed 白名单）

system settings.json 示例（强治理）：

{
  "mcp": {
    "allowed": ["corp-data-api", "source-code-analyzer"]
  },
  "mcpServers": {
    "corp-data-api": {
      "command": "/usr/local/bin/start-corp-api.sh",
      "timeout": 5000
    },
    "source-code-analyzer": {
      "command": "/usr/local/bin/start-analyzer.sh"
    }
  }
}

效果：

• 用户新增的 server 名字不在 mcp.allowed → 直接被阻止
• 同名 server 即使用户定义 → system 会覆盖

---

5.2.6.3 不安全模式（只定义 server 但不加 allowed）

{
  "mcpServers": {
    "corp-data-api": {
      "command": "/usr/local/bin/start-corp-api.sh"
    }
  }
}

风险：用户可以在自己 settings 里新增任意 server，最终会合并进可用工具列表。

---

5.3 Sandbox（沙箱）

原文地址：https://geminicli.com/docs/cli/sandbox/

沙箱的定位：在 AI 工具执行与宿主机之间加一道隔离层，避免误操作造成系统损坏。

沙箱方式有如下两种：

• macOS Seatbelt（仅 macOS）：sandbox-exec，轻量
• Docker/Podman 容器沙箱：跨平台、隔离更强（推荐企业）

---

安装与验证方式如下：

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

---

快速开启沙箱（3 种方式）

方式 1：命令行 flag

gemini -s -p "analyze the code structure"

方式 2：环境变量

export GEMINI_SANDBOX=true
gemini -p "run the test suite"

方式 3：settings.json（长期配置）

{
  "tools": {
    "sandbox": "docker"
  }
}

---

启用优先级（从高到低）：

1. 命令行：-s/--sandbox
2. 环境变量：GEMINI_SANDBOX=true|docker|podman|sandbox-exec
3. settings：{"tools":{"sandbox":true}}（或指定 docker/podman）

---

macOS Seatbelt Profiles（常用）：

通过 SEATBELT_PROFILE 环境变量设置：

• permissive-open（默认）：限制写入外部目录，允许网络
• permissive-closed：限制写入外部目录，不允许网络
• restrictive-open：更严格，允许网络
• restrictive-closed：最严格

---

自定义容器沙箱参数（SANDBOX_FLAGS）

例如 Podman 禁用 SELinux label：

export SANDBOX_FLAGS="--security-opt label=disable"

多个参数：

export SANDBOX_FLAGS="--flag1 --flag2=value"

---

调试沙箱（DEBUG）：

DEBUG=1 gemini -s -p "debug command"

注意：项目 .env 的 DEBUG=true 不会影响 gemini-cli，因为会被自动排除，需要调试请用 .gemini/.env

5.4 OpenTelemetry 可观测性

原文地址：https://geminicli.com/docs/cli/telemetry/

为什么需要可观测性？

• 统计团队使用情况与功能采用率
• 监控 token、延迟、失败率
• 审计工具调用（谁在用什么工具做什么）
• 成本优化（缓存 token、模型路由、重试行为）

---

5.4.1 核心配置项（settings.json / 环境变量）

所有遥测行为都由 .gemini/settings.json 控制，也可以用环境变量覆盖。

常见配置示例：

{
  "telemetry": {
    "enabled": true,
    "target": "gcp",
    "logPrompts": false
  }
}

企业建议：

• enabled: true（开启）
• logPrompts: false（不要采集 prompt 文本，避免敏感信息泄露）
• target: gcp 或 local 看你们的后端

---

5.4.2 Google Cloud 遥测（推荐 Direct Export）

1）启用遥测：

{
  "telemetry": {
    "enabled": true,
    "target": "gcp"
  }
}

2）运行 CLI 并产生数据：

正常使用 gemini 即可。

3）查看（Console）：

• Logs / Metrics / Traces：在 Google Cloud Console 中查看

---

5.4.3 本地遥测

{
  "telemetry": {
    "enabled": true,
    "target": "local",
    "otlpEndpoint": "",
    "outfile": ".gemini/telemetry.log"
  }
}

---

5.4.4 典型企业 system settings 汇总示例

{
  "tools": {
    "sandbox": "docker",
    "core": [
      "ReadFileTool",
      "GlobTool",
      "ShellTool(ls)",
      "ShellTool(cat)",
      "ShellTool(grep)"
    ]
  },
  "mcp": {
    "allowed": ["corp-tools"]
  },
  "mcpServers": {
    "corp-tools": {
      "command": "/opt/gemini-tools/start.sh",
      "timeout": 5000
    }
  },
  "telemetry": {
    "enabled": true,
    "target": "gcp",
    "otlpEndpoint": "https://telemetry-prod.example.com:4317",
    "logPrompts": false
  },
  "advanced": {
    "bugCommand": {
      "urlTemplate": "https://servicedesk.example.com/new-ticket?title={title}&details={info}"
    }
  },
  "privacy": {
    "usageStatisticsEnabled": false
  }
}

---

5.5 小结

到这里，Gemini CLI 的企业级与工程化能力就基本梳理完了。可以看到，Gemini CLI 的设计目标并不只是“提升个人编码效率”，而是从一开始就围绕 可控性、安全性与可运维性 来构建，这也是它能进入真实工程与企业环境的关键。

---

回顾一下本文涉及的几个关键能力：

• Checkpointing：让 AI 的“写文件 / 重构 / 批量修改”变成一件可回滚、可恢复、可审计的事情 → 这是 AI 能真正进入生产仓库的前提

• 集中式配置与优先级合并：系统 / 用户 / 工作区 / 覆盖项的多层合并 → 让“统一策略 + 灵活使用”不再是二选一

• 工具治理 + MCP 安全模型：白名单优先、禁用 YOLO、MCP allowed + includeTools → 把 AI 的能力牢牢限制在“你允许的边界内”

• Sandbox（沙箱执行）：Docker / Podman / macOS Seatbelt → 即使 AI 出错，也被关在笼子里

• OpenTelemetry 可观测性：日志、指标、Trace、成本、审计 → 让 AI 使用情况像任何一个后端服务一样“看得见、管得住”

感谢阅读，希望能帮助到大家，本文完！

06 Skills：按需加载的专家技能体系（Agent Skills）

如果要真正把 Gemini CLI 用到中大型项目或团队协作场景中时，一个绕不开的问题也逐渐显现出来：

如何让 AI 在“知道得足够多”的同时，又不过度消耗上下文、避免被无关信息干扰？

传统的做法，往往是通过 PROMPT.md、GEMINI.md 等全局上下文文件，把所有背景知识一股脑塞给模型，随着项目演进，这类文件不可避免地变得臃肿、难维护，也越来越“吃 Token”。为了解决这一痛点，可以使用 —— Agent Skills。

本文将围绕 Agent Skills 的设计理念、启用方式、目录规范以及一个完整的实战案例，带大家理解它是如何通过 “按需加载上下文”的方式，让 AI 真正具备 模块化、可复用、可治理的专家能。

6.1 什么是 Agent Skills？

在传统的 AI 辅助开发中，我们通常会在项目根目录下放置一个类似于 PROMPT.md 或 GEMINI.md 的全局上下文文件。但这种做法有一个痛点：随着项目变大，全局背景信息会越来越多，不仅消耗大量的 Token，还可能让 AI 的注意力分散。

Agent Skills 就是为了解决这个问题而生的，它是 基于“Agent Skills 开放标准”构建的，简单来说，它将 特定领域的知识、操作流程和相关资源打包成一个独立的文件夹。

它的核心逻辑是“按需加载” (On-demand expertise)： AI 平时并不知道这些详细指令，只有当你提出相关需求时，Gemini 才会自动“激活”对应的技能，将相关上下文拉取到当前会话中。

---

四大核心优势：

• 【按需加载 (Progressive Disclosure)】：初始阶段只加载技能的元数据（名称和描述），大幅节省 Context Tokens。
• 【知识沉淀与共享】：可以将复杂的团队工作流（例如特定的代码审查规范、部署流程）打包，团队成员开箱即用。
• 【可复用的工作流】：确保复杂的多步任务始终以一致的标准化流程执行。
• 【资源捆绑】：不仅能写 Prompt，还能把脚本、模板、示例数据和指令打包在一起给 AI 使用。

---

6.2 启用与管理技能

注意： 该功能目前处于实验阶段，需要开启 experimental.skills 才能使用。你可以在 /settings 交互界面中搜索 “Skills” 进行开启。

Gemini CLI 会从三个主要位置自动发现技能（优先级依次降低）：

1. Workspace 技能 (.gemini/skills/)：特定于当前项目的技能，建议提交到 Git 仓库与团队共享。
2. User 技能 (~/.gemini/skills/)：你的个人专属技能，在所有项目中均可使用。
3. Extension 技能：随扩展程序安装的技能。

在终端中，可以使用 gemini skills 命令行工具来管理：

## 列出所有已发现的技能
gemini skills list

## 从 Git 仓库安装一个公开的技能包
gemini skills install https://github.com/user/repo.git

## 安装到特定项目的 Workspace 作用域
gemini skills install /path/to/skill --scope workspace

## 启用/禁用特定技能
gemini skills enable my-expertise

如果正处于 Gemini 的交互式会话中，也可以使用斜杠命令：

• /skills list：查看技能状态
• /skills disable <name> / /skills enable <name>：管理技能开关

---

6.3 案例实战

创建一个 Skill 非常简单，它本质上就是一个包含 SKILL.md 文件的目录。

建议遵循以下官方推荐的约定（虽然只有 SKILL.md 是必选的）：

my-skill/
├── SKILL.md        # (必选) 元数据和核心指令 Prompt
├── scripts/        # (可选) 可供 AI 运行的 bash/python/node 脚本
├── references/     # (可选) 静态文档、Schema 或示例数据
└── assets/         # (可选) 代码模板等二进制资源

当技能被激活时，AI 可以看到整个文件夹的目录树，并能读取里面的脚本和资源！

---

这里以 代码审查专家 (Code Reviewer) 案例 讲解。

SKILL.md 由两部分组成：顶部的 YAML 元数据，和底部的 Markdown 指令。

最重要的一点：description 字段是 AI 决定是否激活该技能的唯一依据，必须写得精准！

我们在 ~/.gemini/skills/code-reviewer/SKILL.md 中创建以下内容：

---
name: code-reviewer
description: 专门审查代码风格、安全性和性能。当用户要求“反馈”、“Review”、“审查”或“检查代码”时使用此技能。
---

## Code Reviewer (代码审查专家)

你是一名资深的技术专家。当用户要求审查代码时，请严格遵守以下工作流：

1. **分析**：审查暂存的 Git 变更或提供的特定文件。确保变更范围合理。
2. **风格**：确保代码遵循本项目的规范（参考项目根目录的编码指南）。
3. **安全性**：重点检查 SQL 注入、XSS、敏感信息硬编码等安全隐患。
4. **测试覆盖**：验证新逻辑是否包含对应的单元测试。

**输出格式**：请以简洁的 Markdown 列表形式，分别列出“亮点 (Strengths)”和“改进建议 (Opportunities)”。

下次当你对 Gemini CLI 说：“帮我 Review 一下刚才写的代码” 时，Gemini 就会识别到触发词，自动激活这个技能，并按照你设定的 4 步流程进行专业的代码审查。

---

不用担心 AI 乱用你的本地文件。Agent Skills 的运行机制在安全方面设计得很周到：

1. 激活拦截：当 AI 想要激活某个技能时，CLI 会弹出一个用户确认提示，告知你技能的名称和请求访问的目录。
2. 沙箱隔离：只有你批准后，SKILL.md 的内容才会被注入历史记录，对应的文件夹权限才会被开放给 AI。

---

6.4 技能编写建议

想要用好 Agent Skills，建议遵循以下几点：

① Description（描述）是重中之重：AI 激活技能的逻辑类似于函数的语义搜索，你的 description 应该包含具体的触发词。例如，不要写“擅长写代码”，而是写“当需要生成 React 组件或编写前端测试用例时使用”。

---

② 区分作用域 (Scope)：

• 将个人的提效工具放在 User 级别 (~/.gemini/skills/)，比如“Git Commit Message 生成器”、“个人周报总结助手”。
• 将团队规范放在 Workspace 级别 (.gemini/skills/)，比如“团队特有 CI/CD 修复指南”、“微服务部署脚本助手”，并将其提交到 Git。

---

③ “Don’t Just Prompt, Automate” (结合脚本)：

既然支持文件夹，就不要只在 SKILL.md 里写文字，如果技能是关于“日志分析”，不如在 scripts/ 下放一个 python 脚本专门抓取日志，并在 SKILL.md 里告诉 AI：“遇到错误时，先运行 scripts/fetch_logs.py 获取最新日志”。

6.5 小结

从本质上看，Agent Skills 并不是“又一种 Prompt 写法”，而是 Gemini CLI 在 Agent 架构层面迈出的关键一步：

它把“提示工程”从一次性的文本输入，升级为可版本化、可组合、可审计的能力模块。

通过 Agent Skills，你可以：

• 把零散的 Prompt 沉淀为长期资产
• 把个人经验升级为团队共享的专家能力
• 把复杂流程从“靠记忆”变成“可自动执行的标准化工作流”

Agent Skills 几乎是一个绕不开、也非常值得尽早投入的能力。如果你觉得本文对你有帮助，欢迎点赞、收藏或关注，谢谢大家的阅读，本文完！

---

07 Tools：内置工具与工具调用模型

经过前面几篇文章的铺垫，相信大家已经能够顺利使用 Gemini CLI 完成日常开发任务，但在实际工程中，真正拉开效率差距的，并不是“会不会用命令”，而是是否理解 Gemini CLI 背后那套工具机制。

Gemini CLI 并不是一个简单的对话式终端，而是通过一组高度模块化的 Tools，让大模型能够直接：

• 感知并操作本地文件系统
• 执行真实的 Shell 命令并基于结果继续推理
• 获取最新的网络信息，避免模型幻觉
• 记住项目规范与个人偏好
• 在复杂任务中进行自我规划与状态管理
• 甚至通过 MCP 协议对接外部系统

本文将聚焦 Gemini CLI 的核心工具体系，结合官方文档与真实案例，逐一拆解每类工具的设计目的、使用方式以及工程实践中的最佳用法。

7.1 核心工具深度解析

7.1.1 文件系统工具 (File System)

官方文档链接：https://geminicli.com/docs/tools/file-system

这是与日常开发结合最紧密的工具集，赋予了 AI 操作本地代码库的能力。

---

list_directory (列出目录)

用于查看项目结构。AI 会自动读取项目中的 .gitignore 文件，智能过滤掉 node_modules 等无关文件，从而减少 Token 消耗并保持上下文简洁。

---

read_file (读取文件)

这是 AI 理解代码的核心途径。除了纯文本文件，它还支持读取图片、音频甚至 PDF。对于超大文件，该工具支持智能分页读取，防止撑爆模型的上下文窗口。

---

write_file (写入文件)

直接在本地创建或覆盖文件。如果路径中包含不存在的文件夹，它会自动创建完整的目录树。出于安全考虑，此操作默认需要用户在终端按回车确认。

---

search_file_content (内容搜索)

在代码库中搜索特定文本。其底层优先调用 git grep 命令，这使得它能够实现毫秒级的跨文件搜索，比传统的遍历快得多。

---

replace (智能替换)

极其强大的代码修改工具。与传统的正则匹配不同，它通过“上下文匹配”来修改文件。即使目标文件在你和 AI 对话期间发生了轻微的偏移（如加了换行），它的自我纠错机制也能精准定位修改位置，大大提高了安全性。

---

7.1.2 Shell 命令行工具 (Shell)

官方文档链接：https://geminicli.com/docs/tools/shell

让 AI 替你执行 Git 操作、运行构建脚本，甚至启动开发服务器。

---

run_shell_command (运行命令)

AI 可以通过此工具执行任意系统命令，并捕获标准输出 (Stdout)、错误输出 (Stderr) 和退出码，支持在命令末尾添加 & 符号以启动后台进程。

---

交互式 TUI 支持

如果开启了交互模式，AI 甚至可以运行 vim、htop 或 git rebase -i 等基于文本用户界面（TUI）的复杂程序。

安全配置建议 (settings.json)：强烈建议在配置文件中使用白名单模式，严防 AI 误操作

{
  "tools": {
    "shell": {
      "enableInteractiveShell": true, 
      "core": ["run_shell_command(git)", "run_shell_command(npm)", "run_shell_command(pnpm)"], 
      "exclude": ["run_shell_command(rm)"] 
    }
  }
}

---

7.1.3 网络获取与搜索

官方文档链接：https://geminicli.com/docs/tools/web-fetch

摆脱本地环境限制，让 AI 获取实时资讯。

---

web_fetch (网页抓取)

单次请求最多可并发抓取 20 个 URL。如果目标网站屏蔽了 Gemini 的官方服务器 API，CLI 会自动降级，使用你的本地网络环境进行抓取，确保成功率。

---

google_web_search (谷歌搜索)

官方文档链接：Web Search Tool

内置了 Google Search API。返回的结果不仅包含摘要信息，还会提供可验证的来源链接（Citations），确保信息的准确性。

---

7.1.4 记忆工具

官方文档链接：https://geminicli.com/docs/tools/memory

避免每次对话都要重复介绍项目背景和代码规范。

---

save_memory (保存记忆)

该工具会将你的偏好信息永久写入 ~/.gemini/GEMINI.md 文件中。每次启动 CLI 时，系统会自动将该文件内容作为 System Prompt 的一部分加载。

最佳实践：建议仅用于存储核心元数据，如项目规范（“总是使用 TypeScript”）、代码风格偏好等，不建议存储大段的对话历史。

---

7.1.5 Todos 任务清单

官方文档链接：https://geminicli.com/docs/tools/todos

面对长链条的复杂需求，AI 的思路容易发散，Todos 工具帮助 AI 进行“自我规划”。

write_todos (编写待办)

当接到复杂指令（如“初始化一个 React 项目”）时，AI 会先生成任务列表，每个任务包含 pending、in_progress 或 completed 状态。在执行过程中，你可以随时按 Ctrl+T 快捷键，弹出工作进度面板查看 AI 当前进展。

---

7.1.6 MCP 服务器集成

官方文档链接：https://geminicli.com/docs/tools/mcp-server

MCP (Model Context Protocol) 是一种开放标准，通过它，Gemini CLI 的能力可以被无限扩展。

可以通过配置 MCP 服务器，让 Gemini CLI 连接到任何外部系统，例如公司内部的 Jira、本地的 MySQL 数据库，或者是 AWS 云资源。在终端输入 /mcp 即可进入交互式管理界面。

---

7.2 案例实践

接下来看看在真实场景中，Gemini CLI 是如何工作的。

案例一：自动化重构老旧代码 (结合 File System)

场景：接手老 React 项目，需将所有废弃的 componentWillMount 重构为 useEffect。

• 用户 Prompt：“在 src 目录下找出所有使用 componentWillMount 的组件，理解逻辑，并用 useEffect 重构。”
• AI 执行流：glob 搜索 → read_file 阅读上下文 → replace 生成差异 Diff → 等待按回车确认→ 瞬间修改完毕。

---

案例二：一键排查并修复 CI/CD 报错 (结合 Shell)

场景：拉取新代码后，npm run test 终端爆红。

• 用户 Prompt：“帮我运行 npm run test，分析报错原因，修复代码并自动重新运行直到通过。”
• AI 执行流：run_shell_command 运行测试 → 分析 Stderr 发现 lodash 版本过低 → run_shell_command("npm install lodash@latest") → 再次运行测试 → 全绿通过。

---

案例三：解决冷门框架的疑难杂症 (结合 Web Search)

• 用户 Prompt：“我在用 Fresh 框架时遇到 ‘Dynamic imports not allowed’ 报错，搜一下 GitHub Issues 给解决方案。”

• AI 执行流：google_web_search 搜索 GitHub → web_fetch 抓取前三个 Issue 详情 → 直接告诉你：去 deno.json 里加一行配置项即可。

---

案例四：新员工的自动入职向导 (结合 Memory)

• 第一天告诉 AI：“记住：我们的后端是 Go，Git Commit 必须带上 Jira ID（如 feat: [JIRA-123]…）。”
• 几天后日常开发：
  • 用户：“帮我把当前修改提交一下。”
  • AI：自动运行 git status，分析 Diff，生成 feat: [JIRA-123] 增加用户登录接口，无需重复提示规范！

---

案例五：全栈项目从 0 到 1 (结合 Todos)

• 用户 Prompt：“用 FastAPI 和 Vue3 初始化一个记账本，要有前后端目录和添加账单 API。”
• AI 执行流：触发 write_todos，生成包含建目录、装依赖、写代码的 8 步清单，像流水线一样推进，永不“断片”。

---

案例六：化身临时 DBA (结合 MCP)

• 前提：配置了 MySQL MCP Server。
• 用户 Prompt：“帮我查一下 users 表里 ID 为 10086 的用户，最近的 5 条金币消耗记录。”
• AI 执行流：通过 MCP 读取表结构 (get_table_schema) → 自动写 SQL (run_sql) 以 Markdown 表格形式返回数据。

---

7.3 小结

本文参考：https://geminicli.com/docs/tools

本文从工具视角系统梳理了 Gemini CLI 的能力体系，重点解析了文件系统、Shell、网络搜索、记忆、Todos 以及 MCP 等核心工具的设计与使用方式。

这些工具共同构成了 Gemini CLI 的执行基础，使大模型能够在真实开发环境中完成“读代码、跑命令、查资料、记规范、推进任务”等工程行为 ，只有理解并合理组合这些工具，才能在实际项目中稳定、高效地发挥 Gemini CLI 的价值。感谢阅读，希望能帮助到大家，本文完！

---

08 Hooks：生命周期拦截与安全加固

在 AI 辅助开发的浪潮中，Gemini CLI 提供了一种将大模型能力无缝集成到终端的方法。然而，真正的生产力提升往往来自于“量身定制”。如何在 AI 开始写代码前，强行灌输你的项目架构图？如何在 AI 试图删除敏感文件时，紧急制动？

本文将带你深入探索 Gemini CLI 的核心定制机制——Hooks（钩子）。通过本文，你将掌握其底层 I/O 机制、全生命周期事件流。

---

8.1 核心架构

Gemini CLI 的运行机制是一个经典的智能体循环 (Agentic Loop)：它接收输入，调用模型，解析意图，执行工具，再将结果反馈给模型。Hooks 是这个循环中的“拦截器”，它们在不修改 CLI 源码的情况下，通过标准输入输出（stdin/stdout）进行进程间通信（IPC）。

8.1.1 Hook 的基础配置 (hook.json)

要注册一个 Hook，你需要在项目根目录下的 .gemini/hooks/<hook-name>/ 文件夹中创建两个文件：

• 脚本文件（如 index.js 或 main.py）
• hook.json (配置清单)：这决定了你的脚本在什么时候触发。

示例 hook.json：

{
  "name": "project-context-injector",
  "description": "在 AI 思考前注入项目架构说明",
  "events": ["BeforeAgent"], 
  "command": "node index.js",
  "enabled": true
}

8.1.2 进程间通信法则 (IPC Rules)

• 输入 (Stdin)：Gemini CLI 暂停循环，将当前上下文以 JSON 字符串形式灌入你的脚本。
• 输出 (Stdout)：你的脚本只能向 stdout 输出合法的 JSON 字符串，作为对 CLI 的响应。
• 日志 (Stderr)：所有的 console.log (非JSON)、调试信息、错误警告，必须且只能输出到 stderr。Gemini CLI 会捕获这些信息并在调试面板中展示。

注意：如果在 Python 中写了 print("Starting hook...")，或者在 Node 中写了 console.log("Fetching data")，会导致 CLI 接收到的 JSON 损坏，触发解析错误。

---

8.2 生命周期事件 (Hook Events Reference)

原文链接：https://geminicli.com/docs/hooks/reference

Gemini CLI 提供了极其细粒度的控制点，以下是智能体循环中触发 Hook 的顺序：

事件名称 (Event)	触发时机	典型应用场景
BeforeAgent	用户输入刚进来，AI 开始思考前。	上下文注入：附加代码规范、Git diff 历史。
BeforeModel	CLI 即将向大模型发送网络请求前。	提示词改写：动态翻译、自动添加 Few-shot 示例。
AfterModel	大模型返回原始文本响应后。	内容审核：过滤违禁词、结构化解析输出。
BeforeTool	CLI 解析出需要调用工具（如执行 bash、读写文件）时。	安全沙箱：拦截危险命令（如 rm -rf），防止密钥泄露。
AfterTool	工具执行完毕，结果即将发回给模型前。	结果脱敏：将执行结果中的敏感 IP、密码替换为 [REDACTED]。
AfterAgent	整个交互轮次结束，最终回复呈现给用户后。	异步操作：记录日志到数据库、触发 Webhook 通知。

---

8.3 案例实践

原文链接：https://geminicli.com/docs/hooks/writing-hooks

8.3.1 案例一：[Node.js] 缓存高耗时操作 (最佳实践)

如果你的 Hook 需要查询大型数据库，每次都查会拖慢 AI 速度，我们需要实现缓存机制。

目录：.gemini/hooks/cache-demo/index.js
事件：BeforeAgent

#!/usr/bin/env node
const fs = require('fs');
const path = require('path');

// 从 stdin 读取 CLI 传入的当前状态
const input = JSON.parse(fs.readFileSync(0, 'utf-8'));

// 缓存文件路径
const CACHE_FILE = path.join(process.env.GEMINI_PROJECT_DIR, '.gemini/hook-cache.json');
const CACHE_TTL = 3600 * 1000; // 缓存 1 小时

async function getProjectContext() {
  // 检查缓存
  if (fs.existsSync(CACHE_FILE)) {
    const cache = JSON.parse(fs.readFileSync(CACHE_FILE, 'utf-8'));
    if (Date.now() - cache.timestamp < CACHE_TTL) {
      console.error("[Hook] 命中缓存，极速返回！"); // 输出到 stderr
      return cache.data;
    }
  }

  console.error("[Hook] 缓存失效，正在请求远程 API...");
  // 模拟耗时网络请求...
  const data = "项目规范：React 18, TailwindCSS, 严禁使用 class 组件。"; 
  
  // 写入缓存
  fs.writeFileSync(CACHE_FILE, JSON.stringify({ timestamp: Date.now(), data }));
  return data;
}

(async () => {
  const context = await getProjectContext();
  
  // 最终的 JSON 输出到 stdout
  console.log(JSON.stringify({
    hookSpecificOutput: {
      hookEventName: 'BeforeAgent',
      additionalContext: `\n### 实时项目上下文\n${context}`
    }
  }));
})();

8.3.2 案例二：[Python] 拦截危险的系统命令

Python 在数据处理和安全检查上非常方便。我们写一个拦截 sudo 或 rm 命令的安全 Hook。

目录：.gemini/hooks/security-check/main.py
事件：BeforeTool

#!/usr/bin/env python3
import sys
import json

def main():
    # 1. 从标准输入读取上下文
    input_data = json.load(sys.stdin)
    
    # 2. 获取当前要执行的工具和内容
    tool_name = input_data.get("tool_name")
    tool_input = input_data.get("tool_input", {}).get("content", "")

    # 3. 安全检测逻辑
    dangerous_keywords = ["rm -rf", "sudo", "chown", "chmod 777"]
    
    if tool_name == "shell":
        for kw in dangerous_keywords:
            if kw in tool_input:
                # 打印到 stderr 作为调试记录
                print(f"[安全警告] 拦截到危险命令: {kw}", file=sys.stderr)
                
                # 4. 输出拦截指令到 stdout
                result = {
                    "decision": "deny",  # 关键：拒绝执行
                    "reason": f"检测到危险的 Shell 命令: {kw}",
                    "systemMessage": "⚠️ 安全策略阻止了本次操作，请手动执行或修改命令。"
                }
                print(json.dumps(result))
                sys.exit(2) # 退出码 2 表示系统阻止

    # 5. 安全通过
    print(json.dumps({"decision": "allow"}))
    sys.exit(0)

if __name__ == "__main__":
    main()

---

8.4 数据结构参考 (Reference)

为了精确控制，你需要了解 CLI 会传入哪些数据，以及你可以返回哪些字段。

8.4.1 CLI 输入给 Hook 的数据 (stdin)

无论哪个事件，都会收到这个核心对象：

{
  "timestamp": "2024-05-20T10:00:00Z",
  "session_id": "ses_abc123",
  "hook_event_name": "BeforeAgent",
  "messages": [ /* 完整的历史对话记录数组 */ ],
  "working_dir": "/Users/dev/my-project",
  "tool_name": "shell", // 仅在 Tool 相关事件中存在
  "tool_input": { ... } // 仅在 Tool 相关事件中存在
}

8.4.2 Hook 可以返回的控制字段 (stdout)

你的输出直接决定了 CLI 的下一步行为：

• additionalContext (String): 在 prompt 后追加的不可见（对用户）上下文。
• prompt (String): 直接覆盖用户的原始 prompt。
• decision (“allow” | “deny”): 在 Tool 事件中，决定是否执行工具。
• continue (Boolean): 设为 false 可在此轮次中强制停止整个循环。

8.5 小结

本文围绕 Gemini CLI 的 Hooks 机制 展开，系统性地介绍了其在智能体循环中的定位与工作原理，重点解析了 Hook 的基础配置方式、基于 stdin/stdout 的进程间通信规则，以及 Hooks 在 Agent 全生命周期中可介入的关键事件节点。感谢阅读，希望能帮助到大家，本文完！

09 Extensions：扩展打包、开发与发布

通过 Gemini CLI 扩展，可以将提示词（Prompts）、MCP（模型上下文协议）服务器、Agent 技能（Agent Skills）和自定义命令打包成一个用户友好的格式。无论你是想为团队内部构建特定的工作流，还是想向开源社区分享你的 AI 工具，Gemini CLI 扩展都能轻松满足。

本文将基于官方文档，详细介绍 Gemini CLI 扩展的工作原理、开发流程、最佳实践以及如何发布你的扩展。

9.1 什么是 Extensions？

简单来说，Gemini CLI 扩展（Extensions）是一个包含配置和代码的目录，用于扩展 CLI 的原生能力，它的核心功能包括：

• MCP 服务器集成：允许模型调用外部工具（如读取文件、调用 API、查询数据库）。
• 自定义命令 (Custom Commands)：为常用的复杂 Prompt 创建快捷指令（如 /fs:grep-code）。
• Agent 技能 (Agent Skills)：提供按需触发的专家能力和专门的工作流程。
• 生命周期钩子 (Hooks)：在 CLI 的特定生命周期事件中拦截和自定义行为。

9.1.1 扩展的工作原理

启动时，Gemini CLI 会在 ~/.gemini/extensions/ 目录下查找扩展，每个扩展的核心是 gemini-extension.json 配置文件。如果存在冲突（例如扩展命令与用户命令同名），扩展命令会自动添加扩展名前缀进行冲突解决（例如 /gcp.deploy）。

---

9.2 快速入门

从零开始，创建一个包含 MCP 服务器和自定义命令的扩展。

9.2.1 前置准备

确保已经安装了 Gemini CLI 以及 Node.js / TypeScript 环境。

9.2.2 初始化扩展

Gemini CLI 提供了现成的模板，运行以下命令，使用 mcp-server 模板创建名为 my-first-extension 的扩展：

gemini extensions new my-first-extension mcp-server

这会生成一个包含 gemini-extension.json、package.json 和 TypeScript 源码的目录结构。

9.2.3 理解核心文件 gemini-extension.json

这是扩展的“身份证”，定义了扩展如何被加载：

{
  "name": "my-first-extension",
  "version": "1.0.0",
  "mcpServers": {
    "nodeServer": {
      "command": "node",
      "args": ["${extensionPath}${/}dist${/}example.js"],
      "cwd": "${extensionPath}"
    }
  }
}

小贴士：使用 ${extensionPath} 变量可以确保扩展无论安装在何处，路径都能正确解析。

9.2.4 编写 MCP 工具代码 (example.ts)

在 example.ts 中，可以注册自定义工具。例如，注册一个获取网络数据的工具 fetch_posts：

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
// ... 省略 imports
const server = new McpServer({ name: 'prompt-server', version: '1.0.0' });

server.registerTool('fetch_posts', {
  description: '从公共 API 获取帖子列表。',
  inputSchema: z.object({}).shape,
}, async () => {
  const apiResponse = await fetch('https://jsonplaceholder.typicode.com/posts');
  const posts = await apiResponse.json();
  return { content: [{ type: 'text', text: JSON.stringify(posts.slice(0, 5)) }] };
});

9.2.5 构建与本地链接

在开发阶段，我们使用 link 命令将开发目录链接到 CLI 扩展目录，这样改动可以实时生效：

cd my-first-extension
npm install
npm run build
gemini extensions link .

重启 Gemini CLI 后，你就可以对 AI 说：“Fetch posts” 来测试你的新工具了。

---

9.3 丰富扩展功能

9.3.1 添加自定义命令 (Custom Commands)

在扩展目录下创建 commands/fs/grep-code.toml：

prompt = """
请总结以下模式的搜索结果 `{{args}}`。
搜索结果：
!{grep -r {{args}} .}
"""

重启后，可以运行 /fs:grep-code "console.log"，AI 会自动帮你搜索并分析代码。

9.3.2 提供持久上下文 (GEMINI.md)

在根目录创建 GEMINI.md，并在 gemini-extension.json 中配置 "contextFileName": "GEMINI.md"。这里的文本会作为系统提示词加载，指导 AI 如何使用你的扩展。

9.3.3 添加 Agent 技能 (Agent Skills)

在 skills/security-audit/SKILL.md 中定义安全审计技能。当用户询问“检查安全漏洞”时，CLI 会自动激活这个技能，而不需要常驻内存。

---

9.4 最佳实践与用法指南

9.4.1 用户环境配置 (Settings)

如果扩展需要 API Key，不要硬编码。使用 gemini-extension.json 中的 settings 字段：

"settings": [
  {
    "name": "API Key",
    "description": "Your API key for the service.",
    "envVar": "MY_API_KEY",
    "sensitive": true
  }
]

安装时，CLI 会安全地提示用户输入，并保存在扩展目录下的 .env 文件中。

9.4.2 巧用变量

在配置和 Hook 中，善用以下变量：

• ${extensionPath}: 扩展安装路径
• ${workspacePath}: 当前工作区路径
• ${/}: 跨平台的路径分隔符

9.4.3 扩展管理日常用法

作为用户或开发者，你常用以下命令来管理扩展：

• 安装：gemini extensions install <github-url-or-local-path>
• 更新：gemini extensions update <name> (更新所有扩展可加 --all)
• 启用/禁用：gemini extensions disable <name> --scope workspace (支持工作区级别隔离)
• 卸载：gemini extensions uninstall <name>

---

9.5 如何发布?

开发完成后，如何分享给全世界？Gemini CLI 支持两种发布模式：

9.5.1 通过 Git 仓库发布（推荐日常迭代）

最简单的方法。只需将代码推送到公开的 GitHub 仓库，用户即可通过 URL 安装：

gemini extensions install https://github.com/your-name/your-extension

Release Channels 管理：用户可以通过 --ref=stable 安装特定分支。你可以用 dev 分支开发，稳定后 Merge 到 stable 或默认分支。

9.5.2 通过 GitHub Releases 发布（适合生产环境）

对于包含编译步骤（如 TypeScript 构建）或特定平台二进制文件的扩展，GitHub Releases 是最佳选择。用户下载的是打包好的压缩文件，速度更快。

自动化发布最佳实践 (GitHub Actions)：
利用 GitHub Actions 自动构建多平台包。包的命名规范必须遵循：{平台}.{架构}.{扩展名}.{压缩格式}，例如 darwin.arm64.my-tool.tar.gz。

## 示例 GitHub Action 步骤片段
- name: Create release assets
  run: |
    npm run package -- --platform=darwin --arch=arm64
    npm run package -- --platform=linux --arch=x64
    npm run package -- --platform=win32 --arch=x64

当配置正确时，Gemini CLI 会自动检测用户的操作系统（macOS/Linux/Windows）并下载匹配的架构包。

---

9.6 小结

Gemini CLI 的扩展机制极其灵活且对开发者友好。从简单的 Prompt 集合到包含复杂 MCP 逻辑的本地工具库，它都能轻松胜任，赶紧动手开发你的第一个扩展，打造属于你自己的超级 AI 命令行吧！

---

参考文档：

• Gemini CLI Extensions 概述
• Gemini CLI Extensions 入门教程
• Gemini CLI Extensions 发布指南

码字不易，如果本文对您有帮助，欢迎点赞、收藏并在评论区分享你的 Gemini CLI 扩展想法！

---

10 架构与贡献：CLI 组件解密与参与贡献

随着大模型技术的爆发，如何在终端（Terminal）高效地与 AI 交互成为了开发者关注的焦点，今天我们来聊聊 Gemini CLI —— 一个不仅能让你在命令行畅玩 Gemini 模型，还拥有强大插件系统和严谨架构的开源工具。无论你是想高效使用 Gemini，还是想学习如何开发一个高质量的 AI CLI 工具，这篇文章都能带你一探究竟。

10.1 Gemini CLI 是什么？

简单来说，Gemini CLI 是一个交互式的 REPL（Read-Eval-Print Loop）环境，它将 Google Gemini 模型的强大能力直接带入了本地的终端。

不像简单的 API 调用脚本，Gemini CLI 是一个成熟的生产力工具，它具备以下特性：

• 丰富的工具集（Tools）：它不仅仅是聊天。内置了文件系统操作（读写文件）、Shell 命令执行、网页抓取（Web Fetch）、Google 搜索、甚至管理你的代办事项（Todos）。
• 扩展性（Extensions）：支持安装和开发扩展，你可以像给 VS Code 装插件一样给它增强功能。
• 沙箱机制（Sandbox）：在执行系统命令或文件操作时，支持容器化的沙箱环境，确保你的主机安全。
• 企业级特性：支持 Checkpointing（检查点保存会话）、Headless 模式（用于自动化脚本）、以及 Token 缓存优化。

10.2 架构解密

了解工具的架构不仅有助于使用，更是学习优秀系统设计的良机。根据官方的 架构文档，Gemini CLI 采用了前后端分离的设计理念（尽管它们都运行在本地）。

10.2.1 核心组件分离

Gemini CLI 主要由两个核心包组成：

packages/cli (前端/客户端)：

• 职责：负责“门面”工作，处理用户输入、管理历史记录、渲染 UI（使用 Ink 库构建的 React 终端 UI）、处理主题和配置。
• 关键点：它专注于用户体验，不处理具体的 AI 逻辑。

---

packages/core (后端/核心)：

• 职责：这是“大脑”，它接收 CLI 的请求，构建 Prompt，与 Gemini API 通信，并管理工具（Tools）的注册与执行。
• 关键点：所有的状态管理、对话上下文、以及工具调用的逻辑都在这里。

10.2.2 交互流程

当你在终端输入一条命令时，由于系统内部发生了一系列精妙的流转：

• Step 1 用户输入： ：你在 packages/cli 提供的界面中输入 Prompt。

• Step 2 请求转发： ：CLI 将输入发送给 packages/core。

• Step 3 Prompt 构建与 API 请求： ：Core 层构建包含上下文和工具定义的 Prompt，发送给 Gemini API。

• Step 4 模型决策：

  • Gemini API 返回直接回复。
  • 或者，Gemini API 请求调用某个工具（比如“读取这个文件”）。

• Step 5 工具执行： ：

  • 如果是敏感操作（如写文件、执行 Shell），Core 层会请求用户确认（除非在沙箱或只读模式下）。
  • Core 执行工具，并将结果返还给 Gemini API。

• Step 6 最终响应：API 生成最终回答，Core 将其传回 CLI，CLI 渲染展示给用户。

这种 模块化（Modularity） 设计使得开发者可以轻松替换前端 UI，或者将 Core 复用到其他应用中。

---

10.3 开发者指南：如何参与贡献？

Gemini CLI 是开源的，如果你想为它贡献代码，或者想魔改一个属于自己的版本，官方的 贡献指南 非常详尽。以下是核心步骤的精简版。

10.3.1 环境准备

• Node.js 版本：开发环境下，官方强烈建议使用 Node.js ~20.19.0。这通常是因为上游依赖的特定问题，使用 nvm 可以轻松切换。
• 包管理器：项目使用 npm。

10.3.2 开发工作流

Step 1. Fork & Clone：

git clone https://github.com/google-gemini/gemini-cli.git
cd gemini-cli
npm install

Step 2. 构建：

npm run build       # 构建所有包
## 或者
npm run build:all   # 构建包 + 沙箱容器（推荐）

Step 3. 运行与调试：

• 启动：npm start
• 调试（VS Code）：直接按 F5 或运行 npm run debug。
• UI 调试：由于 CLI 使用了 React，你可以使用 React DevTools 来调试终端 UI！

DEV=true npm start
## 在另一个终端运行
npx react-devtools@4.28.5

10.3.3 提交代码前的检查 (Preflight)

在提交 PR 之前，务必运行“起飞前检查”：

npm run preflight

这个命令会执行 ESLint、Prettier 格式化以及所有的单元测试，确保你的代码符合规范。

10.3.4 提 PR 流程

• 关联 Issue：所有的 PR 必须关联一个现有的 Issue。
• 前端自动化审查：如果你修改了 packages/cli，可以在 PR 评论中运行 /review-frontend <PR_NUMBER>，官方提供了一个实验性的工具来自动审查 React 反模式。
• 分配：看到感兴趣的 Issue，评论 /assign 即可认领（每人最多同时认领 3 个）。

---

10.4 小结

Gemini CLI 展示了现代 AI 命令行工具应有的样子：人性化的交互、安全的沙箱机制以及清晰解耦的架构。

本文基于 Gemini CLI 官方文档整理，技术在不断迭代，建议以官方最新文档为准。参考：

• 官方文档首页：https://geminicli.com/docs
• GitHub 仓库：https://github.com/google-gemini/gemini-cli
• 架构概览：https://geminicli.com/docs/architecture
• 贡献指南：https://geminicli.com/docs/contributing

希望本文能帮助到大家，谢谢阅读，本文完！

---

11 总结回顾：核心能力与最佳实践

11.1 Gemini 3 为何物？

我们不应把 Gemini 简单理解为“聊天版 AI”，它更像是 嵌入在搜索、办公、开发与操作系统中的通用智能引擎。Gemini 3 的核心变革在于：

1. 原生多模态：从底层同时理解文本、图片、音频、视频和代码，并进行跨模态推理。
2. Agent-First (智能体优先)：AI 不再只是“回答”，而是具备了“执行”能力（读写文件、跑命令）。
3. 生态闭环：结合 Antigravity (Agent-First AI IDE)、Google Workspace 等，成为系统级智能中枢。

11.1.1 使用形态矩阵

Gemini 提供了零门槛到深度集成的多种使用形态：

使用形态	定位与适用场景
Web / 移动端 App	零门槛日常创作、多模态实时交互 (Live API)。
Gemini CLI	核心推荐：终端里的 AI 助手，适合代码开发、自动化运维。
API / SDK / AI Studio	工程化集成，支持长上下文、工具调用与产品化。
Antigravity (IDE)	高级开发者 / Agent 玩家，让 AI 代理自动写代码、跑命令的 IDE。

---

11.2 环境准备与架构解密

11.2.1 极速安装与订阅

• 订阅准备：利用美区环境与学生身份（Gmail + 米国地址），可薅取 Gemini 3 Pro 免费一年订阅。
• CLI 安装：依赖 Node.js (>= 18.x)，全局安装：npm install -g @google/gemini-cli。（Windows 强烈推荐使用 WSL 环境）。

11.2.2 CLI 架构（前后端分离）

Gemini CLI 采用模块化设计：

• 前端（packages/cli）：负责 UI 渲染（使用 React 终端 UI）、用户输入和主题。
• 后端（packages/core）：负责 Prompt 构建、与 Gemini API 通信以及工具（Tools）的执行。

11.2.3 配置体系（分层合并）

Gemini CLI 拥有一套严谨的配置优先级（从高到低）：
命令行参数 > 环境变量 > 系统设置(System) > 项目设置(Workspace) > 用户设置(User) > 默认值。

最佳实践： 敏感 API Key 用 环境变量；项目规范用 项目级 settings.json；临时改动用 命令行参数。

---

11.3 操控艺术：交互与自动化

Gemini CLI 提供了极其丰富的控制台交互能力：

11.3.1 三大核心命令符号

• / (斜杠 - 系统命令)：控制 CLI 元数据。如 /model (切换模型)、/memory (刷新上下文)、/restore (快照恢复)、/mcp (管理外部服务)。
• @ (At - 上下文注入)：将文件或目录无缝注入 Prompt。支持 Git 过滤，如 @src/my_project/ 总结代码。
• ! (感叹号 - Shell透传)：直接在 AI 环境执行系统命令，如 !git status。

11.3.1.1 自定义命令与宏

你可以使用 .toml 文件将常用指令沉淀为快捷命令（如 /git:commit）。

• {{args}}：动态注入用户输入。
• !{...}：执行 Shell 命令并注入其标准输出（如 !{git diff}）。
• @{...}：注入指定文件内容。

11.3.2 无头模式 (Headless Mode)

专为 CI/CD 和自动化脚本设计。

• 用法：gemini --prompt "..." --output-format json (或 stream-json)
• 价值：可以通过管道符（Pipe）与其他命令结合，例如：cat code.py | gemini -p "找 Bug" > report.txt。

---

11.4 Agent 核心扩展能力矩阵

这是 Gemini CLI 拉开生产力差距的关键，主要由 Tools、Skills、Hooks、Extensions 四大模块组成。

11.4.1 Tools（工具：AI 的手和眼）

赋予大模型操作物理世界的能力：

• 文件系统：list_directory, read_file, write_file, replace (智能正则修正)。
• Shell 命令行：执行编译、Git 操作等，捕获 stdout/stderr。
• 网络与搜索：google_web_search (防幻觉)、web_fetch (实时抓取)。
• Todos (规划)：write_todos 帮助 AI 将复杂任务拆解为多步列表。
• MCP (外部集成)：通过标准协议对接 Jira、数据库等第三方系统。

11.4.2 Agent Skills（技能：按需加载的专家）

解决全局 GEMINI.md 过度消耗 Token 的痛点。

• 机制：打包成 SKILL.md 目录。平时只加载元数据，当用户提到“触发词”时，精准按需加载。
• 组成：Prompt + 脚本文件 (scripts) + 静态资源 (assets)。

11.4.3 Hooks（钩子：生命周期拦截器）

通过标准的 stdin/stdout 进行进程间通信（IPC），在 AI 的生命周期中进行拦截：

• BeforeAgent：注入实时项目上下文。
• BeforeTool：安全拦截，检测到 rm -rf 等危险命令时直接熔断。
• AfterTool：对输出结果进行脱敏（如隐藏密码）。

11.4.4 Extensions（扩展：分发与共享）

将 Tools (MCP)、Skills、Commands、Hooks 打包成 gemini-extension.json。支持通过 Git 或 GitHub Releases 一键分发给团队或社区。

---

11.5 企业级安全与治理

在企业落地时，Gemini CLI 提供了严格的安全与可观测性保障：

11.5.1 Checkpoint (检查点与回滚)

原理：AI 每次修改文件前，自动在隐藏影子仓库（~/.gemini/history/）做 Git 快照。
价值：允许 AI 大胆重构，随时通过 /restore 命令回滚到工具执行前的状态，确保代码安全。

11.5.2 Sandbox (沙箱隔离)

AI 执行的所有 Shell 命令都可以被关进沙箱，避免误删系统文件。

• 支持方式：macOS Seatbelt、Docker、Podman。
• 开启方式：gemini -s 或配置 GEMINI_SANDBOX=docker。

11.5.3 权限治理与可观测性

• 禁用 YOLO 模式：通过配置 disableYoloMode: true 强制要求人工确认。
• 工具白名单：通过 tools.core 配置仅允许使用的安全工具（如只读工具）。
• MCP 治理：使用 allowed 和 includeTools 控制第三方服务的数据访问。
• OpenTelemetry：将 Token 消耗、延迟、工具调用日志导出到 GCP 或本地，实现成本追踪与审计。

---

11.6 小结

Google Gemini 3 的发布，标志着 AI 辅助开发范式的全面升级：

1. 从“聊代码”到“改代码”：通过 File System Tools 和 Checkpoint 机制，AI 已经可以直接参与项目的读写与重构。
2. 从“万能助手”到“模块化专家”：通过 Skills 机制和 Context 的分层加载，实现了低 Token 消耗下的高精度领域知识覆盖。
3. 从“个人提效”到“工程化落地”：Headless 模式、Hooks 机制以及 OpenTelemetry 的支持，让 AI 可以作为标准组件嵌入到企业 CI/CD 流水线中。

一句话原则：善用 settings.json 定制基础体验，用环境变量管密钥，用上下文文件 (GEMINI.md) 让模型懂你，用 Tools 和 Hooks 拓展边界。