OpenClaw 模型切换：provider、当前会话与 fallback

展开本页目录

开始前准备什么

备份实际 OpenClaw 配置，保留 channels、workspace、tools 与原 provider。
在 Gateway 真正运行的环境设置 tokenba_API_KEY，记录版本。
公开目录可见 glm-5.3 和 deepseek-v4-pro 的 Chat；令牌需要分别具备权限，工具调用仍待验收。

新增 provider
核对默认与限制
开新会话
完成固定任务
检查实际回退

先下载样例，再完成自己的首次调用

下载配置与样例中文操作说明本次实际结果

新用户：注册获取 API Key 已有账号：登录配置 Key

示例不含密钥。API 按实际用量计费；下载和点击不代表调用成功。

下载两个模型的配置片段

环境变量占位；保留原配置并手动合并。

下载切换验收任务

只在隔离目录读写，记录实际型号。

2026-10-25 资料复核与操作补充

继续操作前，核对当前配置与执行范围

先执行openclaw --version。modelPolicy.allow属于2026.8.1及之后的显式策略；更早版本按该版本schema核对旧模型列表行为，不直接照抄新字段。当前版本中的models set和别名添加不自动修改allow策略；先保留配置，再在独立环境验证。

openclaw --version
# modelPolicy.allow 需要2026.8.1及之后版本；先核对所装版本的schema。

原记录范围：本页保留原有配置、离线检查和历史记录；本轮没有新增该客户端或协议的在线运行记录。下列相邻实验各有自己的日期、模型和产物，不替代本篇客户端或协议的原生验收。

本次操作和结果

OpenClaw 原生配置读取（无模型请求）。

准备独立样例。安装文章所用客户端，或用 Python 3.11+ 运行标注为本地 HTTP/TOML 的样例。

本例操作：在隔离配置下执行原生读取并对照 agents.defaults 和具体 Agent 的覆盖值。

解压练习包，执行 python3 lab.py --output ./result u15。完整命令、样例输入和输出保存在回执。

打开 result/u15.json，对照实际退出码、请求路径或产物字段。

逐项确认下方通过条件。本例的测试范围以运行回执为准。

通过：原生命令读到默认模型
通过：该 Agent 另有覆盖模型

复跑样例

bash

python3 lab.py --output ./result u15

OpenClaw 换模型后仍走旧请求：核对当前配置来源 · 命令与结果截图 — 执行回执截图。OpenClaw 原生配置读取（无模型请求）。
查看高清原图

切换后从配置回读目标模型

OpenClaw 2026.5.12；本地命令核验。没有模型请求。

先备份配置；脚本将 OPENCLAW_CONFIG_PATH 和状态目录指向临时样例。

执行 models set qrfixture/deepseek-v4.1-flash，再用 config get agents.defaults.model.primary --json 核对。

真实使用时继续确认 Agent、会话及网关日志中的实际模型，再判断切换完成。

不对生产 Agent 或用户已配置的网关执行写入。

通过：set 后重新读取为目标模型
通过：没有启动模型请求

本地样例复跑

bash

python3 lab.py --output ./result a03

切换后从配置回读目标模型：实测命令与结果截图 — 真实客户端或本地脚本执行记录；测试响应来自本机样例服务。
查看高清原图

先分清四个配置层

层级	观察位置	作用
provider/model	models.providers 与 models list	确定 endpoint、协议和准确 ID
默认模型	models set / models status	为默认任务选择入口
当前会话	会话 /model 和实际运行记录	会话选择可能不同于全局默认
策略与 fallback	modelPolicy、fallback 列表	允许范围和失败回退；不是能力承诺

层级: provider/model
观察位置: models.providers 与 models list
作用: 确定 endpoint、协议和准确 ID

层级: 默认模型
观察位置: models set / models status
作用: 为默认任务选择入口

层级: 当前会话
观察位置: 会话 /model 和实际运行记录
作用: 会话选择可能不同于全局默认

层级: 策略与 fallback
观察位置: modelPolicy、fallback 列表
作用: 允许范围和失败回退；不是能力承诺

两个 Chat 模型的配置片段

合并到自己的实际配置，不覆盖其他对象。apiKey 使用环境变量占位，provider/model 前缀是 OpenClaw 引用；发给上游的是 models[].id。示例未填写上下文和价格数值，启用长任务前按所选通道填写已核对的 contextWindow 与 maxTokens；内置默认值不是厂商能力。

openclaw-models.json

json

{
  "models": {
    "mode": "merge",
    "providers": {
      "apizt": {
        "baseUrl": "https://api.apizt.com/v1",
        "apiKey": "${tokenba_API_KEY}",
        "api": "openai-completions",
        "models": [
          { "id": "glm-5.3", "name": "GLM 5.3" },
          { "id": "deepseek-v4-pro", "name": "DeepSeek V4 Pro" }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": { "primary": "apizt/glm-5.3" },
      "models": {
        "apizt/glm-5.3": { "alias": "QR GLM" },
        "apizt/deepseek-v4-pro": { "alias": "QR DeepSeek" }
      }
    }
  }
}

OpenClaw 提供方与模型引用：providers、openai-completions、apizt/glm-5.3、tokenba_API_KEY — 本站绘制的内容说明图：OpenClaw 的 provider/model 引用不是上游单独 model ID；合并配置时保留原有提供方。
查看高清原图

切默认，再核对当前会话和允许范围

新开测试会话，用 /model 查看或切换；核对实际请求记录中的 provider 和准确 ID。
如果策略限制 models，检查当前 modelPolicy.allow 和 agents.defaults.models；models set 不会自动改 modelPolicy.allow。
先分别直测两个型号，确认稳定后再设计 fallback；启用后记录 requested 与 actual model。
不要把 Chat ID 放到 Responses 或 Messages provider 中；协议迁移另做工具和流式验收。

默认切换检查

bash

openclaw --version
openclaw models status
openclaw models list
openclaw models set apizt/glm-5.3
openclaw models status

小任务：读三条事实，写一份摘要

在隔离 workspace 放入 task-note.txt：维护周三 02:00–02:15 UTC；只读可用、写入暂停；未说明补偿。要求读取它，再写 notes-summary.md，不调用消息渠道。分别用两个新目录和新会话测试两种模型。

工具日志应有真实 read 和 write；摘要不补出时区、赔付或其他事实。
task-note.txt 未改，输出文件能够打开。
切换默认后再核对新会话和实际模型，不把旧缓存回答当验证。
保存全部回合和控制台实扣；这份任务没有执行在线模型，也没有费用或速度排名。

OpenClaw 文档任务的事实检查：02:00–02:15 UTC、只读可用、写入暂停、task-note — 本站绘制的内容说明图：本页任务未执行在线模型；图只给出读取、写入与未知政策的验收要求，不宣称已产生速度或费用结果。
查看高清原图

下载完整任务与记录项

常见失败按层处理

现象	先查	验收
Model not allowed	modelPolicy.allow 与实际 provider/model	所需覆盖策略明确允许
Key 在终端有，Gateway 没有	Gateway / service 的启动环境	原运行进程读取同名变量
切换后还是原模型	旧会话与 fallback 日志	新会话 actual model 对应目标
目录默认价格为 0	自定义模型 cost 元数据	不能当免费；以真实账单核对
文字可用工具失败	目标模型 tools 与协议	真实读取、写入和返回闭环

现象: Model not allowed
先查: modelPolicy.allow 与实际 provider/model
验收: 所需覆盖策略明确允许

现象: Key 在终端有，Gateway 没有
先查: Gateway / service 的启动环境
验收: 原运行进程读取同名变量

现象: 切换后还是原模型
先查: 旧会话与 fallback 日志
验收: 新会话 actual model 对应目标

现象: 目录默认价格为 0
先查: 自定义模型 cost 元数据
验收: 不能当免费；以真实账单核对

现象: 文字可用工具失败
先查: 目标模型 tools 与协议
验收: 真实读取、写入和返回闭环

模型切换不改变消息权限

此任务关闭真实渠道发送。改 provider 不会增加 WhatsApp、Slack、邮件或文件系统权限。需要这些能力时，独立验证渠道授权、工具范围与业务幂等。

OpenClaw 对自定义代理协议会调整部分专有字段。不能把原生 OpenAI 搜索、缓存提示或推理参数视为所有代理可用，按当前官方路由规则逐项测试。

怎样确认已经完成

默认、当前会话、策略和 fallback 都有可对应记录。
两个型号分别完成真实 read/write，原文件未变。
实际请求的型号、协议和全部费用可匹配。

常见问题

models set 后旧会话立即换模型吗？

默认模型和会话覆盖分别核对。使用 /model 和实际运行记录确认；需要受控对比时新开干净会话。

添加模型后为什么 Model not allowed？

当前 modelPolicy.allow 可能限制覆盖选择。官方说明 models set 和 aliases 操作不会修改该策略；检查规则而不是反复添加 ID。

配置里价格默认为 0，调用免费吗？

不是。自定义 provider 元数据缺失时的默认 cost 不能代表上游费用，控制台实际账单才用于对账。

资料来源

展开本页目录

开始前准备什么

备份实际 OpenClaw 配置，保留 channels、workspace、tools 与原 provider。
在 Gateway 真正运行的环境设置 tokenba_API_KEY，记录版本。
公开目录可见 glm-5.3 和 deepseek-v4-pro 的 Chat；令牌需要分别具备权限，工具调用仍待验收。

新增 provider
核对默认与限制
开新会话
完成固定任务
检查实际回退

先下载样例，再完成自己的首次调用

下载配置与样例中文操作说明本次实际结果

新用户：注册获取 API Key 已有账号：登录配置 Key

示例不含密钥。API 按实际用量计费；下载和点击不代表调用成功。

下载两个模型的配置片段

环境变量占位；保留原配置并手动合并。

下载切换验收任务

只在隔离目录读写，记录实际型号。

2026-10-25 资料复核与操作补充

继续操作前，核对当前配置与执行范围

openclaw --version
# modelPolicy.allow 需要2026.8.1及之后版本；先核对所装版本的schema。

本次操作和结果

OpenClaw 原生配置读取（无模型请求）。

准备独立样例。安装文章所用客户端，或用 Python 3.11+ 运行标注为本地 HTTP/TOML 的样例。

本例操作：在隔离配置下执行原生读取并对照 agents.defaults 和具体 Agent 的覆盖值。

解压练习包，执行 python3 lab.py --output ./result u15。完整命令、样例输入和输出保存在回执。

打开 result/u15.json，对照实际退出码、请求路径或产物字段。

逐项确认下方通过条件。本例的测试范围以运行回执为准。

通过：原生命令读到默认模型
通过：该 Agent 另有覆盖模型

复跑样例

bash

python3 lab.py --output ./result u15

切换后从配置回读目标模型

OpenClaw 2026.5.12；本地命令核验。没有模型请求。

先备份配置；脚本将 OPENCLAW_CONFIG_PATH 和状态目录指向临时样例。

执行 models set qrfixture/deepseek-v4.1-flash，再用 config get agents.defaults.model.primary --json 核对。

真实使用时继续确认 Agent、会话及网关日志中的实际模型，再判断切换完成。

不对生产 Agent 或用户已配置的网关执行写入。

通过：set 后重新读取为目标模型
通过：没有启动模型请求

本地样例复跑

bash

python3 lab.py --output ./result a03

先分清四个配置层

层级	观察位置	作用
provider/model	models.providers 与 models list	确定 endpoint、协议和准确 ID
默认模型	models set / models status	为默认任务选择入口
当前会话	会话 /model 和实际运行记录	会话选择可能不同于全局默认
策略与 fallback	modelPolicy、fallback 列表	允许范围和失败回退；不是能力承诺

层级: provider/model
观察位置: models.providers 与 models list
作用: 确定 endpoint、协议和准确 ID

层级: 默认模型
观察位置: models set / models status
作用: 为默认任务选择入口

层级: 当前会话
观察位置: 会话 /model 和实际运行记录
作用: 会话选择可能不同于全局默认

层级: 策略与 fallback
观察位置: modelPolicy、fallback 列表
作用: 允许范围和失败回退；不是能力承诺

两个 Chat 模型的配置片段

openclaw-models.json

json

{
  "models": {
    "mode": "merge",
    "providers": {
      "apizt": {
        "baseUrl": "https://api.apizt.com/v1",
        "apiKey": "${tokenba_API_KEY}",
        "api": "openai-completions",
        "models": [
          { "id": "glm-5.3", "name": "GLM 5.3" },
          { "id": "deepseek-v4-pro", "name": "DeepSeek V4 Pro" }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": { "primary": "apizt/glm-5.3" },
      "models": {
        "apizt/glm-5.3": { "alias": "QR GLM" },
        "apizt/deepseek-v4-pro": { "alias": "QR DeepSeek" }
      }
    }
  }
}

切默认，再核对当前会话和允许范围

新开测试会话，用 /model 查看或切换；核对实际请求记录中的 provider 和准确 ID。
如果策略限制 models，检查当前 modelPolicy.allow 和 agents.defaults.models；models set 不会自动改 modelPolicy.allow。
先分别直测两个型号，确认稳定后再设计 fallback；启用后记录 requested 与 actual model。
不要把 Chat ID 放到 Responses 或 Messages provider 中；协议迁移另做工具和流式验收。

默认切换检查

bash

openclaw --version
openclaw models status
openclaw models list
openclaw models set apizt/glm-5.3
openclaw models status

小任务：读三条事实，写一份摘要

工具日志应有真实 read 和 write；摘要不补出时区、赔付或其他事实。
task-note.txt 未改，输出文件能够打开。
切换默认后再核对新会话和实际模型，不把旧缓存回答当验证。
保存全部回合和控制台实扣；这份任务没有执行在线模型，也没有费用或速度排名。

下载完整任务与记录项

常见失败按层处理

现象	先查	验收
Model not allowed	modelPolicy.allow 与实际 provider/model	所需覆盖策略明确允许
Key 在终端有，Gateway 没有	Gateway / service 的启动环境	原运行进程读取同名变量
切换后还是原模型	旧会话与 fallback 日志	新会话 actual model 对应目标
目录默认价格为 0	自定义模型 cost 元数据	不能当免费；以真实账单核对
文字可用工具失败	目标模型 tools 与协议	真实读取、写入和返回闭环

现象: Model not allowed
先查: modelPolicy.allow 与实际 provider/model
验收: 所需覆盖策略明确允许

现象: Key 在终端有，Gateway 没有
先查: Gateway / service 的启动环境
验收: 原运行进程读取同名变量

现象: 切换后还是原模型
先查: 旧会话与 fallback 日志
验收: 新会话 actual model 对应目标

现象: 目录默认价格为 0
先查: 自定义模型 cost 元数据
验收: 不能当免费；以真实账单核对

现象: 文字可用工具失败
先查: 目标模型 tools 与协议
验收: 真实读取、写入和返回闭环

模型切换不改变消息权限

此任务关闭真实渠道发送。改 provider 不会增加 WhatsApp、Slack、邮件或文件系统权限。需要这些能力时，独立验证渠道授权、工具范围与业务幂等。

OpenClaw 对自定义代理协议会调整部分专有字段。不能把原生 OpenAI 搜索、缓存提示或推理参数视为所有代理可用，按当前官方路由规则逐项测试。

怎样确认已经完成

默认、当前会话、策略和 fallback 都有可对应记录。
两个型号分别完成真实 read/write，原文件未变。
实际请求的型号、协议和全部费用可匹配。

常见问题

models set 后旧会话立即换模型吗？

默认模型和会话覆盖分别核对。使用 /model 和实际运行记录确认；需要受控对比时新开干净会话。

添加模型后为什么 Model not allowed？

当前 modelPolicy.allow 可能限制覆盖选择。官方说明 models set 和 aliases 操作不会修改该策略；检查规则而不是反复添加 ID。

配置里价格默认为 0，调用免费吗？

不是。自定义 provider 元数据缺失时的默认 cost 不能代表上游费用，控制台实际账单才用于对账。

OpenClaw 模型切换：provider、当前会话与 fallback

先看结论

开始前准备什么

继续操作前，核对当前配置与执行范围

本次操作和结果

切换后从配置回读目标模型

先分清四个配置层

两个 Chat 模型的配置片段

切默认，再核对当前会话和允许范围

小任务：读三条事实，写一份摘要

常见失败按层处理

模型切换不改变消息权限

怎样确认已经完成

常见问题

资料来源

全球顶尖大模型，一站式接入

创建 API Key

填写接入配置

发起第一次调用

OpenClaw 模型切换：provider、当前会话与 fallback

先看结论

开始前准备什么

继续操作前，核对当前配置与执行范围

本次操作和结果

切换后从配置回读目标模型

先分清四个配置层

两个 Chat 模型的配置片段

切默认，再核对当前会话和允许范围

小任务：读三条事实，写一份摘要

常见失败按层处理

模型切换不改变消息权限

怎样确认已经完成

常见问题

资料来源

全球顶尖大模型，一站式接入

创建 API Key

填写接入配置

发起第一次调用