Claude Code 終端連線不穩？用 V2Ray 設定代理與排查方式

本文重點

瀏覽器能開啟網頁，不代表 Claude Code 的終端機請求也會經過代理。本文以 v2rayN 為例，帶你確認節點與本機 HTTP 代理入口、在終端機設定代理環境變數，並用 curl 檢查連線。若遇到登入失敗或請求逾時，也可依序分辨是代理入口、路由、DNS、TLS，還是驗證流程造成的問題。

一、先了解終端機和瀏覽器的代理設定不同

v2rayN 管理節點、啟動核心並提供本機代理入口；Claude Code 則是從終端機啟動的命令列工具。瀏覽器可能使用作業系統的系統代理，但終端機程式不一定會自動讀取相同設定。因此，即使瀏覽器已能連線，也要另外確認 Claude Code 啟動時是否取得正確的代理環境變數。

設定前先釐清三個位置：遠端節點是 v2rayN 核心連線的目標；本機代理入口是終端機連到的回送位址與連接埠；環境變數則告訴命令列程式要把 HTTP 或 HTTPS 請求送往哪個本機入口。這些不是同一個連接埠。Claude Code 的代理設定通常應指向本機 HTTP 代理，而不是直接填遠端節點的伺服器位址。

Claude Code 代理環境變數本機 HTTP 入口 v2rayN 核心目標服務

v2rayN 能連上節點，只表示核心有機會透過該節點建立連線；不保證每個應用程式都已使用本機代理。反過來說，環境變數有設定，也不代表本機連接埠真的正在監聽。排查時應先確認入口，再測試終端機，最後才檢查 Claude Code 本身。

系統代理：主要影響會遵循作業系統代理設定的應用程式，不能假設終端機程式一定會使用。
終端機代理變數：由命令列程式及其子程序讀取；只在目前終端機工作階段設定時，從其他視窗啟動的程式不會自動取得。
節點與路由：核心依 v2rayN 的節點和路由規則處理連線。若規則將目標直接連線，終端機已送至本機代理也可能沒有使用預期的遠端路徑。

二、確認 v2rayN 的本機 HTTP 代理入口

先在 v2rayN 選擇一個已確認可用的節點，並確認核心已啟動。接著前往「設定」→「參數設定」，尋找本機連接埠或入站相關欄位。不同版本的選單名稱和入口配置可能不同，請以目前介面及核心記錄為準。常見示範值包括 SOCKS 入口 10808、HTTP 入口 10809，但這些不是所有安裝環境都固定使用的預設值。

Claude Code 使用的代理位址必須符合該連接埠提供的協定。如果入口是 HTTP，就使用 http://127.0.0.1:連接埠；如果只有 SOCKS 入口，不要直接把它當 HTTP 代理填入環境變數。部分核心設定提供混合入口，可同時接受 HTTP 與 SOCKS 請求，但仍須確認實際入站類型，不要僅憑連接埠數字猜測。

終端機代理範例

代理協定: HTTP
回送位址: 127.0.0.1
示範連接埠: 10809
環境變數: HTTP_PROXY、HTTPS_PROXY

只有在 v2rayN 確實提供此 HTTP 入口時才使用範例位址；請依本機設定替換連接埠。

入口檢查重點

核心狀態: 已啟動且沒有繫結錯誤
監聽位置: 127.0.0.1 或本機回送位址
協定類型: HTTP 或明確支援 HTTP 的混合入口
路由結果: 確認目標流量符合預期規則

入口沒有監聽、連接埠被其他程式占用，或代理協定填錯，都會讓後續命令失敗。

若使用 Linux，可用 ss 檢查示範連接埠是否正在監聽；Windows 則可在 PowerShell 執行下列命令。請把 10809 換成 v2rayN 目前設定的 HTTP 連接埠。查到監聽只代表本機有程序接受連線，仍須以實際 HTTP 請求確認代理是否可用。

# Linux
ss -lntp 'sport = :10809'

# Windows PowerShell
Get-NetTCPConnection -LocalPort 10809 -State Listen |
  Select-Object LocalAddress, LocalPort, OwningProcess

三、在終端機設定代理環境變數

先用暫時設定測試，不要一開始就修改整個作業系統的代理設定。以下命令以 HTTP 入口位於 127.0.0.1:10809 為例。HTTP 代理可承載 HTTPS 連線的 CONNECT 通道，因此 HTTPS 請求的代理變數值仍以 http:// 開頭；這表示終端機連到的是本機 HTTP 代理，不表示目標網站使用未加密連線。

開啟新終端機

先確認 v2rayN 正在執行且節點已選妥，再開啟新的 PowerShell 或 shell。若環境變數是在終端機啟動後才設定，該視窗中的既有命令不會自動取得新值。
設定代理位址

PowerShell 使用下方的 $env: 寫法；Linux shell 則使用 export。將連接埠改成本機實際的 HTTP 入口，不要把遠端節點位址貼進去。
保留本機直連

將 localhost、127.0.0.1 和 ::1 加入 NO_PROXY，避免登入流程可能使用的本機回呼連線也被送往代理。若組織環境已有 NO_PROXY 清單，先保留原有必要項目。
從同一視窗啟動

設定完成後，直接在同一個終端機執行 Claude Code。從桌面捷徑、另一個終端機或不同使用者帳號啟動的程式，可能不會繼承這次設定。

# Windows PowerShell
$env:HTTP_PROXY = "http://127.0.0.1:10809"
$env:HTTPS_PROXY = $env:HTTP_PROXY
$env:NO_PROXY = "localhost,127.0.0.1,::1"

# Linux shell
export HTTP_PROXY="http://127.0.0.1:10809"
export HTTPS_PROXY="$HTTP_PROXY"
export NO_PROXY="localhost,127.0.0.1,::1"

如果只想讓目前終端機工作階段使用代理，這種設定較容易回復。PowerShell 可執行 Remove-Item Env:HTTP_PROXY, Env:HTTPS_PROXY 移除兩個代理變數；Linux shell 則可執行 unset HTTP_PROXY HTTPS_PROXY。若要讓每次開啟終端機都使用代理，再把命令加到使用者 shell 設定檔；長期設定前，先確認其他程式是否也會因此改走代理。

四、先用 curl 測試，再啟動 Claude Code

在同一個終端機以 curl 測試，可以將「本機入口或代理連線有問題」與「Claude Code 登入、設定或請求本身有問題」分開。以下命令明確指定代理，並對 API 網域發出 HTTPS 請求。伺服器可能回傳需要驗證的 HTTP 狀態；如果已完成 DNS 解析、代理連線和 TLS 握手，出現 HTTP 回應不一定代表傳輸失敗。

# Windows PowerShell：使用 curl.exe，避免 PowerShell 的 curl 別名差異
curl.exe -v --proxy $env:HTTPS_PROXY https://api.anthropic.com/

# Linux
curl -v --proxy "$HTTPS_PROXY" https://api.anthropic.com/

查看輸出時，先找是否成功連到 127.0.0.1 的指定連接埠，再檢查代理是否建立 CONNECT 通道、TLS 是否完成，以及最後是否收到 HTTP 狀態碼。不要把完整的詳細輸出公開貼上；除網路資訊外，其他命令或記錄也可能包含帳號識別資訊、工作目錄或驗證資料。

連線被拒絕：優先檢查 v2rayN 核心是否啟動、HTTP 入口連接埠是否正確，以及是否被其他程序占用。
名稱解析失敗：檢查本機 DNS、節點狀態和核心記錄；必要時比較直連與經代理的解析結果，避免只更換應用程式設定。
CONNECT 或 TLS 失敗：確認環境變數指向 HTTP 代理，而非只接受 SOCKS 的入口；再檢查系統時間、核心記錄和目標網域的路由。
收到 HTTP 回應：傳輸層已取得回應，接著再看狀態碼與 Claude Code 的登入或 API 錯誤。未授權、權限不足與網路逾時是不同問題，不宜一概當成節點故障。

判斷順序：先看 curl，再看應用程式

如果 curl 經指定代理也無法完成 TLS 連線，先處理本機入口、節點或路由；若 curl 能取得 HTTP 回應，而 Claude Code 仍失敗，請檢查 Claude Code 是否從同一個終端機啟動、是否繼承環境變數，以及登入或帳號驗證狀態。

「登入失敗」不一定等於 API 請求沒有經過代理。Claude Code 的登入可能會開啟瀏覽器，並透過本機回呼完成授權；終端機和瀏覽器是兩個不同程序，可能使用不同代理設定。若瀏覽器成功開啟授權頁，但命令列無法完成登入，應同時檢查瀏覽器是否能連線，以及回呼使用的本機位址是否仍可直連。

瀏覽器正常，Claude Code 卻逾時？

在啟動 Claude Code 的同一個終端機查看 HTTPS_PROXY，再用 curl 指定相同代理測試。若 curl 失敗，先核對 v2rayN 的 HTTP 入口和連接埠；若 curl 成功，確認工具是從該視窗啟動，並查看其錯誤記錄。

登入頁能開，授權完成後仍停住？

檢查 NO_PROXY 是否包含 localhost、127.0.0.1 和 ::1，並確認本機回呼連接埠未遭防火牆或其他程序阻擋。不要因為登入頁使用瀏覽器，就認定終端機已取得代理設定。

設定了代理變數，還是連線被拒絕？

確認變數中的協定、位址與連接埠和 v2rayN 的實際 HTTP 入站一致。若目前只有 SOCKS 入口，請在用戶端設定中確認是否另有 HTTP 或混合入口，再重新測試；不要只把網址前綴由 http 改成 socks5 就假設程式支援該代理類型。

更換節點後，錯誤仍然一樣？

先確認選取的新節點確實成為活動伺服器，並檢查核心是否重新載入。若 curl 仍連到錯誤的本機連接埠，換節點不會修正代理入口；若 curl 已取得 HTTP 回應但工具仍拒絕登入，則應分別確認帳號、授權狀態與工具顯示的錯誤內容。

也要留意環境變數的大小寫與來源。許多命令列工具會辨識大寫的 HTTP_PROXY、HTTPS_PROXY，有些也會讀取小寫版本；若系統中同時存在大小寫不同、值又不一致的變數，可能造成判斷混亂。先在目前終端機檢查實際值，再於單一視窗設定一致的值測試。公司網路若另有強制代理或憑證政策，應依管理員提供的設定操作，不要安裝來源不明的憑證或關閉 TLS 驗證。

六、整理設定並保留可重複檢查的紀錄

排查成功後，請記下作業系統、v2rayN 使用的核心、HTTP 入口協定與連接埠，以及測試時使用的命令。記錄只需保留判斷問題所需的資訊；分享前應遮蔽訂閱網址、帳號、存取權杖、公網 IP、完整工作路徑，以及可能包含敏感資料的詳細記錄。

若要把代理變數寫入 shell 設定檔，使用者每次開啟該 shell 都可能經過代理；當 v2rayN 未啟動或連接埠變更時，命令列請求便可能失敗。較穩妥的做法是先保留一組可快速設定及清除變數的命令，確認日常使用需求後再決定是否持久化。修改 v2rayN 入站、路由或核心設定前，先記下原值，並一次只調整一項，方便比較結果。

完成測試後，可在同一終端機重新執行 curl，並從該視窗啟動 Claude Code 做一次實際請求。若本機測試成功但服務回應授權或帳號錯誤，應依該錯誤處理驗證；若出現連線拒絕、解析或 TLS 錯誤，則回到入口、節點和路由檢查。更多 v2rayN 操作可參閱使用指南，也可依目前版本的介面核對設定名稱。