Gemini 教程博客站
api.clawsocket.com
更新于 2026-04-06 · 阅读 13 分钟

Gemini CLI 安装与配置完整教程：从安装到认证的实用指南

大模型 AI 中转站：api.clawsocket.com 支持 GPT gemini claude grok 等最新模型 api 并且价格只有官方七分之一

摘要：讲清楚 Gemini CLI 怎么安装、怎么登录、怎么配置 Gemini API Key，以及日常开发中最常用的启动方式。

Gemini CLI 是 Google 官方开源的终端 AI Agent。
如果你平时就在命令行里工作，那么 Gemini CLI 的价值很好理解：它不是一个单纯的聊天工具，而是一个可以直接进入开发流程的终端助手。

很多人第一次接触 Gemini CLI 时，最常见的问题通常是：

  • Gemini CLI 怎么安装
  • 安装以后怎么登录
  • Gemini API Key 怎么配置
  • Google 登录、API Key、Vertex AI 这几种方式到底该选哪个

这篇文章就按最实用的顺序，把这些问题一次讲清楚。

快速结论

  • Gemini CLI 官方项目是 google-gemini/gemini-cli
  • 最常见的安装方式是 npx @google/gemini-cli 或 npm install -g @google/gemini-cli
  • 官方当前提供 3 种主要认证方式：Google 登录、Gemini API Key、Vertex AI
  • 对大多数个人开发者来说，先用 Google 登录 或 GEMINI_API_KEY 就够了

Gemini CLI 是什么

Gemini CLI 是 Google 官方推出的开源终端工具，可以直接在命令行里使用 Gemini 模型完成开发任务。

根据官方 README，截至我核对时的公开说明，Gemini CLI 具备这些特点：

  • 提供 Gemini 3 模型访问能力
  • 适合终端开发工作流
  • 支持文件操作、Shell 命令、Web 获取等工具能力
  • 支持 MCP 扩展
  • 支持非交互模式，适合脚本和自动化场景

如果你本来就在使用 Codex、Claude Code、OpenClaw 这类工具，那么 Gemini CLI 基本可以理解成 Google 这条技术栈里的对应选项。

第 1 步：安装 Gemini CLI

官方 README 当前给出的安装方式有几种，最常用的是下面这两种。

方式一：用 npx 直接运行

如果你只是想先试一下，最轻量的方式是：

npx @google/gemini-cli

这种方式的优点是不用全局安装，打开就能跑，适合先体验。

方式二：全局安装

如果你准备长期使用，更推荐直接全局安装：

npm install -g @google/gemini-cli

装好以后，你就可以直接运行：

gemini

其他安装方式

官方 README 里还提到了其他安装方式，包括：

  • brew install gemini-cli
  • sudo port install gemini-cli
  • 在 Anaconda 环境里安装 Node.js 后再用 npm 装 CLI

如果你是在受限环境、企业机器或特定包管理器生态里工作，这些方式会更方便。

第 2 步：确认安装是否成功

最简单的验证方式就是直接执行：

gemini

如果命令能正常启动并进入认证或交互界面，说明安装基本就已经成功了。

第 3 步：选择认证方式

Gemini CLI 官方当前主要提供 3 种认证方式。

方式一：使用 Google 账号登录

这是官方最推荐给个人开发者的方式之一。

官方说明里提到，这种方式比较适合：

  • 个人开发者
  • 已经有 Gemini Code Assist 许可的用户
  • 不想自己额外管理 API Key 的用户

使用方式很简单：

gemini

启动后选择 Sign in with Google，然后跟着浏览器里的流程走即可。

如果你使用的是组织购买的 Gemini Code Assist 许可，官方还建议设置：

export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
gemini

方式二：使用 Gemini API Key

如果你希望自己控制模型和计费方式，API Key 会更合适。

官方 README 当前给出的方式是：

export GEMINI_API_KEY="YOUR_API_KEY"
gemini

这个 Key 一般来自：

Google AI Studio API Key

这种方式适合：

  • 你明确想自己管理 Gemini API 使用
  • 你要控制项目里到底走哪个 API Key
  • 你已经有现成的后端或脚本化工作流

方式三：使用 Vertex AI

如果你是企业团队、生产环境或者本来就在 Google Cloud 体系里，Vertex AI 这条路线更适合。

官方 README 里的示例是：

export GOOGLE_API_KEY="YOUR_API_KEY"
export GOOGLE_GENAI_USE_VERTEXAI=true
gemini

这类方式更适合：

  • 企业级安全和合规要求
  • 更高配额
  • 已经有 Google Cloud 基础设施

第 4 步：把配置写进 shell 环境

如果你不想每次都手动输入环境变量，建议直接把它们写进 shell 配置文件。

如果你用的是 zsh：

echo 'export GEMINI_API_KEY="YOUR_API_KEY"' >> ~/.zshrc
source ~/.zshrc

如果你是 Google 登录路线，通常不需要额外长期保存 API Key；但如果你走 API Key 模式，这一步很有必要。

如果你用的是 bash，则改成写入：

  • ~/.bashrc
  • 或 ~/.bash_profile

第 5 步：最常见的 Gemini CLI 使用方式

安装并认证完成后，最常见的使用方式有下面几种。

在当前目录启动 

gemini

这是最常见的用法，Gemini CLI 会把当前目录作为上下文。

指定多个目录 

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

如果你的项目结构比较分散，这个方式很实用。

指定模型 

gemini -m gemini-2.5-flash

当你想手动切模型时，这个参数就很方便。

非交互模式

如果你是写脚本、做自动化，官方 README 也给了这种方式：

gemini -p "Explain the architecture of this codebase"

如果你想拿结构化输出：

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

如果你想做事件流式处理：

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

第 6 步：配置 MCP 和扩展能力

Gemini CLI 官方当前也支持 MCP。

README 里明确提到，MCP server 的配置文件位置是：

~/.gemini/settings.json

这意味着如果你后面想让 Gemini CLI 接更多工具、更多上下文能力，MCP 会是你继续往下扩展的主要入口之一。

常见问题

Gemini CLI 安装后为什么命令找不到

通常有 3 个原因：

  • npm 全局安装目录不在 PATH 里
  • Node.js / npm 本身没装好
  • 你用了 npx 路线，但并没有正确执行包名

最稳的排查方式是：

  1. node -v
  2. npm -v
  3. npm install -g @google/gemini-cli
  4. 再执行 gemini

Google 登录和 API Key 应该选哪个

一般可以这样判断：

  • 想最省事：选 Google 登录
  • 想自己控制 API Key：选 GEMINI_API_KEY
  • 企业或生产环境：选 Vertex AI

对大多数个人开发者来说，前两个已经足够。

Gemini CLI 和 Gemini API 是一回事吗

不是一回事，但有关联。

Gemini API 是底层模型调用接口，Gemini CLI 是 Google 官方做的终端工具。CLI 可以通过 Google 登录、API Key 或 Vertex AI 去访问底层模型能力。

如果我更想统一多个模型入口怎么办

如果你的目标是直接在代码层统一 OpenAI、Claude、Gemini 等多模型入口，而不是只在终端里使用 Gemini CLI，那么更适合你的可能不是 CLI 本身，而是一个统一 API 入口。

在这种情况下，可以考虑直接通过 api.clawsocket.com 来统一接入不同模型，把重点放在产品和开发流程上，而不是每个模型各配一套 API 调用方式。

最佳实践建议

如果你准备长期用 Gemini CLI，我建议顺手保留这些习惯：

  • 先用 npx 试，再决定是否全局安装
  • API Key 一律放环境变量，不要写进项目源码
  • 需要脚本化时优先用 --output-format json
  • 复杂目录场景下用 --include-directories
  • 以后要扩展工具能力时，再去配 ~/.gemini/settings.json

总结

Gemini CLI 的安装和配置并不复杂，关键就是把顺序理清楚：

  1. 先安装 CLI
  2. 再选择认证方式
  3. 把 API Key 或环境变量配置好
  4. 用最基本的 gemini 命令启动验证
  5. 需要脚本化或扩展时，再继续加模型参数、输出格式和 MCP 配置

如果你的目标是把 Gemini 当作终端开发助手，这已经足够开始使用。
如果你的目标是统一产品里的多模型 API 入口，那么可以继续看：

参考资料