<!-- title: 别把Gemini CLI当玩具：八道暗门 -->
<!-- domain: tips-tricks -->

# 别把Gemini CLI当玩具：八道暗门

如果你只知道 Claude Code、Cursor，那你正在错过海外终端圈这半年最"白"的一把刀——**Gemini CLI**。这是 Google 自己开源（Apache 2.0）、装在终端里跑的 AI agent，登录一个普通 Google 账号就白送 **每分钟 60 次、每天 1000 次**的额度，配的是 Gemini 3 级别模型和 **1M token 上下文窗口**。

问题是，国内九成人把它当"问答框"用：装好，问一句，答一句，没了。但翻一遍它的官方仓库 `docs/cli/` 目录你会发现，这玩意儿藏着 **auto-memory、model steering、本地 Gemma 路由、token 缓存、rewind 时光机、checkpointing 影子 Git、headless 无头模式、custom commands**——整整八道暗门。今天逐个拆，每个都给你**操作步骤 + 预期效果 + 适用场景**，抄完立刻能用。

---

## 暗门一：Auto Memory——让它自己挖"技能库"

这是我个人认为最被低估的一个。绝大多数人手写 `GEMINI.md` 写到手酸，但 Gemini CLI 有个实验性功能叫 **Auto Memory**，它会在后台**翻你过去的会话记录**，自动提炼出"可复用的记忆"和"可复用的技能（SKILL.md）"，写成 `.patch` 补丁，丢进一个收件箱等你审批。

**操作步骤：**
1. 打开 `~/.gemini/settings.json`（全局）或项目里的 `.gemini/settings.json`（仅当前项目）；
2. 加入：
   ```json
   { "experimental": { "autoMemory": true } }
   ```
3. 重启 Gemini CLI；
4. 之后任意时刻输入 `/memory inbox` 打开收件箱，可以 **Read / Promote（提升为正式 skill）/ Discard / Apply**。

**触发条件（它不会乱挖）：** 只处理**空闲超过 3 小时**且**至少有 10 条用户消息**的会话，正在跑的、太短的、子 agent 的会话一律忽略。提取跑在 Gemini Flash 预览模型上，且**默认没强证据不产出任何东西**，不会污染你的记忆。

**预期效果：** 你不用手写每一个 `SKILL.md`。比如你三次会话都让它"先跑 `pnpm test:unit` 再改代码"，它会自己把这个流程提炼成一个 skill，下次直接复用。**适用于：** 有固定工作流、反复踩同一个坑、想给团队沉淀 SOP 的人。

> 信息差点：Claude Code 那边社区还在手搓 skill 库，Gemini CLI 这边已经能"自动挖矿"了。

---

## 暗门二：Model Steering——它干活时你能插话

普通 agent 跑起来就是个黑盒，你想纠偏只能 `Ctrl+C` 打断重来。Model Steering 让你在**模型正在转圈（spinner 转动）的时候**直接输入文字、回车，它会把这段话**塞进下一轮上下文**，模型当场重新评估计划。

**操作步骤：**
1. `/settings` 里搜 **Model Steering** 打开；或在 settings.json 写 `"experimental": { "modelSteering": true }`；
2. 开始一个任务，比如"重构数据库服务"；
3. 看到它往错方向走时，在输入框打字（不用等它停），回车。

**常用纠偏话术（直接抄）：**
- **纠正路径：** "Actually, the utilities are in `src/common/utils`."
- **跳过步骤：** "Skip the unit tests for now and just focus on the implementation."
- **补上下文：** "The `User` type is defined in `packages/core/types.ts`."
- **改方向：** "Stop searching the codebase and start drafting the plan now."

**预期效果：** 省掉"打断→重启→重新喂上下文"这一整套，长任务里能省几十次来回。**适用于：** Plan Mode 长任务、复杂重构、agent 容易跑偏的场景。

---

## 暗门三：本地 Gemma 路由——把路由决策下放给本机

这是省钱暗门。Gemini CLI 默认把"该用哪个模型"这种路由判断也发给云端模型，吃你的额度。它支持用**本地跑的 Gemma 模型**来做路由决策，延迟差不多，但**不花云端 token**。

**操作步骤：**
```bash
gemini gemma setup
```
跟着向导走完即可，之后 settings.json 里会开启本地路由器。模型选择的优先级链是这样的（记住这条，下面要考）：

```mermaid
flowchart TD
    A[启动 Gemini CLI] --> B{--model 命令行参数?}
    B -- 有 --> M1[用 --model 指定的模型]
    B -- 没有 --> C{GEMINI_MODEL 环境变量?}
    C -- 有 --> M2[用 GEMINI_MODEL]
    C -- 没有 --> D{settings.json model.name?}
    D -- 有 --> M3[用 model.name]
    D -- 没有 --> E{本地 Gemma 路由器开启?}
    E -- 是 --> M4[本地 Gemma 决定路由到哪个模型]
    E -- 否 --> F[默认 auto 自动路由]
    M1 --> Z[执行当前请求]
    M2 --> Z
    M3 --> Z
    M4 --> Z
    F --> Z
```

**预期效果：** 路由判断这种"小而频繁"的调用不再消耗云端配额。**适用于：** 重度用户、想压低 API 成本的团队。

---

## 暗门四：Token 缓存的"暗税"——免费登录反而不给缓存

这是最反直觉、也最值钱的一个信息差。Gemini CLI 有 token 缓存功能，能复用之前的系统指令和上下文，**大幅减少后续请求处理的 token 数**。但官方文档白纸黑字写着：

> Token caching 适用于：API key 用户（Gemini API key）、Vertex AI 用户。
> **Token caching 不适用于：OAuth 用户（Google 个人/企业账号）**——Code Assist API 暂不支持缓存内容创建。

翻译成人话：**你用 Google 账号 OAuth 登录白嫖的那 1000 次/天，是没有 token 缓存的！** 同样的长上下文反复请求，OAuth 模式每次都全量计费。

**操作步骤：**
1. 去 [Google AI Studio](https://aistudio.google.com/) 申请一个 API key；
2. `export GEMINI_API_KEY="你的key"`，或写进 settings.json；
3. 跑 `/stats`，输出里会显示 **cached token savings**（缓存省了多少 token）。

**预期效果：** 重度长上下文场景下，缓存命中能省下一大笔 token。**适用于：** 把大代码库/长文档反复喂进去迭代的人。**别适用：** 只是偶尔问答的轻用户，OAuth 免费额度够用，没必要上 key。

---

## 暗门五：Rewind——双击 Esc 时光倒流

agent 改崩了代码怎么办？`/rewind` 一键回到之前的任意一步，而且**精细到三档可选**。

**操作步骤：**
- 输入 `/rewind` 回车，**或者直接连按两下 `Esc`**；
- 用上下键在历史交互列表里选一个点（最底的最近），右侧预览显示该步的用户 prompt 和改了几个文件；
- 回车确认后，三选一：
  1. **Rewind conversation and revert code changes**（对话和代码都回退）
  2. **Rewind conversation**（只回退对话，代码改动保留）
  3. **Revert code changes**（只回退代码，对话保留）

**预期效果：** agent 跑歪了不用从头来，精准回到岔路口换条路。**注意：** rewinding 只撤销 AI 编辑工具的改动，**你手改的、或用 shell `!` 跑的命令改动它不管**；跨压缩点也能用（它会从存储的 session 数据重建历史）。

---

## 暗门六：Checkpointing——藏在 ~/.gemini 里的影子 Git

配合 Rewind 用的还有个更强的：**Checkpointing**。每次 AI 要改文件前，它会自动在你主目录下**一个影子 Git 仓库**里做一次快照（commit），完全**不碰你项目自己的 Git**。

**操作步骤：**
1. 在 settings.json 里加（注意：`--checkpointing` 命令行参数在 **0.11.0 版本已被移除**，只能走配置文件）：
   ```json
   { "general": { "checkpointing": { "enabled": true } } }
   ```
2. 快照存在 `~/.gemini/history/<project_hash>`，对话历史和工具调用存 JSON 在 `~/.gemini/tmp/<project_hash>/checkpoints`；
3. 输入 `/restore` 列出所有快照（文件名形如 `2026-07-11T10-00-00_000Z-my-file.txt-write_file`），选一个恢复——它会把文件回滚、对话还原、并**重新提议当初那个工具调用**，让你再跑/改/忽略。

**预期效果：** 敢让 agent 大刀阔斧改代码了，反正随时 `/restore` 回来。**适用于：** 大重构、实验性改动、不信任 agent 改动的谨慎派。

---

## 暗门七：Headless 无头模式——把它当 CI 里的管道工

Gemini CLI 不只能交互，它能在脚本/CI 里**非交互式**运行，吐结构化 JSON。这是把它从"工具"升级成"基础设施"的钥匙。

**操作步骤：**
```bash
# 最简：-p 传 prompt
gemini -p "总结这个仓库的架构"

# 要结构化输出
gemini -p "列出所有 TODO" --output-format json

# 要流式事件（JSONL）
gemini -p "重构入口文件" --output-format json
```
**JSON 输出 schema：** `response`（最终答案）、`stats`（token 用量、API 延迟）、`error`（可选）。流式模式吐 `init` / `message` / `tool_use` / `tool_result` / `error` / `result` 几种事件。

**退出码（写 CI 脚本必背）：**
| 退出码 | 含义 |
|--------|------|
| `0` | 成功 |
| `1` | 一般错误 / API 失败 |
| `42` | 输入错误（prompt 或参数无效）|
| `53` | 轮次超限（turn limit exceeded）|

**预期效果：** 把 Gemini CLI 嵌进 GitHub Action、cron、shell 管道，做自动 PR review、issue 分诊。**适用于：** DevOps、想做 AI 自动化流水线的人。官方还专门有 [Gemini CLI GitHub Action](https://github.com/google-github-actions/run-gemini-cli)，在 issue/PR 里 `@gemini-cli` 就能召唤它。

---

## 暗门八：Custom Commands——把高频 prompt 存成 `/命令`

最后这个是把"重复劳动"固化的。你天天打的那个 prompt，存成 `.toml` 文件，以后一个 `/命令` 搞定，还能带参数、跑 shell、注入文件。

**操作步骤：**
1. 全局命令放 `~/.gemini/commands/`，项目命令放 `<项目>/.gemini/commands/`（项目同名命令**永远覆盖全局**，可提交进 git 团队共享）；
2. 命名即命名空间：子目录用 `/`，渲染成 `:`。比如 `git/commit.toml` → `/git:commit`；
3. 改完跑 `/commands reload` 热加载，`/commands list` 看全部；
4. 文件用 TOML v1 格式：

```toml
# ~/.gemini/commands/git/commit.toml  →  /git:commit
description = "基于 staged 改动生成 Conventional Commit 消息"
prompt = """
请基于下面这段 git diff 生成 Conventional Commit 消息：
!{git diff --staged}
"""
```

**三个魔法占位符（核心）：**
- `{{args}}`——把命令后面的参数注入。在 shell 块 `!{...}` 里会**自动 shell 转义**，防注入；
- `!{...}`——在 prompt 里**直接跑 shell 命令**并把输出注入（会先让你确认，安全检查）；
- `@{...}`——**注入文件/目录内容**，且支持**多模态**：指向 PNG/JPEG/PDF/音频/视频会正确编码成多模态输入，目录会递归列文件（尊重 `.gitignore` / `.geminiignore`）。

**组合技示例：** `/review FileCommandLoader.ts`，prompt 里写 `@{docs/best-practices.md}`，它会把最佳实践文档内容 + 你给的文件名一起喂进去做 review。

**预期效果：** 团队 SOP 一键化，新人 `/<命令>` 就能跑标准流程。**适用于：** 有重复 review/commit/changelog/test 流程的团队。

---

## 信息差总结

| 维度 | 你知道的（10%）| 别人知道但你不知道的（90%）|
|------|--------------|--------------------------|
| 定位 | 免费问答框 | 开源 agent，1000次/天、1M上下文、Gemini 3 |
| 记忆 | 手写 GEMINI.md | **Auto Memory 自动挖 skill 库** |
| 控制 | 跑崩了只能重启 | **Model Steering 运行中插话** |
| 成本 | 免费登录最香 | **OAuth 不给 token 缓存，API key 才给** |
| 撤销 | 手动 git reset | **双击 Esc rewind + 影子 Git checkpointing** |
| 自动化 | 只能交互 | **Headless + 退出码 42/53，可进 CI** |
| 复用 | 复制粘贴 prompt | **Custom Commands：`!{}` `@{}` `{{args}}` 三连** |

---

## 行动指南（今晚就能做）

1. **5 分钟上车：** `npm install -g @google/gemini-cli`，Google 账号登录，先吃满每天 1000 次免费额度。
2. **开两个实验开关：** settings.json 里 `"autoMemory": true` + `"modelSteering": true`，立刻拿到暗门一、二。
3. **算笔账：** 如果你是重度长上下文用户，去 AI Studio 拿 API key 切换登录方式，跑 `/stats` 看 token 缓存省了多少（暗门四）。
4. **建第一个命令：** 照着暗门八的 `/git:commit` 抄一个，体会 `!{}` 注入的爽感。
5. **进阶：** 把 headless 模式接进一个 GitHub Action，让 PR 自动 review（暗门七）。

---

## 参考来源

- Gemini CLI 官方仓库与 README：[github.com/google-gemini/gemini-cli](https://github.com/google-gemini/gemini-cli)
- Auto Memory 文档：[docs/cli/auto-memory.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/auto-memory.md)
- Model Steering：[docs/cli/model-steering.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/model-steering.md)
- Token Caching 与成本：[docs/cli/token-caching.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/token-caching.md)
- Headless 模式参考：[docs/cli/headless.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/headless.md)
- Custom Commands 全语法：[docs/cli/custom-commands.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/custom-commands.md)
- Gemini CLI GitHub Action：[github.com/google-github-actions/run-gemini-cli](https://github.com/google-github-actions/run-gemini-cli)

---
> 本文由「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 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)