GeminiDesktop GeminiDesktop
教程指南

GeminiDesktop 上线 Gemini CLI 聊天模式：白嫖每天 1000 次 Gemini 2.5 Pro，免 API Key

发布于 · 作者： GeminiDesktop Team

GeminiDesktop 的聊天页（geminidesktop.app/chat）新增了一个小开关：CLI Toggle。打开它之后，你的每一条消息不再走 Gemini API，而是直接路由到本地已经登录过的 gemini CLI。这意味着 OAuth 登录即用，每天白嫖 60 RPM / 1000 RPD 的 Gemini 2.5 Pro 免费额度，彻底告别 BYOK API Key 那一长串 AIza...。

TL;DR 快速参考

  • 触发方式：GeminiDesktop 聊天页输入框上方工具栏 → 点击 Search / URL / Code 旁新增的「CLI」按钮
  • 鉴权方式：本地 ~/.gemini/tokens.json（OAuth），API Key 不再进入浏览器
  • 免费额度：个人 Google 账号，每分钟 60 次、每天 1000 次 Gemini 2.5 Pro，1M 上下文
  • 模型选择器：顶栏那个模型下拉无缝复用，选中的模型通过 --model <id> 传给 CLI；按钮上会显示「· via CLI」标识
  • 桌面端独占：只在 Tauri 桌面 app 里可用（浏览器里 toggle 置灰），因为网页端无法 spawn 子进程
  • 安装：bun add -g @google/gemini-cli，或 CLI 未装时 GeminiDesktop 会弹 Install 一键装
  • 底层选型：Headless 模式（gemini --output-format stream-json）而非 ACP，复用已有的 local_agent 事件管道
  • MVP 暂不支持：附件、Computer Use、Regenerate/Edit

输入框旁多了一个「CLI」开关

打开 GeminiDesktop 桌面 app，进入 /chat，输入框上方 Tools 栏里紧挨着 Search / URL / Code 三个 grounding toggle 的位置，新增了一个小按钮：CLI。

逻辑很直观：

  • 关闭（默认）：消息走 @ai-sdk/google 直连 Gemini API，使用设置里的 Gemini API Key（BYOK）
  • 开启：后续消息路由到你电脑上的 gemini CLI（headless 模式），用本地 OAuth token 鉴权

切换完全无感。不需要重启应用、不需要重新登录、不需要清空历史。之前 API 模式下的对话原样保留，从下一条消息开始走 CLI。

**顶栏模型选择器原封复用。**那个熟悉的「Gemini 3.1 Pro / 3.0 Flash / 2.5 Pro / 2.5 Flash / Flash Lite」下拉框，在 CLI 模式下照常工作——选哪个模型就通过 --model <id> 传给 CLI（Gemini CLI 官方文档确认支持该 flag）。为了让你一眼看出当前走的是 CLI 路径，模型名右边会多一行低调的灰色「· via CLI」后缀。

三个切过去的实打实好处

1. 免费额度：OAuth 登录即用，每天 1000 次 Gemini 2.5 Pro

这是大多数人翻开关的主要原因。

根据 Google 官方公告，个人 Google 账号登录 Gemini CLI 后，自动获得免费的 Gemini Code Assist license，可用 Gemini 2.5 Pro：

  • 每分钟 60 次请求
  • 每天 1000 次请求
  • 100 万 token 上下文窗口

对比 BYOK 路径：要么去 Google AI Studio 申请 API Key 然后小心管理，要么薅 Google Cloud 新客户 $300 赠金。CLI 模式直接跳过这一切。一次 OAuth 浏览器授权后，token 存在 ~/.gemini/tokens.json，GeminiDesktop 调用 CLI 时由 CLI 自己读取。你的 API Key 既不进浏览器，也不进 GeminiDesktop 的任何存储。

2. 本地权限：Gemini 不只是说，还会动手

CLI 模式的第二个价值：Gemini 能调用本地工具。

纯 API 的聊天里，Gemini 只能“说”——告诉你怎么做，让你自己执行。CLI 的聊天里，Gemini 可以读文件、写文件、跑 shell 命令。它成了一个真正意义上的本地 agent。

几个日常场景：

  • 「帮我整理 Downloads 里所有 PDF 的标题」：CLI 模式下 Gemini 直接跑 ls ~/Downloads/*.pdf，读 metadata，给你一张表
  • 「这个项目里 TypeScript 报错是什么」：不用再粘贴错误日志，Gemini 自己 cd 到目录、跑 tsc --noEmit、读输出、定位问题
  • 「把这段会议录音转成 Markdown」：Gemini 读本地文件，调用系统命令处理，写出结果

为了安全，默认 permissionMode 是 default 而非 --yolo——CLI 不会擅自改文件，每次敏感操作（写文件、执行命令）在 CLI 层会提示确认。想完全放权的用户可以在设置里切到 YOLO 模式，但默认保守。

3. 流式渲染：和 API 路径长得一模一样

你可能担心：CLI 是独立进程，它的输出会不会在聊天气泡里变成一团乱码？

不会。底层复用的是 GeminiDesktop 已有的成熟事件管道：CLI 的 stream-json 输出在 Rust 侧被解析成统一的消息格式，通过 Tauri event 实时推到前端，再由适配器映射为聊天消息的 parts 更新，最终在原本的聊天气泡组件里渲染。

**UI 层面：API 模式和 CLI 模式长得完全一致。**工具调用（read_file、run_shell）以可折叠的卡片呈现，点开能看输入 JSON 和输出文本。思考过程（Thinking）是淡色的独立气泡。流式文本和 API 模式一样边生成边打字。唯一可见差异就是顶栏那个不起眼的「· via CLI」后缀。

3 步上手

步骤 1：安装 gemini CLI

两种方式，任选其一：

# 方式 A：自己跑命令
bun add -g @google/gemini-cli
# 或 npm install -g @google/gemini-cli

或者在 GeminiDesktop 里一键装：第一次打开 CLI 开关时，如果检测到本地没装 CLI，会弹一个带「Install」按钮的 toast，点一下自动跑上面那条命令。

步骤 2：首次 OAuth 登录

终端里跑：

gemini

浏览器自动打开 Google 登录页，用你的个人 Google 账号授权。完成后 token 写到 ~/.gemini/tokens.json，以后 GeminiDesktop 调用 CLI 都会自动读这个文件，不需要再登录。

步骤 3：打开「CLI」开关

进入 geminidesktop.app/chat，点击输入框工具栏里的「CLI」按钮，变成高亮蓝色 = 已开启。正常发消息就行，第一条消息会看到顶栏显示「Gemini 3.x Pro · via CLI」——说明 CLI 接管了。

本次 MVP 的边界（诚实告知）

✅ 支持：

  • 文字聊天（全部 Gemini 模型可选）
  • 模型切换（顶栏选什么 → CLI --model 用什么）
  • 工具调用流式渲染（read_file / run_shell / code_execution 等）
  • Stop 按钮随时中止 CLI 进程
  • 多轮上下文（prompt-prefix 拼接历史，见下一节）

❌ 暂不支持：

  • 附件上传：CLI 需要文件路径，但浏览器里的图片/PDF 是 blob。把 blob 写到 tmp 文件的胶水层还没写，MVP 版打开 CLI 模式时附件会被阻止。等后续补齐
  • Computer Use：这里容易混——Gemini Computer Use 是 Gemini 3.1 Pro API 的能力（模型截图 + 自动操作桌面），不是 CLI 的能力。Gemini CLI 自身并不暴露 Computer Use 工具。我们后续会把 Computer Use 作为独立 feature 上线，走 API 路径，和 CLI toggle 是两条平行的路
  • Regenerate / Edit 消息：CLI 模式下的 assistant 消息暂时不支持「重新生成」或「编辑后重跑」，这两个按钮在 CLI 气泡上会置灰。后续会补

🔮 未来规划： 如果 Gemini CLI 放出 headless --resume <id> flag 或正式的 ACP 集成，会切换到原生会话状态管理。当前的 prompt-prefix 拼接是务实的替代方案。

为什么是 Headless 而不是 ACP

给技术口味的同学补一段选型背景。

把 Gemini CLI 嵌入聊天 UI 有两条路：

Headless 模式（gemini --output-format stream-json）：每条消息 spawn 一个 CLI 子进程，stdout 吐 stream-json 事件，进程结束本轮结束。多轮上下文手动拼接历史——把之前的 user/assistant 消息作为前缀，和新问题一起喂给 CLI。

ACP 模式（Agent Client Protocol）：启动一个长驻 JSON-RPC 子进程，通过 initialize / newSession / prompt / cancel 等 method 与 CLI 对话。原生多轮状态、loadSession 会话恢复、MCP 工具广播——功能更完整，但实现成本也大得多。

我们选了 Headless，理由很实在：

  1. 复用成熟管道：GeminiDesktop 底层的 local_agent 模块已经用 Headless 跑了近一年 Claude Code、OpenCode、Codex、Cursor 等 CLI。事件桥、消息协议、错误处理、Stop 按钮都现成，接入 Gemini CLI 只需要扩展一个 executor
  2. 时间成本差距：Headless 约 1 周上线；ACP 要写 JSON-RPC 客户端、处理进程生命周期、实现 MCP 服务广播（因为 ACP 里 Gemini CLI 期望 host 托管文件 I/O），周期约 1 个月
  3. Headless 够用：per-turn spawn 开销 150-300ms，对聊天 UX 可接受；多轮 prompt-prefix 拼接虽然每次要重传历史，但 Gemini 2.5 Pro 的 1M 上下文对这点冗余完全不敏感

结论：Headless 先上，ACP 留作后续升级。如果用户体感真被 per-turn 延迟或取消语义拖累再切。

和 Claude Desktop / ChatGPT 对比

GeminiDesktop 的底层 local_agent 模块其实也支持 Claude Code、OpenCode、Codex、Cursor 等多个 CLI。核心差异：

  • Gemini CLI（本次新增）：个人 Google 账号免费（1000 次/天），OAuth 登录即用；长上下文（1M token）优势明显
  • Claude Code：需 Anthropic API 订阅或 Pro 订阅，付费路径；推理能力顶尖

具体怎么选：日常聊天 / 长上下文 / 想白嫖 → Gemini CLI；复杂代码编辑 / Claude 生态用户 → Claude Code。两者可以在同一个 GeminiDesktop 安装里并存，设置里切换默认 agent。

如果你之前用的是 Claude Desktop 或 ChatGPT 桌面端，可以看 从 Claude Desktop 迁移到 Gemini for Mac 的完整指南——结合 GeminiDesktop 的 CLI 模式，能把 Claude 的付费额度彻底省下来。

FAQ

Q1: CLI 模式下我的聊天内容会上传到哪里？

和直连 Gemini API 一样，内容通过 gemini CLI 发送到 Google 的 Gemini 服务器。区别在于：

  • 鉴权：走你本地的 OAuth token，不需要把 API Key 存在浏览器里
  • 数据路径：GeminiDesktop → 本地 CLI 进程 → Google Gemini API（中间没有第三方后端）
  • 消息历史：保存在本地 IndexedDB，不上传任何服务器

Q2: 能同时用 CLI 模式和 API 模式吗？

可以。Toggle 随时切换，两种模式的消息在同一个会话里自然混合。常见混用姿势：日常轻聊用 API 模式 + Flash Lite（便宜、响应快），需要 Gemini 操作本地文件 / 跑代码 / 长推理的时候切到 CLI 模式 + 2.5 Pro。

Q3: 切过去后没反应或报错怎么办？

三种常见原因：

  1. CLI 没装：Toggle 会弹 Install 提示，点「Install」一键装，或自己跑 bun add -g @google/gemini-cli
  2. CLI 没登录：看到「Gemini CLI 未认证」toast，终端跑 gemini 完成 OAuth 授权
  3. 你在网页版而不是桌面 app：Toggle 在浏览器里是灰态。下载 GeminiDesktop 装桌面版

Q4: CLI 模式能代替 Gemini Canvas 或 NotebookLM 吗？

不能，它们是互补关系。Canvas 专注网页/信息图/测验等创作模板，参见 Gemini Canvas 桌面版介绍；NotebookLM 是知识库 RAG 工具，核心是多源文档问答。CLI 模式更适合“让 Gemini 帮我在本地文件系统里做事”的场景——文件整理、代码调试、命令执行、长文本推理。

Q5: Windows 上能用吗？

能。GeminiDesktop 本身支持 macOS 和 Windows 双平台（Tauri 打包），CLI 模式两边通用。如果你还在评估 Windows 下的 Gemini 体验，可以看 Google 为什么还没做 Gemini Windows 原生 app 的讨论。

总结

一个小小的 toggle，把 Google 的免费配额带进了 GeminiDesktop 的聊天体验：无付费 API Key、无终端折腾、无重写模型选择器。对「想用 Gemini 2.5 Pro 但不想折腾 API Key」的用户，这是最低摩擦的路径。

MVP 先跑起来，附件、Computer Use、ACP 模式等升级会作为后续独立 feature 陆续上线。立刻试试：geminidesktop.app/chat。