博客 / 排障指南

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 为例（cdnping 与 AGI Plan 由同一团队运营），cdnping 的 /status/agiplan 会镜像它公开的逐小时请求统计，可用率按真实请求计算，只有 5xx 算平台失败。在前面同一个探测窗口内，cdnping 从 DEN 节点探测 agiplan.dev 的耗时为 883 ms。AGI Plan 明确说明自己不是官方授权渠道。无论用哪种接入方式，都先读清楚服务方关于授权渠道和使用条款的说明。

#照着做的排查表

#平时可以先做的准备

• 把 /down/claude-code 加进书签，报错时先看它。
• 在网络正常时去 /ip 跑一次完整检测，生成一张隐藏 IP 的结果图留作基线，下次出问题时对照差异。
• cdnping 的探测节点、频率和统计口径见 数据方法；每周的稳定性汇总在 周报。