连接模型总览：provider 体系与模型切换

装好 OpenClaw、跑通了 onboarding，你手上已经有一个能用的模型。但 OpenClaw 本体不带模型——模型全部来自「provider 插件」，这正是 OpenClaw 模型配置的核心：接哪家插件、配哪份凭据、模型引用写对 provider/model。

本课（1.6）把这套体系一次讲清：怎么查现状、怎么列目录、怎么设默认、怎么在聊天里随时切换、怎么接入一家全新的 provider。之后 1.7–1.15 的每个模型接入专页，都是这套规则的具体应用。本教程基于 v2026.10.9。

学完你能做什么

• 说出当前 OpenClaw 用的是什么模型：openclaw models status 一查便知
• 用 openclaw models list 浏览任何一家 provider 的模型目录，「OpenClaw 支持哪些模型」不再靠搜
• 用 openclaw models set <provider/model> 改默认模型，不用手改配置文件
• 在聊天里用 /model 命令族随时切换模型：临时的、持久的都行
• 接入一家新 provider 时，三步顺序脱口而出：装插件 → 配凭据 → 选模型

你现在的困境

• 装完能用，但「现在用的到底是哪个模型」说不清；想换个更便宜或更强的，不知道从哪下手
• 搜「OpenClaw 支持哪些模型」，答案五花八门，还混着 Clawdbot / Moltbot 时代的旧命令
• 看别人改配置文件里的 agents.defaults，自己也想动手，又怕改坏了 Gateway 起不来

什么时候用这一招

当你需要：

• 弄清 OpenClaw 的模型体系——当前用什么、还能用什么、怎么换
• 把默认模型换成国产模型（DeepSeek、千问、GLM……），或让不同会话用不同模型
• 聊天中途临时切个强模型，聊完再切回来

而且不想：

• 每换一次模型就手改一次配置文件
• 在 70+ 个条目的官方 provider 目录里迷路
• 把「接入新模型」和「切换已有模型」混成一团，乱试一气

🎒 开始前的准备

• 完成了 安装：5 分钟跑通 OpenClaw：onboarding 已配好至少一家 provider（Claude / Codex 登录或某家 API Key）
• Gateway 在运行：openclaw gateway status 应显示监听 18789（没在跑也能查模型，只是 models list 会读本地缓存目录）
• 想顺手接入新 provider 的话，备好那一家的 API Key——从下一课起用 DeepSeek 举例

核心思路

OpenClaw 本体不带模型。 模型与 agent harness（Claude、Codex、本地模型）都是可换插件。每接一家模型 = 一个 provider 插件 + 一份凭据。OpenClaw 模型配置只有三个概念：

1. provider——一家模型的接入插件，有唯一 id（如 deepseek、qwen、anthropic）
2. 模型引用 provider/model——指名一个模型的统一写法，如 deepseek/deepseek-v4-pro
3. 默认模型与切换——配置里写一个默认；聊天里 /model 随时换

引用规则是全课的地基：

规则	例子	说明
第一个 / 前是 provider id	qwen/qwen3.5-plus	provider id 一律小写（规范化）
模型 ID 自带 / 时必须带全前缀	openrouter/moonshotai/kimi-k2	按「第一个 /」切分，漏前缀就找不到
模型 ID 的拼写跟着厂商走	minimax/MiniMax-M3	MiniMax 的模型 ID 大小写敏感，照插件目录抄

两种接入方式，一张表分清：

	官方 provider 插件	自定义 / 中转端点
适用	有官方插件的模型（DeepSeek、Qwen、GLM、Kimi、MiniMax……）	无官方插件的模型、OpenAI 兼容中转站、本地推理服务
要写 models.providers 配置吗	不用：装插件 + 设 auth + 选模型	要：baseUrl、apiKey、models 列表
详见	1.7–1.13 各家专页	更多国产模型与自定义中转端点

provider 大家族（官方 Provider 目录 收录 70+ 个条目）：

家族	代表	接入方式	本教程专页
国际大厂	OpenAI（openai）、Anthropic（anthropic）、Google（google）	内置插件；onboarding 可复用 Claude Code / Codex CLI 登录	快速起步已覆盖
国产模型	DeepSeek、通义千问、智谱 GLM、Kimi、MiniMax、豆包/火山、混元、千帆、StepFun、小米 MiMo、LongCat	官方插件 + API Key	1.7–1.13 每家一页
聚合路由	OpenRouter、LiteLLM、ClawRouter	一把 Key 开多家模型	1.14 中转与更多国产
本地模型	Ollama、vLLM、SGLang、LM Studio、ds4	跑在自己机器上，零 API 成本	1.15 本地模型

国内用户的好消息：主流国产模型全是「一等公民」——都有官方 provider 插件，从 1.7 开始每家一页手把手配。

跟我做

第 1 步：查看当前模型配置——openclaw models status

为什么：onboarding 帮你配好了模型，但很多人说不清「我用的到底是哪个」。先看清现状，后面每一步才有对照。

openclaw models status

你应该看到：两块信息——解析后的默认模型与 fallback 链（完整的 provider/model 引用），加上各 provider 的凭据概览（Auth overview：环境变量、provider 配置、auth 存储里找到的凭据来源）。有 OAuth 凭据快过期时（默认 24 小时内）也会在这里警告。

三个补充点：

• 裸 openclaw models 等价于 openclaw models status；加 --json 得到机器可读格式

• 不加 --probe 时它不发真实模型请求——凭据「看起来在」不代表能用；要实测加 --probe（会真调模型、可能消耗 token、触发限流）

• 单个会话里的临时切换，CLI 的 status 看不到，要用那个会话里的 /model status

• openclaw models status 里能找到当前默认模型的完整 provider/model 引用

第 2 步：浏览模型目录——openclaw models list（OpenClaw 支持哪些模型在这里看）

为什么：换模型前先看货。每家 provider 有自己的模型目录：上下文窗口、输入类型、是否推理模型，全在表里。

openclaw models list                      # 当前已装 provider 的可见模型
openclaw models list --all                # 完整发布目录
openclaw models list --provider deepseek  # 只看一家

你应该看到：一行一个模型引用（provider/model 形态）。--provider 后面接 provider id（如 deepseek、moonshot），不是界面显示名（如 Moonshot AI）。

四个实用细节：

• 忘了 provider id？先跑 openclaw models list --all，从完整目录里找

• 未知 provider id 会报错退出（exit 非零），并点名被拒的 id

• 新发布的模型可能不在本地目录里，加 --refresh 触发重新发现

• 保存某家的凭据会让它的模型进入可选目录——所以第 5 步接入新 provider 后，记得回来刷新看看

• openclaw models list --provider <你已配好的 provider> 列出了它的模型目录

第 3 步：设默认模型——OpenClaw 模型配置的核心一步

为什么：默认模型决定新会话和定时任务用什么。命令一行，不用手改配置文件。

openclaw models set deepseek/deepseek-v4-pro

（示例用 DeepSeek；前提是装了它的 provider 插件——没装先看第 5 步，或直接去 接入 DeepSeek。）

你应该看到：命令成功无报错；再跑 openclaw models status，默认模型已是新值。

它做的事：写配置项 agents.defaults.model.primary。等价的配置文件写法长这样：

{
  agents: { defaults: { model: { primary: "deepseek/deepseek-v4-pro" } } },
}

两条防呆规则（出自官方 CLI 文档）：

• 未知 provider 直接拒绝：exit 非零、配置不动——引用里的 provider 必须是已装插件或已配置的 provider
• 目录里没有该模型会警告：不阻止写入（新发布或自托管模型可能还没进目录），但值得回头核对拼写

💡 换默认的另外两条路

openclaw models auth login --provider <id> --set-default 在登录时顺手采用该 provider 的推荐默认模型；默认图像模型用 openclaw models set-image <provider/model>（写 agents.defaults.imageModel.primary）。

• openclaw models set <provider/model> 执行成功（或明白它为什么拒绝了你）

第 4 步：聊天里切换模型——/model 命令族

为什么：终端里设的是「默认」；聊天里还能随时换——临时切强模型、聊完切回，全局配置一动不动。

/model                              # 看当前会话用什么
/model list                         # 浏览 provider（/models 也行）
/model deepseek/deepseek-v4-pro     # 只切当前会话（默认行为）
/model deepseek/deepseek-v4-pro -a  # 同时更新该 agent 的默认（需 owner/admin）
/model deepseek/deepseek-v4-pro -g  # 更新全局默认（需 owner/admin）
/model default -s                   # 清除本会话选择，回到配置默认
/model status                       # 各 provider 的凭据候选与 baseUrl / api 模式

你应该看到：切换命令即时生效——agent 空闲时下一次运行就用新模型；正在跑时排队到下一个安全切换点。/models <provider> 列出某家的全部模型。

三个要知道的脾气：

• 会话内选择是「严格」的：选中的模型不可达时直接报错，不会偷偷走 fallback 链（配置的默认才走 fallback）
• 数字选择不支持（/model 3 无效）；Discord / Telegram 有原生选择器界面
• 模型 ID 自带 / 时要写全前缀：/model openrouter/moonshotai/kimi-k2

/model 之外还有 /think、/new 一大家子聊天命令，见 聊天命令速成。

• 聊天里 /model <provider/model> 切换后，下一条回复来自新模型

第 5 步：接入新 provider——装插件、配凭据、选模型

为什么：目录里看中了哪家模型，先让 OpenClaw「认识」它。官方 provider 插件固定三步：

① 装插件（部分 provider 需要） → ② 配凭据（openclaw onboard） → ③ 选模型

以 DeepSeek 为例（它是外部官方插件，需要安装）：

openclaw plugins install @openclaw/deepseek-provider
openclaw onboard --auth-choice deepseek-api-key

你应该看到：onboarding 检测已有 AI 访问 → 等你选 provider → 验证连接通过后只保存可用路由 → 继续配置其余部分。选了 --auth-choice 后，默认模型选择器会预过滤到这家 provider 的模型（同一插件的兄弟 provider 也一起匹配，比如 volcengine / volcengine-plan）。

三件事心里有数：

• 插件要不要装，各家不同：MiniMax 是内置（bundled）插件，openclaw plugins enable minimax 即可；DeepSeek、Qwen、GLM、Kimi 等外部插件要 openclaw plugins install @openclaw/<名字>-provider。每家的准确命令，1.7–1.13 专页开头都给了
• 官方插件不用写 models.providers 配置条目——装插件、设 auth、选模型，三步完事；只有自定义端点或覆盖 baseUrl 时才写（见 1.14）
• 重新 onboard 不会清掉已有的模型配置；模型 provider 或 auth 路由的变更，官方建议跑 openclaw onboard（openclaw configure 留给非推理类的设置）

零一 Yi、百川、讯飞星火这些暂无官方插件的模型，走自定义 OpenAI 兼容端点或聚合商，见 更多国产模型与自定义中转端点；不想花 API 钱，本地模型 教你用 Ollama、vLLM 把模型跑在本机。

• 接入新 provider 的三步顺序能脱口而出：装插件 → 配凭据 → 选模型

检查点 ✅

• openclaw models status 能说出当前默认模型的完整 provider/model 引用
• openclaw models list --provider <id> 能列出一家 provider 的模型目录
• openclaw models set <provider/model> 改默认成功（或明白它为什么拒绝）
• 聊天里 /model <provider/model> 切换生效，/model default -s 能切回默认
• 接入新 provider 的三步顺序说得出来：装插件 → 配凭据 → 选模型

踩坑提醒

❌ 模型引用漏了 provider 前缀

原因：OpenClaw 按「第一个 /」切分引用。省略 provider 时会先试别名、再试唯一匹配的已配置 provider，最后才试默认 provider（已是弃用行为）——多一个同名的模型就选不中。

/model kimi-k2                        # ❌ 多数情况下选不中
/model kimi/kimi-for-coding           # ✅ 带上 provider 前缀
/model openrouter/moonshotai/kimi-k2  # ✅ 模型 ID 自带 / 时必须带全前缀

正确做法：引用一律写全 provider/model；拿不准就先 openclaw models list --provider <id>，照目录里的原文抄（MiniMax 等厂商的模型 ID 大小写敏感）。

❌ 配了新 provider 的 Key，以为默认模型会自动换

原因：保存新 provider 的凭据不会改动已有默认模型——官方 Quick rules 的原话：「Adding provider auth does not change your primary model」，只有显式 --set-default 才会换。

正确做法：换默认走 openclaw models set <provider/model>，或登录时 openclaw models auth login --provider <id> --set-default。症状对不上时，先 openclaw models status 看默认到底是谁。

❌ Gateway 装成守护进程后，export 的 API Key「不生效」

原因：Gateway 作为 launchd / systemd 服务运行时，看不到你交互 shell 里 export 的环境变量——各 provider 文档都专门强调这一点。

正确做法：Key 写进 ~/.openclaw/.env，或经配置里的 env.shellEnv 提供；换了 Key 记得重启 Gateway 服务。

❌ 用了退役的旧模型 ID

原因：模型会退役。DeepSeek 的 deepseek-chat / deepseek-reasoner 已于 2026-07-24 退役，旧 ID 不再可用。

正确做法：openclaw models list --provider deepseek 看现役目录，用 deepseek/deepseek-v4-pro、deepseek/deepseek-v4-flash 这类新 ID；迁移细节见下一课 接入 DeepSeek。

进阶技巧（可选）

给默认模型配 fallback 链。 agents.defaults.model.fallbacks 里的模型依序尝试；凭据轮换发生在 provider 内部，然后才落到下一个 fallback 模型。CLI 管理：

openclaw models fallbacks list
openclaw models fallbacks add deepseek/deepseek-v4-flash
openclaw models fallbacks remove <model-or-alias>
openclaw models fallbacks clear

让 OpenClaw 帮你挑免费 fallback。 openclaw models scan 读 OpenRouter 公开 :free 目录，按图像支持、工具延迟、上下文等排序挑候选。两个注意：元数据扫描不需要 Key，实时检查与 --set-default 需要 OPENROUTER_API_KEY；带探测的 scan 会写配置（直接替换 fallbacks），只想看看加 --no-probe。

给模型起别名。 openclaw models aliases add Opus anthropic/claude-opus-5-5 之后，聊天里 /model Opus 就能选中。别名存在 agents.defaults.models.<key>.alias；一个模型同时只有一个别名，加新的会顶掉旧的。

单次运行指定模型。 不想改任何配置，跑一次性的：

openclaw agent --model deepseek/deepseek-v4-pro --message "..."

Control UI 里也能管模型。 Gateway 的 Models 页提供与 CLI 相同的登录流程；Settings → Models → Set API key 直接换 Key，换完即清掉该凭据的冷却与失败计数，下一次请求立即可试。

更新托管模型目录。 openclaw models refresh 拉取官方托管元数据目录（新模型进目录走这里）；要求本地 Gateway 先停（openclaw gateway stop），刷完再启动。

本课小结

✅ OpenClaw 模型配置的三个概念清楚了：provider（插件 + 凭据）、provider/model 引用、默认模型与切换。

✅ 查 → 列 → 设 → 切的命令链跑通了：models status 看现状、models list 看目录、models set 设默认、/model 聊天里切换。

✅ 接入新 provider 的三步定了型：装插件（需要的话）→ openclaw onboard --auth-choice <id> 配凭据 → 选模型；官方插件不写 models.providers。

✅ 两个脾气记住了：会话内 /model 选择严格匹配、不走 fallback；守护进程形态下 Key 要进 ~/.openclaw/.env。

配置字段 / 命令	形态 / 推荐值	说明
agents.defaults.model.primary	"provider/model"	默认模型；openclaw models set 写这里
agents.defaults.model.fallbacks	模型引用列表	兜底链，依序尝试
agents.defaults.models.<key>.alias	别名字符串	/model <别名> 的快捷入口
models.providers.<id>	自定义端点才写	官方插件不需要
~/.openclaw/.env	PROVIDER_API_KEY=...	守护进程形态下 Key 的家
openclaw onboard --auth-choice <id>	取值见各家专页	配置 / 更换 provider 凭据

命令速查的完整清单见 CLI 命令与配置速查。

下一课预告

体系清楚了，从下一课开始逐家实战——第一家是最多人用的 DeepSeek。下一课 接入 DeepSeek：V4 系列模型配置实战。

你会学到：

• DeepSeek V4 系列模型目录：deepseek-v4-pro / deepseek-v4-flash 怎么选
• DEEPSEEK_API_KEY 配置全流程：插件安装、onboarding、配置文件三种写法
• 旧 ID deepseek-chat / deepseek-reasoner 退役后的迁移
• DeepSeek 专属能力：thinking 等级、DSML 工具恢复、web_search

相关教程

• 更多国产模型与自定义中转端点
• 本地模型：Ollama、vLLM 与 ds4
• 聊天命令速成：/model、/think 与斜杠命令