OpenClaw Ollama 接入教程，本地模型安装配置和排查指南

Ollama 是 OpenClaw 官方重点支持的本地模型运行时之一。它最吸引人的地方，不只是“模型在本机”，而是 OpenClaw 对它做了比较完整的原生集成：支持流式传输、支持工具调用、能自动发现本地模型，还能把本地与云端模型一起接进来。

如果你想把 OpenClaw 接到自己的模型环境里，或者想把部分工作负载放在本地，Ollama 基本就是第一优先级。

先理解 OpenClaw 是怎么接 Ollama 的#

官方文档里有两个非常关键的点：

• OpenClaw 使用的是 Ollama 原生 API，也就是 /api/chat
• 在未定义显式 models.providers.ollama 时，OpenClaw 可以自动发现本地 Ollama 模型

这意味着，对绝大多数用户来说，最顺的路径不是一开始就手写一大堆模型配置，而是：

1. 先把 Ollama 本身跑起来
2. 让 OpenClaw 通过 onboarding 自动发现模型
3. 再在真正需要时改成显式配置

最重要的一个官方提醒：远程 Ollama 不要写 /v1#

这是 Ollama 接入里最常见、也最致命的坑。

官方文档明确写明：

• 不要把远程 Ollama 地址写成 http://host:11434/v1
• 正确写法是 http://host:11434

因为 /v1 会走 OpenAI 兼容模式，而在这种模式下：

• 工具调用不可靠
• 模型可能把工具 JSON 当成普通文本吐出来

如果你希望 OpenClaw 的工具能力工作正常，优先使用原生 Ollama API。

最推荐的做法：通过 onboarding 配置#

官方把这条路线列为推荐做法：

openclaw onboard

在提供商选择里选 Ollama，向导会帮你做几件事：

1. 询问 Ollama 的 base URL，默认 http://127.0.0.1:11434
2. 让你选择 Local 或 Cloud + Local
3. 如果选了 Cloud + Local 且尚未登录 ollama.com，会触发浏览器登录
4. 自动发现可用模型
5. 如果所选本地模型还没下载，会自动拉取

对于第一次接 Ollama 的用户，这条路线成功率最高。

非交互方式怎么做#

官方也支持非交互：

openclaw onboard --non-interactive \
  --auth-choice ollama \
  --accept-risk

如果你在写部署脚本或自动化流程，这一条会更方便。

手动接入前，先把 Ollama 自己跑通#

在接 OpenClaw 之前，先确认 Ollama 自己没问题。官方建议从这几个命令开始：

ollama serve
curl http://localhost:11434/api/tags
ollama list

这三步分别在验证：

• Ollama 服务进程是否能启动
• 原生 API 是否真的能访问
• 本地是否已经有模型

如果这些命令本身都不正常，OpenClaw 只是“最后一个报错的人”，不是问题根源。

没有模型时该怎么做#

官方文档给了几个示例模型：

ollama pull glm-4.7-flash
ollama pull gpt-oss:20b
ollama pull llama3.3

如果你的 ollama list 还是空的，就先至少拉一个模型，再回到 OpenClaw。

手动配置的最小思路#

如果你只是想用自动发现，最简单的做法是：

• 让本地 Ollama 运行在默认地址
• 不显式定义 models.providers.ollama
• 让 OpenClaw 自动读取本地模型

官方说明，这种情况下 OpenClaw 会从 http://127.0.0.1:11434：

• 调 /api/tags
• 尽量从 /api/show 推断 contextWindow
• 按模型名称做 reasoning 能力启发式判断
• 把成本视为 0

这条路径的最大优点是：你不需要每加一个本地模型，就手改一次配置。

什么时候应该改成显式配置#

官方文档列出了几种适合显式设置的场景：

• Ollama 跑在其他主机或端口
• 你想强制指定上下文窗口
• 你想完全手动维护模型列表

示例配置：

{
  "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
          }
        ]
      }
    }
  }
}

这里的重点不是要你照抄每个字段，而是理解：

• 显式配置意味着你自己接管模型清单
• 同时也意味着自动发现会被关闭

所以只有当你真的需要这份控制权时，才值得这么做。

自定义远程 base URL 的正确写法#

官方示例：

{
  "models": {
    "providers": {
      "ollama": {
        "apiKey": "ollama-local",
        "baseUrl": "http://ollama-host:11434",
        "api": "ollama"
      }
    }
  }
}

请再记一遍这条边界：

• 对：http://ollama-host:11434
• 错：http://ollama-host:11434/v1

如果你真的因为上游代理只支持 OpenAI 格式，才被迫使用 /v1，官方也给了兼容写法，但那是“为了兼容而退一步”，不是正常首选方案。

如何设置默认模型#

官方示例是：

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "ollama/gpt-oss:20b",
        "fallbacks": ["ollama/llama3.3", "ollama/qwen2.5-coder:32b"]
      }
    }
  }
}

注意模型名格式永远是：

ollama/<模型名>

也就是说，本地 Ollama 模型和其他 provider 一样，进入 OpenClaw 以后都会被纳入统一模型命名空间。

Local 和 Cloud + Local 应该怎么选#

只选 Local

适合：

• 你只想用本地模型
• 不打算登录 ollama.com
• 希望链路尽量简单

选 Cloud + Local

适合：

• 你既想用本地模型，也想用 Ollama 云端模型
• 希望把一些轻任务放本地，复杂任务走云端

官方文档提到，云端模型例如：

• kimi-k2.5:cloud
• minimax-m2.5:cloud
• glm-5:cloud

这类模型不需要你本地 ollama pull。

reasoning 模型如何被识别#

官方说明，OpenClaw 会把名称里包含下面关键词的模型视为推理模型：

• deepseek-r1
• reasoning
• think

例如：

ollama pull deepseek-r1:32b

这能帮助 OpenClaw 在没有你手动标注的情况下，更合理地推断模型能力。

本地模型的成本如何处理#

官方文档直接把本地 Ollama 模型成本视为 0。这一点很重要，因为它影响的是模型面板、选择器和某些比较逻辑。

当然，从现实角度看，你依然要付出：

• 机器成本
• 电费
• 显存 / 内存占用

只是对 OpenClaw 的 provider 计价视图来说，它们被当作零成本本地调用。

如果你非要用 OpenAI 兼容模式#

官方文档并不是完全不允许，只是明确说这会降低工具调用可靠性。示例：

{
  "models": {
    "providers": {
      "ollama": {
        "baseUrl": "http://ollama-host:11434/v1",
        "api": "openai-completions",
        "injectNumCtxForOpenAICompat": true,
        "apiKey": "ollama-local",
        "models": []
      }
    }
  }
}

只有在你明确受制于某个只接受 OpenAI 格式的代理时，才应该考虑这条路。

最常见问题怎么排#

1. OpenClaw 没检测到 Ollama

先检查：

ollama serve
curl http://localhost:11434/api/tags

如果连原生 API 都打不通，问题在 Ollama 侧，不在 OpenClaw。

2. 没有可用模型

先看：

ollama list

如果列表为空，先拉模型，再重新让 OpenClaw 发现。

3. 连接被拒绝

先排查：

• Ollama 进程是否正在运行
• 端口是否真的是 11434
• baseUrl 是否写对
• 是否误加了 /v1

很多“模型不回话”的问题，最后都只是 base URL 写错。

推荐的接入顺序#

如果你想一次成功率更高，我建议：

1. 先单独把 Ollama 跑起来
2. 用 curl http://localhost:11434/api/tags 验证
3. ollama pull 一个明确要用的模型
4. 运行 openclaw onboard
5. 先走 Local
6. 确认调用正常后，再决定是否开启 Cloud + Local 或显式配置远程主机

Ollama 在 OpenClaw 里其实已经算很成熟的本地模型接法了。真正最容易把人绊倒的只有两件事：一是 Ollama 自己没启动，二是把远程地址误写成 /v1。只要这两件事避开，大多数接入都会顺很多。