导语： 国内技术圈的目光全钉在 Claude Code 和 Cursor 的订阅账单上，却很少有人认真聊 Google 家这个开源 AI Agent——Gemini CLI。多数人只知道「它免费」，装完打个招呼就卸载了。但这个 2025 年 6 月开源、Apache 2.0 协议的终端工具，藏着一整套国内教程几乎空白的能力：TOML 自定义命令、shell 输出注入、参数自动转义、检查点回滚、CI 流水线接入。官方 README 白纸黑字写着：用个人 Google 账号登录，每分钟 60 次请求、每天 1000 次请求免费，还带 Gemini 3 系列模型和 100 万 token 上下文窗口。今天这篇文章，带你把这 1000 次/天的额度，榨出一滴不剩。
注：需要能访问 Google 服务的网络环境和一个 Google 账号，请遵守当地法规合规使用。
# 三选一，任选其一
npx @google/gemini-cli # 免安装直接跑
npm install -g @google/gemini-cli
brew install gemini-cli # macOS/Linux
三个关键事实（均来自官方仓库 README）：
github.com/google-gemini/gemini-cli，官方路线图（Projects 看板）公开可查。对比一下国内常见选择：Claude Code 月订阅 20 美元起步且国内支付困难；Cursor 免费档请求次数抠抠搜搜；而 Gemini CLI 的 1000 次/天对个人开发者来说基本等于「随便用」。同样的 Agent 能力——读写文件、跑 shell、搜索网页、抓取 URL——一分钱不花。
大多数人不知道，Gemini CLI 会自动加载三个层级的上下文文件：
| 层级 | 路径 | 作用域 |
|---|---|---|
| 全局 | ~/.gemini/GEMINI.md |
所有项目生效 |
| 项目根目录 | ./GEMINI.md |
当前项目 |
| 子目录 | ./src/GEMINI.md |
进入相关文件时按需加载 |
操作步骤：在项目根目录敲 /init，CLI 会扫描代码库自动生成一份初版 GEMINI.md；然后手动补充你的规范，比如「统一使用 pnpm、组件用函数式写法、提交信息遵循 Conventional Commits」。敲 /memory show 可随时查看当前加载了哪些记忆内容。
效果：不用每次对话重复交代项目背景，团队把项目级 GEMINI.md 提交进 Git，全员共享同一套 AI 行为约束。这是 Claude Code CLAUDE.md 的对位功能，但国内教程几乎只讲前者的 GEMINI.md 用法，没人讲「三级分层 + 子目录按需加载」这个细节。
这是 Gemini CLI 被低估最狠的功能。自定义命令用 TOML 文件定义，支持命名空间：
# 全局命令（所有项目可用）
mkdir -p ~/.gemini/commands/git
创建 ~/.gemini/commands/git/commit.toml：
description = "Generates a Git commit message based on staged changes."
prompt = """
Please generate a Conventional Commit message based on the following git diff:
```diff
!{git diff --staged}
"""
**注意路径规则**：子目录名会转成冒号命名空间——`commands/git/commit.toml` 对应 `/git:commit`。项目级命令放 `.gemini/commands/` 下，**同名时项目级覆盖全局级**，方便团队定制。
**效果**：以后提交代码只要敲 `/git:commit`，CLI 先执行 `git diff --staged` 拿到暂存区变更，再把 diff 塞进 prompt 让模型写提交信息。一次配置，终身受用。
### 技巧 3：`!{...}` shell 注入 + `{{args}}` 自动转义——安全拼装动态 prompt
技巧 2 里的 `!{...}` 是真正的杀手锏，官方文档管它叫「shell command injection」（良性那种）。三个要点：
1. `!{grep -r {{args}} .}` 中的 `{{args}}` 会被**自动 shell 转义**后再替换，防止命令注入——你传 `It's complicated` 这种带引号的参数也不会炸；
2. 执行前 CLI 会弹出确认框，显示最终要跑的确切命令，安全可控；
3. 命令失败时，stderr 和退出码（如 `[Shell command exited with code 1]`）会一并注入 prompt，**模型能看到失败原因并自我修正**。
**适用场景**：写一个 `/grep-code.toml`，跑 `/grep-code TODO` 就自动全库搜索并让模型总结所有待办；写一个 `/test.toml`，先执行测试再把失败输出发给模型分析。这等于给每条命令装上了「先取证据，再下判断」的流水线。
### 技巧 4：`@{文件}` 注入——连图片、PDF、音视频都能塞进命令模板
在 TOML 命令里写 `@{docs/best-practices.md}`，文件内容会直接嵌入 prompt；更冷的是——**路径指向 PNG、JPEG、PDF、音频、视频时，会被自动编码成多模态输入**。目录路径则展开为整个目录树的文件内容（自动遵守 `.gitignore` 和 `.geminiignore`）。
```toml
# .gemini/commands/review.toml
description = "Reviews code against team best practices."
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 api/handler.ts，团队的评审规范全文 + 目标文件一起进上下文。设计稿截图、需求 PDF 同理——把需求文档路径写进命令模板，一条命令完成「读需求 → 写代码」。
官方文档有专门的 Checkpointing 章节：在 ~/.gemini/settings.json 中开启 checkpointing 后，每次 AI 动你的文件之前都会自动存档，用 /restore 即可回滚到改动前的状态。
{
"checkpointing": {
"enabled": true
}
}
适用场景：让 Agent 大规模重构时手抖改坏了 20 个文件，git stash 救不了未提交的混改，/restore 直接回到上一个检查点。跑 --yolo 自动确认模式的同学，这个开关是保命符。（细节以官方 geminicli.com/docs/cli/checkpointing 文档为准。）
交互模式之外，Gemini CLI 有完整的脚本化形态：
# 单次提问，纯文本输出
gemini -p "总结昨天所有提交的改动"
# 结构化 JSON 输出，方便程序解析
gemini -p "Explain the architecture" --output-format json
# 逐行 JSON 事件流，适合监控长任务
gemini -p "Run tests and deploy" --output-format stream-json
配合 @google/gemini-cli@preview（每周预发版）、@latest（每周二 20:00 UTC 稳定版）、@nightly（每日构建）三条发布通道，可以锁定不同激进度。更狠的是 Google 官方还出了 Gemini CLI GitHub Action（仓库 google-github-actions/run-gemini-cli）：PR 自动代码评审、issue 自动打标签分诊，甚至在 issue 或 PR 里 @gemini-cli 就能召唤它来干活。
在 ~/.gemini/settings.json 配置 mcpServers 即可挂载任意 MCP 服务器，README 给的示例相当嚣张：
> @github List my open pull requests
> @slack Send a summary of today's commits to #dev channel
> @database Run a query to find inactive users
也就是说 GitHub、Slack、数据库都能变成对话里的原生工具。进阶玩法是扩展（Extensions）系统：把斜杠命令、MCP 配置、上下文文件、工具屏蔽规则（excludeTools）打包成一个扩展，从 Git 仓库一键分发安装给全团队（见官方 geminicli.com/docs/extensions 文档）。另外 Google 官方还有 mcp-genmedia 项目，把 Imagen、Veo、Lyria 等媒体生成模型接进 CLI——写代码之余直接生成图、视频和音乐。
很多人卡在「额度用完」就放弃了，其实有三条路：
| 认证方式 | 免费额度 | 适合谁 |
|---|---|---|
| Google 账号 OAuth 登录 | 60 次/分 + 1000 次/天 | 个人开发者首选，免管 Key |
| Gemini API Key（AI Studio 申请） | 1000 次/天（Gemini 3，Flash/Pro 混合计） | 需要指定模型的场景 |
| Vertex AI | 按量付费，企业级配额 | 公司生产环境 |
个人用户的最优解：日常用 OAuth 登录的白嫖额度，重度任务切 API Key 再叠一层免费配额。API Key 在 aistudio.google.com/apikey 一分钟申下来，export GEMINI_API_KEY=... 即可切换。安全敏感的同学还可以开启 --sandbox 沙箱模式（基于容器隔离执行环境），配合 Trusted Folders 功能控制哪些目录信任执行。
把技巧 2-4 串起来，看 /git:commit 从敲下到出结果的完整链路：
flowchart TD
A["输入 /git:commit"] --> B["定位命令文件"]
B --> C{"同名命令在哪层?"}
C -->|项目级优先| D["点 gemini 斜杠 commands"]
C -->|回退全局| E["~ 点 gemini 斜杠 commands"]
D --> F["解析 TOML 模板"]
E --> F
F --> G["第一步: @{文件} 内容注入"]
G --> H["第二步: 执行 !{shell} 命令"]
H --> I["第三步: {{args}} 转义替换"]
I --> J{"安全确认弹窗"}
J -->|允许| K["拼装最终 prompt"]
J -->|拒绝| L["中止执行"]
K --> M["发送给 Gemini 模型"]
M --> N["输出 Conventional Commit 提交信息"]
（图中「点」为目录分隔符示意，实际路径为 .gemini/commands/ 与 ~/.gemini/commands/。）
| 维度 | Gemini CLI | Claude Code |
|---|---|---|
| 价格 | 1000 次/天免费（OAuth） | 订阅制，20 美元/月档起步 |
| 开源 | Apache 2.0，源码可审计 | 闭源（客户端） |
| 自定义命令 | TOML + shell 注入 + 参数自动转义 | Markdown 文件 |
| 模型 | Gemini 3，1M 上下文 | Claude 4.x 系列 |
| 生态 | MCP + Extensions + 官方 GitHub Action | MCP + Skills + Hooks |
客观说：纯写码体验 Claude Code 仍略胜，但「免费 1000 次/天 + 开源可改 + TOML 命令工程化」这个组合，对预算敏感的个人开发者和想批量定制团队工作流的中小团队，是明显的信息差红利。两者完全可以共存——重活给 Claude，批量脚本化任务给 Gemini CLI。
| 大多数人知道的 | 你现在知道的 |
|---|---|
| Gemini CLI 只是个免费聊天框 | 它是带 TOML 命令工程、shell 注入、多模态模板的 Agent 框架 |
| 免费额度很少、很快用完 | OAuth 登录 60 次/分 + 1000 次/天，API Key 还能再叠 1000 次/天 |
| AI 改崩代码只能靠 git 抢救 | 开启 checkpointing 后 /restore 一键回滚 |
| 自动化要自己写脚本调 API | gemini -p 无头模式 + 官方 GitHub Action 直接进 CI |
| 自定义 prompt 每次手打 | ~/.gemini/commands/ 下一个 TOML 文件固化成 /命令，团队共享 |
npm install -g @google/gemini-cli，OAuth 登录，跑 /init 生成项目记忆文件；/git:commit 和代码评审命令开始）；settings.json 开启 checkpointing 和 MCP 服务器；.gemini/commands/ 和 GEMINI.md 提交进仓库，让全组的 AI 行为统一可版本化。{{args}}、!{...}、@{...} 全语法）：https://geminicli.com/docs/cli/custom-commands本文由「51学通信」技术团队出品。51学通信由通信行业18年老兵爱卫生（微信ID: gprshome201101）维护。 聚焦5G/6G核心网、3GPP标准、AI工具实战。知识星球「51学通信」提供深度技术答疑和行业洞察。
[!tip] 51学通信知识星球 星主：爱卫生（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。 星球定位：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。 当前规模：5200 篇主题 / 990 个回答，198 元/年。 加入福利：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。 AI 加持：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。