报错代码分别是什么意思？
| 状态码 | 意思 | 怎么处理 |
|---|---|---|
| 401 | Key 不对、被停用或已删除 | 去 API Key 页面确认 Key 还在；重新复制，注意别少了开头的 sk- 或多了空格换行。 |
| 403 | 余额不够，或这个 Key 不能用这个模型 | 去 控制台 看余额，不够就 充值；余额够的话换一个模型试试。 |
| 404 | 模型名写错，或地址拼错 | 从 模型页 原样复制模型名；检查 ANTHROPIC_BASE_URL 是不是 https://api.macloudai.com，结尾没有 /v1。 |
| 429 | 请求太快 | 等几秒再试；同时开了很多个 Claude Code 窗口的，先关掉几个。 |
| 5xx（500、502、503、529 等） | 上游模型暂时出错或繁忙 | 过一会儿重试；一直不行就先换同家族的另一个模型。 |
| 连接超时 / ECONNREFUSED / ENOTFOUND | 网络没连上接口 | 看下面“终端代理和公司网络”一节。 |
按这个顺序排查
- 在出问题的同一个终端里运行
echo $ANTHROPIC_BASE_URL（Windows PowerShell 用$env:ANTHROPIC_BASE_URL），确认打印的是https://api.macloudai.com，结尾没有/v1、没有多余的斜杠或空格。 - 同样检查
ANTHROPIC_AUTH_TOKEN是不是你控制台里现有的 Key，ANTHROPIC_MODEL是不是模型页上的完整名字。 - 用下面的 curl 命令绕过 Claude Code 直接测一次接口：curl 能通，问题就在 Claude Code 配置；curl 也不通，看返回的状态码。
- 在 Claude Code 里运行
/status，看它实际用的地址和认证方式；如果显示的是官方登录账号，按下文处理登录冲突。 - 打开控制台 用量：如果刚才的请求出现在列表里，说明已经连上了，问题在模型或余额；没出现，说明请求根本没到。
- 还不行就把报错原文、操作系统、Claude Code 版本和这次的时间发给客服。
curl https://api.macloudai.com/v1/messages \
-H "x-api-key: $ANTHROPIC_AUTH_TOKEN" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model": "hk-5-5", "max_tokens": 50, "messages": [{"role": "user", "content": "你好"}]}'$body = '{"model": "hk-5-5", "max_tokens": 50, "messages": [{"role": "user", "content": "hi"}]}'
Invoke-RestMethod -Uri "https://api.macloudai.com/v1/messages" -Method Post -ContentType "application/json" `
-Headers @{ "x-api-key" = $env:ANTHROPIC_AUTH_TOKEN; "anthropic-version" = "2023-06-01" } `
-Body $body注意 curl 里的地址是 https://api.macloudai.com/v1/messages，这是完整接口路径；而 ANTHROPIC_BASE_URL 只填到 https://api.macloudai.com，/v1/messages 由 Claude Code 自己拼上。
base URL 多写了 /v1 会怎样？
这是最常见的 404 原因。很多教程给 OpenAI 格式工具写的是 https://api.macloudai.com/v1，有人顺手也填进了 Claude Code。Claude Code 会在你填的地址后面再加 /v1/messages，结果请求打到 /v1/v1/messages，接口不存在就返回 404。
- Claude Code、Anthropic SDK、Cline 的 Anthropic 模式：填
https://api.macloudai.com。 - Cursor、OpenAI SDK、Cline 的 OpenAI Compatible 模式、LobeChat：填
https://api.macloudai.com/v1。 - 结尾也不要多一个
/，有些工具会拼出//v1导致失败。
环境变量设了却没生效？
典型表现是：明明设了中转，Claude Code 还是让你登录官方账号，或者报“缺少 API Key”。原因通常是下面几种：
- 写进了
~/.zshrc却没source，也没开新终端。macOS 用的是 zsh，写进~/.bash_profile是不会被读的。 - Windows 用
setx设的变量只对新窗口生效；VS Code / Cursor 内置终端要把整个编辑器重启。 - 在 WSL 里运行 Claude Code，但变量设在了 Windows 那边（或者反过来）。
~/.claude/settings.json的 JSON 格式错了（多了逗号、用了中文引号），整个文件被忽略。可以把内容贴进任意 JSON 校验工具检查。- 项目里的
.claude/settings.json或.claude/settings.local.json写了另一套env，把你家目录的配置覆盖了。
登录了官方账号又设了中转，冲突怎么办？
如果你以前用 Claude Pro / Max 账号登录过 Claude Code，又设了 ANTHROPIC_AUTH_TOKEN，Claude Code 可能会提示认证冲突，或者继续用官方账号的额度，不走中转。处理方法：
- 在 Claude Code 里运行
/logout退出官方账号。 - 确认
ANTHROPIC_AUTH_TOKEN和ANTHROPIC_API_KEY只设了一个（按本站文档用前者），另一个用unset ANTHROPIC_API_KEY删掉。 - 重新运行
claude，再用/status看认证方式是否变成了环境变量里的 Token。
终端代理和公司网络的问题
在新加坡、欧美的公司里上班，或者电脑上开了代理工具，经常会遇到连接超时、证书错误（如 SELF_SIGNED_CERT_IN_CHAIN、unable to get local issuer certificate）。
- 终端不会自动用系统代理。如果你的网络必须走代理，设
HTTPS_PROXY（例如export HTTPS_PROXY=http://127.0.0.1:端口）；不需要代理却设了，反而要unset HTTPS_PROXY HTTP_PROXY ALL_PROXY去掉。 - 公司网络做了 HTTPS 检查时，会用公司自己的根证书。向 IT 要这个证书文件，设
NODE_EXTRA_CA_CERTS=/证书路径.pem让 Claude Code（基于 Node.js）信任它。 - 公司防火墙只放行白名单网站时，请 IT 放行
https://api.macloudai.com这个域名。 - 先用手机热点试一次：热点能通、公司网络不通，就是网络限制，不是配置问题。
排查网络时别把 Key 贴到公开的群或 issue 里。截图前把 sk- 后面的部分打码；万一泄露，去 API Key 删掉旧 Key 再建一个，旧 Key 立刻失效。
模型能用，但突然变慢或中断？
长对话里 Claude Code 每一步都要发送大量上下文，单次请求可能很大，响应自然变慢。先 /compact 或 /clear；如果是上游繁忙（5xx、529），等几分钟再继续，或者临时换另一个模型。配置相关的完整说明见 Claude Code 中转怎么配置 和 接入文档。
