入門指南 預計閱讀 10 分鐘

Claude Code 連線不穩？用 Clash Verge 設定終端機代理

使用 Claude Code 寫程式時，若終端機出現連線逾時、登入失敗或無法回應，可先檢查網路與代理環境變數。本文示範以 Clash Verge 開啟系統代理、設定終端機的 HTTP(S)_PROXY，並用規則模式挑選合適路線，也整理常見錯誤的排查方式，讓 AI 程式開發的連線設定更容易上手。

先分清 Claude Code 與系統代理

Claude Code 在終端機出現連線逾時、登入失敗或無法取得回應時，問題不一定出在帳戶，也不一定是 Clash Verge 的節點故障。先確認請求有沒有進入代理核心，再分辨是本機代理連接埠、出口節點、網域解析，還是應用程式認證環節出問題，通常比直接重裝有效。

要特別留意：Clash Verge 開啟「系統代理」，不代表每個終端機程式都會自動使用代理。系統代理主要提供給遵循作業系統代理設定的應用程式；命令列工具則可能需要自行讀取 HTTP_PROXY、HTTPS_PROXY 或 ALL_PROXY 等環境變數。Claude Code 若由終端機啟動，通常要檢查啟動它的那個 Shell 是否取得了正確的代理環境變數。

  • 瀏覽器能連線、Claude Code 逾時：優先檢查終端機環境變數和實際監聽的代理連接埠。
  • Claude Code 啟動後沒有相關連線記錄：檢查環境變數拼字、啟動方式，以及是否在不同的終端機或容器內執行。
  • 連線記錄已選取代理出口，仍然失敗：再查看節點、DNS、遠端服務回應和帳戶狀態。

確認 Clash Verge 的代理連接埠

先開啟 Clash Verge，確認目前設定已載入、核心正在執行，而且選取的策略組有可用出口。接著查看「設定」中的連接埠設定，找到混合代理連接埠，並記下實際數值。介面名稱和預設值會因 Clash Verge 版本、設定檔或使用的核心而不同，不要直接假設連接埠一定是 7890。

以下命令以 7897 示範，這只是範例。請將命令中的連接埠換成自己介面顯示的混合代理連接埠。常見的混合連接埠同時接受 HTTP 代理與 SOCKS 代理連線；Claude Code 使用一般 HTTP(S) 代理環境變數時，可以先用 http://127.0.0.1:連接埠 格式測試。

curl.exe -v --connect-timeout 10 --max-time 20 --proxy http://127.0.0.1:7897 https://example.com/

這條命令會明確指定本機代理，並設下連線與整體請求時間上限。若回應顯示無法連線到 127.0.0.1:7897，先檢查連接埠是否填對、核心是否正在執行，以及混合代理是否已啟用；如果能連上但目標請求失敗，再檢查策略組和節點。example.com 僅是示範網址，實際測試時可換成自己能正常存取的 HTTPS 網址。

接著在 Clash Verge 的「代理」頁面確認目前選取的策略組出口，不要只看群組名稱。群組可能選到 DIRECT、故障節點或其他子群組；需要代理的連線，應確認最後選到的是可用代理節點。打開「記錄」頁面後再啟動一次 Claude Code，查看是否出現相應的網域、連線結果與命中規則。若要暫時排查，保持規則模式並確認規則將相關請求送往預期策略組；切換全域模式只適合短暫比對，不宜把它當成所有問題的固定解法。

  • 核心沒有啟動時，環境變數即使寫得正確，也只會連到一個沒有服務監聽的本機連接埠。
  • 若記錄中顯示的是另一個連接埠，請回頭確認終端機使用的數值和目前設定是否一致。
  • 初次測試時不要同時改 DNS、規則、TUN 和訂閱設定；一次只調整一個條件，較容易判斷是哪項變更有效。

在啟動 Claude Code 的終端機設定代理

環境變數只會影響讀取它的程序及其子程序。先在終端機設定變數，再從同一個視窗啟動 Claude Code；若先開啟應用程式，之後才修改另一個視窗的變數，原本執行中的程序不會自動取得新設定。

Windows PowerShell

在 PowerShell 輸入以下命令，請將 7897 替換成 Clash Verge 實際使用的混合代理連接埠：

$env:HTTP_PROXY = "http://127.0.0.1:7897"
$env:HTTPS_PROXY = "http://127.0.0.1:7897"
$env:ALL_PROXY = "http://127.0.0.1:7897"
claude

這些設定只在目前的 PowerShell 工作階段有效。關閉視窗後，變數會消失；這種作法適合先確認代理是否能解決連線問題。使用 Windows PowerShell 時，測試命令建議明確執行 curl.exe，因為某些 PowerShell 版本會把 curl 當成其他命令的別名。

若想確認變數是否存在，可在同一個視窗執行：

$env:HTTP_PROXY
$env:HTTPS_PROXY
$env:ALL_PROXY

確認測試完成後，如需回復目前視窗的環境，可執行：

Remove-Item Env:HTTP_PROXY -ErrorAction SilentlyContinue
Remove-Item Env:HTTPS_PROXY -ErrorAction SilentlyContinue
Remove-Item Env:ALL_PROXY -ErrorAction SilentlyContinue

macOS 與 Linux 終端機

在 zsh、bash 等 Shell 中，可在同一個視窗設定變數並啟動程式：

export HTTP_PROXY="http://127.0.0.1:7897"
export HTTPS_PROXY="http://127.0.0.1:7897"
export ALL_PROXY="http://127.0.0.1:7897"
claude

如果希望每次開啟該 Shell 都自動使用代理，可將設定加入目前使用的 Shell 啟動檔，例如 zsh 常見的 ~/.zshrc 或 bash 常見的 ~/.bashrc。但先用單次工作階段測試較安全：永久設定可能讓其他命令列工具也經由代理，甚至造成日後關閉 Clash Verge 時，其他工具仍試圖連到本機代理而失敗。完成測試後，若不再需要，可用 unset HTTP_PROXY HTTPS_PROXY ALL_PROXY 清除目前工作階段中的變數。

環境變數名稱的大小寫支援會因工具和執行環境而異。若使用上述大寫名稱仍沒有改善，可另外測試小寫形式 http_proxy、https_proxy；不要把值寫成不存在的範例連接埠。設定同時存在大小寫版本時，也要確認它們指向相同的代理，避免程式讀取到舊值。

用一次測試確認請求走哪條路

建議先確認代理連接埠，再檢查環境變數，最後才重新執行 Claude Code。以下順序可以把用戶端設定問題與代理出口問題分開：

  1. 在 Clash Verge 確認核心運作中、混合代理連接埠正確，而且策略組選取了預期出口。
  2. 在啟動 Claude Code 的同一個終端機設定 HTTP_PROXY 和 HTTPS_PROXY，再用明確指定代理的 curl 命令測試 HTTPS 連線。
  3. 查看 Clash Verge 記錄，確認測試請求確實出現在核心中，且所選出口符合預期。
  4. 在同一終端機啟動 Claude Code，再觀察對應時間的記錄及終端機錯誤訊息。

也可以用 curl 檢查不經代理時的結果作為比較，但要小心命令是否繼承環境變數。若環境中已有代理變數，可用 --noproxy "*" 明確要求這次請求不走代理，再與指定代理的結果比較。比較的目的是縮小問題範圍，不代表任何一種路徑必須成功。

測試結果優先判斷下一步
明確指定代理時無法連上本機位址核心未監聽、連接埠錯誤或代理模式未啟用核對 Clash Verge 的混合代理設定與執行狀態
本機代理可連，但測試網址逾時出口節點、規則選擇、DNS 或目標網路路徑查看核心記錄，確認實際命中規則及代理出口
測試網址可用，Claude Code 仍失敗程式是否取得環境變數、登入狀態或服務端回應從設定變數的同一個終端機重新啟動並記錄錯誤
記錄中完全沒有相應請求請求沒有進入目前這個核心檢查啟動終端機、容器、遠端工作階段及變數設定

終端機若在 WSL、容器、SSH 遠端工作階段或虛擬機中執行，127.0.0.1 指的是該執行環境自己的迴路位址，不一定是 Windows 或 macOS 主機上的 Clash Verge。這時即使主機端代理正常，終端機內的請求也可能連不到主機代理。先辨認 Claude Code 實際執行在哪個環境，再確認該環境可以使用的主機位址與網路設定；不要直接把主機端口令複製過去就假設可通。

避免幾個常見設定誤區

系統代理與終端機代理不是同一項設定

Clash Verge 的系統代理開關方便瀏覽器等遵循系統設定的應用程式使用代理，卻不能保證所有命令列程式都讀取相同設定。反過來說，為 Claude Code 設定環境變數，也不代表瀏覽器或其他程式會自動使用代理。兩者可以同時設定，但排查時先用明確的終端機環境變數，能更直接確認命令列程式使用的路徑。

代理協定與連接埠必須相符

HTTPS_PROXY 中的 HTTPS 指的是要代理的目標請求類型，不代表本機代理網址一定要寫成 https://。常見本機 HTTP 代理的寫法是 http://127.0.0.1:連接埠，它可透過 HTTP CONNECT 建立通往 HTTPS 網站的通道。若把連接埠、代理協定或核心監聽方式配錯，可能會看到連線拒絕、TLS 錯誤或逾時。請以 Clash Verge 的實際代理設定為準，不要在不確定時反覆更換協定。

檢查例外清單與代理憑證

若設定了 NO_PROXY 或 no_proxy，其中列出的主機可能會略過代理。排查時可暫時檢查該值，確認要測試的目標沒有被錯誤排除；不要為了讓某個測試通過，就長期移除所有必要的區域網路例外。一般指向本機 Clash Verge 的代理不需要在 URL 中附上使用者名稱或密碼；若代理服務確實要求認證，請依管理者提供的安全方式處理，避免將密碼寫入共用指令、Shell 記錄或截圖。

Claude Code 的登入失敗也不一定是代理問題。若 HTTPS 測試成功、核心記錄顯示連線已送出，但程式仍回報認證或帳戶錯誤，請依錯誤內容檢查登入狀態、帳戶權限、服務可用性及官方支援的使用條件。代理只能協助建立網路連線，不能修復帳戶憑證、授權狀態或遠端服務故障。

常見問題

開啟 Clash Verge 系統代理後，為什麼 Claude Code 還是逾時？

因為終端機程式未必會讀取作業系統的系統代理設定。請在啟動 Claude Code 的同一個終端機設定 HTTP_PROXY 與 HTTPS_PROXY，並確認變數中的連接埠和 Clash Verge 混合代理連接埠相同。接著用明確指定代理的 HTTPS 請求測試，再查看核心記錄是否收到連線。

應該使用哪個代理連接埠？

使用 Clash Verge 設定中實際顯示的混合代理連接埠，不要只依照網路文章中的預設數字設定。若核心只提供不同類型的監聽埠，請確認該埠接受的協定，再選擇相符的代理 URL 格式。修改連接埠後，也要同步更新終端機環境變數。

設定終端機代理一定要啟用 TUN 嗎？

不一定。本文使用代理環境變數，讓 Claude Code 明確連到 Clash Verge 的本機代理服務；這種做法通常不需要只為此用途啟用 TUN。TUN 主要用來接管符合其路由設定的系統網路流量，涉及權限、路由和 DNS 等更多條件。若目標只是讓命令列程式使用代理，可先測試環境變數方案。

測試網址可連線，為什麼 Claude Code 仍不能登入？

測試只證明該網址、該次請求及所選代理路徑可用，不代表所有目標服務都正常。請確認 Claude Code 是從設定變數的同一個終端機啟動，查看是否有 NO_PROXY 排除項目，並對照核心記錄中的實際目標與出口。如果錯誤明確指向帳戶、授權或服務端回應，應依相應提示處理，而不是持續更換代理連接埠。

下載用戶端