Gemini CLI 國內怎麼用？Clash 訪問設定指南

Gemini CLI 與 Clash 為什麼需要一起設定

Gemini CLI 是在終端機中使用 Gemini 模型的命令列工具，適合程式碼閱讀、專案分析、指令輔助與快速產生檔案。它和瀏覽器中的 Gemini 網頁版不同，不是透過圖形化頁面完成請求，而是由本機的 Node.js 程式直接向相關服務建立 HTTPS 連線。因此，即使瀏覽器已經可以正常開啟外部網站，Gemini CLI 仍可能因為沒有取得代理設定而出現登入失敗、API 無回應或連線逾時。

Clash Verge 在這裡扮演的是本機代理入口。它會在電腦上監聽一個或多個連接埠，接收終端機、瀏覽器或其他應用程式的請求，再依照目前的模式、節點和規則決定流量如何轉送。簡單來說，Gemini CLI 負責發出請求，Clash 負責提供可用的網路路徑；兩邊只要有一邊設定不完整，最終就會表現為工具無法使用。

需要先釐清的是，Clash 本身不提供 Gemini 帳號、API 金鑰或代理節點。您仍需依照服務條款準備合法可用的帳戶與網路服務，並確認所在地區、帳戶權限及 API 配額符合使用要求。本文只討論本機代理與命令列環境的設定，不會提供或分享任何帳戶憑證。

開始前的環境檢查

在匯入訂閱之前，先確認問題究竟出在 Gemini CLI、作業系統、網路，還是 Clash。這一步看似簡單，卻能避免一開始就修改大量 YAML 設定。若 Node.js 版本過舊、系統時間錯誤，或終端機本身沒有權限存取網路，後續即使代理正常也可能出現相同錯誤。

可先在終端機執行 node -v 和 npm -v，確認版本指令能回傳結果。接著執行 Gemini CLI 提供的版本檢查指令，確認命令名稱已加入系統 PATH。如果指令顯示「找不到命令」，這不是 Clash 代理問題，而是工具尚未安裝完成或環境變數尚未重新載入。若所有基本指令都正常，再開始檢查網路。

另外，請暫時關閉其他 VPN、加速器或系統級代理工具。多個工具同時接管 DNS、TUN 或系統代理時，容易形成端口衝突、代理迴圈和錯誤的路由判斷。排查期間保持環境單純，完成設定後再逐一恢復其他網路軟體，會更容易找到真正的衝突來源。

第一步：安裝並開啟 Clash Verge

開啟 Clash Verge 後，先不要急著測試 Gemini CLI。請先在設定頁確認核心已經啟動，而且介面能顯示目前的代理端口。不同版本的 Clash Verge Rev 在文字和選單位置上可能略有差異，但通常可以在 General、Settings 或常規設定中找到系統代理、混合埠、允許區域網路和開機啟動等選項。

1. 啟動 Clash Verge，等待核心狀態顯示為運行中或已啟動。
2. 在 General 或設定頁記下 Mixed Port、HTTP Port 或 SOCKS Port。
3. 確認端口沒有被其他程式佔用；若無法啟動，可先更換為未使用的本機端口。
4. 開啟系統代理前，先確認目前設定檔已成功載入，避免系統流量被送到空的代理入口。

Clash Verge 的系統代理開關只會影響會讀取作業系統代理設定的程式。瀏覽器大多能自動配合，但命令列工具、Git、Docker 或某些 Node.js 套件不一定會跟隨。因此，「系統代理已開啟」不代表 Gemini CLI 必然會走 Clash，後面仍要單獨設定終端機環境變數。

第二步：匯入訂閱並選擇可用節點

在 Clash Verge 的 Profiles 或設定檔頁面，貼上服務商提供的 Clash 訂閱網址。請確認複製的是完整連結，不要把前後的空白、引號或說明文字一併貼入。訂閱網址通常以 https:// 開頭，但實際格式會因服務商而異；如果服務商提供多種格式，應選擇明確標示為 Clash、Clash Meta 或 YAML 的版本。

1. 開啟 Profiles 頁面，找到新增訂閱或 URL 輸入欄位。
2. 貼上訂閱連結，點選下載、匯入或更新。
3. 等待設定檔完成解析，確認畫面沒有 YAML 語法或下載錯誤。
4. 點選剛匯入的設定檔，使其成為目前啟用的配置。
5. 前往 Proxies 頁面，選擇一個延遲合理且狀態正常的節點或策略組。

如果訂閱下載失敗，先用瀏覽器測試該網址是否能開啟，而不是立即修改核心設定。瀏覽器也無法取得內容，代表訂閱網址過期、網域無法解析、服務商限制了來源網路，或目前網路無法連到訂閱伺服器。若瀏覽器能下載設定檔，但 Clash 顯示解析錯誤，則要檢查格式是否真的適用於目前核心，並確認檔案沒有被登入頁面或錯誤訊息取代。

第三步：設定 Rule、Global 與分流規則

Clash 常見的代理模式包括 Rule、Global 和 Direct。Rule 模式會依照設定檔中的規則，把不同網域分配到 DIRECT、代理策略組或 REJECT；Global 模式則通常讓大部分流量經過同一個代理策略；Direct 會嘗試直接連線。對 Gemini CLI 而言，模式的選擇會直接影響 API 網域是否走到正確的出口。

日常使用建議先採用 Rule 模式，因為它能讓本地服務維持直連，同時把需要代理的網域送到指定策略組。但初次排查時，可以短時間切換到 Global，手動選定一個已知可用節點。若 Global 模式下 Gemini CLI 可以正常回應，而 Rule 模式不行，通常表示節點本身沒有問題，應該回頭檢查規則順序、策略組指向或網域匹配。

規則通常由上而下匹配，第一條命中的規則會決定後續路由。過於寬泛的 DOMAIN-SUFFIX、錯誤的 GEOIP 判斷、訂閱中的廣告攔截規則，都可能在真正的代理規則之前先命中。排查時請開啟 Clash Logs 或 Connections，觀察 Gemini CLI 發出的網域、命中的規則名稱，以及最終使用的是 DIRECT、REJECT 還是代理策略。

模式	適合用途	排查意義
Rule	日常分流與本地網站直連	可驗證規則是否正確命中
Global	讓大部分流量使用同一節點	快速區分節點問題與規則問題
Direct	暫時停用代理	確認直連是否本來就能滿足需求

不要在沒有備份的情況下大幅修改訂閱原始檔案。許多設定檔會定期更新，手動改動可能在下一次更新時被覆蓋。若需要固定某些網域的策略，優先使用 Clash Verge 提供的覆寫、Mixin 或本地規則功能，並保留原始設定檔作為回復基準。

第四步：讓終端機使用 Clash 代理

這是 Gemini CLI 設定中最容易被忽略的部分。系統代理開關只代表作業系統提供了一個代理設定，命令列程式是否讀取則取決於它自己的網路函式庫。最常見的作法是在目前終端機工作階段設定環境變數，讓支援標準代理變數的 Node.js 工具知道應該連到哪個本機端口。

如果 Clash Verge 的混合埠是 7890，可以先使用以下形式測試。端口請替換成您介面中實際顯示的數字：

# macOS / Linux / Git Bash
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

# 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"

HTTP_PROXY 和 HTTPS_PROXY 通常適合 HTTP 代理埠；ALL_PROXY 則可提供更通用的代理提示，但不同工具對它的支援程度不一。若您使用的是 SOCKS 專用埠，請使用 socks5://；如果填錯協定，可能會看到連線被重置、TLS 握手失敗或請求持續等待。

1. 先設定環境變數，再用 echo 或 PowerShell 的變數查詢確認內容存在。
2. 使用 curl 連線一個您有權測試的 HTTPS 網站，觀察 Clash Connections 是否出現新連線。
3. 確認 Clash 日誌中的請求不是 DIRECT 或 REJECT，並且策略組有選定節點。
4. 在同一個終端機視窗中啟動 Gemini CLI，避免換到沒有繼承環境變數的新工作階段。

有些 Node.js 工具不會自動讀取代理變數，或由底層套件自行管理 TLS 與 DNS。此時即使 curl 能正常通過 Clash，Gemini CLI 仍可能失敗。請先查看工具的官方說明，確認是否支援 HTTP_PROXY、HTTPS_PROXY，或是否需要額外的 Node.js 代理選項。不要為了繞過錯誤而隨意停用 TLS 憑證驗證，這會降低連線安全性。

第五步：用 Logs 與連線測試定位問題

排錯時應該把整個流程拆成幾層，而不是只重複執行 Gemini CLI。第一層是本機端口，第二層是代理節點，第三層是 DNS 和 TLS，第四層才是 Gemini CLI 的登入或 API 請求。每一層都能正常，問題才有可能出在帳戶權限、配額或工具版本。

如果 Clash 完全沒有連線紀錄，優先檢查終端機是否真的讀取代理變數，以及 Gemini CLI 是否使用獨立的網路設定。如果有紀錄但一直逾時，先更換節點，再檢查 DNS 和防火牆。如果請求很快被拒絕，則要查看策略組是否選到了 REJECT、訂閱規則是否誤攔截，或帳戶端點是否需要不同的存取方式。

在 Windows 上，防毒軟體、企業安全代理和防火牆可能攔截 Node.js 的網路行為；在 macOS 上，系統可能跳出網路或檔案權限提示；在 Linux 上，環境變數可能只存在於某個 Shell，而不會傳給圖形化啟動器。不同平台的表現雖然不同，但核心原則一致：先確認請求有沒有離開應用程式，再確認是否進入 Clash，最後才判斷遠端服務是否回應。

常見錯誤與處理方式

出現 timeout 或 ETIMEDOUT

逾時通常表示請求沒有在預期時間內完成，可能是節點品質不穩、代理端口設定錯誤、DNS 無法解析，或遠端服務沒有回應。先觀察 Clash 是否收到請求，再更換節點。若所有節點都逾時，檢查終端機是否使用了錯誤的 HTTP 或 SOCKS 協定，並確認其他 VPN 沒有佔用本機端口。

出現 TLS、certificate 或 handshake 錯誤

TLS 錯誤可能與系統時間錯誤、憑證鏈不完整、企業網路攔截或節點轉送異常有關。先確認電腦時間和時區正確，再測試其他節點與其他網路。不要把「忽略憑證錯誤」當成永久解法，因為這會讓中間人攻擊更難被發現。

登入成功但 API 仍然拒絕

若網路連線已成功，而服務回傳授權、配額或區域相關訊息，問題可能已經不在 Clash。請檢查 Gemini CLI 使用的帳戶、API 金鑰、模型權限和服務條款，也要確認沒有在環境變數中殘留舊的金鑰或錯誤端點。Clash 只能協助流量到達目標服務，不能替代帳戶驗證。

常見問題

Gemini 網頁版能開，為什麼 Gemini CLI 不行？

瀏覽器通常會自動使用系統代理或瀏覽器內建設定，但命令列程式不一定會讀取相同設定。請確認 HTTP_PROXY、HTTPS_PROXY 或 ALL_PROXY 已在啟動 Gemini CLI 的同一個終端機工作階段中設定，並在 Clash Connections 中確認有相應請求。

應該一直使用 Global 模式嗎？

不建議把 Global 當作唯一方案。它適合用來做短時間的二分法測試，但長期使用會讓不需要代理的本地服務也繞路，增加延遲和流量消耗。完成排查後，建議回到 Rule 模式，並為需要的服務設定清楚、可維護的分流規則。

如何知道代理端口填對了？

以 Clash Verge 設定頁顯示的端口為準，不要直接套用網路文章中的數字。若本機端口可用，終端機測試時應能在 Clash Connections 看到請求；若完全沒有紀錄，通常代表端口、協定、環境變數或應用程式代理支援其中一項不正確。

延伸閱讀

如果您在設定過程中遇到更廣泛的網路問題，可以閱讀《Clash 新手入門完整指南》了解訂閱、節點和系統代理的基本概念；若出現「已連線但無法上網」，可參考《Clash 已連線卻無法上網：DNS 與 fake-ip 排查》；需要在 Windows 上重新安裝用戶端時，則可查看《Clash Windows 安裝與設定教學》。

總結

相較於部分只針對瀏覽器設計的代理工具，單純開啟瀏覽器代理並不能保證命令列程式、開發工具和 Node.js 應用都會跟隨，遇到 API 請求時往往還要另外處理端口、環境變數和分流規則。Clash 的優勢在於代理入口清楚、規則分流彈性高，並能透過日誌與連線面板觀察實際流量，讓問題不再只停留在「能不能開網頁」這個模糊層面。

如果您希望用一套更容易檢查和調整的方式管理 Gemini CLI 網路環境，不妨先從 免費下載 Clash，立即體驗 開始，再依本文步驟完成 Clash Verge 與終端機設定。