Claude Code 為什麼會卡在登入、安裝或連線？
想在終端機使用 Claude Code 協助閱讀專案、修改程式或執行測試，很多人第一個遇到的問題並不是模型指令，而是「瀏覽器明明可以開啟相關頁面，終端機卻一直逾時」。常見現象包括 npm install -g 安裝到一半失敗、啟動後登入頁面可以開啟但回到 CLI 後仍顯示等待、輸入提示後出現 ETIMEDOUT、ECONNRESET 或 fetch failed，也有人只是看到 Claude Code 一直停在載入畫面。
這些問題通常不是單一「代理有沒有開」可以解釋。Claude Code 是在終端機程序中執行的工具，它可能由 Node.js 啟動，之後再透過 HTTPS 連線到套件註冊站、登入服務、API 端點與其他必要網域。瀏覽器使用的是自己的代理設定，終端機則可能遵循系統代理、環境變數，或完全採用直連。兩者走不同路徑時，就會形成「網頁能用、CLI 不能用」的典型分裂。
如果你使用 Clash Verge，正確做法不是先把所有流量粗暴地切到同一個節點，而是先確認本機代理埠、終端機是否真的能使用該埠，再根據連線紀錄建立適合開發工具的分流規則。本文以 2026 年常見的 Clash Verge／Mihomo 使用方式為基礎，整理安裝前檢查、終端機代理、登入流程、規則分流與故障排查，讓你可以逐層定位問題，而不是反覆重裝 Claude Code。
合規提醒：Clash Verge 與 Mihomo 是本機代理、連線管理與規則分流工具，不會自行提供遠端節點。請使用你有權使用的訂閱或設定檔，並遵守 Claude、套件註冊站、公司網路及所在地區的服務條款。
先理解 Claude Code 的實際連線路徑
一次完整的 Claude Code 工作流程，往往不只有「連到模型 API」這一條線。第一次安裝時，套件管理器需要連到 npm registry 或其他套件下載主機；啟動與登入時，瀏覽器和 CLI 可能分別存取帳號認證端點；真正開始對話後，程式還要向模型服務建立 HTTPS 請求。若你使用專案中的 npm 套件、Git 倉庫或 MCP 服務，還會多出 GitHub、套件 CDN 和第三方 API 等額外連線。
- 安裝鏈路：由 npm、pnpm 或 yarn 存取套件 metadata、tarball 與相依套件下載位置。metadata 能成功，不代表真正的壓縮包下載也成功。
- 登入鏈路：瀏覽器可能開啟登入頁面，但 CLI 仍需要等待本機回呼或取得授權結果；瀏覽器與終端機的代理路徑不一致時，最容易在這一步卡住。
- 模型鏈路：Claude Code 送出提示、讀取回覆或執行長連線請求時，必須讓相關 HTTPS 流量使用穩定出口。
- 開發鏈路：Git、GitHub、npm、MCP 伺服器與專案中的遠端 API，可能與模型端點完全不同，不應只用一條模糊的全球規則處理。
因此，排錯時請先問「目前失敗的是哪條鏈路」，再決定是否要調整 Clash 規則。若安裝指令就已經失敗，先不用急著研究 OAuth；如果安裝正常、登入成功，但第一次輸入提示後逾時，重點才是模型服務的連線紀錄與策略組。這種分層思路能避免把不同問題混在一起處理。
Clash Verge 基本設定：先確認代理核心真的在工作
在設定 Claude Code 之前，請先打開 Clash Verge，確認目前使用的設定檔已經成功載入，且核心狀態是執行中。不同版本的介面名稱可能略有差異，但通常可以在 Profiles、配置或設定檔頁面看到目前啟用的 YAML。若設定檔沒有被啟用，或核心顯示停止，終端機即使設定了代理埠，也只會得到連線拒絕。
- 匯入可用設定檔：在 Clash Verge 的設定檔頁面加入你合法取得的訂閱連結或本機 YAML，等待更新完成後啟用該設定檔。若更新失敗，先在連線紀錄中確認是 DNS、TLS 還是遠端伺服器回應錯誤。
- 確認核心與模式：確認使用的是 Mihomo 核心，並將模式先設為
Rule。除錯期間不建議一開始就使用過度複雜的腳本規則，因為你需要清楚知道某一個網域最後命中了哪個策略。 - 確認混合代理埠：在設定頁面記下 HTTP、SOCKS 或 Mixed Port。若介面提供混合埠，通常最方便讓不同 CLI 工具共用，例如
7890或其他你自行設定的本機埠號；實際數值必須以你的 Clash Verge 畫面為準。 - 先測試節點：在 Proxies 頁面固定選擇一個延遲與穩定性都較好的節點，不要在第一次登入時使用頻繁自動切換的測速組。穩定的單一出口更容易判斷到底是規則問題還是節點品質問題。
- 觀察連線紀錄：保持 Clash Verge 的 Connections 或 Logs 頁面開啟，然後再執行 Claude Code。只有看到對應主機出現在連線列表，才能確認終端機請求確實進入了 Clash 核心。
對終端機工作流來說，Rule 模式通常比 Global 模式更適合長期使用。Global 模式雖然容易快速驗證「代理是否能通」，但會把 npm、Git、作業系統更新與公司內部服務全部送到同一出口，可能造成速度變慢、內網服務失效或不必要的流量混用。建議先用 Global 做短暫的對照測試，確認問題確實與出站路徑有關，再回到 Rule 模式細分規則。
實用建議：不要只看節點延遲數字。對 Claude Code 而言，TLS 握手穩定、長時間連線不重置，往往比單次測速的低延遲更重要。可以在固定節點下連續執行幾次簡單請求，觀察是否出現間歇性斷線。
讓終端機使用 Clash：HTTP、HTTPS 與 SOCKS 的選擇
Clash Verge 的系統代理開關主要影響遵循作業系統代理設定的應用程式，並不保證每一個終端機工具都會自動使用它。Claude Code 若由 Node.js 執行，是否能讀到系統代理，還取決於 Node 版本、套件實作與啟動方式。最可靠的做法，是在執行前明確設定終端機代理環境變數，再用獨立的測試指令確認路徑。
如果 Clash Verge 提供 Mixed Port，優先使用它作為 HTTP_PROXY 與 HTTPS_PROXY 的目標。對許多 npm、curl、Git 與 Node 套件而言，HTTP 代理埠可以處理 HTTPS 的 CONNECT 隧道；這裡的「HTTP」是代理協定，不代表你只能存取 HTTP 網站。若你使用 SOCKS5，也可以設定 ALL_PROXY，但個別工具對 SOCKS 的支援方式不同，遇到問題時較難快速分辨。
Shellexport 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
上述埠號只是示例，請替換成 Clash Verge 實際顯示的數值。若你使用 Windows PowerShell，可以使用以下形式設定目前工作階段的環境變數：
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"
接著不要直接跳到 Claude Code，先用簡單的 HTTPS 請求驗證代理。測試目標可以選擇你有權存取的服務首頁或公開 API，不必為了測試而反覆觸發登入。若 curl 能成功連線，但 Clash Verge 的 Connections 完全沒有記錄，代表 curl 沒有讀到環境變數、埠號寫錯，或該工具使用了其他代理設定。若連線有記錄但仍失敗，則應檢查命中規則、節點回應與 TLS 錯誤。
完成測試後，再在同一個終端機視窗啟動 Claude Code。不要先關閉環境變數，也不要在不同的終端機分頁中測試，否則很容易誤以為「設定已生效」，實際上只是某個分頁有代理、另一個分頁沒有。長期使用時，可以把代理設定放在專用的 shell script 或 PowerShell profile 中，但公司內網、localhost 與私有網域應加入 NO_PROXY，避免內部服務被送到外部代理。
Shellexport NO_PROXY=localhost,127.0.0.1,::1,.local
Claude Code 登入與分流：不要只代理瀏覽器看到的網域
Claude Code 的登入流程可能包含瀏覽器導向、授權狀態確認與本機回呼。瀏覽器開啟登入頁面時，Clash Verge 可能已經記錄了相關流量；但 CLI 回到終端機後，仍會發出新的 HTTPS 請求。如果這些請求沒有繼承相同的代理環境，便可能出現「帳號已登入，但 Claude Code 說登入失敗」的情況。此時不應只重複點擊登入，而要同時觀察瀏覽器和 CLI 兩邊的時間點與連線紀錄。
分流規則方面，建議採取從實際連線紀錄建立最小集合的方式。你可以先啟動 Claude Code，執行一次不涉及敏感資料的測試指令，接著在 Clash Verge 的 Connections 中記下出現的主機名稱。將與帳號、模型服務和必要 API 有關的網域放進專用策略組，再讓一般網路、作業系統更新和本機服務維持原本路徑。不要直接使用過寬的 DOMAIN-KEYWORD,anthropic 或把所有未知網域都代理，因為這會增加誤分流與後續排障難度。
規則排列順序也很重要。若你在前面放了寬泛的 GEOIP、FINAL 或其他大型規則集，後面的精確網域規則可能根本沒有機會被執行。較容易維護的順序通常是：本機與區域網路直連、開發工具需要的精確網域、Git 與套件服務規則、其他已知服務規則，最後才是 GEOIP 或 FINAL。每次修改後，都要在 Connections 裡檢查實際命中結果，而不是只看 YAML 是否能成功儲存。
| 症狀 | 優先檢查位置 | 常見處理方向 |
|---|---|---|
| 套件安裝逾時 | npm registry、tarball CDN、終端代理變數 | 確認 npm 與 Node 是否使用同一代理，並在連線紀錄中找出實際下載主機。 |
| 瀏覽器登入成功，CLI 仍等待 | 本機回呼、CLI 的 HTTPS 請求、localhost 排除規則 | 保留 127.0.0.1 直連，同時確認 CLI 的遠端認證請求有進入 Clash。 |
| 登入完成但第一次提示逾時 | 模型 API 主機、代理策略組、節點穩定性 | 固定一個穩定節點，確認模型服務主機命中預期策略，而不是只代理登入頁。 |
| 偶爾成功、偶爾失敗 | 自動選擇組、DNS 模式、節點切換與長連線 | 暫時停用自動切換，固定節點並比較不同 DNS 或出口的連線結果。 |
本機回呼與遠端服務要分開看。像 127.0.0.1、localhost 這類位址通常應該保持 DIRECT，否則可能產生代理迴圈或讓回呼請求無法正確返回；但這不代表所有登入流量都應該直連。真正需要代理的是 CLI 對外發出的 TLS 請求，兩者在 Clash 連線紀錄裡會呈現不同的目的地，不能用「全部代理」或「全部直連」一概而論。
常見排障順序：由本機到遠端逐層確認
當 Claude Code 仍然無法使用時，建議按照由近到遠的順序排查。第一層是 Clash Verge 本身：核心是否啟動、設定檔是否有效、代理埠是否正在監聽、目前策略組是否有可用節點。第二層是終端機：環境變數是否存在、目前 shell 是否繼承設定、是否有舊的 HTTP_PROXY 或 NO_PROXY 覆蓋新值。第三層才是 Claude Code 與遠端服務：登入狀態、版本相容性、API 回應與帳號權限。
- 看到 connection refused：通常表示本機代理埠沒有監聽、埠號填錯，或 Clash Verge 核心已停止。先用作業系統工具確認該埠是否存在，再檢查應用程式設定。
- 看到 timeout：可能是請求未進代理、規則命中 DIRECT、DNS 解析結果不理想，或節點本身無法穩定連到目標服務。查看 Connections 比單看終端錯誤更有價值。
- 看到 401 或 403：不要立即把它判定為代理故障。這可能是登入過期、帳號權限、API 設定或服務端政策問題；先確認請求確實抵達服務，再依官方說明處理帳號層面。
- 看到 certificate 或 TLS 錯誤：檢查系統時間、Node.js 版本、企業防毒的 HTTPS 攔截，以及 Clash 的 DNS 與節點鏈路。不要隨意關閉憑證驗證，這會把真正的安全問題藏起來。
- 只有某個專案失敗：檢查專案內的環境變數、代理設定、MCP 配置與 npm registry。全域 Claude Code 能啟動，不代表專案中的所有外部服務都能走同一條路。
如果你同時使用系統代理與 TUN 模式，排錯時最好先只保留一種主要路徑。系統代理適合快速驗證遵循 HTTP／HTTPS 代理的 CLI；TUN 模式則能接管較多不讀取環境變數的程式，但會涉及虛擬網卡、DNS、路由與作業系統權限。兩者同時開啟時，若規則或路由設定不完整，可能出現重複代理、連線迴圈或某些網域忽然無法使用。確認基本流程後，再依實際需求啟用 TUN。
最後，請記錄每次測試的條件：使用哪個節點、哪個代理埠、是否開啟 TUN、終端機執行的命令、錯誤發生時間，以及 Clash 命中的規則名稱。這份簡單的測試紀錄可以快速分辨「固定環境仍失敗」與「只有某個節點失敗」。相較於一次修改十個設定後重新登入，單變數測試更能保留可重現性，也方便日後更換電腦或更新 Clash Verge 時重新建立環境。
相較之下，一些只面向瀏覽器的代理工具在 Claude Code 這類終端場景中往往不夠用：它們可能沒有清楚的 HTTP／SOCKS 埠管理、看不到實際命中規則，也缺少對 Node、npm 與 TUN 路徑的說明；部分圖形客戶端雖然功能很多，卻把設定分散在不同頁面，初學者很難判斷到底是登入、DNS 還是節點出了問題。Clash 官網 的優勢在於把 Clash Verge 的終端代理、策略分流、連線紀錄與常見錯誤整理成可逐步驗證的流程，讓你能先用最小設定跑通 Claude Code，再按需求擴充規則，而不是依賴模糊的全域代理。如果你正準備建立一套穩定的 Claude Code 開發環境，不妨前往下載 Clash 官網，依照本文的檢查順序開始設定。