外观
常见问题
先按“现象”找答案。不要同时修改多个配置，否则很难判断哪一步解决了问题。
先做四项基础检查
- API Key 已替换占位符，并且没有多余空格或换行。
- 账户余额、Key 额度和目标分组可用。
- Base URL 与工具类型匹配。
- 当前 Provider、Profile 或模型选择器确实切到了 BestAI。
Base URL 速查
| 工具类型 | 通常填写 |
|---|---|
| Claude Code / Anthropic SDK | https://api.bestai.chat |
| Codex / OpenAI Responses | https://api.bestai.chat |
| OpenAI SDK / OpenAI 兼容工具 | https://api.bestai.chat/v1 |
如果控制台的 API 端点提示不是以上地址，以控制台当前显示为准。
普通 Base URL 不要填写完整接口，例如：
text
https://api.bestai.chat/v1/chat/completions
https://api.bestai.chat/v1/responses
https://api.bestai.chat/v1/messages这些完整路径只用于 curl 测试，或用于明确要求完整 URL 的字段。
401 或 403
通常是认证、额度或分组问题。
按顺序检查：
- Key 是否完整，是否仍然是
sk-你的Key这样的占位符。 - 环境变量是否存在，但不要打印 Key 内容：
bash
test -n "$ANTHROPIC_API_KEY" && echo "ANTHROPIC_API_KEY is set" || echo "ANTHROPIC_API_KEY is missing"
test -n "$BESTAI_API_KEY" && echo "BESTAI_API_KEY is set" || echo "BESTAI_API_KEY is missing"- Claude Code 是否同时存在旧的
ANTHROPIC_AUTH_TOKEN。存在时先关闭 Claude Code，再按对应指南清理旧配置。 - 仪表盘中的余额、Key 额度和分组是否可用。
- 当前工具是否真的使用了 BestAI Provider。
不要把完整 Key 发到截图、聊天或公开仓库中。怀疑泄露时直接停用旧 Key 并创建新 Key。
404
优先检查 Base URL 是否填成了完整 endpoint，或是否把 OpenAI、Anthropic 和 Images API 的地址混用了。
| 场景 | 地址 |
|---|---|
| Claude Code / Anthropic | https://api.bestai.chat |
| Codex Responses | https://api.bestai.chat，配置 wire_api = "responses" |
| OpenAI SDK | https://api.bestai.chat/v1 |
如果是 Codex，base_url 不要写成 /responses；如果是 OpenAI SDK，通常需要保留 /v1。
有回复但没有账单
这通常说明回复来自其他 Provider、旧配置或本地会话，而不是当前 BestAI Key。
- 确认当前会话选中的 Provider / Profile。
- 确认 Base URL 是 BestAI 地址。
- 关闭并重新打开工具，让新的环境变量生效。
- 发送短验证句，不要先运行长任务。
- 在 使用记录 按时间查找请求。
只有“工具有回复 + 使用记录有对应请求”才算接入完成。
502 或 503
通常是上游通道、模型可用性或瞬时网络问题。
- 记录发生时间、模型 ID 和完整错误文本。
- 等待 1-2 分钟后，用同一个 Key 测试另一个可用模型。
不要因为一次 502 就重复创建大量 API Key；Key 不会修复上游通道问题。
配置在重启后失效
export 只对当前终端窗口生效。长期使用需要：
- Claude Code：写入
~/.claude/settings.json，或写入~/.zshrc/~/.bashrc。 - Codex：写入
~/.codex/config.toml，并把 Key 保存到长期环境变量。 - 图形化工具：在工具的 Provider 设置中保存，而不是只在终端临时设置。
修改 shell 配置后，重新打开终端或执行对应的 source 命令；修改桌面应用配置后，完全退出并重新启动应用。
Codex App 读不到环境变量
Codex 默认使用 $CODEX_HOME/config.toml，CODEX_HOME 未设置时通常是 ~/.codex。
先在终端验证 CLI，再打开 App：
bash
test -n "$BESTAI_API_KEY" && echo "BESTAI_API_KEY is set" || echo "BESTAI_API_KEY is missing"
codex如果 CLI 可以、App 不可以，检查 App 使用的 CODEX_HOME 和配置文件是否与终端相同。不要把个人自定义目录写成所有用户的固定路径。
Key 额度耗尽
在 API Keys 查看该 Key 的额度和已用额度，在 仪表盘 查看账户余额。
额度限制、账户余额和分组限制是不同层级；提高其中一项不一定会解除另一项限制。
curl 最小测试
当工具行为不明确时，可以先用 curl 分离“服务端问题”和“工具配置问题”。模型 ID 使用控制台配置提示或工具当前配置中的值：
bash
export BESTAI_API_KEY="sk-你的Key"
export BESTAI_MODEL="工具当前配置中的模型 ID"
curl -sS "https://api.bestai.chat/v1/chat/completions" \
-H "Authorization: Bearer $BESTAI_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"model\":\"$BESTAI_MODEL\",\"messages\":[{\"role\":\"user\",\"content\":\"只回复：BestAI curl ok\"}]}" \
-w "\nHTTP %{http_code}\n"测试后不要把带真实 Key 的命令复制到公开位置。成功返回后，再回到 使用记录 核对请求。