結論先說
- 先對號入座選對工具:官方已於 2026-06-18 停止個人谷歌帳號(含免費檔、Google AI Pro 與 Ultra)在舊版 Gemini CLI 上的請求服務,個人帳號請直接改用新版 Antigravity
agy命令行;只有 付費 Gemini API Key、Vertex AI 雲項目及企業許可 仍走本文的環境變量接入路線。 - 環境變量優先級高於交互式緩存:支持寫進系統 Shell 配置或獨立存放在
~/.gemini/.env文件中;一旦終端殘留了舊的GOOGLE_API_KEY或GOOGLE_GENAI_USE_VERTEXAI,就會靜默搶佔認證通道導致報錯。 - 免費層 API Key 在終端跑智能體極易秒觸發
429:按官方配額表,免費層 API Key 每日請求上限低且僅限輕量 Flash 模型;跑多輪讀文件循環須綁定付費結算層級(Paid Tier)。 - Vertex AI 報
limit: 0多半是雲項目沒開 API 或沒綁帳單:先在 GCP 控制檯啟用 Vertex AI API 並核驗gcloud預設憑據。 - 谷歌帳號與多工具訂閱直達入口:體驗 Jules 異步提 PR、Stitch 生 UI 與 AI Studio 需登入合規個人谷歌帳號,缺號可前往本站 谷歌帳號購買頁 選購 2FA 谷歌電郵成品號;跨平台開發與設計訂閱對比見 AI 會員充值中心。

圖:本站根據 Gemini CLI 官方認證文檔 整理的示意圖
本文根據 Gemini CLI 官方認證文檔(geminicli.com/docs/get-started/authentication)及 Google 開發者網誌整理,資料核對於 2026-11-18。配圖為本站整理的示意圖,不是終端截圖。本站(bigolab.com)不是 Google 官方網站。
適用於誰
- 在無圖形介面的 CI/CD 流水線、Docker 容器或遠程伺服器上用 付費 Gemini API Key / Vertex AI 跑
@google/gemini-cli的工程師; - 換了新 API Key 卻依然報
401鑑權失敗,或莫名其妙撞上429 RESOURCE_EXHAUSTED(甚至提示limit: 0)的人; - 分不清當前手頭的任務該繼續配 Gemini CLI 環境變量,還是直接改用新版
agy命令行的人。
一、兩類合規環境變量配法(API Key 與 Vertex AI)
如果你已確認自己的場景屬於按 Token 結算的 API 調用或企業雲項目(基礎安裝與停服背景見 Gemini CLI 停服調整與用法說明),官方推薦以下兩種免瀏覽器彈窗的持久化配法:
路線 A:使用 Google AI Studio 的 GEMINI_API_KEY
適合獨立腳本、GitHub Actions 自動化步驟或按量付費開發者(還沒申請密鑰可先看 Gemini API Key 獲取教學)。你可以把密鑰直接寫入 ~/.gemini/.env,這樣不會污染全局其他工具的環境變量:
bash
mkdir -p ~/.gemini
cat << 'EOF' >> ~/.gemini/.env
GEMINI_API_KEY="在這裏填入你的AI_Studio密鑰"
EOF
首次啟動 gemini 如彈出認證方式詢問,選擇 Use Gemini API Key 即可。
路線 B:通過 Google Cloud Vertex AI 企業項目接入
適合要求數據駐留合規、統一走公司 GCP 帳單結算的團隊。先在終端執行一次應用預設憑據登入:
bash
gcloud auth application-default login
隨後在 ~/.gemini/.env(或 .zshrc / .bashrc)裏同時配齊三個必填變量:
bash
export GOOGLE_GENAI_USE_VERTEXAI=true
export GOOGLE_CLOUD_PROJECT="你的GCP項目ID"
export GOOGLE_CLOUD_LOCATION="us-central1"
如果你既需要準備登入 AI Studio 領密鑰的個人谷歌帳號,又想在本地終端備一套按月包乾的成熟編碼工具兜底,可分別查看本站 谷歌帳號購買說明 與 Claude Code 訂閱服務。
二、常見 429 限流與環境變量串號排查

圖:本站根據 Gemini CLI 官方文檔 與 API 速率說明整理的排錯示意圖
在終端跑代碼智能體時,一次提問背後往往連發十幾次模型請求。遇到報錯時按下面四步逐一拆解:
- 排查環境變量「幽靈覆蓋」:很多開發者以前裝別的 SDK 時在
.zshrc裏留過舊的GOOGLE_API_KEY,或者測完雲項目忘了關GOOGLE_GENAI_USE_VERTEXAI=true。在終端跑下面這條檢查並清空衝突項後再試:
bash
env | grep -E "GEMINI|GOOGLE"
unset GOOGLE_API_KEY GEMINI_API_KEY GOOGLE_GENAI_USE_VERTEXAI
- 區分每分鐘速率(RPM/TPM)與每日配額(RPD)耗盡:打開會話輸入
/stats model可以直觀看到當前已消耗的 Token 量。如果是短時間內掃大倉庫撞上每分鐘輸入 Token 上限(TPM),等一分鐘並用-m參數指定輕量 Flash 模型就能恢復;如果是免費層每日總額度見底,同一項目下換新 Key 也沒用(官方限額按項目而非單把密鑰計算,詳見 Gemini API 免費層限額說明 與 Gemini API 429 錯誤完整排查表)。 - 排查
limit: 0報錯:當報錯詳情裏出現配額上限為0時,說明當前請求落到了一個未在所屬地區開放免費層、或未綁定有效結算帳戶(Billing Account)的空雲項目上。登入 Google AI Studio 的 Dashboard 檢查密鑰所屬項目的計費狀態即可定位。
常見問題
問:寫在當前項目根目錄 .env 裏的 GEMINI_API_KEY 會被誤讀嗎?
答:如果你的業務代碼倉庫本身也有 .env 且裏面恰好有同名變量,在倉庫根目錄直接敲 gemini 時可能發生變量覆蓋。建議專門給 CLI 用的憑據統一放進用戶主目錄 ~/.gemini/.env,並與業務代碼裏的變量名做好區分。
問:無介面模式(Headless)在腳本里怎麼跑完一句話就自動退出?
答:使用 -p 參數即可非交互運行並直接把結果打到標準輸出,例如 gemini -p "檢查當前 git diff 有沒有明顯空指針隱患",非常適合塞進 Git 鉤子或流水線步驟。
問:想用谷歌最新的編碼優化模型寫大項目,繼續充 API 跑舊版 CLI 划算嗎?
答:官方文檔已提示舊版 Gemini CLI 不再針對新一代旗艦編碼模型做專門優化,日常交互式重度開發直接切到新版 Antigravity IDE 或 agy 體驗更完整。
問:註冊谷歌帳號卡在手機號驗證,或者國內沒有外幣卡怎麼配齊 AI 開發工具?
答:本站提供支持支付寶、微信支付與 AlipayHK 自動發卡的 谷歌電郵成品號(登入加固步驟見 谷歌帳號說明頁),同時支持自助獲取兌換碼開通 ChatGPT Plus 與 Claude Code 訂閱,支持開具增值稅發票。
0 條評論
還沒有評論,來搶沙發~