TL;DR
- 连不上先分三层：网络层（地址/协议）、鉴权层（Key 与变量名）、模型层（模型名映射）。
- 90% 的「连不上」卡在两处：
ANTHROPIC_BASE_URL写错，或把ANTHROPIC_AUTH_TOKEN误写成ANTHROPIC_API_KEY。 - 用文末的「一条命令定位法」先拿到分层结论，再按对照表对症处理，不要凭感觉改配置。
图 1：一条请求要过三道关卡，报错串会告诉你被拦在哪一层（示意图）
先确认：你的 Claude Code 是怎么配置的
Claude Code 支持两种接入方式，排查前先弄清自己在用哪种，否则后面的每一步都会对错表：
- 环境变量方式：
ANTHROPIC_BASE_URL（服务地址）+ANTHROPIC_AUTH_TOKEN（中转场景常用 Bearer Token）。 - 官方登录方式：
/login走 Anthropic 账号 OAuth，不经过自定义 Base URL。
中转 / 自定义 API 场景使用环境变量方式。先跑一遍下面三条，把「实际生效的配置」打印出来（macOS / Linux）：
echo "BASE_URL = $ANTHROPIC_BASE_URL"
echo "AUTH_TOKEN 是否已设置：$([ -n "$ANTHROPIC_AUTH_TOKEN" ] && echo yes || echo no)"
echo "API_KEY 是否已设置：$([ -n "$ANTHROPIC_API_KEY" ] && echo yes || echo no)"两个常见陷阱在这里就能暴露：BASE_URL 结尾多写或少写一段路径；同一个终端里同时设置了 ANTHROPIC_API_KEY 和 ANTHROPIC_AUTH_TOKEN，实际生效的优先级和你以为的不一致。Windows PowerShell 用户注意环境变量写法是 $env:ANTHROPIC_BASE_URL，Linux 的 export 语法在 PowerShell 里不生效。
6 个报错串对照表
按报错串对号入座。右列命令可直接复制执行（把变量换成你自己的值）。
| 报错串（关键部分） | 真实含义 | 最常见原因与处理 |
|---|---|---|
Invalid API key · Please run /login | 客户端没拿到可用的凭据 | 中转场景十有八九是变量名用错：应使用 ANTHROPIC_AUTH_TOKEN 而不是 ANTHROPIC_API_KEY（后者按官方密钥格式校验）。改对后重开终端再试。 |
API Error: 401 · authentication_error | 请求已到达服务端，凭据被拒 | Key 已被删除/重置，或复制时带了空格。用下方自检命令直接请求一次，确认是 Key 问题还是客户端问题。 |
API Error: 404 · not_found_error（含 model 字样） | 请求到达了，但模型名在服务端不存在 | 中转平台的模型名与官方不同。设置 ANTHROPIC_MODEL 映射为服务方实际提供的模型名（以服务方模型列表页为准）。 |
Connection error / ECONNREFUSED / ENOTFOUND | 网络层就没走通 | BASE_URL 拼写、协议（https 写成 http）、本地代理干扰。用 curl -I 直接探地址是否可达。 |
API Error: 429 · rate_limit_error | 请求太密或额度池限流 | 等 30-60 秒重试；持续出现说明服务方并发/速率额度紧张，属服务端状况，改客户端配置无效。细分判断见429/502/530 状态码速查表。 |
unable to verify the first certificate / SSL 相关 | TLS 握手失败 | 先查本机系统时间是否准确；再排查本地代理/安全软件的 HTTPS 拦截。不要用跳过证书校验的方式「解决」。 |
一条命令定位法：把问题钉在某一层
与其反复改配置碰运气，不如直接用 curl 模拟一次最小请求。返回结果会明确告诉你问题在哪一层：
curl -sS "$ANTHROPIC_BASE_URL/v1/messages" \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model":"claude-sonnet-4-5","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}'- 毫无输出 / 连接超时 → 网络层：地址不可达或本地代理劫持，先解决连通性。
- 返回 401 JSON → 鉴权层：Key 或变量名问题，回对照表第 1-2 行。
- 返回 404 且提到 model → 模型层：模型名映射问题，回对照表第 3 行。
- 返回正常 JSON（content 字段有文字） → 服务端链路完全正常，问题在 Claude Code 客户端本地配置：重开终端、检查是否有多处配置互相覆盖（shell 配置文件里的旧 export）。
注意：不同服务方的路径约定可能不同（有的 Base URL 已含 /api 等前缀），以上命令以「Base URL + /v1/messages」的常见约定为准，若 404 且不含 model 字样，向服务方确认正确的 Base URL 完整形态。
这些情况该等，别乱改
429 与 529/overloaded 类错误是服务端容量信号，等待重试是正确处理，任何客户端侧的配置改动都不会有帮助。连续 10 分钟以上全是 429，去服务方状态页或售后群确认，而不是继续重装客户端。
反过来，401 / 404 / Invalid API key 是确定性错误，等是等不好的，按对照表改完配置立即复测。
还没解决？按这个顺序收尾
- 重开终端（环境变量改动只对新会话生效，这是最常见的「改了没反应」）。
- 检查是否多处配置互相覆盖：shell 配置文件（
.zshrc/.bashrc）里残留的旧 export。 - 用 curl 定位法区分「服务端正常、客户端配置错」还是「服务端本身不可用」。
- 需要服务入口与可用的模型列表，先看主站的 Provider 与 Base URL 配置自检，或在 shana.baby 售后群按「报错串 + curl 返回原文」提问，能省一轮来回。
维护说明
本文的报错串与命令基于 2026-09 的 Claude Code 常见报错形态与 OpenAI 兼容 / Anthropic 兼容中转的通用行为整理；「以官方文档为准」的断言（变量优先级、路径约定）在客户端大版本更新后会复测并更新本文日期。