先理解 Gemini CLI 為何會連線逾時

Gemini CLI 是在終端機中執行的命令列工具，與瀏覽器、圖形化應用程式的網路行為並不完全相同。許多使用者看到 Clash 已經開啟、瀏覽器也能正常開啟 Google 或其他海外網站，便以為所有終端機請求都會自動經過代理；實際上，這個推論往往是不成立的。

當你執行 Gemini CLI 時，程式通常需要連線至 Google 的 API 服務，例如 generativelanguage.googleapis.com、登入服務網域，以及可能使用的身份驗證或遙測端點。只要其中任何一個網域無法連線、解析到不可達的 IP，或被 Clash 規則錯誤地分配到 DIRECT，CLI 就可能長時間等待，最後顯示 timeout、socket hang up、fetch failed 或無法取得回應等錯誤。

因此，排查的重點不是單純反覆切換節點，而是要回答三個問題：第一，Gemini CLI 的請求有沒有真正進入 Clash；第二，進入 Clash 後是否命中正確的代理規則；第三，DNS、TLS 或本機網路是否在連線建立之前就出現問題。依照這個順序排查，通常比盲目更換設定有效得多。

本文以 Clash Verge Rev 與 Mihomo 核心為例。不同版本的介面名稱可能略有差異，但 HTTP、SOCKS、規則分流與 TUN 模式的排查思路基本一致。本站只介紹工具設定，不提供代理節點或 Gemini 帳戶服務。

第一步：確認 Clash 本身與目前節點正常

在調整 Gemini CLI 之前，先確認問題不是 Clash 核心、訂閱設定檔或節點本身造成的。開啟 Clash 客戶端的首頁，檢查核心狀態是否為執行中，並確認目前已啟用一份有效的設定檔。接著進入「代理」頁面，選擇一個延遲較低、最近測試成功的節點。

不要只根據節點旁的延遲數字判斷可用性。延遲測試通常只代表某個測速網址可以回應，並不等於 Google API 一定能正常使用。建議先在瀏覽器開啟 Google 相關服務，再使用命令列進行實際測試。如果瀏覽器與命令列都失敗，問題多半在節點、路由或 DNS；如果瀏覽器成功而命令列失敗，則應優先檢查終端機代理設定。

確認本機代理連接埠

在 Clash 的設定頁面查看 HTTP 與 SOCKS 監聽連接埠。常見值是 HTTP 7890、SOCKS 7891，但請以你的客戶端實際顯示為準，避免直接照抄預設值。

用 curl 測試代理

將下方命令中的連接埠替換成你的設定，確認請求透過 Clash 後能取得 HTTPS 回應。若命令立刻失敗，先處理節點或代理本身，不要急著修改 Gemini CLI。

curl -I -x http://127.0.0.1:7890 https://generativelanguage.googleapis.com
curl -I --socks5-hostname 127.0.0.1:7891 https://generativelanguage.googleapis.com

兩個命令不一定都要成功，因為部分環境只開啟 HTTP 代理或只使用 SOCKS5。重要的是，至少有一種代理方式可以穩定完成 DNS 與 TLS 連線。如果輸出是 Could not resolve host、Connection refused 或長時間沒有任何回應，分別代表 DNS 解析失敗、本機連接埠沒有監聽，或遠端節點無法建立連線。

第二步：讓終端機與 Gemini CLI 使用 Clash

系統代理開關主要服務於會讀取作業系統代理設定的應用程式。終端機工具是否遵循它，取決於程式使用的網路函式庫與自身設計。最穩定、最容易驗證的方法，是在執行 Gemini CLI 的同一個 Shell 中設定代理環境變數。

如果你使用的是 HTTP 監聽連接埠，可以設定 HTTP_PROXY 與 HTTPS_PROXY。許多 Node.js 或其他命令列工具也會讀取小寫形式，因此建議大小寫兩組都設定。NO_PROXY 則用來排除本機位址，避免 localhost、內網服務或本機開發伺服器被錯誤送進代理。

macOS、Linux 與 WSL 的設定方式

在 Bash、Zsh 或 WSL 中，可先於目前終端機工作階段執行以下命令。這種方式不會永久修改系統設定，適合先測試是否能解決問題：

export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export ALL_PROXY=socks5://127.0.0.1:7891
export http_proxy="$HTTP_PROXY"
export https_proxy="$HTTPS_PROXY"
export all_proxy="$ALL_PROXY"
export NO_PROXY=localhost,127.0.0.1,::1

gemini

如果測試成功，而且你每天都需要使用 Gemini CLI，可以將這些設定放入 ~/.zshrc 或 ~/.bashrc，然後重新載入 Shell。請注意，ALL_PROXY 與 HTTPS_PROXY 同時存在時，不同程式的優先順序可能不同；遇到行為不一致時，可以先只保留 HTTPS 的 HTTP 代理設定，確認基本連線後再加入 SOCKS5。

Windows PowerShell 與命令提示字元

PowerShell 使用 $env: 語法設定目前視窗的環境變數。請在啟動 Gemini CLI 的同一個 PowerShell 視窗執行，若另開一個視窗，設定不會自動繼承：

$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"
$env:ALL_PROXY="socks5://127.0.0.1:7891"
$env:NO_PROXY="localhost,127.0.0.1"

gemini

若你使用命令提示字元，則可使用 set：

set HTTP_PROXY=http://127.0.0.1:7890
set HTTPS_PROXY=http://127.0.0.1:7890
set ALL_PROXY=socks5://127.0.0.1:7891
gemini

設定完成後，可用 echo $env:HTTPS_PROXY 或 echo %HTTPS_PROXY% 檢查值是否存在。若環境變數看起來正確，但 Gemini CLI 仍然完全沒有流量，請開啟 Clash 的連線記錄，執行一次命令後觀察是否出現相關請求。

不要將包含 API Key、帳戶權杖或私人代理資訊的完整終端機輸出貼到公開論壇。排查時可以遮蔽網域中的識別參數、授權標頭與訂閱連結，避免憑證外洩。

第三步：檢查 Google API 網域是否命中代理規則

終端機請求進入 Clash 後，還要經過規則引擎判斷走向。若設定檔只為瀏覽器常用網域配置了代理，而沒有涵蓋 Gemini 使用的 API 網域，請求就可能落入直連或最後的 MATCH 規則。此時瀏覽器某些頁面可以開啟，但 CLI API 請求仍會逾時。

先打開 Clash 的「連線」或「日誌」頁面，再執行 Gemini CLI。搜尋 googleapis.com、generativelanguage.googleapis.com、accounts.google.com 等關鍵字，確認請求是否出現，以及右側顯示的策略名稱是否為代理群組。不同版本的 Gemini CLI 可能使用不同的登入與 API 網域，因此不要只檢查單一主機名稱。

為 API 網域加入明確規則

如果你使用自訂 YAML 設定檔，可以在規則清單中加入較明確的網域後綴規則。規則必須放在通用直連規則之前，否則前面的規則一旦先命中，後面新增的代理規則不會生效：

rules:
  - DOMAIN-SUFFIX,generativelanguage.googleapis.com,PROXY
  - DOMAIN-SUFFIX,googleapis.com,PROXY
  - DOMAIN-SUFFIX,google.com,PROXY
  - DOMAIN-SUFFIX,gstatic.com,PROXY
  - MATCH,DIRECT

其中 PROXY 必須替換成你設定檔中實際存在的代理群組名稱，例如 Proxy、自動選擇 或其他名稱。YAML 的縮排、群組名稱大小寫與中文字元都必須完全符合原設定，否則核心可能無法載入，或規則雖然存在卻無法選取。

不建議一開始就把所有流量永久設定為代理。較好的做法是先使用明確網域規則驗證問題，確認 Gemini CLI 恢復後，再根據日常需求調整分流策略。這樣可以減少不必要的流量，也能避免內網、套件鏡像與本地開發服務受到影響。

第四步：排查 DNS 解析與 TLS 連線

DNS 問題是 Gemini CLI 逾時中很容易被忽略的一環。即使 Clash 已接管 HTTPS 流量，如果網域解析仍由本地網路或不穩定的 DNS 服務器完成，可能得到錯誤、過期或無法連線的 IP。更麻煩的是，某些命令列工具在建立代理連線前就自行解析主機名稱，導致請求根本沒有依照預期進入 Clash。

使用 SOCKS5 測試時，請優先使用 --socks5-hostname，而不是 --socks5。前者會把網域解析交給代理端，後者可能在本機先解析主機名稱。HTTP 代理通常會將完整 URL 交給代理服務器處理，但實際行為仍取決於程式與函式庫版本。

curl -v --socks5-hostname 127.0.0.1:7891 \
  https://generativelanguage.googleapis.com

在 Clash 的 DNS 設定中，可確認是否啟用了內建 DNS、Fake-IP 或 redir-host 模式，並檢查 DNS 劫持是否與 TUN 設定衝突。若切換 DNS 模式後問題消失，通常表示原本的解析請求沒有被正確接管。修改前建議備份設定檔，因為不同核心版本支援的欄位名稱並不完全相同。

如何區分 DNS 問題與憑證問題

若日誌顯示 no such host 或 temporary failure in name resolution，優先處理 DNS。若顯示 connection reset、handshake timeout 或 x509，則可能與節點中斷、系統時間錯誤、TLS 檢查或代理鏈路不穩定有關。請確認作業系統日期與時區正確，因為 HTTPS 憑證驗證對時間非常敏感。

不要為了快速排錯而長期關閉 TLS 驗證。關閉驗證會降低安全性，也可能掩蓋真正的節點或憑證問題。如果只有某一個節點出現 TLS 錯誤，應先切換節點比較；若所有節點都發生相同錯誤，才進一步檢查本機安全軟體、企業網路或系統代理攔截。

第五步：系統代理無效時啟用 TUN 模式

如果你已經設定環境變數，Clash 連線記錄仍然沒有 Gemini CLI 的請求，或者某個 CLI 使用的網路函式庫完全忽略代理設定，可以考慮啟用 TUN 模式。TUN 會在作業系統中建立虛擬網路介面，從更底層接管流量，因此不依賴每個應用程式是否支援 HTTP_PROXY。

在 Clash Verge Rev 中，通常可於「設定」或「系統」頁面找到 TUN 開關。首次啟用時可能需要系統管理員或 root 權限，macOS 也可能要求允許網路擴充功能。啟用後，請確認模式為「規則」，並檢查 DNS 劫持與自動路由選項是否符合你的網路環境。

儲存現有設定

在修改 TUN 或 DNS 前先匯出目前設定檔。若啟用後出現無法上網、內網失效或路由循環，可以快速還原。

開啟 TUN 並授予權限

開啟 TUN 後依照系統提示授權，等待虛擬介面建立完成。不要在權限視窗尚未完成時重複點擊開關。

重新啟動終端機與 CLI

關閉原本的 Gemini CLI 程序並重新開啟終端機，避免舊程序保留未更新的 DNS 或代理狀態，再執行測試命令。

TUN 並不是任何情況下的萬用解。它需要更高權限，可能與 VPN、企業安全軟體、Docker 網路或其他虛擬網卡衝突。若只是單純讓一個 CLI 走代理，優先使用環境變數通常更容易維護；只有在應用程式不支援代理，或需要完整接管 UDP、DNS 與非 HTTP 流量時，才建議使用 TUN。

第六步：依照錯誤訊息快速定位問題

不同錯誤訊息通常對應不同層級的故障。把錯誤分類後再採取行動，可以大幅縮短排查時間。

Connection refused：通常代表 7890 或 7891 沒有服務監聽、連接埠填錯，或 Clash 核心沒有啟動。先在客戶端確認實際連接埠。
Could not resolve host：代表 DNS 解析失敗。檢查 Clash DNS、系統 DNS，以及 SOCKS 測試時是否使用了 --socks5-hostname。
Connect timeout：可能是請求直連被阻斷、規則未命中，或目前節點不可用。查看連線記錄中的策略名稱與目標網域。
Fetch failed：這是較籠統的應用程式錯誤，應配合 Clash 日誌、curl 詳細輸出與環境變數逐層確認。
401 或 403：通常代表網路已經連通，問題轉為 API Key、登入狀態、帳戶權限或服務區域限制，不宜繼續修改代理規則。
429：代表請求已抵達服務，但可能受到速率限制或配額限制。這不是單純的 Clash 逾時問題。

你也可以採用「最小化測試」方法：先用 curl 測試網路，再用相同 Shell 的環境變數執行 CLI，最後才加入複雜的自訂規則、TUN、代理鏈或多重 DNS。每次只修改一個變數，並記錄修改前後的結果，才能知道真正有效的修復方式。

穩定使用 Gemini CLI 的建議設定

完成排查後，建議把設定整理成容易理解、方便還原的形式。首先，為 Gemini 相關網域建立獨立規則，並讓它指向一個穩定的代理群組，而不是直接綁定某一個節點。這樣節點故障時只需在代理群組內切換，不需要修改 YAML 規則。

其次，保留一份可工作的設定檔備份，並為環境變數設定建立簡短的 Shell 別名。例如可以建立 gemini-proxy 腳本，在腳本中先設定代理，再執行 Gemini CLI。這種方式比把一長串命令貼在歷史紀錄中更容易重複，也能避免每次手動輸入時打錯連接埠。

最後，定期觀察 Clash 的連線日誌與節點品質。若某個節點只在晚間逾時，可能是高峰期擁塞；若只有 IPv6 環境失敗，可能是 IPv6 路由或 DNS 優先順序問題；若更新 CLI 後才開始失敗，則應查看新版本是否改變了 API 網域、代理函式庫或憑證處理方式。將時間、節點、錯誤訊息與規則策略記錄下來，未來遇到相同問題時會更容易處理。

最可靠的驗證方式是觀察 Clash 連線記錄：執行 Gemini CLI 的同時，確認目標網域出現、請求策略為代理群組，且連線狀態能完成。單看瀏覽器是否正常，無法證明終端機已使用代理。

總結：先確認流量，再修規則與 DNS

Gemini CLI 連線逾時通常不是單一按鈕造成，而是「終端機代理、Clash 規則、DNS 解析、節點品質」其中一環沒有接通。最有效率的順序是：先用 curl 確認 Clash 節點能連線，再在目前 Shell 設定 HTTP 或 SOCKS 代理環境變數，接著從 Clash 日誌確認 Google API 網域與代理策略，最後才處理 DNS、TUN 或更複雜的路由設定。

相較於只提供簡單系統代理開關的工具，Clash 的優勢在於可以清楚查看請求、建立網域規則、切換代理群組，並在需要時使用 TUN 接管更完整的流量。這些功能讓 Gemini CLI、套件管理器、Git、容器工具等不同類型的終端機程式，都能按照實際需求分流。

使用 Clash 連線記錄確認 Gemini CLI 的請求是否真正進入代理。
透過環境變數讓不一定遵循系統代理的終端機工具使用正確連接埠。
為 googleapis.com 與相關服務網域設定明確的代理規則。
遇到解析錯誤時檢查 Clash DNS，必要時使用 TUN 接管完整網路流量。
根據錯誤訊息區分網路連通、身份驗證、配額與帳戶權限問題。

如果你尚未安裝或需要更新 Clash 客戶端，可以前往下載頁面取得適合你作業系統的版本。完成安裝後，先準備有效設定檔，再依照本文的測試順序逐項確認，就能更穩定地使用 Gemini CLI。

Gemini CLI Clash故障排除連線逾時

Gemini CLI 連線逾時怎麼辦？Clash 配置排查與修復指南