Gemini CLI 連不上？v2rayN 終端代理設定排查法

瀏覽器可以正常開啟 Gemini 相關服務，但 Gemini CLI 一直顯示連線失敗，通常不代表 v2rayN 節點立即失效。更常見的情況是：瀏覽器讀取了系統代理設定，而終端機中的命令列工具沒有自動繼承同一套代理；另一種情況則是終端機雖然設定了代理，DNS、路由模式或本機連接埠仍未配合。本文以 Windows 上的 v2rayN 與 Gemini CLI 為主要例子，從本機代理入口、Shell 環境變數、連線測試、DNS 解析到 Tun 模式，逐層找出瀏覽器與終端機結果不同的原因。

先分辨瀏覽器與終端機的代理路徑

v2rayN 啟動節點後，通常會在本機建立 SOCKS、HTTP 或混合代理入口。瀏覽器能正常使用，可能是因為 v2rayN 已開啟「系統代理」，也可能是瀏覽器本身已設定獨立代理。這不等於所有命令列程式都會自動使用同一入口。許多 CLI 工具只會讀取目前 Shell 的代理環境變數，或者完全不支援代理；若沒有明確指定，程式就會直接連接遠端服務。

先不要急著更換節點或重新匯入訂閱。開啟 v2rayN 主介面，確認活動伺服器確實已選取，接著查看「設定」→「參數設定」中的本機監聽連接埠。常見混合代理連接埠可能是 10808，但實際值會依版本與個人設定而不同。若只看到 SOCKS 代理，應使用 socks5://127.0.0.1:連接埠；若同一連接埠同時提供 HTTP 代理，才可使用 http://127.0.0.1:連接埠。

• 系統代理：主要影響遵循作業系統代理設定的應用程式，不保證所有 CLI 都會讀取。
• HTTP 代理：適合能讀取 HTTP 代理環境變數的工具，網址通常寫成 http://127.0.0.1:10809。
• SOCKS5 代理：適合支援 SOCKS 的工具，常見寫法是 socks5://127.0.0.1:10808。
• Tun 模式：由虛擬網路介面接收系統流量，不依賴個別程式是否支援代理環境變數。

在 v2rayN 確認核心與本機連接埠

Gemini CLI 的錯誤可能發生在「連不到本機代理」、「本機代理無法連到遠端」或「遠端回應被程式拒絕」三個不同階段。v2rayN 端要先形成可驗證的基準：活動節點可以通過真實連線延遲測試，Xray 核心正在執行，且本機監聽連接埠沒有被其他程式占用。若節點包含 VLESS + REALITY 或 xtls-rprx-vision，應在「設定」→「參數設定」→「Core 類型」選擇能支援該設定的 Xray 核心。

確認設定後，查看 v2rayN 記錄視窗。正常啟動時通常可以看到入站監聽成功、核心程序啟動及活動出站等資訊；若出現 address already in use，表示本機連接埠已被占用，CLI 即使設定完全正確也無法連入。此時可在 v2rayN 中改用其他未占用的連接埠，例如將 HTTP 代理改成 10809，再讓終端機環境變數同步使用新值。

1. 選取活動節點

   在 v2rayN 主介面選取可用節點，執行真實連線延遲測試，不要只依據 ICMP ping。

2. 確認核心類型

   進入「設定」→「參數設定」→「Core 類型」，包含 REALITY 或 Vision 的節點優先使用 Xray。

3. 記錄代理連接埠

   記下 SOCKS 與 HTTP 監聽值；沒有 HTTP 入口時，不要把 SOCKS 連接埠誤寫成 HTTP 代理。

4. 查看核心日誌

   確認沒有連接埠占用、DNS 失敗、TLS 交握錯誤或遠端連線逾時。

Windows 終端機設定代理環境變數

PowerShell 與命令提示字元設定環境變數的語法不同，而且暫時設定與永久設定的作用範圍也不同。建議先使用暫時設定驗證，關閉該終端機視窗後設定就會失效；確認 Gemini CLI 可以連線後，再決定是否寫入使用者環境。以下假設 v2rayN 的 SOCKS 入口是 127.0.0.1:10808，如果你的實際值不同，必須全部替換。

# PowerShell：只影響目前視窗
$env:HTTP_PROXY = "http://127.0.0.1:10808"
$env:HTTPS_PROXY = "http://127.0.0.1:10808"
$env:ALL_PROXY = "socks5://127.0.0.1:10808"

# 查看目前值
Get-ChildItem Env:HTTP_PROXY,Env:HTTPS_PROXY,Env:ALL_PROXY

# 清除目前視窗的設定
Remove-Item Env:HTTP_PROXY,Env:HTTPS_PROXY,Env:ALL_PROXY

如果 v2rayN 這個連接埠只提供 SOCKS5，部分程式可能不接受把 HTTP_PROXY 寫成 socks5://。遇到這種情況，應在 v2rayN 開啟可用的 HTTP 代理入口，或使用工具明確支援 SOCKS5 的寫法。不要只設定大寫變數後就假設所有程式都會讀取；某些以 Unix 網路函式庫為基礎的工具也會檢查小寫名稱，因此可在測試時一併設定。

# PowerShell：同時提供大小寫名稱，避免工具辨識差異
$proxyHttp = "http://127.0.0.1:10809"
$proxySocks = "socks5://127.0.0.1:10808"
$env:HTTP_PROXY = $proxyHttp
$env:HTTPS_PROXY = $proxyHttp
$env:ALL_PROXY = $proxySocks
$env:http_proxy = $proxyHttp
$env:https_proxy = $proxyHttp
$env:all_proxy = $proxySocks

命令提示字元使用 set 只會影響目前視窗，使用 setx 則會寫入後續新開啟的視窗。setx 不會更新目前已開啟的命令提示字元，而且把代理憑證或含特殊字元的網址寫入永久環境，可能造成安全與轉義問題。因此排查階段優先使用以下暫時設定。

set HTTP_PROXY=http://127.0.0.1:10809
set HTTPS_PROXY=http://127.0.0.1:10809
set ALL_PROXY=socks5://127.0.0.1:10808
set http_proxy=%HTTP_PROXY%
set https_proxy=%HTTPS_PROXY%
set all_proxy=%ALL_PROXY%

echo %HTTP_PROXY%
echo %HTTPS_PROXY%
echo %ALL_PROXY%

• 代理網址中的協定名稱要與入口類型相符，http:// 與 socks5:// 不能任意互換。
• 不要在同一個視窗殘留舊連接埠；例如 v2rayN 已改成 10809，環境變數仍是 10808 就會得到連線拒絕。
• 使用代理環境變數啟動 CLI 後，子程序通常會繼承設定；但已經開啟的 IDE 或整合終端機不一定會立即更新。
• 若環境變數包含使用者名稱與密碼，避免將完整指令貼到公開記錄或團隊聊天中。

用 curl 先驗證代理，再測試 Gemini CLI

在終端機直接執行 Gemini CLI 之前，應先用較容易觀察結果的 curl 測試。第一輪測試本機入口，第二輪測試代理後的 HTTPS 請求，第三輪才測試 CLI。這樣可以把問題分成「環境變數沒有生效」、「v2rayN 代理入口無法工作」及「Gemini CLI 自身參數或版本問題」。測試網址只用於確認 HTTPS 連線，不應把成功取得網頁內容誤當成 Gemini API 驗證已完成。

# PowerShell：明確指定 HTTP 代理入口
curl.exe -I -v --proxy http://127.0.0.1:10809 https://generativelanguage.googleapis.com

# 明確指定 SOCKS5 入口
curl.exe -I -v --proxy socks5h://127.0.0.1:10808 https://generativelanguage.googleapis.com

# 只依靠目前環境變數
curl.exe -I -v https://generativelanguage.googleapis.com

使用 socks5h:// 時，DNS 名稱解析會交給 SOCKS 代理端處理；這對本機 DNS 無法解析目標網域的環境特別有用。若明確指定代理可以連線，但只依靠環境變數時失敗，表示 Shell 變數名稱、格式或 CLI 所使用的網路函式庫存在差異。若兩種方式都出現 connection refused，先回到 v2rayN 檢查本機入口；若是 TLS 逾時或遠端解析失敗，再查看核心日誌與 DNS。

DNS 與路由造成的隱性失敗

有些情況下，瀏覽器透過 v2rayN 代理解析網域，Gemini CLI 卻先由本機 DNS 解析，於是兩者得到不同結果。尤其當終端機工具使用 HTTP_PROXY 而 DNS 仍由作業系統處理時，網域解析失敗可能出現在連線尚未送入代理之前。測試時可比較一般 SOCKS5 與 socks5h 的結果；後者把主機名稱解析交給代理伺服器，能幫助確認是否為本機 DNS 問題。

在 v2rayN 中檢查「設定」→「參數設定」→「DNS」及路由模式。不要在排查初期同時修改 DNS、路由、核心與節點，否則無法知道是哪一項改動產生效果。可先使用較單純的全域代理模式測試；確認 CLI 能連線後，再恢復規則分流，並為需要代理的網域檢查是否被誤判為直連。

• nslookup generativelanguage.googleapis.com 能解析，但代理請求逾時：優先查看節點出口與核心記錄。
• 本機 nslookup 失敗，但使用 socks5h:// 後成功：較接近 DNS 路徑差異，檢查遠端解析或 v2rayN DNS 設定。
• 瀏覽器可用、CLI 失敗且核心日誌沒有請求：CLI 沒有把流量送到 v2rayN，先處理環境變數或程式代理參數。
• 核心日誌看到請求但遠端逾時：CLI 已進入代理，下一步是比較節點、路由規則與遠端服務回應。

環境變數無效時改用 Tun 模式

如果確認 v2rayN 的 SOCKS 與 HTTP 入口都正常、curl 明確指定代理也能連線，但 Gemini CLI 仍完全不讀取代理環境變數，才考慮 Tun 模式。Tun 會建立虛擬網路介面，由 v2rayN 或 Xray 接收系統層級流量，再依路由規則送往代理出站。它不依賴 CLI 是否理解 HTTP_PROXY，因此適合不提供代理設定、忽略環境變數或自行建立底層連線的程式。

啟用前先保存目前設定，並關閉其他可能建立虛擬網卡的網路工具。進入 v2rayN 的 Tun 相關設定，選擇需要的虛擬網路介面與路由模式；Windows 可能要求管理員權限或安裝對應的虛擬網路驅動。啟用後重新開啟終端機，再以不帶 --proxy 的 curl 測試。若 Tun 模式生效，核心記錄應看到新的系統流量請求，而不是只有瀏覽器請求。

Tun 模式不是所有問題的萬用解法。若節點本身無法連線、遠端 DNS 失敗或核心設定錯誤，接管更多流量只會讓排錯範圍變大。啟用後若出現所有網頁都無法連線，先停用 Tun、恢復原本系統代理，再查看是否選錯虛擬介面、路由模式或 DNS。測試完成後，也要檢查是否有其他終端機仍保留舊的代理環境變數，避免同一個請求同時經過環境變數與 Tun 兩條路徑。

最後的完整排查順序

Gemini CLI 連不上時，最有效率的方式不是反覆重裝 v2rayN，而是固定由近到遠檢查。先確認程式是否使用正確的 Shell，再確認本機連接埠，接著確認代理協定與 DNS，最後才處理 CLI 的應用層錯誤。每完成一層，就用一個簡單測試記錄結果，這樣即使切換節點或重啟核心，也能保留可比較的依據。

1. 確認 v2rayN 主介面有活動節點，Xray 核心沒有立即退出。
2. 在「設定」→「參數設定」中記錄實際 SOCKS、HTTP 連接埠，不使用猜測的 10808。
3. 在目前使用的 PowerShell 或命令提示字元中查看 HTTP_PROXY、HTTPS_PROXY 與 ALL_PROXY。
4. 使用 curl.exe --proxy 明確指定入口，測試 HTTPS 連線是否能離開本機。
5. 比較 socks5:// 與 socks5h://，判斷 DNS 是在本機還是代理端解析。
6. 在 v2rayN 記錄中確認是否收到 CLI 請求；沒有請求代表 CLI 尚未使用代理。
7. 若 CLI 明確不支援代理變數，再保存設定並測試 Tun 模式。
8. 網路層恢復後，重新檢查 Gemini CLI 的登入狀態、API 金鑰、模型名稱與服務端錯誤。