本地部署openclaw+本地大模型

本地模型跑起来了，聊天窗口也能出字，但一把 OpenClaw 指过去就报错、卡住、或者智能体反复空转——这类问题基本都出在「接口这一层没对齐」。这篇按接线顺序走一遍：先确认本地服务暴露出的端点长什么样，再填 OpenClaw 需要的那几项参数，最后给一份从网络、模型名到超时的排查清单，照着逐条对就能定位卡在哪一步。

本地模型能跑起来、聊天窗口里能正常出字，不代表 OpenClaw 接过去就能用。实际卡住的地方绝大多数不在模型权重上，而在接口这一层：端点格式对不对、模型标识写没写对、超时够不够长、上下文够不够塞。这篇按接线顺序走一遍，从确认本地服务露出什么接口，到把配置填对，再到跑不通时的排查顺序，照着一项项对就行。

有个基本判断要先说清楚：如果本地服务本身没开对外的兼容端点，或者 OpenClaw 跑在容器、虚拟机、另一台机器里而服务只监听本机，那后面所有参数怎么调都没用。所以第一步永远是先用命令行把本地服务本身验通，再谈接线。

先确认你的本地模型露出了什么接口

本地推理服务一般有两种暴露方式：只绑在本机回环地址上，只有同机进程能访问；或者监听所有网卡，允许容器、虚拟机、局域网其他机器连过来。OpenClaw 如果不在同一台机器上，第一种默认一定连不上，这不是框架的锅，是你压根没让它看到那个端口。

• 分清监听范围：回环地址只给本机用，监听全部网卡才能被容器或别的机器访问，先确认你要的是哪种。
• 统一成 OpenAI 兼容格式最省事：多数本地推理服务都能开一个 /v1 风格的兼容端点，智能体框架基本按这套发请求，先把兼容层打开。
• 自己动手验一次再上智能体：直接对端点发一条最短对话请求，能拿到回复说明服务没问题，拿不到就别往下折腾参数了。
• 把端口、路径前缀、协议三样都记下来：很多人填了主机和端口却漏了路径前缀，或者把 http 和 https 写反，后面所有报错都从这来。

把 OpenClaw 的模型配置填对

配置项看起来不多，但每一项都有坑。调用地址要带上完整的路径前缀；模型标识要用本地服务自己认的名字，而不是权重文件夹名；鉴权字段按框架文档给的方式留空，本地服务多数不校验密钥，但空着和随便填一个占位串，行为可能不一样。

1. 查服务端认可哪些模型名调用服务端的模型清单接口，把返回的名字原样复制过去，不要凭记忆手打。
2. 填调用地址主机、端口、路径前缀三段都写全，协议别写反，填完先自己在浏览器或命令行访问一下这个地址。
3. 把超时给足本地模型首轮加载权重很慢，智能体一轮任务又会连续发多次请求，默认短超时容易在第一次调用就被掐断，表现成「连不上」而不是「慢」。
4. 按实际能力勾开关本地模型不一定支持函数调用、结构化输出或视觉输入，勾了不支持的能力，前端看着像模型不听话，其实是框架发了它读不懂的请求。

这几项填完，最好先用一个最简的测试任务跑一遍，确认单轮对话能通，再开工具调用和多步循环。一上来就挂一堆工具，出错了你根本分不清是配置问题还是能力问题。

上下文长度与智能体循环的对齐

智能体的上下文消耗比普通聊天大得多：系统提示、所有工具的描述、历史步骤、每一步工具返回的结果，全都要塞进同一段窗口里。本地模型窗口偏小时，最先崩的往往不是回答质量，而是请求直接被服务端拒掉。

• 按任务类型砍内容：只做问答就关掉多余工具，只做单步操作就别挂长链路。
• 工具描述写精简一点：留出来的窗口越多，正文和历史的余地越大。
• 留意并发：智能体可能并行发多条请求，本地服务同时只吃一两个请求时，其余会排队甚至报错，先把并发降下来比换更大模型见效快。
• 什么情况下这招不适用：如果本地服务本身不支持流式返回，而框架又强依赖流式，那得在服务侧开流式或改框架配置，调上下文长度解决不了。

跑不通时的排查顺序

出问题别东一榔头西一棒子。按下面这个顺序走，每一步都能把问题域砍掉一半，比反复改参数快得多。先测连通，再看服务日志，再缩短链路，最后拿一套能通的配置做对照。

1. 测连通从 OpenClaw 所在的运行环境去访问那个地址，不要从你自己的开发机测，两者网络环境可能完全不同。
2. 看服务日志请求到底有没有到达本地模型服务。到了就是参数或格式问题，没到就是网络、端口或地址写错，这一步能把问题域砍一半。
3. 缩短链路把工具调用、多步循环、长系统提示全关掉，只留一轮最简对话。能通就说明是上下文或能力配置的问题，再逐项加回来。
4. 做对照同一套配置换成官方接口或站内列出的中转端点试一次。能通说明是本地侧的事，不能通说明是 OpenClaw 配置本身写错了。