身份验证设置

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

1. 使用 Google 登录（Gemini Code Assist）：

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

   • 在初次启动时，Gemini CLI 会引导您到网页进行身份验证。验证完成后，您的凭据将在本地缓存，这样在后续运行时可以跳过网页登录。

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

   • 在以下情况下，用户可能需要指定 GOOGLE_CLOUD_PROJECT：

     1. 您拥有 Google Workspace 账户。Google Workspace 是为企业和组织提供的付费服务，提供一套生产力工具，包括自定义电子邮件域名（例如 [email protected]）、增强的安全功能和管理控制。这些账户通常由雇主或学校管理。
     2. 您通过 Google 开发者计划 获得了 Gemini Code Assist 许可证（包括合格的 Google 开发者专家）
     3. 您已被分配了当前 Gemini Code Assist 标准版或企业版订阅的许可证。
     4. 您在免费个人使用的支持区域之外使用该产品。
     5. 您是 18 岁以下的 Google 账户持有者
     • 如果您属于这些类别之一，您必须首先配置要使用的 Google Cloud 项目 ID，启用 Gemini for Cloud API 并配置访问权限。

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

     export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"

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

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

2. Gemini API 密钥：

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

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

       export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"

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

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

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

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

3. Vertex AI：

   • 获取您的 Google Cloud API 密钥：获取 API 密钥
     • 设置 GOOGLE_API_KEY 环境变量。在以下方法中，将 YOUR_GOOGLE_API_KEY 替换为您的 Vertex AI API 密钥：
       • 您可以使用以下命令在当前 shell 会话中临时设置这些环境变量：

         export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"

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

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

   • 要使用应用程序默认凭据 (ADC)，请使用以下命令：
     • 确保您有 Google Cloud 项目并已启用 Vertex AI API。

       gcloud auth application-default login

       有关更多信息，请参阅为 Google Cloud 设置应用程序默认凭据。
     • 设置 GOOGLE_CLOUD_PROJECT 和 GOOGLE_CLOUD_LOCATION 环境变量。在以下方法中，将 YOUR_PROJECT_ID 和 YOUR_PROJECT_LOCATION 替换为您项目的相关值：

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

         export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
         export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION" # 例如：us-central1

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

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

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

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

4. Cloud Shell：

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

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

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

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

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

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

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

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

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

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

示例

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

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

用户范围的设置（在每个目录中都可用）：

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 密钥：

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

2. Vertex AI：

   • 设置 GOOGLE_GENAI_USE_VERTEXAI=true 环境变量。
   • 使用 API 密钥： 设置 GOOGLE_API_KEY 环境变量。
   • 使用应用程序默认凭据 (ADC)：
     • 在您的环境中运行 gcloud auth application-default login 来配置 ADC。
     • 确保设置了 GOOGLE_CLOUD_PROJECT 和 GOOGLE_CLOUD_LOCATION 环境变量。

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