身份验证设置

配置与 Google AI 服务的身份验证方法

首页 > CLI 指南 > 身份验证设置

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

1. Google 登录（Gemini Code Assist）

推荐方法

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

  • 在初始启动期间，Gemini CLI 将引导您到网页进行身份验证。一旦身份验证完成，您的凭据将在本地缓存，因此可以跳过后续运行的网页登录。
  • 注意，网页登录必须在能够与运行 Gemini CLI 的机器通信的浏览器中完成。（具体来说，浏览器将被重定向到 Gemini CLI 将监听的 localhost URL）。

特殊情况：需要指定 GOOGLE_CLOUD_PROJECT

如果您属于以下类别之一，可能需要指定 GOOGLE_CLOUD_PROJECT：

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

如果您属于这些类别，您必须首先配置要使用的 Google Cloud 项目 ID，启用 Gemini for Cloud API 并配置访问权限。

临时设置环境变量

export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"

永久设置（添加到 shell 配置文件）

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

2. Gemini API 密钥

简单快速

从 Google AI Studio 获取 API 密钥是最直接的方法。

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

临时设置

export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"

永久设置

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

3. Vertex AI

企业级选项

适用于需要企业级安全和控制的组织。

非 Express 模式

  1. 确保您有 Google Cloud 项目并已启用 Vertex AI API。
  2. 设置应用程序默认凭据 (ADC)： 
    gcloud auth application-default login
    更多信息，请参阅为 Google Cloud 设置应用程序默认凭据。
  3. 设置环境变量（将 YOUR_PROJECT_ID 和 YOUR_PROJECT_LOCATION 替换为您项目的相关值）：

临时设置

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

永久设置

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

Express 模式

设置 GOOGLE_API_KEY 环境变量（将 YOUR_GOOGLE_API_KEY 替换为 express 模式提供的 Vertex AI API 密钥）：

临时设置

export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"
export GOOGLE_GENAI_USE_VERTEXAI=true

永久设置

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

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

推荐的管理方式

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

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

🔑 API 密钥管理

最佳实践：

  • 永远不要将 API 密钥提交到版本控制
  • 使用 .env 文件进行本地开发
  • 在生产环境中使用环境变量
  • 定期轮换 API 密钥

🛡️ 安全考虑

安全提示：

  • 确保 .env 文件在 .gitignore 中
  • 使用适当的文件权限（600）
  • 避免在日志中记录凭据
  • 使用最小权限原则

相关文档：

↑ 顶部