会写这篇 OpenClaw 换模型的配置教程完全是因为我身边太多朋友卡在同一个地方框架能跑起来但默认模型越用越别扭——要么写代码不够聪明要么问复杂问题开始胡诌要么 token 烧得太快。他们第一反应是“这框架是不是不行”其实 OpenClaw 只是一个壳真正干活的脑子是背后接的大模型。换掉它没那么玄乎改一行配置的事。OpenClaw 本身就是个配置驱动的开源智能体运行框架模型层被设计成可插拔的默认让你快速上手但不会替你决定“用哪个模型最好”。这篇文章要解决的就是怎么在不动一行代码的前提下把 OpenClaw 底层的模型切换成你想要的任何一种——包括不想花钱时接入本地模型或免费额度方案。整个过程我说得很直白三步拿 Key、改配置、重启验证。适合刚把 OpenClaw 跑起来的新手也适合已经用了一段时间、想优化输出质量和成本的老手。1. 为什么要给 OpenClaw 换模型先搞清楚你要什么1.1 默认模型真的够用吗先泼一盆冷水OpenClaw 默认内置的模型配置定位是“开箱即用”不是“最佳表现”。它选型时优先考虑的是速度、稳定性和通用性而不是每一项任务的上限。你拿它回个邮件、整理日程、跑个简单 API 调用完全没问题但一旦涉及多步推理、复杂代码调试、长文内容生成默认模型很快就会露馅——逻辑链条变短上下文一长就开始遗忘前面的指令输出格式也不稳定。这不是 OpenClaw 的锅是模型能力的天花板。框架和模型的关系我习惯这么理解OpenClaw 是操作系统模型是 CPU。你给电脑装的处理器决定它能跑多重的活操作系统只负责调度。默认配置相当于给一台工作站配了个入门级 CPU能开机能办公但你要渲图就得换 CPU。所以换模型的第一个判断标准不是“哪个模型名字好听”而是“我到底要它帮我干哪类活”。把这个想清楚了后面选型不纠结。1.2 三类模型的适用场景对照我接触过的模型服务不管厂商怎么包装实际用起来就三大类。别管它们叫“大模型”或“小模型”分类维度完全按使用场景走模型类型优势短板适合 OpenClaw 的场景通用对话模型响应快、成本低、日常任务稳复杂推理容易绕弯信息查询、指令执行、邮件草稿、日常对话推理强化模型数学/代码/逻辑推理强步骤严谨延迟高、token 消耗大代码生成、Bug 排查、多步任务规划、数据分析轻量本地模型免费、离线、隐私好无外部依赖能力上限明显硬件吃配置内网环境、敏感数据、断网场景、低成本批量任务我见过不少人一上来就把最强推理模型配给 OpenClaw结果每次对话等 20 秒才出结果跑一天下来账单吓人。实际上 OpenClaw 很多场景只需要“听话”不需要“聪明”把强模型用在刀刃上平时用通用模型这才叫合理配置。1.3 换模型前先想清楚这三件事动手改配置之前建议你先花五分钟回答三个问题可以帮你少踩几次坑一是频次。你是每天高频使用还是偶尔跑一下任务高频用推荐便宜模型或本地模型偶尔用可以大胆上强模型反正单次成本可控。二是任务的复杂上限。你丢给 OpenClaw 的任务里最复杂的那种是什么别拿最简单的任务来决定模型也别拿最极端的决定取一个“80% 任务刚好够用”的档位。三是对延迟的容忍度。OpenClaw 调用模型属于同步等待模型响应多快直接决定你等多久。推理模型在复杂问题上慢这是物理规律没有免费的快。这三个问题想清楚再去看各家模型的参数和价格你会发现自己选型不会再纠结了。2. 换模型前的准备工作API 凭证、兼容服务与配置入口2.1 第一步拿到模型服务的 API KeyOpenClaw 本身不生产模型它通过 API 去调用别人家的模型服务。所以换模型之前的硬前提是你得有一个能用的模型服务账号。具体做法不复杂去你选定的模型服务商那里注册账号开通 API 访问权限然后在控制台生成一个 API Key。这个 Key 就是 OpenClaw 访问模型服务的通行证一般长这样sk-xxxxxxxx。生成之后记得马上复制保存很多平台只明文显示一次关掉页面就再也找不回来了。申请 Key 时有三件事特别提醒。第一看清楚这个平台是否支持“标准兼容接口”。目前主流模型服务商基本都支持但总有例外。如果你的服务商只提供某个专用 SDK 而不开放 HTTP 接口OpenClaw 大概率接不上。第二看清免费额度和计费规则。标题里说“免费切换”落到实处通常是两条路一条是选有免费额度的服务商初期几百上千万 token 够你玩很久另一条是用本地开源模型完全免费但你需要有一台配置还行的机器。两条路我都走过大多数人的第一台 OpenClaw 更适合走免费额度路线因为配置最简单。不要为了免费去薅那些来路不明的渠道API Key 是能花钱的安全第一。第三把 API Key 单独存好不要到处乱发。这是个很容易被忽略的细节开源项目里很多人习惯把 Key 写进配置文件再同步到远端仓库结果等于公开自己的账单。2.2 配置文件长什么样OpenClaw 的模型配置结构OpenClaw 的模型配置集中在一个 YAML 文件里通常叫config.yaml放在项目根目录。启动时它读这个文件决定“去哪个服务商、调哪个模型、用什么参数”。这个文件的核心是一个叫model的配置节点。我拆给你看# config.yaml 中的模型配置段 model: provider: example-cloud name: advanced-chat-v3 api_base: https://api.example-dev.com/v1 api_key_env: MODEL_API_KEY temperature: 0.7 max_tokens: 4096 timeout: 60 retries: 3各个字段的作用我后面会逐个讲。这里你先记住一个原则OpenClaw 通过provider判断用哪一套通信协议通过name决定调服务商下面的哪个模型实例通过api_key_env去环境变量里取密钥。这三者配合起来就是一个完整的模型指向。你的 OpenClaw 如果想保留多套模型配置来回切换不要直接覆盖这个文件更好的办法是复制一份config.yaml比如config-default.yaml、config-reasoning.yaml每次切换前改软链接或启动时参数指定。这是我用下来最稳的方式后面章节我会专门讲。2.3 API 服务地址与模型名称的对应关系很多新手改配置不生效问题往往出在两个字段api_base和name。api_base是模型服务的入口地址格式通常是https://域名/v1这种。注意末尾的路径别抄错少了/v1或者多了一个斜杠都会导致请求 404。name是模型在你所选服务商那里的真实名称。这个必须一字不差。我见过最多的错误是把“对外宣传名”当成“API 调用名”比如网页版叫“全能助手”实际上 API 里的名字是super-chat-v2s——名字填错了报错信息还特别隐晦一会儿显示“模型不存在”一会儿显示“认证失败”折腾半天。最可靠的确认方式是去你所用服务的开发者文档里查“模型列表”或“API 参数”那部分复制它给出的精确字符串别手敲。也不要凭记忆填旧版本的模型名模型迭代很快旧名字有时候会静默下线。还有一点API Key 和api_base必须来自同一家服务商。用 A 家的 Key 去调 B 家的地址请求会直接失败这是配置里最常见的低级错误。3. 三步切换大模型完整实操配置演示3.1 第一步写入 API Key 到环境变量拿到 Key 之后不要直接把它写进config.yaml。OpenClaw 推荐的做法是把 Key 放到环境变量文件.env里然后在config.yaml中通过api_key_env字段去引用。这样做有两个直接好处第一配置文件可以放心备份、分享不会泄露密钥第二以后想换 Key只改.env一处不用动整个配置。.env的写法很简单# .env MODEL_API_KEYsk-你的私有密钥保存之后建议你验证一下环境变量是否真的被加载了。在项目目录下执行这条命令openclaw doctor它会检查配置完整性其中就包括“环境变量是否存在”这一项。如果输出里MODEL_API_KEY显示为not set大概率是.env文件没放对位置或者在启动 OpenClaw 之前没有先加载它。我遇到过几次这种情况最后发现是.env文件名前面多了一个空格Linux 下文件名是区分大小写和空格的.env和.env完全是两个文件。3.2 第二步修改 config.yaml 中的模型指向现在进入关键环节。用编辑器打开config.yaml找到model节点把参数改成你要换的模型信息。我以“切换成一个通用对话模型”为例完整示例是这样model: provider: example-cloud name: advanced-chat-v3 api_base: https://api.example-dev.com/v1 api_key_env: MODEL_API_KEY temperature: 0.7 max_tokens: 4096 timeout: 60逐个解释一下每个字段的意义这比直接抄配置更重要。provider字段告诉 OpenClaw 用哪一套 API 协议来通信。大多数兼容服务都用同一套标准协议所以填example-cloud这类通用标识即可。如果你接的是本地模型通常填localOpenClaw 会走本地推理进程不走外部 HTTP 请求。name字段是模型名这是整份配置里最不能错的地方。填法和我在 2.3 小节强调的一样去服务商文档里复制精确字符串。比如你用的服务商文档里写的是advanced-chat-v3你就填advanced-chat-v3不要把“v3”写成“V3”大小写不一致也会报“模型不存在”。api_base是 API 入口填服务商提供的地址通常以/v1结尾。如果你不确定可以把该地址在浏览器里打开能看到返回一段 JSON 说明地址有效如果直接 404那就是地址不对。api_key_env填环境变量的名字——注意是名字不是 Key 本身。这里填MODEL_API_KEYOpenClaw 启动时会自动去.env里取对应值。填错这个字段请求会报认证失败而且错误信息很有迷惑性。如果你要切换的是本地开源模型provider改成local同时把name改成你已经下载好的模型名api_base可以删掉或留空OpenClaw 会用本地推理引擎直接加载。改完保存。记住一个原则配置只改一处、只验证一处。不要同时改三个字段又换了 Key出了问题都不知道是哪一步造成的。3.3 第三步重启 OpenClaw 并验证模型生效配置改完必须重启 OpenClaw 才能让新配置生效。重启命令很简单openclaw restart如果你是用进程守护方式跑的重启命令可能不同但思路一样先停掉旧进程再启动新进程。观察启动日志正常情况下你会看到一行类似“model loaded: advanced-chat-v3”的输出这行日志是判断配置是否被正确加载的硬指标。重启之后不要急着跑复杂任务先发一条简单的测试指令我习惯用“回复两个字正常”。这一步是为了验证链路通不通。如果这条消息正常返回说明 API Key、服务地址、模型名全链路畅通如果报错直接跳到第 4 章排查。验证完基础链路再试一条你已经知道标准答案的任务比如“1 加到 100 等于多少”看它输出是否正常。如果逻辑准确、格式稳定说明模型切换成功。如果你的场景是代码生成就随便找一段你以前写过的代码让它重新生成一遍对比输出质量的变化。3.4 参数调优temperature、max_tokens、timeout 怎么填模型切换成功只是第一步想让 OpenClaw 输出稳定、好用还得学会调参数。我挑最影响体验的四个参数讲。temperature控制随机性取值范围通常 0 到 1。数值越小输出越稳定保守默认值0.7算是均衡点。如果 OpenClaw 用来跑自动化任务比如生成 JSON、写 API 调用我建议调到0.2甚至0.1可以让格式更稳定。如果用来写文案、做头脑风暴可以调到0.8以上。但别盲目追求高温度OpenClaw 是做事为主的框架不是聊天玩具我最后都稳定在0.2到0.5之间。max_tokens决定单次回复的输出长度上限不是输入长度。默认4096对大多数任务够用。如果你经常让它生成长文档比如周报、代码文件可以调到8192但要注意输出 token 是会持续计费的调高意味着单次调用成本上升要根据实际需要来。timeout是请求超时时间单位秒。通用模型响应通常几秒到十几秒填60算合理。推理强化模型响应时间可能到两三分钟如果切了这类模型记得把超时时间调到180以上。超时时间太短会频繁报错太长会在模型无响应时干等这个值最值得你按模型类型单独调。retries是请求失败后的重试次数填3是比较稳的默认值。单位时间里请求过多会触发服务商限流重试次数过多反而加剧限流填 2 到 3 就好不需要贪多。这几项参数没有绝对标准答案但有一个好习惯每换一次模型就用一组新参数去测观察输出质量和响应速度再微调。别一套参数走天下不同模型的“脾气”真的不一样。4. 频率最高的问题与排查思路4.1 改了配置却没生效多数是缓存问题这是所有换模型的人第一个会遇到的坑配置改了文件也保存了服务也重启了但跑起来还是旧模型。原因在于 OpenClaw 有配置缓存机制重启命令有时不会自动清除缓存特别是openclaw restart这个命令走的是快速重启路径可能跳过配置重新加载。我之前遇到这种情况折腾半天才发现要执行openclaw clear-cache openclaw start先清缓存再启动配置才会完整重载。如果你用的是软链接方式切换多份配置缓存问题更容易出现因为软链接指向变了但缓存里记录的还是旧路径。另一个可能性是文件名不对。OpenClaw 默认读取的配置文件名可能是config.yaml但你的项目里如果同时存在config.yml和config.yaml启动时会按优先级取其中一个另一个被忽略。你改了被忽略的那个文件自然不生效。解决方法是先确认当前生效的配置文件到底是哪个可以用openclaw config show查看实际加载路径。4.2 请求超时与限流并发和重试策略“请求超时”和“请求被限流”是使用外部模型 API 时最容易遇到的两类问题但原因完全不同。超时大概率是网络路径不通或响应太慢。先把api_base地址单独拿出来测试一下连通性curl -I https://api.example-dev.com/v1如果curl能通OpenClaw 超时一般是模型响应太慢此时把timeout参数调大或者换一个响应更快的模型。如果curl都不通那就是api_base填错了或者服务商接口暂时不可用检查地址拼写。限流则表现为 429 状态码。有些免费额度服务商对并发请求数限制很严OpenClaw 默认的并行任务一多就容易触发限流。排查方法是减少 OpenClaw 的任务并发数同时把retries重试间隔调长一点。这里说句实话免费额度通常够个人使用但如果你把 OpenClaw 跑成 24 小时自动化服务很快会撞限流要么控制任务节奏要么考虑升级到付费档位。4.3 上下文被截断这是最容易被忽略的问题做长任务时你可能会发现OpenClaw 聊到一半突然“失忆”或者输出内容莫名其妙少了后半段。这通常不是配置错误而是上下文窗口超限。模型都有上下文窗口限制比如 8K、32K、128K。当对话历史加上系统提示超过窗口上限有两个后果要么旧消息被裁剪模型忘记前面内容要么新请求直接报错。OpenClaw 对历史消息有自己的裁剪策略裁剪得太狠自然就“失忆”了。解决思路有三个按优先级从低到高排一是换上下文窗口更大的模型这是最省事的二是在 OpenClaw 配置里调小“记忆保留条数”少留历史消息给新内容腾位置三是给复杂的长期任务加摘要机制每过几轮让模型把关键信息压缩成一条摘要代替完整历史。第三条需要你写点配置逻辑但效果最好能显著延长有效工作长度。4.4 常见错误信息速查表最后给一张我整理的速查表几乎覆盖了换模型后 90% 的报错场景。我建议你把它收藏起来遇到问题按图索骥报错特征可能原因解决动作401 / 403API Key 错误、权限不足检查.env中密钥是否复制完整确认服务商后台已开通模型权限404 / Model Not Foundapi_base路径错或name拼错从官方文档复制模型名核对地址结尾/v1429 Too Many Requests触发限流或并发超限降低任务并发调大重试间隔检查免费额度是否耗尽超时 / 连接重置网络不通或模型响应过慢用curl测api_base调大timeout参数上下文超长报错对话历史超过模型窗口换大窗口模型或调小记忆保留条数加载了旧模型配置缓存或文件优先级执行openclaw clear-cache检查是否有多个配置文件这套表看起来简单但每条都是我实际踩过坑之后总结出来的。遇到报错先对照表格别急着改配置参数很多时候问题根本不在参数上。我个人最后再分享一个习惯每次调整模型配置之前我都会把当前config.yaml复制一份重命名成config-backup-20240615.yaml这种带日期的文件。因为模型换完之后有些微妙差异是测不出来的跑几天才觉得不对那时想退回旧配置如果没有备份只能靠记忆重写非常痛苦。有了备份一个复制命令就能完全回到旧状态。还有个小技巧是第一次切到新模型时先让它跑三个不同类型的任务简单查询测连通、结构化任务测格式、复杂推理测能力上限。三关都过了再让它接手你的日常工作。这样能最大程度避免“看着配置成功实际用起来拉胯”的尴尬。OpenClaw 的价值在于把你从重复劳动里解放出来而模型选对、配置调稳是这一切的前提。