Claude Code 受到開發者關注後,不少新手遇到的第一個問題不是指令本身,而是終端機無法穩定連線。瀏覽器可以正常開啟網頁,不代表命令列工具也會自動使用 Clash 代理,因為終端程式通常讀取的是 HTTP_PROXY、HTTPS_PROXY 或 ALL_PROXY 環境變數。本文以 Clash Verge 為例,說明如何確認本機代理連接埠、匯入訂閱、選擇可用節點,再為 macOS、Linux 與 Windows PowerShell 設定終端代理,並整理 Claude Code 安裝、登入與日常使用時常見的分流問題。
本文只介紹本機代理與終端環境設定,不提供帳號註冊、付款或服務區域限制的規避方案。使用 Claude Code 前,請確認帳號、服務和所在地區符合相關服務條款,並妥善保護 API 金鑰與登入資訊。
先理解 Clash Verge 與終端代理的關係
Clash Verge 是桌面端用戶端,負責啟動 mihomo 內核、載入配置、建立代理連接埠並按照規則分流。Claude Code 則是在終端機中執行的命令列工具,它不一定會讀取作業系統的「系統代理」開關。即使 Clash Verge 顯示系統代理已開啟,終端中的 curl、npm、git 或 Claude Code 仍可能直接連線。
兩者之間通常需要透過以下其中一種方式銜接:
- 環境變數代理:在目前 Shell 工作階段設定 HTTP 或 SOCKS5 代理位址,由支援這些變數的程式自行讀取。
- TUN 模式:由 mihomo 建立虛擬網路介面,在系統網路層接管流量,不依賴每個命令列工具是否支援代理環境變數。
- 工具獨立設定:某些套件管理器、Git 或容器工具有自己的代理設定,需要另外指定,不能只依賴 Clash Verge 的系統代理。
對 Claude Code 這類需要連線到遠端服務的終端工具而言,最容易控制和排查的是環境變數方式。TUN 模式則適合需要讓多個不支援代理變數的程式統一走代理,或需要處理登入瀏覽器、子程序和其他系統流量的情境。
匯入訂閱並確認代理連接埠
首次使用 Clash Verge 時,先不要急著安裝 Claude Code。應先確認配置能正常載入、至少有一個節點可以連線,以及本機代理連接埠正在監聽。訂閱連結通常包含帳號識別資訊,建議只在可信的 Clash Verge 設定頁中使用,不要貼到公開論壇、截圖或無關的線上工具。
- 開啟 Clash Verge,進入配置或 Profiles 頁面,貼上服務商提供的訂閱連結。
- 下載配置後,確認列表中出現新的配置檔,並將它設為目前啟用的配置。
- 進入代理頁面,選擇一個延遲較低且狀態正常的節點或代理群組。
- 在設定頁查看 HTTP、SOCKS 或 Mixed 連接埠。若使用環境變數,通常優先選擇 HTTP 代理連接埠;若使用 SOCKS5,則要使用對應的 SOCKS 連接埠。
- 確認 Clash Verge 內核正在執行,並查看日誌是否出現配置解析錯誤、端口被佔用或節點握手失敗。
不同版本的 Clash Verge 介面名稱可能略有差異,連接埠也可能由使用者自行修改,因此不要直接照抄網路文章中的固定數字。以下只示範常見的本機位址與連接埠格式,實際數值應以 Clash Verge 設定頁顯示的內容為準:
HTTP 代理: 127.0.0.1:7890
SOCKS5 代理: 127.0.0.1:7891
Mixed 代理: 127.0.0.1:7890如果 Clash Verge 使用的是 Mixed 連接埠,它通常可以同時處理 HTTP 代理與 SOCKS5 請求,但仍應確認目前版本與配置的具體行為。測試時最好先用 HTTP 代理格式驗證,因為不少命令列工具對 HTTP CONNECT 的支援較一致。
訂閱更新成功只代表配置檔能被下載,不代表每個節點都可用。先選定單一節點,再用最小化的 curl 命令測試,能避免把訂閱問題、節點問題和終端環境問題混在一起。
為終端機設定 HTTP 與 HTTPS 代理
在 macOS 或 Linux 上,可以先於目前終端機暫時設定環境變數。這種方式只影響當前 Shell 及其後啟動的子程序,關閉終端視窗後通常會失效,適合初次測試:
export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"
export ALL_PROXY="socks5://127.0.0.1:7891"
export http_proxy="$HTTP_PROXY"
export https_proxy="$HTTPS_PROXY"
export all_proxy="$ALL_PROXY"同時設定大小寫版本是為了提高相容性。不同工具的實作不完全一致,有些只讀取小寫變數,有些會優先讀取大寫變數。若你使用的是 Bash,可以把設定寫入 ~/.bashrc 或 ~/.bash_profile;若使用 Zsh,通常寫入 ~/.zshrc。修改後重新載入設定:
source ~/.zshrc
# 或
source ~/.bashrcWindows PowerShell 的暫時設定方式如下:
$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"
$env:ALL_PROXY="socks5://127.0.0.1:7891"
$env:http_proxy=$env:HTTP_PROXY
$env:https_proxy=$env:HTTPS_PROXY
$env:all_proxy=$env:ALL_PROXY設定完成後,先檢查變數是否真的存在:
echo $HTTP_PROXY
echo $HTTPS_PROXYPowerShell 則可以使用:
Write-Output $env:HTTP_PROXY
Write-Output $env:HTTPS_PROXY不建議一開始就把代理設定永久寫入所有 Shell。先以臨時變數完成連線測試,確認 Claude Code 使用的節點與分流規則正常後,再決定是否加入啟動檔。若需要存取公司內網、本機服務或區域網路資源,還可以設定 NO_PROXY,避免這些位址被送進代理:
export NO_PROXY="localhost,127.0.0.1,::1,.local"
$env:NO_PROXY="localhost,127.0.0.1,::1,.local"用 curl 確認終端代理是否生效
先不要直接以 Claude Code 作為第一個測試工具,因為安裝器、登入流程和 API 請求可能涉及多個網域。使用 curl 可以先確認本機代理連接埠是否可用:
curl -I https://example.com如果環境變數未被工具讀取,可以用 -x 明確指定 HTTP 代理:
curl -x http://127.0.0.1:7890 -I https://example.com如果命令可以取得回應標頭,代表 Clash Verge 的本機 HTTP 代理至少能建立基本連線。若明確指定 -x 仍然逾時,應回到 Clash Verge 檢查目前節點、配置模式、DNS 和日誌,不要先修改 Claude Code 的安裝參數。
安裝 Claude Code 並處理登入流程
Claude Code 通常透過 Node.js 生態的套件管理器安裝。請先確認本機已安裝符合要求的 Node.js 與 npm,再依照官方目前提供的安裝方式執行命令。常見的安裝形式如下,實際套件版本與官方命令若有變動,應以官方文件為準:
node --version
npm --version
npm install -g @anthropic-ai/claude-code安裝完成後可以檢查命令是否已加入 PATH:
claude --version
which claudeWindows PowerShell 可使用:
Get-Command claude如果 npm 下載套件時出現逾時或網路錯誤,先用已設定代理的同一個終端執行 npm config get proxy 與 npm config get https-proxy 查看狀態。npm 在不同版本與作業環境下對環境變數的支援情況可能不同,必要時可以明確設定 npm 的代理:
npm config set proxy http://127.0.0.1:7890
npm config set https-proxy http://127.0.0.1:7890這類設定會寫入 npm 使用者配置,不再只是目前工作階段有效。如果日後關閉 Clash Verge, npm 仍可能嘗試連到這個本機端口而失敗,因此不使用代理時要記得檢查或移除設定:
npm config delete proxy
npm config delete https-proxy登入 Claude Code 時,工具可能開啟瀏覽器或提供一次性驗證流程。若瀏覽器可以登入但終端回報回呼失敗,先確認瀏覽器與終端是否使用同一種網路路徑。系統代理只影響部分桌面應用,環境變數只影響目前終端及其子程序,TUN 模式則會涵蓋更多系統流量。三者不一致時,就可能出現瀏覽器成功、終端失敗的情況。
不要把 API 金鑰、登入回呼網址、授權標頭或包含帳號資訊的完整錯誤日誌貼到公開場所。終端畫面截圖前,應先遮蔽識別資訊與敏感欄位。
Claude Code 的分流規則與 TUN 模式選擇
Claude Code 的連線不只涉及一個命令。安裝階段可能需要存取 npm 套件來源,登入階段可能需要瀏覽器和驗證服務,執行任務時則會產生 API 請求,另外還可能使用 Git、套件管理器或遠端開發工具。若規則把不同網域分到不同策略,就會出現安裝成功但登入失敗,或登入成功但執行任務時逾時的情況。
建議先使用明確的代理策略驗證完整流程,不要一開始就建立過於複雜的自訂規則。確認可用後,再按照需求細分直連與代理。常見的判斷原則如下:
- 代理組策略:與 Claude Code 相關的服務網域應落入穩定的代理組,不要在測試時隨意交給延遲最高或負載不明的節點。
- npm 與 Git:套件下載和程式碼倉庫存取可能命中不同規則,需要分別觀察日誌中的網域與實際策略。
- 本機與內網:
localhost、127.0.0.1、區域網路網段和公司內部網域通常應保留直連,避免本機開發服務被送到代理。 - DNS 策略:如果網域解析失敗,單純切換代理組未必有效,應同時查看 DNS 模式、nameserver 和 DNS 劫持設定。
如果只是讓支援代理環境變數的 Claude Code 和 npm 使用代理,可以先不開 TUN 模式。這樣路由範圍較小,發生問題時容易判斷是環境變數或工具設定造成。若登入瀏覽器、子程序、容器或不讀取代理變數的工具仍然無法連線,再考慮在 Clash Verge 開啟 TUN 模式。
TUN 模式需要系統授權建立虛擬網卡,部分平台可能需要系統管理員或 root 權限。啟用後要注意它與其他 VPN、企業安全軟體、虛擬機網路以及 Docker 路由的衝突。排查時不建議同時開啟多個流量接管工具,否則即使 Claude Code 報錯,也很難確認封包實際經過哪一層。
| 使用情境 | 優先方式 | 需要注意 |
|---|---|---|
| 只讓 Claude Code 和 npm 使用代理 | 環境變數 | 確認命令由同一個終端工作階段啟動 |
| 瀏覽器登入與終端路徑不一致 | 環境變數加系統代理,或測試 TUN | 確認兩者使用相同節點與規則 |
| 工具不支援代理環境變數 | TUN 模式 | 檢查虛擬網卡、權限與路由衝突 |
| 公司內網與遠端服務同時使用 | 規則分流 | 為內網網域和本機位址設定直連 |
常見錯誤與固定排查順序
當 Claude Code 顯示網路錯誤、連線逾時或登入無法完成時,建議按照固定順序排查,不要同時更改節點、TUN、DNS 和 npm 設定:
- 確認 Clash Verge 內核正在執行。查看目前配置是否已啟用,代理頁是否能切換節點,日誌是否持續出現配置或端口錯誤。
- 確認節點本身可用。用同一個節點執行
curl -x測試,若所有命令都失敗,先處理節點或本機網路問題。 - 確認終端環境變數。檢查大小寫變數是否存在,以及 Claude Code 是否從設定好變數的同一個終端啟動。
- 分開測試安裝、登入和 API 任務。npm 下載失敗不等於登入服務失敗,瀏覽器登入成功也不等於終端 API 請求一定成功。
- 查看 Clash 日誌。以目標網域搜尋日誌,確認請求是否進入 Clash、命中了哪條規則、使用了哪個代理組,以及錯誤發生在 DNS、TCP 或 TLS 階段。
- 最後才檢查 TUN 和第三方工具衝突。如果環境變數方式已確認可用,不必為了所有問題立即開啟 TUN;若開啟 TUN 後故障,應暫時關閉其他 VPN 或虛擬網路工具再重試。
ECONNREFUSED 通常表示本機指定的代理端口沒有程式監聽,或代理位址與連接埠填寫錯誤。ETIMEDOUT 可能出現在本機代理、節點連線或遠端服務回應階段,需要配合 Clash 日誌判斷。若 npm 顯示憑證或 TLS 錯誤,不要直接長期停用憑證驗證,應先檢查系統時間、代理鏈路、DNS 和中間網路設備。
完成配置後,建議保留一份不含密碼和金鑰的設定備份,記錄目前使用的代理連接埠、Shell 設定檔位置與 TUN 狀態。日後更換節點或升級 Clash Verge 時,可以逐項對照,避免把正常的終端設定誤判為 Claude Code 本身故障。