连接成功为什么还不能调用模型
网络连通只说明电脑能找到目标主机或端口，不能证明请求路径、鉴权头、模型名和响应协议都正确。比如 base_url 已经包含一段版本路径，客户端又自动拼接一次；或者测试 profile 能通过健康探测，但正式 profile 使用了已下线的模型别名。这些问题都会让 CCSwitch 看起来“在线”，实际任务却失败。
排查时不要先连续切换模型。先把当前 profile、配置来源和实际请求摘要保存下来，再用一个最小文本样本验证。这样可以区分 CCSwitch 配置问题、AI 模型接口问题和业务调用代码问题。
适用场景
适合个人电脑配置、团队共享 profile、Codex 接入、开发者 AI 调用和 AI 自动化办公。只要同一台机器上存在主路由、备用路由、测试路由或多个环境，就应该明确当前任务使用哪个 profile，不能只看列表里是否有一个相似的模型名字。
操作步骤：按四层检查，不要只看绿灯
- 记录配置来源。确认 CCSwitch 当前加载的是哪一个文件、环境变量或 profile，记下 profile 名、版本、更新时间和目标环境。先排除改了 A 文件却实际读取 B 文件。
- 检查
base_url形态。把主机、版本路径和资源路径分开看，确认是否重复拼接/v1、是否多了空格、是否把网页地址误当成 API 地址。只修改规范的接口字段，不要把完整 Key 贴进截图。 - 检查鉴权和模型名。对照接口要求的 Header、Key 作用域、模型别名和大小写。连接测试通过但模型调用失败，通常要看服务端返回的错误对象，而不是继续测试端口。
- 用最小样本验证路由。只发一条短文本，记录 requested_model、命中的 profile、selected_model、HTTP 状态、finish_reason 和原始错误类别。确认成功后，再跑 JSON、流式或 Codex 工具调用样本。
若仍然失败，可以把配置拆成三份对比：主路由、备用路由、已知可用的本地样例。每次只改变一个变量，改变后立刻记录结果。关于“网络通但模型不通”的分层思路，可参考 CCSwitch 健康探测与回退；如果修改后客户端仍使用旧值，可查看 配置没有生效的排查记录。
常见问题 / 避坑
最常见的坑是把 base_url 填成浏览器能打开的网页地址，或者把完整接口路径填到一个会自动拼接路径的客户端里。第二个坑是 profile 名字相同但环境不同，测试时命中了开发接口，正式任务却走生产接口。第三个坑是模型别名在网关和上游不一致，列表能显示，实际调用时却被拒绝。
还要留意缓存。CCSwitch、终端环境和 Codex 进程可能分别缓存旧配置，改完文件不等于正在运行的进程已经重新加载。排查时关闭多余进程，重新打开一个明确工作区，再做一次最小调用。必要时把配置版本写进日志，便于 AI API 接入和模型调用管理复盘。相关入口可查看 CCSwitch 配置专题、AI API 接入专题 和 Codex 接入专题。
检查清单
- 当前 profile、配置文件、环境变量和运行进程已经对应。
- base_url 的主机、版本路径和资源路径没有重复或遗漏。
- 鉴权字段、模型名和别名与目标 AI 模型接口的要求一致。
- 最小文本调用能够记录请求模型、命中 profile、实际模型和错误类别。
- 更换配置后已经重启或重新加载实际使用的客户端进程。
- 测试、生产和备用 Key 没有混用，日志和截图已经完成脱敏。
验收标准
验收不是看到 CCSwitch 显示绿色连接，而是同一 profile 能完成最小文本调用，并且日志能解释请求走了哪里。若任务还需要 Codex 工具、严格 JSON 或流式输出，则必须在对应能力上单独做样本，不要用普通聊天成功替代完整验收。
配置复盘怎么写
复盘记录保留五项就够：配置来源、base_url 结构、模型别名、命中的 profile、最小样本结果。不要保存秘密值，也不要把临时切换写成永久规则。以后新增 AI 模型接口时，复制这五项做对照，能更快判断是地址错误、鉴权错误、模型错误还是路由优先级错误。
不要把健康探测当成完整验收
健康探测可以先证明地址存在，但不能证明模型接口、鉴权和响应格式都适合当前任务。建议把探测分成三层：地址探测、最小文本调用、真实能力样本。每层都记录 profile 和配置版本。只有最小文本和真实样本都通过，才把 profile 标记为可用于开发者 AI 调用或自动化办公；否则只能标记为待排查，不能因为界面显示在线就放进正式任务。
重试样本怎么留
遇到失败时，保留一次成功 profile 和一次失败 profile 的脱敏对比，字段只包含地址结构、模型名、状态码和错误类别。每次只改一个字段，再重新跑短文本样本。这样既能证明修复有效，也能避免同时更换模型、Key 和路由后无法判断真正原因。
延伸阅读
更多 CCSwitch 配置、AI API 接入、开发者 AI 调用和模型调用管理实践，可继续阅读永沃云枢在 https://ai.jn83.com 的专题内容。