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 金鑰。互動式登入常會在終端機顯示網址,接著使用預設瀏覽器完成授權,最後再透過瀏覽器重新導向或本機回呼把結果交回命令列程式。這裡至少有三段路徑需要分開檢查:
- 終端機到 Google 授權服務:由 Gemini CLI 發起,是否讀取目前 Shell 的代理環境變數。
- 瀏覽器到授權頁面:可能使用 Clash 系統代理、瀏覽器獨立代理,或完全不使用代理。
- Gemini CLI 到模型 API:登入完成後的實際 API 請求,可能與登入時使用不同網域。
如果使用 API 金鑰,則不一定需要互動式瀏覽器登入,但仍要能連線到 API 服務,而且金鑰必須具備相應權限。不要把 API 金鑰直接貼到公開設定檔、Shell 歷史紀錄截圖或問題回報中。若曾經意外公開金鑰,應立即在提供金鑰的管理介面中撤銷並重新建立。
在 Clash Verge 中準備基本代理設定
開始設定前,先確認 Clash Verge 已經匯入可用的設定或訂閱,而且目前使用的是能正常啟動的核心。現代 Clash Verge 發行版通常會搭配 Mihomo 或相容核心,但不同版本的選單名稱、核心管理方式與設定欄位可能不完全相同。若用戶端顯示核心啟動失敗,應先處理 YAML 語法、訂閱內容或核心相容性,不能直接從 Gemini CLI 端反覆重試。
在 Clash Verge 中可以依序檢查以下項目:
- 在設定檔或 Profiles 頁面確認目前啟用的是預期設定,而不是剛下載但尚未套用的檔案。
- 在 Proxies 或代理頁面選擇可用的策略組,先以延遲穩定、連線成功率高的節點作為測試對象。
- 在設定頁面確認 HTTP、SOCKS 或 mixed-port 的實際連接埠,不要只假定一定是
7890。 - 先啟用系統代理,讓遵循作業系統代理設定的應用程式使用 Clash。
- 確認 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 的規則與連線頁面觀察以下資訊:
- 目標網域:確認請求是否確實屬於 Google 或 Gemini 相關服務,而不是被錯誤導向其他位址。
- 命中規則:查看是網域規則、規則集、GEO 類規則,還是最後的
MATCH命中。 - 策略組:確認連線交給預期的代理組,而不是意外使用
DIRECT或失效節點。 - 解析結果:若連線在建立前就逾時,檢查 DNS 模式與上游 DNS 是否可用。
- 連線時間:區分 DNS、TCP、TLS 或代理伺服器握手階段的延遲。
如果需要在本機設定中加入簡單規則,應先了解現有規則順序。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 終端機失敗的差異。
最後,保留一個最小化測試順序:
- 確認 Clash Verge 核心正在執行,且策略組有可用節點。
- 確認本機 mixed-port 或 HTTP port 正在監聽。
- 使用
curl明確指定代理測試 HTTPS。 - 在目前 Shell 設定大小寫一致的代理環境變數。
- 啟動 Gemini CLI,先查看說明,再進行登入或 API 測試。
- 在 Clash 連線記錄中確認實際命中的網域、規則與策略組。
- 只有在基本代理穩定後,才考慮 TUN、DNS 覆寫或更複雜的分流。
這套順序可以把問題分成「核心沒有啟動」、「本機連接埠錯誤」、「終端機沒有使用代理」、「規則或節點不穩定」以及「帳戶或服務端限制」幾個範圍。每次只修改一個變數並重新測試,通常比一次更換用戶端、訂閱、DNS 與節點更容易找到真正原因。