Gemini CLI 身份验证设置

在使用 Gemini CLI 前，需要通过 Google 的服务完成身份验证。请选择以下 任一 方式完成配置：

  • 交互式模式
    • 推荐：使用 Google 登录
    • 使用 Gemini API key
    • 使用 Vertex AI
  • 无界面（非交互）模式
  • Google Cloud Shell

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

如果在 Google Cloud Shell 环境中运行，通常会自动继承当前会话的身份，无需额外配置。

在交互式模式下认证

通过命令行运行 CLI 时，会看到以下选项：

> 1. Login with Google
> 2. Use Gemini API key
> 3. Vertex AI

下文分别说明不同选项的具体步骤。

推荐：使用 Google 登录

若在本地机器使用 Gemini CLI，最简单的方式是使用 Google 账号登录。

重要： 若你订阅了 Google AI Pro 或 Google AI Ultra，请使用与订阅关联的 Google 账号登录。

  1. 选择 Login with Google，CLI 会在浏览器中打开登录页面。
  2. 按照提示完成登录，凭据会缓存在本地以便后续使用。

说明： 需要确保能够在运行 CLI 的机器上打开浏览器，并完成返回 localhost 的回调。

（可选）设置 Google Cloud Project

登录时可能会提示选择 GOOGLE_CLOUD_PROJECT，以下情况需要设置：

  • 使用 Google Workspace 账号；
  • 使用 Google Developer Program 提供的 Gemini Code Assist 许可证；
  • 使用 Gemini Code Assist 订阅；
  • 在免费个人使用的支持地区之外使用；
  • Google 账号年龄未满 18 岁。

如需设置：

  1. 拥有 Google Cloud 项目 ID；
  2. 启用 Gemini for Cloud API；
  3. 授予所需 IAM 权限。

通过环境变量配置项目：

# 标准变量，优先读取
export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"

# 备用变量
export GOOGLE_CLOUD_PROJECT_ID="YOUR_PROJECT_ID"

如何持久化环境变量，请参阅持久化设置。

使用 Gemini API key

如果不想使用 Google 登录，可在 Google AI Studio 获取 API key。

  1. 前往 Google AI Studio 创建 API key。

  2. 设置环境变量：

    export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"

持久化方法见持久化环境变量。

警告： API key 属于敏感凭据，请妥善保管，避免泄露导致账号被滥用。

使用 Vertex AI

若计划使用 Google Cloud Vertex AI，可选择以下认证方式：

  • Application Default Credentials（ADC）+ gcloud
  • 服务账号 JSON key
  • Google Cloud API key

首先：设置必要环境变量

无论采用哪种方式，通常需要设置：

  • GOOGLE_CLOUD_PROJECT（或 GOOGLE_CLOUD_PROJECT_ID）
  • GOOGLE_CLOUD_LOCATION

示例：

export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
export GOOGLE_CLOUD_LOCATION="us-central1"

A. Vertex AI + ADC（配合 gcloud）

  1. 确认项目已启用 Vertex AI。

  2. 通过 gcloud 登录：

    gcloud auth application-default login

    详见设置 Application Default Credentials。

  3. 确保已设置 GOOGLE_CLOUD_PROJECT（或 GOOGLE_CLOUD_PROJECT_ID）与 GOOGLE_CLOUD_LOCATION。

B. Vertex AI + 服务账号 JSON key

适用于非交互环境、CI/CD，或企业禁止使用用户级 ADC/API key 的场景。

说明： 若之前设置过 GOOGLE_API_KEY 或 GEMINI_API_KEY，请先取消：

unset GOOGLE_API_KEY GEMINI_API_KEY

  1. 创建服务账号及密钥，赋予 “Vertex AI User” 角色。

  2. 设置 GOOGLE_APPLICATION_CREDENTIALS 为 JSON 文件的绝对路径：

    export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/keyfile.json"

  3. 设置 GOOGLE_CLOUD_PROJECT（或 GOOGLE_CLOUD_PROJECT_ID）与 GOOGLE_CLOUD_LOCATION。

警告： 服务账号密钥可访问你的资源，请妥善保护。

C. Vertex AI + Google Cloud API key

  1. 获取 API key：https://cloud.google.com/vertex-ai/generative-ai/docs/start/api-keys?usertype=newuser

  2. 设置环境变量：

    export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"

若遇到 “API keys are not supported by this API” 等错误，说明组织限制了 API key，可改用服务账号或 ADC。

同样，可参考持久化环境变量。

持久化环境变量

为避免每次启动 shell 都重新设置，可：

  1. 写入 shell 配置文件：在 ~/.bashrc、~/.zshrc、~/.profile 等启动文件中追加 export，并重新加载。

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

    警告： 将 API key 或服务账号路径写入 shell 配置文件意味着所有从该 shell 启动的进程都能读取。

  2. 使用 .env 文件：在项目或用户目录创建 .gemini/.env（推荐）。CLI 会从当前目录向上查找第一个 .env 文件，并加载其中的变量。

    mkdir -p ~/.gemini
cat >> ~/.gemini/.env <<'ENV'
GOOGLE_CLOUD_PROJECT="your-project-id"
# 可以继续添加 GEMINI_API_KEY 等
ENV

    注意：只会加载首次找到的 .env 文件，不会合并。

无界面 / 非交互环境

若在非交互模式下运行，CLI 会复用已有的认证缓存。如果尚未登录，需要通过环境变量显式配置：

  1. Gemini API key： 设置 GEMINI_API_KEY。
  2. Vertex AI：
    • 设置 GOOGLE_GENAI_USE_VERTEXAI=true。
    • 若使用 API key：设置 GOOGLE_API_KEY。
    • 若使用 ADC/服务账号：配置 ADC 或 GOOGLE_APPLICATION_CREDENTIALS，并设置 GOOGLE_CLOUD_PROJECT / GOOGLE_CLOUD_PROJECT_ID 与 GOOGLE_CLOUD_LOCATION。

若未检测到有效凭据，CLI 将报错退出。

下一步

不同认证方式会影响配额、定价、服务条款与隐私声明，请继续阅读：