常见问题

先按“现象”找答案。不要同时修改多个配置，否则很难判断哪一步解决了问题。

先做四项基础检查

1. API Key 已替换占位符，并且没有多余空格或换行。
2. 账户余额、Key 额度和目标分组可用。
3. Base URL 与工具类型匹配。
4. 当前 Provider、Profile 或模型选择器确实切到了 BestAI。

Base URL 速查

工具类型	通常填写
Claude Code / Anthropic SDK	https://api.bestai.chat
Codex CLI / App	https://api.bestai.chat
OpenAI SDK（含 Responses）/ OpenAI 兼容工具	https://api.bestai.chat/v1

如果控制台的 API 端点提示不是以上地址，以控制台当前显示为准。

普通 Base URL 不要填写完整接口，例如：

https://api.bestai.chat/v1/chat/completions
https://api.bestai.chat/v1/responses
https://api.bestai.chat/v1/messages

这些完整路径只用于 curl 测试，或用于明确要求完整 URL 的字段。

401 或 403

通常是认证、额度或分组问题。

按顺序检查：

1. Key 是否完整，是否仍然是 sk-你的Key 这样的占位符。
2. 环境变量是否存在，但不要打印 Key 内容：

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"

3. Claude Code 是否同时存在互相冲突的 ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN 或 apiKeyHelper。两种变量各自都可用于 BestAI；按采用的方案保留一种，用 /status 核对实际认证来源。
4. 仪表盘中的余额、Key 额度和分组是否可用。
5. 当前工具是否真的使用了 BestAI Provider。Codex 使用本文的 env_key 方案时，还要确认没有设置 requires_openai_auth = true。

不要把完整 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。模型回复“已连接”不能证明请求路径，日期或筛选不匹配也会让记录暂时看不到。

1. 在使用记录刷新，确认日期范围包含验证时间，重置不确定的筛选。
2. 按所用 Key、模型和时间查找，避免误认其他工具同时发出的请求。
3. 确认当前会话选中的 Provider / Profile，以及对应的 Base URL 和 Key。
4. 需要重新加载配置时，在已设置变量的同一个终端重启工具，再发送一条短验证句；临时变量不会自动传给新开的终端。
5. 请求结束后再次核对记录；仍无结果时保留请求时间、模型和脱敏错误信息供排查。

只有“工具有回复 + 使用记录有对应请求”才算接入完成。

429、请求过大或超时

• 429：先读错误代码。额度耗尽需要处理额度，并发或队列限制需要减慢提交；不是所有 429 都能靠重试解决。见429 原因与处理。
• 400 / 413：分别检查参数与协议、附件和总请求大小。见HTTP 状态速查。
• 超时 / 输出中断：保留部分结果，先核对记录，再决定是否重发。见失败阶段与流式结束判断。

502 或 503

通常是上游通道、模型可用性或瞬时网络问题。

1. 记录发生时间、模型 ID 和脱敏错误正文。
2. 查看分组状态，按错误提示处理或稍后重试一次。不要自动循环重试或不断切换模型，额外请求可能产生用量。

不要因为一次 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：

test -n "$BESTAI_API_KEY" && echo "BESTAI_API_KEY is set" || echo "BESTAI_API_KEY is missing"
codex

如果 CLI 可以、App 不可以，检查 App 使用的 CODEX_HOME、配置文件和进程环境。写入 .zshrc 不代表桌面应用一定读得到变量。按Codex 桌面接入说明检查，并在 App 中单独发出请求、核对记录。

Key 额度耗尽

在 API Keys 查看该 Key 的额度和已用额度，在 仪表盘 查看账户余额。

额度限制、账户余额和分组限制是不同层级；提高其中一项不一定会解除另一项限制。

curl 最小测试

先选和出错工具相同的协议；不能用 Chat Completions 测试替代所有客户端的验证。保持 Key、模型、短提示词和网络环境一致，按协议选择最小请求。成功返回后，再到使用记录核对。

仍然无法定位时，填写排障反馈模板，保留状态、时间和请求标识，去掉密钥与业务正文。