為何 Gemini CLI 在終端機比瀏覽器更容易卡住
「官方套件可以裝」「文件頁能打開」，不代表你 shell 底下那串 Node 行程真的走對出口。Gemini CLI 典型會把三件彼此獨立的事壓在同一個指令列生命週期：從發佈倉抓版本與依賴、從 GitHub CDN 拉大檔或小工具、以及進入對話／工具呼叫後對 generative language 類端點的長連線請求。任何一段被規則誤放在 DIRECT（直連）而你的直連環境對該區域並不友善，就只會在日誌裡反覆打印泛用逾時。與只做網頁對話的情境不同，套件拉取對 SNI／Host 的命中細節敏感得多；同一品牌底下也會分出 registry、CDN 與 OAuth 的子網域，請勿用「都打 Google」一句話帶過。
TUN（虛擬網卡通路）在這種場景的價值在於：以路由層補環境變數不好覆蓋的漏網。npx、corepack、pnpm 或企業套件管理器往往在子行程裡發請求；只開系統 HTTP(S) 代理時常仍會看到異常比例的直連紀錄。與之相對，導出 HTTPS_PROXY／HTTP_PROXY／必要時 ALL_PROXY（並補 NO_PROXY 排除內網）對「會讀標準環境變數的行程」更有效，成本也較低。務實上你會混搭：先用規則＋紀錄校準發佈倉與 API 名稱是否真的命中預期的策略組，再決定是否長開 TUN。若你已處理其他模型 CLI，可把本文當終端共通套路的 Gemini 特例化。
相關延續閱讀：與套件端對齊的通用文章可對照 Google Agents CLI 與 npm／uv／TUN（偏 Python／Node 混合型鏈）；純codex 類請看 OpenAI Codex CLI 終端機逾時。WSL2 與宿主 Windows Clash 對齊可讀 WSL2、Git、npm 與 Clash。
1先復現，再用連線紀錄補主機清單
準備官方的 Node 版本要求後，請用你在卡的那段完全一致的指令復現問題：例如文件中建議全域安裝、以 npx 單次執行或使用 pnpm dlx，都請保留原貌，避免因快取遮蔽而誤判。並行在 Mihomo／Meta 或前端的連線清單盯住逾時發生前後的紀錄，先把Hostname／SNI記下：registry.npmjs.org、registry.npmmirror.com（若鎖過鏡像）、objects.githubusercontent.com、github-releases.githubusercontent.com、storage.googleapis.com、generativelanguage.googleapis.com、oauth2.googleapis.com、以及任何出現過的登入／授權子網域。對照每一列顯示的策略組，若發現應該跨境卻標成 DIRECT，優先用紀錄回填規則，而不是馬上猜測套件壞掉。
第二個容易混淆是分類問題：慢與逾時。前者可能只是節點頻寬或對端限速；後者通常在 TLS、路由黑洞或規則搶先到錯的策略組。Gemini SDK 對大型回應的逾時門檻也會疊加網路程式延遲，因此請在 Clash 同時監看對話發生期的長連線是否真的走代理並且沒有被中途切回直連。切記：你在瀏覽器裡對 Google AI Studio「看起來可連」並不能證明目標 API 域名在終端也得到相同對外視圖。
2TUN、系統代理與環境變數如何取捨
對多數套件管理器來說，最短的嘗試是於當前 shell 輸出一組對應 Mihomo Mixed／HTTP inbound 的環境變數，並用 NO_PROXY 排除 localhost／內網段／公司 SCM。Gemini CLI 若有子行程對 mTLS／自簽 或公司 HTTPS 解密閘道 過敏，錯誤訊息常僅縮寫成泛用的 TLS handshake 失敗，此時請與紀錄層級同看，避免把問題誤會成「國際路由」。TUN 則適合你已經明確看到很多二進位子行程根本不吃環境變數，或你希望「整機開發環境對外視圖」一致的情境；啟動前請讀過 Clash Verge Rev TUN 開啟教學，並注意與公司全隧道 VPN 同時開啟時的預設路由競爭。
實務建議：先對 registry 類主機達成可重現命中，再評估長駐 TUN；不要僅換節點卻不重看規則。
macOS／Windows／Linux 桌面彼此權限與劫持方式不同：mihomo 核心層對 loopback／系統服務的處理差異會影響「看起來已開代理仍未命中」的假陰性。WSL／容器裡請把 DNS／代理視為獨一空間；若宿主已跑 Clash，務必核對宿主 IP、轉發埠與自動代理腳本的一致性，並避免雙 DNS 競態。高安全／設備控管較嚴的環境若對執行檔來源強校驗，確保你已用官方發佈的安裝路徑，以免把ENOENT誤會成ECONNRESET類網路連線問題。
3npm／鎖鏡像、.npmrc與規則
registry 多半是終端卡住的第一個嫌疑對象：若紀錄顯示 registry.npmjs.org 仍反覆進 DIRECT，請將該類網域名稱與實際命中的 CDN 別名補到你的策略組，並確認MATCH／GEOIP 類規則沒有更早就吃走。.npmrc 鎖國內或公司鏡像時，請同時對鏡像主機放行合理策略；鏡像品質問題與「其實沒進代理」是兩件事，避免混成一團。strict-ssl=false在非充分理解的情境下只是把 TLS 異常掩埋成「能過就好」，對企業環境並不適合優先選用；請先對齊中介 CA 或節點相容性。pnp／pnpm store快取若在跨磁碟複製過程異常慢，也請別忘了核對紀錄中是否仍然有對外 etag／packument的網際請求。
下面是規則骨架示範：PROXY 請取代成你YAML 裡確實存在的策略組名稱；並依你的連線紀錄增刪主機。MATCH 最終一跳請與日常使用一致。Mihomo／Meta 若拆分 rule-providers，建議對高頻變動的發佈倉來源做小檔按需更新。註解使用英文以迎合設定檔慣例。
# Example only — replace PROXY; extend rows from YOUR connection logs
rules:
- DOMAIN-SUFFIX,npmjs.org,PROXY
- DOMAIN-SUFFIX,npm.community,PROXY
- DOMAIN-KEYWORD,github,PROXY
# Google AI / oauth / apis — prefer exact domains recorded in YOUR logs:
# - DOMAIN-SUFFIX,googleapis.com,PROXY
# - DOMAIN-SUFFIX,google.dev,PROXY
# - DOMAIN-SUFFIX,google.com,PROXY # widen only if justified by hostname evidence
- MATCH,DIRECT「把整棵 *.google* 一刀切」對某些場景過寬也容易誤傷國內可直連的子服務；對工程排查而言，請把實際在紀錄中出現的子網域列優先級，並用規則順序保障命中穩定。Gemini 對話鏈若改用 regional endpoint，紀錄也會對應變化——請以你自己的連線紀錄為準，而不是複製他人數月前的域名表。
4呼叫 Gemini API 時的域名與混合逾時
安裝成功後卡住，問題常轉移到推論請求／工具呼叫／憑證刷新：OAuth 環節對時間同步與HTTPS 劫持都很敏感。Gemini 對外端點多落在 googleapis.com 家族或其指引的 regional 名稱後綴；若你已啟GEOIP／GEOSITE 自動選路，請確認那些 API 並沒有被更早規則誤送回直連。部分企業對 mTLS pinning 或對 AI 出站做分類，終端側錯誤訊息只會籠統顯示「請求未完成」。此時請以Mihomo 紀錄觀察對話發生毫秒級是否仍落在預期的策略組，並把RST／timeout／i/o deadline區分開來。
若你並行運行多款模型 CLI（例如對照 Anthropic／OpenAI），不要把「一家的規則」想當然套到另一家；本篇只強調：Google 的流量可能與 CDN、物件儲存、登入伺服器並行發生。Cursor 類 IDE 對 GitHub／npm 的對齊可參考 Cursor／npm 分流對照（2026）——把終端對外視圖與 IDE 對外視圖對齊到同一 Mihomo inbound，能顯著降低心智負載。對於會啟動本機OAuth 裝置授權的流程，紀錄中偶爾出現臨時導向或驗票端點；請仍以你在畫面上看到跳轉的網域名稱回填規則，而不是硬套舊版本的靜態表。
5DNS、Fake‑IP 與規則早匹配
TUN 並非 DNS 問題的替代品：若你看到「換個時間又好了」，優先懷疑 fallback DNS race、fake-ip-filter 漏項目或雙隧道 DNS。請對照 Meta／Mihomo DNS 指南，把發佈倉與 OAuth／API 類名稱與規則解析視圖一起校準。OpenWrt／透明代理／桌面 Mihomo混用時請先釐清哪一層在吃第一跳 DNS，避免紀錄中出現來源混亂的假象。
提醒：公司 HTTPS inspection 會改寫終端對 CA 的信任模型——請先走完資訊安全流程，別把略過 TLS 驗證視為解法。
「先把 DNS 調到校準極限再談規則」或「只靠規則忽略 DNS」兩種極端都會誤導：實際上請同步看SNI／DoH／劫持與規則匹配的解析一致度，並以可重現的 curl -v／openssl s_client 對照請求（僅在貴單位授權的情境）做小範圍驗證。若對端對 HTTP/3 有特殊要求，也請檢視節點對 UDP 的相容。mihomo對嗅探、SNI sniff 類開關在部分場景能改善匹配，但也要理解其對隱私與紀錄噪音的權衡。
6驗收取捨：從對測回到日常
- 請先確認TUN或環境變數其中一側已穩定生效，再以 registry 與對話發生期的連線紀錄挑出仍疑惑的 Host，跑最小對測並留下團隊能理解的重現證據。
- 重跑你最初卡的那段安裝與對話指令，並保持環境完全一致；對照紀錄中是否出現異常偏高的 DIRECT 比例。
- 若規則命中正確但依然慢：輪換低延遲並且與 Google API 區域相容的節點，並避免同時競爭兩個全隧道網路。
- 若你已排除網路子系統但仍有配額／身分問題，請回到開發者控制台與錯誤訊息，本文不重複身分治理教學。
常見問題（對照紀錄讀）
瀏覽器能上文件，為何套件仍逾時？因為對外鏈路不同。npx 卡住就是 npm 問題？未必，也可能是 GitHub CDN 或大檔下載。TUN 一定要常開嗎？視你的子行程複雜度決定——先紀錄、後策略。
開源、授權與本站工具
Gemini CLI／底層客戶端授權以官方發佈倉自述為準。mihomo 核心與圖形前端許可亦請直接查閱 upstream。日常請優先從本站 下載區 取用經過整理的發佈，並搭配 總文件 釐清系統代理／TUN／mixed 的差異；本文不重製上游 release note。
結語
「Gemini CLI 壞掉了」往往是個假性結論：真正把命令列卡住的是發佈倉、GitHub CDN 與Google API／OAuth 並行鏈路之中任意一段對外視圖沒對齊。把 Mihomo 的連線紀錄當第一手證據，先補 hostname 粒度規則，再談環境／TUN，最後換節點，通常能砍掉大量輪試成本。DNS 與規則匹配必須同步思考，而不要期待單一總開關解決所有終端機差異。
與只靠「系統層級一鍵翻牆」的方案相比，Clash 體系把主機級命中細節放回工程師可用的排錯面：你能看到 registry.npmjs.org 是否真的走了代理策略，也能看到對話發生期有沒有被悄悄切回DIRECT。mihomo對大型規則集與自動更新也方便把 registry 來源視為會演化的對象來維護。
若你想把本篇流程落成日常環境：建議優先試著用TUN，或在安裝專用小 shell設定代理，並把針對 googleapis／npmjs／GitHub 三大類主機的回填策略寫進你的長期備份規則庫。免費下載 Clash並對照紀錄實際改一輪規則，通常比無限拉長套件管理器的網路逾時門檻更能定位根因。免費下載 Clash後請依本文順序自查，並把紀錄與對測結果存成你可回放的操作手冊（runbook）以利團隊共用。