---
title: "认证方式"
description: "Gemini CLI 认证方式：Google OAuth、Gemini API Key、Vertex AI、Workspace/组织账号、Google Cloud Project 和 headless 场景怎么选。"
verifiedAt: "2026-05-09"
---

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

> [!NOTE]
> **先给结论**：个人本机交互优先 `Login with Google`；脚本、headless、CI 优先 API key 或 Vertex AI；企业、Workspace、Code Assist subscription 和受控区域用户要先确认 Google Cloud Project、API 启用和 IAM。

## 1. 认证选择图

```mermaid
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. 认证方式选择

| 场景 | 推荐方式 | 是否通常需要 Google Cloud Project |
| --- | --- | --- |
| 个人 Google 账号 | Sign in with Google | 通常不需要 |
| 公司、学校、Workspace 账号 | Sign in with Google | 需要 |
| Gemini API Key 用户 | Gemini API Key | 不需要 |
| Vertex AI 用户 | Vertex AI | 需要 |
| Headless / CI | API Key 或 Vertex AI | API Key 不需要，Vertex AI 需要 |

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

## 3. Google 账号登录

```bash
gemini
```

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

适合：

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

> [!IMPORTANT]
> **OAuth 需要浏览器回跳**：官方认证文档说明，本机登录会把浏览器重定向到 CLI 监听的 `localhost` URL。远程服务器、SSH、容器和无浏览器环境，不要默认选这条路。

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

> [!IMPORTANT]
> **个人 Google 账号（包括免费层和 Google AI Pro / Ultra）通常不需要 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 官方页](https://github.com/google-gemini/gemini-cli/blob/main/docs/get-started/authentication.mdx) 处理。

设置 Project 需要做四件事：① 在 [Google Cloud Console](https://console.cloud.google.com/) 找到或新建 Project（参考 [创建管理项目文档](https://cloud.google.com/resource-manager/docs/creating-managing-projects)）；② 启用 Gemini for Cloud API；③ 配置 IAM 权限；④ 设置环境变量。常见环境变量：

```bash
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](https://aistudio.google.com/app/apikey) 获取 API key：

```bash
# 把 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 的环境。

> [!IMPORTANT]
> **Free 层 API key 只能用 Flash 模型**：每天 250 次请求，且模型固定 Flash。需要 Pro 或更高模型，要切到付费层（Pay-as-you-go）。详见 [Quota and pricing](https://github.com/google-gemini/gemini-cli/blob/main/docs/resources/quota-and-pricing.md)。

> [!WARNING]
> **API key 是密码**：不要写进教程、仓库、日志、截图、共享配置或 shell history。团队项目只写变量名，真实值进入 secret store、CI secrets 或本机 `.gemini/.env`。

## 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 通常需要设置：

```bash
export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION"
```

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

```bash
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`，并把真实文件加入忽略列表。

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

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

## 9. 选择建议

| 你是谁 | 建议 |
| --- | --- |
| 中文个人开发者 | 先用 Google OAuth，把第一轮任务跑通 |
| 课程学员或新手 | 不要一开始搞 Vertex AI，先降低变量 |
| 企业成员 | 先确认组织账号、许可、Cloud Project 和安全策略 |
| 自动化脚本 | API Key 或 Vertex AI，不依赖浏览器登录 |
| 生产/企业级 | Vertex AI + IAM + policy + telemetry 统一治理 |

## 10. 接下来去哪

<Cards>
  <Card title="Quickstart" description="认证完成后，跑第一条可控任务闭环，而不是直接交给它改项目。" href="/docs/gemini-cli/official/00-getting-started/03-quickstart" />
  <Card title="Quota and pricing" description="不同认证方式会影响 quota、计费和隐私边界，具体数字回官方页核验。" href="/docs/gemini-cli/official/00-getting-started/06-quota-and-pricing" />
  <Card title="Enterprise config" description="企业场景继续看集中配置、policy engine、sandbox、telemetry 和隐私边界。" href="/docs/gemini-cli/official/06-security-enterprise/62-enterprise-config" />
</Cards>

## 官方来源

- [Google Developers Gemini CLI](https://developers.google.com/gemini-code-assist/docs/gemini-cli?hl=zh-cn)
- [Gemini CLI Authentication Setup](https://google-gemini.github.io/gemini-cli/docs/get-started/authentication.html)
- [Gemini CLI Configuration](https://google-gemini.github.io/gemini-cli/docs/get-started/configuration.html)
