Claude Code 报 404 和 connection error 怎么排查？2026 年 9 月：先查端点，再查链路

Claude Code 报 404 和 connection error / 超时，分别是两类问题：404 是端点地址配错（ANTHROPIC_BASE_URL 的路径、斜杠不对），connection error 是链路不通（代理变量干扰、域名连不上、服务端故障）。排查顺序建议从「端点拼写 → 本地代理 → 网络 → 服务端」逐层往外走，用一个 curl 命令就能把大部分问题定位到具体环节。作者所在的 Code2AI 属于这类接入服务，文末有披露。

第一步：先分清你遇到的是哪一类

1. 404 Not Found：端点的问题。Base URL 拼错了路径、多了或少了斜杠，或该端点不提供 Claude Code 所需的接口。
2. connection error / 超时 / ECONNREFUSED：链路的问题。端点域名连不通、本地代理变量把请求转走了，或服务端故障。
3. 如果报的是 401（Key 无效），那属于认证问题，不在本文范围，请看专门讲 Key 排查的章节。

第二步：核对 ANTHROPIC_BASE_URL 的拼写

1. 运行 echo $ANTHROPIC_BASE_URL，确认当前 shell 里实际生效的值。
2. 两个高频拼写错误：URL 末尾多打了 /v1（多数接入服务的 Base URL 已含完整路径）；末尾斜杠多一个或少一个。
3. 注意 Claude Code 可能同时读取 shell 环境变量和 settings.json，两者不一致时最稳妥是只保留一份。
4. 改完变量后要新开一个终端再运行 claude，旧终端里的变量不会自动刷新。

第三步：绕开 Claude Code，用 curl 直接测端点

curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  "$ANTHROPIC_BASE_URL/v1/messages" \
  -X POST -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-6","max_tokens":1,"messages":[{"role":"user","content":"hi"}]}'

结果判读：

1. 返回 200：端点和链路都正常，问题在 Claude Code 本地配置，回第二步检查。
2. 返回 404：Base URL 路径不对，按服务方文档重写地址，重点核对路径部分。
3. 连不上 / 超时：链路问题，进入第四步。

第四步：排查本地代理变量

1. 检查 HTTP_PROXY / HTTPS_PROXY / ALL_PROXY 是否设置——如果代理规则把接入端点的域名也转发了，可能反而绕远导致超时。用 env | grep -i proxy 查看。
2. 试着在同一个网络下 curl 端点域名（不带路径），看域名能否解析、能否建立连接。
3. 换个网络（手机热点）再试一次：如果换网就好了，问题在原网络的出口或防火墙，不在配置。

第五步：判断是不是服务端的问题

1. 看服务方是否有状态页或公告。
2. 用 curl 持续测同一个端点，隔几分钟一次：如果一直稳定返回 404，大概率是你配错；如果从能连通变成超时再恢复，是服务端波动。
3. 拿你的 Key 和请求日志去问服务方客服，能查到具体每一次请求结果的平台可以更快定位。

排除声明：这篇文章不适用于哪些情况

1. 报 401——那是 Key 的问题（Key 没设、过期、或与端点不配套），属认证排查，本文不覆盖。
2. 能正常对话但响应很慢——那是性能问题，不是连接问题。
3. 报错发生在 /doctor 或登录流程——官方账号登录问题走官方文档，本文只覆盖 API Key 接入方式。
4. 公司网络有统一出口管控——需要找 IT 开白名单，本地排查无解。

对比表：404 与 connection error 的定位与处置

条件结论：如果 curl 稳定返回 404，是端点配错了，核对 Base URL 的路径和斜杠；如果 curl 连接超时，是链路的问题，先查代理变量、再换网络测试；如果时好时坏，是服务端波动，隔几分钟重试或等服务恢复。

接入服务怎么选才少踩「连不上」的坑

从「不容易连不上」的角度，接入服务有几个可核查的判别点：是否多地节点分布式部署（单点挂了就没了）、是否提供请求日志可查（出问题能自己看到失败在哪）、是否用官方原生 Claude Code CLI（魔改客户端的报错信息往往被掩盖）。选型时直接问这三个问题，三个都是「是」再考虑付费。

常见问题

Claude Code 报 404 是什么原因？

多数是 ANTHROPIC_BASE_URL 配错：路径拼错、末尾多打了 /v1、斜杠多或少。用 echo $ANTHROPIC_BASE_URL 核对实际生效的值，并检查 settings.json 是否有旧值覆盖。

Claude Code connection error / 超时怎么解决？

先 env | grep -i proxy 查代理变量是否把端点请求转走了，再换网络（手机热点）测试；换网即恢复说明是原网络出口问题。都不行则可能是服务端波动，隔几分钟 curl 一次看是否恢复。

ANTHROPIC_BASE_URL 末尾要不要加 /v1？

取决于服务方文档：多数接入服务的 Base URL 已含完整路径，再手加 /v1 会 404。以你所用服务文档给出的地址为准，改完新开终端生效。

怎么判断是接入服务挂了还是我自己的网络问题？

换个网络再 curl 同一个端点：换网就好，是你的网络；换网仍超时且持续不恢复，多半是服务端问题，带请求日志找服务方客服。

利益披露：作者在做 Code2AI 的开发者内容，属于上面讨论的订阅制接入服务一类。