Gemini CLI 連線逾時，先分辨是哪一段失敗

Gemini CLI 出現「一直等待」「API 沒有回應」或 ETIMEDOUT 時，問題不一定在模型服務本身。終端工具和瀏覽器的網路行為不同：瀏覽器可能透過系統代理、瀏覽器擴充功能或既有連線順利開啟網頁，但 CLI 由 Node.js 或其他執行環境啟動，未必會自動採用相同的代理設定。一次完整的 Gemini CLI 請求，通常可能包含登入授權、Google 帳戶驗證、模型 API、版本檢查、說明文件或套件下載等多條連線。只要其中一個主機沒有命中正確規則，最外層就可能只顯示逾時。

排查時不要一開始就不停更換節點，也不要看到「Gemini」就把所有 Google 網域全部送進同一個策略組。較可靠的做法，是先記錄錯誤發生的時機：如果連安裝指令都無法完成，優先檢查套件註冊表與 CDN；如果安裝完成但登入卡住，應查看授權跳轉和本機回呼；如果登入成功、只有模型請求逾時，才把重點放到 API 主機、TLS 握手、DNS 和目前節點的穩定性。

另一個常見假象是「瀏覽器可以使用 Gemini，Gemini CLI 卻不行」。這往往代表兩者走了不同路徑，而不是代表 Clash 完全失效。瀏覽器可能使用作業系統的 HTTP 代理，CLI 卻只讀取 HTTPS_PROXY；也可能是瀏覽器支援系統憑證，CLI 使用自己的 TLS 實作。先將問題拆成「安裝」「登入」「API 呼叫」三個階段，再針對每一階段查看 Clash 連線日誌，會比盲目修改整份 YAML 更快找到原因。

ℹ 起手三件事：確認 CLI 是否真的使用 Clash 代理；查看失敗主機的實際網域與規則命中結果；再檢查 DNS 解析、節點延遲和系統時間是否正常。

先確認 Gemini CLI 是否真的走到 Clash

Clash 已經啟用，不代表所有命令列程式都會自動走代理。若你使用的是一般代理模式，必須確認終端環境中的代理變數已指向 Clash 的 HTTP 或 mixed port。不同客戶端的埠號可能不同，常見值包括 7890、7897 或自訂埠，請以 Clash 介面顯示的實際值為準。不要直接複製別人的埠號，因為即使本機有另一個程式正在監聽該埠，請求也可能被送到錯誤的服務。

在 macOS 或 Linux 中，可以先檢查目前 shell 是否存在舊的代理設定。若你曾經使用過 VPN、公司代理、終端加速器或其他 Clash 客戶端，HTTP_PROXY、HTTPS_PROXY、ALL_PROXY 和 NO_PROXY 可能互相矛盾。Windows PowerShell 也可能保留使用者層級環境變數。重點不是把所有變數都填滿，而是讓 Gemini CLI 使用一條清楚、可驗證的路徑，並避免同時套用 SOCKS、HTTP 與 TUN 造成重複接管。

代理變數的大小寫也值得留意。部分 Node.js 套件會讀取大寫欄位，部分工具或相依套件則會檢查小寫欄位；如果你只設定其中一組，可能出現主指令可用、子程序卻直連的情況。可以在測試期間暫時統一設定，再重新啟動終端和 CLI，不要只在已經開啟的 shell 內修改後期待背景程序立即更新。完成測試後，記得檢查是否有不必要的全域設定，避免日後讓公司內網、localhost 或本地套件服務也被送進代理。

如果你使用 Mihomo 或支援 TUN 的 Clash 客戶端，可以先選擇一種模式進行測試，不要讓「系統代理」「環境變數代理」與「TUN」三者同時改變。一般流程建議先使用混合埠加環境變數驗證，因為連線路徑最容易理解；確認 CLI 能穩定完成登入與 API 呼叫後，再測試 TUN。若 TUN 模式能用、一般代理不能用，問題通常在 CLI 的代理繼承；若一般代理能用、TUN 反而逾時，則應檢查路由、DNS 接管或防火牆權限。

環境變數與本機回呼的注意事項

OAuth 或瀏覽器登入流程常會在本機開啟回呼連接埠，例如 127.0.0.1 或 localhost。這些位址通常不應經過遠端代理，因此 NO_PROXY 應包含本機回呼使用的主機名與位址。若本機回呼被錯誤送往 Clash，登入頁面可能已經顯示成功，但 CLI 始終等不到授權結果。另一方面，若你把過大的網域範圍加入 NO_PROXY，Google 相關 API 又可能意外直連，造成登入成功後的模型請求逾時。

建議在登入期間同時觀察三個畫面：終端輸出、瀏覽器是否正常完成授權，以及 Clash 的連線日誌。若日誌只有本機回呼，沒有任何外部 Google 主機，代表 CLI 可能沒有把請求交給 Clash；若外部主機出現但顯示直連，應檢查規則；若主機已命中代理卻在 TLS 階段長時間停留，才需要進一步比較節點、DNS 和網路環境。

Gemini CLI 的 Clash 規則：不要只寫一個關鍵字

Gemini CLI 的實際連線主機會受到版本、登入方式、地區、Google 帳戶流程和核心更新影響，因此不宜把一份固定網域清單當成永久答案。更穩妥的方法，是先在測試期間打開 Clash 的連線紀錄，按時間排序找出 CLI 啟動後新增的主機，再把它們分成「授權與控制平面」「模型 API」「套件與更新」三類。分類的目的不是把規則寫得越多越好，而是讓不同用途可以使用不同的策略組，方便日後判斷是哪一條鏈路出問題。

對於已確認的精確主機，可以使用 DOMAIN 規則；同一服務有多個可信子網域時，再考慮 DOMAIN-SUFFIX。但是，請避免為了讓 Gemini CLI 立即恢復，就把整個廣泛的 Google 網域都送往代理。這樣做可能讓搜尋、YouTube、公司 Google Workspace 或其他不需要代理的服務一起改道，也會增加規則衝突和隱私風險。規則順序同樣重要：較精確的主機規則應放在寬泛規則之前，否則前面的 `MATCH`、地區規則或大型規則集可能已經提前決定出口。

如果你的配置使用遠端規則集，還要確認規則集本身可以正常更新。規則檔下載失敗、快取過期或格式不相容時，介面可能仍然顯示「已啟用」，實際卻沒有最新條目。建議在修改規則後重新載入配置，清楚記下測試時間、命中的規則名稱與策略組，並一次只改一個變數。例如先固定策略組不換節點，只驗證網域規則；再固定規則，換兩個不同地區節點比較；不要同時改規則、DNS、TUN 和節點，否則結果無法歸因。

DNS、fake-ip 與 TLS：逾時不一定是節點太慢

DNS 是 Gemini CLI 排障中很容易被忽略的一層。Clash 的規則判斷可能依賴主機名，但系統解析、遠端解析、fake-ip 和嗅探的組合會影響最終連線位址。若 CLI 使用的 DNS 路徑和瀏覽器不同，兩者可能得到不同的 IP、不同的 CDN 邊緣節點，甚至一個成功、一個在 TLS 握手時逾時。這也是為什麼「我用瀏覽器開得了」不能直接證明 CLI 的 DNS 沒問題。

使用 fake-ip 時，請確認目前配置和客戶端核心版本的行為一致。部分本機回呼、企業內網、特殊驗證主機或需要真實 IP 的服務，可能需要放入 fake-ip-filter 或直連例外。不要一次把所有 Google 網域加入排除清單，因為這會讓原本需要代理的 API 直接連線。比較好的順序是先從連線紀錄找出單一失敗主機，短暫建立最小範圍例外，再測試是否改善；若有效，再評估它是否適合長期保留。

TLS 逾時也可能與系統時間、根憑證、SNI、節點出口或中間設備有關。請確認作業系統日期與時區正確，並避免使用過於老舊的 Clash 核心或客戶端。若只有某一個節點在 Gemini CLI 上逾時，換到同一策略組內的另一個穩定節點是有意義的；若全部節點都失敗，則應回頭檢查規則和 DNS，而不是繼續購買或更換節點。測試時可分別觀察「DNS 解析完成」「TCP 建立」「TLS 握手」「收到 HTTP 回應」各階段，這比單看最後的 timeout 文字更有判斷價值。

⚠ 不要把 verify 關掉當作永久修復：若你為了避開憑證錯誤而停用 TLS 驗證，最多只能作為隔離問題的短暫測試，不能當成正式配置。先確認系統時間、根憑證、節點來源與 Clash 核心版本，再恢復正常的憑證驗證。

節點、策略組與 TUN 模式的實際測試順序

當規則看起來正確，下一步才是檢查節點品質。Gemini CLI 的請求通常需要較穩定的長連線，單純看延遲數字不夠。某個節點可能對測速網址反應很快，但對 Google API 的 TLS 握手不穩，或在長時間串流回應期間頻繁斷線。因此，選節點時應同時考慮握手成功率、連線維持時間、不同時段表現和實際 API 回應，而不是只挑面板中 RTT 最低的節點。

若策略組使用 url-test，請理解探針網址的結果不等於 Gemini API 的真實品質；若使用 fallback，健康檢查地址失敗可能觸發切換，但不代表所有 API 主機都失敗。建議建立一個專門給 AI CLI 使用的策略組，先用 select 固定節點完成對照測試，再視結果改為自動選擇。固定節點的價值在於可重現：你能知道是規則改動造成改善，還是自動策略剛好換到另一條線。

TUN 模式適合處理不尊重系統代理的程式，卻也會引入路由表、虛擬網卡、DNS 接管和作業系統權限等新變數。開啟 TUN 前，先關閉可能衝突的 VPN、虛擬網卡或舊版加速器，確認 Clash 核心具有必要權限，並保留原本可以工作的普通代理配置。啟用後，先測試一般 HTTPS 網站，再測試 Gemini CLI；如果普通網站正常但 CLI 仍逾時，查看該程序是否被防火牆、端點安全軟體或特殊代理設定排除。

  1. 固定一個已知穩定的節點，使用 Clash HTTP 或 mixed port 測試 CLI。
  2. 在連線紀錄中確認授權、API 和更新主機的規則命中結果。
  3. 只更換另一個節點，觀察逾時發生率是否改變。
  4. 最後才啟用 TUN，重新確認 DNS、路由和本機回呼。

常見錯誤與修復方向

如果 Gemini CLI 在安裝階段逾時，先檢查套件管理器的 registry 設定、代理變數和下載 CDN，不要先調整模型 API 規則。若安裝完成但登入頁無法開啟，檢查瀏覽器是否被錯誤代理、授權主機是否命中策略組，以及本機回呼是否被 NO_PROXY 正確排除。若登入成功後才出現 API timeout，則查看模型請求的實際主機、節點出口和串流連線是否中途斷開。

如果錯誤訊息是 ECONNRESET 或連線被重設，可能是節點出口、TLS 中間設備或長連線穩定性問題；如果是 ENOTFOUND，優先檢查 DNS 與主機名；如果是 407 Proxy Authentication Required，通常表示 CLI 使用了需要帳密的代理，但環境變數或 Clash 埠設定不符合預期。遇到 403 或 429，則不要簡單歸類為網路逾時，還要考慮帳戶權限、配額、地區限制和請求頻率。

你也可以建立一份簡單的排查紀錄，包含日期、CLI 版本、Clash 客戶端與核心版本、使用的模式、策略組、節點、失敗主機和錯誤類型。這份紀錄能幫助你分辨「每個節點都失敗」與「只有某一個節點失敗」，也能避免更新訂閱後忘記自己改過哪些規則。涉及訂閱 URL、API 金鑰或帳戶令牌時，請先遮蔽敏感資訊，再分享日誌；完整貼出設定檔可能同時暴露節點、密碼與個人識別資料。

Gemini CLI 逾時常見問題

瀏覽器可以用 Gemini，為什麼 CLI 還是逾時？

最常見原因是兩者沒有使用同一條代理路徑。瀏覽器可能採用系統代理，CLI 卻沒有讀取環境變數；也可能 CLI 的 DNS、TLS 或本機回呼行為不同。請先在 Clash 連線日誌確認 CLI 的實際主機是否出現，再檢查規則命中和代理埠，而不是只用瀏覽器測試網站。

一定要開 TUN 才能使用 Gemini CLI 嗎？

不一定。若 Gemini CLI 能正確讀取 HTTP、HTTPS 或 SOCKS 代理設定，一般代理模式已經足夠。TUN 主要用來接管不尊重代理變數的程式，或在多個程序需要透明代理時提供一致路徑。建議先用 mixed port 驗證，再決定是否需要 TUN，這樣更容易定位問題。

更換 DNS 後仍然逾時，下一步應該做什麼？

DNS 只是一個環節。接著應查看實際主機的規則命中、節點出口、TLS 握手和長連線穩定性。如果只有一個節點失敗，先固定規則並更換節點；如果所有節點都失敗，回頭檢查代理變數、規則順序、核心版本與帳戶回應，不要持續反覆切換 DNS。

相較於只提供瀏覽器開關的簡單代理工具，部分同類產品在命令列環境變數繼承、TUN 路由、DNS 例外和連線日誌方面較難細分，遇到 Gemini CLI 這類多階段工具時，往往只能靠反覆重啟或盲目換線；Clash V.CORE 則能把規則分流、策略組、DNS 行為與節點測試放在同一套可觀測流程中，方便針對登入、API 和更新鏈逐段驗證。若你希望把本文的排查方法落實到日常工作流，可以前往下載 Clash V.CORE，從固定策略組與查看連線日誌開始，逐步建立穩定的 Gemini CLI 代理環境。