OpenClaw Model Provider（模型提供商）完整详解

一、核心定位与边界区分

Model Provider 是模型通信适配层插件抽象，负责对接各类大模型上游服务（OpenAI、Anthropic、DeepSeek、本地Ollama、兼容OpenAI协议私有网关等），完成鉴权、协议转换、请求封装、流式解析、错误分类、用量统计。

一句话边界：

Provider = HTTP/网络协议适配器（通信层）

Harness = Agent Turn 执行运行时（推理循环层）

必须厘清层级边界（极易混淆）

Channel Adapter：南北向，对接外部IM/Web客户端（飞书、Websocket）
Gateway 内核：会话管理、SessionLock、上下文引擎、安全规则、路由
Model Provider（本模块）：东西向，网关 ↔ LLM服务之间的网络适配
Agent Harness：驱动一轮Agent ReAct循环（内置openclaw-harness / codex-harness）
LLM上游服务：云端API、本地推理服务、Codex二进制进程

核心设计目标

模型无关（Model-Agnostic），网关上层所有业务逻辑不感知底层模型厂商协议；
统一模型寻址规范 provider/modelId；
封装厂商差异：鉴权头、消息格式、思考链格式、工具schema、错误码体系；
为上层Harness提供标准化推理请求/流式分片/响应结构；
支撑模型路由、主备fallback、多密钥轮询、用量计量、故障分级。

适用范围

✅ HTTP API类模型、兼容OpenAI/Anthropic协议网关、Ollama、LM Studio、阿里云百炼等

❌ 不负责：Agent内部ReAct循环、上下文组装、工具调度；这类逻辑属于Harness职责

特例：Codex/Claude-CLI这类独立本地二进制智能体 ，拥有自有进程与原生循环：

依然会注册一个轻量Provider用于寻址；但真实执行交给配套Harness + Native线程池，Provider仅做路由元数据声明，不直接发起推理请求。

二、Provider三层架构

Layer1：插件注册层（网关启动阶段）

Provider以可插拔插件形式注册到网关注册表：

唯一providerId（openai/anthropic/ollama/custom）
认证方式定义（API Key、OAuth、环境变量映射 ${VAR:default}）
内置钩子集合、模型目录能力声明
支持内置原生Provider + 第三方自定义Provider插件

Layer2：配置与模型目录层（三层配置体系加载）

配置路径：global.yaml → agent.yaml → tenant.yaml

yaml 复制代码

models:
  providers:
    openai:
      baseUrl: "${OPENAI_BASEURL:https://api.openai.com/v1}"
      apiKey: "${OPENAI_API_KEY}"
      timeoutSeconds: 120
      # 该提供商下所有模型清单
      models:
        - id: gpt-4o
          name: GPT-4o
          contextWindow: 128000
          maxTokens: 16384
          # 关键：绑定agentRuntime，决定后续Harness选择
          agentRuntime: auto

寻址标准格式：provider/modelId，例如 openai/gpt-4o

Layer3：运行时执行钩子层（推理调用阶段）

Provider提供一系列标准化钩子，网关/Harness调用推理时依次执行：

normalizeRequest：标准化请求体，统一转换为厂商私有协议
wrapStream：原始流式分片 → OpenClaw标准Chunk事件
classifyFailoverReason：区分可重试错误（429、5xx）/永久错误（401密钥失效）
resolveThinkingProfile：原生思考链（reasoning/think标签）适配
normalizeToolSchema：统一工具函数描述格式，抹平厂商差异
fetchUsage：提取输入/输出token用量，供给观测与成本统计

三、完整消息链路（标准内置Harness + HTTP Provider）

复制代码

1. Channel接收消息 → Gateway抢占SessionLock，加载Agent六层MD
2. ModelRouter 根据agent配置选出主模型引用 primary: openai/gpt-4o
3. 【查找对应Model Provider：openai】
4. Harness选择器读取model条目内 agentRuntime=auto → 选中builtin-openclaw-harness
5. 内核构造PreparedAttempt、RuntimePlan安全策略包
6. Harness发起推理请求，交由openai Provider处理
===== Provider内部执行 =====
7. Provider解析环境变量API Key，组装HTTP Header
8. 将标准化transcript消息转换为OpenAI messages格式
9. 发起HTTP/流式请求
10. 持续接收服务端chunk，通过wrapStream转换为统一on_stream_chunk事件
11. 推理结束，提取token用量、结束原因
===== 返回网关 =====
12. 标准化TurnResult回传给Harness
13. Harness解析是否存在tool_call，上交内核执行三层Tool治理
14. 一轮Turn完成，释放SessionLock，更新transcript

特殊链路：Codex本地二进制（Provider + 外部Harness + Native线程）

复制代码

modelRef: openai/codex-v1
model配置 agentRuntime: codex
1. 路由找到openai provider（仅作为寻址元数据载体）
2. Harness选择器匹配codex-harness
3. 任务投递至Native线程池
4. codex-harness直接管理本地二进制进程通信
5. Provider不再负责HTTP调用，仅提供认证、模型能力元信息

重点区分：Provider存在 ≠ Provider一定发起网络请求；原生智能体场景Provider退化为元数据注册与路由标识。

四、核心内置能力详解

4.1 多密钥轮询 & 密钥优先级体系

支持单Provider配置多组API Key，自动轮询、失效自动剔除

优先级（由高至低）

会话/租户临时覆盖密钥
PROVIDER_API_KEY（主密钥）
PROVIDER_API_KEY_1、PROVIDER_API_KEY_2 多密钥列表
PROVIDER_API_KEYS 逗号分隔批量密钥
密钥失效（401）自动标记冷却，避免持续无效请求。

4.2 错误分级与回退协同（和模型fallback、Harness回退联动）

Provider钩子 classifyFailoverReason 将错误分为三类：

临时可重试：429限流、5xx服务过载、网络超时 → 自动重试，未耗尽重试则不触发模型候选链切换
永久故障：密钥无效、权限关闭、模型不存在 → 直接进入agents配置的fallbacks模型候选链
业务拒绝：内容审核拦截、参数非法 → 不重试、不切换模型，直接返回用户

区分两条独立降级链路：

1）模型候选链切换（更换provider/model）；

2）Harness内部fallback（同模型下外部Harness切内置Harness）。

4.3 流式标准化适配

各厂商流式格式差异巨大（OpenAI chunks、Anthropic delta结构）

Provider wrapStream 统一输出标准事件集合：

文本增量
思考内容增量
tool_call 增量
结束标记、token消耗快照
保证上层Harness、Per-Request观测Hook完全不用区分底层模型。

4.4 Thinking（深度思考/Reasoning）适配

不同模型原生思考标签格式不统一：

Claude：thinking 块
DeepSeek：...
Provider通过resolveThinkingProfile识别、剥离、标准化，
同时向Harness暴露"是否支持原生思考"能力，支撑深度推理自适应预算。

4.5 工具Schema归一化

部分厂商对函数入参、description存在格式限制；

Provider自动清洗、补齐schema，保证统一ReAct循环无需针对每个模型修改工具描述。

五、Model 寻址 → Provider → Harness选择完整串联逻辑

复制代码

agent配置 primary: openai/codex-v1
  ↓
1. ModelRouter 拆分 providerId=openai, modelId=codex-v1
2. 在models.providers.openai.models[]查找该model条目
3. 读取 model.agentRuntime = codex
   a. 如果是固定runtime ID：查找对应Harness插件
   b. 如果是auto：遍历所有已启用Harness，调用supportsRoute(provider,model)匹配
4. 选中Harness后执行runTurn；推理通信由对应载体执行
   - runtime=openclaw（内置）→ 使用对应Provider发起HTTP调用
   - runtime=codex → codex-harness接管，Provider仅用于配置元信息

六、Model Provider vs Agent Harness 核心对比表

维度	Model Provider	Agent Harness
定位	模型通信适配器（网络/协议层）	Agent一轮Turn执行运行时（循环层）
职责	鉴权、HTTP封装、协议转换、流式解析、错误分类	驱动ReAct循环、上下文交互、工具调用协调
运行载体	协程（通用HTTP模型）	协程（内置harness） / Native OS线程（codex/cli）
是否管理进程	一般不；仅原生二进制场景不负责通信	外部Harness负责管理本地二进制进程
典型实例	openai provider、ollama provider	builtin-openclaw-harness、codex-harness
依赖关系	Harness在需要调用LLM时调用Provider	Harness独立选择、持有Provider引用

最简记忆口诀：

Provider管"怎么发给模型"；Harness管"怎么组织一轮Agent思考循环"。

七、与全OpenClaw体系联动

7.1 联动三层配置分层 + ${VAR:default}

Provider所有参数（baseUrl、apikey、timeout）遵循三层配置优先级，原生支持环境变量插值；

可通过ConditionalOnGlobalEnv离线环境禁用外网Provider。

7.2 联动 Harness选择 / Harness回退

model条目挂载agentRuntime，作为Harness选择核心输入；
Harness回退（codex → builtin）切换运行时，但仍然使用同一个Provider模型元数据；
模型fallback切换到备用model，会重新完整执行Provider查找 + Harness选择流程。

7.3 联动并发安全（Per-Request）

所有Provider推理请求绑定当前Per-Request上下文；

异步流式chunk回调自动生成只读上下文快照，配合Observability Per-Request Hook，杜绝Trace串扰；

Cron定时任务调用模型使用CronContextHolder上下文。

7.4 联动四层Langfuse观测

ModelRunSpan 由Provider推理事件驱动；
Span自动标签：provider_id、model_id、stream=true/false；
Provider提取的输入/输出token用量统一上报，支持按租户、Provider维度成本分摊；
错误类型、重试次数、回退原因全部写入Span。

7.5 联动 SubAgent + Transcript Mirror

子代理独立执行Model路由、独立选择Provider+Harness；
子代理镜像上下文交付选中Harness，推理请求走对应Provider；
子代理结果遵循Transcript Mirror摘要受控回写规则。

7.6 联动 Context Compaction / 深度推理自适应

Provider上报模型contextWindow上限，作为压缩硬边界；
Harness根据RuntimePlan传递thinking预算，Provider适配模型原生思考参数。

7.7 联动三层Tool治理

Provider仅标准化tool_schema；工具真实执行永远上交内核ToolAdapter沙箱层；Provider与Harness均无权绕过三层Tool治理直接运行工具。

八、自定义Provider开发准入规范

仅做协议适配、鉴权、消息转换；不要嵌入ReAct循环逻辑；存在循环逻辑应当实现Harness；
所有网络IO必须支持超时、取消（支持abortTurn中断推理）；
必须完整实现流式标准化钩子，禁止厂商私有chunk直接向外暴露；
区分永久错误/临时错误，正确支撑上层回退机制；
禁止硬编码密钥，全部通过环境变量/配置层读取，兼容${VAR:default}插值；
支持只读上下文快照，异步回调不捕获可变会话引用，防止并发竞态。

九、常见误区澄清

❌ 误区1：Provider = Harness

✅ 纠正：Provider是通信适配器；Harness是执行循环；内置Harness大量依赖Provider发起HTTP请求；Codex场景Provider仅作为路由元信息。

❌ 误区2：只要注册Provider，就一定会发起HTTP网络调用

✅ 纠正：codex/cli类原生智能体，Harness接管进程通信，Provider只保存模型能力、配置元数据。

❌ 误区3：agentRuntime配置写在provider顶层，全局统一

✅ 纠正：标准规范为model条目层级配置agentRuntime；provider顶层仅作为未配置model时的默认继承值。

❌ 误区4：Provider内部可以自主执行工具调用

✅ 纠正：工具调用属于内核三层Tool治理范围；任何tool_call必须向上层Harness/网关内核上交。

十、生产最佳实践

云端模型优先使用官方内置Provider；私有兼容OpenAI网关使用custom通用Provider，减少定制开发；
密钥统一使用环境变量 ${PROVIDER_KEY:} 无默认格式，禁止明文写入yaml；
高可用架构配置fallbacks模型候选链，配合Provider错误分级自动切换；
codex等原生智能体：model显式配置agentRuntime: codex，并开启modelSelectionLocked:true锁定会话运行时；
Langfuse配置指标告警：监控Provider 4xx/5xx错误突增、连续鉴权失败；
多租户场景利用tenant.yaml覆盖Provider参数，实现租户独立密钥与模型权限隔离。

OpenClaw Model Provider（模型提供商）完整详解

一、核心定位与边界区分

必须厘清层级边界（极易混淆）

核心设计目标

适用范围

二、Provider三层架构

Layer1：插件注册层（网关启动阶段）

Layer2：配置与模型目录层（三层配置体系加载）

Layer3：运行时执行钩子层（推理调用阶段）

三、完整消息链路（标准内置Harness + HTTP Provider）

特殊链路：Codex本地二进制（Provider + 外部Harness + Native线程）

四、核心内置能力详解

4.1 多密钥轮询 & 密钥优先级体系

4.2 错误分级与回退协同（和模型fallback、Harness回退联动）

4.3 流式标准化适配

4.4 Thinking（深度思考/Reasoning）适配

4.5 工具Schema归一化

五、Model 寻址 → Provider → Harness选择完整串联逻辑

六、Model Provider vs Agent Harness 核心对比表

七、与全OpenClaw体系联动

7.1 联动三层配置分层 + ${VAR:default}

7.2 联动 Harness选择 / Harness回退

7.3 联动 并发安全（Per-Request）

7.4 联动四层Langfuse观测

7.5 联动 SubAgent + Transcript Mirror

7.6 联动 Context Compaction / 深度推理自适应

7.7 联动三层Tool治理

八、自定义Provider开发准入规范

九、常见误区澄清

十、生产最佳实践

7.3 联动并发安全（Per-Request）