先把現象說清楚:Gemini CLI 的逾時多半不是「單一網域」造成
如果你在終端機裡跑 Gemini CLI(或相近的 Google 終端工具鏈),最常見的挫折往往不是立即報錯,而是間歇性逾時、TLS 握手停很久、模型/延伸套件下載卡在百分比、或呼叫推理時一直重試。許多人的第一直覺是換節點、關掉 HTTP/2、甚至整機改成全域代理;但在實務上,這類問題更像多條連線同時走錯出口:一邊要打 generativelanguage.googleapis.com 這類與 Google AI API 相關的控制面;另一邊可能同時開啟瀏覽器視窗完成 Google 帳戶授權;背景又可能透過 npm 拉 tarball、或從 GitHub CDN 取 release/程式碼物件。只要其中一條路徑被規則誤判成 DIRECT、被 DNS 指到不理想的上游、或 UDP/QUIC 走了你沒預期的通道,CLI 端就常以泛用的「逾時」呈現,讓人誤以為是模型服務本身故障。
另一個關鍵是:終端程式經常不吃圖形介面的系統代理。你可能已在桌面用戶端把 Clash 開得很好,Chrome 也能順暢開啟 Google 服務;但回到 zsh 或 bash,若沒有正確的 HTTPS_PROXY/ALL_PROXY、或沒有讓流量進入 TUN/透明代理鏈路,CLI 仍可能繞過你以為已生效的代理。這也是為何「Gemini CLI 代理」值得獨立討論:它同時牽涉應用程式行為與網路層可觀測性。若你正要處理純終端環境變數與 Shell 繼承問題,建議先對照本站macOS 終端機代理與環境變數一文,把進入核心的方式對齊後,再回到本文做Google AI API 分流與套件鏈路的網域級拆分。
流量桶怎麼切:Google AI API 分流不是「一個 googleapis」就結束
要把Gemini CLI Clash規則寫得可維護,第一步是接受一件事:終端體驗通常不是單一主機名稱,而是多個用途並行。建議先在筆記裡至少切出四個桶,而不是把所有東西都塞進名叫 PROXY 的策略組。
第一個桶是推理與 Google AI 控制面:常見會包含 generativelanguage.googleapis.com 這類端點(實際名稱請以你當下版本與區域的連線日誌為準)。這裡封包小、延遲敏感、對長連線穩定度要求高;最忌諱的是把它與「大型物件下載」綁在同一個會頻繁切換節點的 url-test 組,導致連線被打斷而表現成逾時或重試風暴。
第二個桶是Google 帳戶、OAuth 與登入相關網域:CLI 初次設定或重新授權時,常會跳轉到瀏覽器或命中與帳戶驗證相關的主機名稱。這類流量對「憑證鏈、時間同步、cookies 與跨網域重新導向」更敏感;若你將它們與純 API 混在同一個過窄規則裡,容易出現「瀏覽器視窗開了但 CLI 仍等不到 token」的割裂感。實務上可先在日誌裡搜尋 accounts.google、oauth、google.com 等你環境實際出現的字根,再決定是否獨立成 GOOGLE-ID 類策略組。
第三個桶是npm registry 與 tarball 鏈路:許多 CLI 工具以 Node 生態發佈或會在背景執行 npm install 類行為;除了 registry.npmjs.org 查索引,實際 tgz 往往落在另一組 CDN 主機上。這條路徑與 API 不同之處在於頻寬、分段下載與 TCP 視窗行為;把它獨立出來,你才能在某天下載爆量時只切換「套件出口」,而不動到推理 API。站內npm/pnpm 與 tarball CDN 分流已把 JavaScript 套件鏈寫得很細;本文把同一套方法論接到「Gemini CLI 同時打 Google AI」的場景,避免你只優化 registry 卻讓 googleapis 仍誤走直連。
第四個桶是GitHub 與 GitHub CDN:模型索引、工具發佈頁、release 資產或相依原始碼常命中 github.com、codeload.github.com、objects.githubusercontent.com 等。這類GitHub CDN Clash規則若與 npm tarball 混為同一桶不是不行,但在除錯時會失去「一眼分辨 Git 物件與 registry 套件」的能力;對開發者工具鏈而言,分桶通常更省時間。
DOMAIN 或交由 rule-providers 分段維護;需要拆檔時可延伸閱讀Rule Providers 教學。策略組命名:讓 GEMINI-API、NPM、GH-CDN 在日誌裡讀得懂
實務上建議準備至少三個語意清楚的策略組(名稱自訂),例如 GEMINI-API、NPM-CHAIN、GH-CDN,並視需要再加 GOOGLE-ID。命名重點是除錯時可讀,而不是把所有請求都叫同一個 PROXY。select 適合你做手動對照;url-test 適合長期挑延遲較低的節點,但要小心:對「大檔下載」友善的節點,未必是對「小封包 API」延遲最低的那個。
你也可以在 GEMINI-API 內保留一顆可信的手動節點,專門給推理呼叫;在 NPM-CHAIN 與 GH-CDN 內放另一組偏頻寬或對分段下載較穩定的線路。這樣當你懷疑「代理反而拖慢 npm」時,可以只在套件組做 DIRECT 對照,而不必動到 API 組。
下列 YAML 僅示意結構與註解位置;鍵名、型態與規則語法請以你所用的 Mihomo/Clash 核心版本為準。程式碼區塊內註解一律使用英文,方便你貼回範本後比對。
proxy-groups:
- name: GEMINI-API
type: select
proxies:
- NODE-LATENCY-STABLE
- DIRECT
- name: GOOGLE-ID
type: select
proxies:
- NODE-LATENCY-STABLE
- DIRECT
- name: NPM-CHAIN
type: select
proxies:
- NODE-BULK-FRIENDLY
- DIRECT
- name: GH-CDN
type: select
proxies:
- NODE-BULK-FRIENDLY
- DIRECT
rules:
# Put BEFORE broad GEOIP / third-party lists when possible.
# Replace hostnames with values observed in your logs.
- DOMAIN,generativelanguage.googleapis.com,GEMINI-API
- DOMAIN-SUFFIX,googleapis.com,GEMINI-API
- DOMAIN-SUFFIX,accounts.google.com,GOOGLE-ID
- DOMAIN-SUFFIX,google.com,GOOGLE-ID
- DOMAIN-SUFFIX,npmjs.org,NPM-CHAIN
- DOMAIN-SUFFIX,npm.pkg.github.com,NPM-CHAIN
- DOMAIN-SUFFIX,github.com,GH-CDN
- DOMAIN-SUFFIX,githubusercontent.com,GH-CDN
請把上一段範例當作「起點」,而不是可直接複製到生產環境的終稿:DOMAIN-SUFFIX,googleapis.com 與 google.com 都可能過寬,會把大量非 CLI 必要的請求一起帶進同一出口;更穩健的流程永遠是先日誌、後收斂。若你發現某些子網域其實更适合走直連或企業內網,請把它們用更前面的規則逐條排除。
DOMAIN-SUFFIX 搭配過大的第三方規則集,最容易造成「偶發正常、偶發失敗」的假隨機現象;這時應優先檢查規則命中順序,而不是反覆重裝 CLI。規則優先順序:為什麼「已經寫了分流」卻像沒生效?
Clash/Mihomo 規則由上而下匹配,命中即停止。最常見的狀況,是某條地區直連、教育網直連、或超大第三方規則集,把 Google/GitHub/npm 相關請求提前判成 DIRECT,導致你後面為 Gemini CLI 細修的規則永遠讀不到。另一種常見狀況則相反:你把「所有 HTTPS」先丟進代理,結果本機 healthcheck、套件快取探測或特定 UDP 行為互相干擾,看起來像工具鏈更新失敗,其實是子請求在錯誤策略下重試。
實務上建議順序:本機、區網、以及確定必須直連的管理介面保留在最前段;接著放你已用日誌確認過、且範圍明確的 Gemini/Google AI、npm、GitHub 規則;最後才是大型 GEOIP 或兜底規則。每加一條規則都問自己:它會不會比我更寬鬆、卻排在更前面?若答案是會,就要調整順序或把規則改窄。若你同時也在 IDE 裡使用擴充市集,可把情境與Cursor/GitHub 分流對照:該篇偏圖形化開發環境;本文偏終端與 CLI,並行時建議分檔維護避免規則表失控。
DNS 與「誰在解析、誰在連線」:第二個戰場
很多使用者花大量時間調整節點,卻忽略 DNS。典型症狀是:瀏覽器開網頁正常,但 CLI 卡住;或同一台機器上,某些子命令成功、某些永遠逾時。這類落差往往代表解析鏈路與實際連線鏈路不一致:程式仍繞過 Clash 的 DNS 流程,得到與策略組假設不同的位址,接著 TCP 連線又在另一條路徑上發起。
若你使用 fake-ip 類模式,更要理解它的設計目標是讓應用程式把流量交回核心;一旦部分程式仍自行解析,就會出現難以直覺理解的錯位。請把排查濃縮成一句:先確認誰在回答 DNS,再確認誰在發起連線。可依序參考本站使用說明與文件以及連線看似正常但無法上網的日誌排查,把 DNS 模式與規則放回同一張心智圖。
另一個與 DNS 強相關、卻常被誤會成「Google 壞掉」的情況,是過於激進的廣告攔截或追蹤封鎖規則,把某些驗證或分析子網域 REJECT 掉。CLI 不一定會顯示清楚錯誤碼,只會用逾時或重試呈現;請先在日誌確認該主機名稱是否被拒絕,再決定是否放行或改走特定出口。
TLS、UDP、HTTP/3:別把所有逾時都怪在模型 API
當你觀察到「握手階段拖很久」時,請不要立刻把原因歸咎於 Gemini 服務本身;要先確認是不是 UDP 路徑、或 HTTP/3/QUIC 行為與節點能力不相容。這類問題常見於同一台機器同時開著瀏覽器與 CLI:瀏覽器可能走不同協定棧或不同快取,導致表象不一致。若只有部分資源卡住,可先對照本站QUIC/HTTP3 排查,再回到本場景對照異常主機名稱。
驗證流程:用日誌把「猜」變成「可重現」
請盡量單因子改動;下列步驟可依序做一次就記錄結果,並對照策略組命中是否符合預期。
- 確認 CLI 的流量有進核心:依環境選擇 TUN、系統代理,或為終端設定
HTTPS_PROXY/ALL_PROXY;並確認沒有第二套 VPN 在更底層搶路由。 - 重現問題時立刻開連線日誌:搜尋
googleapis、google、npm、github、objects等字串,以實際出現的主機名稱為準建立規則。 - 對照規則命中:確認每一條卡住請求的策略組是否符合你的意圖;若否,回到規則順序章節檢查是否有寬規則提前匹配。
- 分開測試三個桶:暫時只讓
GEMINI-API走候選節點、其餘維持原設定,觀察逾時是否改善;再輪流只改NPM-CHAIN或只改GH-CDN。 - 對照環境變數與 Shell:若懷疑 CLI 仍繞過代理,回到終端環境變數與 IDE 繼承檢查,避免只在圖形介面調整。
若你希望把另一家供應商的終端工具拿來對照方法論,本站OpenAI Codex CLI 分流描述了相近的拆分邏輯;與本文並讀有助建立「終端開發代理」共通心智模型。
與站內 Chrome Gemini、純 npm 專題的關係
Chrome Gemini Skills 分流著重瀏覽器帳戶、googleapis 與桌面端整合的工作流;本文則以命令列為主軸,並補上 npm GitHub CDN Clash 這條常與 CLI 並行的「資料面」。純 npm專題更深耕 registry 鏈每一跳;本文把它接到 Gemini 終端場景,三者並非重複,而是同一方法論在不同痛點上的切片。
合規與安全
請遵循所在地法令、雇主資訊安全政策與 Google、GitHub、npm 等供應商條款。代理與分流僅協助你做網路路徑可觀測與可控,而非繞過合規管制或規避服務限制。請只信任來源明確的訂閱與規則集,並定期更新用戶端。
常見問題(速查)
問:為什麼我已經全域代理,Gemini CLI 還是逾時?
答:全域不一定代表「終端每個子行程都走同一條鏈路」,也不代表 DNS 與 TCP 路徑一致;請先用日誌確認實際命中策略組與主機名稱。
問:npm 走鏡像時還需要拆 GitHub 嗎?
答:常常需要;許多套件仍會直接或間接依賴 GitHub 物件或 release 資產,鏡像無法自動涵蓋全部相依。
問:可以把規則全部交給訂閱嗎?
答:可以作為基底,但開發者 CLI 場景仍建議保留一小段「可自行調序」的自訂規則片段,否則你很難在超大規則集裡快速定位為何某個 hostname 被提前直連。
總結
Gemini CLI在終端的逾時,經常是 Google AI API、npm tarball 鏈路與 GitHub CDN 並發時其一掉鏈的結果,再疊加上終端不吃系統代理或 DNS 鏈路錯位。把它們拆成可命名的策略組、把精確規則放在大型 GEOIP/第三方集合之前,並用連線日誌驗證命中,通常比全屋換節點更有效。
相比之下,部分同類工具若不是一次只能選「全機 VPN」與「完全不代理」,就是把規則藏在封閉介面裡,對開發者常用的「多 hostname、多協定、多進程」場景缺乏可觀測性;遇到 CLI 與套件鏈並發時,往往只能反覆更換線路或關閉防護,卻很難定位到底是 API、套件還是 CDN 哪一跳異常。
Clash/Mihomo 生態則相對有利於把 Gemini CLI 代理所需的路徑分層表達清楚:你可以分別為推理、身分驗證、npm 與 GitHub 物件指定出口,並用日誌核對策略命中;無論是只想穩定完成模型下載,還是要在日常迭代裡長期跑終端 Agent,都能維持「可驗證」的調校節奏,而不是靠運氣試節點。
若希望先把用戶端來源統一,再依本文微調分流,可到本站用戶端下載頁取得目前平台的組建。