认证方式

Gemini CLI 的认证方式会同时影响可用模型、quota、计费、隐私条款、企业管控和 headless 能不能跑。不要把它当成“随便填一个 key”的步骤；先判断你是在本机交互、Cloud Shell、CI，还是企业 Google Cloud 环境里运行。

1. 认证选择图

flowchart TD
    Start["启动 gemini"] --> CloudShell{"在 Google Cloud Shell?"}
    CloudShell -->|是| Auto["通常使用 Cloud Shell 凭据"]
    CloudShell -->|否| Interactive{"本机交互式使用?"}
    Interactive -->|是| OAuth["Login with Google"]
    Interactive -->|否| Headless{"headless / CI / 自动化?"}
    Headless -->|是| KeyOrVertex["GEMINI_API_KEY 或 Vertex AI"]
    Headless -->|否| Enterprise{"企业 Google Cloud 管控?"}
    Enterprise -->|是| Vertex["Vertex AI + Project + Location + IAM"]
    Enterprise -->|否| OAuth

    style OAuth fill:#dcfce7,stroke:#22c55e
    style KeyOrVertex fill:#fef3c7,stroke:#f59e0b
    style Vertex fill:#fee2e2,stroke:#ef4444

2. 认证方式选择

Cloud Shell 是特殊入口。官方认证页说明，如果 Gemini CLI 运行在 Google Cloud Shell 环境里，认证通常会自动使用 Cloud Shell 凭据；但你仍然要确认当前 project 是否是你想使用的 project。

3. Google 账号登录

gemini

启动后选择 Login with Google，浏览器会打开登录流程。认证完成后，凭据会缓存在本地，后续会话可复用。

适合：

• 个人开发者。
• Google AI Pro / Ultra 用户。
• 已有 Gemini Code Assist 许可的用户。
• 主要在本机交互式使用 Gemini CLI 的人。

4. 什么时候要设置 Google Cloud Project

官方认证页当前列出 3 类必须设置 Google Cloud Project 的情况（Vertex AI 认证另外单独走 Vertex 路径，不在这一节）：

• 公司、学校或 Google Workspace 账号。
• 使用 Google Developer Program 的 Gemini Code Assist license。
• 使用 Gemini Code Assist subscription license。

早期文档曾把"地区限制 / 未满 18 岁"也列入，但官方当前认证页已精简。如果你看到 CLI 报错让设置 project，按报错提示和当前 authentication 官方页 处理。

设置 Project 需要做四件事：① 在 Google Cloud Console 找到或新建 Project（参考 创建管理项目文档）；② 启用 Gemini for Cloud API；③ 配置 IAM 权限；④ 设置环境变量。常见环境变量：

export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION"

设置 project 不只是填环境变量。企业或组织账号还要确认 Gemini for Cloud API、必要 IAM 权限、账单和组织策略。缺一个环节，CLI 可能能启动但调用失败。

5. Gemini API Key

如果不想用 Google 账号登录，可以从 Google AI Studio 获取 API key：

# 把 YOUR_GEMINI_API_KEY 替换为你从 AI Studio 拿到的 key
export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
gemini

启动后在认证菜单里选 Use Gemini API key。

适合：

• 需要 headless 或脚本化运行。
• 想明确走 Gemini API key 计费和限制。
• 不方便使用浏览器 OAuth 的环境。

6. Vertex AI

Vertex AI 适合企业、生产工作负载和 Google Cloud 管控场景。官方文档列了三类方式：

• Application Default Credentials：gcloud auth application-default login
• Service account JSON key
• Google Cloud API key

Vertex AI 通常需要设置：

export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION"

如果使用 ADC 且之前设置过 GOOGLE_API_KEY 或 GEMINI_API_KEY，官方文档建议先 unset：

unset GOOGLE_API_KEY GEMINI_API_KEY

service account JSON key 能用于非交互环境，但它的风险也更高。文件路径要用绝对路径，权限要最小化，JSON key 不能进仓库。

7. headless 和 CI 怎么处理

Headless 模式会复用已有凭据；如果没有缓存的交互式登录凭据，就必须通过环境变量提供认证。按官方认证页，常见路径是：

• Gemini API Key：设置 GEMINI_API_KEY。
• Vertex AI + API key：设置 GOOGLE_GENAI_USE_VERTEXAI=true 和 GOOGLE_API_KEY。
• Vertex AI + ADC / service account：设置 ADC、GOOGLE_CLOUD_PROJECT 和 GOOGLE_CLOUD_LOCATION。

CI 里不要依赖“某台机器曾经登录过”。可复现的做法是把认证方式、project、location、secret 名称和权限边界写进 workflow 文档。

8. .env 和持久化边界

Gemini CLI 官方配置说明会加载环境变量；认证页建议可以用 shell 配置或 .env 持久化。团队教程里更推荐显式放到 .gemini/.env，并把真实文件加入忽略列表。

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

变量加载不是“越多越好”。如果同一环境里同时存在 GEMINI_API_KEY、GOOGLE_API_KEY、ADC 和 Vertex AI 开关，排障会变复杂。每个项目只保留当前需要的认证路径。

9. 选择建议

10. 接下来去哪

官方来源

• Google Developers Gemini CLI
• Gemini CLI Authentication Setup
• Gemini CLI Configuration