Gemini CLI 搭配 Clash：內地使用者連線設定攻略

先理解 Gemini CLI 與 Clash 的分工

Gemini CLI 是在終端機中使用 AI 輔助開發功能的命令列工具，可以協助閱讀程式碼、解釋錯誤、產生修改建議，以及在明確授權後操作工作目錄中的檔案。它的連線通常依賴 HTTPS 請求、網域名稱解析與登入憑證，因此終端機所在的網路環境會直接影響登入、模型請求與檔案分析的穩定性。

Clash 或採用 mihomo 核心的 FlClash，則負責在本機建立代理入口，依照設定檔中的策略組與規則轉送流量。兩者不是同一個程式：Gemini CLI 不會自動讀取 FlClash 的策略選擇，Clash 也不會替 Gemini CLI 管理 API 金鑰。最常見的連接方式，是讓 Gemini CLI 讀取環境變數中的 HTTP 或 HTTPS 代理位址，再將請求交給 Clash 的 mixed-port。

確認本機代理入口

開啟 FlClash 的設定檔或核心資訊頁，確認目前實際使用的 mixed-port。常見值是 7890，但不能直接假設所有安裝環境都使用這個連接埠。有些設定會使用 7897、10809 或其他數值。若 Clash 啟用了 mixed port，通常可以同時接受 HTTP 與 SOCKS5 請求。

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
external-controller: 127.0.0.1:9090

allow-lan: false 代表只允許本機連線，對個人電腦較安全。Gemini CLI 在同一台電腦上執行時，代理位址應使用 127.0.0.1 或 localhost，不要使用區域網路 IP。只有在確實需要讓其他裝置共用代理時，才考慮開放區域網路監聽，並搭配防火牆與存取限制。

準備訂閱與 Gemini CLI 分流設定

在匯入訂閱之前，先確認訂閱產生的是 Clash、Clash Meta 或 mihomo 格式。若設定包含 proxy-providers、rule-providers、Hysteria2、TUIC、VLESS Reality、TUN 或較新的 DNS 欄位，應優先使用支援 mihomo 的客戶端與核心。FlClash 可以在設定頁匯入訂閱 URL，也可以載入本機 YAML；匯入後不要只看節點是否出現，還要確認核心檢查沒有報錯。

Gemini CLI 相關網域可能會因版本、登入方式、API 入口或地區而變化，因此不建議只複製一份過時的網域清單。較穩妥的做法，是將需要使用的 AI 服務網域交給同一個「AI」策略組，並以官方登入或實際錯誤日誌中出現的網域作為後續核對依據。不要把所有流量一律送往代理，否則套件下載、公司內網與本機服務可能受到不必要的影響。

建立可維護的策略組

以下是示意設定。節點名稱必須替換成訂閱中實際存在的名稱；如果直接貼上不存在的節點，mihomo 會在載入或策略選擇時回報錯誤。

proxy-groups:
  - name: AI
    type: select
    proxies:
      - AUTO
      - DIRECT

  - name: AUTO
    type: url-test
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50
    proxies:
      - 節點甲
      - 節點乙

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

這段範例的重點不是固定網域，而是規則結構。proxy-groups 先建立可手動切換的 AI 策略，再用 url-test 從多個節點中挑選回應較快者。rules 由上而下比對，AI 相關規則必須放在最後的 MATCH,DIRECT 之前，否則所有尚未命中的流量會先被直接連線處理。

動手設定 Gemini CLI 的代理

完成 Clash 分流後，建議先不要急著進行完整 AI 工作。先在同一個終端機中設定代理環境變數，再用簡單的 HTTPS 請求測試本機代理是否能建立連線。以下假設 FlClash 的 mixed port 是 7890，如果你的設定不同，請替換為實際數值。

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,::1

gemini

HTTP、HTTPS 與 SOCKS5 的環境變數並非每個 CLI 都會以完全相同的優先順序讀取。通常先設定 HTTP_PROXY 與 HTTPS_PROXY 已足夠；ALL_PROXY 可作為未明確指定協定時的後備值。如果設定 ALL_PROXY 後某個工具出現異常，應先暫時移除它，避免同一請求同時受到多個代理變數影響。

NO_PROXY 用來排除本機服務。若沒有排除 localhost 與 127.0.0.1，命令列工具呼叫本機 API、開發伺服器或容器服務時，可能被錯誤送入 Clash，造成連線延遲或失敗。若需要連線公司內網，也可以將內部網域加入排除清單，但不要把整個公共網域粗略寫入 NO_PROXY。

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 中使用 $env: 設定的值只會套用到目前視窗及其啟動的子程序。關閉終端機後，這些變數通常不會保留。這種暫時設定很適合測試，因為不會影響其他應用程式。若確認設定穩定，再按照團隊的安全規範加入 PowerShell 個人設定檔；不建議將 API 金鑰直接寫入共享腳本或提交到版本控制系統。

確認代理是否真的生效

先使用不包含帳戶資料的公開 HTTPS 網址測試請求，再啟動 Gemini CLI。若 curl 能透過代理取得回應，但 Gemini CLI 仍然失敗，問題可能在登入流程、金鑰權限、CLI 支援的環境變數或特定 API 網域規則，而不是 Clash 基礎連線。

curl -I --connect-timeout 10 https://www.gstatic.com/generate_204

# 檢查目前 Shell 是否有代理變數
env | grep -i proxy

Windows PowerShell 可以使用以下命令查看變數：

Get-ChildItem Env:*proxy*

同時開啟 FlClash 的連線記錄，執行一次 Gemini CLI 請求。若日誌中完全沒有相關網域，表示 CLI 沒有讀取代理變數、流量被其他網路層處理，或目前命令並未發出請求。若日誌顯示連線命中 DIRECT，則需要檢查規則順序；若命中 AI 卻持續 timeout，應切換策略組中的節點並觀察錯誤類型。

登入憑證與開發工作流的安全做法

Gemini CLI 的登入方式可能包含瀏覽器授權、環境變數 API 金鑰或特定雲端專案憑證。不同版本的命令與支援範圍可能不同，因此應以目前安裝版本的內建說明為準。可以先執行 gemini --help，查看登入、設定與診斷相關的子命令，不要把網路文章中屬於舊版的參數直接套用到目前環境。

若採用 API 金鑰方式，建議讓金鑰只存在作業系統的環境變數、密碼管理器或 CI/CD 的密鑰儲存區。不要在命令列參數中反覆貼上金鑰，因為部分系統會將完整命令保留在歷史記錄中。使用版本控制時，也應檢查 .env、暫存檔與除錯輸出是否已加入忽略規則。

• 為不同用途建立不同金鑰，並設定合理的配額與權限。
• 不要讓 Gemini CLI 在未檢查的專案目錄中自動執行破壞性命令。
• 涉及公司程式碼時，先確認組織的資料處理政策與模型服務條款。
• 將 Git 未提交變更先備份，再讓工具提出大範圍修改建議。
• 遇到登入失敗時，先區分代理連線錯誤、OAuth 回呼錯誤與帳戶授權錯誤。

對實際開發而言，建議將工作流程分成三階段。第一階段只確認 Clash 核心、代理連接埠與 DNS 正常；第二階段在乾淨的測試專案中完成 Gemini CLI 登入並發出簡短請求；第三階段才載入大型程式庫、執行測試或授權工具修改檔案。每一階段都保留終端機錯誤與 Clash 連線日誌的時間點，發生問題時比較容易定位。

常見問題與故障排查