OpenClaw 模型发现架构升级：无需发版，动态接入新模型

10 个关键问题 Q&A

1. Q：本次改造要解决的核心问题是什么？ A：解决 OpenClaw 以往必须等客户端发版，才能支持新大模型的痛点，实现不更新客户端即可加载新模型。
2. Q：现在 OpenClaw 从哪三处获取模型列表？ A：托管在线模型目录、服务商账号接口实时拉取、本机 PATH 中安装的 Codex 程序。
3. Q：托管目录多久更新一次，数据源是什么？ A：每 4 小时自动重建，基础数据来自 models.dev，叠加自定义清单、价格信息。
4. Q：为什么最初上报最新 Codex 版本的方案被回滚？ A：查询模型列表上报高版本 Codex，但实际运行会话仍使用内置旧版，模型能选中但发消息直接报错，问题后置。
5. Q：Codex 现在的选用规则是怎样？ A：优先加载 PATH 里本地 Codex；稳定版、同主版本、版本高于内置则启用，查询和运行共用它；失败自动回落内置 Codex。
6. Q：现在怎么获取模型支持的思考等级、API 端点？ A：直接读取服务商接口返回信息，不再依靠模型名称猜测，适配未知新模型。
7. Q：模型列表会不会因为目录更新、接口超时无故变少？ A：不会，新增保护逻辑：自动重试、切换目录时保留上一份完好模型列表。
8. Q：上千个模型太长，怎么优化选择器体验？ A：每个服务商配套人工每日维护的精选推荐列表置顶，其余模型折叠，搜索支持全库检索。
9. Q：还有哪些场景依旧需要 OpenClaw 发版？ A：没有安装更高版本本地 Codex 时，ChatGPT 可用模型仍受内置 Codex 限制；刚上线、目录还未收录的模型价格信息缺失。
10. Q：怎么查看当前 OpenClaw 实例能访问的全部模型？ A：执行命令：openclaw models list --refresh

OpenClaw 现在可以从托管模型目录、服务商账户以及你本地安装的 Codex 获取新增模型信息，推出新模型后，用户不必等待 OpenClaw 版本更新就能使用。原文链接：https://openclaw.ai/blog/authors/ayaan-zaidi作者：Ayaan Zaidi发布时间：2026 年 11 月 6日

当初 OpenAI 上线 GPT-6.1 Sol 时，通过 ChatGPT 账号登录 OpenClaw 的用户无法选择该模型。这是因为 OpenClaw 内置打包的 Codex 版本为 0.158.0，但 ChatGPT 仅向 Codex 0.159.2 及以上版本开放 Sol；而在当时，这个版本号只能通过发布新版本才能修改。

模型首发日正是用户最想尝鲜的时候，而我们的版本机制却成了阻碍。于是，我们历时约五周、提交了近 80 个拉取请求，重构了 OpenClaw 发现可用模型的整套逻辑。

本文会介绍 OpenClaw 当前获取模型列表的三大来源、一次上线后又回滚的方案，以及仍然需要依靠版本更新才能实现的场景。

过去，模型是怎样推送给用户的

以往，每个服务商插件都会在清单文件中内置模型列表，这份清单随 OpenClaw 安装包一起打包发布。服务商以插件形式接入，而插件是和程序发布版本绑定死的。

图 1：新模型推送到模型选择器的旧流程与新流程对比

如今 OpenClaw 会从三处动态加载、填充模型列表：

1. 可自动更新的托管模型目录

我们在 catalog.openclaw.ai 托管了模型目录。后台任务每 4 小时重建一次目录数据：数据源取自 https://models.dev/，在此基础上叠加我们自定义的清单配置、补充价格信息，最终对外发布。目前目录收录约 1000 个模型。

图 2：托管目录的数据构成，以及下发至运行中的网关的流程

正在运行的网关会在后台检测目录新版本，并实现无缝切换：

• 旧逻辑：网关下载新目录后，会继续沿用旧目录，直到你重启程序
• 新逻辑：新会话直接使用新版目录；已经启动的会话会沿用开始时加载的目录，保证该会话的模型列表、价格信息自洽匹配

发布脚本同时会下架服务商已经停服、不再提供的模型。举个例子：NVIDIA 从其 API 下线了 2 个模型，但之前目录里还保留着它们的条目。

曾经踩过的坑9 月 21 日，models.dev 将 kimi-for-coding 拆分成两条独立条目。当时我们的发布程序把单个服务商数据缺失判定为致命错误，导致整轮构建全部失败。那段时间里，GPT-6 Sol、Luna 都没法推送到存量用户。现在，单个服务商异常只会输出警告，其余服务商的数据更新不受影响。

2. 只要你的账户有权限，就能直接选用

托管目录记录的是公开可用模型，而你的服务商账户决定了你实际能不能调用。当你登录服务商账号后，OpenClaw 会拉取该账户下的模型清单，展示其中所有对话模型 —— 包括比当前 OpenClaw 版本更新、或是仅对你账号开放的私有模型。

• OpenAI API Key：旧版提示 Unknown model: openai/gpt-5.2（明明账户有权限）；新版会自动展示并运行账户列表里的对话模型
• Anthropic API Key：旧版 Claude 新模型必须等 OpenClaw 发版才会显示；新版只要 Anthropic 接口返回该模型，立刻可见
• Claude Code：旧版是我们手动维护的固定列表；新版直接读取你账号对应的 Claude Code 模型菜单
• GitHub Copilot：旧版调用 kimi-k3 首条消息就报错 unsupported_api_for_model；新版自动识别每个模型适配的接口端点并正确路由
• Grok 订阅：旧版 grok-4.7-build-fast 仅提供「关闭思考 / 极致思考」两档；新版跟随服务商清单，提供低、中、高、超高四档思考强度
• Ollama：旧版执行 ollama pull 拉取模型后，不会在选择器里出现；新版刷新后即可展示
• OpenCode Go：旧版会漏掉你账户下 4 个可用模型；新版全部展示

这部分改造有一半工作量集中在模型能力描述。过去 OpenClaw 靠模型名称猜测它支持的思考等级、请求格式，遇到从未见过的新模型就会出错。服务商本身已经在接口返回里标明了这些能力，现在我们直接读取这份官方信息，不再靠名字猜。

3. Codex 版本适配问题（也就是开篇提到的 Sol 故障）

ChatGPT 会根据客户端上报的 Codex 版本，决定向你开放哪些模型。旧版本 Codex 能看到的模型列表更短。

我们最初的修复方案很简单：从 npm 查询最新 Codex 版本，拉取模型列表时上报这个版本号。这么改完，Sol 确实出现在选择器里了。

问题在于：查询模型列表时上报的是 0.161.0，但实际运行对话会话时，程序还是用打包内置的 0.160.0 二进制文件，而这个程序本身在每次请求里都会上报自己真实版本。于是出现一个糟糕的现象：需要高版本 Codex 的模型能被选中，但发送第一条消息就返回 HTTP 400。我们只是把报错时机从「选择模型时」延后到「首次对话」，问题更隐蔽，所以我们回滚了这个方案。

图 3：不同设计方案下，查询模型列表所用 Codex 版本、实际运行会话所用 Codex 版本对比

OpenClaw 会先检索系统环境变量 PATH 中是否存在本地安装的 Codex：如果是稳定版、主版本号和内置版本一致、且版本号高于内置版，OpenClaw 会和它完成完整握手校验；校验通过后，同一个 Codex 程序既负责拉取模型列表，也负责运行对话。一旦校验失败，自动回退到内置打包的 Codex。OpenClaw 不会自动帮你安装 Codex。

下面是 Mac 环境、本地安装 Codex 0.162.1 的网关测试日志：

[agent/embedded] Codex app-server: using installed ~/.local/bin/codex 0.162.1 (newer than bundled 0.161.0)

现在，你只需要升级全局的 Codex，就可以使用依赖高版本 Codex 的新模型。

保证模型列表不会无故变少

找到模型是一个难题，让模型稳定停留在列表里是另一个难题。过去经常出现和用户操作无关的模型丢失问题：

• OpenRouter 接口单次超时
  旧版：列表从 466 个直接只剩 3 个，必须手动刷新才能恢复
  新版：自动重试，首次等待 30 秒，后续间隔逐步拉长，最长间隔 30 分钟
• 网关切换新版托管目录
  旧版：生产环境网关最多会出现 4 分钟内模型从 599 个掉到 54 个
  新版：全程维持 599 个；新目录完整加载完成前，继续保留上一份完好列表
• 修改默认模型
  旧版：耗时 68–142 秒，网关需要重载全部大型插件，界面卡死
  新版：耗时 0.6–1.4 秒，复用已经加载好的插件

模型选择器的打开速度也优化了：优先展示 OpenClaw 已经缓存的模型，后台异步补全剩余数据，不再像之前那样最长等待 5 秒，等全部模型发现完成才弹出选择框。

上千模型太多了，做精选推荐

全部模型展示后列表会过于冗长，仅 OpenRouter 一家就有 466 个模型。因此托管目录现在为每个服务商维护一份精选推荐列表，在选择器置顶展示。

图 4：选择器里 OpenRouter 分组示意图；搜索功能仍然检索全部模型

这是我们自有网关的选择器示例：OpenAI 分组里，当前使用模型排在第一位，随后是 2 个推荐模型，其余 33 个模型折叠收纳在一行入口内。

图 5：运行中网关的控制面板对话选择器，OpenAI 分组截图

推荐列表由人工维护，每日更新，综合我们内部实测数据与各类评测基准筛选。

核心结论

1. 查询模型列表的 Codex 版本，必须和实际运行会话的 Codex 版本一致。上报一个版本、跑会话用另一个版本，只是把报错延后，治标不治本。
2. 从服务商接口读取模型能力，不要靠模型名称推断。服务商清单自带思考等级、支持端点等信息；基于名字写的规则，遇到从未见过的新模型必然失效。
3. 保留上一份有效列表。刷新失败、切换目录的过程中，绝不允许选择器里模型数量无故变少。
4. 单个数据源故障，不能阻塞全局。models.dev 里一个服务商条目更名，曾经导致全部服务商目录更新中断，现在降级为警告，互不影响。

仍然需要等待版本更新的场景

• 如果你没有自行安装更高版本的 Codex，内置打包版本依旧决定了你在 ChatGPT 里能看到哪些模型。
• 比托管目录更新更早上线的模型，暂无价格数据：OpenClaw 会标注费用未知，并采用保守的默认限流策略，直到目录同步更新。

你可以执行这条命令，查看当前实例能访问到的全部模型：

openclaw models list --refresh

后续规划

我们会持续优化体验，接入更多服务商。如果你账户里有权限的模型没有在 OpenClaw 中显示，可以去 GitHub 提 issue，并附上上面命令的输出：https://github.com/openclaw/openclaw/issues

致谢

本文作者：Ayaan Zaidi感谢：

• vincentkoc：目录 v2 版本、按路由独立定价能力
• ly85206559：models.dev 服务商别名适配
• mcooks-cmd：目录后台任务内存泄漏修复
• steipete：多服务商目录并行刷新提速

核心拉取请求：https://github.com/openclaw/openclaw/pull/137131https://github.com/openclaw/openclaw/pull/158000https://github.com/openclaw/openclaw/pull/167462https://github.com/openclaw/openclaw/pull/168228https://github.com/openclaw/openclaw/pull/167230https://github.com/openclaw/openclaw/pull/167370

标签：models、providers、catalog、codex、engineering