認證方式

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