---
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="/zh-Hant/docs/gemini-cli/official/00-getting-started/03-quickstart" />
  <Card title="Quota and pricing" description="不同認證方式會影響 quota、計費和隱私邊界，具體數字回官方頁核驗。" href="/zh-Hant/docs/gemini-cli/official/00-getting-started/06-quota-and-pricing" />
  <Card title="Enterprise config" description="企業場景繼續看集中配置、policy engine、sandbox、telemetry 和隱私邊界。" href="/zh-Hant/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)
