> 一句话信息差：谷歌的 Gemini CLI 用个人 Google 账号登录，每天白送 **1000 次请求 + Gemini 3 + 100万 token 上下文**，但 90% 的人只会敲 `gemini` 进去聊天。它的 `--worktree` 并行工地、`/rewind` 时光倒流、Model Steering 半路插话、`stream-json` 当脚本引擎、`@mcp` 一句话调外部服务——这七个暗开关，能把一个免费工具逼出付费 IDE 的生产力。今天就把官方文档里藏在二级目录的硬货一次性拆给你。 ## 先把账算清楚：你可能白扔了一半免费额度 很多人装完 Gemini CLI，第一反应是"和 Claude Code、Cursor 比怎么样"。这个问题问错了方向。**它和那些付费工具根本不在一个赛场上**——你拿个人 Google 账号 OAuth 登录，官方明文给的额度是 **每分钟 60 次、每天 1000 次请求**，跑的是 **Gemini 3 模型**，上下文窗口 **100 万 token**。这意味着你不用绑卡、不用 API Key、不用付一分钱，就能有一个能读整个大型仓库的 agent。 但这里藏着第一个认知差，国内几乎没人讲： > **Token caching（token 缓存省钱）只在 API Key 和 Vertex AI 模式下生效，OAuth 登录的用户用不上。** 官方 `token-caching.md` 写得很直白："Token caching is not available for OAuth users (Google Personal/Enterprise accounts) - the Code Assist API does not support cached content creation at this time." 翻译过来：白嫖 OAuth 额度的人，每次请求都是全价 token；而用 API Key 的人，重复的系统指令和上下文会被缓存，**长上下文重复场景下显著降低单次请求的 token 消耗**。 所以正确的姿势是两条腿走路： - **日常试错、临时改个小 bug** → 用 OAuth，白嫖 1000 次/天，反正免费。 - **同一个大仓库、要 agent 反复读上下文、又在意 token 成本** → 切到 `GEMINI_API_KEY`（在 https://aistudio.google.com/apikey 申请），让 token caching 工作，并用 `/stats` 命令实时看缓存省了多少 token。 `/stats` 这个命令是被严重低估的。输入它，你能看到本轮会话的 token 用量和 cached token 节省量。**很多人抱怨"AI 编程烧 token"，但从来没打开过 /stats 看一眼钱花哪了**。先把这一步补上，再谈优化。 ## 暗开关一：`gemini -w` 一条命令开七个工地 这是我个人认为 Gemini CLI 最被低估的功能。平时你让 AI agent 改代码，最大的痛点是**它一次只能干一件事**，你想同时推进三个功能，得来回切、上下文还串味。 `--worktree`（简写 `-w`）直接把这个问题干掉了。原理是 Git worktree：给每个 agent 会话分配一个**独立的工作目录 + 独立的分支**，共享同一份仓库历史，但文件改动互不污染。 ```bash # 三个终端，三条命令，三个 agent 并行干活 gemini -w feat-auth # agent A 专门改登录模块 gemini -w feat-search # agent B 专门改搜索 gemini -w fix-bug-77 # agent C 专门修 bug ``` 它在 `.gemini/worktrees/` 下创建独立目录，分支名就是你传的名字。退出（`/quit` 或 Ctrl+C）时，**Gemini 故意不删 worktree**，你的未提交改动、新 commit 全部保留，下次 `cd .gemini/worktrees/feat-auth && gemini --resume ` 直接续上。 注意这是 **experimental 功能**，要先开： ```json // ~/.gemini/settings.json { "experimental": { "worktrees": true } } ``` 或者在 CLI 里敲 `/settings` 搜 "Enable Git Worktrees" 设为 true。 信息差在哪？Claude Code 也能用 git worktree，但要自己手动 `git worktree add` 再切目录；Gemini CLI 把它做成了**一个 flag**，开箱即用。对中国开发者来说，这意味着你可以在一台 Mac 上同时跑一个"写前端"的 agent、一个"写后端 API"的 agent、一个"写测试"的 agent，三个一起推进，半天干完原本三天的活。 ```mermaid flowchart LR MAIN[主分支 main
共享历史] --> W1["gemini -w feat-auth"] MAIN --> W2["gemini -w feat-search"] MAIN --> W3["gemini -w fix-77"] W1 --> A1["agent A
独立目录+分支"] W2 --> A2["agent B
独立目录+分支"] W3 --> A3["agent C
独立目录+分支"] A1 --> PR[各自出 PR] A2 --> PR A3 --> PR PR --> MERGE[合并回 main] style MAIN fill:#fff,stroke:#333 style PR fill:#e8f5e9,stroke:#2e7d32 ``` ## 暗开关二：`/rewind` 或连按两次 Esc，时光倒流 AI 改坏了代码怎么办？大多数人选择手动 `git checkout` 或者干脆重启会话。Gemini CLI 给了个更优雅的方案：`/rewind`（或直接 **连按两次 Esc**）。 它会弹出一个交互列表，用上下箭头浏览历史每一步交互，并预览"这步 AI 改了几个文件"。选定后给你**三档选项**，这是关键： 1. **Rewind conversation and revert code changes** — 对话和文件改动一起回滚到那一步之前。 2. **Rewind conversation** — 只回滚对话，文件改动保留（适合"思路错了但代码还想留着"）。 3. **Revert code changes** — 只回滚文件，对话保留（适合"代码改崩了但想记住刚才聊到哪"）。 这个三档设计比"Ctrl+Z"高明得多。它的价值场景很具体：agent 跑偏了一条完整路线（比如你让它重构，它顺手把测试全删了），你不需要从头来过，只回退到"开始重构前"那一步，换个指令重走。 要提醒两个坑： - **rewind 只回滚 AI 用编辑工具做的改动**，你自己手动改的文件、以及用 shell 工具（`!` 命令）触发的改动，它管不了。 - 如果你只 revert 了代码、没回滚对话，**agent 不知道文件变了**，你得主动告诉它"文件已经改了"，否则它还按旧内容推理。 ## 暗开关三：Model Steering，agent 干活时直接插话 这个功能我第一次看到时愣了一下——**它允许你在 agent 还在转圈干活时，直接打字给它纠偏，而不用停下来重启**。 同样要先开 experimental 开关： ```json { "experimental": { "modelSteering": true } } ``` 开了之后，当 agent 正在执行任务（spinner 在转），你在输入框打字回车，**这段文字会作为 steering hint 直接注入到 agent 下一轮的 context 里**，它会重新评估当前计划并调整动作。典型用法： - **纠路径**："其实工具类在 `src/common/utils` 里。" → 它立刻停止满仓库乱搜。 - **跳步骤**："单测先别写，先把实现搞出来。" - **补上下文**："`User` 类型定义在 `packages/core/types.ts`。" - **改方向**："别再搜代码了，现在开始出方案。" 背后的机制挺聪明：CLI 用一个**小而快的模型**先生成一句"收到"的确认（让你知道指令被接住了），然后把你的 hint 加上一层内部指令，告诉主 agent"重新评估计划、判断这是新任务还是补充信息、用最小改动更新待办"。等于给 agent 装了一个**实时方向盘**。 对比 Claude Code：你要中断必须按 Esc 停掉重发。Model Steering 的差别是"不停、直接改航向"。对跑长任务（Plan Mode 重构、subagent 长链路）来说，能省下大量"停下来—改 prompt—重新跑"的来回。 ## 暗开关四：Headless 模式，把它当 CI 脚本引擎 很多人不知道 Gemini CLI 能**完全脱离终端 UI 跑**，这正是把它从"聊天工具"升级成"自动化基础设施"的入口。 两种触发方式：在非 TTY 环境运行，或用 `-p` / `--prompt` 直接给查询。 ```bash # 最简单：拿一句话文本结果 gemini -p "解释这个仓库的架构" # 结构化 JSON：response + stats（token、延迟） gemini -p "解释这个仓库的架构" --output-format json # 流式 JSONL 事件：可逐行解析，用于监控长任务 gemini -p "跑测试并部署" --output-format stream-json ``` `stream-json` 会吐出一连串事件：`init`（会话元数据、模型）、`message`（消息块）、`tool_use`（工具调用）、`tool_result`（工具输出）、`result`（最终结果+按模型拆分的 token 统计）。 最实用的是它的**退出码**，可以直接被 shell 脚本和 CI 判断： | 退出码 | 含义 | |--------|------| | `0` | 成功 | | `1` | 一般错误或 API 失败 | | `42` | 输入错误（prompt 或参数非法） | | `53` | **超过 turn 限制** | `53` 这个码特别值得记住——它告诉你"agent 跑到轮数上限还没干完"，脚本里可以据此自动重试或拆分任务。把这个能力和 GitHub Action 一结合（后面会讲），你就能搭出"PR 一开，Gemini 自动 review 并在评论里给修改建议"的流水线，全程不占你一个工时。 ## 暗开关五：`@mcp` 一句话调 GitHub、Slack、数据库 MCP（Model Context Protocol）是当下所有 AI agent 的标配扩展口，Gemini CLI 也支持。在 `~/.gemini/settings.json` 里配好 MCP server 后，你在对话里直接 `@服务名` 调用： ```text > @github 列出我所有 open 的 PR > @slack 把今天的 commit 摘要发到 #dev 频道 > @database 跑个查询，找出 30 天没登录的用户 ``` 信息差在于：大多数人的 MCP 还停留在"接个文件系统"，但海外开发者已经把 Gemini CLI 当成**自动化中枢**——连 GitHub 读 PR、连 Slack 发通知、连数据库出报表，一句话串起来。对一个独立开发者，这等于免费拥有一个"会读代码、会发消息、会查数据"的助理。 ## 暗开关六：`GEMINI.md` 给项目装长期记忆 这个概念和 Claude Code 的 `CLAUDE.md` 同源，但很多国内用户没用过。你在项目根目录放一个 `GEMINI.md`，写清楚：项目用了什么技术栈、代码风格约定、测试怎么跑、哪些目录不能动。**Gemini CLI 每次启动都会自动加载它**，相当于给 agent 一份永久的"项目说明书"。 进阶玩法是配合 **custom commands（自定义斜杠命令）**：把高频操作封装成 `/xxx`。比如你天天让 agent "按团队规范生成 API 文档"，就写成一个自定义命令，下次一句话触发。这是把"临时提问"变成"可复用资产"的关键一步。 ## 暗开关七：`@gemini-cli` GitHub Action，让 PR 自己被 review 最后这个偏"团队/开源"场景，但含金量极高。Google 官方提供了 **Gemini CLI GitHub Action**（`google-github-actions/run-gemini-cli`），在 issue 和 PR 里 `@gemini-cli` 提一下，它就会： - **自动 review PR**，给出带上下文的修改建议； - **自动给 issue 打标签、排优先级**； - 帮你 debug、解释代码、派发任务。 对维护开源项目的人，这是把免费的"代码审查员"塞进了 GitHub 流程。结合暗开关四的 headless 模式，整套自动化几乎零成本。 ## 信息差总结：你知道的 vs 别人不知道的 | 维度 | 多数人的认知 | 实际信息差 | |------|------------|-----------| | **价格** | "好用得付费" | OAuth 登录免费 1000 次/天 + Gemini 3 + 100万上下文 | | **省钱** | 全程全价 token | API Key 模式开 token caching，`/stats` 看节省 | | **并行** | 一个 agent 串行干 | `gemini -w` 一 flag 开多个工地并行 | | **容错** | 改坏就手动 git 回退 | `/rewind` 或 Esc Esc，对话/代码三档分别回滚 | | **纠偏** | 出错必须 Esc 重来 | Model Steering，干活时直接插话改航向 | | **自动化** | 只能交互式用 | `-p` + `stream-json` 当 CI 引擎，退出码 53 卡轮数 | | **扩展** | 只用来改本机代码 | `@mcp` 调 GitHub/Slack/DB；`@gemini-cli` 自动审 PR | ## 行动指南：今晚就能上手 1. **装起来**：`npx @google/gemini-cli`（免安装试）或 `npm install -g @google/gemini-cli`，个人 Google 账号登录，先白嫖。 2. **看账**：进去第一件事敲 `/stats`，建立 token 消费直觉。 3. **开两个 experimental 开关**：编辑 `~/.gemini/settings.json`，把 `worktrees` 和 `modelSteering` 都设 true，解锁并行工地和半路插话。 4. **建项目记忆**：在常做的项目根目录写一份 `GEMINI.md`，把技术栈和约定喂给它。 5. **试一个 worktree**：新开终端 `gemini -w play-xxx`，让它在隔离分支里随便改，体会"互不污染"的爽感。 6. **进阶搭 CI**：找个自己的仓库，挂上 `@gemini-cli` GitHub Action，下一个 PR 就有免费 review。 ## 参考来源 - Gemini CLI 官方仓库 README（免费额度、认证、安装）： - Git Worktrees 官方文档（`-w` 并行工地）： - Token Caching 与 `/stats`（API Key 才省钱）： - Rewind 文档（Esc Esc 时光倒流）： - Model Steering 文档（干活时插话）： - Headless 模式与退出码（`stream-json`、退出码 53）： - 官方免费课程（deeplearning.ai）： > 本文由「51学通信」技术团队出品。51学通信由通信行业18年老兵**爱卫生**（微信ID: gprshome201101）维护。 > 聚焦5G/6G核心网、3GPP标准、AI工具实战。知识星球「51学通信」提供深度技术答疑和行业洞察。 ### 完成摘要 **注意事项** - WebSearch/webReader MCP 本周额度已耗尽（2026-07-18 重置），本轮信息源改用 curl 直抓 raw GitHub + Context7（后者未授权，未用到）。所有硬事实（额度、token caching 限制、`-w`、`/rewind`、steering、退出码 53）均有官方文档背书，未编造数据。 - "token caching 省钱"只对 API Key/Vertex 生效、OAuth 无效——这一关键差异已在文中明确写出，避免误导。 > [!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 等场景全覆盖。