跳到正文

Gemini CLI：Google 官方开源的终端智能体

安装 Gemini CLI、完成登录，在命令行里用好内置工具和 MCP server——以及决定哪种方式适合你的免费层配额和身份验证选项。

当前有效最后核验

适用平台

  • Gemini CLI（macOS、Windows、Linux）

官方文档怎么说

  • Gemini CLI 是一个开源、Apache 2.0 许可的 AI 智能体，把 Gemini 直接带进终端，让你能在命令行里轻量地访问 Gemini。

    Get started with Gemini CLI

  • 用个人 Google 账号，免费层提供每分钟 60 次请求、每天 1,000 次请求，可以访问 Gemini 3 模型，上下文窗口达 100 万 token。

    Get started with Gemini CLI

  • 内置工具包括 Google 搜索联网、文件操作、Shell 命令和网页抓取；还支持 MCP（Model Context Protocol）用于自定义集成。

    Get started with Gemini CLI

  • 推荐的系统规格是 macOS 15+、Windows 11 24H2+ 或 Ubuntu 20.04+，Node.js 20.0.0+，以及 Bash、Zsh 或 PowerShell 中的一种 shell；轻度使用 4GB 以上内存即可，处理大型代码库、深度上下文这类重度使用场景建议 16GB 以上内存。

    Gemini CLI installation, execution, and releases

  • 标准安装方式是 `npm install -g @google/gemini-cli`；也可以不安装、直接用 `npx @google/gemini-cli` 运行，或者通过 Homebrew、MacPorts、Anaconda 安装。

    Gemini CLI installation, execution, and releases

  • 一共有三个发布渠道——stable（每周发布，默认的 latest 标签）、preview（每周发布，用 preview 标签安装）、nightly（每天从 main 分支构建，用 nightly 标签安装）。

    Gemini CLI installation, execution, and releases

  • 对个人 Google 账号，推荐的身份验证方式是 "Sign in with Google"——运行 gemini，选择 "Sign in with Google"，按浏览器流程完成；凭据会缓存在本地供后续会话使用。

    Gemini CLI authentication setup

  • 大多数个人 Google 账号身份验证时不需要设置 Google Cloud 项目；组织账号（公司、学校或 Google Workspace）需要设置。

    Gemini CLI authentication setup

  • 另一种身份验证方式是使用来自 Google AI Studio 的 Gemini API 密钥，设置为 GEMINI_API_KEY 环境变量——适用于 AI Studio 用户和无头（headless）模式。

    Gemini CLI authentication setup

  • 内置命令以斜杠（/）、艾特符号（@）或感叹号（!）开头；斜杠命令用于 CLI 的元层级控制，包括 /about（版本信息）、/auth（切换身份验证方式）、/bug（提交问题）、/agents（管理本地和远程子智能体，带 list、reload、enable、disable、config 子命令）。

    Gemini CLI commands reference

  • MCP server 通过 Model Context Protocol 向 Gemini CLI 暴露工具和资源，让它可以发现工具、用指定参数执行工具，并访问资源（如文件或 API 数据）；Gemini CLI 支持 Stdio、SSE 和 Streamable HTTP 三种 MCP server 传输方式。

    MCP servers with Gemini CLI

  • MCP 资源可以在对话中用引用本地文件同样的 @ 语法来引用，格式为 @server://resource/path。

    MCP servers with Gemini CLI

是什么

Gemini CLI 是 Google 官方的开源终端智能体，Apache 2.0 许可——从你 shell 里的一句提示词到 Gemini 模型之间最直接的路径，内置 Google 搜索联网、文件操作、Shell 命令和网页抓取，覆盖不到的地方还有 MCP 支持。用个人 Google 账号，免费层就能拿到每分钟 60 次、每天 1,000 次针对 Gemini 3 模型的请求，上下文窗口 100 万 token——不需要 API 密钥就能用到这些。

安装：好几条路径

推荐配置：macOS 15+、Windows 11 24H2+ 或 Ubuntu 20.04+；Node.js 20.0.0+；Bash、Zsh 或 PowerShell。轻度使用 4GB 以上内存就够；在大型代码库上重度使用，16GB 以上内存会更舒服。

标准安装：

npm install -g @google/gemini-cli

然后运行：

gemini

如果不想永久安装：

npx @google/gemini-cli

针对受限环境，还有基于 Homebrew（macOS/Linux）、MacPorts（macOS）和 Anaconda 的安装方式。

发布渠道

一共三个渠道。stable（latest 标签，也是默认版本）每周发布——是上一周 preview 版加修复之后的版本。preview 同样每周发布，但还没完全验证过，可能有回归问题。nightly 每天从 main 分支构建，应当假定存在待验证的问题。除非你确实想测试即将到来的改动，否则 npm install -g @google/gemini-cli 默认给你的 stable 就是你想要的。

完成身份验证

运行 gemini，选择一种身份验证方式：

  • Sign in with Google（大多数个人用户推荐）——按浏览器流程走一遍；之后凭据会缓存在本地。大多数个人账号不需要额外配置。组织账号——公司、学校或 Google Workspace——需要显式设置 Google Cloud 项目。

  • Gemini API 密钥——从 Google AI Studio 获取，然后导出：

    export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"

    这条路径适合已经是 AI Studio 用户的人，或者没有浏览器登录流程可用的无头/脚本化场景。

这是两条真正独立的路径——用的是哪一种，决定了适用哪种配额和计费方式，值得一开始就想清楚，而不是随便选一个先用着。

一开始就值得学的命令

内置命令用三种前缀：/ 用于 CLI 的元层级控制，@ 用于引用文件或 MCP 资源，! 用于 Shell 命令。几个从第一天就值得了解的斜杠命令：

  • /about —— 版本信息，提交 issue 时值得附上。
  • /auth —— 不用重启就能切换身份验证方式。
  • /bug —— 直接从当前会话向 Gemini CLI 的 GitHub 仓库提交问题。
  • /agents —— 管理子智能体，带 list、reload、enable、disable、config 子命令。

用 MCP server 扩展能力

MCP server 通过 Model Context Protocol 向 Gemini CLI 暴露工具和资源——用来连接数据库、内部 API，或任何内置工具覆盖不到的东西。Gemini CLI 支持 Stdio、SSE 和 Streamable HTTP 三种传输方式，配置好之后会自动发现对应工具。

server 接入之后，它的资源可以像本地文件一样被引用，只是用自己的协议前缀：

@server://resource/path

三个值得一试的终端工作流

按内容给文件改名。"根据实际内容给我 photos 目录下的照片重命名"——Gemini CLI 会先申请权限，然后根据每张图片里实际的内容完成重命名。

读代码库而不只是看 README。 指向一个公开仓库——"克隆 https://github.com/chalk/chalk 这个 chalk 仓库，阅读它的关键源码文件，解释它是怎么工作的"——它会克隆、阅读实际源码，然后给出总结。

自动化重复性的终端任务。 因为 Gemini CLI 可以在脚本里非交互式运行，查询 pull request 或者处理复杂的 rebase 这类操作性任务，都是官方文档给出的、超出交互式聊天之外的用法。

什么时候该用 CLI

如果任务本来就发生在终端里——读代码库、跑 Shell 命令、用文件或 Git 操作自动化某件重复的事——Gemini CLI 是最直接的工具。如果你想构建一个以编程方式调用 Gemini 的应用，看 Gemini API 入门；如果你想在更大的智能体里给 Gemini 配上它自己能调用的函数，看函数调用与工具。

实际操作

  1. 安装：npm install -g @google/gemini-cli（或者不装，直接用 npx @google/gemini-cli 运行）。
  2. 运行 gemini，选择身份验证方式——大多数个人账号用 Sign in with Google，AI Studio 用户或无头场景导出 GEMINI_API_KEY。
  3. 如果选了 Sign in with Google，按浏览器流程完成登录；凭据会缓存在本地供后续会话使用。
  4. 直接在终端里试一条提示词，按需用上内置的文件操作、Shell 命令、Google 搜索联网等工具。
  5. 如果内置工具不够用，接入一个 MCP server，然后用 @server://resource/path 引用它的资源。

Windows 步骤

  1. Windows 11 24H2+ 是推荐的系统版本；PowerShell 和 Bash、Zsh 一样是官方支持的 shell 之一。
  2. 安装和运行方式与其他平台一致——npm install -g @google/gemini-cli，然后运行 gemini。

手机步骤

不适用Gemini CLI 是面向 macOS、Windows、Linux 的终端工具；官方文档没有说明移动端客户端。

使用案例

  • 让 Gemini CLI 根据照片的实际内容给一个文件夹里的图片重命名，而不是自己一张张看着改。
  • 克隆一个不熟悉的开源仓库，让 Gemini CLI 读实际源码来解释它是怎么工作的，而不只是看 README。
  • 接入一个 MCP server，让 Gemini CLI 用上内置的文件、Shell、搜索工具之外，某个项目专属的工具或数据源。

常见错误

  • 以为随便哪个 Google 账号都能零配置拿到百万上下文的 Gemini 3 访问权限。组织账号（公司、学校、Google Workspace）需要显式设置 Google Cloud 项目——只有大多数个人账号才能跳过这一步。
  • 本来想要稳定版，却不小心装成了 preview 或 nightly 标签——preview 和 nightly 都可能有回归问题；大多数用户想要的是 stable（默认的 latest 标签）。
  • 不知道 GEMINI_API_KEY 和 "Sign in with Google" 是完全独立的两条身份验证路径——把两者搞混会导致不清楚到底适用哪种配额或计费方式。
  • 忘了 MCP server 暴露的资源用的是自己的 @server://resource/path 语法，跟引用本地文件的 @ 语法是分开的。

常见问题

Gemini CLI 免费吗？
用个人 Google 账号加免费层，是免费的——每分钟 60 次请求、每天 1,000 次请求，可以用 Gemini 3 模型，上下文窗口 100 万 token，不需要管理 API 密钥。
怎么安装？
标准方式是 npm install -g @google/gemini-cli，然后运行 gemini。也可以不安装，直接用 npx @google/gemini-cli 运行，或者用 Homebrew、MacPorts、Anaconda 安装。
应该用哪种身份验证方式？
对大多数个人开发者来说，在 gemini 命令里选 "Sign in with Google" 是推荐路径——不用管理 API 密钥。如果你已经是 AI Studio 用户，或者要以无头模式运行 Gemini CLI，就用 Gemini API 密钥。
Gemini CLI 能用内置之外的工具吗？
可以——它支持 MCP（Model Context Protocol）server，通过 Stdio、SSE 或 Streamable HTTP 传输暴露额外的工具和资源。接入之后，MCP server 的资源可以在对话里用 @server://resource/path 引用。
stable、preview、nightly 这三个渠道有什么区别？
stable 每周发布，也是 npm install -g @google/gemini-cli 默认安装的版本——是上一周 preview 版加上修复之后的完整晋级版本。preview 同样每周发布，但还没有完全验证过。nightly 每天从 main 分支构建，应当假定存在尚未验证的问题。

官方来源

这些是本教程对照核验的官方页面。需要厂商的原始措辞时请直接查阅。

来源状态