Gemini CLI 身份验证设置

Gemini CLI 需要使用 Google 服务进行身份验证。在使用 Gemini CLI 之前，请配置 任一 以下身份验证方法：

• 交互模式：
  • 推荐：使用 Google 登录
  • 使用 Gemini API 密钥
  • 使用 Vertex AI
• 无头（非交互式）模式
• Google Cloud Shell

快速检查：是否在 Google Cloud Shell 中运行？

如果您在 Google Cloud Shell 环境中运行 Gemini CLI，身份验证通常会使用您的 Cloud Shell 凭据自动完成。

在交互模式下进行身份验证

当您通过命令行运行 Gemini CLI 时，Gemini CLI 将提供以下选项：

> 1. 使用 Google 登录
> 2. 使用 Gemini API 密钥
> 3. Vertex AI

以下各节提供了每种身份验证选项的说明。

推荐：使用 Google 登录

如果您在本地计算机上运行 Gemini CLI，最简单的方法是使用您的 Google 帐户登录。

重要提示： 如果您是 Google AI Pro 或 Google AI Ultra 订阅用户，请使用此方法。

1. 选择 使用 Google 登录。Gemini CLI 将使用您的网络浏览器打开登录提示。

   如果您是 Google AI Pro 或 Google AI Ultra 订阅用户，请使用与您的订阅关联的 Google 帐户登录。

2. 按照屏幕上的说明操作。您的凭据将缓存到本地，供以后使用。

   注意： 此方法需要一个能够与运行 CLI 的终端通信的网络浏览器（例如，您的本地计算机）。浏览器将被重定向到 CLI 在设置过程中监听的 localhost URL。

(可选) 设置您的 GOOGLE_CLOUD_PROJECT

当您使用 Google 帐户登录时，可能会提示您选择一个 GOOGLE_CLOUD_PROJECT。

如果您符合以下任一情况，则可能需要此设置：

• 使用 Google Workspace 帐户。
• 使用来自 Google Developer Program 的 Gemini Code Assist 许可证。
• 使用来自 Gemini Code Assist 订阅的许可证。
• 在免费个人使用支持的区域 不支持的区域 之外使用该产品。
• 年龄未满 18 岁的 Google 帐户持有者。

如果您属于以上任一类别，则必须：

1. 拥有一个 Google Cloud 项目 ID。
2. 启用 Gemini for Cloud API。
3. 配置必要的 IAM 访问权限。

要设置项目 ID，请导出 GOOGLE_CLOUD_PROJECT 环境变量：

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

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

使用 Gemini API 密钥

如果您不想使用 Google 帐户进行身份验证，可以使用 Google AI Studio 的 API 密钥。

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

2. 设置 GEMINI_API_KEY 环境变量：

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

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

警告： 将 API 密钥（尤其是像 Gemini 这样的服务）视为敏感凭据。保护好它们，以防止未经授权的访问和潜在的服务滥用。

使用 Vertex AI

如果您打算使用 Google Cloud 的 Vertex AI 平台，有几种身份验证选项：

• 应用程序默认凭据 (ADC) 和 gcloud。
• 服务帐户 JSON 密钥。
• Google Cloud API 密钥。

首先：设置所需的环境变量

无论您选择哪种身份验证方法，通常都需要设置以下变量：GOOGLE_CLOUD_PROJECT 和 GOOGLE_CLOUD_LOCATION。

要设置这些变量：

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

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_PROJECT 和 GOOGLE_CLOUD_LOCATION。

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 文件的绝对路径：

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

3. 确保已设置 GOOGLE_CLOUD_PROJECT 和 GOOGLE_CLOUD_LOCATION。

警告： 保护您的服务帐户密钥文件，因为它提供了对您资源的访问权限。

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 密钥使用。请尝试使用 服务帐户 JSON 密钥 或 ADC 方法。

要使这些 Vertex AI 环境变量设置中的任何一个持久化，请参阅 持久化环境变量。

持久化环境变量

为了避免在每个终端会话中都设置环境变量，您可以：

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 帐户）登录，则 必须 使用环境变量配置身份验证：

1. Gemini API 密钥： 设置 GEMINI_API_KEY。
2. Vertex AI：
   • 设置 GOOGLE_GENAI_USE_VERTEXAI=true。
   • 使用 Google Cloud API 密钥： 设置 GOOGLE_API_KEY。
   • 使用 ADC： 确保 ADC 已配置（例如，通过具有 GOOGLE_APPLICATION_CREDENTIALS 的服务帐户），并设置 GOOGLE_CLOUD_PROJECT 和 GOOGLE_CLOUD_LOCATION。

如果在非交互式模式下找不到合适的环境变量，CLI 将以错误退出。

下一步？

您的身份验证方法会影响您的配额、定价、服务条款和隐私声明。请查阅以下页面以了解更多信息：

• Gemini CLI：配额和定价。
• Gemini CLI：服务条款和隐私声明。