最近在折腾OpenClaw本地部署的朋友应该都有同感装好框架、跑通离线整合包只是第一步真正让这个AI助手“有脑子”的关键还是得把在线模型接进来。我本地部署OpenClaw大概三周踩了不少坑也把配置在线模型的完整路径摸清楚了。这篇文章就把我实际操作的配置方法、参数解析和排错经验一次讲透不管是刚拿到龙虾包的新手还是准备从本地小模型切到云端大模型的老手都能直接用上。先说清楚OpenClaw这套东西的逻辑它本身是个Agent调度框架负责管理记忆、工具调用、多技能协作但真正做语义理解、生成回复的是背后的大语言模型。本地部署只是让OpenClaw的壳跑在你自己的机器上而模型本身可以走在线API。所以配置在线模型本质上就是做两件事告诉OpenClaw“该去连哪个模型服务商的哪个接口”以及把手上的密钥、模型名、参数这些信息填对。1. 为什么本地部署OpenClaw还要接在线模型1.1 OpenClaw这类AI Agent框架的运作逻辑OpenClaw本质上是一个人机交互的Agent框架它负责把用户指令拆解成任务、调用工具、管理上下文记忆再协调一个或多个大模型来实际完成生成。你可以把它理解成一个“调度中心”OpenClaw自己不做复杂推理它像项目经理一样把活儿分配给手下的模型员工。本地部署OpenClaw指的是把框架本身安装在你自己的电脑或服务器上数据、配置、消息记录都保留在本地。但“本地部署”不代表模型也必须跑在本地。实际上绝大多数人部署OpenClaw之后接的都是在线模型API因为这才是性价比最高的组合框架本地跑模型云端跑。1.2 本地模型与在线模型的取舍我一开始也试过用ollama跑本地模型比如qwen2.5 7B、deepseek-r1蒸馏版后来还是切回了在线API。原因很现实本地模型对显存要求太高7B模型量化后也要6-8GB显存跑起来电脑基本干不了别的小参数模型的指令遵循能力参差不齐OpenClaw这种强工具调用的场景模型一旦理解错意图整个链路就断了在线模型像deepseek-chat、minimax、qwen-plus这些上下文窗口更大工具调用能力也经过专门优化配合Agent框架成功率会高很多当然本地模型也有它的价值——断网可用、数据不外传、隐私性好。所以很多人的做法是“在线为主、本地兜底”日常对话和工具调用走在线大模型特殊情况切到本地小模型应急。这篇讲的配置方法两种方式都能覆盖。2. 配置在线模型前的准备工作2.1 确认OpenClaw版本与安装方式不同安装方式配置文件的路径和格式会有一点差异。目前主流的安装方式有三种你属于哪种就按哪种找配置文件安装方式配置文件位置说明官方脚本安装~/.openclaw/config.yaml或$OPENCLAW_HOME/config.yaml最常规的部署方式Windows离线整合包解压目录下的config.yaml或配置文件夹一般整合包都会把配置项放到显眼位置源码部署你所clone仓库根目录下的config.example.yaml复制为config.yaml从GitHub main分支检出源码后自行配置这里有个经验不管哪种方式改配置前先备份原文件。我吃过一次亏改坏了配置文件导致OpenClaw启动失败折腾了半天才发现是YAML缩进问题。2.2 获取模型服务商的API Key配置在线模型必须在模型服务商那边拿到API Key。目前国内用户用得比较多的几家DeepSeek开放平台走OpenAI兼容接口模型名是deepseek-chat和deepseek-reasoner硅基流动SiliconFlow聚合了Qwen、GLM、DeepSeek等多个开源模型的API一个Key用多家模型MiniMax有自己的API体系模型名通常是MiniMax-M1之类的阿里云百炼DashScope提供通义千问系列模型的APIOpenAI官方需要海外支付方式国内访问稳定性也一般但如果你有渠道配置方式一样注册、实名认证、充值——这是所有平台统一的流程。充值金额不用太多个人测试的话充个几十块能用很久。API Key通常在平台的“API密钥”或“令牌管理”页面生成生成后一定要立刻复制保存很多平台只在创建时完整显示一次。2.3 准备一个可用的模型名清单配置之前先确认你要用的模型ID。这个很容易搞错——你在平台网页聊天框里看到的名字和API调用时用的model参数值往往不是同一个。以DeepSeek为例网页版显示“DeepSeek Chat”但API的model参数是deepseek-chat。硅基流动这边你创建的是“Qwen/Qwen2.5-7B-Instruct”那model参数就得写全这个带斜杠的名字。我建议你登录服务商的API文档页把准备用的模型ID复制下来后续配置时直接粘贴不要手打。另外还要确认两件事一是这个API是否兼容OpenAI格式二是模型是否支持工具调用function calling。OpenClaw这类Agent框架高度依赖工具调用能力如果你配的模型不支持function calling即使能对话也无法完成查天气、发消息、操作浏览器这类复杂任务。3. OpenClaw配置在线模型的完整流程3.1 找到并打开配置文件先找到你的配置文件。以最常见的脚本安装为例在终端里执行# 查看openclaw配置目录 echo $OPENCLAW_HOME # 如果没有输出一般默认在用户目录下 ls ~/.openclaw/Windows整合包用户通常不用这么麻烦直接在安装目录下找config.yaml或者“配置”文件夹里的文件。打开方式用任何文本编辑器都行但强烈建议用VS Code或者Notepad因为它们能高亮YAML语法缩进问题一眼就能看出来。3.2 配置模型提供商参数的两种方式OpenClaw的配置有两种方式全局配置文件和环境变量。我推荐优先用配置文件因为更直观、可追溯。下面分别说。先在配置文件里找到模型相关的段落通常是llm或model开头。把默认配置改成下面这样llm: provider: deepseek model: deepseek-chat api_key: sk-xxxxxxxxxxxxxxxxxxxxxxxx base_url: https://api.deepseek.com/v1 temperature: 0.7 max_tokens: 4096这里的参数含义拆开说provider服务商标识填deepseek、openai、siliconflow等取决于你用的是哪家model实际的模型ID就是前面说的API模型名api_key你从服务商平台复制的那串密钥base_urlAPI接口的根地址。这个参数很容易被忽略但不填对一定连不上。OpenAI官方是https://api.openai.com/v1DeepSeek是https://api.deepseek.com/v1硅基流动是https://api.siliconflow.cn/v1temperature回复的随机性0到1之间任务执行类场景建议设低一点0.3-0.5聊天陪伴类可以设0.7以上max_tokens单次生成的最大token数执行复杂任务时设大一点4096起步比较稳妥如果你用的是环境变量的方式原理一样只是把配置项写到了系统环境变量里。以DeepSeek为例export OPENCLAW_LLM_PROVIDERdeepseek export OPENCLAW_LLM_MODELdeepseek-chat export OPENCLAW_API_KEYsk-xxxxxxxxxxxxxxxxxxxxxxxx export OPENCLAW_BASE_URLhttps://api.deepseek.com/v1两种方式用哪种都行但不要同时用。同时配置的话OpenClaw会以环境变量优先到时候改配置文件半天不生效卡在这种问题上最冤枉。3.3 配置OpenAI兼容接口的通用写法如果你用的是硅基流动、MiniMax这类平台或者想用One API这类中转网关配置方式稍微变一下。很多这类平台都声明“兼容OpenAI接口格式”所以provider一栏可以直接用openai然后通过base_url指向对应的服务地址。以硅基流动为例llm: provider: openai model: Qwen/Qwen2.5-72B-Instruct api_key: sk-xxxxxxxxxxxxxxxxxxxxxxxx base_url: https://api.siliconflow.cn/v1这里的关键点是只要服务商提供的是OpenAI兼容接口provider填openaibase_url填服务商自己的地址就能连上。这个技巧在OpenClaw社区里叫“OpenAI兼容模式”几乎适用于所有主流模型平台。配完之后重启OpenClaw让它重新读取配置。看到日志里出现类似Model loaded: Qwen/Qwen2.5-72B-Instruct via SiliconFlow这样的信息就说明模型已经加载成功了。3.4 用生产级配置模板一键替换上面是最简配置但我实际跑了一段时间后发现生产环境还需要加一些参数来保证稳定性。这是我目前在用的完整配置模板可以直接抄llm: provider: openai model: Qwen/Qwen2.5-72B-Instruct api_key: sk-xxxxxxxxxxxxxxxxxxxxxxxx base_url: https://api.siliconflow.cn/v1 temperature: 0.4 max_tokens: 8192 top_p: 0.8 timeout: 120 max_retries: 3 agent: max_iterations: 10 memory_enabled: true参数说明timeout请求超时时间秒在线模型处理长任务时容易超过默认值设成120秒能显著降低超时率max_retries失败自动重试次数网络波动时很有用top_p核采样参数和temperature一起控制随机性任务型场景一般0.8左右max_iterationsAgent单次任务的最大循环次数。这个值设太小复杂任务做一半就被掐断设太大又可能在死循环里浪费token。实测10次是个不错的平衡点这套配置的好处是容错率高、不容易被打断比较适合长时间挂着跑任务比如微信机器人、定时巡检这类场景。4. 模型切换与多模型协作实战4.1 快速切换主模型ccswitch/模型切换机制OpenClaw社区里热词榜上有个“ccswitch切换模型”很多朋友都在问。这实际上是OpenClaw内置的一个模型切换机制通过命令或配置文件动态切换当前主模型不需要重启服务。我用的方式是配置文件切换以编辑config.yaml的方式为主。具体操作把llm段落下的模型字段改成目标模型保存后执行热加载命令不同版本命令略有差异通常是openclaw reload或openclaw config reload就能无缝切换。如果你希望按时间段自动切换还可以写一个简单脚本。比如白天用DeepSeek执行任务效率高、性价比好晚上用MiniMax-M1聊天体验好、回复更自然。用crontab定时调用openclaw config reload配合不同配置文件实现垂类场景切换这个玩法在社区里很流行。4.2 按技能分配不同模型OpenClaw的Skill机制可以给不同技能绑定不同的模型这个功能很多人没用上。配置方法是在技能配置里增加model字段skills: coding: model: deepseek-reasoner chat: model: MiniMax-M1 image: model: qwen-image-edit这样做的好处很明显写代码的任务用推理强化模型日常聊天用性价比高的模型图像编辑的指令用专门的图像模型——分工明确每个任务都跑在最合适的模型上token消耗也会优化不少。比如我自己的配置是通用对话走deepseek-chat代码分析走deepseek-reasoner浏览器操作走qwen-max整体跑下来稳定性和效果都挺好。4.3 结合本地模型做离线兜底在线模型依赖网络和API服务万一服务商故障或者断网了OpenClaw就只能干瞪眼。所以我推荐做一套“在线为主、本地兜底”的双模型机制在线模型正常时全量功能跑在云端在线模型失败时OpenClaw把请求降级到本地ollama加载的小模型。实现方式是在配置里增加fallback参数llm: provider: openai model: deepseek-chat api_key: sk-xxx base_url: https://api.deepseek.com/v1 fallback: provider: ollama model: qwen2.5:7b base_url: http://localhost:11434/v1这样配置之后一旦在线API调用失败OpenClaw会自动尝试本地模型不会出现整个Agent直接罢工的情况。虽然本地模型的效果差一些但至少能维持基础对话和简单指令查询不至于完全瘫痪。5. 常见问题与排查技巧实录5.1 API连接失败、401鉴权错误这类问题的报错信息一般是401 Unauthorized或AuthenticationError。排查思路从简单到复杂第一步检查API Key是否复制完整。API Key通常以sk-开头一长串字符复制时很容易漏掉末尾几位。我建议把Key放到一个纯文本文件里和配置里的值做一次字符级对比肉眼核对很容易出错用diff命令最稳。第二步确认base_url是否正确。很多人把https://api.deepseek.com这个裸地址填进去了少了/v1后缀就直接报404或者RouteNotFound。记住绝大多数OpenAI兼容接口的完整地址是“根域名/v1”。第三步确认服务商那边账户余额是否充足。很多平台欠费后不会明确提示“余额不足”而是返回一个不痛不痒的鉴权错误。登录平台控制台看一眼余额就能排除这个因素。5.2 配置后不生效、一直走默认模型这种情况通常有四个原因按概率排序配置文件改错了位置。OpenClaw实际读取的配置文件和你想改的文件不是同一个。先用openclaw config path这样的命令查看实际加载路径再去改对应的文件环境变量覆盖了配置文件。前面反复强调过环境变量的优先级高于配置文件。如果你之前设置过OPENCLAW_LLM_MODEL之类的环境变量配置文件的修改会被覆盖YAML格式错误。OpenClaw用的配置文件是YAML格式对缩进极其敏感。llm:和provider:之间必须缩进两个空格且同一层级的字段必须对齐。推荐用VS Code的YAML插件做格式校验或者直接从官方文档复制模板改改了配置忘了重启。配置文件要重启进程才能重新加载热加载命令不一定所有版本都支持5.3 微信等渠道触发服务端风控或会话残留这部分是从OpenClaw微信插件使用中整理的高频问题。在使用微信接入OpenClaw时可能会出现会话残留、消息丢失、被服务端短暂限制等情况。虽然不同接入方式的表现会有差异但这类问题基本都指向同一个根因短时间内请求频率过高或者某个会话上下文异常堆积。我的处理经验是给Agent加一个冷却机制两条消息之间至少间隔1-2秒避免连续刷屏触发对方服务端的频控策略开启会话超时清理比如30分钟内无对话就自动清空上下文防止上下文堆积导致异常定期重启OpenClaw进程长期挂机的进程容易积累异常状态注意如果你接的是第三方即时通讯渠道一定要控制消息频率和长度“高频大包”是触发限制的最常见原因。建议把OpenClaw的单条回复最大长度限制在1000字以内既稳妥又不容易被截断。5.4 模型回复格式异常、工具调用失效如果你发现OpenClaw接了在线模型之后工具调用经常失败比如让它查天气它却一本正经地编了一个天气问题大概率出在模型选型上。OpenClaw这类的Agent框架对模型的指令遵循能力和function calling能力要求非常高。如果你用的是偏对话优化的模型比如某些基础版Chat模型它可能不理解tool_calls这种结构化输出格式导致工具链路断裂。解决办法优先选择服务商明确标注“支持function calling”的模型。DeepSeek的deepseek-chat、MiniMax的MiniMax-M1、通义千问的qwen-plus系列都是经过验证的这些模型对Agent场景做了专门优化。如果你坚持要用某个不支持工具调用的模型那只能把OpenClaw当作纯聊天机器人使用技能类功能基本废掉。5.5 请求超时和限流问题在线API经常会遇到Timeout或者RateLimitError尤其是高峰期。这类问题大多不是配置错误而是服务商的负载策略。我的实操建议配置重试机制max_retries设成3次配合指数退避能扛过大部分瞬时限流降低请求频率在OpenClaw的Agent配置里加请求间隔控制避免短时间密集调用换一个base_url有些服务商提供多个接入点比如国际站和国内站切换接入点有时能绕开高峰期拥堵多Key轮询如果某个模型的调用量特别大可以注册两个账号配置里支持多Key轮询压力分散后明显更稳定5.6 常见故障速查表故障现象可能原因解决动作401 UnauthorizedAPI Key错误、账户欠费重新复制Key检查余额404 RouteNotFoundbase_url缺少/v1后缀在根域名后补上/v1模型加载失败model参数填错从API文档复制标准模型ID配置不生效环境变量覆盖了配置文件检查env工具调用失效模型不支持function calling换支持工具调用的模型请求超时网络波动、服务商限流加大timeout配置重试消息被吞/会话残留频率过高、上下文物堆积加冷却时间开启会话清理6. 配置完成后的验证方法与优化建议6.1 三步验证配置是否生效配置全部填好之后别急着挂到生产环境先用三步验证一下第一步命令行测试。给OpenClaw发一条简单的指令比如“你好帮我确认一下你当前使用的模型名称和提供商”。如果它正确回复并且你看到MODEL已加载的日志说明主链路通了。第二步工具调用测试。发一个需要调用工具的指令比如“帮我查一下北京今天的天气”。如果它去调用了天气API并返回结构化结果说明function calling功能正常。第三步长时间稳定性测试。连续跑一两个小时观察日志里有没有频繁的报错、超时、重试。如果稳定说明配置适合长期挂机如果频繁报错回到上一节的排查表逐项检查。6.2 配置在线模型常见误区归纳最后总结我这三周踩坑下来最有价值的心得不要盲目追求超大模型。在Agent场景里模型的函数调用能力比参数量更重要。一个调用能力强的7B/14B模型在任务完成率上可能比一个调用能力弱的70B模型好得多不要忽略上下文长度。OpenClaw在和模型对话时会携带历史上下文如果模型的最大上下文不够大长对话后就会报错或者丢记忆。建议选至少32K及以上上下文版本的模型不要把所有鸡蛋放在一个篮子里。至少常备两个不同服务商的KeyA家挂了切B家不至于整个Agent瘫痪定期清理日志和会话缓存。长期运行的OpenClaw会累积大量日志和会话文件占用磁盘空间不说还可能导致启动变慢6.3 一份常备的在线模型配置速查服务商base_url模型示例特点DeepSeekhttps://api.deepseek.com/v1deepseek-chat、deepseek-reasoner性价比高Reasoner版推理强硅基流动https://api.siliconflow.cn/v1Qwen/Qwen2.5-72B-Instruct模型全一个Key用多家MiniMaxhttps://api.minimax.chat/v1MiniMax-M1长上下文聊天体验好阿里云百炼https://dashscope.aliyuncs.com/compatible-mode/v1qwen-plus、qwen-max稳定国内访问快这个表格里的信息是我实际验证过的。如果你用的是其他平台原理一模一样——找到它的base_url和model参数填进OpenClaw的llm配置段就能接上。配置在线模型这件事说穿了就是填好“服务商地址、密钥、模型ID”这三个信息。很多人卡住主要卡在base_url少了/v1、model参数填了网页显示名而不是API模型名、或者环境变量和配置冲突这几个点上。按照这篇文章的流程走一遍大多数问题都能在十分钟内解决。我个人在实际操作中的体会是OpenClaw这类框架的配置并不复杂复杂的是要把“不同模型的特性”和“不同任务的诉求”匹配起来。多跑几轮、多看看日志你会慢慢找到最适合自己的那套模型组合。
:下载、安装)
