你从一家中转站拿到 Claude 的 Key，照着文档填进代码，结果要么鉴权失败、要么路径 404、要么提示模型不存在，反复试也说不清是 Key 的问题还是地址写错。这篇给一条从拿到凭据到跑通第一条请求的固定顺序，再把三类最常撞上的报错按原因和改法对一遍，让你十分钟内判断卡在哪一步。
你从一家中转站拿到 Claude 的 Key，照着文档填进代码，结果要么鉴权失败、要么路径 404、要么提示模型不存在，反复试也说不清是 Key 的问题还是地址写错。问题通常不在「中转站不好用」，而在于你把两套协议混着抄了。
这篇给一条从拿到凭据到跑通第一条请求的固定顺序，再把三类最常撞上的报错按原因和改法对一遍。全程只动一个变量，卡在哪一步能立刻看出来，不用靠猜。
第一步：拿到 Key 和 Base URL，先分清两套写法
中转站一般给你两样东西：一串 Key 和一个 Base URL。Key 只存在你这一侧，别贴进前端代码，也别提交到公开仓库——中转站的 Key 通常是可计费的，泄露等于别人替你花钱。第一件事不是填代码，是先问清楚：你手上这把 Key 走的是哪套协议。
- Anthropic 原生协议
- 地址后缀带 /v1，SDK 用 Anthropic 官方那套，鉴权走单独的请求头字段
- OpenAI 兼容协议
- 地址后缀可能不带版本段，SDK 用 OpenAI 那套写法，鉴权走常见的 Bearer 头
- 同一家中转站的 Claude 渠道不一定两种协议都开，先用哪套就按哪套填，别看着别人的示例照抄
- 地址后缀是两套协议最容易搞混的地方，抄之前先确认你这份文档属于哪一类
- 拿不准价格与模型范围时，到 /official-api/providers/anthropic 对照官方口径，再到 /sites/all 看这家站的条目
- 如果这家站同时在多个渠道挂了 Claude，条目页会写清各自支持的协议，以那里为准
第二步：环境变量怎么填，名字和值各管什么
环境变量只有两件事：名字对不对、值有没有多写。名字错，SDK 读不到就成了空 Key；值多写一段路径，就变成 404。这两类错误的表现完全不同，但改法都很机械。
| 走哪套协议 | Key 变量名 | 地址变量名 | 地址填到哪 |
|---|---|---|---|
| Anthropic 原生 | ANTHROPIC_API_KEY | ANTHROPIC_BASE_URL | 域名加版本段为止 |
| OpenAI 兼容 | OPENAI_API_KEY | OPENAI_BASE_URL | 按该站给的地址原样抄 |
| 常见错误 | 两套变量同时存在 | 两个地址各填一半 | 自己再拼一段接口路径 |
- 按协议选一套变量只保留与你实际使用的那套协议对应的两个变量，另一套先清掉，避免代码读错。
- 地址只填到版本段不要自己再拼 /messages 或 /chat/completions，多拼一段就是 404 的常见来源。
- 改完重启进程环境变量改了要重开终端或重启 IDE，很多「改了不生效」其实是进程还在用旧值。
- 打印出来确认本地同时装了两套 SDK 时，把代码实际读到的变量名和地址打印一行看一眼，再往下排错。
第三步：发一次最小请求，验证通没通
验证阶段的目标不是跑通业务，而是让变量只剩最少几个。请求里只留模型名、一条用户消息、很小的输出长度上限，流式开关先关掉——流式一旦断连，你分不清是鉴权问题还是传输问题。
curl -sS "$BASE_URL" -H "content-type: application/json" -d '{"model":"<从站内条目复制的模型名>","max_tokens":64,"messages":[{"role":"user","content":"ping"}]}'- 先用命令行发一条最短请求，不要一上来就跑完整业务逻辑
- 通了以后再加参数：先加流式，再加 system，再加工具调用，每次只动一个变量
- 把完整请求地址和返回体原文留一份，后面问客服时直接用
- 想量延迟基线可以到 /tools/speed-test 对同一地址测几轮，通不通和快不快是两个问题
排错的顺序永远是：先确认地址，再确认模型名，最后才怀疑 Key。
报错一：鉴权失败，先怀疑 Key 而不是网络
鉴权失败分两种表现：请求根本没到你预期的地址，或者到了但对方不认这把 Key。前者看地址拼写，后者看 Key 本身和请求头。别急着换网络或换电脑，那通常不是原因。
| 现象 | 优先怀疑 | 怎么改 |
|---|---|---|
| 提示未授权、缺凭据 | Key 复制时带了空格或换行 | 完整重粘一遍，确认尾部无空白 |
| 换客户端就通、换回来不通 | 客户端读的变量名或请求头不对 | 核对变量名，确认用的是这套协议的头 |
| 近期还能用突然不行 | Key 过期或额度用尽 | 到 /sites 看该站条目，必要时换一把 Key 再验 |
如果同一把 Key 在另一种协议下能通、在当前协议下不通，问题基本在那套客户端读的变量名或请求头，不在 Key。想按状态码往下分，可参照 /guides/401-vs-403-api-errors 的排查顺序走。
报错二与三：路径 404、模型名不存在
这两个报错常被当成一回事，其实原因完全不同：404 是地址问题，模型不存在是命名问题。把它们分开看，改起来各只有一两处。
- 404 多是把两套协议的路径拼串了：兼容协议下写了原生协议的后缀，或者反过来
- 也可能是 Base URL 里已经带了版本段，你又手动再加一次
- 报模型不存在，通常是你写的模型名不是这家中转站挂的别名，各家对同一个模型的命名并不统一
- 模型名一律从站内条目复制，不要凭记忆或从别家文档抄
- 改法固定成一条顺序：先核对地址原样抄回、再核对模型名、最后才怀疑 Key 权限
改完仍不通，把完整请求地址和返回体原文一起发给客服，比只贴一句「报错了」有用得多。中转站的模型清单和命名随时会调，去 /sites/all 看该站当前的条目，比翻旧教程靠谱。
下一步先到站点目录确认你用的这家挂了哪些 Claude 渠道、支持哪套协议，再回来看变量该怎么填；顺手用测速页留一条延迟基线，以后排查就知道是慢还是错。→常见问题
同一个 Key 在别的工具里能用，在我代码里就不行，为什么？
大概率是两套协议的差别。别的工具可能走 OpenAI 兼容格式，你代码里用的是 Anthropic 原生 SDK，路径和鉴权头都不一样。先确认代码里读的是哪个环境变量、请求打到哪个路径，再决定是换 SDK 还是换 Base URL 的后缀，不要在同一份代码里混着两套写法。
Base URL 到底要不要带 /v1？
看你走哪套协议，也看这家站自己的约定，没有统一答案。可靠做法是把站里给的地址原样复制，不要自己增删路径段；如果你不确定它给的是哪一套，就看它文档里示例请求的完整路径，照着写一遍。多拼或少拼一段，最典型的表现就是 404。
报错说模型不存在，是这家站没有这个模型吗？
不一定，更多是名字对不上。中转站常给模型挂自己的别名，和你从官方文档里抄来的名字可能差几个字符。到这家站的条目页把模型名整段复制过来再发一次；如果站里确实没挂，那就不是配置问题，换一个它列出来的模型做验证即可。
