Claude Code 搭配 Clash：終端連線設定與排錯指南

先拆開問題：終端機、Clash 與服務端是三段連線

Claude Code 在終端機中出現連線逾時、登入失敗或無法取得回應時，問題不一定出在代理節點。完整路徑通常包含三段：終端機程序是否使用代理設定、請求是否進入 Clash 核心，以及核心是否依規則選到可用的出站策略。瀏覽器能開啟網站，只能說明瀏覽器目前的連線方式可用，不能直接證明 Claude Code 也走相同路徑。

Clash 的系統代理主要提供本機 HTTP、HTTPS 或 SOCKS 代理入口，供遵循系統設定的應用程式使用；命令列程式則可能不讀取系統代理。TUN 透過虛擬網卡接管符合路由條件的 IP 流量，能涵蓋部分沒有設定代理環境變數的程式，但也會增加路由、權限、DNS 與其他 VPN 衝突等排查因素。建議先用環境變數設定終端機代理，確認基本連線後，再視需要測試 TUN。

確認 Clash 本機代理入口與出站策略

先在 Clash 用戶端確認核心已啟動，並查看目前設定的 HTTP 或 mixed 代理連接埠。常見範例是 127.0.0.1:7890，但這不是固定值；若用戶端使用其他連接埠，後續指令也必須一併修改。不要把控制介面連接埠誤當成代理連接埠：控制介面用於管理核心，不是提供終端機轉送請求的入口。

若設定中只有 SOCKS 連接埠，先確認目前 Claude Code 版本及其執行環境是否支援該代理協定。為降低相容性變數，可優先使用 Clash 的 HTTP 或 mixed 入口，並在環境變數中以 http:// 指定本機代理。mixed 入口能接收多種代理請求，但環境變數寫法仍應依應用程式支援的格式設定。

確認核心正在監聽

以下指令以連接埠 7890 為例。若你的 Clash 設定不同，請將指令中的連接埠換成實際值。Windows 可在 PowerShell 執行：

Test-NetConnection 127.0.0.1 -Port 7890

macOS 或 Linux 可使用：

nc -vz 127.0.0.1 7890

連線測試成功，表示本機有程序接受該 TCP 連線，不代表代理節點或遠端服務已經可用。若測試失敗，先回到 Clash 檢查核心狀態、代理連接埠，以及是否有另一個程式占用該連接埠。不要因為瀏覽器仍可上網，就推定終端機使用的本機入口一定有效。

檢查規則與代理群組

將 Clash 暫時切換至規則模式，確認目標請求命中預期的代理群組，並在該群組選取可用節點。可以在連線記錄中觀察請求的網域、命中規則和最終出站策略；如果連線顯示為 DIRECT，應檢查規則順序、規則是否命中，以及代理群組名稱是否與設定相符。不要為了測試而長期把所有流量改成全域代理，也不要把臨時測試結果直接當成正式分流設定。

動手設定：只讓目前終端機工作階段使用代理

最容易回復的做法，是在啟動 Claude Code 的同一個終端機工作階段設定代理環境變數。以下假設 Clash 的 HTTP 或 mixed 入口為 127.0.0.1:7890。若你的實際連接埠不同，請替換範例中的數值；代理網址指向本機，不是訂閱網址，也不是遠端節點位址。

Windows PowerShell

$env:HTTP_PROXY = "http://127.0.0.1:7890"
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
$env:NO_PROXY = "localhost,127.0.0.1,::1"
claude

這種設定只作用於目前 PowerShell 視窗及從該視窗啟動的子程序。關閉視窗後，環境變數即不再保留。若只在 Windows「設定」的系統 Proxy 頁面開啟代理，命令列工具仍可能不採用該設定，因此應以相同終端機中明確設定的環境變數進行驗證。

macOS 與 Linux 終端機

export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"
export NO_PROXY="localhost,127.0.0.1,::1"
claude

HTTPS_PROXY 的值仍可使用 http://，因為它代表透過 HTTP 代理轉送 HTTPS 請求，並不表示遠端 HTTPS 連線會被改成明文。大小寫環境變數的支援情況可能因終端機、執行環境或工具版本而異；若設定後仍未生效，可在同一個工作階段補上小寫名稱再測試：

export http_proxy="$HTTP_PROXY"
export https_proxy="$HTTPS_PROXY"
export no_proxy="$NO_PROXY"

先不要把代理變數寫進全系統設定或永久 shell 啟動檔。確認連線正常後，再決定是否將設定放入個人 shell 設定；若使用共用電腦或工作環境，應避免讓不需要代理的其他程式意外繼承設定。測試結束後，可在目前工作階段移除變數：

unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxy NO_PROXY no_proxy

PowerShell 可使用 Remove-Item Env:HTTP_PROXY,Env:HTTPS_PROXY,Env:NO_PROXY -ErrorAction SilentlyContinue 清除目前工作階段中的設定。移除變數後，新啟動的 Claude Code 不會再使用這些明確指定的入口；已執行中的程序則可能仍保留啟動時讀取的環境。

逐層驗證：確認終端機請求確實經過 Clash

設定環境變數後，先測試代理入口，不要一開始就反覆登入或重新安裝 CLI。macOS 與 Linux 可執行：

curl -I --proxy "$HTTPS_PROXY" https://api.anthropic.com/

Windows PowerShell 可使用 curl.exe，避免與 PowerShell 的別名混淆：

curl.exe -I --proxy $env:HTTPS_PROXY https://api.anthropic.com/

這項測試用來觀察本機代理連線、TLS 握手及遠端 HTTP 回應，不是登入測試。根路徑回傳非 200 狀態，不一定代表網路故障；要先看是否能連上代理、是否完成 TLS，以及 Clash 連線記錄中有沒有對應請求。若錯誤訊息是連接埠拒絕，優先檢查本機監聽；若代理連線建立後逾時，則檢查節點、規則與遠端連線。

1. 先確認本機入口：用連接埠測試指令確認 Clash 的 HTTP 或 mixed 代理正在監聽。此步失敗時，先不要排查帳號或 CLI 登入。
2. 再確認請求命中：執行 curl 測試時查看 Clash 連線記錄，確認請求進入核心，且選到預期的出站策略，而非意外直連或拒絕。
3. 最後測試 Claude Code：在設定了環境變數的同一個終端機中執行 claude --version，確認 CLI 可啟動，再執行 claude 測試登入及對話。版本指令成功只能確認 CLI 可執行，不能單獨證明服務連線或帳號驗證正常。
4. 保留測試條件：記下用戶端名稱、核心名稱與版本、代理連接埠、出站模式、作業系統及錯誤時間。回報問題時不要附上訂閱網址、存取權杖或完整認證資料。

如需確認環境變數是否存在，可在 PowerShell 執行 Get-ChildItem Env:HTTP_PROXY,Env:HTTPS_PROXY,Env:NO_PROXY；在 macOS 或 Linux 執行 env | grep -iE '^(http|https|no)_proxy='。分享輸出前先確認沒有包含帳號、密碼或其他敏感代理資訊；本機代理通常不需要在變數中加入任何認證。

依錯誤類型排查逾時、登入與分流問題

逾時、憑證與 DNS 問題

如果本機連接埠測試成功，但 curl 在建立遠端連線時逾時，查看 Clash 記錄確認實際出站節點和失敗階段。若請求根本沒有出現在記錄中，Claude Code 可能未讀取環境變數，或連線採用了其他網路路徑。若記錄顯示已選擇代理但連線失敗，先確認該節點可用、規則沒有指向錯誤群組，並檢查本機網路是否限制相關連線。

TLS 憑證錯誤不應以關閉憑證驗證作為解法。先檢查系統日期與時間、企業網路是否有合法的 HTTPS 檢查設備，以及終端機是否使用自訂憑證設定。除非清楚了解信任鏈與安全影響，否則不要加入不明 CA 憑證，也不要將憑證驗證停用後長期使用。

登入失敗與環境變數混用

命令列的代理變數只會影響從該工作階段啟動、且會讀取這些變數的程式。已開啟的 IDE、另一個終端機分頁、背景服務或桌面版應用程式，可能仍使用舊環境。請在設定變數的同一個終端機重新啟動 Claude Code，並避免同時設定互相衝突的大小寫變數、PAC 腳本及多個代理入口。

若網路測試成功但登入仍失敗，記錄 CLI 顯示的錯誤分類，確認登入流程是否需要在瀏覽器完成，以及瀏覽器是否能使用相同帳號。不要將登入網址中的一次性代碼、Cookie、存取權杖或終端機完整除錯輸出貼到公開討論區。帳號停用、方案權限或地區可用性問題，不能靠改動 Clash 規則解決。

何時再測試 TUN

如果環境變數已正確設定，代理入口與 curl 測試正常，但 Claude Code 仍未依預期連線，可先確認該執行環境是否忽略代理變數，再將 TUN 作為第二種接入方式進行比較。啟用 TUN 前，確認系統授權、路由狀態與 DNS 設定，並暫停其他 VPN 進行單一變因測試。TUN 會接管符合路由條件的 IP 流量，但不會自動修正無效帳號、錯誤規則或不可用節點；測試後若出現其他應用程式無法連線，先還原 TUN 與相關路由，再繼續排查。

整理結果時，依序記錄「本機入口是否可達、curl 是否經由預期出站、Claude Code 是否出現服務回應、登入是否通過」。這四個結果能把問題定位在本機代理、Clash 分流、遠端服務或帳號驗證，通常比反覆切換模式、重裝程式或一次修改多項設定更有效。