Skip to content

身份验证设置

¥Authentication Setup

Gemini CLI 要求您使用 Google 的 AI 服务进行身份验证。首次启动时，您需要配置一以下身份验证方法：

¥The Gemini CLI requires you to authenticate with Google's AI services. On initial startup you'll need to configure one of the following authentication methods:

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

    ¥Login with Google (Gemini Code Assist):

    • 使用此选项可以通过您的 Google 帐户登录。

      ¥Use this option to log in with your Google account.

    • 初始启动时，Gemini CLI 会将您引导至一个网页进行身份验证。身份验证完成后，您的凭据将被缓存在本地，以便后续运行时无需再进行 Web 登录。

      ¥During initial startup, Gemini CLI will direct you to a webpage for authentication. Once authenticated, your credentials will be cached locally so the web login can be skipped on subsequent runs.

    • 请注意，Web 登录必须在能够与运行 Gemini CLI 的计算机通信的浏览器中进行。（具体来说，浏览器将被重定向到 Gemini CLI 将监听的本地主机 URL）。

      ¥Note that the web login must be done in a browser that can communicate with the machine Gemini CLI is being run from. (Specifically, the browser will be redirected to a localhost url that Gemini CLI will be listening on).

    • 如果出现以下情况，用户可能必须指定 GOOGLE_CLOUD_PROJECT：

      ¥Users may have to specify a GOOGLE_CLOUD_PROJECT if:

    • 您拥有一个 Google Workspace 帐号。Google Workspace 是一项面向企业和组织的付费服务，提供一系列生产力工具，包括自定义电子邮件域名（例如，your-name@your-company.com）、增强的安全功能和管理控制。这些帐号通常由雇主或学校管理。

      ¥You have a Google Workspace account. Google Workspace is a paid service for businesses and organizations that provides a suite of productivity tools, including a custom email domain (e.g. your-name@your-company.com), enhanced security features, and administrative controls. These accounts are often managed by an employer or school.

    • 您已通过Google 开发者计划（包括合格的 Google 开发者专家）

      ¥You have received a Gemini Code Assist license through the Google Developer Program (including qualified Google Developer Experts)

    • 您已获得当前 Gemini Code Assist 标准或企业订阅的许可证。

      ¥You have been assigned a license to a current Gemini Code Assist standard or enterprise subscription.

    • 您正在使用产品之外支持的区域供个人免费使用。

      ¥You are using the product outside the supported regions for free individual usage.

    • 您是未满 18 周岁的 Google 帐户持有者

      ¥You are a Google account holder under the age of 18

    • 如果您属于以下类别之一，则必须首先配置 Google Cloud 项目 ID 才能使用，启用 Gemini for Cloud API和配置访问权限。

      ¥If you fall into one of these categories, you must first configure a Google Cloud Project ID to use, enable the Gemini for Cloud API and configure access permissions.

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

    ¥You can temporarily set the environment variable in your current shell session using the following command:

    bash export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"- 为了重复使用，您可以将环境变量添加到您的.env 文件或者你的shell的配置文件（比如~/.bashrc，~/.zshrc， 或者~/.profile)。例如，以下命令将环境变量添加到~/.bashrc文件：

    ¥bash export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID" - For repeated use, you can add the environment variable to your .env file or your shell's configuration file (like ~/.bashrc, ~/.zshrc, or ~/.profile). For example, the following command adds the environment variable to a ~/.bashrc file:

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

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

  2. Gemini API 密钥：

    ¥Gemini API key:

    • 从 Google AI Studio 获取您的 API 密钥：https://aistudio.google.com/app/apikey

      ¥Obtain your API key from Google AI Studio: https://aistudio.google.com/app/apikey

    • 设置GEMINI_API_KEY环境变量。在以下方法中，替换YOUR_GEMINI_API_KEY使用您从 Google AI Studio 获取的 API 密钥：

      ¥Set the GEMINI_API_KEY environment variable. In the following methods, replace YOUR_GEMINI_API_KEY with the API key you obtained from Google AI Studio:

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

      ¥You can temporarily set the environment variable in your current shell session using the following command: bash export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"

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

      ¥For repeated use, you can add the environment variable to your .env file.

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

      ¥Alternatively you can export the API key from your shell's configuration file (like ~/.bashrc, ~/.zshrc, or ~/.profile). For example, the following command adds the environment variable to a ~/.bashrc file:

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

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

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

      ¥:warning: Be advised that when you export your API key inside your shell configuration file, any other process executed from the shell can read it.

  3. 顶点人工智能：

    ¥Vertex AI:

    • API密钥：

      ¥API Key:

    • 获取您的 Google Cloud API 密钥：获取 API 密钥

      ¥Obtain your Google Cloud API key: Get an API Key

    • 设置GOOGLE_API_KEY环境变量。在以下方法中，替换YOUR_GOOGLE_API_KEY使用您的 Vertex AI API 密钥：

      ¥Set the GOOGLE_API_KEY environment variable. In the following methods, replace YOUR_GOOGLE_API_KEY with your Vertex AI API key:

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

        ¥You can temporarily set the environment variable in your current shell session using the following command: bash export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"

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

        ¥For repeated use, you can add the environment variable to your .env file or your shell's configuration file (like ~/.bashrc, ~/.zshrc, or ~/.profile). For example, the following command adds the environment variable to a ~/.bashrc file:

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

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

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

      ¥:warning: Be advised that when you export your API key inside your shell configuration file, any other process executed from the shell can read it.

      笔记：如果您遇到类似以下错误"API keys are not supported by this API - Expected OAuth2 access token or other authentication credentials that assert a principal"，则您的组织可能已限制创建服务帐号 API 密钥。在这种情况下，请尝试服务帐户 JSON 密钥方法如下所述。

      ¥Note: If you encounter an error like "API keys are not supported by this API - Expected OAuth2 access token or other authentication credentials that assert a principal", it is likely that your organization has restricted the creation of service account API keys. In this case, please try the service account JSON key method described below.

    • 应用程序默认凭证 (ADC)：

      ¥Application Default Credentials (ADC):

    笔记：如果您之前设置了GOOGLE_API_KEY或者GEMINI_API_KEY环境变量，您必须取消设置它们才能使用应用程序默认凭据。

    ¥Note: If you have previously set the GOOGLE_API_KEY or GEMINI_API_KEY environment variables, you must unset them to use Application Default Credentials.

    bash unset GOOGLE_API_KEY GEMINI_API_KEY-使用gcloud（针对本地开发）：- 确保您拥有 Google Cloud 项目并已启用 Vertex AI API。- 使用您的用户凭据登录：bash gcloud auth application-default login有关详细信息，请参阅为 Google Cloud 设置应用程序默认凭据.-使用服务帐户（对于应用程序或当服务帐户 API 密钥受到限制时）：- 如果您由于以下原因无法创建 API 密钥组织政策或者如果您在非交互式环境中运行，则可以使用服务帐户密钥进行身份验证。-创建服务帐户和密钥，并下载 JSON 密钥文件。服务帐号需要分配“Vertex AI 用户”角色。- 设置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:warning: 请注意，当您在 shell 配置文件中导出服​​务帐户凭据时，从 shell 执行的任何其他进程都可以读取它。

    ¥bash unset GOOGLE_API_KEY GEMINI_API_KEY - Using gcloud (for local development): - Ensure you have a Google Cloud project and have enabled the Vertex AI API. - Log in with your user credentials: bash gcloud auth application-default login For more information, see Set up Application Default Credentials for Google Cloud. - Using a Service Account (for applications or when service account API keys are restricted): - If you are unable to create an API key due to organization policies, or if you are running in a non-interactive environment, you can authenticate using a service account key. - Create a service account and key, and download the JSON key file. The service account will need to be assigned the "Vertex AI User" role. - Set the GOOGLE_APPLICATION_CREDENTIALS environment variable to the absolute path of the JSON file. - You can temporarily set the environment variable in your current shell session: bash export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/keyfile.json" - For repeated use, you can add the command to your shell's configuration file (e.g., ~/.bashrc). bash echo 'export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/keyfile.json"' >> ~/.bashrc source ~/.bashrc :warning: Be advised that when you export service account credentials inside your shell configuration file, any other process executed from the shell can read it.

    • ADC 所需的环境变量：

      ¥Required Environment Variables for ADC:

      • 当使用 ADC 时（无论是gcloud或服务帐户），您还必须设置GOOGLE_CLOUD_PROJECT和GOOGLE_CLOUD_LOCATION环境变量。在以下方法中，替换YOUR_PROJECT_ID和YOUR_PROJECT_LOCATION与您的项目相关的值：

        ¥When using ADC (either with gcloud or a service account), you must also set the GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION environment variables. In the following methods, replace YOUR_PROJECT_ID and YOUR_PROJECT_LOCATION with the relevant values for your project:

      • 您可以使用以下命令在当前 shell 会话中临时设置这些环境变量：bash export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID" export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION" # e.g., us-central1

        ¥You can temporarily set these environment variables in your current shell session using the following commands: bash export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID" export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION" # e.g., 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

        ¥For repeated use, you can add the environment variables to your .env file or your shell's configuration file (like ~/.bashrc, ~/.zshrc, or ~/.profile). For example, the following commands add the environment variables to a ~/.bashrc file: 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 环境中运行时可用。

      ¥This option is only available when running in a Google Cloud Shell environment.

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

      ¥It automatically uses the credentials of the logged-in user in the Cloud Shell environment.

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

      ¥This is the default authentication method when running in Cloud Shell and no other method is configured.

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

      ¥:warning: Be advised that when you export your API key inside your shell configuration file, any other process executed from the shell can read it.

持久化环境变量.env文件

¥Persisting Environment Variables with .env Files

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

¥You can create a .gemini/.env file in your project directory or in your home directory. Creating a plain .env file also works, but .gemini/.env is recommended to keep Gemini variables isolated from other tools.

重要的：一些环境变量（如DEBUG和DEBUG_MODE) 将自动从项目中排除.env文件以防止干扰 gemini-cli 的行为。使用.gemini/.envgemini-cli 特定变量的文件。

¥Important: Some environment variables (like DEBUG and DEBUG_MODE) are automatically excluded from project .env files to prevent interference with gemini-cli behavior. Use .gemini/.env files for gemini-cli specific variables.

Gemini CLI 自动从第一的 .env它使用以下搜索顺序找到的文件：

¥Gemini CLI automatically loads environment variables from the first .env file it finds, using the following search order:

  1. 从当前目录并向上移动/，对于它检查的每个目录：

    ¥Starting in the current directory and moving upward toward /, for each directory it checks:

  2. .gemini/.env

    ¥.gemini/.env

  3. .env

    ¥.env

  4. 如果没有找到文件，它会返回到你的主目录：

    ¥If no file is found, it falls back to your home directory:

  5. ~/.gemini/.env

    ¥~/.gemini/.env

  6. ~/.env

    ¥~/.env

重要的：搜索停止于第一的遇到文件——变量未合并跨多个文件。

¥Important: The search stops at the first file encountered—variables are not merged across multiple files.

示例

¥Examples

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

¥Project-specific overrides (take precedence when you are inside the project):

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

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

¥User-wide settings (available in every directory):

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

非交互模式/无头环境

¥Non-Interactive Mode / Headless Environments

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

¥When running the Gemini CLI in a non-interactive environment, you cannot use the interactive login flow. Instead, you must configure authentication using environment variables.

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

¥The CLI will automatically detect if it is running in a non-interactive terminal and will use one of the following authentication methods if available:

  1. Gemini API密钥：

    ¥Gemini API Key:

    • 设置GEMINI_API_KEY环境变量。

      ¥Set the GEMINI_API_KEY environment variable.

    • CLI 将使用此密钥通过 Gemini API 进行身份验证。

      ¥The CLI will use this key to authenticate with the Gemini API.

  2. 顶点人工智能：

    ¥Vertex AI:

    • 设置GOOGLE_GENAI_USE_VERTEXAI=true环境变量。

      ¥Set the GOOGLE_GENAI_USE_VERTEXAI=true environment variable.

    • 使用 API 密钥：设置GOOGLE_API_KEY环境变量。

      ¥Using an API Key: Set the GOOGLE_API_KEY environment variable.

    • 使用应用程序默认凭证（ADC）：

      ¥Using Application Default Credentials (ADC):

    • 跑步gcloud auth application-default login在您的环境中配置 ADC。

      ¥Run gcloud auth application-default login in your environment to configure ADC.

    • 确保GOOGLE_CLOUD_PROJECT和GOOGLE_CLOUD_LOCATION环境变量已设置。

      ¥Ensure the GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION environment variables are set.

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

¥If none of these environment variables are set in a non-interactive session, the CLI will exit with an error.