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

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

本章你将学会什么

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

读者前置

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

openclaw models list

openclaw models set <provider/model>

6.1 模型与推理的基本概念

6.1.1 模型引用统一写法

想象你去快递柜取包裹，需要输入取件码 + 柜号。
在 OpenClaw 里，调用模型同样需要两部分信息：供应商是谁 + 用哪个模型。

OpenClaw 统一使用这种写法：

provider/model

也就是：

供应商名称 / 模型名称

中间用斜杠隔开，记住这个格式就行。

来看几个具体例子：

供应商	模型名	完整写法（provider/model）
Z.AI	GLM-5	`zai/glm-5`
MiniMax	M2.5	`minimax/MiniMax-M2.5`
Moonshot	K2.5	`moonshot/kimi-k2.5`

为什么统一格式这么重要？

因为你在命令行、配置文件、日志里看到的模型名，统一都是这个格式。
下次你看到 openclaw models set zai/glm-5，别犹豫，照着敲就行。

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

很多新手会有一个误解：只要选一个“榜单第一”的模型，系统就稳了。

其实模型效果由两层决定：

模型本身能力 —— 就是模型够不够聪明，做题能不能做对；
你的工具边界、路由策略、重试与回退 —— 就是模型答对了，你能不能收到、收到后怎么处理、模型挂了有没有备胎。

新手常犯的错是只盯第 1 层（天天看榜单和参数）。
但实际线上稳不稳，往往由第 2 层决定。

这就好像买车：

车本身动力强不强（类似模型能力）
但你还得有备胎、导航、保养手册（类似路由、失败处理）

这章主要帮你搞定第 2 层。

6.1.3 本书与官方文档的关系

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

📢 如果以后官方出了新版本或新供应商，只要记住 provider/model 这个统一格式，就能平滑迁移。

6.2 供应商选择原则

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

选供应商就像找对象，不能只看颜值（榜单排名），得看四项硬指标：

维度	问自己	什么意思
质量	这家模型做题成功率怎么样？	别选一个经常“答非所问”的
延迟	发出请求后多久能收到第一个字？	首 token 越快越好，体验才丝滑
成本	跑一次任务花多少钱？失败重试要不要加钱？	便宜很重要，但别贪便宜选个经常超时的
可用性	关键稳不稳？文档全不全？限流严不严？	别选那种三天两头让你重新输 Key 的

打分方法：

找张纸，画四列，每列 10 分。
每试用一家供应商，就四项都打个分。
分数最高的就是你的首选。

别拍脑袋，也别听别人说“好用你就用”。
自己测过才知道。

6.2.2 国内读者的落地建议

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

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

💡 提示：国内供应商的支付和 Key 管理通常更顺畅，文档也是中文的。有问题更容易搜到答案。

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

想换供应商？记住一个原则：一次只改一件事。

正确姿势：

# 第 1 步：先只换主模型
openclaw models set zai/glm-5

# 第 2 步：稳定跑 24 小时，观察日志
openclaw logs --follow

# 第 3 步：确认没问题，再动 fallback 和高级参数

错误姿势：

同时换了主模型、改了超时配置、加了新的 fallback、还换了 Key
→ 出问题了，你根本不知道是哪一步改坏的

小技巧： 每次改配置前，先截个图或复制一份配置文件。出问题了好回滚。

6.3 路由与回退（Failover）思路

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

想象一下：你开车去约会，主车是宝马，但万一抛锚了，你得有个备胎方案——比如叫滴滴。

模型调用也是一样的道理：

{
  agents: {
    defaults: {
      model: {
        // 你的主车：优先使用这个
        primary: "moonshot/kimi-k2.5",
        // 备胎方案：如果主车挂了，自动切换到这里
        fallbacks: ["zai/glm-5"],
      },
    },
  },
}

🔧 这里的 primary 就是主模型，fallbacks 是备用模型列表。按顺序尝试，第一个不行就换下一个。

建议：至少配一主一备。

如果你只配一个模型，等它挂了，你的系统就卡住了。
多配一个备用模型，成本几乎不变，但稳定性提升一大截。

6.3.2 回退触发的常见场景

OpenClaw 的 failover（自动切换）会在以下情况触发：

鉴权失败 —— Key 过期了或权限被收回
限流 —— 短时间内请求太多，供应商把你拒了
超时 —— 等太久没响应，超过了失败判定阈值

⚠️ 注意：不是所有错误都会自动切 fallback。比如你写错了模型名（Unknown model），这种情况 fallback 也救不了你，得先去改配置。

所以日志与错误分类仍然重要——你得知道到底是哪种错误。

6.3.3 profile 轮转与会话粘性

如果你配置了多套 auth profile（身份凭证），OpenClaw 会按顺序轮转使用。

什么是 profile？

你可以理解为“不同的账号和 Key 的组合”。
比如你有两个 MiniMax 的账号，就可以配成两个 profile，系统会轮流用。

会话粘性是什么？

有时候你会发现，同一个对话任务好像“偏爱”某个 profile，连续好几次都用了同一个。
这是正常的——目的是减少来回切换造成的“抖动”（就像你开车总换车道反而更慢）。

别担心，这是设计好的行为。

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

6.4.1 Key 与 profile 分层

很多新手容易把两件事搞混：

auth.profiles / auth.order —— 路由规则：先试哪个 profile、后试哪个
credentials / auth store —— 实际密钥：你的 API Key 到底是什么

📦 简单理解：profile 是“地址本”，credentials 是“钥匙”。别把钥匙和地址本搞混了。

如果只改了路由顺序（auth.order），但没换 Key，别以为“已经换了个号”。
很多人犯这个错：以为自己切换成功了，其实还在用原来的 Key。

6.4.2 多供应商并存时的规则

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

实操建议：

供应商	主 Key	备 Key	备注
MiniMax	key-xxx-1	key-xxx-2	两套轮着用
Z.AI	key-yyy-1	key-yyy-2	同上
Moonshot	key-zzz-1	key-zzz-2	同上

📝 建议用表格或笔记记下来，哪天 Key 挂了容易查。

6.4.3 泄露后的标准动作

如果你的 Key 不小心泄露到公开场合（比如发到 GitHub），按这个顺序操作：

1. 撤销旧密钥 → 2. 生成新密钥 → 3. 更新配置 → 4. 验证模型路由 → 5. 回看异常日志

不要只做第一步！

如果你只撤销了旧 Key，但没更新配置文件，系统可能还在用那个失效的 Key，每次请求都会失败。
一定要确认配置里已经换成新 Key，并测试一下能否正常调用。

自检清单：

旧 Key 已从供应商后台撤销
新 Key 已更新到配置文件或环境变量
执行 openclaw models list 确认能正常列出模型
发送一条简单测试请求，确认成功
翻一下异常日志，看看有没有泄露期间的非授权调用

6.5 模型侧故障排查

6.5.1 五条命令先跑一遍

遇到模型调用失败，先跑这五个命令，基本能定位 90% 的问题：

# 1. 看系统整体状态
openclaw status

# 2. 看当前配置了哪些模型
openclaw models list

# 3. 看网关状态
openclaw gateway status

# 4. 实时看日志，滚动输出
openclaw logs --follow

# 5. 医生来了：自动诊断常见问题
openclaw doctor

🩺 这五个命令就是你的“五大神兽”。遇到问题先敲一圈，总有一个能给你线索。

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

快速判断技巧：

情况	很可能的原因
只有某个 provider 失败	这个 provider 的 Key 过期了、或者 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 管理要和路由策略分层，泄漏处置要闭环到验证。
遇到问题先跑五个命令：status → models list → gateway status → logs —follow → doctor。