OpenClaw models 使用教程 模型认证和状态检查指南

openclaw models 是处理模型层问题时最值得先学的一组命令。只要你刚配置完 OpenAI、Anthropic、OpenRouter、Ollama 或 Codex 订阅，第一时间都应该来这里确认，而不是先去聊天窗口里盲测。

它主要解决什么问题#

openclaw models 最常见的用途有三类：

• 查看当前有哪些 provider 和模型可用
• 处理 provider 的登录或认证
• 验证默认模型配置有没有真正生效

这也是为什么它适合放在模型教程和 FAQ 中间，作为排障桥梁。

什么时候应该优先用它#

下面这些场景里，models 都应该排在很靠前的位置：

• 刚接完 OpenAI / Anthropic / OpenRouter
• 刚做完 openclaw onboard
• 改了默认模型名
• 模型调用失败，但你不知道是认证还是配置问题
• 从 API Key 切到 OAuth / Codex 订阅后做验证

最常用的检查命令#

先从这个命令开始：

openclaw models status

它最适合回答这几个问题：

• 哪些 provider 已认证
• 默认模型是否被识别
• 当前模型配置是否处于可用状态

如果这里就已经显示异常，就没必要先去折腾渠道、工具或业务工作流。

模型认证相关命令#

当 provider 需要登录时，官方命令通常会走：

openclaw models auth login --provider <provider>

例如：

openclaw models auth login --provider openai-codex

这类命令最适合：

• 你要补做 OAuth 登录
• 某个 provider 的登录态失效了
• 你想在不重跑 onboarding 的情况下重新认证

它和 openclaw status --deep 的关系#

可以这样分工理解：

• openclaw models status：更聚焦模型和 provider 层
• openclaw status --deep：更适合做全系统视角的深检查

当你明确怀疑问题就在模型层时，先用 models 会更高效；当你不确定问题到底在模型、渠道还是 Gateway 层时，再用 status --deep。

一条很实用的排查顺序#

如果你改完模型配置后发现系统不回话，我建议按这个顺序来：

1. openclaw models status
2. openclaw status --deep
3. 确认默认模型名是否真的存在
4. 再去测试聊天或渠道入口

这样能很快区分：

• 是认证没成功
• 是默认模型写错
• 还是系统其他层出了问题

最常见的误区#

误区 1：只要 API Key 写进去了，就不需要看 models status

不对。密钥存在不等于 provider 已经被系统正确识别，也不等于默认模型名写对了。

误区 2：模型调不通时先看渠道

顺序反了。渠道只是消息入口，模型层没准备好，再正常的渠道也不会产生正确响应。

误区 3：provider 认证和默认模型配置是一回事

不是。你可能已经认证成功，但默认模型名仍然写错；也可能模型名没问题，但认证本身失效了。

一个推荐习惯#

每次你改了任何一项模型相关配置，都先跑一次：

openclaw models status

把它当成模型侧的“保存后自检”。这个习惯会帮你少绕很多弯路。