CCSwitch 模型名总填错怎么办？

CCSwitch 配好多模型后，最常见的小问题不是不会填 Key，而是模型名、别名、默认项和 profile 说明越来越乱。一个字母错了，调用就失败；一个别名含义变了，团队就用错模型。

适用场景：多人共用配置，模型名越来越乱

这篇适合团队用 CCSwitch 管理多个供应商、多个模型、测试和正式 profile 的场景。典型表现是 Codex 调用时报模型不存在；同事复制了旧配置；测试模型被设成默认；文档里写的是别名，实际接口要真实模型名。如果你关注测试和正式 Key 隔离，可先看 CCSwitch 怎么区分测试 Key 和正式 Key；团队配置漂移可参考 团队里的 CCSwitch 配置不一致怎么排查。

先分清三类名字：真实模型名、显示名和任务别名

真实模型名是上游接口要求的值，不能随意改。显示名是给人看的，可以写得更清楚。任务别名是团队为了路由建立的简称，例如写作、代码、长文、低成本。把三类名字混在一个字段里，后面一定会出错。

操作步骤：建立一张可维护的模型表

1. 列出当前所有 profile

把 profile、API 地址、Key 权限、真实模型名、显示名、任务别名、默认状态和负责人列成表。不要只截图配置界面，因为截图无法比较变更。API 地址优先级问题可参考 Codex 调用的 API 地址为什么总是旧的。

2. 给别名加用途和边界

别名不要只叫 fast、pro、default。建议写清用途：短文本草稿、代码审查、长文摘要、低成本批处理、人工复核前预分类。每个别名都要说明不适合的任务，避免团队把低成本模型用于高风险合同摘要。

3. 固定测试提示词

每次新增或改模型名后，用固定提示词测试：一次简单中文回答、一次 JSON 输出、一次长上下文摘要和一次错误输入。测试结果记录时间、profile 和模型名。多模型路由可以看 CCSwitch 多模型怎么按任务切换。

4. 变更后同步文档和示例

配置改了，文档、脚本、环境变量示例和 Codex 任务说明也要同步。否则新同事复制旧文档，线上又会出现“明明配置了却调用旧模型”的问题。相关排查可看 CCSwitch 改了配置但 Codex 仍用旧模型怎么办。

常见问题/避坑：默认项最容易被忽略

第一个坑是把任务别名当真实模型名传给上游。第二个坑是测试 profile 和正式 profile 使用同一个显示名。第三个坑是默认模型悄悄变更，没有变更记录。第四个坑是只在一个人电脑上测试通过，团队其他机器仍是旧配置。

如果模型名填错，错误表现可能是 404、400、模型不存在、权限不足或回退到默认模型。不要只看前端报错，要查 CCSwitch 日志、上游返回体和 Codex 实际读取的配置。AI API 错误码分工可结合 AI API 返回 401、429、500 怎么分工排查。

命名治理也和费用有关。不同别名背后可能是不同价格和上下文能力，如果团队只看别名，不知道真实模型，就很难解释账单变化。费用归因可继续看 CCSwitch 调用费用对不上怎么办。

我建议把模型表放进团队文档，而不是只存在某个人本机配置里。表里加一列“最后验证时间”，每次修改后用固定提示词跑一次。这样下一次报错时，先看配置有没有过期，而不是每个人重新猜一遍模型名。

对于个人用户，也可以做一个简化版：只保留两个 profile，一个测试、一个正式；每个 profile 只设一个默认模型；新增模型先放到测试 profile，用固定提示词验证后再决定是否加入正式配置。少即是多，尤其适合刚开始做 Codex 接入的新手。若仍然频繁填错，就把旧别名标记为停用，并在备注里写清替代项。

检查清单：模型名治理是否到位

• 是否区分真实模型名、显示名和任务别名。
• 是否记录 profile、API 地址、Key 权限和负责人。
• 默认模型变更是否有时间、原因和验证记录。
• 新增模型是否用固定提示词做回归测试。
• 团队文档、脚本示例和环境变量是否同步更新。
• 是否能从调用日志追到真实模型名，而不是只看到别名。

验收标准：配置能被复制，也能被解释

合格的 CCSwitch 模型命名规范，应让新同事复制配置不容易填错，让异常调用能追到真实模型，让默认项变更有记录。永沃云枢建议把模型表和 CCSwitch 配置专题 一起维护，后续在 https://ai.jn83.com 做 AI 模型接口和模型调用管理时，减少小配置造成的大排查。