地呱碰知识库

【攻略】Gemini CLI使用指南

攻略GitHubAI工具发布：2026-07-01 10:41:16更新：2026-07-01 10:41:16

Gemini CLI 是 Google 开源的终端 AI Agent，可通过 OAuth、Gemini API Key 或 Vertex AI 接入模型，适合代码理解、自动化任务和 MCP 工具集成。

这是什么

Gemini CLI 是 Google 开源的终端 AI Agent，主仓库为 google-gemini/gemini-cli。它把 Gemini 放进命令行，适合在本地项目中做代码理解、代码生成、自动化任务、文件处理、多目录上下文分析和工具调用。

从项目元数据看，Gemini CLI 使用 TypeScript 编写，License 为 Apache-2.0，包名是 @google/gemini-cli，命令名是 gemini。GitHub API 显示该仓库在 2026-07-01 仍有 push 活动，项目主页为 geminicli.com。项目的 package.json 要求 Node.js 20 或更高版本。

适合解决什么问题

Gemini CLI 最适合放在开发者每天已经打开的终端里，而不是另起一个聊天窗口。典型场景包括：

快速理解一个代码库的结构、入口和模块关系
让模型跨多个目录阅读代码和文档
生成脚本、测试、迁移说明或命令行辅助工具
在本地文件上下文中解释报错、整理变更和输出 JSON
通过 MCP 接入 GitHub、Slack、数据库或内部工具
在 GitHub Actions 中做 PR review、issue triage 或按需代码助手

它的定位不是替代 IDE，而是把“问模型”和“跑命令、看文件、改项目”的距离缩短。

安装方式

最快的方式是直接用 npx 运行：

npx @google/gemini-cli

如果需要长期使用，可以全局安装：

npm install -g @google/gemini-cli

macOS 用户也可以用 Homebrew：

brew install gemini-cli

MacPorts 用户可以使用：

sudo port install gemini-cli

如果你用 conda 管理环境，可以先装 Node.js，再装 CLI：

conda create -n gemini-cli nodejs\nconda activate gemini-cli\nnpm install -g @google/gemini-cli

官方 README 还说明了三个发布通道：stable 每周二 20:00 UTC 推送 latest，preview 每周二 23:59 UTC 推送 preview，nightly 每天 00:00 UTC 推送 nightly。生产环境建议优先使用 latest，并固定团队文档中的安装方式。

第一次登录与模型接入

安装后运行：

gemini

最省事的方式是 Google OAuth。官方 README 写明，使用个人 Google 账号登录后可获得免费额度，适合日常试用和轻量开发。

如果你要用 Gemini API Key，可以设置环境变量：

export GEMINI_API_KEY="YOUR_API_KEY"\ngemini

如果企业已经在 Google Cloud 上使用 Vertex AI，可以按官方方式启用 Vertex：

export GOOGLE_API_KEY="YOUR_API_KEY"\nexport GOOGLE_GENAI_USE_VERTEXAI=true\ngemini

无论哪种方式，都不要把 API Key 写进仓库、截图或日志。团队协作时，建议把密钥放在操作系统环境变量、CI Secret 或统一的密钥管理服务里。

常用命令

进入项目目录后启动交互会话：

gemini

让 Gemini 同时读取多个目录：

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

指定模型：

gemini -m gemini-2.5-flash

用一次性提示词分析代码库：

gemini -p "Explain the architecture of this codebase"

要求输出 JSON：

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

在自动化流水线里使用流式 JSON：

gemini -p "Run tests and summarize failures" --output-format stream-json

这类命令的好处是可以被脚本、CI 或本地 alias 组合起来，形成团队自己的小工具。

MCP 与 GitHub Actions

Gemini CLI 支持 MCP 服务器配置，默认配置文件位于 ~/.gemini/settings.json。官方 README 给出的方向包括 GitHub、Slack、数据库等工具接入。一个常见做法是先把只读能力接进来，比如仓库检索、issue 查询、文档搜索；等流程稳定后，再逐步开放写入能力。

项目还提供 GitHub Action：google-github-actions/run-gemini-cli。它适合放在 PR review、issue triage、按需代码助手等场景里。需要注意的是，CI 里的权限要比本地更严格，建议把 token 权限、可访问路径和可执行命令写清楚，避免让 Agent 在流水线里获得过大的操作范围。

常见坑

第一，Node.js 版本要够新。package.json 要求 Node.js 20 或更高，老环境先升级运行时。

第二，认证方式要分清。OAuth 适合个人试用，Gemini API Key 适合开发者脚本，Vertex AI 更适合已经有 Google Cloud 账号、项目和企业治理要求的团队。

第三，CLI 能读写本地项目，使用前要确认当前目录是否可信。不要在包含敏感凭证、私钥或生产配置的目录里随意让 Agent 扫描全量文件。

第四，MCP 很强，但也会扩大边界。接入数据库、工单、仓库写权限之前，先从只读开始，逐步增加权限，并保留日志。

第五，不要安装来路不明的“Gemini CLI 增强版”。官方项目地址是 github.com/google-gemini/gemini-cli，npm 包名是 @google/gemini-cli。

适合谁，不适合谁

适合的人：每天在终端里处理代码、脚本、文档和自动化任务的开发者；需要把模型接入研发流程的技术负责人；想用 MCP 把 AI 接入内部工具的团队。

不太适合的人：只想简单聊天、没有命令行使用习惯、或不愿意管理 API Key 和本地权限的用户。对这类用户，网页端或 IDE 插件会更自然。

企业实践场景

对中小型技术团队来说，Gemini CLI 可以先作为“项目问答和脚本助手”落地，再逐步接入 GitHub、文档库和测试命令。这样既能提升研发效率，也能把权限、日志和操作边界留在团队熟悉的工程体系里。

参考链接

GitHub 仓库：google-gemini/gemini-cli
项目主页：geminicli.com
License：Apache-2.0
GitHub Action：google-github-actions/run-gemini-cli