openclaw 调用 ollama 的模型

本地 ollama 已经跑起来了，模型在命令行里聊得挺好，可一放进 openclaw 就报错、卡住、或者根本列不出模型——这是很多人第一次把本地模型接进智能体框架时会遇到的场景。这篇不重复讲要不要本地部署，只讲调用这一层：接口长什么样、配置写在哪、连通性怎么一步步验，以及哪些情况下这套方式并不合适。

本地 ollama 已经跑起来了，命令行里聊得挺好，可一放进 openclaw 就报错、卡住、或者根本列不出模型。这不是模型坏了，而是调用这一层没接通。你平时在终端敲的那套东西，和 openclaw 内部发出去的请求，走的是两个通道。

这篇不重复讲要不要本地部署，只讲调用这层：接口长什么样、配置写在哪、连通性怎么一步步验，以及哪些情况下这套方式并不合适。先把「模型能跑」和「接口能被外部调用」分成两件事看，后面的排查会顺很多。

先搞清 openclaw 到底在调 ollama 的哪个接口

openclaw 不是去读模型文件，而是把 ollama 当成一个本地 HTTP 服务来请求。命令行能聊天，说明服务本事没问题；但服务默认只监听本机回环地址，只有本机进程连得上。openclaw 如果跑在容器、虚拟机或另一台机器上，请求就会卡在门外。

原生接口

ollama 自己那套路径和字段，给自家客户端用的口径

兼容接口

按 OpenAI 风格开放的路径，字段名跟原生不一样，openclaw 这类工具通常优先走它

回环监听

服务只接受本机来源的连接，跨机、跨容器必先改这个绑定地址

模型标识

本地列表里的名字，配置里要逐字符一致，带不带标签差别很大

• 判断顺序：先用命令行把接口单独打通，再让 openclaw 去连，别两边同时改参数
• 写配置前先确认 openclaw 读的是配置文件还是启动参数，字段名是从它自己的文档来的，不是照抄别家的
• 两套接口口径的字段名不通用，填错常见结果不是报错，而是静默失败或返回空
• 模型名建议从本地列表里复制粘贴，不要手打，大小写和分隔符都算数

接入配置的落地步骤：从能连上到能被调用

把接入拆成四步走，每一步都要留下一次独立的验证结果。这样真出错时，你能立刻知道是哪一环断的，而不是对着日志猜。

1. 确认服务在跑且模型在列表里在本机用最基础的请求方式取一次模型列表，拿到返回再往下走。取不到列表，后面的配置全是空谈。
2. 找到 openclaw 的配置入口看它读的是配置文件还是启动参数，把地址、端口、模型名三项按它自己的字段名填对。模型名跟本地列表逐字符一致。
3. 处理网络边界同机直连最省事；跨机或容器场景要放开监听地址，同时用防火墙或访问控制把来源范围收紧，别直接暴露到公网。
4. 做一次最小验证用最短的一句提示词跑通一轮，确认返回内容和模型名对得上，再接入真实任务。跑不通就退回本机请求这一步复验。

调不通时的排查顺序

按「服务在不在 → 端口通不通 → 模型在不在 → 参数对不对 → 超时够不够」这个顺序查，不要跳步。每一步都留一次独立验证的结果，跳步排查最常见的结果是把两个问题混在一起，越查越乱。

• 模型名对不上是最高频的原因，本地列表里带标签的名字和配置里写的别名可能不是同一个字符串
• 超时类报错未必是网络问题，本地模型首次加载要读权重进显存，第一轮响应会明显偏慢，单独放宽首轮超时能解决一大半
• 返回为空或截断，多半是上下文上限或输出长度设置不匹配，两边取较小值即可
• 并发一高就排队，说明单机服务在处理能力上到顶了，这时候再调参数意义不大

至于具体留多少超时、上下文设多大才合适，跟你机器上的显存和内存直接挂钩，这类数字到 /models/deploy 按自己机器算一遍，比照搬别人的配置靠谱。

什么情况下别硬走这条路

本地调用有它的甜区：单人或小团队、低频使用、数据不出内网。但只要场景稍微变一变，硬走这条路就是给自己找麻烦。

还有一种常被忽略的情况：小团队里只有一个人懂这套配置，一旦他不在，服务挂了没人能快速恢复。如果本地模型要进关键流程，至少要留下配置说明和一份排查顺序，别让接入方式只存在某个人的脑子里。