Gemini CLI 认证设置

Gemini CLI 认证设置

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

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

选择你的认证方法

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

用户类型 / 场景	推荐的认证方法	是否需要 Google 云项目
个人 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 的终端通信的机器上有一个网页浏览器（例如，您的本地机器）。

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

要认证并使用 Gemini CLI：

1. 启动 CLI：

   gemini

2. 选择 使用Google 账户登录。Gemini CLI 会使用您的网页浏览器打开一个登录提示。按照屏幕上的说明操作。您的凭证将被本地缓存，以便用于将来的会话。

我需要设置我的Google Cloud项目吗？

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

• 您使用的是公司、学校或 Google Workspace 账户。
• 您使用的是来自Google 开发者计划的 Gemini Code Assist 许可证。
• 您使用的是 Gemini Code Assist 订阅的许可证。

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

使用 Gemini API 密钥

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

使用 Gemini CLI 和 Gemini API 密钥进行认证和使用：

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

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

   # Replace YOUR_GEMINI_API_KEY with the key from AI Studio
   export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"

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

3. 启动 CLI：

   gemini

4. 选择 使用 Gemini API 密钥。

警告： 对于像 Gemini 这样的服务的 API 密钥，应视为敏感凭据。保护它们以防止未授权访问和潜在的服务滥用。

使用 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 资源的位置或您想要运行作业的位置。

例如：

# Replace with your project ID and desired location (e.g., 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 用户”角色。

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

    # Replace /path/to/your/keyfile.json with the actual path
    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：

    # Replace YOUR_GOOGLE_API_KEY with your Vertex AI API key
    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开发者计划的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_ID 变量：

   # Replace YOUR_PROJECT_ID with your actual Google Cloud project ID
   export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"

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

持久化环境变量

为了避免为每个终端会话设置环境变量，您可以使用以下方法将其持久化：

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

   # Example for .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"
   # Add other variables like GEMINI_API_KEY as needed
   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：配额和定价。
• Gemini CLI：服务条款和隐私声明。