CCSwitch 里的模型别名要下线，怎么迁移才不影响旧任务？
CCSwitch 模型别名退役前，应建立别名映射、旧任务扫描、灰度迁移和回滚记录，避免历史任务继续引用失效模型名。
- 站内相关：ccswitch-model-alias-environment-map-2026-07-21
- 站内相关：ai-model-profile-version-pinning-2026-07-23
- 站内相关：ccswitch-team-profile-naming-convention-2026-07-31
- 站内相关：ccswitch-response-format-compatibility-check-2026-08-02
- AI API 接入专题
- Codex 安装专题
- CCSwitch 配置专题
- AI 自动化办公专题
- Codex 实操与 AI 资讯栏目
真实问题
团队使用 CCSwitch 配置多模型接口时，常会为了方便给模型起别名，例如 fast、office、reasoning 或 backup。前期这样做很顺手，但当某个模型别名要下线、换供应商或调整能力等级时，旧任务、脚本、Codex 配置和 AI 自动化办公流程可能仍然引用旧名字。表现出来可能是模型找不到、响应格式变化、费用突然升高，或某些历史批处理结果变差。永沃云枢在 https://ai.jn83.com 建议把别名退役当成迁移项目，而不是简单改名。
适用场景
适合已经用 CCSwitch 管理多个 profile 的团队，特别是同时服务 Codex 接入、AI API 接入、知识库问答和办公自动化的环境。只要别名被写进脚本、环境变量、用户文档、队列任务或前端下拉框，就不能直接删除。模型别名迁移还适用于从测试模型切到生产模型、从便宜模型切到高质量模型、或把临时备用项合并到正式配置。
操作步骤
第一步，导出现有 profile 和模型别名清单，记录别名、真实模型名、base_url、权限、预算和负责人。第二步，用搜索找出旧别名出现的位置，包括配置文件、任务模板、文档、定时批处理和 Codex 提示词。第三步，新建新别名，不要覆盖旧别名，并在备注里写清迁移窗口。第四步，选择只读任务或内部任务灰度运行，比较响应格式、耗时、费用和人工评分。第五步，把旧别名改成只读或低优先级保留，等历史队列清空后再删除。
排错路径
如果迁移后 JSON 字段变了，先参考响应格式兼容检查，不要只改前端解析。若旧任务继续命中新模型，检查是否有默认 profile 指向新别名。若费用升高，查看是否把摘要类任务迁移到了推理能力过高的模型。若 Codex 运行时仍报旧别名不存在，检查本机配置缓存、项目环境变量和团队共享说明是否同步。若部分用户成功、部分失败，重点看用户所属项目是否使用了不同 CCSwitch profile。
常见问题 / 避坑
问：能否保留同一个别名但指向新模型？可以，但必须有灰度和回滚记录，否则问题发生时无法解释变化来源。问：旧别名是否要永久保留？不建议，长期保留会让文档和真实配置越来越不一致。问：GPT 中转这类说法能否写进别名？不建议，它更像搜索词，内部别名应描述能力、环境和用途。问：迁移是否只看连通性？不够，还要看响应结构、质量、成本和工具调用兼容性。
检查清单
检查旧别名所有引用位置已扫描；检查新别名有清晰命名和负责人；检查灰度样本覆盖短问答、长上下文、结构化输出和工具调用；检查回滚只需要恢复别名映射；检查用户文档没有把临时别名写成长期入口；检查 AI API 接入和 AI 自动化办公任务都完成一次真实调用验收。
验收标准
迁移完成后，随机抽取三条历史任务复跑，确认输出可接受；检查 24 小时内旧别名调用量是否下降到预期；确认 sitemap、帮助文档或内部教程没有继续推荐旧名称。对于模型调用管理平台，还要保存迁移前后配置快照。这样即使后面有人问“为什么同一个任务输出变了”，也能回到明确的别名变更记录。
复盘建议
复盘时把别名迁移表留下来：旧别名、新别名、真实模型、影响入口、灰度样本、回滚方式和删除时间。这个表比口头说明更可靠，也能帮助后续 Codex 接入任务判断该用哪个 profile。
补充检查
别名迁移还要关注文档和培训材料。很多失败不是来自线上配置，而是新人照着旧截图填写 profile，或者把测试别名复制进生产任务。建议在迁移窗口内保留一个只读提示页，写明旧别名停止使用的日期、新别名用途、适用模型接口和回滚联系人。若站内帮助页、Codex 提示词模板、AI 自动化办公脚本都引用同一别名，就要同步更新，不能只改 CCSwitch 主配置。
继续前的人工确认
如果别名迁移牵涉多个团队，最好设置一个短冻结期：冻结期内只允许新增新别名和修正文档，不允许再把旧别名指向第三个模型。负责人每天检查一次旧别名调用量、失败样本和费用变化。等旧队列清空后，再安排删除动作。这个节奏比一次性改完慢一些，但能让 AI API 接入、Codex 接入和 AI 自动化办公任务都留下可追踪证据。