Claude Code 為什麼會在終端機連不上？

到了 2026 年，Claude Code 已經成為不少開發者在終端機裡使用 AI 編程能力的工具。它可以讀取專案檔案、分析程式碼、協助修改文件，也能依照指令執行測試與整理重構方案。可是，很多人第一次安裝後遇到的並不是模型使用方式，而是更基礎的連線問題：瀏覽器可以開啟 Claude，Claude Code 卻顯示登入逾時；npm 套件已經安裝完成，但執行指令時卡在授權頁；登入瀏覽器完成後，終端機仍然停在等待回呼；或是對話開始後頻繁出現 timeout、socket disconnected 與 network error。

這些現象通常不能單純歸咎於 Claude Code 本身。終端機程式與瀏覽器的代理行為不同，Node.js 或其他執行環境也不一定會自動沿用系統代理。換句話說，即使你已經在 Clash Verge 裡開啟「系統代理」，瀏覽器能正常連線，也不代表 Claude Code 的每一個 HTTPS 請求都確實經過 Clash 核心。登入頁面、授權回呼、模型請求與套件下載，可能還會分別走不同的網路路徑。

本篇將焦點放在Clash Verge 搭配 Claude Code 的終端機連線設定，包括訂閱匯入、代理模式選擇、系統代理與環境變數的差異，以及如何利用 Clash Verge 的連線紀錄判斷問題。本文不提供任何第三方帳號、API Key 或遠端節點；請使用你自行取得且符合服務條款的 Claude Code 帳號與訂閱設定。

先分清楚四條連線：不要只代理一個網域

Claude Code 的安裝與使用通常會涉及幾個不同階段。若只把其中一個網址加入代理規則，常會出現「某一步成功、下一步失敗」的狀況。實際網域可能因版本、登入方式、地區與官方架構調整而變更，因此下列分類應視為除錯心智模型，而不是永遠不變的完整網域清單。

• 套件安裝鏈路：使用 npm install 或其他套件管理工具時，會先連到 npm registry 取得 metadata，接著再從實際 tarball 主機下載檔案。metadata 可以成功，不代表後續壓縮包下載也成功。
• 帳號登入鏈路：Claude Code 可能開啟瀏覽器完成登入，再由瀏覽器回到本機暫時監聽的回呼埠。對外的登入服務與本機 127.0.0.1 回呼是兩件不同的事。
• 模型請求鏈路：登入完成後，CLI 仍需向 Anthropic 相關服務建立 HTTPS 連線。若登入成功但第一次提問逾時，通常應檢查這一段，而不是重複清除登入狀態。
• 更新與輔助資源：CLI 更新、版本檢查、遙測設定或遠端文件可能使用不同的主機。若遇到只有更新失敗的情形，請從 Clash Verge 的連線列表找出實際主機，再決定是否加入更精確的規則。

在 Clash Verge 中，建議先使用規則模式，不要一開始就把所有流量改成全域代理。規則模式方便觀察哪些主機命中了代理群組，也能避免公司內網、私人服務、版本庫或本機開發環境被不必要地送往遠端出口。若你正在測試的終端工具不遵循系統代理，再考慮 TUN 模式，而不是盲目增加大量 DOMAIN-KEYWORD 規則。

系統代理、終端環境變數與 TUN 模式的差異

系統代理主要影響會讀取作業系統 HTTP 或 SOCKS 設定的應用程式。瀏覽器通常支援得很好，但不同版本的 Node.js、Git、npm 與 CLI 工具不一定會自動讀取相同設定。終端環境變數則是直接告訴命令列程式應使用哪個 HTTP 或 SOCKS 代理，適合用來進行可控、可重現的測試。TUN 模式在網路層接管較廣泛的流量，對不支援代理環境變數的程式更方便，但需要額外權限，也可能與 VPN、企業安全軟體或其他虛擬網卡衝突。

如果你只是想確認 Claude Code 能否登入，建議依序從系統代理、環境變數再到 TUN 模式測試。每次只改一個變數，並在 Clash Verge 的連線紀錄中確認結果，這樣比同時開啟多種代理方式更容易定位問題。

第一步：在 Clash Verge 匯入訂閱並確認核心正常

在處理 Claude Code 之前，先把 Clash Verge 本身的基礎代理功能確認清楚。很多終端機錯誤其實源於訂閱已過期、設定檔沒有啟用、策略組沒有可用節點，或核心根本沒有成功啟動。若這些基礎項目尚未確認，直接修改 shell 設定只會讓問題變得更複雜。

1. 開啟 Clash Verge，進入「訂閱」或「Profiles」頁面，將你自行取得的 Clash 訂閱連結貼到輸入欄位，按下匯入或更新。
2. 確認設定檔已完成解析，並檢查核心類型是否顯示為 Mihomo 或目前版本所使用的相容核心。若設定檔顯示 YAML 解析錯誤，先處理設定檔本身，不要急著測試 Claude Code。
3. 在設定檔列表中選取要使用的 profile，使它成為目前生效的設定。只有下載設定檔而沒有啟用，代理群組不會按照你的預期工作。
4. 進入「代理」頁面，為主要策略組選擇一個延遲較低且穩定的節點。初次測試時建議固定單一節點，不要立刻使用會自動切換出口的 url-test 群組。
5. 先在瀏覽器開啟一般 HTTPS 網站，再觀察 Clash Verge 的連線列表是否出現紀錄。確認請求有命中預期的代理策略後，才進入終端機測試。

若瀏覽器完全無法連線，請先檢查 Clash Verge 的「系統代理」是否真的開啟、目前 profile 是否生效，以及本機混合埠是否正在監聽。常見的混合埠格式是 127.0.0.1:7890，但實際埠號可能由設定檔或客戶端版本決定，不能直接照抄範例。你可以在 Clash Verge 的設定頁查看目前 HTTP、SOCKS 或 mixed port，再把相同數值用於後續終端測試。

第二步：讓終端機明確使用 Clash Verge

確認 Clash Verge 能代理瀏覽器後，下一步是確認 shell 裡的 Claude Code 是否能看見代理。先在終端機查詢目前是否已有殘留設定：

Shellecho $HTTP_PROXY
echo $HTTPS_PROXY
echo $ALL_PROXY
echo $NO_PROXY

Windows PowerShell 可使用以下方式查看：

PowerShellGet-ChildItem Env:HTTP_PROXY,Env:HTTPS_PROXY,Env:ALL_PROXY,Env:NO_PROXY

如果結果顯示舊 VPN、公司代理或已經不存在的本機埠，Claude Code 可能會優先使用這些錯誤值。測試前可以先暫時清除它們，再依照 Clash Verge 實際顯示的埠號建立新的設定。HTTP 代理通常可用於 HTTPS 請求，因為 HTTPS 會透過 HTTP CONNECT 建立通道；如果你的環境要求 SOCKS，則應使用 Clash Verge 提供的 SOCKS 埠。

Shellunset HTTP_PROXY HTTPS_PROXY ALL_PROXY
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890

PowerShell 的暫時設定方式如下：

PowerShell$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"

這些指令只會影響目前的終端機工作階段。這種做法很適合排錯，因為關閉視窗後設定就會消失，不會把代理永久寫進所有程式。等 Claude Code 確認可以登入與發送請求後，再決定是否要把設定加入 shell 啟動檔或 Windows 使用者環境變數。

不要在不確定的情況下同時設定 HTTP、HTTPS、ALL_PROXY 與多組不同埠號。例如 HTTPS 指向一個已關閉的 SOCKS 埠，而 ALL_PROXY 又指向另一個不存在的服務，某些函式庫可能會依照自己的優先順序選值，最後造成「curl 可以用，但 Claude Code 不行」的表象。排錯時保留一組清楚、單一的代理設定，結果會更可靠。

第三步：登入 Claude Code，並用連線紀錄驗證

當 Clash Verge 的節點、profile 與終端代理都準備好後，再執行 Claude Code 的登入流程。登入時請留意瀏覽器與終端機的時間順序：CLI 啟動授權後，瀏覽器可能被導向官方登入頁；完成授權後，瀏覽器再嘗試回到本機的 127.0.0.1 回呼位址。這個本機位址通常不應該經過遠端代理，否則可能無法回到正在等待的 CLI 程序。

1. 在 Clash Verge 中保持代理核心運作，確認目前策略組已選定固定節點，並打開連線列表或日誌視窗。
2. 在新的終端機視窗設定一組明確的 HTTP_PROXY 與 HTTPS_PROXY，埠號以 Clash Verge 顯示的 mixed port 為準。
3. 執行 Claude Code 提供的登入指令，按照瀏覽器畫面完成官方帳號驗證，不要把授權網址、驗證碼或私人 Token 貼到公開聊天室。
4. 觀察 Clash Verge 是否出現新的登入服務連線。若只看到本機 127.0.0.1 回呼而沒有對外 HTTPS 紀錄，表示前一段可能沒有進入 Clash 或仍使用了其他代理。
5. 登入完成後，先執行一個簡單、低風險的提問，確認模型請求也出現在連線列表中。登入成功不代表模型 API 的路徑一定已經正常。

在連線列表中，請特別留意主機名稱、命中規則、使用的策略組、連線狀態與錯誤時間。如果請求顯示為 DIRECT，但你原本期待它走代理，應先檢查規則順序與目前 profile。Clash 的規則通常是由上而下比對，過早命中的 GEOIP、FINAL 或寬泛關鍵字規則，都可能讓你新增的網域規則完全沒有機會生效。

常見錯誤與排查順序

如果 Claude Code 仍然無法工作，可以按照「核心、埠號、環境變數、規則、帳號」的順序排查。不要一看到逾時就重新安裝所有工具，因為重新安裝通常不會修正錯誤的代理設定。

如果錯誤訊息是 ECONNREFUSED，通常代表本機代理埠沒有服務在監聽，或環境變數填入了錯誤埠號；如果是 ETIMEDOUT，則可能是請求走了不合適的直連路徑、遠端節點品質不穩，或 DNS 與實際出口不一致；如果是 407 Proxy Authentication Required，代表你連到了一個要求帳號密碼的代理，而不是 Clash Verge 的本機埠。這些錯誤應分別處理，不要全部歸類為「Claude 登入失敗」。

若你在公司網路或校園網路中測試，還要考慮 TLS 檢查、出口防火牆與 DNS 政策。這類環境可能允許瀏覽器透過受管理的憑證連線，卻阻擋未註冊的 Node.js 程式。此時請先確認組織政策是否允許使用相關開發工具，不要任意關閉端點防護或匯入來源不明的憑證。若規則與埠號都正確，但只有特定網路失敗，換一個受信任的網路做對照測試，通常能快速區分本機設定與網路政策問題。

建立穩定的日常使用方式

完成首次登入後，建議把日常使用流程固定下來。第一，讓 Clash Verge 在執行 Claude Code 前就完成核心啟動與 profile 載入；第二，盡量使用穩定的固定策略，而不是在一個長時間的程式工作階段中頻繁切換節點；第三，將專案內網域、localhost、公司 Git 服務與資料庫位址列入合理的直連範圍，避免 AI 工具執行本機工作時被不必要地送出；第四，定期檢查訂閱更新時間與節點狀態，但不要在正在進行長任務時隨意更新並切換設定檔。

如果你需要在不同專案使用不同網路策略，可以在 Clash Verge 建立清楚命名的 profile，例如「開發代理」「一般瀏覽」與「公司內網」。每份設定只保留必要規則，並在切換後用連線列表確認結果。終端機方面則可使用獨立 shell 工作階段，避免把代理環境變數永久寫入所有命令列工具。這種做法雖然比單純按下全域模式多幾個步驟，卻更容易保護 Git、套件管理器與本機服務不被誤分流。

最後，請把可觀察性當成設定的一部分。當 Claude Code 再次出現登入逾時或模型請求失敗時，先記錄發生時間、終端錯誤、Clash 命中規則與節點名稱，再逐項比較。與其反覆刪除設定、重新安裝 CLI，不如保留一份可以重現的測試流程。對開發者而言，能知道請求是否進入 Mihomo、走了哪個策略群組，以及在哪個主機階段失敗，往往比一份看似完整但無法驗證的 YAML 更有價值。

相比之下，部分同類代理工具在終端機代理繼承、TUN 權限與連線紀錄方面的說明較零散，初學者常只能靠猜測埠號或反覆切換全域模式；有些工具則偏重簡化介面，遇到 Claude Code 這類需要區分登入回呼、套件下載與模型請求的場景時，除錯資訊不夠完整。Clash 官網 以 Clash Verge、Mihomo 核心與終端機實際操作為主軸整理設定思路，讓你能從訂閱匯入、策略選擇到連線紀錄逐步驗證，而不是只照抄一組可能過期的規則。如果你想先準備一套適合開發工具使用的 Clash 客戶端，不妨前往下載，再依本文流程完成 Claude Code 的終端機連線設定。