Gemini CLI 在台港怎麼用?Clash Verge 連線設定教學

Gemini CLI 成為開發者討論的熱門工具後,台灣與香港使用者常會遇到幾種不同層面的問題:瀏覽器登入頁可以開啟,但終端機中的授權流程沒有回應;一般網站可以存取,Gemini CLI 卻在 API 呼叫時逾時;Clash Verge 已經啟用代理,命令列工具仍然直接連線,或因環境變數指向錯誤的本機連接埠而失敗。

這些現象不一定代表節點失效。Gemini CLI 的登入、模型 API 請求、套件下載與本機回呼,可能使用不同的網域、連線階段與代理判斷方式。本文以 Clash Verge 為例,說明如何確認核心、設定本機代理、為終端機指定環境變數,再依照連線記錄與錯誤訊息逐步定位問題。台港地區的服務可用性、帳戶資格與 Google 服務政策可能隨時間和帳戶而變化,代理設定只能改善網路路徑,不能取代服務本身的地區或帳戶限制。

先理解 Gemini CLI 會連線到哪些位置

Gemini CLI 是在終端機中執行的開發工具,實際流量不會因為安裝了 Clash Verge 就自動全部進入代理。它可能透過 Google 帳戶完成互動式登入,也可能使用 GEMINI_API_KEY 或其他環境設定進行 API 驗證。不同驗證方式會涉及不同的 HTTPS 請求;即使登入頁面能夠開啟,也不表示模型請求使用了相同的代理路徑。

第一次執行工具時,通常需要先完成登入或設定 API 金鑰。互動式登入常會在終端機顯示網址,接著使用預設瀏覽器完成授權,最後再透過瀏覽器重新導向或本機回呼把結果交回命令列程式。這裡至少有三段路徑需要分開檢查:

如果使用 API 金鑰,則不一定需要互動式瀏覽器登入,但仍要能連線到 API 服務,而且金鑰必須具備相應權限。不要把 API 金鑰直接貼到公開設定檔、Shell 歷史紀錄截圖或問題回報中。若曾經意外公開金鑰,應立即在提供金鑰的管理介面中撤銷並重新建立。

在 Clash Verge 中準備基本代理設定

開始設定前,先確認 Clash Verge 已經匯入可用的設定或訂閱,而且目前使用的是能正常啟動的核心。現代 Clash Verge 發行版通常會搭配 Mihomo 或相容核心,但不同版本的選單名稱、核心管理方式與設定欄位可能不完全相同。若用戶端顯示核心啟動失敗,應先處理 YAML 語法、訂閱內容或核心相容性,不能直接從 Gemini CLI 端反覆重試。

在 Clash Verge 中可以依序檢查以下項目:

  1. 在設定檔或 Profiles 頁面確認目前啟用的是預期設定,而不是剛下載但尚未套用的檔案。
  2. 在 Proxies 或代理頁面選擇可用的策略組,先以延遲穩定、連線成功率高的節點作為測試對象。
  3. 在設定頁面確認 HTTP、SOCKS 或 mixed-port 的實際連接埠,不要只假定一定是 7890。
  4. 先啟用系統代理,讓遵循作業系統代理設定的應用程式使用 Clash。
  5. 確認 Clash 的 Connections 或日誌頁面會出現新的連線記錄。

mixed-port 適合桌面測試,因為同一個本機連接埠通常可以接受 HTTP 與 SOCKS5 代理請求;若設定同時提供不同連接埠,則必須分辨它們的用途。下表是常見概念,實際數值應以 Clash Verge 目前顯示的生效設定為準。

項目 常見用途 終端機測試寫法
HTTP port 接收 HTTP 代理請求,也常被用來轉送 HTTPS CONNECT http://127.0.0.1:連接埠
SOCKS port 接收 SOCKS5 代理請求 socks5h://127.0.0.1:連接埠
mixed-port 以單一連接埠兼容常見 HTTP 與 SOCKS 用法 http://127.0.0.1:連接埠
TUN 由虛擬網路介面接管較廣泛的流量 通常不由代理環境變數直接指定

對一般 Gemini CLI 測試而言,建議先使用系統代理或環境變數,不要一開始就同時啟用 TUN、覆寫 DNS、流量嗅探與多套規則。功能疊加後若發生問題,會很難判斷究竟是終端機沒有使用代理、DNS 解析錯誤,還是 TUN 權限與路由衝突。

動手設定終端機代理環境變數

桌面端的「系統代理」主要影響會讀取作業系統設定的程式。許多命令列工具則會尋找 HTTP_PROXY、HTTPS_PROXY、ALL_PROXY 等環境變數。為了避免程式只辨識其中一種大小寫形式,可以在目前工作階段同時設定大小寫版本,但不要讓不同變數指向不同連接埠。

macOS 與 Linux

假設 Clash Verge 的 mixed-port 是 7890,可在 Bash 或 Zsh 中暫時設定:

export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890

gemini

這些變數只會套用到目前的 Shell 及其子程序。若希望使用 SOCKS5,並讓代理解析目標網域,可改用 socks5h:

export all_proxy=socks5h://127.0.0.1:7891
export ALL_PROXY=socks5h://127.0.0.1:7891

不要在同一個工作階段同時保留指向 7890 的 HTTPS_PROXY 與指向另一個失效連接埠的 ALL_PROXY,因為不同程式選取代理變數的優先順序不一致。若先前設定過舊代理,可以先清除再重新輸入:

unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY all_proxy ALL_PROXY

export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890

Windows CMD 與 PowerShell

在 Windows CMD 中,以下設定只作用於目前開啟的命令提示字元視窗:

set http_proxy=http://127.0.0.1:7890
set https_proxy=http://127.0.0.1:7890
set HTTP_PROXY=http://127.0.0.1:7890
set HTTPS_PROXY=http://127.0.0.1:7890

gemini

PowerShell 則使用目前程序的 Env 物件:

$Env:http_proxy = "http://127.0.0.1:7890"
$Env:https_proxy = "http://127.0.0.1:7890"
$Env:HTTP_PROXY = "http://127.0.0.1:7890"
$Env:HTTPS_PROXY = "http://127.0.0.1:7890"

gemini

如果想確認變數是否真的存在,可使用 echo %HTTPS_PROXY% 或 $Env:HTTPS_PROXY 查看。環境變數設定正確不代表 Clash 一定能連線;還需要確認本機連接埠正在監聽、目前策略組不是空的,以及連線記錄中出現相應的目標網域。

先測試代理,再執行登入與 API 呼叫

不要一開始就把登入失敗視為帳戶問題。先透過明確指定代理的命令測試「終端機到 Clash」這一段路徑。HTTP 代理可使用:

curl.exe -I -x http://127.0.0.1:7890 https://example.com

macOS 與 Linux 可以使用相同的 curl 語法。若使用 SOCKS5,建議加入 h,讓目標網域由代理端解析:

curl -I --proxy socks5h://127.0.0.1:7891 https://example.com

測試時同時觀察 Clash Verge 的 Connections 頁面。如果命令執行後出現對應的連線,而回應狀態正常,表示本機代理連接埠與目前節點大致可用。若沒有連線記錄,可能是連接埠填錯、請求沒有真正執行、Shell 仍使用其他代理,或本機有另一個代理程式接管了連線。

接著再執行 Gemini CLI 的說明命令,確認程式可以啟動:

gemini --help

若工具提供版本查看選項,也可以先確認目前安裝的版本與執行檔來源。Node.js、套件管理器與 Gemini CLI 本身的安裝問題,應與代理問題分開處理。當命令顯示找不到執行檔、權限不足或套件安裝失敗時,先檢查 PATH、執行環境與套件來源,不要直接修改 Clash 規則。

完成基本網路測試後,再開始登入。互動式登入期間,瀏覽器可能會被自動開啟。如果瀏覽器可以開啟授權頁,但終端機一直等待,應檢查本機回呼是否被防火牆或其他程序攔截;如果終端機很快顯示網路逾時,則優先查看 Clash 是否出現 Google 相關連線,以及該連線命中了哪個策略組。

為 Gemini CLI 設計分流與選擇節點

Gemini CLI 的連線不應簡單套用「所有流量全部代理」這一種方案。較穩定的做法是先確認設定中的策略組,再依實際連線記錄為需要的網域選擇合適出口。對開發工具而言,穩定的 HTTPS 連線、可靠的 DNS 解析與較低的丟包率,通常比單次延遲數字更重要。

可在 Clash Verge 的規則與連線頁面觀察以下資訊:

如果需要在本機設定中加入簡單規則,應先了解現有規則順序。Clash 規則通常由上到下比對,命中第一條規則後便交給對應策略。把自訂規則放在 MATCH 之後不會產生預期效果;而直接修改由訂閱產生的檔案,也可能在下次更新時被覆蓋。較適合長期保存的方式,是使用 Clash Verge 支援的覆寫或合併設定功能。

mode: rule

rules:
  - DOMAIN-SUFFIX,googleapis.com,PROXY
  - DOMAIN-SUFFIX,google.com,PROXY
  - DOMAIN-SUFFIX,gemini.google.com,PROXY
  - MATCH,DIRECT

以上只是說明規則結構的簡化範例,不代表所有 Gemini CLI 請求只會使用這些網域,也不建議在不了解現有訂閱規則的情況下直接複製。實際網域可能因登入方式、API 版本、模型服務與工具更新而變化。應以 Clash 連線記錄中的實際目標為準,並避免把過於寬泛的規則套用到所有 Google 服務。

選擇節點時,可先測試兩至三個候選節點,再固定到一個穩定策略組。若使用自動選擇或延遲測試,請注意測試網址只反映測試端點的結果,不一定代表 Gemini API 的實際可用性。出現 TLS 重設、頻繁切換節點或 API 回應不完整時,應優先改用穩定節點,而不是不斷增加規則數量。

依錯誤現象定位問題

Gemini CLI 的錯誤文字可能由命令列工具、Node.js 執行環境、代理核心或遠端服務回傳。排查時先記下完整錯誤類型、是否在登入前發生、Clash 是否出現連線,以及同一時間使用的代理連接埠。下表可作為第一輪判斷:

現象 優先檢查項目 處理方向
connection refused 本機代理連接埠、Clash 核心狀態 確認監聽連接埠與環境變數一致,關閉衝突程序
請求逾時 節點、DNS、規則命中與防火牆 查看連線階段,改用穩定節點並測試 DNS
登入頁成功但 CLI 等待 本機回呼、瀏覽器與終端機路徑 保留 localhost 直連,確認回呼沒有被其他程式占用
401 或 403 API 金鑰、帳戶權限、服務政策 重新確認驗證方式,不把授權錯誤當成節點故障
429 請求頻率、配額與帳戶限制 降低重試頻率,檢查配額與模型使用限制
設定解析失敗 YAML 縮排、核心支援欄位 查看核心日誌,逐段還原最近修改的設定

若 Clash Verge 中完全看不到 Gemini CLI 的連線,先在同一個終端機使用 curl 明確指定代理;若 curl 能出現連線而 Gemini CLI 沒有,問題多半在工具是否讀取環境變數、Shell 是否已重新啟動,或程式本身對代理變數的支援方式。若 curl 與 Gemini CLI 都出現連線,但只有 CLI 失敗,則要進一步檢查帳戶、API 金鑰、配額、TLS 回應與工具版本。

如果瀏覽器登入可以完成,但 API 呼叫返回 401、403 或 429,通常不應繼續更換節點。401 多與驗證資訊不正確或失效有關;403 可能涉及帳戶、權限、地區或服務政策;429 則常見於配額與請求頻率限制。這些回應需要在官方帳戶或服務管理介面確認,代理只能解決連線路徑問題。

建立可重複、容易還原的使用流程

完成測試後,建議把設定整理成一套可重複使用的流程,而不是每次啟動 Gemini CLI 都手動猜測連接埠。首先固定 Clash Verge 使用的代理連接埠,並在 Shell 設定檔中保存環境變數;如果不同專案需要不同代理,可以使用專案啟動腳本或獨立 Shell 工作階段,避免全域環境變數影響其他工具。

其次,將登入驗證與 API 金鑰分開管理。API 金鑰不要寫入 Git 儲存庫、公開的 .env 範例或終端機錄影;多人協作時使用本機環境變數與受控的秘密管理方式。若同一台電腦有多個 Shell,確認它們使用相同的代理變數和相同的 Clash 連接埠,否則可能出現 PowerShell 正常、IDE 終端機失敗的差異。

最後,保留一個最小化測試順序:

  1. 確認 Clash Verge 核心正在執行,且策略組有可用節點。
  2. 確認本機 mixed-port 或 HTTP port 正在監聽。
  3. 使用 curl 明確指定代理測試 HTTPS。
  4. 在目前 Shell 設定大小寫一致的代理環境變數。
  5. 啟動 Gemini CLI,先查看說明,再進行登入或 API 測試。
  6. 在 Clash 連線記錄中確認實際命中的網域、規則與策略組。
  7. 只有在基本代理穩定後,才考慮 TUN、DNS 覆寫或更複雜的分流。

這套順序可以把問題分成「核心沒有啟動」、「本機連接埠錯誤」、「終端機沒有使用代理」、「規則或節點不穩定」以及「帳戶或服務端限制」幾個範圍。每次只修改一個變數並重新測試,通常比一次更換用戶端、訂閱、DNS 與節點更容易找到真正原因。

下載Clash