使用指南
常见问题
连接失败时，从地址、密钥、分组和模型四项开始检查。
先看错误，再找原因
错误码用于定位方向，最终原因以接口返回的错误信息为准。
| 现象 | 优先检查 |
|---|---|
| 401 / 密钥无效 | 密钥是否完整、有无前后空格、是否已过期或被删除；是否用了码头签发的密钥。 |
| 403 / 无权访问 | 厂商与分组、模型权限、IP 限制，以及账号是否被禁用。 |
| 余额或额度不足 | 账号余额、订阅是否有效、密钥限额和分组配额；以具体错误提示为准。 |
| 404 / 路径不存在 | Base URL 是否重复添加 /v1，或误填了登录页、完整请求路径；协议是否匹配。 |
| 模型不可用 | 模型 ID 的拼写、分组支持情况及上游状态。模型列表可见不等于每次调用都能成功。 |
| 429 / 请求太多 | 速率、并发和配额限制。按提示等待并降低并发，不要连续点击重试。 |
| 5xx / 超时 | 检查网络与服务状态，稍后用简单任务重试；记录错误时间与请求 ID。 |
配置好了，却没有生效
CC Switch 切换后仍在使用原来的服务
确认切换的是当前客户端，供应商已启用；完全退出客户端再打开。检查系统环境变量、CC Switch 本地代理与用户配置是否存在冲突。先备份再调整，避免盲目删除配置。
Codex 仍提示登录，或一直连接中
先核对 Base URL、认证模式与配置位置。上面的直接密钥模式使用 requires_openai_auth = false 与 experimental_bearer_token；不能同时混入另一套 auth.json 或 env_key 配置。已经登录过其他模式时，按客户端当前提示切换认证并重启。
若当前桌面版本不识别该供应商，参考控制台生成配置和官方版本说明。不要因此关闭系统安全保护或安装来源不明的修改版客户端。
Claude Code 默认模型报错
默认模型可能不在你的分组内。在控制台查看支持的模型 ID，使用 /model 选择，或按「使用密钥」中的模型配置操作。不要照搬其他中转站的模型名与分组。
配置文件格式错误
JSON 使用英文双引号，最后一项后面不能带逗号；TOML 不要重复声明同一个字段。先恢复备份，再只修改连接所需的设置。
联系支持前，准备这些信息
- 使用的工具、版本，以及 Windows / macOS 系统版本。
- 出错时间、模型 ID、分组名称与错误提示。
- 请求 ID（如果有），以及已打码的截图。
请通过控制台实际展示的支持渠道联系管理员。不要发送完整 API Key、auth.json 或未经打码的配置截图。
参考与适用范围
本教程以码头中转站的入口与分组为基础编写。客户端界面随版本变化，具体按钮名称与可用模型以实际页面为准。
- Totokens 教程：作为教程结构参考，本站文案与操作示意重新编写。
- CC Switch 官方发布页
- OpenAI Codex 配置说明
- Claude Code 网关说明
本教程已核对站点地址、厂商分组及配置文档；尚未在 Windows / macOS 各版本客户端逐一进行真实模型调用。