OpenClaw 这个系列写到第五篇终于要碰整个系统里最能决定用户体验的部分模型与提供商系统。我在好几个群里都看到有人问为什么 OpenClaw 里模型配置不像别的工具那样一行 base_url 就完事还要拆出 providers、models、capabilities 好几层也有人说本地明明装了 Ollama接上去却提示“模型繁忙请稍后再试”完全搞不清是模型没加载还是路由没走对。这些问题归根结底都是因为没把“模型”和“提供商”当成两件事来理解。这篇我打算用实际部署过的配置把模型抽象、提供商适配、路由容错、本地与云端混合调度完整过一遍。无论你是刚把 OpenClaw 跑起来的新手还是已经在上面折腾过几个 skill、想接入 qwen2.5-3b、ollama 或其他本地模型的老手相信都能从中找到可以直接抄的配置和排查思路。我会尽量少讲空泛的架构理论多写配置、命令和那些文档里不会写的运行细节毕竟这个系列走到第五篇该上点硬货了。1. 模型与提供商为什么要拆成两件事1.1 单一模型接入的坑早期 OpenClaw 的模型配置确实简单一个model: gpt-4o-mini加上一个固定地址就完事。但这种写法在个人使用场景下很快就会碰壁你想把默认模型切成 localhost 上的 qwen2.5-3b得改代码你想用兼容 OpenAI 接口的本地推理服务又得改代码更麻烦的是一旦某个模型服务端挂了整个智能体直接瘫痪没有回退方案。这个问题的本质在于模型名承担了太多职责——它既是“能力描述”又是“寻址方式”还是“运行参数”。真正要灵活调度模型这三个职责必须拆开。后来 OpenClaw 把系统重构成了两层模型是抽象层面的描述提供商是实现层面的来源。模型只说我想要什么能力、多大上下文、是否支持工具调用提供商只负责这些能力从哪里来、用什么协议取。1.2 适配层把“请求”和“来源”隔离开理解 OpenClaw 提供商系统可以先看一个所有主流工具都在用的套路。OpenClaw 对每个提供商做了一层适配接口核心是 ChatComplete 和 Embedding 两类方法。OpenClaw 的主进程永远不直接访问某个具体模型服务它面对的是一个标准化的请求结构底层是 Ollama、OpenAI、Anthropic 还是自己写的一个内部推理网关核心层完全不关心。这个设计的好处是新接一个推理后端只需要写一个适配器不需要动上层逻辑。比如我要接一个公司内部的统一推理平台先看它有没有提供 OpenAI 兼容接口如果有直接用 openai_compatible 类型走通基本不用写代码。我在 GPUSstack 上也验证过这一点只要提供商类型选对整个 agent 的调度、技能调用、上下文管理全部复用不用重新适配。1.3 能力标签模型不再只是名字为了让路由系统知道“某个模型到底能干什么”OpenClaw 给每条模型记录挂了 capabilities 标签。一条模型记录可以同时包含 chat、tool_calling、embedding 等能力标识。我自己的配置里qwen2.5-3b 会打上 chat 和 tool_calling一个本地 embedding 模型会打上 embedding 标签longformer 这类长文本模型则会打上长上下文标签。路由的时候候选模型经过能力过滤之后才进入排序阶段。如果当前任务是 agentic 的需要反复调用工具那么即使某个模型名字再好听只要没标 tool_calling就不会被选中。这个机制非常有价值尤其是一个人同时管理多台机器多个模型的时候能力标签直接帮你把模型分成了不同用途的池子而不是靠记忆去区分。2. 本地模型接入的完整实操2.1 先接 Ollama5 分钟跑通 qwen2.5-3bOllama 部署 OpenClaw 是最常见的本地场景。我建议先确认 Ollama 自己工作正常在终端跑一遍ollama list、ollama pull qwen2.5:3b然后 curl 一下它的 API 端点确认可以访问再接入 OpenClaw。curl http://127.0.0.1:11434/v1/models如果这个请求能返回模型列表说明 Ollama 的 OpenAI 兼容端点已经就绪。OpenClaw 里的 provider 配置类似这样providers: - name: ollama_local type: ollama base_url: http://127.0.0.1:11434 prefer: local models: - name: qwen2.5:3b alias: qwen3 capabilities: [chat, tool_calling, context_32k] priority: 10这里有两个小细节。第一地址建议写127.0.0.1而不是localhost。因为 OpenClaw 如果跑在容器或 WSL2 里localhost解析到的是容器或 WSL 自己连不上 Windows 宿主机的 Ollama。我踩过这个坑容器里用 localhost 配了一下午没通改成127.0.0.1后立刻正常。第二alias 是你在 skill 和对话里实际要用的名字它可以和模型名不一样。配置完成后用openclaw models list看模型是否注册成功再用openclaw providers test ollama_local做一次连通性测试。实测下来只要这两步过了后续对话基本不会再碰到模型接入层面的问题。2.2 LM Studio 与 OpenAI 兼容端点LM Studio 在本地模型场景里越来越流行它内置了 OpenAI 兼容服务做法和 Ollama 几乎一样只是默认端口是1234。Claude Code 调用 LM Studio 本地模型的思路完全可以照搬到 OpenClaw 上来。Provider 类型可以直接用 openai_compatiblebase_url 填http://127.0.0.1:1234api_key 随便填一个非空字符串就行因为 LM Studio 本地服务默认不校验 key。LM Studio 和 Ollama 有一个关键区别它更适合同时管理多个大模型并且支持 GPU offload 参数调整。如果机器显存不大在加载 7B 以上模型时建议在 LM Studio 侧限制 GPU offload 层数避免内存溢出导致进程被杀。实测下来LM Studio 在 Windows 上做本地推理的稳定性比早期版本好了很多配合 OpenClaw 的流式输出体验已经很接近云端 API。2.3 GPUSstack 部署模型到 Windows 的注意事项有些人喜欢用 GPU Stack 这类推理平台来管理多模型部署在 Windows 上部署时OpenClaw 侧的配置逻辑也一样选 openai_compatiblebase_url 指向 GPU Stack 暴露的服务地址。需要注意一个路径陷阱base_url 不要带/v1后缀。很多兼容服务的路由规则不一样有些能容忍/v1有些会直接返回 404。我第一次配 GPU Stack 时理所当然加了/v1结果跑了一下午全是 404去掉之后请求就通了。这一点同样适用于 FastChat、vLLM、LocalAI 这些常见推理框架统一建议填根地址。另外如果 GPU Stack 服务部署在另一台机器上OpenClaw 所在机器要确保能通过内部网络访问对应端口。很多 Windows 防火墙会默认拦截跨设备请求排查时先在这台机器上用 curl 请求一下模型地址确认网络层面通没通再去怀疑 OpenClaw 配置。2.4 自定义模型服务地址怎么配“自定义模型服务地址”这个问题在 langflow 里问的人最多OpenClaw 的答案其实是一样的provider 类型选 openai_compatible填 base_url 和 api_key。base_url 是服务根地址api_key 是服务端要求的密钥如果你本地服务不校验随便填个字符串就行。有一点建议给自定义 provider 起名时避免使用冒号和特殊符号尤其是模型别名里不要带冒号否则注册表解析时会出问题。我之前见过一个报错错误报告里的 message 写着“自定义模型 c”其实是因为别名my:cool:model被解析器拆成了三段后面两段被当成未知字段了。命名用中横线加字母数字最稳。2.5 回答那个灵魂问题只能用 API 方式使用算力吗很多人问 OpenClaw 是不是只能通过接入 API 的方式使用算力答案很明确不是。OpenClaw 可以完全本地推理。我自己在只有 CPU 的旧笔记本上也跑通过慢是慢了点但完全能用。OpenClaw 做得好的地方是支持冷热分离——把 embedding 和轻量对话模型放在本机把重活大模型放远程 API形成混合调度。实际配置中我会把本地 Ollama 里的 qwen2.5-3b 当成默认模型负责大部分日常对话和简单工具调用遇到复杂推理任务时通过 skill 里的模型绑定切到云端更大的模型。这样既节省 API 费用又能保证关键任务的效果还不必让 OpenClaw 完全依赖外网服务。3. 云端提供商与路由容错3.1 内置提供商与密钥管理OpenClaw 内置的提供商一般包括 OpenAI、Anthropic、Google 以及 Mistral 这类主流服务。这些 provider 的开启方式基本一致填 api_key然后模型列表里会有一批预设好的模型实例。但我强烈建议不要把 api_key 明文写在配置文件里而是放在环境变量中配置文件里用占位符引用。export OPENCLAW_PROVIDER_OPENAI_KEYsk-xxxx export OPENCLAW_PROVIDER_ANTHROPIC_KEYsk-ant-xxxx这样做的好处有两个。一是避免配置文件不小心提交到 git 仓库导致密钥泄露二是切换不同环境的配置时不用改文件只改环境变量就行。我已经不止一次看到有人把密钥贴进配置文件后发到群里问报错结果整把 key 直接公开实在没必要。如果同一个模型在多个 provider 下都可用路由系统会按 priority 排序数值越小越优先。我会把本地模型的 priority 设成 10云端的同款模型设成 20这样本地可用时优先走本地免费且隐私好本地挂了自动切到云端。3.2 路由优先级与故障回退OpenClaw 的故障回退机制不是无脑重试。我实测下来的行为是连接类错误会直接触发切换比如服务端口不通、TLS 握手失败这些错误重试没有意义立刻转到下一个 priority 的 provider。而超时类错误会先重试一次再切换因为本地模型经常有冷启动问题——模型要读盘加载、分配显存第一次请求可能要等几秒钟这种场景直接切换反而会把一个本来能用的本地源浪费掉。终端出现provider failover: ollama_local - cloud_openai这样的 warning 时不用太紧张这是正常回退。但要留意后续是否频繁出现如果本地 provider 隔几分钟就挂一次多半是显存不足导致服务进程被杀不是 OpenClaw 的问题。routing: retry_on_timeout: true max_retries_per_provider: 1 switch_on_connection_error: true这里我给的建议是 max_retries_per_provider 不要设太高一次足够。因为重试本身也消耗时间尤其是 agent 任务中一次工具调用可能涉及多次模型请求如果每个 provider 都重试三四次整个任务的时间会成倍膨胀。3.3 模型切换后对话跳闪的真相有用户反馈用 cc switch 切换模型后原对话不停跳闪。这个现象我在跑长对话时也遇到过根因不在模型本身而在上下文重放。切换模型时OpenClaw 会把历史消息重新发送给新模型做 prefilling让新模型“接上”之前的语境。如果历史消息很长网络又不够稳定流式输出过程中旧消息重放和新消息增量会混在一起视觉上就像对话在跳闪。解决方法有两个一是在切换模型前主动清空或重置上下文牺牲一点连续性换来稳定性二是在配置里关掉重放让新模型只基于当前这一轮消息继续不回溯历史。如果你是做日常聊天前者体验更好如果是做长文档总结建议选后者避免历史重放造成上下文长度超限。3.4 “模型繁忙”到底是谁的问题提示“模型繁忙请稍后再试”是目前群里问得最多的问题之一。我排查过十几次类似情况结论是绝大多数时候不是 OpenClaw 的问题而是本地推理服务的并发能力不足。Ollama 默认单请求排队如果你同时在 web viewer 里做流式输出又跑了一个 skill 在做并行工具调用显存不够时 Ollama 会直接返回 503。解决方案分两步。第一步给 Ollama 调大并发设置OLLAMA_NUM_PARALLEL2甚至更高第二步在 OpenClaw 侧限制并发请求数避免一次任务里同时发起多个模型调用。# 设置 Ollama 并发 set OLLAMA_NUM_PARALLEL2 ollama serveOpenClaw 侧则把 max_concurrent_requests 调低一般 1-2 就够了。个人智能体场景下真正需要高并发的场景很少限制并发反而能让每个请求更稳定、更快返回。4. 部署环境与配置实战4.1 Windows 上最常见的第一道坎WSL 环境校验Windows 用户部署 OpenClaw 时,如果报错“无法安全验证当前环境”,同时提示在 PowerShell 中运行wsl --status不要慌这不是安全软件拦截而是 OpenClaw 安装脚本在检查 WSL 内核组件是否完整。我遇到这个问题时在 PowerShell 里运行了一次wsl --status发现内核版本信息缺失重新执行wsl --update再跑安装脚本就好了。如果wsl --status显示“没有已安装的分发版”先运行wsl --set-default-version 2指定 WSL 版本再安装一个分发版。另外PowerShell 执行策略也可能导致安装脚本无法启动报错“无法加载脚本”这时运行下面的命令放开当前用户级别的限制Set-ExecutionPolicy -Scope CurrentUser RemoteSigned这个命令只影响当前用户不影响系统级的安全策略。我建议在 Windows 上部署 OpenClaw 时先把这两步走完再去看文档里的其他配置否则后面每一步都可能因为环境问题反复报错而错误信息又不指向真正的根因。4.2 配置文件长什么样一个可工作的 OpenClaw 模型配置通常包含三块providers 定义连接方式models 定义能力标签和别名routing 定义回退和超时策略。下面是我实际在用的一个精简版配置providers: - name: ollama_local type: ollama base_url: http://127.0.0.1:11434 models: - name: qwen2.5:3b alias: qwen3 capabilities: [chat, tool_calling] priority: 10 - name: nomic-embed-text alias: embed_local capabilities: [embedding] priority: 10 - name: cloud_openai type: openai api_key_env: OPENCLAW_PROVIDER_OPENAI_KEY models: - name: gpt-4o-mini alias: gptmini capabilities: [chat, tool_calling] priority: 20 routing: retry_on_timeout: true max_retries_per_provider: 1 switch_on_connection_error: true这里最容易被忽略的是 embedding 模型。很多智能体任务其实不直接依赖大模型而是先做检索再交给大模型总结。如果 embedding 模型没配置好后面接记忆系统和知识库都会出问题。我的习惯是默认把 embedding 模型指向本地因为这类推理比较轻量本地跑完全够用既能加快响应速度也能减少隐私风险。4.3 超时、并发与重试参数对照在调整参数之前先理解每个参数的含义。下面这个表是我根据自己的部署经验整理的常用参数和建议值参数默认值建议值说明request_timeout60s120s本地 7B 模型在 CPU 上生成长回复较慢超时设短了会被误判失败connect_timeout10s15s容器和跨网络部署时TCP 握手可能超过 10 秒max_retries_per_provider01只对超时类错误生效连接错误直接切换max_concurrent_requests41-2本地模型并发请求容易触发 503model_load_retries12冷启动加载模型的场景建议重试一次我刚开始用 OpenClaw 时踩过一个坑默认超时 60 秒本地 qwen2.5-3b 在 CPU 上生成一篇较长回复时直接超时OpenClaw 判定模型失败并切到云端白白浪费了本地算力。后来把 request_timeout 改成 120 秒切换频率明显下降。如果你的机器配置更低甚至可以考虑 180 秒。4.4 手机上的 OpenClawTermux 与 Windows Companion很多人在手机上部署 OpenClaw主要是想把个人智能体随身带。Termux 里安装 OpenClaw 的逻辑和 PC 端类似区别在于手机资源有限不建议本地跑 7B 以上模型。我试过在手机上跑 qwen2.5-3b速度勉强能接受但机身发热明显长时间使用会影响稳定性。更合理的做法是配置里打开远程推理开关让手机端只做客户端模型统一走服务器。Windows Companion 是配合 PC 端使用的辅助组件配置时会要求填入 OpenClaw 的服务地址和令牌。这里有个细节手机和 PC 要在同一个局域网内或者通过内网隧道打通。配置完成后可以在手机浏览器打开 web viewer 做验证如果页面能正常加载并完成对话说明联动已经生效。Companion 的主要作用是作为补充入口我在外网环境基本靠它应急实际主力还是终端或 API 调用。4.5 扩展skill 系统与模型绑定OpenClaw 的技能系统讨论度一直很高很少有人把 skill 和模型系统放在一起看。我个人觉得这俩其实是强相关的。每个 skill 可以绑定自己的模型需求。比如文档总结类的 skill 可以绑定长上下文模型正则提取类的 skill 用速度更快的小模型不需要所有任务都走同一个大模型。我在配置里会给特定 skill 指定模型映射一份类似下面的结构就够用skills: doc_summary: model: longformer max_tokens: 4096 quick_reply: model: qwen3 max_tokens: 256这样做的收益非常明显常用轻量操作响应快重活才有大模型参与整体 API 成本能降不少。如果只把 OpenClaw 当成一个聊天工具来用这个配置确实用不上但只要开始写自己的 skill模型绑定就是绕不开的一环。5. 常见问题与排查速查5.1 错误报告怎么读OpenClaw 出报错时终端会打印一份 error report 结构的报告下面通常分成 user-friendly information 和 technical detail 两块。第一块是给普通用户看的告诉你是模型繁忙、连接超时还是配置缺失第二块才是开发者定位用的堆栈信息。我强烈建议遇到报错先看 user-friendly information 里的 message不要一上来就翻堆栈。很多新手一看到堆栈就慌实际去搜最后几行栈帧浪费大量时间。比如最常见的“模型繁忙请稍后再试”就是 user-friendly 层的提示看到这一句你就应该先去查推理服务的并发和显存而不是盯着 OpenClaw 的调用栈看。5.2 模型下载失败与缺失模型处理模型下载失败是本地模型场景的高频问题。比如用户说自定义模型下载一直失败或者 ComfyUI 那边提示缺失模型文件本质上都是同一个问题模型仓库的直连下载被网络策略限制或者磁盘空间不足。我遇到过一次磁盘满了下载进度卡在 90% 一直重试日志里也没有明确提示空间问题后来清理磁盘后直接恢复正常。解决办法是离线导入。在一台网络正常的机器上把模型文件拉下来传到目标机器的~/.openclaw/models/目录然后运行一次模型索引重建让 OpenClaw 扫描到新文件。openclaw models prune openclaw models list注意先备份目录里已有的模型文件prune 会清理掉索引中不存在的残余文件如果没有备份容易误删。我建议导入新模型前总是先看一眼目标目录的磁盘占用量这个习惯能省下很多排查时间。5.3 模型安全别忽视模型投毒与提示注入模型安全是很多人不会主动去想的问题但它真实存在。模型投毒是指从不可信来源下载的模型文件可能包含恶意代码或精心构造的后门数据。一个从不明网盘拉下来的 safetensors 文件加载时可能执行恶意逻辑轻则模型效果极差重则影响宿主机安全。我的建议非常明确只从模型官方仓库或可信镜像下载文件模型文件落地后比对官方发布的哈希值敏感环境不加载来路不明的 adapter 或 LoRA给 OpenClaw 设置沙箱指令使用不可信模型时默认关闭自动工具执行权限所有工具调用必须二次确认。另外提一句提示注入这属于模型输出安全。如果模型来源不可信恶意构造的系统提示可能导致智能体执行非预期操作。配置里把工具调用的自动批准关掉是比较稳健的做法。5.4 常见报错速查表我把最近群里问得最多的问题整理成了一个速查表基本覆盖了模型与提供商系统的大部分坑症状根因解法模型繁忙请稍后再试本地推理服务并发不足或显存不够调大 OLLAMA_NUM_PARALLEL限制 OpenClaw 并发无法安全验证当前环境运行环境缺少 WSL 内核组件在 PowerShell 运行 wsl --status再执行 wsl --update404 错误base_url 带了 /v1 后缀去掉 /v1 后缀模型切换后对话跳闪历史上下文重放与流式增量混叠切换前重置上下文或关闭历史重放自定义模型 c 解析异常模型别名包含冒号等特殊符号别名改用中横线加字母数字模型下载卡住网络策略限制或磁盘空间不足离线导入模型文件或者清理磁盘连接超时本地模型冷启动过慢调大 request_timeout 到 120 秒以上这张表看起来不长但每一条我都反复验证过。如果你在部署中遇到的问题正好在其中按着解法操作基本能解决。如果还没解决建议先跑一遍openclaw providers test把 provider 状态拉出来结合错误报告里的 user-friendly information 再判断不要盲目改配置。5.5 检查模型是否真正注册成功无论配置写得多完整最后都要回到事实层面验证。我在每次改完模型配置之后都会跑一遍这三个命令openclaw models list openclaw providers test ollama_local openclaw models inspect qwen3尤其是第三个命令能查看某个 alias 的具体能力标签和路由优先级便于确认配置解析正确。有一次我改了 priority 后以为生效了结果 inspect 一看还是旧值原来是配置文件里有两个同名的 provider 块后者覆盖了前者。这种隐蔽问题只有检查命令能查出来光看配置文本很容易漏掉。我一直认为模型与提供商系统是整个 OpenClaw 项目里最值得花时间研究的模块。表面上看它只是在做 API 对接实际上它是一个完整的调度层能力标签、优先级、回退策略、冷热分离这些机制叠加在一起才让 OpenClaw 能同时驾驭本地小模型和云端大模型在成本、速度、效果之间动态平衡。我自己的使用习惯是让 qwen2.5-3b 常驻本地做默认路由把更大的模型作为兜底和特殊任务专用。这套配置跑了一段时间后非常稳定唯一要定期检查的就是本地模型文件的磁盘占用和 Ollama 的日志有没有出现频繁的 reload 记录。如果你也想让 OpenClaw 真正变成自己顺手的工具建议从openclaw models inspect开始把你当前所有已注册模型的能力标签和优先级完整捋一遍——这一步做完你对这套系统的掌控感会和之前完全不同。
OpenClaw 这个系列写到第五篇终于要碰整个系统里最能决定用户体验的部分模型与提供商系统。我在好几个群里都看到有人问为什么 OpenClaw 里模型配置不像别的工具那样一行 base_url 就完事还要拆出 providers、models、capabilities 好几层也有人说本地明明装了 Ollama接上去却提示“模型繁忙请稍后再试”完全搞不清是模型没加载还是路由没走对。这些问题归根结底都是因为没把“模型”和“提供商”当成两件事来理解。这篇我打算用实际部署过的配置把模型抽象、提供商适配、路由容错、本地与云端混合调度完整过一遍。无论你是刚把 OpenClaw 跑起来的新手还是已经在上面折腾过几个 skill、想接入 qwen2.5-3b、ollama 或其他本地模型的老手相信都能从中找到可以直接抄的配置和排查思路。我会尽量少讲空泛的架构理论多写配置、命令和那些文档里不会写的运行细节毕竟这个系列走到第五篇该上点硬货了。1. 模型与提供商为什么要拆成两件事1.1 单一模型接入的坑早期 OpenClaw 的模型配置确实简单一个model: gpt-4o-mini加上一个固定地址就完事。但这种写法在个人使用场景下很快就会碰壁你想把默认模型切成 localhost 上的 qwen2.5-3b得改代码你想用兼容 OpenAI 接口的本地推理服务又得改代码更麻烦的是一旦某个模型服务端挂了整个智能体直接瘫痪没有回退方案。这个问题的本质在于模型名承担了太多职责——它既是“能力描述”又是“寻址方式”还是“运行参数”。真正要灵活调度模型这三个职责必须拆开。后来 OpenClaw 把系统重构成了两层模型是抽象层面的描述提供商是实现层面的来源。模型只说我想要什么能力、多大上下文、是否支持工具调用提供商只负责这些能力从哪里来、用什么协议取。1.2 适配层把“请求”和“来源”隔离开理解 OpenClaw 提供商系统可以先看一个所有主流工具都在用的套路。OpenClaw 对每个提供商做了一层适配接口核心是 ChatComplete 和 Embedding 两类方法。OpenClaw 的主进程永远不直接访问某个具体模型服务它面对的是一个标准化的请求结构底层是 Ollama、OpenAI、Anthropic 还是自己写的一个内部推理网关核心层完全不关心。这个设计的好处是新接一个推理后端只需要写一个适配器不需要动上层逻辑。比如我要接一个公司内部的统一推理平台先看它有没有提供 OpenAI 兼容接口如果有直接用 openai_compatible 类型走通基本不用写代码。我在 GPUSstack 上也验证过这一点只要提供商类型选对整个 agent 的调度、技能调用、上下文管理全部复用不用重新适配。1.3 能力标签模型不再只是名字为了让路由系统知道“某个模型到底能干什么”OpenClaw 给每条模型记录挂了 capabilities 标签。一条模型记录可以同时包含 chat、tool_calling、embedding 等能力标识。我自己的配置里qwen2.5-3b 会打上 chat 和 tool_calling一个本地 embedding 模型会打上 embedding 标签longformer 这类长文本模型则会打上长上下文标签。路由的时候候选模型经过能力过滤之后才进入排序阶段。如果当前任务是 agentic 的需要反复调用工具那么即使某个模型名字再好听只要没标 tool_calling就不会被选中。这个机制非常有价值尤其是一个人同时管理多台机器多个模型的时候能力标签直接帮你把模型分成了不同用途的池子而不是靠记忆去区分。2. 本地模型接入的完整实操2.1 先接 Ollama5 分钟跑通 qwen2.5-3bOllama 部署 OpenClaw 是最常见的本地场景。我建议先确认 Ollama 自己工作正常在终端跑一遍ollama list、ollama pull qwen2.5:3b然后 curl 一下它的 API 端点确认可以访问再接入 OpenClaw。curl http://127.0.0.1:11434/v1/models如果这个请求能返回模型列表说明 Ollama 的 OpenAI 兼容端点已经就绪。OpenClaw 里的 provider 配置类似这样providers: - name: ollama_local type: ollama base_url: http://127.0.0.1:11434 prefer: local models: - name: qwen2.5:3b alias: qwen3 capabilities: [chat, tool_calling, context_32k] priority: 10这里有两个小细节。第一地址建议写127.0.0.1而不是localhost。因为 OpenClaw 如果跑在容器或 WSL2 里localhost解析到的是容器或 WSL 自己连不上 Windows 宿主机的 Ollama。我踩过这个坑容器里用 localhost 配了一下午没通改成127.0.0.1后立刻正常。第二alias 是你在 skill 和对话里实际要用的名字它可以和模型名不一样。配置完成后用openclaw models list看模型是否注册成功再用openclaw providers test ollama_local做一次连通性测试。实测下来只要这两步过了后续对话基本不会再碰到模型接入层面的问题。2.2 LM Studio 与 OpenAI 兼容端点LM Studio 在本地模型场景里越来越流行它内置了 OpenAI 兼容服务做法和 Ollama 几乎一样只是默认端口是1234。Claude Code 调用 LM Studio 本地模型的思路完全可以照搬到 OpenClaw 上来。Provider 类型可以直接用 openai_compatiblebase_url 填http://127.0.0.1:1234api_key 随便填一个非空字符串就行因为 LM Studio 本地服务默认不校验 key。LM Studio 和 Ollama 有一个关键区别它更适合同时管理多个大模型并且支持 GPU offload 参数调整。如果机器显存不大在加载 7B 以上模型时建议在 LM Studio 侧限制 GPU offload 层数避免内存溢出导致进程被杀。实测下来LM Studio 在 Windows 上做本地推理的稳定性比早期版本好了很多配合 OpenClaw 的流式输出体验已经很接近云端 API。2.3 GPUSstack 部署模型到 Windows 的注意事项有些人喜欢用 GPU Stack 这类推理平台来管理多模型部署在 Windows 上部署时OpenClaw 侧的配置逻辑也一样选 openai_compatiblebase_url 指向 GPU Stack 暴露的服务地址。需要注意一个路径陷阱base_url 不要带/v1后缀。很多兼容服务的路由规则不一样有些能容忍/v1有些会直接返回 404。我第一次配 GPU Stack 时理所当然加了/v1结果跑了一下午全是 404去掉之后请求就通了。这一点同样适用于 FastChat、vLLM、LocalAI 这些常见推理框架统一建议填根地址。另外如果 GPU Stack 服务部署在另一台机器上OpenClaw 所在机器要确保能通过内部网络访问对应端口。很多 Windows 防火墙会默认拦截跨设备请求排查时先在这台机器上用 curl 请求一下模型地址确认网络层面通没通再去怀疑 OpenClaw 配置。2.4 自定义模型服务地址怎么配“自定义模型服务地址”这个问题在 langflow 里问的人最多OpenClaw 的答案其实是一样的provider 类型选 openai_compatible填 base_url 和 api_key。base_url 是服务根地址api_key 是服务端要求的密钥如果你本地服务不校验随便填个字符串就行。有一点建议给自定义 provider 起名时避免使用冒号和特殊符号尤其是模型别名里不要带冒号否则注册表解析时会出问题。我之前见过一个报错错误报告里的 message 写着“自定义模型 c”其实是因为别名my:cool:model被解析器拆成了三段后面两段被当成未知字段了。命名用中横线加字母数字最稳。2.5 回答那个灵魂问题只能用 API 方式使用算力吗很多人问 OpenClaw 是不是只能通过接入 API 的方式使用算力答案很明确不是。OpenClaw 可以完全本地推理。我自己在只有 CPU 的旧笔记本上也跑通过慢是慢了点但完全能用。OpenClaw 做得好的地方是支持冷热分离——把 embedding 和轻量对话模型放在本机把重活大模型放远程 API形成混合调度。实际配置中我会把本地 Ollama 里的 qwen2.5-3b 当成默认模型负责大部分日常对话和简单工具调用遇到复杂推理任务时通过 skill 里的模型绑定切到云端更大的模型。这样既节省 API 费用又能保证关键任务的效果还不必让 OpenClaw 完全依赖外网服务。3. 云端提供商与路由容错3.1 内置提供商与密钥管理OpenClaw 内置的提供商一般包括 OpenAI、Anthropic、Google 以及 Mistral 这类主流服务。这些 provider 的开启方式基本一致填 api_key然后模型列表里会有一批预设好的模型实例。但我强烈建议不要把 api_key 明文写在配置文件里而是放在环境变量中配置文件里用占位符引用。export OPENCLAW_PROVIDER_OPENAI_KEYsk-xxxx export OPENCLAW_PROVIDER_ANTHROPIC_KEYsk-ant-xxxx这样做的好处有两个。一是避免配置文件不小心提交到 git 仓库导致密钥泄露二是切换不同环境的配置时不用改文件只改环境变量就行。我已经不止一次看到有人把密钥贴进配置文件后发到群里问报错结果整把 key 直接公开实在没必要。如果同一个模型在多个 provider 下都可用路由系统会按 priority 排序数值越小越优先。我会把本地模型的 priority 设成 10云端的同款模型设成 20这样本地可用时优先走本地免费且隐私好本地挂了自动切到云端。3.2 路由优先级与故障回退OpenClaw 的故障回退机制不是无脑重试。我实测下来的行为是连接类错误会直接触发切换比如服务端口不通、TLS 握手失败这些错误重试没有意义立刻转到下一个 priority 的 provider。而超时类错误会先重试一次再切换因为本地模型经常有冷启动问题——模型要读盘加载、分配显存第一次请求可能要等几秒钟这种场景直接切换反而会把一个本来能用的本地源浪费掉。终端出现provider failover: ollama_local - cloud_openai这样的 warning 时不用太紧张这是正常回退。但要留意后续是否频繁出现如果本地 provider 隔几分钟就挂一次多半是显存不足导致服务进程被杀不是 OpenClaw 的问题。routing: retry_on_timeout: true max_retries_per_provider: 1 switch_on_connection_error: true这里我给的建议是 max_retries_per_provider 不要设太高一次足够。因为重试本身也消耗时间尤其是 agent 任务中一次工具调用可能涉及多次模型请求如果每个 provider 都重试三四次整个任务的时间会成倍膨胀。3.3 模型切换后对话跳闪的真相有用户反馈用 cc switch 切换模型后原对话不停跳闪。这个现象我在跑长对话时也遇到过根因不在模型本身而在上下文重放。切换模型时OpenClaw 会把历史消息重新发送给新模型做 prefilling让新模型“接上”之前的语境。如果历史消息很长网络又不够稳定流式输出过程中旧消息重放和新消息增量会混在一起视觉上就像对话在跳闪。解决方法有两个一是在切换模型前主动清空或重置上下文牺牲一点连续性换来稳定性二是在配置里关掉重放让新模型只基于当前这一轮消息继续不回溯历史。如果你是做日常聊天前者体验更好如果是做长文档总结建议选后者避免历史重放造成上下文长度超限。3.4 “模型繁忙”到底是谁的问题提示“模型繁忙请稍后再试”是目前群里问得最多的问题之一。我排查过十几次类似情况结论是绝大多数时候不是 OpenClaw 的问题而是本地推理服务的并发能力不足。Ollama 默认单请求排队如果你同时在 web viewer 里做流式输出又跑了一个 skill 在做并行工具调用显存不够时 Ollama 会直接返回 503。解决方案分两步。第一步给 Ollama 调大并发设置OLLAMA_NUM_PARALLEL2甚至更高第二步在 OpenClaw 侧限制并发请求数避免一次任务里同时发起多个模型调用。# 设置 Ollama 并发 set OLLAMA_NUM_PARALLEL2 ollama serveOpenClaw 侧则把 max_concurrent_requests 调低一般 1-2 就够了。个人智能体场景下真正需要高并发的场景很少限制并发反而能让每个请求更稳定、更快返回。4. 部署环境与配置实战4.1 Windows 上最常见的第一道坎WSL 环境校验Windows 用户部署 OpenClaw 时,如果报错“无法安全验证当前环境”,同时提示在 PowerShell 中运行wsl --status不要慌这不是安全软件拦截而是 OpenClaw 安装脚本在检查 WSL 内核组件是否完整。我遇到这个问题时在 PowerShell 里运行了一次wsl --status发现内核版本信息缺失重新执行wsl --update再跑安装脚本就好了。如果wsl --status显示“没有已安装的分发版”先运行wsl --set-default-version 2指定 WSL 版本再安装一个分发版。另外PowerShell 执行策略也可能导致安装脚本无法启动报错“无法加载脚本”这时运行下面的命令放开当前用户级别的限制Set-ExecutionPolicy -Scope CurrentUser RemoteSigned这个命令只影响当前用户不影响系统级的安全策略。我建议在 Windows 上部署 OpenClaw 时先把这两步走完再去看文档里的其他配置否则后面每一步都可能因为环境问题反复报错而错误信息又不指向真正的根因。4.2 配置文件长什么样一个可工作的 OpenClaw 模型配置通常包含三块providers 定义连接方式models 定义能力标签和别名routing 定义回退和超时策略。下面是我实际在用的一个精简版配置providers: - name: ollama_local type: ollama base_url: http://127.0.0.1:11434 models: - name: qwen2.5:3b alias: qwen3 capabilities: [chat, tool_calling] priority: 10 - name: nomic-embed-text alias: embed_local capabilities: [embedding] priority: 10 - name: cloud_openai type: openai api_key_env: OPENCLAW_PROVIDER_OPENAI_KEY models: - name: gpt-4o-mini alias: gptmini capabilities: [chat, tool_calling] priority: 20 routing: retry_on_timeout: true max_retries_per_provider: 1 switch_on_connection_error: true这里最容易被忽略的是 embedding 模型。很多智能体任务其实不直接依赖大模型而是先做检索再交给大模型总结。如果 embedding 模型没配置好后面接记忆系统和知识库都会出问题。我的习惯是默认把 embedding 模型指向本地因为这类推理比较轻量本地跑完全够用既能加快响应速度也能减少隐私风险。4.3 超时、并发与重试参数对照在调整参数之前先理解每个参数的含义。下面这个表是我根据自己的部署经验整理的常用参数和建议值参数默认值建议值说明request_timeout60s120s本地 7B 模型在 CPU 上生成长回复较慢超时设短了会被误判失败connect_timeout10s15s容器和跨网络部署时TCP 握手可能超过 10 秒max_retries_per_provider01只对超时类错误生效连接错误直接切换max_concurrent_requests41-2本地模型并发请求容易触发 503model_load_retries12冷启动加载模型的场景建议重试一次我刚开始用 OpenClaw 时踩过一个坑默认超时 60 秒本地 qwen2.5-3b 在 CPU 上生成一篇较长回复时直接超时OpenClaw 判定模型失败并切到云端白白浪费了本地算力。后来把 request_timeout 改成 120 秒切换频率明显下降。如果你的机器配置更低甚至可以考虑 180 秒。4.4 手机上的 OpenClawTermux 与 Windows Companion很多人在手机上部署 OpenClaw主要是想把个人智能体随身带。Termux 里安装 OpenClaw 的逻辑和 PC 端类似区别在于手机资源有限不建议本地跑 7B 以上模型。我试过在手机上跑 qwen2.5-3b速度勉强能接受但机身发热明显长时间使用会影响稳定性。更合理的做法是配置里打开远程推理开关让手机端只做客户端模型统一走服务器。Windows Companion 是配合 PC 端使用的辅助组件配置时会要求填入 OpenClaw 的服务地址和令牌。这里有个细节手机和 PC 要在同一个局域网内或者通过内网隧道打通。配置完成后可以在手机浏览器打开 web viewer 做验证如果页面能正常加载并完成对话说明联动已经生效。Companion 的主要作用是作为补充入口我在外网环境基本靠它应急实际主力还是终端或 API 调用。4.5 扩展skill 系统与模型绑定OpenClaw 的技能系统讨论度一直很高很少有人把 skill 和模型系统放在一起看。我个人觉得这俩其实是强相关的。每个 skill 可以绑定自己的模型需求。比如文档总结类的 skill 可以绑定长上下文模型正则提取类的 skill 用速度更快的小模型不需要所有任务都走同一个大模型。我在配置里会给特定 skill 指定模型映射一份类似下面的结构就够用skills: doc_summary: model: longformer max_tokens: 4096 quick_reply: model: qwen3 max_tokens: 256这样做的收益非常明显常用轻量操作响应快重活才有大模型参与整体 API 成本能降不少。如果只把 OpenClaw 当成一个聊天工具来用这个配置确实用不上但只要开始写自己的 skill模型绑定就是绕不开的一环。5. 常见问题与排查速查5.1 错误报告怎么读OpenClaw 出报错时终端会打印一份 error report 结构的报告下面通常分成 user-friendly information 和 technical detail 两块。第一块是给普通用户看的告诉你是模型繁忙、连接超时还是配置缺失第二块才是开发者定位用的堆栈信息。我强烈建议遇到报错先看 user-friendly information 里的 message不要一上来就翻堆栈。很多新手一看到堆栈就慌实际去搜最后几行栈帧浪费大量时间。比如最常见的“模型繁忙请稍后再试”就是 user-friendly 层的提示看到这一句你就应该先去查推理服务的并发和显存而不是盯着 OpenClaw 的调用栈看。5.2 模型下载失败与缺失模型处理模型下载失败是本地模型场景的高频问题。比如用户说自定义模型下载一直失败或者 ComfyUI 那边提示缺失模型文件本质上都是同一个问题模型仓库的直连下载被网络策略限制或者磁盘空间不足。我遇到过一次磁盘满了下载进度卡在 90% 一直重试日志里也没有明确提示空间问题后来清理磁盘后直接恢复正常。解决办法是离线导入。在一台网络正常的机器上把模型文件拉下来传到目标机器的~/.openclaw/models/目录然后运行一次模型索引重建让 OpenClaw 扫描到新文件。openclaw models prune openclaw models list注意先备份目录里已有的模型文件prune 会清理掉索引中不存在的残余文件如果没有备份容易误删。我建议导入新模型前总是先看一眼目标目录的磁盘占用量这个习惯能省下很多排查时间。5.3 模型安全别忽视模型投毒与提示注入模型安全是很多人不会主动去想的问题但它真实存在。模型投毒是指从不可信来源下载的模型文件可能包含恶意代码或精心构造的后门数据。一个从不明网盘拉下来的 safetensors 文件加载时可能执行恶意逻辑轻则模型效果极差重则影响宿主机安全。我的建议非常明确只从模型官方仓库或可信镜像下载文件模型文件落地后比对官方发布的哈希值敏感环境不加载来路不明的 adapter 或 LoRA给 OpenClaw 设置沙箱指令使用不可信模型时默认关闭自动工具执行权限所有工具调用必须二次确认。另外提一句提示注入这属于模型输出安全。如果模型来源不可信恶意构造的系统提示可能导致智能体执行非预期操作。配置里把工具调用的自动批准关掉是比较稳健的做法。5.4 常见报错速查表我把最近群里问得最多的问题整理成了一个速查表基本覆盖了模型与提供商系统的大部分坑症状根因解法模型繁忙请稍后再试本地推理服务并发不足或显存不够调大 OLLAMA_NUM_PARALLEL限制 OpenClaw 并发无法安全验证当前环境运行环境缺少 WSL 内核组件在 PowerShell 运行 wsl --status再执行 wsl --update404 错误base_url 带了 /v1 后缀去掉 /v1 后缀模型切换后对话跳闪历史上下文重放与流式增量混叠切换前重置上下文或关闭历史重放自定义模型 c 解析异常模型别名包含冒号等特殊符号别名改用中横线加字母数字模型下载卡住网络策略限制或磁盘空间不足离线导入模型文件或者清理磁盘连接超时本地模型冷启动过慢调大 request_timeout 到 120 秒以上这张表看起来不长但每一条我都反复验证过。如果你在部署中遇到的问题正好在其中按着解法操作基本能解决。如果还没解决建议先跑一遍openclaw providers test把 provider 状态拉出来结合错误报告里的 user-friendly information 再判断不要盲目改配置。5.5 检查模型是否真正注册成功无论配置写得多完整最后都要回到事实层面验证。我在每次改完模型配置之后都会跑一遍这三个命令openclaw models list openclaw providers test ollama_local openclaw models inspect qwen3尤其是第三个命令能查看某个 alias 的具体能力标签和路由优先级便于确认配置解析正确。有一次我改了 priority 后以为生效了结果 inspect 一看还是旧值原来是配置文件里有两个同名的 provider 块后者覆盖了前者。这种隐蔽问题只有检查命令能查出来光看配置文本很容易漏掉。我一直认为模型与提供商系统是整个 OpenClaw 项目里最值得花时间研究的模块。表面上看它只是在做 API 对接实际上它是一个完整的调度层能力标签、优先级、回退策略、冷热分离这些机制叠加在一起才让 OpenClaw 能同时驾驭本地小模型和云端大模型在成本、速度、效果之间动态平衡。我自己的使用习惯是让 qwen2.5-3b 常驻本地做默认路由把更大的模型作为兜底和特殊任务专用。这套配置跑了一段时间后非常稳定唯一要定期检查的就是本地模型文件的磁盘占用和 Ollama 的日志有没有出现频繁的 reload 记录。如果你也想让 OpenClaw 真正变成自己顺手的工具建议从openclaw models inspect开始把你当前所有已注册模型的能力标签和优先级完整捋一遍——这一步做完你对这套系统的掌控感会和之前完全不同。
