設定實戰 約 12 分鐘閱讀

Gemini CLI 怎麼用？用 Clash 設定穩定連線教學

想在終端機使用 Gemini CLI，卻一直碰到登入失敗或回應逾時？本篇整理 Clash 用戶端、訂閱匯入、分流規則與 DNS 檢查流程，協助新手建立穩定的使用環境。

Gemini CLI 與 Clash 的分工

Gemini CLI 是在終端機裡執行的命令列工具,通常會透過登入流程或 API 憑證建立 AI 服務連線。Clash 則負責代理轉發、規則分流與 DNS 解析,兩者不是同一層的工具。Gemini CLI 能否正常使用,取決於命令列程序是否真的把請求送進 Clash,以及 Clash 是否把相關網域分配到可用的代理策略組。

最常見的誤判是「瀏覽器已經可以開啟服務,所以終端機也應該可以登入」。瀏覽器通常會遵循系統代理,但命令列工具不一定讀取系統代理設定。即使終端機顯示網路已連線,Node.js、Python 或其他執行環境仍可能直接連線,最後出現登入頁打不開、OAuth 回呼失敗、API 回應逾時或憑證交換失敗。

先把問題拆成三層會比較容易排查:

  • Clash 用戶端層:確認訂閱已載入、代理模式正確、目前策略組有可用節點,並且系統代理或 TUN 沒有被其他 VPN 工具覆蓋。
  • 命令列環境層:確認 Gemini CLI 使用的終端機程序已取得 HTTP_PROXY、HTTPS_PROXY 或 ALL_PROXY 等環境變數。
  • 服務連線層:確認登入頁、授權回呼與 API 網域都命中代理規則,DNS 沒有回傳錯誤位址,節點所在地區也能正常存取該服務。

先確認核心與用戶端

Gemini CLI 的連線需求通常需要較完整的 HTTPS、TLS 與 DNS 支援。若仍在使用停止更新的原版 Clash 核心,建議改用內建 mihomo 核心的 Clash Verge Rev、Mihomo 類用戶端,再開始排查規則與命令列代理。介面名稱可能不同,但要找的功能通常是「設定檔 / Profiles」、「代理」、「系統代理」與「TUN」。

安裝 Clash 與匯入訂閱

先到下載中心選擇與作業系統相符的用戶端。Windows 使用安裝版時,首次啟動若出現防火牆提示,至少要允許私人網路;如果稍後要使用 TUN 或區域網路功能,再依實際環境授予必要權限。macOS 第一次開啟系統代理或 TUN,可能需要在「系統設定 › 隱私權與安全性」允許輔助程式。Linux 則要確認用戶端程序具有建立虛擬網卡或修改路由所需的權限。

安裝完成後,從服務商取得訂閱網址。訂閱網址不是普通首頁連結,通常是一串包含授權權杖的 HTTPS 網址。進入用戶端的「設定檔」頁面,選擇從網址新增設定檔,貼上完整連結並下載。下載完成後,還要點選這份設定檔使其生效;只下載而沒有啟用,代理頁面可能看得到節點,實際流量卻仍使用舊設定。

  1. 在 Clash 的設定檔頁面確認訂閱名稱、最後更新時間與節點數量,節點數量顯示為零時先不要測試 Gemini CLI。
  2. 進入代理頁面,選擇一個延遲合理且狀態正常的節點或策略組,不要只選名稱看起來相同但未完成測試的項目。
  3. 把模式切換為 Rule,讓一般國內流量直連,需要代理的 AI 服務流量交由規則判斷。
  4. 開啟系統代理,並確認混合連接埠。例如設定檔中若有 mixed-port: 7890,HTTP 與 SOCKS5 通常都可透過這個連接埠使用。
  5. 先用瀏覽器確認代理節點可用,再開啟新的終端機視窗。新終端機能讀到最新的環境變數,避免使用舊工作階段的錯誤設定。

如果訂閱下載失敗,先確認系統時間是否準確。TLS 憑證驗證依賴正確時間,時間偏差過大時會被判定為憑證尚未生效或已經過期。接著檢查訂閱網址是否被服務商重設,以及目前是否有其他代理工具攔截連線。訂閱網址含有帳號授權資訊,不要貼到公開討論區,也不要直接放進 shell 歷史、公開腳本或螢幕截圖。

命令列代理環境設定

GUI 用戶端的系統代理開關,不等於所有命令列程序都會自動使用代理。最穩定的做法是在啟動 Gemini CLI 前,明確設定命令列代理環境變數。以下以 Clash 混合連接埠 7890 為例,請先在設定檔中確認實際連接埠,不要直接照抄。

Windows 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:7890"
$env:NO_PROXY="localhost,127.0.0.1"
gemini

上述設定只對目前這個 PowerShell 視窗有效,關閉視窗後會失效。這種方式適合測試,可以避免把代理設定永久寫入所有命令列工具。若確定需要長期使用,再到 Windows 的環境變數設定加入同名變數,並重新開啟終端機讓新值生效。

macOS 與 Linux

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:7890"
export NO_PROXY="localhost,127.0.0.1"
gemini

如果使用的是 zsh,可把設定放入 ~/.zshrc;bash 則通常放在 ~/.bashrc。修改後執行 source ~/.zshrc 或重新開啟終端機。部分程式只讀取大寫變數,部分程式也會讀取小寫形式,遇到代理沒有生效時可以補上:

export http_proxy="$HTTP_PROXY"
export https_proxy="$HTTPS_PROXY"
export all_proxy="$ALL_PROXY"
export no_proxy="$NO_PROXY"

HTTP_PROXY 的值使用 HTTP 代理格式,即使目標網站是 HTTPS,也通常仍由 HTTP CONNECT 建立加密通道。ALL_PROXY 則常用 SOCKS5 格式。不要把兩者寫成帶有多餘路徑的網址,也不要把 Clash 控制面板連接埠誤當成代理連接埠。控制面板常見於另一個連接埠,例如 9090,它不能拿來代替 mixed-port。

避免重複代理

如果系統已經開啟另一個 VPN、終端機工具又設定了不同代理,請先關閉其中一個。多層代理可能造成 TLS 交握延遲、DNS 走向不一致或登入回呼落到錯誤介面。排查時只保留 Clash 與一組環境變數,結論會比較清楚。

規則與 DNS 實作檢查

Gemini CLI 的請求不一定只涉及一個網域。登入流程可能包含授權頁、驗證端點、API 端點與本機回呼;只把某一個網域加入代理規則,仍可能在下一步被直連規則攔截。建議先在 Clash 的連線記錄中觀察實際請求,再根據記錄補充規則,不要憑猜測大量加入關鍵字規則。

在 mihomo 設定中,可以建立一個專用策略組名稱,以下範例使用 AI-PROXY 作為示意。域名請依連線記錄替換成實際服務所使用的網域,範例中的 ai.example 只是明顯的假網域,不能直接當作可用規則。

proxy-groups:
  - name: AI-PROXY
    type: select
    proxies:
      - 自動選擇
      - 節點-1
      - DIRECT

rules:
  - DOMAIN-SUFFIX,ai.example,AI-PROXY
  - DOMAIN-KEYWORD,auth,AI-PROXY
  - GEOIP,LAN,DIRECT,no-resolve
  - MATCH,PROXY

DOMAIN-SUFFIX 適合明確的主網域及其子網域,DOMAIN-KEYWORD 則容易誤判,只建議在連線記錄已確認且關鍵字足夠特殊時使用。不要把 MATCH,AI-PROXY 放在整份規則中段,否則後面的本機、區域網路與直連規則都不會生效。若只是測試能否登入,可以暫時切換到 Global 模式;如果 Global 能用而 Rule 不能用,問題多半在規則或 DNS,不是節點本身。

DNS 方面,建議使用 mihomo 的 DNS 模組,並依環境選擇 fake-ip 或 redir-host。fake-ip 能讓 Clash 依原始網域進行分流,但區域網路、部分回呼服務與特殊應用程式可能需要加入 fake-ip-filter。如果開啟 TUN,應確認 DNS 劫持設定已經接管 53 埠,否則命令列程序可能繞過 Clash 直接使用系統 DNS。

dns:
  enable: true
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - "+.lan"
    - "+.local"
  nameserver:
    - https://dns.example/dns-query
  fallback:
    - https://fallback.example/dns-query
  fallback-filter:
    geoip: true
    geoip-code: CN

以上上游網址同樣是示意值,請使用用戶端或設定檔支援的實際 DNS 上游。重點不在於複製某個固定伺服器,而是確認 nameserver、fallback 與代理解析策略彼此不形成循環。測試時可在 Clash 記錄中觀察命令列啟動、登入與 API 請求是否出現,也可以用 nslookup 或 dig 檢查回應是否落入 fake-ip 網段。若回應一直來自路由器或本地電信商 DNS,先處理 DNS 接管,不要急著更換節點。

Gemini CLI 登入測試流程

設定完成後,不要一開始就連續重試登入。先用最小測試確認代理鏈路,再執行互動式登入。這樣可以分辨是 Clash 沒有接管、命令列沒有讀取代理,還是帳號授權流程本身失敗。

  1. 在 Clash 代理頁面固定一個狀態正常的節點,模式先使用 Rule,並記下目前混合連接埠。
  2. 在終端機輸出代理變數,例如 Windows 使用 Get-ChildItem Env:HTTPS_PROXY,macOS 或 Linux 使用 echo $HTTPS_PROXY,確認值指向 127.0.0.1:7890。
  3. 執行 Gemini CLI 的版本或說明指令,例如 gemini --version。如果連版本資訊都無法顯示,先處理 Node.js、PATH 或安裝問題,不要把它誤判為代理故障。
  4. 執行登入指令,依終端機提示完成瀏覽器授權或 API 憑證設定。瀏覽器跳出後,不要關閉正在等待回呼的終端機程序。
  5. 回到 Clash 的連線記錄,依時間排序查看新增的 HTTPS 連線,確認相關網域命中 AI-PROXY 而不是 DIRECT。
  6. 登入成功後再送出一個很短的測試請求,觀察回應時間、錯誤內容與節點流量。連續逾時時,先停止重試,改測另一個節點或暫時使用 Global 模式作對照。

登入頁可以開啟但授權完成後終端機沒有反應,通常是回呼階段被本機防火牆、瀏覽器安全設定或錯誤代理變數阻擋。此時保留 NO_PROXY=localhost,127.0.0.1,讓本機回呼不再繞到遠端節點;同時確認 Clash 的 TUN 或系統代理沒有把本機回呼位址改寫。若服務要求指定連接埠,還要檢查該連接埠是否被其他程式佔用。

現象優先檢查項目處理方向
指令不存在Node.js、套件安裝位置、PATH先修正安裝環境,再測試代理
登入頁無法開啟HTTPS_PROXY、Clash 連接埠、節點狀態確認變數與 mixed-port 一致
瀏覽器授權成功但終端機逾時NO_PROXY、本機回呼、防火牆放行 localhost 與 127.0.0.1,避免回呼繞路
Rule 失敗、Global 成功規則順序、網域命中、DNS 結果查看連線記錄並補上精確網域規則
偶爾成功、經常逾時節點品質、DNS 延遲、策略組選擇固定低延遲節點,再比較不同出口

常見錯誤與穩定化調整

如果回應逾時只發生在長時間輸入或較大的請求,不一定代表登入失敗。可能是節點頻寬不足、TCP 連線被中途重置,或策略組的自動測速把請求切換到另一個不穩定出口。測試期間先把策略組改為手動選擇,固定同一節點觀察數分鐘,再決定是否恢復自動選擇。

如果錯誤訊息顯示憑證無效,先檢查系統時間與 Node.js 執行環境,不要立刻關閉 TLS 驗證。停用憑證驗證會把真正的中間人、錯誤代理或網路劫持隱藏起來,也會降低帳號與 API 憑證的安全性。若只有某一個節點發生憑證錯誤,換節點並查看 Clash 連線記錄,通常比修改全域安全設定更合理。

如果命令列代理設定後仍完全沒有連線記錄,可能是該版本工具不讀取標準環境變數,或它在子程序中覆寫了代理設定。此時先查看工具自身的代理選項與啟動說明,再確認是否需要使用 HTTP 代理而不是 SOCKS5。不要同時把 HTTP_PROXY、HTTPS_PROXY 指向不同連接埠,否則登入頁與 API 可能分別走兩條路徑。

完成登入後,可以把日常配置固定成「Rule 模式 + AI 專用策略組 + TUN 視需要開啟」。一般瀏覽與本地服務不必全部走代理,只有連線記錄確認需要的網域交給 AI 策略組。每次更新訂閱後重新查看策略組名稱與節點是否仍存在,因為部分訂閱會重寫策略組或規則段落。若設定檔被更新覆蓋,應把自訂規則放在用戶端支援的覆寫區,不要直接修改每次都會重新下載的原始訂閱。

穩定配置的判斷標準

不是「所有流量都開 Global」才算穩定,而是 Gemini CLI 的登入、授權回呼與 API 請求都能穩定命中預期代理,同時本機回呼、區域網路與一般直連服務不被錯誤攔截。用連線記錄、代理變數與 DNS 結果三方交叉確認,比單看一次成功更可靠。

開始使用 Clash

如果尚未安裝用戶端,可先依作業系統選擇合適版本,再按照設定檔、代理模式與命令列環境變數的順序完成測試。

前往下載 查看教程

下載 Clash 用戶端

規則分流的前提是用戶端先接管流量。前往下載中心依平台選擇用戶端,再回到教學文章完成系統代理或 TUN 接管設定。

前往下載頁 看教學
下載Clash