Gemini CLI Deep Dive — Google 终端 AI Agent 深度解析

M0 项目概览与定位

Google 官方开源的终端 AI Agent，以极致慷慨的免费额度和 1M token 上下文为核心差异化，在 CLI Coding Agent 领域异军突起。

基本信息

属性	详情
名称	Gemini CLI (`@google/gemini-cli`)
开源协议	Apache-2.0
语言 / 运行时	TypeScript / Node.js ≥ 18
GitHub Stars	96,000+（发布 2 周内）
仓库	`google-gemini/gemini-cli`
首次发布	2025-06-25（Google I/O 2025 后续）
安装方式	`npx @google/gemini-cli` / npm / Homebrew / MacPorts / Anaconda

核心差异化

Gemini CLI 最大的竞争力不是功能最全面，而是 免费额度极其慷慨：使用 Google 账号登录即可获得 60 req/min、1,000 req/day 的 Gemini 2.5 Pro 额度，无需信用卡，无需 API Key。这意味着个人开发者和学生可以零成本使用顶级模型进行日常编程。

免费额度

60 req/min
1,000 req/day
Gemini 2.5 Pro 模型
Google OAuth 登录即用
无需信用卡

1M Token 上下文

超大代码库分析
长文件完整理解
跨文件关联推理
Token Caching 降低延迟

Google 生态集成

内置 Google Search grounding
Vertex AI 企业版支持
GitHub Action 官方集成
多模态（PDF/图片/草图）

VS 竞品对比

维度	Gemini CLI	Claude Code	OpenAI Codex CLI
开源协议	Apache-2.0	Source-available (BUSL)	Apache-2.0
核心模型	Gemini 2.5 Pro / Flash	Claude Sonnet 4 / Opus 4	codex-mini (o4-mini)
免费额度	60 req/min, 1000/day	无（按 token 计费）	有限（$5/月 Plus）
上下文窗口	1M tokens	200K tokens	192K tokens
语言 / TUI	TypeScript / Ink (React)	TypeScript / Ink (React)	TypeScript / Ink (React)
沙箱方案	Seatbelt / Docker / gVisor / LXC	macOS Seatbelt	Docker (强制)
MCP 支持	Stdio / SSE / Streamable HTTP	Stdio / SSE	有限
多模态	PDF / 图片 / 草图	图片	图片（有限）
特色功能	Google Search grounding / 子代理 / Browser Agent	Extended Thinking / 多模态截图 / 成熟度最高	强制沙箱 / 专注安全
扩展系统	Extensions（主题/钩子/技能/命令/MCP）	Skills + Hooks + MCP	基础
成熟度	快速迭代中	最成熟	Preview

选择建议：追求零成本 + 超大上下文选 Gemini CLI；追求代码质量 + 最成熟生态选 Claude Code；追求极致安全隔离选 Codex CLI。三者底层架构高度相似（都是 TypeScript + Ink TUI + Agent Loop），可以并行使用、互补切换。

多模态能力

Gemini CLI 支持多种文件格式的理解和处理：

图片：拖入终端或 @image.png 引用，支持 PNG/JPG/WebP/GIF
PDF：使用 @document.pdf 引用 PDF 文件进行分析
草图 → 应用：拍照手绘线框图，直接生成前端代码
截图分析：分析 UI 截图、错误截图，提供修复建议

信息来源: github.com/google-gemini/gemini-cli | Google 官方博客

M1 核心架构

TypeScript Monorepo 三包结构：CLI 渲染层、Core 引擎层、A2A 服务层。Agent Loop 驱动工具调用循环，子代理系统处理专门任务。

Monorepo 三包结构

CLI packages/cli -- Ink/React TUI 渲染层，负责终端 UI、用户交互、命令路由 Ink + React

IMPORTS

Core packages/core -- Agent Loop 引擎、工具系统、MCP、记忆、安全策略 Agent Engine

EXPORTS

A2A packages/a2a-server -- Agent-to-Agent 服务层，支持 Google A2A 协议 A2A Protocol

CLI 层 (packages/cli)

Ink + React：使用 React 组件模型渲染终端 UI
命令路由：解析 / 前缀斜杠命令和 @ 文件引用
主题系统：通过 Extensions 支持自定义终端主题
输入处理：多行编辑、Vim Mode、快捷键绑定

Core 层 (packages/core)

Agent Loop：核心循环引擎，驱动「用户输入 → 模型推理 → 工具调用 → 结果返回」
Tool System：15 个内置工具 + MCP 动态工具
ModelAvailabilityService：健康监控 + 自动降级
Safety：沙箱管理、Policy Engine、信任文件夹
Memory：save_memory 工具 + GEMINI.md 系统
Checkpointing：Git shadow repo 自动快照

Agent Loop 流程

子代理系统 (Experimental)

Gemini CLI 引入了实验性的子代理（Sub-agents）系统，用于处理特定领域任务。子代理有独立的系统提示和工具约束：

codebase_investigator

代码库调查专家，擅长分析代码结构、依赖关系、调用链路。使用只读工具集（read_file / grep / glob），不修改文件。

cli_help

CLI 帮助代理，解答 Gemini CLI 自身的使用问题。内嵌产品文档，快速回答 /help 相关查询。

generalist_agent

通用子代理，可以被主代理委派执行任何任务。用于需要保护主上下文不被大量信息污染的场景。

browser_agent (Experimental)

浏览器代理，基于 Puppeteer 实现，可以导航网页、截图、提取内容。需要 npm i puppeteer 安装依赖。

模型路由与健康监控

ModelAvailabilityService 是模型选择的核心组件，负责：

健康检查：周期性探测每个模型端点的可用性
自动降级：当 Pro 不可用时自动降级到 Flash，再到 Flash-Lite
速率限制处理：收到 429 后自动切换到备选模型
用户感知：在终端显示当前使用的模型和降级原因

模型标识	实际模型	适用场景
`auto`	系统自动选择最优可用模型	默认推荐
`pro`	Gemini 2.5 Pro	复杂编程、架构设计
`flash`	Gemini 2.5 Flash	快速迭代、简单任务
`flash-lite`	Gemini 2.0 Flash-Lite	极速响应、高吞吐

vs Claude Code — 核心架构对比

维度	Gemini CLI	Claude Code
代码结构	TypeScript monorepo (packages/cli + core + a2a-server)	TypeScript 单体
TUI 框架	Ink / React	Ink / React
模型回退	ModelAvailabilityService 自动回退链	无自动回退
子代理	4 个内置子代理 (codebase_investigator, cli_help, generalist_agent, browser_agent)	Agent tool 动态生成任意类型子代理
浏览器代理	内置 browser_agent	无内置，需 MCP

Gemini CLI 优势

模型健康监测 + 自动回退，不怕单模型宕机
内置浏览器代理，无需额外配置
monorepo 结构更适合社区贡献

Claude Code 优势

更灵活的子代理生成（按需创建任意类型）
Claude 模型编码质量更优
生态更成熟，工具调用更可靠

信息来源: packages/core 源码 | architecture.md

M2 核心功能模块

15 个内置工具覆盖文件操作、搜索、执行、记忆四大类别，配合 Plan Mode、Checkpointing、Session 管理等高级功能。

15 个内置工具

文件操作

read_file

read_many_files

write_file

replace

list_directory

搜索与导航

glob

grep_search

google_web_search

web_fetch

执行与交互

run_shell_command

ask_user

write_todos

记忆与技能

save_memory

get_internal_docs

activate_skill

工具名	功能描述	关键参数
`read_file`	读取单个文件内容，支持行范围	`file_path`, `start_line`, `end_line`
`read_many_files`	批量并行读取多个文件	`file_paths[]`
`write_file`	创建或完整覆写文件	`file_path`, `content`
`replace`	精确替换文件中的指定内容	`file_path`, `old_string`, `new_string`
`list_directory`	列出目录内容（包含大小和类型）	`directory_path`
`glob`	按模式搜索文件名	`pattern`, `path`
`grep_search`	正则搜索文件内容	`query`, `path`, `include`
`run_shell_command`	在终端执行 shell 命令	`command`, `directory`
`ask_user`	向用户提问并等待回复	`question`
`write_todos`	创建/更新任务清单（持久化）	`todos[]`
`save_memory`	保存信息到持久记忆（GEMINI.md）	`key`, `value`
`get_internal_docs`	获取 Gemini CLI 内部文档	`topic`
`activate_skill`	激活注册的技能	`skill_name`
`google_web_search`	Google 搜索（带 grounding）	`query`
`web_fetch`	抓取网页内容	`url`

与 Claude Code 的工具设计对比：Gemini CLI 的 replace 对应 CC 的 Edit（精确字符串替换），read_many_files 是 CC 没有的批量读取工具。最大差异是 google_web_search -- Gemini CLI 内置了 Google 搜索 grounding，而 CC 需要通过 MCP 或 WebSearch 工具。

Plan Mode（只读研究模式）

Plan Mode 是一种只读安全模式，Agent 只能使用搜索和读取工具，不能写入文件或执行命令：

可用工具：read_file, read_many_files, glob, grep_search, list_directory, google_web_search, web_fetch
禁用工具：write_file, replace, run_shell_command
激活方式：启动时 gemini --plan 或运行中 /plan 切换
用途：代码审查、架构分析、需求调研、安全审计

$ gemini --plan > 分析这个项目的架构，找出所有的安全隐患 # Agent 只能读不能写，安全进行代码审计

Checkpointing（Git 影子仓库快照）

Gemini CLI 在每次文件修改前自动创建 Git 快照，实现无损回滚：

Shadow Repo：在 .gemini/shadow-repo/ 下创建独立的 Git 仓库
自动快照：每次 write_file / replace / run_shell_command（有写操作）前自动提交
Rewind：按 Esc 两次触发时间旅行 UI，查看每个快照的文件变更
恢复：选择任意历史快照恢复文件状态

Rewind 快捷操作：连续按两次 Esc 进入 Rewind 模式。这不仅撤销 Agent 的修改，还能查看每一步的 diff，帮助理解 Agent 的决策链路。类似于 Claude Code 的 /undo，但有完整的时间线 UI。

Session Management

会话管理支持跨终端窗口恢复上下文：

命令	功能
`gemini --resume`	恢复上次会话
`gemini --resume <session_id>`	恢复指定会话
`/save <title>`	保存当前会话
`/load <title>`	加载已保存的会话
`/sessions`	列出所有已保存的会话
`/history`	查看当前会话的完整对话历史

其他高级功能

Token Caching

自动缓存系统提示和工具定义，减少重复 token 传输。对于长会话可节省 30-50% 的 token 消耗和延迟。

Vim Mode

通过 /vim 命令或 settings.json 启用 Vim 键位绑定。支持 Normal/Insert/Visual 模式，适合 Vim 用户在终端中高效编辑提示词。

Browser Agent (Experimental)

基于 Puppeteer 的浏览器自动化代理。可以导航网页、截取截图、填写表单、提取数据。需要单独安装 puppeteer。

Headless Mode

支持三种无头输出格式：text（纯文本）、json（结构化 JSON）、stream-json（流式 JSON）。用于 CI/CD 集成和脚本自动化。

# Headless 模式示例 $ echo "解释这个函数" | gemini --output text $ gemini --output json -p "列出所有 TODO" $ gemini --output stream-json -p "重构这段代码" | jq '.text'

vs Claude Code — 核心功能对比

功能	Gemini CLI	Claude Code
内置工具数	15 个	相近数量
Web 搜索	google_web_search 内置 (Google Search grounding)	需 MCP 接入
Checkpointing	Git shadow repo 自动快照	无自动检查点
Token Caching	内置（复用 system instructions）	依赖 Anthropic prompt caching
Plan Mode	只读研究模式，Shift+Tab 切换	有 plan 模式但集成度较低
Rewind	Esc×2 回滚对话 + 代码变更	无 rewind 能力
编码质量	Gemini 2.5 Pro	Claude Sonnet/Opus 编码更可靠
工具执行	偶有不稳定	工具调用更稳定可靠

Gemini CLI 优势

Google Search grounding — 独家实时搜索能力
Git 自动检查点，修改可安全回滚
Rewind 功能一键回退对话和代码
内置 Token Caching 降低延迟

Claude Code 优势

模型编码质量更高（Claude > Gemini for coding）
工具执行更稳定可靠，错误率更低

信息来源: docs/cli/commands.md | docs/features/

M3 安全与沙箱

四种沙箱方案覆盖 macOS / Linux / 容器环境，Policy Engine 提供细粒度权限控制，审批模式从严格到全自动可调节。

四种沙箱方案

macOS Seatbelt

平台：macOS
原理：使用 macOS 内置的 sandbox-exec 系统调用，通过 .sb profile 限制进程权限。
限制：仅允许读/写工作目录、网络访问白名单、禁止访问 Keychain 和系统偏好。
配置：sandbox: { type: "seatbelt" }

Docker / Podman

平台：全平台
原理：在容器中运行 shell 命令，完全隔离文件系统和网络。
特点：可自定义 Dockerfile 预装工具、挂载工作目录为 volume。
配置：sandbox: { type: "docker", image: "node:20" }

gVisor (runsc)

平台：Linux
原理：Google 开发的应用内核，拦截系统调用提供更强隔离。
特点：比 Docker 更安全（用户态内核），性能开销可接受。
配置：sandbox: { type: "gvisor" }

LXC / LXD

平台：Linux
原理：操作系统级虚拟化，每个会话一个容器。
特点：完整 Linux 环境、支持持久化容器、资源限制 (cgroups)。
配置：sandbox: { type: "lxc" }

Gemini CLI 的沙箱方案是目前 CLI Coding Agent 中 最丰富的：4 种方案覆盖不同安全级别和平台。对比 Claude Code（仅 Seatbelt）和 Codex CLI（仅 Docker），Gemini CLI 提供了更灵活的安全选择。生产环境推荐 Docker + gVisor 双层隔离。

信任文件夹配置

通过 settings.json 配置信任目录，控制 Agent 的文件访问范围：

{ "trustedFolders": [ "/Users/me/projects/my-app", "/Users/me/projects/shared-lib" ] }

信任文件夹内的操作 自动批准（根据审批模式）
信任文件夹外的操作 始终询问
首次进入新目录时 Gemini CLI 会提示是否信任

Policy Engine（TOML 规则引擎）

Policy Engine 是 Gemini CLI 最强大的安全特性之一，使用 TOML 文件定义细粒度权限规则：

# .gemini/policies/security.toml # 允许读取所有文件 [[rule]] tool = "read_file" action = "allow" # 允许写入 src 目录 [[rule]] tool = "write_file" action = "allow" condition = { path_prefix = "src/" } # 禁止删除 node_modules [[rule]] tool = "run_shell_command" action = "deny" condition = { command_pattern = "rm.*node_modules" } # 危险命令需要用户确认 [[rule]] tool = "run_shell_command" action = "ask_user" condition = { command_pattern = "git push|npm publish|docker push" }

规则动作

动作	行为	适用场景
`allow`	自动批准	安全操作（读文件、搜索）
`deny`	静默拒绝	危险操作（删除生产数据）
`ask_user`	弹出确认	需审批的操作（git push）

四种审批模式

default

写文件：询问
Shell 命令：询问
MCP 工具：询问
推荐日常使用，安全与效率平衡。

auto_edit

写文件：自动批准
Shell 命令：询问
MCP 工具：询问
信任文件编辑但谨慎执行命令。

yolo

写文件：自动批准
Shell 命令：自动批准
MCP 工具：自动批准
全自动，适合沙箱环境或 CI/CD。

plan

写文件：禁止
Shell 命令：禁止
MCP 工具：只读
只读模式，用于安全审计和分析。

安全提醒：yolo 模式在非沙箱环境下极其危险。建议仅在 Docker 容器内或 CI/CD 管道中使用。生产环境推荐 default 模式 + Policy Engine 自定义规则。

vs Claude Code — 安全与沙箱对比

维度	Gemini CLI	Claude Code
沙箱选项	4 种：Seatbelt / Docker / gVisor / LXC	容器级沙箱
最强隔离	gVisor（用户态内核）	无 gVisor 等价方案
权限策略	Policy Engine (TOML 规则, allow/deny/ask_user + regex)	Tool-level 权限 + Hooks 自定义策略
审批模式	default / auto / yolo 三级	类似分级
配置复杂度	功能多但配置项较多	开箱即用，配置简单

Gemini CLI 优势

沙箱方案最丰富（4 种覆盖不同安全级别和平台）
Policy Engine 灵活度高（TOML + regex 精确匹配）
gVisor 提供最强隔离（用户态内核拦截系统调用）

Claude Code 优势

开箱即用，大多数场景无需复杂配置
Hooks 机制可实现等价的自定义安全策略

信息来源: docs/security/ | docs/cli/sandboxing.md

M4 配置与扩展

7 层配置优先级、GEMINI.md 三层加载、MCP 三种传输、Extensions 六大类型、11 个钩子生命周期事件，构成了极其灵活的扩展体系。

7 层配置优先级

配置从低到高，高优先级覆盖低优先级：

L1 内置默认值 -- 代码中硬编码的默认配置 Lowest

L2 系统默认 -- 系统级 settings.json /etc/gemini/

L3 用户配置 -- ~/.gemini/settings.json ~/.gemini/

L4 项目配置 -- .gemini/settings.json（项目根目录） .gemini/

L5 系统覆盖 -- 系统管理员强制覆盖 Override

L6 环境变量 -- GEMINI_* 前缀环境变量 ENV

L7 CLI 参数 -- 命令行直接传入的参数 Highest

settings.json 核心参数

▶ settings.json 完整参数列表 20+ 参数

参数	类型	默认值	说明
`model`	string	`"auto"`	模型选择: auto / pro / flash / flash-lite / 自定义模型名
`theme`	string	`"default"`	终端主题
`sandbox`	object	`{ type: "seatbelt" }`	沙箱配置
`approvalMode`	string	`"default"`	审批模式: default / auto_edit / yolo / plan
`trustedFolders`	string[]	`[]`	信任文件夹列表
`mcpServers`	object	`{}`	MCP 服务器配置
`extensions`	object	`{}`	扩展配置
`customInstructions`	string	`""`	自定义系统提示
`tokenCaching`	boolean	`true`	Token 缓存开关
`checkpointing`	boolean	`true`	Git 快照开关
`vimMode`	boolean	`false`	Vim 键位绑定
`maxTokens`	number	`65536`	单次回复最大 token 数
`temperature`	number	`0.7`	模型温度
`telemetry`	boolean	`true`	遥测数据收集

GEMINI.md 三层加载

GEMINI.md 是 Gemini CLI 的项目指令系统，类似于 Claude Code 的 CLAUDE.md：

层级	路径	用途
全局	`~/.gemini/GEMINI.md`	用户级通用指令，适用所有项目
项目	`.gemini/GEMINI.md`	项目级指令，可提交到 Git
JIT (Just-In-Time)	通过 `@./path` 动态导入	按需加载的模块化指令

模块化导入

GEMINI.md 支持使用 @./path 语法导入其他 Markdown 文件，实现模块化组织：

# GEMINI.md ## 项目规范 @./docs/coding-standards.md ## API 文档 @./docs/api-reference.md ## 架构设计 @./docs/architecture.md

/init 自动生成

运行 /init 命令可以自动扫描项目结构，生成 GEMINI.md 初始内容：

自动检测项目类型（前端/后端/全栈）
识别技术栈（React/Vue/Node/Python 等）
扫描 README、package.json、tsconfig 等配置
生成项目概述、目录结构、开发命令等初始指令

MCP 支持

Gemini CLI 支持 Model Context Protocol 的三种传输方式：

Stdio

最常见的方式，通过进程标准输入/输出通信。适合本地工具。

{ "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@mcp/fs"] } } }

SSE (Server-Sent Events)

通过 HTTP SSE 连接远程服务器。适合云端部署的 MCP 服务。

{ "mcpServers": { "remote": { "url": "https://mcp.example.com/sse" } } }

Streamable HTTP

最新的 MCP 传输协议，支持双向流式通信。

{ "mcpServers": { "stream": { "url": "https://mcp.example.com/stream", "transport": "streamable-http" } } }

@server 语法

在对话中使用 @server_name 语法直接引用特定 MCP 服务器的工具：

> @github 创建一个新的 issue，标题是 "修复登录 bug" > @filesystem 列出 src 目录下所有文件

OAuth 认证

对于需要认证的 MCP 服务器，Gemini CLI 支持 OAuth 流程，自动打开浏览器完成授权。

Extensions 扩展系统

Gemini CLI 的扩展系统包含六大类型，统一通过 settings.json 或 npm 包安装：

类型	功能	示例
Prompts	预定义提示模板	代码审查模板、PR 描述生成
MCP	MCP 服务器集成	GitHub、Slack、数据库连接
Commands	自定义斜杠命令	`/deploy`、`/test`
Themes	终端主题样式	颜色方案、图标风格
Hooks	生命周期事件钩子	工具调用前/后拦截
Sub-agents	自定义子代理	专业领域分析代理

技能系统 (Skills)

Gemini CLI 采用 AgentSkills.io 开放标准的技能系统：

渐进式披露：技能只在需要时才加载到上下文，避免 token 浪费
activate_skill 工具：Agent 通过工具调用主动激活技能
技能注册：在 .gemini/skills/ 目录下放置 Markdown 文件
技能内容：可包含系统提示、工具定义、示例对话

# .gemini/skills/react-component.md --- name: React Component Generator description: Generate React components with TypeScript and Tailwind triggers: - "create component" - "new component" --- ## 规则 1. 使用 TypeScript + React.FC 2. Props 接口单独导出 3. 使用 Tailwind CSS 样式 4. 包含基本的 Storybook story

钩子系统（11 个生命周期事件）

▶ 完整的 11 个钩子生命周期事件 11 events

事件名	触发时机	可用数据
`session_start`	新会话开始时	session ID, CWD, model
`session_end`	会话结束时	session ID, duration, token usage
`pre_tool_call`	工具执行前	tool name, parameters
`post_tool_call`	工具执行后	tool name, result, duration
`pre_model_call`	模型 API 调用前	messages, model, temperature
`post_model_call`	模型 API 调用后	response, token usage, latency
`user_input`	用户输入消息时	message content, attachments
`model_response`	模型返回响应时	response text, tool calls
`error`	发生错误时	error type, message, stack
`checkpoint`	创建检查点时	checkpoint ID, files changed
`approval_request`	请求用户审批时	tool name, parameters, risk level

钩子配置示例：

# .gemini/hooks/log-tools.sh #!/bin/bash # 记录所有工具调用到日志 echo "[$(date)] Tool: $GEMINI_TOOL_NAME Args: $GEMINI_TOOL_ARGS" >> ~/.gemini/tool-log.txt

# settings.json { "hooks": { "post_tool_call": { "command": ".gemini/hooks/log-tools.sh" } } }

认证方式

方式	配置	适用场景
Google OAuth	首次运行自动触发浏览器登录	个人开发者（推荐，免费额度）
API Key	`GEMINI_API_KEY` 环境变量	脚本/CI/CD 自动化
Vertex AI	`GOOGLE_CLOUD_PROJECT` + ADC	企业用户（GCP 计费）

# Google OAuth（默认，推荐） $ gemini # 首次运行自动打开浏览器 # API Key $ export GEMINI_API_KEY="AIza..." $ gemini # Vertex AI $ export GOOGLE_CLOUD_PROJECT="my-project" $ export GOOGLE_CLOUD_LOCATION="us-central1" $ gemini

vs Claude Code — 配置与扩展对比

维度	Gemini CLI	Claude Code
配置层级	7 层优先级	settings + CLAUDE.md 3 层
指令文件	GEMINI.md — JIT 自动发现 + @./path 模块化导入	CLAUDE.md 3 层，无 JIT，无模块化导入
初始化	/init 自动生成 GEMINI.md	手动创建 CLAUDE.md
扩展市场	Extension Gallery（浏览/安装/开发）	无扩展市场
Skills	AgentSkills.io 社区	Skills 内置
Hook 事件	11 个生命周期事件	3 个 (PreToolUse / PostToolUse / Stop)
Hooks 成熟度	较新	经过大量实战验证
心智模型	功能丰富但学习曲线陡	更简单直观

Gemini CLI 优势

更丰富的扩展生态（Extension Gallery）
JIT 上下文发现（工具访问新目录时自动扫描 GEMINI.md）
11 个 Hook 事件覆盖更多生命周期节点
/init 命令自动生成项目指令文件

Claude Code 优势

Hooks 机制更经过实战验证
心智模型更简单，上手门槛低

信息来源: docs/auth/ | docs/extensions/

M5 使用指南

从安装到高级用法，涵盖安装方式、CLI 参数、斜杠命令、键盘快捷键、GitHub Action 集成和自定义命令。

安装方式

安装 Gemini CLI

1/5

$ npx @google/gemini-cli

方式 1: npx（推荐，即用即跑）
无需安装，直接运行。Node.js ≥ 18 环境下一行命令启动。每次运行自动使用最新版本。适合快速体验和偶尔使用。

$ npm install -g @google/gemini-cli $ gemini

方式 2: npm 全局安装
安装到全局 node_modules，之后直接使用 gemini 命令。适合日常频繁使用，避免每次 npx 下载。

$ brew install gemini-cli

方式 3: Homebrew（macOS）
macOS 用户推荐方式，通过 Homebrew 包管理器安装。自动管理依赖和更新。

$ sudo port install gemini-cli

方式 4: MacPorts（macOS 备选）
另一个 macOS 包管理器选项，适合已有 MacPorts 生态的用户。

$ conda install -c conda-forge gemini-cli

方式 5: Anaconda / Conda
适合 Python/数据科学开发者，通过 conda-forge 频道安装。可集成到 conda 虚拟环境中。

发布节奏

频道	更新频率	安装命令	适用
Nightly	每日构建	`npx @google/gemini-cli@nightly`	尝鲜最新功能，可能不稳定
Preview	每周	`npx @google/gemini-cli@preview`	提前体验即将发布的功能
Stable	按需发布	`npx @google/gemini-cli`	生产使用推荐

CLI 参数一览

参数	缩写	说明
`--prompt <text>`	`-p`	非交互式执行单条提示
`--model <name>`	`-m`	指定模型（pro / flash / flash-lite / auto）
`--sandbox <type>`		指定沙箱类型
`--approval-mode <mode>`		设置审批模式
`--yolo`	`-y`	等同于 `--approval-mode yolo`
`--plan`		以 Plan Mode 启动
`--resume [id]`	`-r`	恢复上次/指定会话
`--output <format>`	`-o`	输出格式：text / json / stream-json
`--debug`	`-d`	启用调试日志
`--version`	`-v`	显示版本号
`--help`	`-h`	显示帮助信息
`--color <mode>`		颜色输出：auto / always / never
`--config <path>`		指定配置文件路径

斜杠命令系统

Gemini CLI 提供了丰富的斜杠命令体系：

会话管理

命令	功能
`/clear`	清空当前对话历史（保留系统提示）
`/save <title>`	保存当前会话
`/load <title>`	加载已保存的会话
`/sessions`	列出所有已保存的会话
`/history`	查看当前对话历史
`/compress`	压缩对话历史（保留关键信息）

模式切换

命令	功能
`/plan`	切换到 Plan Mode（只读）
`/yolo`	切换到 YOLO Mode（全自动）
`/vim`	切换 Vim Mode 开关
`/model <name>`	切换当前使用的模型

工具与信息

命令	功能
`/tools`	列出所有可用工具（内置 + MCP）
`/mcp`	查看 MCP 服务器连接状态
`/stats`	显示当前会话统计（token 用量、工具调用次数）
`/memory`	查看/管理持久记忆
`/todos`	查看任务清单

文件与项目

命令	功能
`/init`	自动生成 GEMINI.md 项目指令
`/diff`	查看 Agent 所做的文件变更
`/checkpoint`	手动创建检查点

其他

命令	功能
`/help`	显示帮助信息
`/quit` / `/exit`	退出 Gemini CLI
`/theme <name>`	切换终端主题
`/auth`	管理认证状态

键盘快捷键

快捷键	功能
`Esc Esc`（连按两次）	Rewind 模式（时间旅行 UI，查看文件变更历史）
`Ctrl + C`	中断当前操作（模型响应/工具执行）
`Ctrl + D`	退出 Gemini CLI
`Tab`	自动补全命令/文件路径
`Up / Down`	浏览历史输入
`Shift + Enter`	多行输入模式（换行不发送）
`@`	文件引用（触发文件选择器）

GitHub Action 官方集成

Google 官方提供了 GitHub Action，可在 CI/CD 中使用 Gemini CLI：

# .github/workflows/gemini-review.yml name: Gemini Code Review on: pull_request: types: [opened, synchronize] jobs: review: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: google-gemini/gemini-cli-action@v1 with: prompt: | 审查这个 PR 的代码变更，检查： 1. 潜在的 bug 2. 性能问题 3. 安全隐患 4. 代码风格 model: pro output: json env: GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}

CI/CD 实用场景：自动代码审查、PR 描述生成、测试用例生成、文档更新检查、变更日志自动化。配合 --output json 可以解析结构化输出并创建 GitHub Issue/Comment。

自定义命令（TOML 定义）

可以在 .gemini/commands/ 目录下创建 TOML 文件定义自定义斜杠命令：

# .gemini/commands/deploy.toml [command] name = "deploy" description = "部署到 staging 环境" prompt = """ 执行以下部署步骤： 1. 运行测试确保通过 2. 构建项目 3. 部署到 staging 4. 验证部署状态 """ [command.options] env = { type = "string", default = "staging", description = "目标环境" }

# 使用自定义命令 > /deploy > /deploy --env production

实用技巧速查

文件引用技巧

@file.ts 引用单个文件
@*.test.ts 引用匹配的文件
@image.png 引用图片
@doc.pdf 引用 PDF
拖拽文件到终端自动添加

管道与自动化

echo "fix bugs" | gemini
cat error.log | gemini -p "分析错误"
git diff | gemini -p "审查变更"
gemini -o json -p "..." | jq

多会话工作流

/save feature-x 保存进度
切换到其他任务
gemini -r 恢复上次会话
/sessions 查看所有会话

调试技巧

gemini --debug 查看详细日志
/stats 监控 token 消耗
/tools 确认工具可用性
/mcp 检查 MCP 连接

vs Claude Code — 使用与生态对比

维度	Gemini CLI	Claude Code
免费额度	60 req/min, 1000 req/day（Google 账号即用）	需付费 API Key
上下文窗口	1M tokens（5 倍）	200K tokens
CI/CD	官方 GitHub Action (google-github-actions/run-gemini-cli)	claude -p 命令行模式，无官方 Action
Vim 模式	内置 Vim 键绑定	无 Vim 模式
编码质量	Gemini 2.5 Pro	Claude Sonnet/Opus 更优
稳定性	快速迭代中，偶有不稳定	最成熟可靠
生态成熟度	社区活跃但较新	最成熟的 CLI Agent 生态

Gemini CLI 优势

零成本使用顶级模型（免费 + 无需信用卡）
5 倍上下文窗口（1M vs 200K）
官方 CI Action 开箱可用
内置 Vim 模式

Claude Code 优势

模型编码质量更高，复杂任务表现更优
整体稳定性和可靠性最强
生态最成熟，社区资源最丰富

信息来源: docs/cli/ | README.md | docs/features/