前言：先判斷問題出在哪一層
使用 Clash 執行 Gemini CLI 時，最常見的症狀包括指令長時間停在載入畫面、出現 timeout、connection refused、請求失敗，或是在登入流程中無法開啟瀏覽器頁面。這些現象看起來很像「Gemini CLI 壞掉了」，但實際上通常是連線路徑、代理模式、DNS 解析或節點品質其中一環出現問題。
Gemini CLI 並不一定完全遵循瀏覽器的代理設定。瀏覽器能正常開啟 Gemini，不代表終端機裡的 CLI 一定能連上相同服務。CLI 可能使用系統環境變數、Node.js 或 Python 的網路函式庫，也可能需要額外的登入回呼連線。因此，排查時不要只重複切換節點，而應該按照「本機網路 → Clash 狀態 → DNS → 規則 → 節點 → CLI 設定」的順序逐層確認。
排查原則
先用簡單的域名與 HTTPS 請求確認代理是否可用，再檢查 Gemini 相關域名是否命中正確策略，最後才調整 TUN 或 CLI 參數，避免一次改動太多設定而無法定位原因。
1常見錯誤與初步判斷
不同錯誤訊息通常對應不同的故障位置。先記下完整錯誤內容與發生時間，並觀察 Clash 的連線日誌，通常可以大幅縮小排查範圍。
| 症狀或訊息 | 常見原因 | 優先檢查項目 |
|---|---|---|
ETIMEDOUT、請求逾時 |
節點延遲過高、路由不通或流量未走代理 | 節點延遲、代理模式、Clash 日誌 |
ENOTFOUND、DNS 解析失敗 |
本地 DNS 污染、Fake-IP 或 DNS 設定衝突 | DNS 模式、解析結果、TUN 設定 |
403、401 |
登入狀態失效、地區不符或節點 IP 風險較高 | 帳戶狀態、出口地區、固定節點 |
| 瀏覽器可用，CLI 不可用 | 終端機未使用系統代理或環境變數錯誤 | HTTP_PROXY、HTTPS_PROXY、端口 |
| 登入回呼卡住 | 本機回呼端口被阻擋或瀏覽器流量分流異常 | localhost 連線、系統防火牆、瀏覽器規則 |
注意
不要把所有錯誤都歸咎於 Gemini 服務端。若 Clash 日誌完全沒有出現相關請求，問題多半發生在 CLI 沒有使用代理，而不是節點本身失效。
2先完成 Clash 與系統的基礎檢查
首先確認 Clash 客戶端仍在運作，並且目前使用的是有效配置。若訂閱已過期、配置檔案沒有成功更新，或代理核心停止運行，CLI 當然無法建立連線。
- 打開 Clash 客戶端，確認核心狀態為執行中，並記下混合代理端口，例如
7890或7897。不同客戶端的端口可能不同，不要直接照抄範例。 - 在代理模式中先選擇「規則」模式，確認目前有可用的代理策略組。若策略組顯示空白、節點全部失效，先更新訂閱或選擇其他節點。
- 在 Clash 的連線頁面觀察請求日誌。稍後執行 Gemini CLI 時，應該能看到 Gemini 或 Google 相關域名的連線紀錄。
- 暫時關閉其他 VPN、加速器、企業安全軟體或瀏覽器代理擴充功能，避免多個代理同時接管同一條連線。
接著用終端機測試代理端口。以下範例適用於 HTTP 混合端口，請將 7890 改成你在 Clash 中看到的實際端口：
如果第一個請求成功、第二個請求逾時，代表本機代理基本可用，但 Gemini API 相關路徑或節點可能存在問題。如果兩個請求都失敗，應先修復 Clash 或節點，不要急著修改 Gemini CLI。若你使用的是 SOCKS5 端口，則應改用 -x socks5h://127.0.0.1:端口，其中 socks5h 會讓域名交由代理端解析。
3動手設定：讓 Gemini CLI 明確使用 Clash
這是整篇排查中最容易被忽略、也最值得先做的一步。桌面 Clash 的「系統代理」主要影響支援系統代理的應用程式，而終端機工具未必會自動讀取它。最穩妥的方式，是在啟動 CLI 前明確設定代理環境變數。
- 確認 Clash 的混合端口，例如
7890。 - 在目前 PowerShell 視窗設定代理變數。
- 在同一個視窗啟動 Gemini CLI，避免變數只設定在另一個終端機工作階段。
在啟動 CLI 前執行以下指令。若你的客戶端只提供 SOCKS5 端口，請把網址改成 socks5h://127.0.0.1:7891。
設定後再次執行 CLI，並同步查看 Clash 日誌。如果仍然完全沒有相關請求，可能是該版本 CLI 使用獨立的網路實作，或環境變數名稱不被它讀取。此時可先確認工具版本與官方文件，並用相同終端機執行 curl，分辨是 CLI 特有問題還是代理本身問題。
小撇步
不要在命令列中公開貼出 API 金鑰、登入權杖或完整錯誤日誌。分享問題時，請先遮蔽帳戶資訊、訂閱網址與本機路徑。
4調整 Gemini 分流規則與 DNS
若 CLI 已經能連到代理，但請求依然逾時，下一步就是檢查分流規則。規則必須放在較寬泛的規則之前，否則可能先被 GEOIP、MATCH 或其他策略攔截。以下是可作為排查起點的域名規則，策略名稱請依你的配置修改：
登入流程與 API 請求可能使用不同的域名，因此只添加一個 API 域名往往不夠。若你希望一般 Google 服務維持原有分流，也可以為 Gemini 建立獨立策略組，固定使用一個穩定節點，而不要讓它在每次請求時隨機切換地區。
DNS 模式與解析結果
DNS 問題常會表現成「偶爾成功、偶爾逾時」。在 Clash 設定中確認 DNS 已啟用，並避免同時依賴本地運營商 DNS 與代理 DNS。若使用 Mihomo，可根據客戶端支援情況選擇 Fake-IP 或 Redir-Host；更重要的是讓代理域名使用可靠的遠端解析，並確認 Fake-IP 過濾清單沒有誤排除 Google 相關域名。
修改 DNS 後，重新載入配置、清理系統 DNS 快取，再測試連線。Windows 可執行 ipconfig /flushdns；macOS 或 Linux 則應依作業系統版本重啟 DNS 快取服務。若改成遠端解析後問題消失，就表示原先的域名解析路徑確實是故障來源。
5何時需要開啟 TUN 模式
如果系統代理與環境變數都已設定，但 Gemini CLI 仍然不出現在 Clash 日誌中，或某些登入回呼、背景請求始終繞過代理，可以考慮啟用 TUN 模式。TUN 會建立虛擬網路介面，接管更多不遵循一般代理設定的流量，對需要完整接管的 CLI、開發工具與子程序特別有幫助。
- 在 Clash 客戶端設定中開啟 TUN，必要時允許系統管理員權限或安裝虛擬網卡。
- 確認 TUN 的堆疊模式、DNS 劫持與自動路由選項互相匹配，不要同時啟用多個 VPN 虛擬介面。
- 重新啟動 Clash 核心與終端機，再測試
curl和 Gemini CLI。 - 若開啟後所有網站都無法連線，立即停用 TUN，回到規則模式檢查路由與 DNS，而不是持續疊加設定。
權限與安全提醒
TUN 會接管系統層級流量，請只使用可信任的 Clash 客戶端與配置。啟用前先備份設定，並留意公司網路、虛擬機器和安全軟體可能與 TUN 發生衝突。
6排除節點品質與登入問題
當規則、DNS 與 CLI 代理都正確，仍然出現逾時或請求失敗時，問題很可能在節點出口。Gemini 對連線穩定度、IP 地區和共享 IP 的風險都較敏感。高峰時段多人共用的節點，可能出現 TCP 建連成功但 TLS 或 API 回應很慢的情況。
- 先測延遲，再測穩定度： Clash 顯示的延遲只是單次測試結果，連續執行多次請求，觀察是否有大量波動或封包遺失。
- 固定出口地區： 登入與日常使用盡量使用同一地區、同一策略組，避免短時間內從多個國家或地區切換。
- 避免盲目追求最低延遲： 延遲低不代表 API 穩定，能持續完成 HTTPS 請求與長連線的節點通常更實用。
- 重新驗證登入： 若只有登入失敗，先在瀏覽器登出不必要的帳戶，清除失效的授權狀態，再使用穩定節點重新登入。
也要檢查本機時間是否正確。TLS 憑證驗證與 OAuth 登入都依賴系統時間，時間偏差過大時，可能出現看似代理問題的憑證或授權錯誤。若更換節點後能正常登入，卻在原節點重現錯誤，通常應向節點服務商回報出口 IP、連線時間與錯誤類型，而不是反覆刪除 CLI。
推薦的最終檢查順序
確認 Clash 核心運作 → 用代理執行 curl → 檢查 CLI 環境變數 → 查看規則命中 → 測試 DNS → 更換穩定節點 → 最後才啟用 TUN 或重新登入。
只要按照這個順序處理，大多數 Gemini CLI 的連線逾時都能被定位。記得每次只修改一個變數，並在修改後重新測試；這樣不但更容易找出根因，也能避免留下過度寬鬆或彼此衝突的 Clash 規則。