模型接入：从“能用”到“用得好”

第 2 章你已经把模型连上了。
这章要解决“第二阶段问题”：怎么选模型更稳、一个挂了怎么自动顶上、费用怎么别跑飞。

本章你将学会什么

理解 provider/model 的统一模型引用方式。
用“质量、延迟、成本、稳定性”四维度选供应商。
配置主模型 + fallback，避免单点失效。
管理多套 Key 与 auth profile，减少“凭证失效”中断。
用最短命令排查模型调用失败。

读者前置

你已完成第 2 章模型接入流程。
你可以执行：

openclaw models list

openclaw models set <provider/model>

6.1 模型与推理的基本概念

6.1.1 模型引用统一写法

OpenClaw 统一使用：

provider/model

例如：

zai/glm-5
moonshot/kimi-k2.5
minimax/MiniMax-M2.5

这个点你一定要记住：
你在命令行、配置文件、日志里看到的模型名，统一都是这个格式。

6.1.2 “模型能答”不等于“系统能稳”

模型效果由两层决定：

模型本身能力；
你的工具边界、路由策略、重试与回退。

新手常犯错是只盯第 1 层（模型榜单和参数）。
实际线上稳定性，往往由第 2 层决定。

6.1.3 本书与官方文档的关系

本书以 v2026.2.17 为冻结基线。
如果你在第 2 章已按国内路线使用 M2.5 / GLM-5 / K2.5，本章方法仍适用：
核心不变，都是“统一模型引用 + 可回退 + 可追溯”。

6.2 供应商选择原则

6.2.1 四维度选择法（够用且实操）

按这四项打分，别拍脑袋选：

质量：任务成功率与稳定性；
延迟：首 token 和总完成时间；
成本：单位调用费用与失败重试成本；
可用性：鉴权稳定性、限流行为、文档完整度。

6.2.2 国内读者的落地建议

对国内场景，建议优先选“你能稳定付费、稳定鉴权、稳定访问”的供应商。
不要为了“榜单第一”牺牲可用性。

你可以从第 2 章已跑通的三家开始（MiniMax / Z.AI / Moonshot），再逐步扩展。

6.2.3 供应商切换要做“最小变更”

先只改主模型，不改其它策略：

openclaw models set zai/glm-5

先稳定跑 24 小时，再动 fallback 与高级参数。
这样一旦出问题，你能快速知道是“哪一步改坏了”。

6.3 路由与回退（Failover）思路

6.3.1 主模型 + 回退模型是标配

建议至少一主一备：

{
  agents: {
    defaults: {
      model: {
        primary: "moonshot/kimi-k2.5",
        fallbacks: ["zai/glm-5"],
      },
    },
  },
}

6.3.2 回退触发的常见场景

官方 failover 重点覆盖：

鉴权失败；
限流；
超时（达到失败判定阈值）。

不是所有错误都会自动切 fallback。
所以日志与错误分类仍然重要。

6.3.3 profile 轮转与会话粘性

如果你维护多套 auth profile，系统会按顺序轮转。
会话可能存在“偏好 profile”的粘性，这是正常行为，目的是减少来回切换造成的抖动。

6.4 Key 管理与泄露预防（进阶版）

6.4.1 Key 与 profile 分层

auth.profiles / auth.order：路由与策略信息；
实际密钥：存储在 credentials / auth store（不建议散落在文档）。

这能避免“只改了路由顺序，却误以为自己换了密钥”的错觉。

6.4.2 多供应商并存时的规则

建议每家至少准备两套身份（主 + 备），并留下轮换记录。
一旦某家短时限流，系统能切到同家次级或跨家 fallback，不至于整体中断。

6.4.3 泄露后的标准动作

撤销旧密钥 -> 生成新密钥 -> 更新配置 -> 验证模型路由 -> 回看异常日志

不要只做第一步。
如果不验证路由，系统可能仍在使用失效 profile。

6.5 模型侧故障排查

6.5.1 五条命令先跑一遍

openclaw status

openclaw models list

openclaw gateway status

openclaw logs --follow

openclaw doctor

6.5.2 先判断“模型问题”还是“系统问题”

快速判断：

只有某个 provider 失败：大概率是 provider/auth/model id 问题；
所有 provider 都失败：优先查 gateway、网络、配置结构。

6.5.3 高概率错误与第一动作

现象	高概率原因	第一动作
`Unknown model`	model id 写错或未加入可用列表	`openclaw models list` 后重新 `models set`
401/403	Key 失效或权限不足	更新 key 并复测
频繁超时	模型拥塞或网络波动	检查 fallback、超时阈值与重试策略
间歇性成功	profile 轮转与限流叠加	复核 `auth.order` 与 failover日志

本章小结

模型接入不是“一次配置就完事”，而是持续管理过程。
统一 provider/model 口径能显著减少排障复杂度。
主模型 + fallback 是生产稳定性的最低配置。
Key 管理要和路由策略分层，泄漏处置要闭环到验证。