OpenClaw对接本地Ollama模型指南

寧瀞致逺

1083人浏览 · 2026-03-22 15:38:42

寧瀞致逺 · 2026-03-22 15:38:42 发布

将 OpenClaw 配置为使用本地部署的 Ollama 模型，主要涉及 Ollama 服务部署与 OpenClaw 网关配置两大环节。以下是详细步骤及常见问题解决方案。

1. Ollama 本地部署与模型准备

首先，需要在 macOS 上安装并运行 Ollama 服务，这是 OpenClaw 能够调用本地模型的基石。

安装 Ollama
- 访问 Ollama 官网 (https://ollama.com) 下载适用于 macOS 的安装包，或使用 Homebrew 命令行安装。
```
# 使用 Homebrew 安装示例
brew install ollama
```
拉取并运行模型
- 安装完成后，在终端通过 ollama pull 命令下载所需的大模型。推荐使用在中文场景下表现优秀的模型。
```
# 拉取 Qwen2.5 系列模型（例如 7B 或 0.5B 版本）
ollama pull qwen2.5:7b
# 或拉取其他模型，如 Llama 3、DeepSeek-R1 等 
ollama pull llama3.2
```
- 拉取成功后，可以通过 ollama run <model-name> 直接在终端测试模型是否工作正常。
验证 Ollama API
- Ollama 默认在 http://localhost:11434 提供与 OpenAI 兼容的 API 服务。这是 OpenClaw 对接的关键。
- 可以使用 curl 命令进行简单验证，确保服务已就绪。
```
curl http://localhost:11434/api/generate -d '{
  "model": "qwen2.5:7b",
  "prompt": "你好",
  "stream": false
}'
```
- 若能收到包含文本回复的 JSON 响应，则说明 Ollama 服务运行正常，可供外部调用。

2. OpenClaw 配置对接 Ollama

完成 Ollama 基础服务部署后，需要修改 OpenClaw 的配置文件，使其将请求转发至本地 Ollama API。

定位 OpenClaw 配置文件
- 根据安装方式不同，配置文件路径可能有所差异。通常需要找到 openclaw.json（或类似命名的配置文件），该文件可能位于 OpenClaw 的安装目录或用户配置目录下。
- 如果通过 npm 或特定安装脚本部署，可以尝试在项目根目录或 ~/.openclaw/ 下寻找。

修改配置文件

核心是配置 providers（模型供应商）和 models（可用模型列表），将 Ollama 添加为一个自定义供应商。
以下是一个典型的配置示例，展示了如何集成 Ollama 中的 qwen2.5:7b 模型。

{
  "providers": [
    {
      "id": "ollama-custom",
      "name": "Ollama (Local)",
      "type": "openai",
      "apiKey": "ollama", // API密钥并非必需，但作为占位符
      "baseURL": "http://localhost:11434/v1", // 关键：指向Ollama API地址
      "models": ["qwen2.5:7b", "llama3.2"]
    }
    // ... 可以保留或注释掉其他云厂商的provider配置
  ],
  "models": [
    {
      "id": "qwen2.5-7b-local",
      "name": "Qwen2.5-7B (Ollama)",
      "provider": "ollama-custom", // 关联到上述provider的id
      "model": "qwen2.5:7b" // 对应Ollama拉取的实际模型名
    },
    {
      "id": "llama3.2-local",
      "name": "Llama 3.2 (Ollama)",
      "provider": "ollama-custom",
      "model": "llama3.2"
    }
  ]
}

关键点:
- baseURL 必须正确设置为 http://localhost:11434/v1，因为 Ollama 的 OpenAI 兼容端点在此路径下。
- apiKey 字段虽然通常需要，但对于本地无鉴权的 Ollama，可以填写任意非空字符串（如 "ollama"）作为占位符。
- model 字段的值必须与 ollama list 命令列出的模型名称完全一致。

重启 OpenClaw 网关服务
- 修改配置文件后，必须重启 OpenClaw 的网关服务才能使配置生效。
```
# 具体命令取决于你的启动方式，常见的有：
# 如果使用 pm2 管理进程
pm2 restart openclaw
# 或者如果是在项目目录下直接运行
npm run gateway:restart
# 或找到并重启相关的服务进程
```
- 重启后，访问 OpenClaw 的 Web 管理界面（通常为 http://127.0.0.1:18789 ），在模型选择或供应商设置中，应该能看到新添加的 “Ollama (Local)” 选项及对应的本地模型。

3. 配置步骤总结与验证

为了更清晰地展示从环境准备到配置完成的完整流程，其核心步骤可归纳如下表：

阶段	关键步骤	命令/操作示例	目标/验证点
1. 环境准备	安装 Ollama	`brew install ollama` 或下载安装包	终端可执行 `ollama --version`
	拉取模型	`ollama pull qwen2.5:7b`	`ollama list` 显示模型已下载
	启动 Ollama 服务	（通常安装后自动运行）	`curl` 测试 `localhost:11434` API 可通
2. OpenClaw配置	定位配置文件	查找 `openclaw.json`	找到正确的配置文件路径
	编辑 Provider 与 Model	按上述示例修改 JSON 配置	`baseURL` 正确指向 `http://localhost:11434/v1`
	重启网关服务	`pm2 restart openclaw` 或相应命令	服务重启无报错
3. 集成验证	在 OpenClaw 中选择模型	在 Web 界面或 CLI 中选择新增的本地模型	模型列表中出现 “Qwen2.5-7B (Ollama)” 等选项
	发起对话测试	通过飞书机器人或 Web 界面发送消息	能收到来自本地模型的合理回复

4. 常见问题与解决方法

在配置过程中，可能会遇到以下典型问题，其解决方法总结如下：

问题现象	可能原因	解决方案
OpenClaw 无法连接模型，提示 “API Error” 或 “Model not found”。	1. Ollama 服务未运行 2. 配置文件 `baseURL` 错误 3. 模型名称不匹配	1. 终端执行 `ollama serve` 确保服务启动。 2. 检查 `baseURL` 是否为 `http://localhost:11434/v1`。 3. 核对配置中 `model` 字段与 `ollama list` 的输出是否完全一致（包括冒号后的标签）。
运行 `ollama` 相关命令提示 “command not found”。	Ollama 未正确安装或环境变量未配置。	重新安装 Ollama，或检查安装路径是否已加入系统 PATH。对于 Homebrew 安装，可尝试 `brew link ollama` 。
修改配置文件后，OpenClaw 网关启动失败。	JSON 配置文件语法错误。	使用 JSON 在线校验工具检查配置文件，确保括号、引号配对，逗号使用正确。
飞书机器人能收到消息但无回复，或提示超时。	1. 网络权限问题 2. 模型首次响应慢 3. OpenClaw 网关未正确监听	1. 确保防火墙或安全软件未阻止 `localhost:11434` 和 OpenClaw 网关端口（如 `
18789`）的本地通信。<br> 2. 首次加载大模型需要时间，可查看 Ollama 日志确认是否在加载权重。<br> 3. 通过` netstat`或`lsof` 命令检查网关服务是否在预期端口上监听。
希望切换使用不同的本地模型。	需要在配置文件中注册多个模型。	在 `providers` 的 `models` 数组以及顶层的 `models` 数组中，参照格式添加新的模型条目，重启网关后即可在界面切换。