Gemini CLI 认证配置

要使用 Gemini CLI，你需要通过 Google 进行认证。本指南帮助你根据账户类型和使用方式快速找到最佳登录方式。

对于大多数用户，我们建议启动 Gemini CLI 并使用个人 Google 账户登录。

选择认证方法

在下表中选择与你情况匹配的认证方法：

用户类型/场景	推荐认证方法	需要 Google Cloud 项目
个人 Google 账户	使用 Google 登录	否，有例外
使用公司、学校或 Google Workspace 账户的组织用户	使用 Google 登录	是
拥有 Gemini API 密钥的 AI Studio 用户	使用 Gemini API 密钥	否
Google Cloud Vertex AI 用户	Vertex AI	是
无头模式	使用 Gemini API 密钥 或 Vertex AI	否（Gemini API 密钥）/ 是（Vertex AI）

我的 Google 账户类型是什么？

• 个人 Google 账户： 包括所有免费层账户（如个人版 Gemini Code Assist），以及 Google AI Pro 和 Ultra 的付费订阅。

• 组织账户： 通过组织（如公司、学校或 Google Workspace）使用付费许可证的账户。包括 Google AI Ultra for Business 订阅。

（推荐）使用 Google 登录

如果你在本地机器上运行 Gemini CLI，最简单的认证方法是使用 Google 账户登录。此方法需要在可以与运行 Gemini CLI 的终端通信的机器上使用 Web 浏览器（例如你的本地机器）。

重要： 如果你是 Google AI Pro 或 Google AI Ultra 订阅者，请使用与订阅关联的 Google 账户。

要认证并使用 Gemini CLI：

1. 启动 CLI：

   gemini

2. 选择 Login with Google。Gemini CLI 使用 Web 浏览器打开登录提示。按照屏幕上的说明操作。你的凭据将在本地缓存以供将来会话使用。

我需要设置 Google Cloud 项目吗？

大多数个人 Google 账户（免费和付费）不需要 Google Cloud 项目进行认证。但是，当你满足以下至少一个条件时，需要设置 Google Cloud 项目：

• 你使用的是公司、学校或 Google Workspace 账户。
• 你使用的是来自 Google Developer Program 的 Gemini Code Assist 许可证。
• 你使用的是来自 Gemini Code Assist 订阅的许可证。

有关说明，请参阅设置 Google Cloud 项目。

使用 Gemini API 密钥

如果你不想使用 Google 账户进行认证，可以使用来自 Google AI Studio 的 API 密钥。

要使用 Gemini API 密钥认证并使用 Gemini CLI：

1. 从 Google AI Studio 获取你的 API 密钥。

2. 将 GEMINI_API_KEY 环境变量设置为你的密钥。例如：

   # 将 YOUR_GEMINI_API_KEY 替换为来自 AI Studio 的密钥
   export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"

   要使此设置持久化，请参阅持久化环境变量。

3. 启动 CLI：

   gemini

4. 选择 Use Gemini API key。

警告： 将 API 密钥（特别是 Gemini 等服务的密钥）视为敏感凭据。保护它们以防止未经授权的访问和潜在的服务滥用。

使用 Vertex AI

要将 Gemini CLI 与 Google Cloud 的 Vertex AI 平台一起使用，请从以下认证选项中选择：

• A. 使用 gcloud 的应用程序默认凭据 (ADC)。
• B. 服务账户 JSON 密钥。
• C. Google Cloud API 密钥。

无论你选择哪种 Vertex AI 认证方法，都需要将 GOOGLE_CLOUD_PROJECT 设置为启用了 Vertex AI API 的 Google Cloud 项目 ID，并将 GOOGLE_CLOUD_LOCATION 设置为 Vertex AI 资源的位置或你想要运行作业的位置。

例如：

# 替换为你的项目 ID 和所需位置（例如 us-central1）
export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION"

要使任何 Vertex AI 环境变量设置持久化，请参阅持久化环境变量。

A. Vertex AI - 使用 gcloud 的应用程序默认凭据 (ADC)

如果你已安装 Google Cloud CLI，请考虑此认证方法。

注意： 如果你之前设置了 GOOGLE_API_KEY 或 GEMINI_API_KEY，必须取消设置它们才能使用 ADC：

unset GOOGLE_API_KEY GEMINI_API_KEY

1. 验证你有 Google Cloud 项目并且已启用 Vertex AI API。

2. 登录 Google Cloud：

   gcloud auth application-default login

3. 配置你的 Google Cloud 项目。

4. 启动 CLI：

   gemini

5. 选择 Vertex AI。

B. Vertex AI - 服务账户 JSON 密钥

在非交互式环境、CI/CD 管道中，或者如果你的组织限制基于用户的 ADC 或 API 密钥创建，请考虑此认证方法。

注意： 如果你之前设置了 GOOGLE_API_KEY 或 GEMINI_API_KEY，必须取消设置它们：

unset GOOGLE_API_KEY GEMINI_API_KEY

1. 创建服务账户和密钥并下载提供的 JSON 文件。为服务账户分配 "Vertex AI User" 角色。

2. 将 GOOGLE_APPLICATION_CREDENTIALS 环境变量设置为 JSON 文件的绝对路径。例如：

   # 将 /path/to/your/keyfile.json 替换为实际路径
   export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/keyfile.json"

3. 配置你的 Google Cloud 项目。

4. 启动 CLI：

   gemini

5. 选择 Vertex AI。

警告： 保护你的服务账户密钥文件，因为它可以访问你的资源。

C. Vertex AI - Google Cloud API 密钥

1. 获取 Google Cloud API 密钥：获取 API 密钥。

2. 设置 GOOGLE_API_KEY 环境变量：

   # 将 YOUR_GOOGLE_API_KEY 替换为你的 Vertex AI API 密钥
   export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"

   注意： 如果你看到类似 "API keys are not supported by this API..." 的错误，你的组织可能限制了此服务的 API 密钥使用。请尝试其他 Vertex AI 认证方法。

3. 配置你的 Google Cloud 项目。

4. 启动 CLI：

   gemini

5. 选择 Vertex AI。

设置 Google Cloud 项目

重要： 大多数个人 Google 账户（免费和付费）不需要 Google Cloud 项目进行认证。

当你使用 Google 账户登录时，可能需要为 Gemini CLI 配置 Google Cloud 项目。这适用于满足以下至少一个条件的情况：

• 你使用的是公司、学校或 Google Workspace 账户。
• 你使用的是来自 Google Developer Program 的 Gemini Code Assist 许可证。
• 你使用的是来自 Gemini Code Assist 订阅的许可证。

要配置 Gemini CLI 使用 Google Cloud 项目，请执行以下操作：

1. 查找你的 Google Cloud 项目 ID。

2. 启用 Gemini for Cloud API。

3. 配置必要的 IAM 访问权限。

4. 配置环境变量。将 GOOGLE_CLOUD_PROJECT 或 GOOGLE_CLOUD_PROJECT_ID 变量设置为要与 Gemini CLI 一起使用的项目 ID。Gemini CLI 首先检查 GOOGLE_CLOUD_PROJECT，然后回退到 GOOGLE_CLOUD_PROJECT_ID。

   例如，设置 GOOGLE_CLOUD_PROJECT 变量：

   # 将 YOUR_PROJECT_ID 替换为你的实际 Google Cloud 项目 ID
   export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"

   要使此设置持久化，请参阅持久化环境变量。

持久化环境变量

为避免每次终端会话都设置环境变量，你可以使用以下方法持久化它们：

1. 将环境变量添加到 shell 配置文件： 将 export ... 命令附加到 shell 的启动文件（例如 ~/.bashrc、~/.zshrc 或 ~/.profile）并重新加载 shell（例如 source ~/.bashrc）。

   # .bashrc 示例
   echo 'export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"' >> ~/.bashrc
   source ~/.bashrc

   警告： 请注意，当你在 shell 配置文件中导出 API 密钥或服务账户路径时，从该 shell 启动的任何进程都可以读取它们。

2. 使用 .env 文件： 在项目目录或主目录中创建 .gemini/.env 文件。Gemini CLI 自动从找到的第一个 .env 文件加载变量，从当前目录向上搜索，然后在 ~/.gemini/.env 或 ~/.env 中搜索。推荐使用 .gemini/.env。

   用户范围设置示例：

   mkdir -p ~/.gemini
   cat >> ~/.gemini/.env <<'EOF'
   GOOGLE_CLOUD_PROJECT="your-project-id"
   # 根据需要添加其他变量，如 GEMINI_API_KEY
   EOF

变量从找到的第一个文件加载，不会合并。

在 Google Cloud 环境中运行

在某些 Google Cloud 环境中运行 Gemini CLI 时，认证是自动的。

在 Google Cloud Shell 环境中，Gemini CLI 通常使用你的 Cloud Shell 凭据自动认证。在 Compute Engine 环境中，Gemini CLI 自动使用来自环境元数据服务器的应用程序默认凭据 (ADC)。

如果自动认证失败，请使用本页描述的交互式方法之一。

无头模式

无头模式将使用你现有的认证方法（如果已缓存现有认证凭据）。

如果你尚未使用认证凭据登录，必须使用环境变量配置认证：

• 使用 Gemini API 密钥
• Vertex AI

下一步

你的认证方法会影响你的配额、定价、服务条款和隐私声明。查看以下页面了解更多：

• Gemini CLI：配额与定价。