常见问题

优先检查三项：地址是否匹配协议、Key 是否完整、模型 ID 是否可用。修改后重新启动客户端，再发起一次简单请求。

401：认证失败

1. 确认已将 sk-your-api-key 换成自己的密钥，前后没有空格或换行。
2. 在 API Keys 页面确认 Key 未停用或失效。
3. 检查客户端实际读取的认证来源：配置文件、环境变量或供应商切换工具。

余额不足是另一个检查项，以接口返回的错误内容和控制台余额为准，不要把所有扣费问题都当成 401。

404：地址错误或模型不可用

先查看返回内容，区分路由不存在和模型不存在。

使用方式	应填写
Claude Code Base URL	https://one-model.com
OpenAI Base URL / Codex	https://one-model.com/v1
完整 Chat Completions URL	https://one-model.com/v1/chat/completions

检查最终请求地址是否重复 /v1。模型 ID 应与 模型页面 一致，还要确认 Key 的分组可以访问该模型。

400：参数不支持

先关闭可选的思考强度、图片输入或其他高级设置，使用文本消息验证基础调用。再根据模型支持的能力逐项打开。

Codex 需要 Responses 兼容能力；不要仅凭客户端支持 OpenAI 格式就推断所有模型功能完全一致。

429：请求受限

查看错误内容，区分请求频率、并发或额度限制。降低并发、稍后重试，并在控制台核对额度和 Key 设置。如果响应提供重试时间，按提示等待。

连接超时或响应较慢

1. 确认本地网络可以访问 OneModel。
2. 切换到 备用线路，只替换域名，保留协议路径。
3. 长上下文或复杂推理可能需要更多时间，可先用简短消息检查连接。
4. 若出现 5xx，记录发生时间和接口返回的请求标识，稍后重试。

修改了配置却没有生效

• 保存文件，关闭并重新打开终端、客户端或 IDE。
• 检查修改的是当前用户实际使用的配置目录。
• 检查项目级配置、环境变量和 CC Switch 是否覆盖了手动配置。
• Codex 的环境变量应在启动它的同一个终端中设置。

Cherry Studio 中找不到刚添加的模型

在服务商页面获取模型列表并添加需要的模型，再打开服务商右上角的启用开关。回到聊天窗口重新选择模型。

Trae 中选不了自定义模型

按原教程，自定义模型需要关闭模型菜单中的 Auto Mode。不同版本的入口可能调整，请检查当前版本是否提供自定义模型功能。

在哪里查看消费明细？

打开 用量页面，核对模型、输入、输出、缓存读取和扣费。估算方法见 计费与用量。

排查后仍无法连接

保留客户端名称与版本、模型 ID、使用的地址、发生时间、HTTP 状态码和脱敏后的错误内容。分享截图或日志前隐藏 API Key，便于后续定位问题。