部落格 / 排障指南

Claude Code 連線超時和報錯怎麼排查：四層網路檢查清單

2026-10-17cdnping 編輯部約 6 分鐘讀完

Claude Code 連線超時或報錯，原因通常在四個地方：服務端故障、本機網路不通、出口 IP 受限，或者本地配置寫錯。建議的順序是先看服務狀態，再測本機到 api.anthropic.com 的連通性，然後看出口 IP，最後核對環境變數和配置檔案。下面每一層都給了具體的檢查方法。

#先看現象：錯誤資訊對應哪一層

動手之前，先把 Claude Code 給出的錯誤原文記下來。不同的報錯大致對應不同的層：

表裡的對應關係是經驗判斷，不是絕對規則。比如 403 可能來自賬號許可權，也可能和請求來源的地區有關，要結合後面的檢查一起看。

#第一層：Claude 服務本身是不是掛了

服務端故障時，本地怎麼改都沒用，所以這一步放在最前面。

#檢查方法

1. 開啟 cdnping 的 Claude Code 掛了嗎 頁面。這一頁綜合了官方狀態頁、每 5 分鐘一次的 API 探測和使用者的一鍵報告（打不開、很慢、限流、被登出等）。如果短時間內報告集中出現，而且別人的報錯和你一樣，大機率是服務端問題。
2. 再看 Anthropic API 狀態。cdnping 從 Cloudflare 邊緣每 5 分鐘探測一次官方 API 入口，每 15 分鐘同步一次 Anthropic 官方狀態頁，保留 30 天曆史。
3. 以官方狀態頁 status.anthropic.com 為最終依據。

#參考資料

下面是 cdnping 在 2026-10-17 08:40–10:05（UTC）這段探測視窗內，從 Cloudflare 丹佛節點（DEN）對 api.anthropic.com 的探測結果：

來源：cdnping /status 邊緣探測，資料以 CC BY 4.0 開放。cdnping 從 2026-10-17 才開始採集，這個視窗不到一個半小時，只能說明當時入口是通的。數字來自境外邊緣節點，不代表你在國內本機測到的延遲。

另一組資料來自 cdnping 同步的 Anthropic 官方狀態頁記錄：2026-09-17 至 2026-10-17 這 30 天裡，共記錄 Claude 相關事件 8 起，官方標為 major 的 6 起、minor 1 起、none 1 起；快照收錄的最近 40 條事件（2026-10-09 至 10-16）裡沒有 Claude 條目。一個月 8 起不算少，所以報錯時先花半分鐘看狀態頁，比直接改本地配置划算。

同一時段，cdnping 也記錄到 Cloudflare 自身的多起事件，例如 2026-10-10 開始的 “Elevated Errors in China Network Colos”（官方標為 minor）。/status 頁也同步 Cloudflare 的狀態頁，如果你的鏈路經過的基礎設施出了問題，同樣可能表現為連線異常，可以一起對照。

#第二層：本機到 api.anthropic.com 通不通

服務正常，就把問題收窄到你的機器到 api.anthropic.com 這一段。

#用 curl 拆開 DNS、TCP、TLS 耗時

curl -sS -o /dev/null \
  -w "DNS: %{time_namelookup}s\nTCP: %{time_connect}s\nTLS: %{time_appconnect}s\n總計: %{time_total}s\nHTTP: %{http_code}\n" \
  https://api.anthropic.com/v1/messages

不帶金鑰請求，返回 401、404 或 405 都正常，說明網路已經通到服務端。按輸出判斷：

• DNS 一項很長或直接失敗：解析有問題，換一個解析器試試，或檢查代理軟體的 DNS 設定。
• TCP 卡住、超時：連線沒建立起來，問題在路由或出口。
• TLS 失敗或報證書錯誤：常見於公司網路的 HTTPS 審計代理，或本機開著抓包工具。
• 各項都正常，Claude Code 仍超時：多半是 Claude Code 沒走你以為的那條路，直接跳到第四層查配置。

#瀏覽器能開啟 claude.ai，終端卻連不上

這種情況通常是瀏覽器走了系統代理，終端沒有。先看終端裡實際生效的代理變數：

env | grep -i -E "https?_proxy|no_proxy|all_proxy"

再在瀏覽器開啟 cdnping 首頁線上測速，看 Claude 一項的“首次連線”（含 DNS 和 TLS 握手）和“往返”（連線複用後 3 次請求的中位數）。瀏覽器測得通、終端 curl 不通，說明兩邊走的不是同一條路。

#第三層：出口 IP 是不是被限制了

網路是通的，但請求返回 403，或者連線建立後很快被斷開，就要看出口 IP。

前提先說清楚：Anthropic 只在其支援的國家和地區提供服務，請以官方公佈的支援地區為準，並遵守服務條款和當地法規。本文只講怎麼確認問題出在哪，不討論如何繞開地區限制。

#在 /ip 頁面看哪幾項

開啟 cdnping 的 IP 與環境檢測，重點看這幾項：

排查 Claude Code 時，多出口檢測和分流檢測最有用。常見的情況是：你以為所有流量都走同一個出口，實際上 Claude 的請求按分流規則走了另一條線路，或者直接走了本地網路。兩項結果對照著看，就能確認 Claude 的請求實際從哪裡出去。分流的原理見 什麼是分流，原生 IP 和廣播 IP 的區別見 這篇說明，洩漏檢測的原理見 DNS 洩漏與 WebRTC 洩漏。

#生成隱藏 IP 的結果圖，方便求助

在團隊群或社羣裡求助時，可以在 /ip 頁面直接生成一張結果圖，不用截好幾張屏。結果圖帶 cdnping 水印，生成時可以選擇隱藏 IP 地址，別人能看到出口型別、分流判斷、延遲特徵這些排查需要的資訊，你的具體 IP 不會露出來。瀏覽器指紋類檢測在本地計算，不會上傳。

#第四層：Claude Code 配置是不是寫錯了

前三層都正常，問題就在本地配置。Claude Code 會讀取環境變數，以及 ~/.claude/settings.json 裡 env 欄位的配置，兩處都要查。

#檢查命令

# 1. 讓 Claude Code 自檢安裝和配置
claude doctor

# 2. 檢視相關環境變數
env | grep -E "ANTHROPIC_|API_TIMEOUT_MS|NODE_EXTRA_CA_CERTS"

# 3. 檢視使用者級配置裡的 env 欄位
cat ~/.claude/settings.json

# 4. 專案級配置也可能覆蓋全域性設定
cat .claude/settings.json .claude/settings.local.json 2>/dev/null

逐項核對：

• ANTHROPIC_BASE_URL：設過自定義介面地址的，檢查拼寫、協議頭（https）、末尾有沒有多餘路徑。地址寫錯時常見 404 或連線超時。用完第三方地址後忘了刪，也經常導致出錯。
• ANTHROPIC_API_KEY 與 ANTHROPIC_AUTH_TOKEN：金鑰是否過期、有沒有多餘空格；同時設定了多種認證方式時，確認當前生效的是哪一個。在 Claude Code 裡輸入 /status 可以檢視當前的賬號和介面資訊。
• HTTPS_PROXY / NO_PROXY：公司網路要走內部代理時，確認變數在 Claude Code 所在的終端裡生效；NO_PROXY 裡不要誤加 anthropic.com。
• NODE_EXTRA_CA_CERTS：公司 HTTPS 審計代理會替換證書，需要把公司根證書的路徑填進來，否則會出現第二層提到的證書錯誤。
• API_TIMEOUT_MS：網路慢、長任務經常超時，可以適當調大請求超時。這隻能緩解，鏈路本身的問題還在。

改完配置後，新開一個終端再執行 claude，避免舊環境變數殘留。

#用了第三方介面地址怎麼排查

如果你透過第三方閘道器使用 Claude Code（只改 ANTHROPIC_BASE_URL 和金鑰），排查時要把閘道器當作單獨的一層：先確認閘道器本身的狀態，再看閘道器到上游的情況。

以 AGI Plan 為例（AGI Plan 是 cdnping 的商業合作方），cdnping 的 /status/agiplan 會映象它公開的逐小時請求統計，可用率按真實請求計算，只有 5xx 算平臺失敗。在前面同一個探測視窗內，cdnping 從 DEN 節點探測 agiplan.dev 的耗時為 883 ms。AGI Plan 明確說明自己不是官方授權渠道。無論用哪種接入方式，都先讀清楚服務方關於授權渠道和使用條款的說明。

#照著做的排查表

#平時可以先做的準備

• 把 /down/claude-code 加進書籤，報錯時先看它。
• 在網路正常時去 /ip 跑一次完整檢測，生成一張隱藏 IP 的結果圖留作基線，下次出問題時對照差異。
• cdnping 的探測節點、頻率和統計口徑見 資料方法；每週的穩定性彙總在 週報。