原理解析 預計閱讀 12 分鐘

Gemini CLI 搭配 Clash Verge：穩定連線設定指南

Gemini CLI 讓開發者可以直接在終端機呼叫 AI 輔助功能，但實際使用時可能受到連線品質和服務可用性的影響。本文整理 Clash Verge 的入門設定與分流技巧，帶你完成從安裝到穩定使用的完整流程。

開始前先分清楚:Gemini CLI、Clash Verge 與代理核心

Gemini CLI 是在終端機中執行的命令列工具,主要透過網路連線到對應的 AI 服務。它和瀏覽器裡的聊天頁面不是同一條連線路徑:瀏覽器通常會讀取作業系統代理設定,命令列工具則可能讀取 HTTP_PROXY、HTTPS_PROXY、ALL_PROXY 等環境變數,也可能使用自身的網路設定。這也是「瀏覽器可以打開,但 Gemini CLI 連不上」最常見的原因。

Clash Verge 本身是圖形介面,真正負責建立本機監聽埠、載入設定檔、執行分流規則的是底層代理核心。不同版本的 Clash Verge 可能使用 Clash Meta 或 mihomo 核心,設定頁的名稱和按鈕位置會略有差異,但基本概念一致:先讓核心正常運行,再確認本機代理埠,最後把命令列工具的流量指向這個埠。

因此,整個設定可以拆成三層來看。第一層是節點和訂閱是否可用;第二層是 Clash Verge 是否正在運行並監聽代理埠;第三層是 Gemini CLI 的程序是否真的讀取了正確的代理環境變數。任何一層出錯,終端機裡都可能只顯示連線逾時、請求失敗或無法完成登入,不能只靠重新執行命令解決。

核心觀念:開啟 Clash Verge 的「系統代理」不等於所有命令列程式都會自動走代理。對 Gemini CLI 這類工具,最好在終端機內明確設定代理環境變數,並用診斷命令確認設定已生效。

安裝 Clash Verge 並確認本機代理埠

先從本站的下載頁取得與作業系統架構相符的 Clash Verge 或 Clash Verge Rev 安裝包。Windows 使用者要留意 x64 與 ARM64 的區分,macOS 則要確認 Apple Silicon 與 Intel 版本。安裝後第一次啟動,先不要急著匯入多份設定,應該先確認核心狀態、設定檔狀態和系統權限都正常。

  1. 開啟 Clash Verge,在設定檔頁匯入 Clash 格式的 YAML 訂閱,或貼上訂閱連結後完成更新。匯入後確認設定檔能通過解析,沒有紅色錯誤訊息。
  2. 切換到代理頁,確認至少有一個代理群組和可用節點。選擇一個延遲正常的節點,不要只停留在「自動選擇」而不檢查目前實際使用的成員。
  3. 在設定或常規頁找到 HTTP、混合代理或 SOCKS 代理的監聽埠。不同設定檔和版本可能使用不同數字,不能直接假定每台電腦都是同一個埠。
  4. 確認核心狀態為執行中,再用系統代理開關做瀏覽器測試。瀏覽器能正常開啟目標網站,只代表圖形介面和系統代理路徑正常,還需要另外測試命令列路徑。

Clash Verge 常見的本機位址是 127.0.0.1 或 localhost,但真正應使用的埠號以目前介面顯示為準。假設介面顯示 HTTP 或 mixed-port 為 7897,那麼代理地址可以寫成 http://127.0.0.1:7897。如果設定頁顯示的是只提供 SOCKS5 的埠,則應使用 socks5://127.0.0.1:埠號,不要把 SOCKS 埠誤填成 HTTP 代理。

注意:不要把網路服務商提供的遠端節點地址直接填入 HTTP_PROXY。環境變數需要指向本機 Clash Verge 監聽的代理埠,由 Clash Verge 再依照分流規則選擇遠端節點。

為 Gemini CLI 設定 HTTP、HTTPS 與 SOCKS 代理

命令列工具通常透過環境變數取得代理資訊。Gemini CLI 的具體行為可能受版本、底層 HTTP 函式庫和作業系統影響,所以建議優先使用最通用的 HTTP_PROXY 與 HTTPS_PROXY,再視需要補上小寫版本。許多 Unix 工具會區分大小寫,同時設定大小寫兩組可以減少不同程序之間的差異。

Windows PowerShell 設定方式

在 PowerShell 中,可以先為目前視窗設定臨時環境變數。以下範例假設 Clash Verge 的 HTTP 代理埠是 7897,實際使用時請替換成介面裡顯示的數字:

$env:HTTP_PROXY="http://127.0.0.1:7897"
$env:HTTPS_PROXY="http://127.0.0.1:7897"
$env:ALL_PROXY="http://127.0.0.1:7897"
$env:NO_PROXY="localhost,127.0.0.1,::1"

這些設定只對目前開啟的 PowerShell 視窗有效,關閉視窗後就會消失。這種方式適合先測試,因為不會永久改動系統。若確認連線正常,再依照常用的終端機、工作目錄或開發腳本需求決定是否寫入使用者環境變數。CMD 的寫法則是使用 set,例如 set HTTPS_PROXY=http://127.0.0.1:7897。

macOS 與 Linux 終端機設定方式

在 zsh、bash 等 Shell 中,可以使用 export 設定目前工作階段:

export HTTP_PROXY="http://127.0.0.1:7897"
export HTTPS_PROXY="http://127.0.0.1:7897"
export ALL_PROXY="http://127.0.0.1:7897"
export NO_PROXY="localhost,127.0.0.1,::1"

若要讓每次開啟終端機都自動套用,可以把設定放進目前 Shell 使用的啟動檔,例如 zsh 常見的 ~/.zshrc,bash 常見的 ~/.bashrc。不過不建議在不了解影響範圍時直接全域寫入,因為部分公司內網、套件管理器、版本控制工具或本機服務不應該經過代理。需要排除的內網網域和地址可以加入 NO_PROXY,並在重新開啟終端機後確認變數已載入。

如果 Clash Verge 只提供 SOCKS5 代理,可將 ALL_PROXY 改成相應的 socks5://127.0.0.1:埠號。但並非所有命令列網路函式庫都會正確處理 SOCKS 代理,遇到 HTTPS 請求失敗時,優先改用 Clash Verge 的 HTTP 或 mixed-port 測試,通常比反覆更換節點更容易定位問題。

動手完成一次連線測試與登入流程

完成環境變數設定後,不要直接把問題歸因於 Gemini CLI。按照下面順序測試,每一步都只驗證一個環節,可以避免多個設定同時改動造成排查混亂。

  1. 在同一個終端機執行 echo $env:HTTPS_PROXY 或 echo $HTTPS_PROXY,確認 PowerShell、CMD 和 macOS/Linux 的語法沒有混用。輸出的地址應該是本機地址和 Clash Verge 實際監聽埠。
  2. 確認 Clash Verge 的日誌頁正在出現新的連線記錄。若執行測試命令後完全沒有日誌,通常表示環境變數沒有被目前程序讀到,或程序使用了不支援該變數的網路函式庫。
  3. 使用一個簡單的 HTTPS 請求測試代理是否能轉發。Windows PowerShell 可使用 curl.exe -I https://example.com,macOS/Linux 可使用 curl -I https://example.com。若請求成功,再進行 Gemini CLI 登入,不要把兩個測試混在一起。
  4. 依照 Gemini CLI 目前版本提供的登入指引完成授權。瀏覽器授權頁打不開時,先確認瀏覽器和終端機是否使用同一個 Clash Verge 設定,不要只給瀏覽器開系統代理而忘記終端機環境變數。
  5. 登入完成後執行一個簡短請求,先測文字回應,再測較長的輸入或需要讀取本機檔案的功能。這樣可以區分基本 API 連線、長連線穩定度和本機檔案權限問題。

測試時可以同時觀察 Clash Verge 的日誌。正常情況下,日誌中能看到目標網域、命中的規則和使用的代理策略。如果終端機顯示連線失敗,但日誌完全沒有對應網域,問題大多發生在環境變數或程序啟動方式;如果日誌顯示已連線但請求很快被中斷,才需要進一步檢查節點品質、TLS、DNS 或服務端回應。

針對 Gemini 服務建立穩定的分流策略

Clash 的分流不是「開啟代理後所有流量都走同一條線」這麼簡單。規則模式下,核心會依照規則順序判斷網域、IP、程序或其他條件,再把請求交給指定的代理群組。對 Gemini CLI 而言,最重要的是不要只把一個猜測中的主網域加入規則,因為登入、API 請求、驗證和內容傳輸可能使用不同的服務網域。

如果訂閱設定檔已經包含完整的 AI 服務規則,優先沿用原有策略,只檢查規則是否被更前面的 GEOIP、IP-CIDR 或自訂直連規則覆蓋。若需要在本地覆寫,應該使用 Clash Verge 支援的設定覆寫功能,不要直接修改每次更新都會被遠端覆蓋的原始訂閱檔。

rules:
  - DOMAIN-SUFFIX,googleapis.com,AI
  - DOMAIN-SUFFIX,google.com,AI
  - DOMAIN-SUFFIX,generativelanguage.googleapis.com,AI
  - DOMAIN-SUFFIX,accounts.google.com,AI
  - MATCH,DIRECT

上面只是分流結構示例,不是所有網域都必然適用,也不能保證涵蓋某個版本的全部服務端點。AI 應該替換成實際存在的代理群組名稱。規則順序非常重要:針對特定網域的規則必須放在寬泛的直連或拒絕規則之前,否則即使文字寫對了也不會被命中。

需求建議策略檢查重點
Gemini CLI API 請求建立專用 AI 代理群組確認相關網域沒有被前置直連規則攔截
Google 帳戶登入登入網域與 API 網域保持一致策略瀏覽器授權與終端機請求不要使用互相衝突的出口
本機套件下載與內網服務使用 DIRECT 或 NO_PROXY排除 localhost、公司內網和本機開發埠
長時間生成或大型請求選擇穩定群組,不要只按最低延遲挑選觀察丟包、重連和尖峰時段的實際表現

穩定性調整與常見故障排查

Gemini CLI 的穩定度不只取決於面板裡顯示的延遲。命令列請求可能包含較長的等待時間、較大的回應內容或串流輸出,對丟包、連線重設和代理節點負載更敏感。選擇節點時,可以先用 URL Test 排除明顯逾時的節點,再實際執行數次短請求,觀察是否出現中途停止、重試過多或回應不完整。

如果瀏覽器正常而 Gemini CLI 失敗,先檢查以下三項:目前終端機是否真的有代理環境變數、環境變數中的埠是否和 Clash Verge 當前設定一致、以及是否有其他工具在啟動腳本中覆蓋了代理變數。Windows 上尤其要留意從開始選單開啟的終端機和 IDE 內建終端機可能不是同一個程序環境,修改後需要重新開啟 IDE 或終端機。

如果日誌顯示請求命中了 DIRECT,但你原本預期它走 AI 代理群組,應該檢查規則順序和網域寫法。若日誌顯示命中了正確群組,卻頻繁出現 timeout 或 connection reset,可以依序更換節點、降低並發請求、重新測試 HTTP 埠,並確認系統時間正確。TLS 憑證驗證對時間十分敏感,本機時間偏差也會造成看似代理故障的錯誤。

DNS 方面,若使用 mihomo 的 Fake-IP 模式,一般能讓網域規則更容易命中,但公司 VPN、區域網路服務和某些依賴真實 IP 的程式可能需要加入 fake-ip-filter 或改用 Redir-Host 對照測試。這個調整主要影響名稱解析和流量接管,不會替代 Gemini CLI 的代理環境變數設定;兩者是不同層面的問題。

不要忽略安全性:代理環境變數會被部分子程序繼承,不要把帶有帳號、密碼或敏感認證資訊的代理地址寫入公開腳本、專案儲存庫或錯誤回報內容。若使用需要認證的本機代理,建議採用不會被提交的使用者環境設定,並在分享日誌前移除完整命令列和環境資訊。

建議的日常使用流程

完成一次設定後,日常使用可以固定成簡單流程:先啟動 Clash Verge 並確認核心運行,再確認目前選中的代理群組,最後開啟帶有代理環境變數的終端機。每次修改訂閱或切換模式後,先用短請求測試,不要直接在長時間任務中驗證。這樣即使連線失敗,也能迅速判斷是節點、規則、環境變數還是 Gemini CLI 本身的問題。

  • 訂閱更新後,確認代理群組仍然存在,因為遠端設定可能改名或移除群組。
  • 切換 HTTP 代理埠後,同步更新終端機中的 HTTP_PROXY、HTTPS_PROXY 和 ALL_PROXY。
  • 遇到單一節點失效時,先切換同群組內的其他節點,不要立即重寫整份 YAML。
  • 長時間使用前,查看日誌是否有連續重連、DNS 失敗或規則命中錯誤。
  • 結束代理工作後,若不希望其他命令列工具繼續使用代理,關閉該終端機或清除目前工作階段的環境變數。

需要下載客戶端或查看完整操作說明時,可以前往下載頁和使用指南。穩定使用的關鍵不是堆疊更多參數,而是讓 Clash Verge 的本機監聽、分流規則和 Gemini CLI 的代理環境三者保持一致,每次只改一個變數並用日誌驗證結果。

下載客戶端