如何让 OpenClaw 跑本地模型

很多人提到 OpenClaw 本地模型，第一反应都是：装个 Ollama，不就行了。

这话只说对了一半。官方文档里其实给了两个很重要的提醒：

• 最低摩擦的本地方案，确实是 Ollama + openclaw onboard
• 但真正的 Agent 负载，对上下文长度和抗提示词注入能力要求比很多人想象得更高

所以这篇文章会把这两件事一起讲清楚：怎么最快跑起来，以及哪些情况下“能跑”不等于“够用”。

来源：Ollama provider docs

先说最短路径

如果你只想先把 OpenClaw 本地模型跑起来，官方推荐路径其实很简单：

1. 安装 Ollama
2. 运行 openclaw onboard
3. 选择 Ollama
4. 选择 Local only
5. 让 OpenClaw 自动发现或自动拉取模型
6. 把它设成默认模型

对大部分人来说，这就是最应该先走的路径。

本地模型最适合什么

OpenClaw 跑本地模型，最适合以下目标：

• 降低长期模型成本
• 让敏感文本尽量留在本地
• 做离线或半离线实验
• 先把工作流搭起来，再决定要不要接云模型

比较适合本地模型的任务有：

• 文档问答
• 各类摘要
• 低风险自动化
• 开发和测试阶段的工作流验证

但如果你期待“弱机器 + 小模型 = 完整生产级 Agent”，通常会失望。

最重要的限制，不要跳过

OpenClaw 官方 local models 文档写得非常直接：本地部署当然可以，但 Agent 场景往往需要更大的上下文和更强的防注入能力。文档甚至明确提醒，小模型和重度量化模型更容易在安全和上下文上掉链子。

翻译成人话就是：

• 本地小模型做摘要，可能没问题
• 同一个模型去跑高权限 Agent，就未必还靠谱

如果你的 OpenClaw 会碰邮件、浏览器、文件系统或其他敏感工具，那“本地”不自动等于“更安全”。

最快能跑起来的方案：Ollama + Onboarding

OpenClaw 对 Ollama 的集成，走的是 Ollama 原生 API，也就是 /api/chat，不是 OpenAI 兼容的 /v1 路径。

这个细节很重要。官方文档明确警告：如果你把 Ollama 地址写成 http://host:11434/v1，工具调用可能会出问题，模型甚至可能把原始 tool JSON 当普通文本吐出来。

对 OpenClaw 来说，正确写法是：

http://127.0.0.1:11434

第 1 步：安装 Ollama

先从 ollama.com/download 安装 Ollama。

然后检查：

ollama --version

第 2 步：拉一个本地模型

OpenClaw 当前 provider 文档里的示例模型包括：

ollama pull gemma4
# or
ollama pull gpt-oss:20b
# or
ollama pull llama3.3

如果你只是想先把流程跑通，官方当前建议的本地默认模型是 gemma4。

第 3 步：运行 onboarding

openclaw onboard

然后按这个选：

1. 选择 Ollama
2. 使用默认地址 http://127.0.0.1:11434
3. 选择 Local only
4. 让 OpenClaw 自动发现可用模型
5. 如果本地没有，它会自动帮你 pull

第 4 步：确认 OpenClaw 看到了模型

openclaw models list --provider ollama

再把它设成默认模型：

openclaw models set ollama/gemma4

做到这里，本地模型方案就已经真正跑通了。

OpenClaw 支持的 3 种 Ollama 模式

官方文档里，Ollama 不是只有“本地”一种玩法，而是三种模式：

• Local only
• Cloud + Local
• Cloud only

这篇文章主讲 Local only，但你最好理解这三者的区别：

• Local only 隐私最好
• Cloud + Local 对很多真实用户来说更平衡
• Cloud only 不是本地推理，而是 Ollama 托管云模型

如果你希望复杂任务还能有高质量输出，但平时又想尽量本地跑，那么 Cloud + Local 往往比“死磕纯本地”更实际。

自动发现到底怎么工作

OpenClaw 做得比较好的一个点，是很多情况下你不用手写一大坨模型配置。

根据官方 provider 文档，只要你设置了 OLLAMA_API_KEY，并且没有显式定义 models.providers.ollama，OpenClaw 就会自动去 http://127.0.0.1:11434 发现本地模型。

它会做这些事：

• 查 /api/tags
• 尝试调用 /api/show
• 读取上下文窗口信息
• 把 Ollama 模型成本全部标记为 0

最简设置可以直接写：

export OLLAMA_API_KEY="ollama-local"

然后跑：

ollama list
openclaw models list

对于单机本地部署，这是最干净的方案。

什么时候需要显式配置

以下情况才建议你自己写 models.providers.ollama：

• Ollama 不在本机，而在另一台机器
• 你要自定义 base URL
• 你要手工定义模型列表
• 你要精细控制 context window 或 alias

例如：

{
  "models": {
    "providers": {
      "ollama": {
        "baseUrl": "http://ollama-host:11434",
        "apiKey": "ollama-local",
        "api": "ollama",
        "models": [
          {
            "id": "gpt-oss:20b",
            "name": "GPT-OSS 20B",
            "reasoning": false,
            "input": ["text"],
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
            "contextWindow": 8192,
            "maxTokens": 81920
          }
        ]
      }
    }
  }
}

这里有两个关键点：

• api 保持为 "ollama"
• baseUrl 不要带 /v1

硬件现实，别自我欺骗

如果你只看 Ollama provider 文档，会觉得很容易；如果你再看 OpenClaw 的 local models 指南，语气就会严厉很多。

官方在那页里明确说了：严肃的本地 Agent 负载，需要更大的上下文和更强的安全边界，小显存卡和激进量化模型都可能带来更高的提示词注入风险。

所以更实际的理解是：

• 本地非常适合低风险任务
• 本地不等于自动适合所有 Agent 工作负载
• 如果模型太弱，就别拿它硬扛高权限场景

更现实的生产方案：本地优先，云端兜底

OpenClaw 的 local models 文档其实给了一个更成熟的思路：本地和云模型一起保留。

也就是：

• 本地模型做便宜、隐私敏感、低风险的任务
• 遇到更复杂的场景时，回退到更强的托管模型

这通常比“强行纯本地”更接近真实可用。

说得再直白一点：

• 摘要、初稿、结构化提取：本地经常够用
• 长上下文、高权限工具调用、复杂推理：最好保留云端 fallback

最常见的 5 个错误

1. 把 Ollama 地址写成 /v1

这是最常见、也最不该犯的错误。官方已经明确写了不要这么做。

错的写法：

http://127.0.0.1:11434/v1

对的写法：

http://127.0.0.1:11434

2. 以为“免费”就等于“够好”

本地成本是零，不代表质量足够支撑你的工作流。

3. 用弱本地模型跑高权限 Agent

如果模型上下文能力和抗注入能力都不够，高权限自动化就更难信任。

4. 一开始就过度配置

单机 Ollama 本地部署，先用 onboarding 和自动发现跑通，再考虑手写配置。

5. 以为纯本地一定是终极方案

对很多真实用户来说，最好的生产组合不是纯本地，而是本地优先 + 云端兜底。

快速检查清单

• 装好 Ollama
• pull 至少一个本地模型
• 运行 openclaw onboard
• 选择 Ollama 和 Local only
• 使用原生 Ollama base URL，不要带 /v1
• 用 openclaw models list --provider ollama 验证
• 设好默认模型
• 如果机器不强，保留云端 fallback

官方参考

• Ollama provider docs
• Local models guide