Gemini CLI Docs

简体中文

English

简体中文

English

主题

身份验证设置 ​

Gemini CLI 需要您通过 Google 的 AI 服务进行身份验证。在初始启动时，您需要配置以下身份验证方法中的一种：

  1. 使用 Google 登录 (Gemini Code Assist)：

    • 使用此选项通过您的 Google 账户登录。

    • 在初始启动期间，Gemini CLI 将引导您到网页进行身份验证。一旦通过身份验证，您的凭据将在本地缓存，因此在后续运行中可以跳过网页登录。

    • 请注意，网页登录必须在能够与运行 Gemini CLI 的机器通信的浏览器中完成。（具体来说，浏览器将被重定向到 Gemini CLI 正在监听的 localhost url）。

    • 用户可能需要指定 GOOGLE_CLOUD_PROJECT，如果：

      1. 您有 Google Workspace 账户。Google Workspace 是为企业和组织提供的付费服务，提供一套生产力工具，包括自定义电子邮件域（例如 [email protected]）、增强的安全功能和管理控制。这些账户通常由雇主或学校管理。
      2. 您通过 Google Developer Program 获得了 Gemini Code Assist 许可证（包括合格的 Google Developer Experts）
      3. 您已被分配到当前 Gemini Code Assist 标准或企业订阅的许可证。
      4. 您在免费个人使用的支持地区之外使用该产品。
      5. 您是 18 岁以下的 Google 账户持有者

      您可以使用以下命令在当前 shell 会话中临时设置环境变量：

      bash
      export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
      • 对于重复使用，您可以将环境变量添加到您的 .env 文件或 shell 的配置文件中（如 ~/.bashrc、~/.zshrc 或 ~/.profile）。例如，以下命令将环境变量添加到 ~/.bashrc 文件中：
      bash
      echo 'export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"' >> ~/.bashrc
source ~/.bashrc

  2. Gemini API key：

    • 从 Google AI Studio 获取您的 API key：https://aistudio.google.com/app/apikey
    • 设置 GEMINI_API_KEY 环境变量。在以下方法中，将 YOUR_GEMINI_API_KEY 替换为您从 Google AI Studio 获得的 API key：

      • 您可以使用以下命令在当前 shell 会话中临时设置环境变量：

        bash
        export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"

      • 对于重复使用，您可以将环境变量添加到您的 .env 文件中。

      • 或者，您可以从 shell 的配置文件（如 ~/.bashrc、~/.zshrc 或 ~/.profile）导出 API key。例如，以下命令将环境变量添加到 ~/.bashrc 文件中：

        bash
        echo 'export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"' >> ~/.bashrc
source ~/.bashrc

        ⚠️ 请注意，当您在 shell 配置文件中导出 API key 时，从 shell 执行的任何其他进程都可以读取它。

  3. Vertex AI：

    • API Key：

      • 获取您的 Google Cloud API key：获取 API Key
      • 设置 GOOGLE_API_KEY 环境变量。在以下方法中，将 YOUR_GOOGLE_API_KEY 替换为您的 Vertex AI API key：

        • 您可以使用以下命令在当前 shell 会话中临时设置环境变量：

          bash
          export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"

        • 对于重复使用，您可以将环境变量添加到您的 .env 文件或 shell 的配置文件中（如 ~/.bashrc、~/.zshrc 或 ~/.profile）。例如，以下命令将环境变量添加到 ~/.bashrc 文件中：

          bash
          echo 'export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"' >> ~/.bashrc
source ~/.bashrc

          ⚠️ 请注意，当您在 shell 配置文件中导出 API key 时，从 shell 执行的任何其他进程都可以读取它。

          注意： 如果您遇到类似 "API keys are not supported by this API - Expected OAuth2 access token or other authentication credentials that assert a principal" 的错误，很可能是您的组织限制了 service account API key 的创建。在这种情况下，请尝试下面描述的 service account JSON key 方法。

    • Application Default Credentials (ADC)：

      注意： 如果您之前设置了 GOOGLE_API_KEY 或 GEMINI_API_KEY 环境变量，您必须取消设置它们才能使用 Application Default Credentials。

      bash
      unset GOOGLE_API_KEY GEMINI_API_KEY

      • 使用 gcloud（用于本地开发）：

      • 使用 Service Account（用于应用程序或当 service account API key 受限时）：

        • 如果由于组织策略而无法创建 API key，或者如果您在非交互式环境中运行，您可以使用 service account key 进行身份验证。
        • 创建 service account 和 key，并下载 JSON key 文件。service account 需要被分配"Vertex AI User"角色。
        • 将 GOOGLE_APPLICATION_CREDENTIALS 环境变量设置为 JSON 文件的绝对路径。
          • 您可以在当前 shell 会话中临时设置环境变量：
            bash
            export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/keyfile.json"
          • 对于重复使用，您可以将命令添加到 shell 的配置文件中（例如 ~/.bashrc）。
            bash
            echo 'export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/keyfile.json"' >> ~/.bashrc
source ~/.bashrc
            ⚠️ 请注意，当您在 shell 配置文件中导出 service account 凭据时，从 shell 执行的任何其他进程都可以读取它。

      • ADC 所需的环境变量：

        • 当使用 ADC（无论是使用 gcloud 还是 service account）时，您还必须设置 GOOGLE_CLOUD_PROJECT 和 GOOGLE_CLOUD_LOCATION 环境变量。在以下方法中，将 YOUR_PROJECT_ID 和 YOUR_PROJECT_LOCATION 替换为您项目的相关值：
          • 您可以使用以下命令在当前 shell 会话中临时设置这些环境变量：
            bash
            export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION" # 例如，us-central1
          • 对于重复使用，您可以将环境变量添加到您的 .env 文件或 shell 的配置文件中（如 ~/.bashrc、~/.zshrc 或 ~/.profile）。例如，以下命令将环境变量添加到 ~/.bashrc 文件中：
            bash
            echo 'export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"' >> ~/.bashrc
echo 'export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION"' >> ~/.bashrc
source ~/.bashrc

  4. Cloud Shell：

    • 此选项仅在 Google Cloud Shell 环境中运行时可用。

    • 它自动使用 Cloud Shell 环境中已登录用户的凭据。

    • 这是在 Cloud Shell 中运行且未配置其他方法时的默认身份验证方法。

      :warning: 请注意，当您在 shell 配置文件中导出 API key 时，从 shell 执行的任何其他进程都可以读取它。

使用 .env 文件持久化环境变量 ​

您可以在项目目录或主目录中创建一个 .gemini/.env 文件。创建普通的 .env 文件也可以，但建议使用 .gemini/.env 来保持 Gemini 变量与其他工具隔离。

重要： 某些环境变量（如 DEBUG 和 DEBUG_MODE）会自动从项目 .env 文件中排除，以防止干扰 gemini-cli 行为。对于 gemini-cli 特定变量，请使用 .gemini/.env 文件。

Gemini CLI 自动从找到的第一个 .env 文件加载环境变量，使用以下搜索顺序：

  1. 从当前目录开始向上移动到 /，对于每个目录，它检查：
    1. .gemini/.env
    2. .env
  2. 如果未找到文件，则回退到您的主目录：
    • ~/.gemini/.env
    • ~/.env

重要： 搜索在遇到第一个文件时停止——变量不会在多个文件之间合并。

示例 ​

项目特定覆盖（当您在项目内部时优先）：

bash
mkdir -p .gemini
echo 'GOOGLE_CLOUD_PROJECT="your-project-id"' >> .gemini/.env

用户全局设置（在每个目录中都可用）：

bash
mkdir -p ~/.gemini
cat >> ~/.gemini/.env <<'EOF'
GOOGLE_CLOUD_PROJECT="your-project-id"
GEMINI_API_KEY="your-gemini-api-key"
EOF

非交互模式 / 无头环境 ​

在非交互式环境中运行 Gemini CLI 时，您无法使用交互式登录流程。 相反，您必须使用环境变量配置身份验证。

CLI 将自动检测是否在非交互式终端中运行，如果可用，将使用以下身份验证方法之一：

  1. Gemini API Key：

    • 设置 GEMINI_API_KEY 环境变量。
    • CLI 将使用此 key 通过 Gemini API 进行身份验证。

  2. Vertex AI：

    • 设置 GOOGLE_GENAI_USE_VERTEXAI=true 环境变量。
    • 使用 API Key： 设置 GOOGLE_API_KEY 环境变量。
    • 使用 Application Default Credentials (ADC)：
      • 在您的环境中运行 gcloud auth application-default login 来配置 ADC。
      • 确保设置了 GOOGLE_CLOUD_PROJECT 和 GOOGLE_CLOUD_LOCATION 环境变量。

如果在非交互式会话中未设置这些环境变量，CLI 将退出并显示错误。

基于 MIT 许可证发布

版权所有 © 2025-至今