错误代码对照表

按常见程度降序排列，90% 的问题都在这一页。

速查表

错误信息	状态码	根因	跳转
Invalid token / Auth rejected	401	Key 错或失效	→ 详情
No available accounts	503	号池暂时无可用账号	→ 详情
Service unavailable	503	上游服务抖动	→ 详情
Upstream access forbidden	502	上游封禁（严重）	→ 详情
user agent not allowed	400	UA 不在白名单	→ 详情
model_not_found / 分组无渠道	503	当前 Key 分组没有该模型	→ Key 分组
model_not_found	503	模型不在 channel	→ 模型对照
Invalid URL /v1/v1/messages	404	base_url 多了 /v1	→ base_url
一直 retry / Propagating	—	上游慢 / 配置或路由异常	→ 详情
install.sh ✅ 但找不到 claude	—	安装阶段下载失败	→ 详情
command not found: claude	—	PATH 没加	→ 详情
程序"claude.exe"无法运行	—	npm 残留 / 缺 Git for Windows	→ 详情
claude --version 报错	—	PowerShell 执行策略	→ 详情
npm -v not recognized	—	Node.js 未装 / PATH 缺	→ 详情
npm error EACCES	—	npm 全局权限	→ 详情

错误严重度

等级	含义	例子
🟢 易修	改配置即可	401 / 404 base_url 错
🟡 中等	等几分钟或换模型	503 / retry / model_not_found
🔴 严重	需联系管理员	502 Upstream forbidden

按客户端归类

Claude Code

• 一直 retry / Propagating
• App unavailable in region
• Opus 频繁 503

Codex CLI

• 404 /v1/responses
• Not inside a trusted directory
• Missing environment variable: OPENAI_API_KEY

CC Switch

• Auth rejected (401) 启动检查误报
• Service unavailable (503)

自助诊断 5 步

遇到问题先按这个顺序排查：

1. 检查环境变量

# bash / zsh
echo $ANTHROPIC_BASE_URL
echo $ANTHROPIC_AUTH_TOKEN

# fish
echo $ANTHROPIC_BASE_URL
echo $ANTHROPIC_AUTH_TOKEN

两个都应该有输出。空输出 = 没生效。

2. base_url 写对了吗

客户端	base_url 是否带 /v1
Claude Code	❌ 不带：https://shuro.vip
Codex CLI	✅ 带：https://shuro.vip/v1
OpenAI SDK	✅ 带：https://shuro.vip/v1

base_url 写错

Claude Code 会自己拼 /v1/messages。如果你填 https://shuro.vip/v1 → 拼成 /v1/v1/messages → 404 → 客户端无限 retry。

3. curl 直连验证 key 有效

curl -sS -X POST 'https://shuro.vip/v1/messages' \
  -H 'content-type: application/json' \
  -H 'anthropic-version: 2023-06-01' \
  -H 'x-api-key: <您的 API Key>' \
  -d '{"model":"claude-haiku-4-5-20251001","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

返回	含义
✅ 200 + Hi 响应	key OK，问题在客户端配置
❌ 401	Key 失效/拼错 —— 去 控制台 重新生成
❌ 503	上游号池问题，等几分钟
❌ 完全无响应	网络问题，看 代理设置

4. 看日志详情

Shuro 控制台 → 「日志」 → 失败请求 → 详情。会显示上游真实错误（不是客户端包装后的版本）。

5. 还不行？换 Provider 试

如果你装了 CC Switch，一键切到 Claude Official，如果切完能跑 → 是 Shuro 问题；如果还不行 → 是客户端或网络。

Codex 404 /v1/responses

unexpected status 404 Not Found: Invalid URL (GET /v1/responses)

原因 1：你的 API Key 只有 Claude 权限，没 OpenAI 权限。

原因 2：config.toml 里 base_url 漏了 /v1。

解决：

• 确认当前 Key 的分组是否包含 GPT 系列模型（TODO/VERIFY：Shuro 反馈渠道待确认，如需开通请向平台反馈）
• 检查 base_url 是 https://shuro.vip/v1 不是 https://shuro.vip

base_url 写错

HTTP=404: /v1/v1/messages

客户端自带路径拼接逻辑，base_url 只填根域名：

客户端	正确 base_url
Claude Code	https://shuro.vip
Codex CLI	https://shuro.vip/v1
OpenAI Python SDK	https://shuro.vip/v1
Anthropic Python SDK	https://shuro.vip

找不到答案？

• 看 FAQ
• 向平台反馈（TODO/VERIFY：Shuro 反馈渠道待确认）