OpenClaw 源码解析（一）：模型接入从 openclaw.json 到 Runtime Execution 的完整链路

在使用 OpenClaw 构建 Agent 或多模型系统时，大多数开发者往往只关注模型配置，例如：

• 如何在 openclaw.json 中配置 provider

• 如何设置默认模型

• 如何切换模型

但如果想真正理解 OpenClaw 的模型系统，就必须搞清楚一个核心问题：

模型从配置文件到最终调用 API 的完整执行链路是什么？

本文将从 源码逻辑 + 官方文档 两个维度，对 OpenClaw 的 Model 接入机制进行一次完整拆解，包括：

• 配置层（Configuration）

• Registry 物化（Materialization）

• Model Catalog 构建

• Model Selection 策略

• resolveModel(…) Binding

• Runtime Execution

一、先给一个总判断

完整链路

openclaw.json
        │
        ▼
models.providers / agents.defaults
        │
        ▼
models.json (registry materialization)
        │
        ▼
Model Catalog Construction
        │
        ▼
Model Selection
(default / alias / allowlist)
        │
        ▼
resolveModel(…)
(Model Binding)
        │
        ▼
Auth / Profile / API Key Resolution
        │
        ▼
runEmbeddedAttempt(…)
        │
        ▼
activeSession.prompt(…)
        │
        ▼
Streaming / Tools / Error Handling

二、OpenClaw model 接入的完整路径

1. 配置层：openclaw.json才是主配置源

国际包当前推荐的入口是 ~/.openclaw/openclaw.json。你主要会改两块：一块是 models.providers，用于声明 provider、baseUrl、apiKey、api 和 models[]；另一块是 agents.defaults，用于设默认模型 primary，以及可选的 allowlist agents.defaults.models。官方文档还明确说了：如果你设置了 agents.defaults.models，它就会变成 allowlist。

2. 物化层：models.json是派生文件，不是首选编辑文件

官方文档说明，custom providers in models.providers 会被写入默认 agent 目录下的 models.json，这个文件默认参与 merge。也就是说，models.json 更像运行时 registry 投影，而不是主编辑入口。你应该把 openclaw.json 当源配置，把 models.json 当验收产物。

3. catalog 层：系统把“有哪些模型”整理成目录

模型目录的作用不是直接执行，而是整理“系统里看得到哪些 provider/model”。官方模型文档和 provider 文档都把“选择 provider、列模型、设默认模型”作为独立概念，说明 catalog/selection 是运行前的独立阶段。openclaw models list 和 openclaw models set <provider/model> 也是官方给出的标准入口。

4. policy 层：默认模型、alias、allowlist 在这里起作用

这一层决定“哪些模型允许被选中”。你前面已经从源码里验证过，provider/model ref 会经历 normalize、alias 解析、default 解析和 allowlist 判断。官方文档与 CLI 设计也印证了这一点：agents.defaults.model.primary 是默认模型入口，而 agents.defaults.models 会收紧为 allowlist。

5. binding 层：resolveModel(…)把 ref 变成可尝试执行的 Model<Api>

这一层是最容易被误解的地方。binding 成功，表示 OpenClaw 已经把 (provider, modelId) 解析成了可供 runtime 使用的模型对象；但 binding 成功并不等于 end-to-end 一定可运行。你已经从 model.ts 看到了：只要命中 discovered path、inline config path、forward-compat path、OpenRouter pass-through，甚至 generic configured-provider fallback，都可能生成 model object。源码意义上，这保证的是“可绑定”，不是“远端接口一定真的兼容”。

6. execution 层：真正触发模型是在 activeSession.prompt(…)

OpenClaw 的运行时会根据最终选中的 api adapter 决定请求/响应协议、streaming wrapper、extra params、tool-call 兼容逻辑。官方支持的 api 类型目前包括 openai-completions、openai-responses、openai-codex-responses、anthropic-messages、google-generative-ai、github-copilot、bedrock-converse-stream、ollama；文档还把 api 描述为“控制 request/response compatibility handling 的 provider API adapter”。这说明 api 不是标签，而是运行时 transport dialect。

三、为什么 api这么关键

如果只看配置，很容易把 provider 当成最重要的字段；但对 OpenClaw 来说，真正决定“按什么协议去调用”的是 api。官方当前文档把 api 定义为 adapter selection，控制模型调用时的 request/response compatibility handling。你可以把它理解成：provider 决定“你是谁”，api 决定“我怎么和你说话”。

这也是为什么很多第三方或国内平台会配成：

"api": "openai-completions"

不是因为它们就是 OpenAI，而是因为它们对外暴露的是 OpenAI-compatible dialect。OpenClaw 官方文档也明确支持 custom/base URL providers，并且像 vLLM 这类 OpenAI-compatible 服务就是按 openai-completions 接入。

四、国内模型接入策略：不要一刀切

1. 第一优先级：能走内置 provider，就不要走 custom

例如火山方舟，OpenClaw 官方当前 provider 文档已经把 volcengine 列为内置 provider 之一，并给了示例模型与认证方式。对这种平台，最佳策略是优先用内置 provider，因为 catalog、auth、selection、binding、runtime compat 都更稳。

2. 第二优先级：OpenAI-compatible 的国内平台，走 custom provider

像硅基流动，如果官方 provider 列表没有把它列成内置 provider，但平台本身明确提供 OpenAI Compatible 接口、标准 /v1 base URL、streaming、function calling/tools，那它就适合走：

"api": "openai-completions"

这种路线。SiliconFlow 官方文档明确提供了 OpenAI Compatible 使用方式、https://api.siliconflow.cn/v1、流式和 tools/function calling 能力。对这类平台，custom provider 是合理策略。

3. 第三优先级：协议不兼容的国内平台，不要只靠写配置

如果一个平台的接口不是 OpenAI-compatible，也不是 OpenClaw 当前支持的其他 api adapter 之一，那就不是“写 provider 配置”能解决的，而是要开发或引入新的 adapter/runtime compatibility 层。因为 binding 可以成功，但 execution 还是会失败。官方当前已公开的 api 适配类型是有限集合，不是无限可扩展的自由字符串。

五、多国内模型接入时，openclaw.json应该怎么维护

推荐把模型相关内容固定成三块：

第一块是 models.mode，控制 merge 或 replace。

第二块是 models.providers，定义 provider、baseUrl、apiKey、api、models。

第三块是 agents.defaults，定义默认模型与 allowlist。官方文档已经明确：models.providers 是 custom provider 的入口；agents.defaults.models 一旦写了，就会成为 allowlist。

如果要挂多个国内模型，最稳的做法是：

• 一个 provider 对应一个平台，例如 siliconflow、deepseek、myproxy

• 每个 provider 下用 models[] 列多个模型

• agents.defaults.model.primary 只选一个默认模型

• 如果你写了 agents.defaults.models，把所有允许的模型都列进去

否则会出现一种很典型的坑：provider 配进去了、catalog 可见、binding 也许成功了，但由于 allowlist 没放行，模型就是“看得见但选不中”。官方文档对这一点说得很明确。

六、merge和 replace的正确使用策略

用 merge 的时候

适合你在现有模型系统上做增量补充，比如保留 OpenClaw 原有 provider，同时再加几个国内 custom provider；也适合你还要和官方 onboarding / wizard 共存。官方文档说明 models.json 默认参与 merge。

用 replace的时候

适合你们后台统一托管模型清单、希望配置结果可预测、避免 agent 目录下旧 models.json 残留值继续参与合并。最近 GitHub issue 里已经有人把 models.mode = "replace" 当成解决 merge 残留、历史明文 key/baseUrl 被保留问题的可靠 workaround。

我给你的实战建议

你个人研究、频繁试 provider 的阶段，用 merge 比较方便。

你们后台产品化、要给用户稳定托管国内模型接入时，用 replace 更稳。最近 issue 里暴露出的 merge 保留旧值问题，正说明托管场景下 replace 更容易得到确定结果。

七、升级、回滚、灰度接入的推荐策略

1. 升级前

先备份：

• ~/.openclaw/openclaw.json

• ~/.openclaw/agents/<agentId>/models.json

• 相关 auth 配置与环境变量来源

同时记录当前版本、当前默认模型、当前 provider 列表。官方模型与 provider 文档都把配置、模型选择、默认模型作为主入口，所以这些就是升级最小快照。

2. 升级时

如果这次升级涉及 provider 结构变化、baseUrl 变化、api 变化，优先切到 replace 模式，避免旧 models.json 参与 merge。最近 issue 明确指出 merge 可能保留旧 apiKey、baseUrl 等内容。

3. 升级后验证

不要只看配置文件，至少做三层验证：

• openclaw models list

• openclaw models status

• 基础 agent run 文本验证

官方文档把 openclaw models list 和 openclaw models set 当成标准模型验证入口。

4. 回滚策略

如果升级后模型选择异常、明明改了 openclaw.json 但行为像还在吃旧值，最优先检查 models.json 是否残留旧数据。回滚时推荐：

• 恢复之前备份的 openclaw.json

• 恢复或清理对应 agent 的 models.json

• 临时切 models.mode = "replace" 再启动一次，确认运行时 registry 被重建

近期 issue 里已经证明，replace 是绕开 merge 历史残留的直接办法。

八、给国内模型接入做一个成熟分级

第一档：官方原生支持

例如 volcengine/* 这种已经在官方 provider 体系里的平台。

特点是：provider native，风险最低。

第二档：兼容协议支持

例如 SiliconFlow 这类 OpenAI-compatible 平台。

特点是：适合通过 custom provider + openai-completions 接入，但仍要验证流式、tools、错误处理。

第三档：仅可配置 / 可绑定

即配置能写入、binding 能通过，但 execution 还没证实。

这类平台最容易制造“已支持”的错觉，应该在产品文案里明确标成“实验接入”或“兼容性待验证”。