/README.md

<!-- WEHUB_ZH_README -->
> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。  
> [English](./README.en.md) · [原始项目](https://github.com/google-gemini/gemini-cli) · [上游 README](https://github.com/google-gemini/gemini-cli/blob/HEAD/README.md)  
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

# Gemini CLI

[![Gemini CLI CI](https://github.com/google-gemini/gemini-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/google-gemini/gemini-cli/actions/workflows/ci.yml)
[![Gemini CLI E2E（链式）](https://github.com/google-gemini/gemini-cli/actions/workflows/chained_e2e.yml/badge.svg)](https://github.com/google-gemini/gemini-cli/actions/workflows/chained_e2e.yml)
[![版本](https://img.shields.io/npm/v/@google/gemini-cli)](https://www.npmjs.com/package/@google/gemini-cli)
[![许可证](https://img.shields.io/github/license/google-gemini/gemini-cli)](https://github.com/google-gemini/gemini-cli/blob/main/LICENSE)
[![查看代码 Wiki](https://assets.codewiki.google/readme-badge/static.svg)](https://codewiki.google/github.com/google-gemini/gemini-cli?utm_source=badge&utm_medium=github&utm_campaign=github.com/google-gemini/gemini-cli)

![Gemini CLI 截图](/docs/assets/gemini-screenshot.png)

Gemini CLI 是一个开源 AI 代理，将 Gemini 的强大能力直接带到您的终端。它提供轻量级访问 Gemini 的途径，为您提供从提示到模型的最直接路径。

在[文档](https://geminicli.com/docs/).)中了解 Gemini CLI 的全部内容。

## 🚀 为什么选择 Gemini CLI？

- **🎯 免费使用额度**：使用个人 Google 账号即可享受每分钟 60 次请求和每日 1,000 次请求。
- **🧠 强大的 Gemini 3 模型**：访问改进的推理能力和 100 万 token 上下文窗口。
- **🔧 内置工具**：Google 搜索验证、文件操作、Shell 命令、网页抓取。
- **🔌 可扩展**：支持 MCP（模型上下文协议）以实现自定义集成。
- **💻 终端优先**：为命令行开发者量身打造。
- **🛡️ 开源**：基于 Apache 2.0 许可证。

## 📦 安装

请参阅
[Gemini CLI 安装、运行与版本发布](https://www.geminicli.com/docs/get-started/installation))
了解推荐系统规格和详细的安装指南。

### 快速安装

#### 使用 npx 立即运行

```bash
# Using npx (no installation required)
npx @google/gemini-cli
```

#### 使用 npm 全局安装

```bash
npm install -g @google/gemini-cli
```

#### 使用 Homebrew 全局安装（macOS/Linux）

```bash
brew install gemini-cli
```

#### 使用 MacPorts 全局安装（macOS）

```bash
sudo port install gemini-cli
```

#### 使用 Anaconda 安装（受限环境）

```bash
# Create and activate a new environment
conda create -y -n gemini_env -c conda-forge nodejs
conda activate gemini_env

# Install Gemini CLI globally via npm (inside the environment)
npm install -g @google/gemini-cli
```

## 发布渠道

详见[版本发布](https://www.geminicli.com/docs/changelogs))。

### 预览版

每周二 UTC 23:59 发布新的预览版。这些版本未经全面验证，可能包含退化或其他未解决的问题。请帮助我们测试，并使用 ``preview`` 标签安装。

```bash
npm install -g @google/gemini-cli@preview
```

### 稳定版

- 每周二 UTC 20:00 发布新的稳定版，即上周 ``preview`` 版本的完整升级，包含所有 Bug 修复和验证。使用 ``latest`` 标签。

```bash
npm install -g @google/gemini-cli@latest
```

### 每夜版

- 每天 UTC 00:00 发布新版本，包含截至发布时 main 分支上的所有变更。应假定存在待处理的验证和问题。使用 ``nightly`` 标签。

```bash
npm install -g @google/gemini-cli@nightly
```

## 📋 主要功能

### 代码理解与生成

- 查询和编辑大型代码库
- 利用多模态能力从 PDF、图片或草稿生成新应用
- 调试问题并使用自然语言排查故障

### 自动化与集成

- 自动化运维任务，如查询拉取请求或处理复杂的变基操作
- 使用 MCP 服务器连接新能力，包括
  [使用 Imagen、Veo 或 Lyria 生成媒体](https://github.com/GoogleCloudPlatform/vertex-ai-creative-studio/tree/main/experiments/mcp-genmedia))
- 以非交互模式在脚本中运行，实现工作流自动化

### 高级能力

- 使用内置的
  [Google 搜索](https://ai.google.dev/gemini-api/docs/grounding))为查询提供实时信息验证
- 对话检查点功能，可保存和恢复复杂会话
- 自定义上下文文件（GEMINI.md），为项目定制行为

### GitHub 集成

通过
[**Gemini CLI GitHub Action**](https://github.com/google-github-actions/run-gemini-cli):)
将 Gemini CLI 直接集成到您的 GitHub 工作流中

- **拉取请求审查**：基于上下文的自动化代码审查，提供反馈和建议
- **问题分类**：基于内容分析自动对 GitHub Issue 进行标注和优先级排序
- **按需协助**：在 Issue 和拉取请求中提及 ``@gemini-cli``，获取调试、解释或任务委派方面的帮助
- **自定义工作流**：构建自动化、定时和按需工作流，满足团队需求

## 🔐 身份验证选项

选择最适合您的身份验证方式：

### 选项 1：使用 Google 账号登录（OAuth 登录）

**✨ 适合：** 个人开发者以及拥有 Gemini Code Assist 许可证的用户（详见
[配额限制与服务条款](https://cloud.google.com/gemini/docs/quotas))）

**优势：**

- **免费使用额度**：每分钟 60 次请求和每日 1,000 次请求
- **Gemini 3 模型**，附带 100 万 token 上下文窗口
- **无需管理 API 密钥**——只需使用 Google 账号登录即可
- **自动更新**至最新模型

#### 启动 Gemini CLI，然后选择"使用 Google 账号登录"并按提示完成浏览器身份验证流程

```bash
gemini
```

#### 如果您使用的是所在组织的付费 Code Assist 许可证，请记得设置 Google Cloud 项目

```bash
# Set your Google Cloud Project
export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
gemini
```

### 选项 2：Gemini API 密钥

**✨ 适合：** 需要特定模型控制或付费层级访问权限的开发者

**优势：**

- **免费使用额度**：Gemini 3（Flash 和 Pro 混合）每日 1,000 次请求
- **模型选择**：选择特定的 Gemini 模型
- **按用量计费**：需要更高额度时升级

```bash
# Get your key from https://aistudio.google.com/apikey
export GEMINI_API_KEY="YOUR_API_KEY"
gemini
```

### 选项 3：Vertex AI

**✨ 适合：** 企业团队和生产环境工作负载

**优势：**

- **企业级特性**：高级安全性和合规性
- **可扩展**：使用结算账户获得更高的速率限制
- **集成**：与现有 Google Cloud 基础设施协同工作

```bash
# Get your key from Google Cloud Console
export GOOGLE_API_KEY="YOUR_API_KEY"
export GOOGLE_GENAI_USE_VERTEXAI=true
gemini
```

关于 Google Workspace 账号和其他身份验证方式，请参阅
[身份验证指南](https://www.geminicli.com/docs/get-started/authentication).)。

## 🚀 快速上手

### 基本用法

#### 在当前目录启动

```bash
gemini
```

#### 包含多个目录

```bash
gemini --include-directories ../lib,../docs
```

#### 使用指定模型

```bash
gemini -m gemini-2.5-flash
```

#### 脚本模式（非交互）

获取纯文本响应：

```bash
gemini -p "Explain the architecture of this codebase"
```

如需更高级的脚本操作（包括解析 JSON 和处理错误），请使用
``--output-format json`` 标志获取结构化输出：

```bash
gemini -p "Explain the architecture of this codebase" --output-format json
```

如需实时事件流（适用于监控长时间运行的操作），
使用 ``--output-format stream-json`` 获取换行符分隔的 JSON 事件：

```bash
gemini -p "Run tests and deploy" --output-format stream-json
```

### 快速示例

#### 启动新项目

```bash
cd new-project/
gemini
> Write me a Discord bot that answers questions using a FAQ.md file I will provide
```

#### 分析现有代码

```bash
git clone https://github.com/google-gemini/gemini-cli
cd gemini-cli
gemini
> Give me a summary of all of the changes that went in yesterday
```

## 📚 文档

### 快速入门

- [**快速开始指南**](https://www.geminicli.com/docs/get-started)) — 快速上手。
- [**认证设置**](https://www.geminicli.com/docs/get-started/authentication)) — 详细的身份验证配置。
- [**配置指南**](https://www.geminicli.com/docs/reference/configuration)) — 设置与自定义。
- [**键盘快捷键**](https://www.geminicli.com/docs/reference/keyboard-shortcuts)) — 提高效率的小技巧。

### 核心功能

- [**命令参考**](https://www.geminicli.com/docs/reference/commands)) — 所有斜杠命令（``/help``、``/chat`` 等）。
- [**自定义命令**](https://www.geminicli.com/docs/cli/custom-commands)) — 创建你自己的可复用命令。
- [**上下文文件 (GEMINI.md)**](https://www.geminicli.com/docs/cli/gemini-md)) — 为 Gemini CLI 提供持久化上下文。
- [**检查点**](https://www.geminicli.com/docs/cli/checkpointing)) — 保存和恢复对话。
- [**令牌缓存**](https://www.geminicli.com/docs/cli/token-caching)) — 优化令牌用量。

### 工具与扩展

- [**内置工具概览**](https://www.geminicli.com/docs/reference/tools))
  - [文件系统操作](https://www.geminicli.com/docs/tools/file-system))
  - [Shell 命令](https://www.geminicli.com/docs/tools/shell))
  - [网络抓取与搜索](https://www.geminicli.com/docs/tools/web-fetch))
- [**MCP 服务器集成**](https://www.geminicli.com/docs/tools/mcp-server)) — 通过自定义工具进行扩展。
- [**自定义扩展**](https://geminicli.com/docs/extensions/writing-extensions)) — 构建和分享你自己的命令。

### 高级主题

- [**无头模式（脚本化）**](https://www.geminicli.com/docs/cli/headless)) — 在自动化工作流中使用 Gemini CLI。
- [**IDE 集成**](https://www.geminicli.com/docs/ide-integration)) — VS Code 配套工具。
- [**沙箱与安全**](https://www.geminicli.com/docs/cli/sandbox)) — 安全的执行环境。
- [**受信任文件夹**](https://www.geminicli.com/docs/cli/trusted-folders)) — 按文件夹控制执行策略。
- [**企业指南**](https://www.geminicli.com/docs/cli/enterprise)) — 在企业环境中部署和管理。
- [**遥测与监控**](https://www.geminicli.com/docs/cli/telemetry)) — 使用追踪。
- [**工具参考**](https://www.geminicli.com/docs/reference/tools)) — 内置工具概览。
- [**本地开发**](https://www.geminicli.com/docs/local-development)) — 本地开发工具。

### 故障排查与支持

- [**故障排查指南**](https://www.geminicli.com/docs/resources/troubleshooting)) — 常见问题与解决方案。
- [**常见问题**](https://www.geminicli.com/docs/resources/faq)) — 常见问题解答。
- 使用 ``/bug`` 命令直接从 CLI 报告问题。

### 使用 MCP 服务器

在 ``~/.gemini/settings.json`` 中配置 MCP 服务器，以通过自定义工具扩展 Gemini CLI：

```text
> @github List my open pull requests
> @slack Send a summary of today's commits to #dev channel
> @database Run a query to find inactive users
```

有关设置说明，请参阅
[MCP 服务器集成指南](https://www.geminicli.com/docs/tools/mcp-server))。

## 🤝 贡献

欢迎贡献！Gemini CLI 是完全开源的（Apache 2.0），我们鼓励社区：

- 报告 Bug 和提出功能建议。
- 改进文档。
- 提交代码改进。
- 分享你的 MCP 服务器和扩展。

请参阅我们的[贡献指南](./CONTRIBUTING.md)，了解开发环境搭建、编码标准以及如何提交 Pull Request。

查看我们的[官方路线图](https://github.com/orgs/google-gemini/projects/11))，了解计划中的功能和优先级。

## 📖 资源

- **[免费课程](https://learn.deeplearning.ai/courses/gemini-cli-code-and-create-with-an-open-source-agent/information)**)** — 学习基础知识。
- **[官方路线图](./ROADMAP.md)** — 查看下一步计划。
- **[更新日志](https://www.geminicli.com/docs/changelogs)**)** — 查看近期重要更新。
- **[NPM 包](https://www.npmjs.com/package/@google/gemini-cli)**)** — 包注册表。
- **[GitHub Issues](https://github.com/google-gemini/gemini-cli/issues)**)** — 报告 Bug 或请求功能。
- **[安全公告](https://github.com/google-gemini/gemini-cli/security/advisories)**)** — 安全更新。

### 卸载

请参阅[卸载指南](https://www.geminicli.com/docs/resources/uninstall))了解移除步骤。

## 📄 法律信息

- **许可证**：[Apache License 2.0](LICENSE)
- **服务条款**：[条款与隐私](https://www.geminicli.com/docs/resources/tos-privacy))
- **安全**：[安全策略](SECURITY.md)

<p align="left">
 <a href="https://www.star-history.com/google-gemini/gemini-cli">
  <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=google-gemini/gemini-cli&theme=dark" />
   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/badge?repo=google-gemini/gemini-cli" />
   <img alt="Star History Rank" src="https://api.star-history.com/badge?repo=google-gemini/gemini-cli" />
  </picture>
 </a>
</p>

---

<p align="center">
  由 Google 与开源社区 ❤️ 共同构建
</p>