Skip to content
FunCoding

Search

Search docs, agents, posts, Skills and MCP servers

认证

Gemini CLI 的登录方式：用 Google 账号登录（推荐）、Gemini API Key、Vertex AI（ADC、服务账号、API Key）；什么时候需要 Google Cloud 项目、如何持久化环境变量。

使用 Gemini CLI 需要向 Google 认证。多数用户推荐先启动 Gemini CLI，用个人 Google 账号登录。你的认证方式会影响配额、价格、服务条款和隐私声明（见「配额与价格」页）。

怎么选

用户类型 / 场景推荐的认证方式是否需要 Google Cloud 项目
个人 Google 账号Sign in with Google否（有例外）
使用公司、学校或 Google Workspace 账号的组织用户Sign in with Google是
有 Gemini API Key 的 AI Studio 用户使用 Gemini API Key否
Google Cloud Vertex AI 用户Vertex AI是
无头模式Gemini API Key 或 Vertex AIGemini API Key 不需要，Vertex AI 需要

个人 Google 账号包括所有免费层账号（如面向个人的 Gemini Code Assist），以及 Google AI Pro 和 Ultra 的付费订阅。组织账号指通过公司、学校或 Google Workspace 等组织使用付费许可的账号，包括 Google AI Ultra for Business 订阅。

推荐：用 Google 账号登录

如果在本机运行 Gemini CLI，最简单的认证方式就是用 Google 账号登录。这种方式需要在能与运行 Gemini CLI 的终端通信的机器上有网页浏览器。如果你是 Google AI Pro 或 Google AI Ultra 订阅用户，使用与订阅关联的 Google 账号。步骤：启动 gemini，选 Sign in with Google，Gemini CLI 用浏览器打开登录提示，按屏幕说明操作；你的凭据会缓存在本地供后续会话使用。

我需要设置 Google Cloud 项目吗？ 大多数个人 Google 账号（免费和付费）认证时不需要 Google Cloud 项目。但满足以下至少一个条件时需要设置：使用公司、学校或 Google Workspace 账号；使用来自 Google Developer Program 的 Gemini Code Assist 许可；使用 Gemini Code Assist 订阅的许可。设置方法：查找你的 Google Cloud 项目 ID；启用 Gemini for Cloud API；配置必要的 IAM 访问权限；然后把环境变量 GOOGLE_CLOUD_PROJECT 或 GOOGLE_CLOUD_PROJECT_ID 设为项目 ID（Gemini CLI 先检查 GOOGLE_CLOUD_PROJECT，再回退到 GOOGLE_CLOUD_PROJECT_ID）。

使用 Gemini API Key

不想用 Google 账号认证时，可以用 Google AI Studio 的 API Key：

  1. 从 Google AI Studio 获取 API Key
  2. 把 GEMINI_API_KEY 环境变量设为你的 Key，例如 export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"（Windows PowerShell 用 $env:GEMINI_API_KEY="..."）
  3. 启动 gemini，选 Use Gemini API key

把 API Key（尤其是 Gemini 这类服务的）当作敏感凭据对待，保护好它们，防止未授权访问和在你账号下的滥用。

使用 Vertex AI

要让 Gemini CLI 使用 Google Cloud 的 Vertex AI 平台，可以选择三种认证选项：A. 通过 gcloud 的应用默认凭据（ADC）；B. 服务账号 JSON 密钥；C. Google Cloud API Key。无论哪种方式，都要把 GOOGLE_CLOUD_PROJECT 设为启用了 Vertex AI API 的 Google Cloud 项目 ID，并把 GOOGLE_CLOUD_LOCATION 设为你的 Vertex AI 资源所在的位置（或你想运行任务的位置，如 us-central1）。

  • A. ADC：已安装 Google Cloud CLI 时考虑这种方式。如果之前设置过 GOOGLE_API_KEY 或 GEMINI_API_KEY，必须先 unset 它们。确认有 Google Cloud 项目且启用了 Vertex AI API，运行 gcloud auth application-default login，配置 Google Cloud 项目，启动 gemini 并选 Vertex AI
  • B. 服务账号 JSON 密钥：适用于非交互环境、CI/CD 流水线，或你的组织限制基于用户的 ADC 或 API Key 创建的情形。同样要先 unset GOOGLE_API_KEY 和 GEMINI_API_KEY。创建服务账号和密钥并下载 JSON 文件，给服务账号分配「Vertex AI User」角色，把 GOOGLE_APPLICATION_CREDENTIALS 设为该 JSON 文件的绝对路径，配置 Google Cloud 项目，启动 gemini 并选 Vertex AI
  • C. Google Cloud API Key：官方文档里有对应说明；如果看到 API keys are not supported by this API... 这类错误，说明你的组织可能限制了这项服务的 API Key 使用，改用其他 Vertex AI 认证方式

持久化环境变量

要避免在每个终端会话里重新设置环境变量，有两种办法：

  1. 加进 shell 配置文件：把环境变量命令追加到 shell 的启动文件（如 ~/.bashrc、~/.zshrc、~/.profile，PowerShell 里是 $PROFILE）。注意：在 shell 配置文件里导出 API Key 或服务账号路径后，从该 shell 启动的任何进程都能读到它们
  2. 用 .env 文件：在项目目录或主目录里创建 .gemini/.env。Gemini CLI 自动加载找到的第一个 .env 文件：从当前目录向上搜索，然后是主目录的 .gemini/.env（如 ~/.gemini/.env）。变量从找到的第一个文件加载，不合并

在 Google Cloud 环境里自动认证

在 Google Cloud Shell 里，Gemini CLI 通常用你的 Cloud Shell 凭据自动认证；在 Compute Engine 环境里，它自动使用环境元数据服务器的应用默认凭据（ADC）。自动认证失败时，改用本页的交互方式。

无头模式

无头模式会使用你已有的认证方式（如果有缓存的凭据）。如果还没有用某个认证凭据登录过，就必须用环境变量配置认证：使用 Gemini API Key 或 Vertex AI。