Google 开源的 AI 终端智能体Gemini CLI

Gemini CLI 是 Google 开源的 AI 终端智能体，将 Gemini 模型的能力直接带入你的命令行。它是 Gemini 的"终端第一"客户端，提供轻量级访问，让你从提示到模型拥有最直接的路径

洛星核

349人浏览 · 2026-06-03 10:45:10

洛星核 · 2026-06-03 10:45:10 发布

Gemini CLI

官方仓库: https://github.com/google-gemini/gemini-cli
官方文档: https://geminicli.com/docs/
NPM 包: https://www.npmjs.com/package/@google/gemini-cli
许可证: Apache License 2.0
最低运行环境: Node.js >= 20.0.0

一、项目概述

Gemini CLI 是 Google 开源的 AI 终端智能体，将 Gemini 模型的能力直接带入你的命令行。它是 Gemini 的"终端第一"客户端，提供轻量级访问，让你从提示到模型拥有最直接的路径。

核心特点

免费层级: 使用个人 Google 账户登录，60 次请求/分钟、1,000 次请求/天
强大的 Gemini 模型: 支持 Gemini 2.5 系列模型（Pro/Flash），具备 100 万 token 上下文窗口
内置工具: Google 搜索 grounding、文件操作、Shell 命令、Web 抓取
可扩展: 支持 MCP（Model Context Protocol）连接自定义工具和服务
终端优先: 专为在命令行中工作的开发者设计
完全开源: Apache 2.0 许可证
多模式: 支持交互式终端模式和无头脚本模式
IDE 集成: 可配合 VS Code 等编辑器使用

二、安装步骤

方式 1：使用 npx（即时运行，无需安装）

# 无需安装，直接使用 npx 运行
npx @google/gemini-cli

优点：零安装，立即可用。
缺点：每次都需要从网络加载。

方式 2：使用 npm 全局安装（推荐）

# 安装最新稳定版
npm install -g @google/gemini-cli

# 或使用镜像源（国内推荐）
npm install -g @google/gemini-cli -i https://registry.npmmirror.com

安装后验证：

gemini --version
# 或
gemini -v

方式 3：使用 Homebrew（macOS/Linux）

brew install gemini-cli

方式 4：使用 MacPorts（macOS）

sudo port install gemini-cli

方式 5：使用 Anaconda（受限环境）

# 创建并激活新环境
conda create -y -n gemini_env -c conda-forge nodejs
conda activate gemini_env

# 在环境中通过 npm 全局安装
npm install -g @google/gemini-cli

发行频道

频道	标签	发布频率	说明
稳定版	`@latest`	每周二 UTC 20:00	经过验证的正式版本
预览版	`@preview`	每周二 UTC 23:59	新特性，可能有问题
夜间版	`@nightly`	每天 UTC 00:00	最新代码，不保证稳定性

# 安装预览版
npm install -g @google/gemini-cli@preview

# 安装夜间版
npm install -g @google/gemini-cli@nightly

系统要求

Node.js >= 20.0.0
支持的平台：macOS、Linux、Windows
终端需要支持 ANSI 颜色和 PTY（伪终端）

更新

# 更新到最新版本
npm install -g @google/gemini-cli@latest

# 或在交互会话中使用
gemini --upgrade
# 或使用 /upgrade 命令

三、认证配置

Gemini CLI 支持三种认证方式，选择最适合你的方式：

方式 1：使用 Google 账户登录（推荐，最便捷）

适用场景: 个人开发者、任何拥有 Gemini Code Assist 许可证的用户

优势:

免费层级：60 次/分钟、1,000 次/天
Gemini 2.5 模型，100 万 token 上下文窗口
无需管理 API Key
自动更新到最新模型

步骤:

# 1. 启动 CLI
gemini

# 2. 选择 "Sign in with Google"
# 3. 浏览器会自动打开，完成 OAuth 认证
# 4. 凭证会缓存在本地供后续使用

如果你使用组织的付费 Code Assist License，还需要设置 Google Cloud Project：

export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
gemini

方式 2：使用 Gemini API Key

适用场景: 需要特定模型控制或付费层级的开发者

优势:

免费层级：每天 250 次请求（仅限 Flash 模型）
可选择特定 Gemini 模型
按需付费，升级更高限制

步骤:

# 1. 从 https://aistudio.google.com/apikey 获取 API Key

# 2. 设置环境变量
# macOS/Linux:
export GEMINI_API_KEY="your-api-key-here"

# Windows PowerShell:
$env:GEMINI_API_KEY="your-api-key-here"

# 3. 启动 CLI
gemini

# 4. 选择 "Use Gemini API key"

方式 3：使用 Vertex AI

适用场景: 企业团队和生产工作负载

优势:

企业级功能：高级安全和合规
可缩放：更高速率限制
与现有 Google Cloud 基础设施集成

步骤:

# 必须设置的变量：
export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
export GOOGLE_CLOUD_LOCATION="us-central1"  # 或其他区域

# A. 使用 Application Default Credentials (gcloud):
# 确保未设置 GOOGLE_API_KEY 或 GEMINI_API_KEY
unset GOOGLE_API_KEY GEMINI_API_KEY
gcloud auth application-default login
gemini
# 选择 "Vertex AI"

# B. 使用 Service Account JSON Key:
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/keyfile.json"
gemini
# 选择 "Vertex AI"

# C. 使用 Google Cloud API Key:
export GOOGLE_API_KEY="your-google-api-key"
export GOOGLE_GENAI_USE_VERTEXAI=true
gemini
# 选择 "Vertex AI"

持久化环境变量

将环境变量添加到 shell 配置文件（如 ~/.bashrc、~/.zshrc）：

echo 'export GEMINI_API_KEY="your-key"' >> ~/.bashrc
source ~/.bashrc

或使用 .env 文件：

# 创建用户级 .env 文件
mkdir -p ~/.gemini
cat > ~/.gemini/.env << 'EOF'
GEMINI_API_KEY="your-api-key"
GOOGLE_CLOUD_PROJECT="your-project-id"
EOF

Gemini CLI 会自动从当前目录向上搜索 .gemini/.env，然后在 ~/.gemini/.env 中查找。

四、基本使用方法

交互式模式

# 在当前目录启动
gemini

# 包含多个目录
gemini --include-directories ../lib,../docs

# 使用特定模型
gemini -m gemini-2.5-flash

# 启用沙盒模式
gemini -s

启动后会进入交互式终端界面，你可以：

输入自然语言提示与 Gemini 对话
使用 / 斜杠命令控制 CLI 本身
使用 @ 符号引用文件/目录
使用 ! 直接执行 Shell 命令

无头模式（脚本/自动化）

# 简单文本响应
gemini -p "解释这个代码库的架构"

# JSON 结构化输出
gemini -p "解释这个代码库的架构" --output-format json

# 实时事件流（用于监控长时间运行的操作）
gemini -p "运行测试并部署" --output-format stream-json

常见使用场景

# 1. 开始新项目
cd new-project/
gemini
> 帮我写一个用 FAQ.md 回答问题的 Discord 机器人

# 2. 分析现有代码
git clone https://github.com/some/repo
cd repo
gemini
> 总结一下昨天的所有变更

# 3. 调试问题
gemini
> 帮我找出 src/main.py 中的 bug

# 4. 代码审查
gemini
> 审查这个 PR 的代码质量

五、完整命令参考

斜杠命令 (`/`)

命令	功能
`/about`	显示版本信息（提交 issue 时需提供）
`/agents`	管理本地和远程子智能体（list/reload/enable/disable/config）
`/auth`	切换认证方式
`/bug <描述>`	直接在 GitHub 提交 bug 报告
`/chat` 或 `/resume`	浏览和恢复之前的会话/检查点
`/clear`	清屏（快捷键：Ctrl+L）
`/commands`	管理自定义斜杠命令（list/reload）
`/compress`	用摘要压缩整个聊天上下文，节省 token
`/copy`	复制最后一条输出到剪贴板
`/directory` 或 `/dir`	管理工作区目录（add/show）
`/docs`	在浏览器中打开 Gemini CLI 文档
`/editor`	选择支持的外部编辑器
`/extensions`	管理扩展（config/disable/enable/explore/install/link/list/restart/uninstall/update）
`/help` 或 `/?`	显示帮助信息
`/hooks`	管理生命周期钩子（enable/disable/list）
`/ide`	管理 IDE 集成（enable/disable/install/status）
`/init`	分析当前目录并生成 GEMINI.md 上下文文件
`/mcp`	管理 MCP 服务器（auth/desc/disable/enable/list/reload/schema）
`/memory`	管理指令上下文（list/refresh/show）
`/model`	管理模型配置（manage/set）
`/permissions`	管理文件夹信任权限
`/plan`	进入/退出计划模式
`/policies`	管理策略
`/privacy`	显示隐私信息
`/quit` 或 `/exit`	退出 CLI
`/restore`	恢复之前的会话
`/rewind`	回滚之前的操作
`/resume <tag>`	恢复已保存的会话
`/settings`	打开设置
`/shells` 或 `/bashes`	管理后台 Shell
`/setup-github`	设置 GitHub 集成
`/skills`	管理 Agent Skills
`/stats`	显示使用统计（token 消耗等）
`/terminal-setup`	终端设置
`/theme`	切换主题
`/tools`	查看当前会话中的可用工具
`/upgrade`	升级到最新版本
`/vim`	切换 Vim 模式

`@` 命令（文件引用）

@path/to/file.txt    # 在提示中包含文件内容
@src/                # 包含整个目录
@.                   # 包含当前目录

当你在提示中使用 @ 符号时，会触发 read_many_files 工具，将文件内容包含到上下文中。

`!` 命令（Shell 直通）

!ls -la              # 直接执行 Shell 命令
!git status          # 执行 git 命令
!npm test            # 运行测试

空提示时输入 ! 可进入/退出 Shell 模式。

会话检查点命令

/chat save <tag>     # 保存当前会话（标记为 tag）
/chat resume <tag>   # 恢复已保存的会话
/chat list           # 列出所有已保存的检查点
/chat delete <tag>   # 删除检查点
/chat share file.md  # 导出会话为 Markdown
/chat share file.json # 导出会话为 JSON
/chat debug          # 导出最近一次 API 请求为 JSON

检查点默认位置：

Linux/macOS: ~/.gemini/tmp/<project_hash>/
Windows: C:\Users\<Username>\.gemini\tmp\<project_hash>\

六、配置详解

配置层级（优先级从低到高）

默认值 — 应用内硬编码
系统默认文件 — 系统级基础设置
用户设置文件 — 当前用户全局设置
项目设置文件 — 项目特定设置
系统设置文件 — 系统级覆盖（最高优先级）
环境变量 — 系统或会话级变量
命令行参数 — 启动时传入的值

设置文件位置

文件	位置	作用域
系统默认	`/etc/gemini-cli/system-defaults.json` (Linux)	系统级最低优先级
用户设置	`~/.gemini/settings.json`	当前用户全局
项目设置	`./.gemini/settings.json`	仅当前项目
系统设置	`/etc/gemini-cli/settings.json` (Linux)	系统级最高优先级

macOS 系统文件: /Library/Application Support/GeminiCli/
Windows 系统文件: C:\ProgramData\gemini-cli\

主要配置项

{
  "general": {
    "preferredEditor": "vscode",
    "vimMode": false,
    "defaultApprovalMode": "default",
    "enableAutoUpdate": true,
    "enableAutoUpdateNotification": true,
    "enableNotifications": false,
    "checkpointing": {
      "enabled": false
    },
    "plan": {
      "enabled": true,
      "modelRouting": true
    },
    "retryFetchErrors": true,
    "maxAttempts": 10,
    "sessionRetention": {
      "enabled": true,
      "maxAge": "30d",
      "maxCount": null,
      "minRetention": "1d"
    },
    "topicUpdateNarration": true
  },
  "output": {
    "format": "text"
  },
  "ui": {
    "theme": null,
    "autoThemeSwitching": true,
    "inlineThinkingMode": "off",
    "showStatusInTitle": false,
    "dynamicWindowTitle": true,
    "hideBanner": false,
    "hideTips": false,
    "compactToolOutput": true
  },
  "tools": {
    "sandbox": false
  },
  "context": {
    "fileName": ["GEMINI.md"]
  },
  "mcpServers": {}
}

详细配置项说明

general 类别

配置项	类型	默认值	说明
`general.preferredEditor`	enum	undefined	首选编辑器（vscode/vim/neovim/etc）
`general.vimMode`	boolean	false	启用 Vim 键位
`general.defaultApprovalMode`	enum	“default”	工具审批模式（default/auto_edit/plan）
`general.enableAutoUpdate`	boolean	true	自动更新
`general.enableNotifications`	boolean	false	终端通知
`general.checkpointing.enabled`	boolean	false	会话检查点（需重启）
`general.plan.enabled`	boolean	true	计划模式（需重启）
`general.plan.modelRouting`	boolean	true	计划时自动切换 Pro/Flash
`general.maxAttempts`	number	10	最大请求重试次数（不超过 10）
`general.sessionRetention.enabled`	boolean	true	自动清理会话
`general.sessionRetention.maxAge`	string	“30d”	会话保留时间（如 “30d”, “7d”, “24h”）

ui 类别

配置项	类型	默认值	说明
`ui.theme`	string	undefined	颜色主题
`ui.autoThemeSwitching`	boolean	true	根据终端背景自动切换亮/暗主题
`ui.inlineThinkingMode`	enum	“off”	内联思考显示（off/full）
`ui.showStatusInTitle`	boolean	false	在终端标题显示工作状态
`ui.dynamicWindowTitle`	boolean	true	动态更新窗口标题图标
`ui.hideBanner`	boolean	false	隐藏启动横幅
`ui.hideTips`	boolean	false	隐藏提示
`ui.compactToolOutput`	boolean	true	紧凑工具输出
`ui.escapePastedAtSymbols`	boolean	false	粘贴时转义 @ 符号

tools 类别

配置项	类型	默认值	说明
`tools.sandbox`	boolean/string	false	沙盒模式（true/docker/podman 等）

环境变量

变量	说明
`GEMINI_API_KEY`	Gemini API Key
`GOOGLE_API_KEY`	Google Cloud API Key（Vertex AI）
`GOOGLE_GENAI_USE_VERTEXAI`	使用 Vertex AI（设为 true）
`GOOGLE_CLOUD_PROJECT`	Google Cloud 项目 ID
`GOOGLE_CLOUD_PROJECT_ID`	备用项目 ID 变量
`GOOGLE_CLOUD_LOCATION`	Vertex AI 区域
`GOOGLE_APPLICATION_CREDENTIALS`	Service Account JSON 路径
`GEMINI_SANDBOX`	沙盒模式（true/docker/podman/…）
`NODE_USE_SYSTEM_CA`	使用系统 CA 证书库
`NODE_EXTRA_CA_CERTS`	额外的 CA 证书路径

命令行参数

gemini [选项]

# 常用选项
-p, --prompt <text>       # 无头模式，执行提示后退出
-m, --model <name>        # 指定模型
-s, --sandbox             # 启用沙盒模式
--include-directories <dirs> # 包含额外目录
--output-format <format>  # 输出格式（text/json/stream-json）
--debug                   # 调试模式
--yolo                    # YOLO 模式（自动批准所有操作）
--approval-mode <mode>    # 审批模式
--version, -v             # 显示版本

七、GEMINI.md 上下文文件

GEMINI.md 是 Gemini CLI 的核心功能之一，用于为 AI 提供项目特定的指令和上下文。

上下文层级

Gemini CLI 按以下顺序加载上下文文件：

全局上下文: ~/.gemini/GEMINI.md — 所有项目的默认指令
项目/工作区上下文: 工作区目录及其父目录中的 GEMINI.md
即时上下文 (JIT): 当工具访问文件/目录时，自动扫描该目录及其祖先

示例 GEMINI.md

# 项目: 我的 TypeScript 库

## 通用指令
- 生成新的 TypeScript 代码时，遵循现有的编码风格
- 确保所有新函数和类都有 JSDoc 注释
- 在适当的地方优先使用函数式编程范式

## 编码风格
- 使用 2 个空格缩进
- 接口名称前缀使用 `I`（例如 `IUserService`）
- 始终使用严格相等（`===` 和 `!==`）

管理上下文

/memory show        # 显示所有已加载的上下文内容
/memory list        # 列出所有上下文文件路径
/memory refresh     # 重新加载所有 GEMINI.md 文件
/init               # 自动分析当前目录并生成 GEMINI.md

模块化导入

在 GEMINI.md 中可以使用 @ 语法导入其他文件：

# 主 GEMINI.md 文件
这是主要内容。
@./components/instructions.md
更多内容。
@../shared/style-guide.md

自定义上下文文件名

在 settings.json 中修改：

{
  "context": {
    "fileName": ["AGENTS.md", "CONTEXT.md", "GEMINI.md"]
  }
}

八、工具系统

工具分类

Gemini CLI 的工具按功能分类：

执行工具

工具	类型	说明
`run_shell_command`	Execute	执行任意 Shell 命令，支持交互式会话和后台进程

文件系统工具

工具	类型	说明
`glob`	Search	按 glob 模式查找文件
`grep_search`	Search	在文件内容中搜索正则表达式
`list_directory`	Read	列出目录内容
`read_file`	Read	读取文件（支持文本、图片、音频、PDF）
`read_many_files`	Read	读取并合并多个文件（`@` 触发）
`replace`	Edit	精确文本替换（需确认）
`write_file`	Edit	创建或覆盖文件（需确认）

Web 工具

工具	类型	说明
`google_web_search`	Search	Google 搜索获取实时信息
`web_fetch`	Fetch	获取和处理 URL 内容

交互工具

工具	类型	说明
`ask_user`	Communicate	向用户请求澄清信息
`write_todos`	Other	维护内部子任务列表

计划工具

工具	类型	说明
`enter_plan_mode`	Plan	进入只读计划模式
`exit_plan_mode`	Plan	退出计划模式，请求批准实施

工具使用方式

自动执行: Gemini CLI 在需要时自动调用工具。修改文件和执行 Shell 命令需要用户手动确认（显示 diff 或命令预览）。

手动触发:

@file.txt           # 触发 read_many_files，将文件内容包含到提示中
@src/               # 包含目录
!ls -la             # 触发 run_shell_command，直接执行

工具管理:

/tools              # 列出所有注册的工具
/tools desc         # 列出工具及完整描述

九、MCP 服务器集成

MCP（Model Context Protocol）允许 Gemini CLI 连接外部系统和服务。

配置 MCP 服务器

在 settings.json 中配置：

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "database": {
      "command": "node",
      "args": ["/path/to/db-server.js"]
    }
  }
}

MCP 传输方式

方式	说明
Stdio	子进程，通过 stdin/stdout 通信（默认）
SSE	连接到 Server-Sent Events 端点
Streamable HTTP	HTTP 流式通信

MCP 管理命令

/mcp list           # 列出所有 MCP 服务器和工具（默认操作）
/mcp desc           # 列出带描述的服务器和工具
/mcp schema         # 列出带描述和 schema 的服务器
/mcp enable <name>  # 启用服务器
/mcp disable <name> # 禁用服务器
/mcp reload         # 重新加载所有 MCP 服务器
/mcp auth <name>    # OAuth 认证

# 命令行管理
gemini mcp add      # 添加服务器
gemini mcp list     # 列出服务器
gemini mcp remove   # 移除服务器
gemini mcp enable   # 启用服务器
gemini mcp disable  # 禁用服务器

使用 MCP 工具

> @github List my open pull requests
> @slack Send a summary to #dev channel
> @database Find inactive users

MCP 资源

MCP 服务器可以暴露资源（不仅仅是工具）：

/mcp list           # 查看 Resources 部分
@<resource-uri>     # 在对话中引用资源

十、快捷键

基本控制

快捷键	操作
Enter	确认/提交
Esc / Ctrl+[	取消/关闭对话框
Ctrl+C	取消当前请求 / 清空输入时退出
Ctrl+D	输入为空时退出 CLI

光标移动

快捷键	操作
Ctrl+A / Home	行首
Ctrl+E / End	行尾
Ctrl+Backspace / Ctrl+W	删除前一个单词
Ctrl+Delete / Alt+D	删除后一个单词
Ctrl+K	删除到行尾
Ctrl+U	删除到行首

历史记录

快捷键	操作
Ctrl+P / Up	上一条历史
Ctrl+N / Down	下一条历史
Ctrl+R	反向搜索历史

文本编辑

快捷键	操作
Ctrl+Z	撤销
Ctrl+Shift+Z	重做
Ctrl+Enter / Alt+Enter	插入换行（不提交）
Ctrl+G	在外部编辑器中打开
Ctrl+V	粘贴

应用控制

快捷键	操作
Ctrl+L	清屏并重绘
Ctrl+T	切换完整 TODO 列表
Ctrl+Y	切换 YOLO 模式
Ctrl+O	展开/折叠粘贴内容
Ctrl+B	切换后台 Shell 可见性
Ctrl+S	切换鼠标模式
Alt+M	切换 Markdown 渲染
F12	切换调试控制台
F8	导出当前帧快照
F6	开始/停止录制
Shift+R / R	重启应用
Tab	将焦点移到活动 Shell

输入提示快捷键

快捷键	操作
`!` (空提示)	进入/退出 Shell 模式
`?` (空提示)	显示快捷键面板
Tab + Tab	在最小和完整 UI 之间切换
Shift+Tab (输入中)	循环审批模式
`\` + Enter	插入换行（不离开单行模式）
Esc (快速按两次)	清空输入 / 回滚
数字键 1-9	在对话框中跳到对应选项

自定义键位绑定

创建 ~/.gemini/keybindings.json：

[
  { "command": "edit.clear", "key": "cmd+l" },
  { "command": "-app.toggleYolo", "key": "ctrl+y" },
  { "command": "input.submit", "key": "ctrl+y" }
]

前缀 - 表示解除绑定。

十一、高级功能

1. 沙盒模式 (Sandboxing)

沙盒隔离了潜在危险的操作（Shell 命令、文件修改）。

启用方式:

# 命令行参数
gemini -s
gemini -s -p "分析代码结构"

# 环境变量
export GEMINI_SANDBOX=true
gemini

# 配置文件
# settings.json:
{ "tools": { "sandbox": "docker" } }

支持的沙盒方法:

方法	平台	说明
Seatbelt	macOS	轻量级内置沙盒（sandbox-exec）
Docker/Podman	跨平台	容器化完全隔离
Windows Sandbox	Windows	Windows 原生沙盒
gVisor/runsc	Linux	Linux 容器运行时沙盒
LXC/LXD	Linux	实验性 Linux 容器

2. 会话检查点 (Checkpointing)

自动保存会话检查点（在文件修改前）：

{
  "general": {
    "checkpointing": {
      "enabled": true
    }
  }
}

3. 计划模式 (Plan Mode)

只读安全模式，用于研究复杂变更：

/plan               # 进入计划模式
# 在计划模式下，只能读取文件，不能修改
# 计划完成后，请求批准开始实施

配置自动模型路由（计划用 Pro，实施用 Flash）：

{
  "general": {
    "plan": {
      "enabled": true,
      "modelRouting": true
    }
  }
}

4. Token 缓存

优化 token 使用，缓存频繁使用的上下文内容。对 API Key 用户（非 OAuth 用户）可用。

5. 子智能体 (Subagents)

/agents list        # 列出所有子智能体
/agents reload      # 重新扫描和重新加载
/agents enable <name>
/agents disable <name>
/agents config <name>

6. 自定义命令

在 ~/.gemini/commands/ 或项目 .gemini/commands/ 中创建 .toml 文件：

# ~/.gemini/commands/test.toml
name = "test"
description = "Run tests and report results"
prompt = "Run the test suite and give me a summary of the results."

/commands list      # 列出自定义命令
/commands reload    # 重新加载

7. 钩子 (Hooks)

生命周期事件钩子：

/hooks list         # 列出所有钩子
/hooks enable <name>
/hooks disable <name>
/hooks enable-all
/hooks disable-all

8. IDE 集成

/ide status         # 检查 IDE 集成状态
/ide enable         # 启用
/ide install        # 安装 IDE 伴侣
/ide disable        # 禁用

9. GitHub 集成

通过 Gemini CLI GitHub Action 集成：

Pull Request 自动审查
Issue 自动分类和优先级排序
在 issue/PR 中 @gemini-cli 获取帮助

10. 撤销 (Rewind)

/rewind             # 回滚之前的文件修改操作

十二、配额与定价

免费使用

认证方式	免费限额	说明
Google 账户（个人）	1,000 次/天	Gemini 2.5 系列模型
Gemini API Key（免费）	250 次/天	仅限 Flash 模型
Vertex AI Express	90 天免费	限额因账户而异

付费层级（固定费用）

订阅	限额	适用账户
Google AI Pro	1,500 次/天	个人
Google AI Ultra	2,000 次/天	个人
Code Assist Standard	1,500 次/天	组织
Code Assist Enterprise	2,000 次/天	组织
Workspace AI Ultra	2,000 次/天	组织

按量付费

方式	说明
Vertex AI	按 API 调用量计费，无每日限额
Gemini API Key	升级付费层后按需计费

检查使用量

/stats              # 在 CLI 中查看 token 使用统计

十三、快捷键完整参考

参见上方"十、快捷键"部分。详细文档: https://geminicli.com/docs/reference/keyboard-shortcuts

十四、常见问题 (FAQ)

为什么收到 “429 - Resource exhausted” 错误？

这是 API 请求限制。解决方法：

检查 Google AI Studio 或 Cloud 控制台的使用量
优化提示，批处理请求
请求配额增加或升级到付费层级

如何检查版本？

gemini --version
# 或
npm list -g @google/gemini-cli
# 或在 CLI 中: /about

如何安全存储 API Key？

# 方法 1: .env 文件（推荐）
mkdir -p ~/.gemini
echo 'GEMINI_API_KEY="your-key"' > ~/.gemini/.env

# 方法 2: 系统密钥环（更安全）
# macOS: 使用 Keychain
# Windows: 使用 Credential Manager
# Linux: 使用 secret-service

配置和设置文件在哪里？

用户级: ~/.gemini/settings.json
项目级: ./.gemini/settings.json

为什么收到认证错误？

“You must be a named user…”: 你设置了 GOOGLE_CLOUD_PROJECT 但使用的是个人账户。解决方法：取消设置该变量。

“UNABLE_TO_GET_ISSUER_CERT_LOCALLY”: 企业网络拦截 SSL。解决方法：

export NODE_USE_SYSTEM_CA=1
# 或
export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.crt

在 CI 环境中无法进入交互模式？

如果设置了 CI_ 前缀的环境变量（如 CI_TOKEN），Gemini CLI 会认为在 CI 环境中。解决方法：

env -u CI_TOKEN gemini

在 Windows 上运行 `chmod` 命令崩溃？

chmod 是 Unix 命令，Windows 不支持。使用 icacls 或在 Git Bash/WSL 中运行。

十五、卸载

方法 1: npx 方式（清除缓存）

# macOS/Linux
rm -rf "$(npm config get cache)/_npx"

# Windows PowerShell
Remove-Item -Path (Join-Path $env:LocalAppData "npm-cache\_npx") -Recurse -Force

方法 2: npm 全局安装

npm uninstall -g @google/gemini-cli

方法 3: Homebrew

brew uninstall gemini-cli

方法 4: MacPorts

sudo port uninstall gemini-cli

十六、故障排除

常见退出码

退出码	错误类型	说明
0	-	成功
1	-	一般错误或 API 失败
41	FatalAuthenticationError	认证错误
42	FatalInputError	无效或缺失输入
44	FatalSandboxError	沙盒环境错误
52	FatalConfigError	配置文件错误
53	FatalTurnLimitedError	会话回合数达到上限

调试技巧

# 使用调试标志
gemini --debug

# 在交互模式中按 F12 打开调试控制台
# 设置调试环境变量
export DEBUG_MODE=true
# 使用 Node.js 调试工具
node --inspect packages/cli/dist/index.js

常见问题

问题	原因	解决
EADDRINUSE	MCP 服务器端口被占用	停止占用进程或更改端口
Command not found	未正确安装或不在 PATH 中	重新安装或检查 PATH
MODULE_NOT_FOUND	依赖未安装或未构建	运行 `npm install && npm run build`
Permission denied	沙盒限制了操作	检查沙盒配置
npm WARN deprecated	依赖过时警告	可安全忽略

十七、与其他工具的对比

特性	Gemini CLI	Claude Code	GitHub Copilot CLI
免费层级	1,000 次/天	无	需要订阅
开源	是 (Apache 2.0)	否	部分
MCP 支持	是	是	有限
沙盒模式	是	有限	有限
多模型选择	Gemini 系列	Claude 系列	GPT 系列
内置搜索	Google Search	有限	有限
终端优先	是	是	是

十八、文档资源链接

官方文档: https://geminicli.com/docs/
快速入门: https://geminicli.com/docs/get-started
认证设置: https://geminicli.com/docs/get-started/authentication
配置指南: https://geminicli.com/docs/reference/configuration
命令参考: https://geminicli.com/docs/reference/commands
工具参考: https://geminicli.com/docs/reference/tools
快捷键: https://geminicli.com/docs/reference/keyboard-shortcuts
MCP 集成: https://geminicli.com/docs/tools/mcp-server
沙盒安全: https://geminicli.com/docs/cli/sandbox
GEMINI.md: https://geminicli.com/docs/cli/gemini-md
无头模式: https://geminicli.com/docs/cli/headless
IDE 集成: https://geminicli.com/docs/ide-integration
扩展开发: https://geminicli.com/docs/extensions/writing-extensions
企业指南: https://geminicli.com/docs/cli/enterprise
FAQ: https://geminicli.com/docs/resources/faq
故障排除: https://geminicli.com/docs/resources/troubleshooting
配额与定价: https://geminicli.com/docs/resources/quota-and-pricing
卸载指南: https://geminicli.com/docs/resources/uninstall
更新日志: https://geminicli.com/docs/changelogs
课程: https://learn.deeplearning.ai/courses/gemini-cli-code-and-create-with-an-open-source-agent/information
GitHub Issues: https://github.com/google-gemini/gemini-cli/issues
官方路线图: https://github.com/orgs/google-gemini/projects/11

十九、总结

Gemini CLI 是 Google 旗下一款功能强大的终端 AI 智能体，具有以下优势：

免费且慷慨: 个人 Google 账户即可享受每天 1,000 次请求
强大的模型: 支持 Gemini 2.5 系列，100 万 token 上下文窗口
丰富的工具系统: 内置文件操作、Shell 执行、Web 搜索、Google 搜索 grounding
可扩展: 通过 MCP 协议连接任意外部服务
多模式支持: 交互式终端、无头脚本、CI/CD 集成
安全: 沙盒隔离、用户确认、信任文件夹
高度可配置: 多层配置系统、自定义命令、钩子、主题
社区驱动: 完全开源 (Apache 2.0)，欢迎贡献
生态系统: 支持扩展、Agent Skills、IDE 集成、GitHub Action

注意事项:

需要 Node.js >= 20.0.0
2026年6月18日后未付费用户需迁移到 Antigravity CLI
在国内使用可能需要配置 npm 镜像源
企业网络可能需要额外配置 CA 证书

https://edu.csdn.net/learn/39067/627173?utm_source=2019755004

汇聚全球AI编程工具，助力开发者即刻编程。

更多推荐

Codex又又又更新了！这次似乎不需要Xcode了？Codex更新、Codex遥控器、Codex手机版、iOS Builder、Xcode替代方案、AI编程工具、Codex客户端下载、Mac远程控制、

AI编程社区

告别拖拽做工作流：两个Skill让Dify应用全流程自动化

AI编程社区

Claude Code 通信机制逆向分析

使用 Proxyman 抓包工具对 Claude Code 的 API 通信进行完整逆向分析，浅谈 AI Agent 的工作机制。

AI编程社区

所有评论(0)

查看更多评论

洛星核

@weixin_43796399

已为社区贡献2条内容

Google 开源的 AI 终端智能体Gemini CLI

洛星核

Gemini CLI

一、项目概述

核心特点

二、安装步骤

方式 1：使用 npx（即时运行，无需安装）

方式 2：使用 npm 全局安装（推荐）

方式 3：使用 Homebrew（macOS/Linux）

方式 4：使用 MacPorts（macOS）

方式 5：使用 Anaconda（受限环境）

发行频道

系统要求

更新

三、认证配置

方式 1：使用 Google 账户登录（推荐，最便捷）

方式 2：使用 Gemini API Key

方式 3：使用 Vertex AI

持久化环境变量

四、基本使用方法

交互式模式

无头模式（脚本/自动化）

常见使用场景

五、完整命令参考

斜杠命令 (/)

@ 命令（文件引用）

! 命令（Shell 直通）

会话检查点命令

六、配置详解

配置层级（优先级从低到高）

设置文件位置

主要配置项

详细配置项说明

general 类别

ui 类别

tools 类别

环境变量

命令行参数

七、GEMINI.md 上下文文件

上下文层级

示例 GEMINI.md

管理上下文

模块化导入

自定义上下文文件名

八、工具系统

工具分类

执行工具

文件系统工具

Web 工具

交互工具

计划工具

工具使用方式

九、MCP 服务器集成

配置 MCP 服务器

MCP 传输方式

MCP 管理命令

使用 MCP 工具

MCP 资源

十、快捷键

基本控制

光标移动

历史记录

文本编辑

应用控制

输入提示快捷键

自定义键位绑定

十一、高级功能

1. 沙盒模式 (Sandboxing)

2. 会话检查点 (Checkpointing)

3. 计划模式 (Plan Mode)

4. Token 缓存

5. 子智能体 (Subagents)

6. 自定义命令

7. 钩子 (Hooks)

8. IDE 集成

9. GitHub 集成

10. 撤销 (Rewind)

十二、配额与定价

免费使用

付费层级（固定费用）

斜杠命令 (`/`)

`@` 命令（文件引用）

`!` 命令（Shell 直通）

在 Windows 上运行 `chmod` 命令崩溃？