# Gemini CLI 八道暗门：谷歌账号白嫖千次 国内开发者一提到 Google 的命令行 AI agent **Gemini CLI**，第一反应往往是"要 API Key 吧？国内又用不了，算了"。这是一个巨大的**认知差**：截至 2026 年 7 月，Gemini CLI 不仅开源（Apache 2.0），而且**只要一个普通 Google 账号 OAuth 登录，每天白送 1000 次请求、60 次/分钟**，背后跑的是 **Gemini 3 模型 + 100 万 token 上下文窗口**。更狠的是，它还藏了一堆默认关闭、文档里才提一句的"暗门"：文件改崩了一键时光倒流、AI 自动偷读你历史会话提炼记忆、用本地 Gemma 模型替你做路由决策省思考费…… 这篇就拆 **8 道多数人没碰过的暗门**，每道都能在 5 分钟内上手。 --- ## 暗门一：谷歌账号 OAuth = 每天 1000 次免费请求（别用 API Key） **这是最大的信息差。** 90% 的国内教程都教你去 aistudio.google.com/apikey 申请 API Key，然后告诉你"免费额度够用"。但官方 `docs/resources/quota-and-pricing.md` 写得很清楚： | 认证方式 | 免费档 | 每日上限 | 模型范围 | |---------|--------|---------|---------| | **Google 账号（OAuth）** | Gemini Code Assist 个人版 | **1000 次** | Gemini 3 全家族自动路由 | | Gemini API Key（未付费） | Free tier | **250 次** | **仅 Flash 模型** | | Vertex AI（Express） | 90 天免费 | 视账号而定 | 视账号而定 | **操作步骤：** 1. `npm install -g @google/gemini-cli`（或 `brew install gemini-cli`）。 2. 终端敲 `gemini`，首屏选 **Sign in with Google**，走浏览器 OAuth。 3. 不需要任何 API Key、不需要绑卡。 **预期效果：** 每天硬上限 1000 次、每分钟 60 次，模型在 Gemini 3 Pro / Flash 之间自动路由，1M token 上下文（把整个中型仓库丢进去都不慌）。 **适用场景：** 个人开发者日常写代码、读代码库。如果你之前用 API Key 还在为 250 次不够发愁，换 OAuth 直接翻 4 倍。 **一个坑（详见暗门四）：** OAuth 走的是 Code Assist API，**不支持 Token 缓存**。所以重度付费用户反而该考虑 API Key + 按量付费。免费党选 OAuth。 --- ## 暗门二：Checkpointing + /restore —— AI 改崩文件，一键时光倒流 让 AI agent 自由改文件，最怕它一把 `write_file` 把你半个月的代码冲掉。Gemini CLI 内置了**断点续存（Checkpointing）**，但**默认是关闭的**——这就是为什么大多数人没用过。 原理（来自 `docs/cli/checkpointing.md`）：每次你批准一个会改文件的工具调用（`write_file` / `replace`），CLI 会自动： 1. 在你家目录下的**影子 Git 仓库** `~/.gemini/history/` 做一次 commit（**不碰你项目自己的 Git**）； 2. 保存此刻的完整对话历史； 3. 记录即将执行的那个工具调用。 **操作步骤：** 编辑 `~/.gemini/settings.json`（或项目级 `.gemini/settings.json`）： ```json { "general": { "checkpointing": { "enabled": true } } } ``` > ⚠️ 注意：`--checkpointing` 命令行参数在 **v0.11.0 已被移除**，现在只能在 settings 里开。很多旧教程还在教你加 flag，照做会失效。 开启后，AI 每次改文件前自动留档。要回退就敲： ``` /restore # 列出所有断点 /restore 2026-07-03T10-00-00-utils.py-write_file # 恢复到某个断点 ``` **预期效果：** 恢复时不仅文件回滚，**连对话历史也一起回到那一刻**，原本那个工具调用还会重新弹出来让你决定改、删、重跑。等于给 AI 操作装了"系统还原点"。 **适用场景：** 让 AI 做大规模重构、批量改文件时必开。 --- ## 暗门三：Auto Memory —— 它会后台偷读历史会话，自动提炼记忆和技能草稿 这是 Gemini CLI 最"细思极恐"也最省心的实验特性（`docs/cli/auto-memory.md`）。开启后，它会**在后台扫描你过去的会话**，挖掘出反复出现的偏好、约束、流程，然后**主动起草**两种东西放进一个"待审收件箱"等你批准： - **记忆补丁**：`.patch` 格式的 unified diff，更新到你的记忆文件； - **技能草稿**：`SKILL.md` 文件，把反复出现的流程沉淀成可复用 skill。 **操作步骤：** 在 `~/.gemini/settings.json` 加： ```json { "experimental": { "autoMemory": true } } ``` 重启 CLI 生效（提取服务在会话启动时拉起）。 **关键安全边界（来自官方文档）：** - 只有**闲置满 3 小时、且用户消息 ≥10 条**的会话才会被扫； - 它**永远不直接改**活动记忆文件、settings、凭证或 `GEMINI.md`，全部进收件箱人工审； - 证据不强就**不产出**任何东西，所以经常扫完一场空，属正常。 **预期效果：** 你不用再手动写"我们项目跑测试用 `pnpm test:unit`、构建在 `apps/core/`"这种破事，跑过几次它自己就学会了。 **适用场景：** 沉淀团队约定、把"踩过的坑"固化成未来会话能避开的约束、零成本启动一个技能库。 --- ## 暗门四：Token Caching 省钱术 —— 但 OAuth 党吃不到 `docs/cli/token-caching.md` 里藏着一句很容易被忽略的话：**Token 缓存只对 API Key 用户和 Vertex AI 用户自动生效，OAuth（Google 个人/企业号）用户用不了**——因为 Code Assist API 当前不支持 cached content。 **操作步骤：** 不用配置，自动生效。用 API Key / Vertex 认证后，输入： ``` /stats ``` 输出里会单独列出 **cached tokens**——也就是被缓存复用、没重新计费的部分。 **怎么用才划算？** 这里有个反直觉的权衡矩阵（建议收藏）： | 你的情况 | 推荐认证 | 理由 | |---------|---------|------| | 免费、日均请求 < 1000 | **OAuth** | 额度最大（1000/天），不在意无缓存 | | 按量付费、长会话反复读同一仓库 | **API Key** | 缓存命中能省下大量重复上下文 token | | 企业/生产、要合规和高并发 | **Vertex AI** | 既有缓存又能弹性扩 | **预期效果：** 同一个仓库在一个长会话里反复读，缓存命中后**后续请求的重复上下文按缓存价计费**（远低于全价）。`/stats` 直接看见省了多少。 --- ## 暗门五：Hooks —— 在 11 个生命周期节点拦截 AI 如果 Checkpointing 是"事后后悔药"，Hooks 就是"事前门卫"。`docs/hooks/index.md` 列出了它能在 agent loop 的哪些节点同步插入你的脚本： | 事件 | 触发时机 | 能干嘛 | |------|---------|-------| | `SessionStart` | 会话开始/恢复/clear | **注入上下文**（如 `git log` 摘要） | | `BeforeAgent` | 你提交 prompt 后、规划前 | 校验、拦截、加上下文 | | `BeforeModel` | 发给 LLM 之前 | **改 prompt、换模型、mock 响应** | | `BeforeTool` | 工具执行前 | **校验参数、拦截危险操作** | | `AfterTool` | 工具执行后 | 跑测试、隐藏/处理结果 | | `PreCompress` | 上下文压缩前 | 存档状态 | | `Notification` | 系统通知 | 转发到桌面提醒 | Hooks 是**同步执行**的——事件触发时 CLI 会等所有匹配的 hook 跑完再继续，所以能真正"卡住"流程。 **操作步骤（思路）：** - `BeforeTool` 写个 hook，匹配到 `shell` 工具且参数含 `rm -rf /` 就返回阻塞退出码 → 危险命令直接被拦； - `SessionStart` 注入当前分支 + 最近 5 条 commit → AI 开口就知道你在干啥； - `AfterTool` 在 `write_file` 后自动跑 `eslint` → 改完即查。 **预期效果：** 不改 Gemini CLI 源码，就能给它装上安全闸、上下文注入器、合规审计。这是把它从"玩具"变"生产工具"的关键。 --- ## 暗门六：Headless + stream-json —— 把 Gemini 编进 CI 和脚本 很多人只用交互模式敲对话，没意识到 Gemini CLI 是个**一等公民的命令行程序**，能直接进 CI。`docs/cli/headless.md` 给了三种输出格式。 **操作步骤：** ```bash # 纯文本结果 gemini -p "审一下最近一次 git diff，列出可疑点" # 结构化 JSON（含 token 用量、延迟） gemini -p "解释这个仓库架构" --output-format json # 流式 JSONL 事件（监控长时间任务） gemini -p "跑测试并部署" --output-format stream-json ``` stream-json 会吐出 `init` / `message` / `tool_use` / `tool_result` / `result` 等事件，每个都带结构。 **退出码（脚本判定用）：** - `0` 成功；`1` 通用错误/API 失败；**`42` 输入错误**（prompt/参数非法）；**`53` turn 上限超了**。 **预期效果：** 把它接进 GitHub Actions——PR 一开自动 review、issue 自动打标签、每天定时跑一遍"昨天改了啥"摘要。配合官方的 [Gemini CLI GitHub Action](https://github.com/google-github-actions/run-gemini-cli)，甚至能在 issue 里 `@gemini-cli` 直接召唤。 **适用场景：** 独立开发者把 AI review 固化进流水线、批量处理代码库、定时巡检。 --- ## 暗门七：本地 Gemma 接管路由决策 —— 把"思考费"留在本机 还记得前面说 agent 每次都要做"该用哪个模型/工具"的路由决策吗？这些决策默认发给**托管模型**，长期累积也是一笔"思考费"。`docs/core/local-model-routing.md` 给了个实验解法：**让本地跑的 Gemma 模型来做路由决策**。 **操作步骤（推荐用自动化命令）：** ```bash gemini gemma setup # 官方一键引导，下载 LiteRT-LM 运行时 + Gemma 3 1B ``` 它会在本地起一个 LiteRT-LM 服务（提供 Windows/Linux/macOS 预编译二进制），Gemma 通过 Gemini API 协议被调用，承担路由判断。 **预期效果：** 路由决策的延迟和质量接近托管模型，但**这部分调用不花云端额度**。用量越大、路由越多，省得越明显。 **适用场景：** 高频重度用户、对延迟敏感的交互、想把账单压到临界点的人。 --- ## 暗门八：斜杠命令全家桶 —— 90% 人只敲过 `/help` `docs/reference/commands.md` 里有一整屏命令，国内能背全的凤毛麟角。挑最实用的： - **`/chat save `** / **`/resume `**：给当前对话打标签存档、随时恢复（注意：会话是**项目级**的，存在 `~/.gemini/tmp//`，换目录就看不到）。 - **`/chat share report.md`**（或 `.json`）：一键把整段对话导成 Markdown/JSON 文件——写周报、做复盘神器。 - **`/chat debug`**：把最近一次 API 请求导出成 JSON，调试 prompt、排查返回异常时救命。 - **`/agents list | enable | disable | config `**：管理子 agent，`config` 还能单独调每个子 agent 的**模型、温度、执行上限**——等于一个 agent 编排台。 - **`/stats`**：看 token 用量和缓存节省（暗门四）。 - **`/restore`**：时光倒流（暗门二）。 - 还支持 **`@`** 前缀（引用文件/资源）和 **`!`** 前缀（执行 shell）。 **预期效果：** 不再手动复制对话，不再为切模型重启，复盘和调试效率翻倍。 --- ## 认证 & 省额度决策流程 ```text flowchart TD A[开始用 Gemini CLI] --> B{日均请求多少?} B -->|"< 1000, 想免费"| C[OAuth: 谷歌账号登录] B -->|"想缓存省钱 / 按量付费"| D[API Key 认证] B -->|"企业/生产/合规"| E[Vertex AI] C --> C1[额度: 1000次/天, 60次/分] C --> C2[❌ 无 Token 缓存] C --> C2b[✅ Gemini 3 全家族 + 1M ctx] D --> D1[✅ Token 缓存自动生效] D --> D2[免费仅 250次/天, 仅 Flash] C1 --> F[开 Checkpointing: settings.json] D1 --> F E --> F F --> G[开 Auto Memory: experimental.autoMemory] G --> H[/stats 看缓存节省 + /restore 兜底] ``` --- ## 信息差总结 | 维度 | 多数人以为 | 实际暗门 | |------|-----------|---------| | 门槛 | 要 API Key、国内难用 | **普通谷歌号 OAuth 即可，1000 次/天免费** | | 改文件安全 | AI 改崩只能手动 `git checkout` | **Checkpointing + `/restore` 一键回滚文件+对话** | | 记忆 | 每次重开都要重新交代背景 | **Auto Memory 后台偷读历史，自动起草记忆和 skill** | | 省钱 | 没法省，按调用算 | **API Key 用户 Token 缓存自动生效，`/stats` 看省多少** | | 安全 | 怕 AI 乱跑命令只能盯着 | **Hooks 在 BeforeTool 节点同步拦截危险操作** | | 自动化 | 只能交互式聊天 | **`-p` + `--output-format stream-json` 进 CI** | | 路由成本 | 路由决策只能花云端额度 | **本地 Gemma 接管路由，思考费留本机** | | 命令 | 只会 `/help` | **`/chat share/debug`、`/agents config` 等，效率翻倍** | --- ## 行动指南（按优先级，今天就能做） 1. **先翻 4 倍额度**：`npm i -g @google/gemini-cli` → `gemini` → 选 Sign in with Google。别再用 API Key 的 250 次。 2. **立刻开断点**：往 `~/.gemini/settings.json` 加 `"checkpointing":{"enabled":true}`，从此敢让 AI 大改。 3. **导出你的第一份对话**：`/chat share week1.md`，体会命令行的力量。 4. **重度用户再加三件套**：开 `autoMemory`、用 API Key 拿 Token 缓存、`gemini gemma setup` 把路由留本地。 5. **进阶玩家**：写一个 `BeforeTool` hook 拦截危险 shell，把它推进生产流水线。 --- ## 参考来源 - [Gemini CLI 官方仓库（Apache 2.0）](https://github.com/google-gemini/gemini-cli) - [Quotas and pricing —— 额度对照表](https://github.com/google-gemini/gemini-cli/blob/main/docs/resources/quota-and-pricing.md) - [Checkpointing 断点续存文档](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/checkpointing.md) - [Auto Memory 自动记忆文档](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/auto-memory.md) - [Hooks 生命周期文档](https://github.com/google-gemini/gemini-cli/blob/main/docs/hooks/index.md) - [Token caching 与 /stats](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/token-caching.md) - [Headless mode 脚本模式与退出码](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/headless.md) - [Local model routing 本地 Gemma 路由](https://github.com/google-gemini/gemini-cli/blob/main/docs/core/local-model-routing.md) --- > 本文由「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 等场景全覆盖。