現象：裝好 Gemini CLI，終端認證卻一直轉圈

2026 年許多工程師會用 npm install -g @google/gemini-cli 把 Gemini CLI 裝進本機，期待在終端直接跑免費的 Agent 工作流；實際卻常在第一步就卡住：「Login with Google」OAuth 逾時、瀏覽器回呼後 CLI 仍顯示等待、改用 API Key 測試也報連線錯誤，或對話一開始就 ETIMEDOUT。若你正在搜尋 Gemini CLI 逾時、Gemini CLI Clash 或 Clash 分流 Google API，請先建立一個與「只開瀏覽器代理」不同的認知：終端 AI 代理必須讓 Node 子行程的對外 TLS 真的進 Mihomo／Clash 核心，且規則要覆蓋認證與推論各自的主機，而不是只放行 gemini.google.com 網頁。

本站已有 Gemini／AI Studio 網頁分流 與 Gemini Enterprise／GCP 企業分流 專文，主機集合與產品介面都不同。本篇只處理 CLI：npm 安裝鏈路、OAuth 本機回呼、Code Assist 端點與 Generative Language API。 與 Claude Code 終端分流 並讀時，可把「終端怎麼進核心」當共用底座，再把 Google 系主機桶換成下文清單。

合規提醒：Clash／Mihomo 為本機轉送與規則管理工具，不提供公開節點。請在合法合規與 Google 產品條款允許的前提下使用 API／OAuth，勿將訂閱連結或金鑰貼到公開討論區。

安裝階段：先讓 npm install -g 不要假裝成功

許多「Gemini CLI 壞了」其實停在全域套件根本沒裝完：registry.npmjs.org metadata 能過、tarball 卻被寬鬆 GEOIP 帶走錯誤出口，或終端根本沒進核心。請先把 npm registry／tarball 分流專文 的步驟跑通，確認日誌裡 npmjs.org 與實際下載主機命中開發者代理群組，再執行：

Shellnpm install -g @google/gemini-cli
gemini --version

若使用 pnpm、corepack 或公司私服，請一併核對 registry 與 shell 內殘留的 HTTPS_PROXY／NO_PROXY，避免安裝走 A 路、執行走 B 路。安裝完成只代表 CLI 二進位與相依就緒，不等於 Google 認證鏈路已通。

認證兩條路：OAuth「Code Assist」與 API Key 公開端點

Gemini CLI 在 2026 年的實作裡，常見兩種出口，分流規則必須同時覆蓋，否則會出現「登入網頁看似成功、CLI 仍 403／逾時」：

  • API Key／金鑰路線：多數透過公開 generativelanguage.googleapis.com 與 @google/genai SDK 相容端點發送請求。只寫網頁用 gemini.google.com 規則時，金鑰測試常全失敗。
  • OAuth「Login with Google」路線：依官方 Code Assist 流程，除 accounts.google.com、oauth2.googleapis.com 外，推論與帳號綁定還會涉及 cloudcode-pa.googleapis.com（內部 Code Assist API）、codeassist.google.com 等主機；與消費端網頁主機不完全重疊。

OAuth 會在本機暫聽 127.0.0.1 埠（例如 /oauth2callback）等待瀏覽器回呼；本機回呼本身應 DIRECT，但回呼前後對 Google 的 HTTPS 若未代理，仍會在終端顯示「認證逾時」。請勿把問題簡化成「關防火牆就好」，而應對照連線日誌看哪一段主機仍為 DIRECT 到不穩 BGP。

主機心智地圖：建議納入 GEMINI_CLI 的網域

下列為教學用骨架，請以你環境日誌為準增刪；避免單條過寬的 DOMAIN-KEYWORD,google 誤傷無關服務。

模型與 Code Assist API

  • generativelanguage.googleapis.com — API Key 與多數腳本呼叫。
  • cloudcode-pa.googleapis.com — OAuth／Code Assist 路線常見；缺此條時「登入成功、對話逾時」機率高。
  • 可選：www.googleapis.com 底下其他子網域（如 userinfo）；企業若走 Vertex 請另參 Enterprise 專文，勿整包 googleapis.com 一把梭。

OAuth 與帳號

  • accounts.google.com、oauth2.googleapis.com — 登入與權杖交換。
  • codeassist.google.com — 部分回呼與文件導向主機（以日誌為準）。
  • developers.google.com — 成功／失敗導向頁可能出現在瀏覽器分頁，建議短期與 CLI 共用同一出口做對照。

靜態與共用資源（慎用最寬規則）

  • www.gstatic.com — 測速與部分載入；除非日誌明確指向載入失敗，否則不必為 CLI 單獨全域改寫。

終端進核心：TUN、系統代理與 HTTPS_PROXY

「瀏覽器開 Gemini 正常、Gemini CLI Clash 卻無效」多半仍是行程未進核心。請對照 僅瀏覽器走代理 與 TUN 模式指南，在 Rule 模式下二選一或並用：

  • 系統級 TUN／系統代理：覆蓋面大，適合長期在 iTerm、VS Code 內建終端跑 gemini；記得規劃 LAN／公司 VPN 略過。
  • 只對執行 CLI 的 Shell 設定：export HTTPS_PROXY=http://127.0.0.1:埠（mixed-port 對應位址），NO_PROXY 保留 127.0.0.1,localhost 與內網 Git，勿把本機回呼埠誤送進上游代理。

除錯時請同時看兩個問題：(1) 連線有沒有出現在 Mihomo 日誌？ (2) 若有，命中哪個 proxy-groups？ 規則寫得再漂亮，沒進核心都等於零。

五步收斂：從安裝到重新登入

若尚未匯入訂閱，請先完成 訂閱匯入，再將下列步驟接到你的規則骨架（整體順序哲學可讀 規則分流詳解）。

  1. 確認 npm install -g @google/gemini-cli 全程日誌命中 npm 開發者群組；版本指令 gemini --version 能立即回應。
  2. 開啟連線日誌，在未設任何 Proxy 的乾淨 Shell 執行 gemini 觸發登入；若完全沒有 Google 主機紀錄，先處理 TUN 或 HTTPS_PROXY，不要急著換節點。
  3. 新建 GEMINI_CLI（名稱可自訂）select 群組，除錯期手動鎖單一低抖動節點，暫停頻繁 url-test 切換，避免 OAuth 工作階段被視為環境跳動。
  4. 在 GEOIP、巨大 RULE-SET、寬鬆 MATCH 之前插入上文主機的 DOMAIN-SUFFIX；OAuth 與 API Key 路線先收斂到同一群組，待穩定後再視需求拆分。
  5. 重跑 OAuth 或金鑰測試；若規則顯示正確仍異常，轉查 DNS：fake-ip-filter、瀏覽器安全 DNS／DoH 是否繞過本機；必要時用 curl -v --proxy 對 generativelanguage.googleapis.com 做手動對照。

小貼士：OAuth 失敗時除錯請分「連不上 Google」與「連得上但 403／scope 不符」兩類；前者用本文分流與進核心收斂，後者可能涉及 Google 帳號方案或 Code Assist 專案綁定，需對照官方文件而非無限加規則。

YAML 骨架（請替換節點名並依日誌補洞）

YAMLproxy-groups:
  - name: "GEMINI_CLI"
    type: select
    proxies:
      - "GEMINI_CLI_AUTO"
      - "Your-Hand-Picked-Node"
      - DIRECT
  - name: "GEMINI_CLI_AUTO"
    type: url-test
    proxies:
      # paste real proxies from subscription
    url: "https://www.gstatic.com/generate_204"
    interval: 300
    tolerance: 50

rules:
  - DOMAIN-SUFFIX,lan,DIRECT
  - DOMAIN-SUFFIX,local,DIRECT
  # Gemini CLI: OAuth + API (BEFORE broad GEOIP / RULE-SET)
  - DOMAIN-SUFFIX,generativelanguage.googleapis.com,GEMINI_CLI
  - DOMAIN-SUFFIX,cloudcode-pa.googleapis.com,GEMINI_CLI
  - DOMAIN-SUFFIX,oauth2.googleapis.com,GEMINI_CLI
  - DOMAIN-SUFFIX,accounts.google.com,GEMINI_CLI
  - DOMAIN,codeassist.google.com,GEMINI_CLI
  # npm global install (see npm split article)
  - DOMAIN-SUFFIX,npmjs.org,NPM_REGISTRY_PROXY
  - DOMAIN-SUFFIX,npmjs.com,NPM_REGISTRY_PROXY
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

粒度提醒：訂閱模板若把整段 googleapis.com 提前命中 DIRECT 或錯誤群組，你手寫的 CLI 細則可能永遠輪不到。請以載入後實際順序與日誌命中來源為準，而不是只看 YAML 檔案視覺位置。

節點選型：延遲低不等於 OAuth／串流穩

url-test 對 generate_204 的結果不保證對 cloudcode-pa.googleapis.com 長連線友善。實務建議：在 GEMINI_CLI 內先用美西／美東或新加坡等常見節點手動固定完成登入與首輪對話，確認穩定後再恢復自動測速；tolerance 過小會讓工作階段內頻繁換出口，表現成「假性逾時」。

若你同時跑 Cursor、MCP 外掛與 CLI，可把 MCP 分流文 當並行參考，但不要假設 MCP 規則會自動涵蓋 Gemini CLI 的 Code Assist 主機。

常見問題

只代理瀏覽器，為什麼 gemini auth 仍逾時？ 因為 CLI 由 Node 子行程發起，未繼承瀏覽器 PAC；請確認日誌中 Google 主機是否仍 DIRECT。

OAuth 與 API Key 要分開兩個策略群組嗎？ 除錯期建議同一群組降低變因；穩定後若需讓一般 Google 網頁走直連、CLI 走代理，再拆分並注意登入出口分裂。

規則寫了為什麼還是逾時？ 依序檢查：未進核心、規則被寬集合提前命中、DNS／fake-ip、節點品質。勿在未確認日誌前無限複製他人規則包。

結語

2026 年 Gemini CLI 是高頻的終端 AI 代理入口，痛點集中在「npm 裝得起來，認證與 API 卻逾時」。把問題拆成安裝鏈路、終端進核心、OAuth 與 generativelanguage／cloudcode-pa 兩類主機，再用 Clash 分流 Google API 收斂到可觀測的 GEMINI_CLI 群組，多數案例可在不改 CLI 版本的前提下收斂；與 AI Studio 網頁、Enterprise 主控台相比，CLI 更需要終端視角而非只抄瀏覽器規則。

相較於只靠系統 VPN「整台一把抓」或論壇零散的域名列表，市面作法往往缺少可審核的 YAML 順序與連線日誌對照，團隊在 CI 與本機對齊時容易反覆踩同一個 Gemini CLI 逾時 坑。Clash 官網 把訂閱、TUN、npm 與終端分流放在同一套文件脈絡裡，對照日誌就能分清「卡在安裝、OAuth 還是模型 API」。若你想把本篇步驟穩定下來，不妨先在合法合規前提下 免費下載 Clash 官網，再依 教學文件 把 GEMINI_CLI 規則收斂成可回溯的團隊版本。