你可能已经把 Ollama 在本机跑起来了，命令行里也能对话，但一接到 OpenClaw 这类 Agent 框架上就出问题：要么连不上地址，要么模型不认工具调用，要么多轮跑几轮就卡死或答非所问。这篇按「先通接口、再验能力、最后调参数」的顺序走一遍，每一步都给出可执行的检查动作，让你能自己定位是哪一层出的问题，而不是反复重装。
你可能已经把 Ollama 在本机跑起来了，命令行里也能对话，但一接到 OpenClaw 这类 Agent 框架上就出问题：要么连不上地址，要么模型不认工具调用，要么多轮跑几轮就卡死或者答非所问。这篇按「先通接口、再验能力、最后调参数」的顺序走一遍，每一步都给可执行的检查动作，让你能自己定位是哪一层出的问题，而不是反复重装。
核心原则只有一条：分层验证。接口层、模型层、Agent 配置层、资源层，任何一层没过，都不要去动后面的参数。大部分「OpenClaw 接 Ollama 失败」的案例，问题都在接口地址或者模型名这类最基础的地方，而不是模型能力不行。
第一步：把 Ollama 的接口暴露对，别让 Agent 找不到门
Ollama 默认只监听本机回环地址，OpenClaw 如果跑在容器、另一台机器或 WSL 里，就会连不上。先确认监听地址与端口是否对调用方可见，这一步没通，后面所有配置都是白费。
- 确认 Ollama 进程监听的是哪个地址：如果 Agent 跑在容器里，回环地址在容器内指向的是容器自身，不是宿主机
- 把 Ollama 的 OpenAI 兼容接口当作对接面，Agent 侧通常按 OpenAI 格式填 base_url，路径后缀和鉴权头要按兼容层的要求写，不要混用原生接口
- 用一条最简单的 curl 先确认「能返回、延迟多少」，再去配 Agent，否则分不清是模型问题还是网络问题
- 如果 OpenClaw 和后端模型必须跨公网访问，先想清楚鉴权和端口暴露，不要直接开无认证端口
curl -s http://127.0.0.1:11434/v1/models | head；如果这个地址在外面不通，就把监听地址改成 0.0.0.0 再试，同时确认防火墙和端口映射第二步：拉对模型，并确认它是「能干活的」那一档
Agent 场景对模型的要求比闲聊高：要能稳定按格式输出、能接受工具描述、能多轮记住上下文。小参数量模型常常在第二步就崩，裸测时看着还行，一进 Agent 就原形毕露。
| 任务类型 | 对模型的要求 | 验证方式 |
|---|---|---|
| 本地知识库问答 | 能读懂长文本、能按格式回答 | 喂一段文档，看它能否只依据文档作答 |
| 需要调用工具 | 能理解工具描述、能输出结构化调用 | 给一个简单工具，看它是真调用还是复述 |
| 多步编排 | 多轮上下文不丢、指令遵循稳定 | 连续追问几轮，看它是否还记得最初的目标 |
| 纯闲聊 | 能连贯对话即可 | 命令行裸测就够，不必强求工具能力 |
拉模型前先明确这个 Agent 要干什么。只是问答检索，还是需要调工具、写文件、跑代码？后者对指令遵循能力要求明显更高。模型拉下来之后先在命令行裸测一遍，看它能否按要求输出结构化内容；连裸测都不稳的，接进 Agent 只会更难排查。
第三步：OpenClaw 侧的配置入口与必填项
这一步是最容易出错的环节，因为配置项多，而且错误信息往往不指向真正的原因。把下面几项对齐，基本能排除大部分「模型不存在」和「连不上」的问题。
- 提供方类型
- 选 OpenAI 兼容，不要选原生 Ollama 协议，除非框架明确支持
- 接口地址
- 填到兼容层的根路径，注意末尾斜杠和版本段，写错会返回 404
- 模型名
- 写 Ollama 里实际存在的那个标签，不是宣传名，写错是最常见的「模型不存在」来源
- 上下文长度
- 不要照抄宣传上限，按本机显存和内存填，填太大跑几轮就慢或失败
- 超时
- 本地推理首字延迟通常比云上高，默认值往往偏短，按实际生成速度留余量
- 确认模型名在命令行列出本地已有模型，把标签原样复制到 Agent 配置里，不要手打
- 设一个保守的上下文先填小一点，跑通了再往上加，避免一上来就因为上下文过大而失败
- 验证工具调用让 Agent 执行一个最简单的动作，比如查当前时间，看它是真的调用了工具，还是把工具说明当成普通文本复述出来
- 留足超时先给一个宽松的值，确认能跑通后再逐步收紧
排查顺序：出问题时按这个次序往下切，别乱改
出问题时最忌讳的是同时改好几个配置。按下面的顺序逐层排查，每层确认通过了再往下走，这样你始终知道问题被缩小到了哪一层。
- 第一层：接口能不能通。用 curl 直接打模型列表，通了再往下
- 第二层：模型能不能裸跑通。命令行直接对话，确认模型本身没问题
- 第三层：Agent 能不能拿到回复。看 Agent 日志里有没有请求体和返回体
- 第四层：回复里工具调用是否正确。是格式不匹配，还是模型根本没理解工具
- 第五层：资源和并发。降上下文或降到单并发，看是否恢复
格式不匹配比能力不足更常见。Agent 侧一般会打出请求体和返回体，比对模型实际返回的格式与框架期望的格式是否一致，很多时候改一个字段就通了。最后才考虑换模型：前面的都排完了还不行，再按站内模型库换一个更擅长指令遵循的。
什么情况下这条路不适合你
本地部署有它的适用边界，硬上只会浪费时间。下面几种情况，建议先想清楚再决定要不要走这条路。
| 场景 | 为什么不适合 | 替代方向 |
|---|---|---|
| 需要高并发或多人同时用 | 本地单机推理的吞吐撑不住 | 按站内部署测算先算一遍再决定 |
| 需要强长文档理解和复杂工具编排 | 本地能跑的模型规模有限，多步任务成功率差距明显 | 用云端接口，或把重活拆给云上 |
| 数据不敏感、预算有限 | 自建的机器和电费也是成本 | 走云端接口未必更贵 |
| 只是偶尔用一下 | 维护本地服务的时间成本更高 | 直接用现成接口 |
判断标准很简单：如果这个 Agent 是给你一个人偶尔用，本地部署很舒服；如果是要给团队用、要稳定跑多步任务、还要处理长文档，先用小规模验证效果差距，再决定要不要继续投入。
下一步想核对本地部署的吞吐预期、模型选型和成本对比，去站内相关页面看当时的数字，比拍脑袋估算靠谱。→常见问题
Ollama 已经在命令行能对话了，为什么 OpenClaw 里还是连不上？
多半是监听地址或路径写法的问题。Ollama 默认只对本机回环地址开放，Agent 跑在容器、WSL 或另一台机器上就连不到；另外 Agent 侧一般走 OpenAI 兼容路径，后缀和鉴权头的写法跟原生接口不一样，两处都要对一遍。先用一条最简单的请求确认能拿到返回，再去配 Agent。
本地模型接进 Agent 后，工具调用总是失败是什么原因？
常见两种情况：一是模型本身的指令遵循能力不够，把工具说明当普通文本复述而不是真的发起调用；二是 Agent 期望的返回格式和模型实际输出的格式对不上。先在命令行裸测这个模型能不能按要求输出结构化内容，能的话再去比对请求体和返回体的格式差异，不要一上来就换模型。
接进去之后越跑越慢，甚至中途失败怎么办？
先看上下文和并发。本地推理吃显存，对话轮数一多、上下文填得太大，或者同时跑多个请求，都会把速度拖下来甚至失败。把上下文长度调到实际需要的大小，先降到单并发试一次，恢复了再往上加。如果单并发也慢，那就是模型规模超出这台机器的实际能力，该换小的或者换硬件。
