> [!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
[](https://github.com/google-gemini/gemini-cli/actions/workflows/ci.yml)
[](https://github.com/google-gemini/gemini-cli/actions/workflows/chained_e2e.yml)
[](https://www.npmjs.com/package/@google/gemini-cli)
[](https://github.com/google-gemini/gemini-cli/blob/main/LICENSE)
[](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 是一个开源 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)
---
由 Google 与开源社区 ❤️ 共同构建