真实问题：换模型后文本能回，工具却不动
CCSwitch 配置的价值在于把多个 profile 管起来，但“能请求成功”不代表“能力一样”。一个模型可以稳定聊天，却不一定支持工具调用；一个模型能输出 JSON，却可能不接受严格 JSON Schema；一个模型支持流式输出，分片格式又可能和前端或 Codex 插件预期不同。于是团队把默认模型切到备用 profile 后，表面上 AI API 接入仍是 200，实际工具没有触发、函数参数为空、自动化办公流程停在中间。
这类问题不能靠临时猜测。切换前应该先建能力矩阵，把每个 profile 能做什么、不能做什么、需要什么参数和失败时怎么回退写清楚。永沃云枢在日常排障中，通常把健康探测和能力验收分开：探活只证明可连通，能力矩阵才证明可用于具体任务。
适用场景
适合团队共用 CCSwitch 配置、多模型备用、Codex 需要调用工具、开发者 AI 调用依赖 JSON、客服工单或表格流程需要自动写回、AI 自动化办公要同时处理文本和结构化字段的场景。尤其是准备把测试 profile 推到正式环境前，不要只跑一句“你好”，而要跑真实样本：一次工具调用、一次结构化输出、一次长上下文、一次流式显示和一次失败回退。
能力矩阵怎么写
矩阵至少包含这些列：profile 名称、模型名、base_url、是否支持工具调用、是否支持严格 JSON Schema、流式分片格式、最大上下文、超时阈值、重试策略、费用标签、适用任务、禁止任务、回退 profile、样本记录。每一列都要用可验证事实填写，不要写“应该支持”。如果文档不清楚，就用小样本证明，例如让模型调用一个只读天气工具、生成固定字段 JSON、输出 30 秒流式文本，再观察返回结构。
矩阵还要记录负面能力。比如某 profile 不适合代码修改，不适合批量财务摘要，不适合工具链任务。这些限制比优点更重要，因为路由一旦出错，任务会悄悄降级。模型调用管理不是把所有模型放进列表，而是把任务和能力对齐。
操作步骤
第一步，从现有 CCSwitch 配置导出 profile 清单，记录模型名和 base_url。第二步，按任务设计样本，不要只用闲聊。Codex 接入样本要包含工具调用和文件读取边界；AI API 接入样本要包含 JSON 字段；AI 自动化办公样本要包含审批人、金额或日期这类业务字段。第三步，逐个 profile 跑样本，把返回状态、错误对象、耗时和输出格式填进矩阵。
第四步，设置路由规则。工具调用任务只允许命中通过工具样本的 profile；结构化写入任务只允许命中通过 Schema 的 profile；普通摘要任务可以使用更宽松的模型。第五步，设置回退。回退不是“随便换一个模型”，而是换到同类能力通过验收的 profile。相关兼容性排查可参考 JSON 结构兼容检查、流式输出兼容性 和 健康探测与降级切换。
常见问题 / 避坑
不要把“模型更强”直接等同于“更适合当前工具链”。有些模型文字质量好，但函数参数稳定性差；有些模型速度快，却不适合长上下文。不要在正式任务里第一次试工具调用。不要让测试 profile 和正式 profile 共享模糊命名，相关隔离方法可参考 测试流量避免打到正式模型。如果你用 Codex 生成矩阵，也要人工抽查样本输出，避免它把一次偶然成功写成永久能力。
检查清单
- 每个 profile 都有真实样本记录，而不是只写“可用”。
- 工具调用、JSON Schema、流式输出、长上下文和失败回退分开验收。
- 路由规则按任务能力匹配，不按模型名好坏粗暴切换。
- AI API 接入日志能看到命中的 profile 和回退原因。
- 专题入口包含 CCSwitch 配置专题、AI API 接入专题、Codex 专题 和 AI 自动化办公专题，方便团队复查。
能力矩阵的重点不是做一张漂亮表格，而是让每一次切换都有证据。只有工具能力、输出格式和回退路径都清楚，CCSwitch 才能承担多模型接口管理的职责。
矩阵落地后的维护节奏
能力矩阵不是一次性文档。每次新增 profile、修改模型名、调整 base_url、更新客户端版本或改变任务路由，都应该补跑样本。可以把样本分成每日轻量检查和上线前完整检查：每日只验证连接、工具调用和 JSON 三项，上线前再加长上下文、流式输出、费用标签和回退路径。这样不会把维护成本拉得太高，也能及时发现模型能力变化。
团队共用配置时，还要给矩阵指定负责人。负责人不一定是开发主管，可以是最常处理 AI API 接入问题的人。只要有人负责更新样本结果、记录失败原因和同步禁用 profile，Codex 接入、开发者 AI 调用和自动化办公流程就不容易因为一次临时切换而出现隐性故障。