OpenClaw 接入本地 Ollama

1. 概述

本手册介绍如何在 OpenClaw 中配置本地 Ollama 服务。Ollama 是一个开源的本地大语言模型运行框架，支持在本地机器上运行多种开源模型，如 Llama、DeepSeek、Qwen 等。

适用范围：

• 希望在本地运行 AI 模型的用户
• 需要离线使用 OpenClaw 的用户
• 关注数据隐私的用户
• 想要降低 API 调用成本的用户

Ollama 的优势：

• 本地运行：数据不离开本地机器，保护隐私
• 离线可用：无需网络连接即可使用
• 开源免费：无需支付 API 费用
• 模型丰富：支持多种开源大语言模型

2. 环境准备

2.1 安装 Ollama

macOS

# 使用 Homebrew 安装
$ brew install ollama
# 或使用官方安装脚本
$ curl -fsSL https://ollama.com/install.sh | sh

Linux

$ curl -fsSL https://ollama.com/install.sh | sh

安装完成后，Ollama 服务会自动启动。

验证安装：

$ ollama --version
ollama version 0.19.0

2.2 拉取模型

安装完成后，需要拉取想要使用的模型。根据您的硬件配置选择合适的模型：

提示： 模型大小影响显存/内存占用，请根据机器配置选择：

• 8GB 内存：推荐使用 7B 参数模型
• 16GB 内存：可以使用 13B 参数模型
• 32GB+ 内存：可以使用更大模型或同时运行多个模型

以下是推荐的模型（以 qwen2.5:7b 为例）：

# 通义千问 2.5 - 阿里开源模型，中文优化好
$ ollama pull qwen2.5:7b
# 其他可选模型：
# DeepSeek Coder - 适合编程任务
$ ollama pull deepseek-coder:6.7b
# CodeLlama - Meta 的开源代码模型
$ ollama pull codellama:7b
# Llama 3 - Meta 的通用大模型
$ ollama pull llama3:8b

查看已安装的模型：

$ ollama list
NAME                    ID              SIZE      MODIFIED
qwen2.5:7b              845dbda0ea48    4.7 GB    28 seconds ago

2.3 验证 Ollama 服务

启动 Ollama 服务（macOS/Windows 通常自动启动）：

$ ollama serve

测试 API 是否正常工作：

$ curl http://localhost:11434/api/generate -d '{
  "model": "qwen2.5:7b",
  "prompt": "Hello, how are you?"
}'

如果能正常返回响应，说明 Ollama 服务运行正常。

2.4 安装 OpenClaw

使用 npm 全局安装 OpenClaw：

# 替换国内的npm源
$ npm config set registry https://registry.npmmirror.com/
# 安装 OpenClaw
$ npm install -g openclaw

验证安装：

$ openclaw --version

3. Ollama API 说明

3.1 Ollama 简介

Ollama 是一个本地大语言模型运行框架，特点：

• OpenAI 兼容 API：提供与 OpenAI 兼容的 REST API
• 模型管理：简单的命令行工具管理模型
• 跨平台：支持 macOS、Linux、Windows
• Modelfile：支持自定义模型参数和系统提示词

3.2 API 端点说明

Ollama 默认监听 http://localhost:11434，提供以下 API：

OpenAI 兼容端点：

3.3 支持的模型

以下是 Ollama 支持的部分编程相关模型：

4. 启动服务

4.1 运行 onboard 命令

完成 Ollama 安装和模型拉取后，启动 OpenClaw 服务：

$ openclaw onboard

4.2 向导配置步骤

步骤 1：安全提示和配置确认

• 首先确认 "I understand this is personal-by-default and shared/multi-user use requires lock-down. Continue?" 选择 Yes
• 选择 Setup mode: QuickStart
• 系统会检测现有配置，显示如下信息：

  Existing config detectedworkspace: ~/.openclaw/workspacemodel: ollama/qwen2.5:7bgateway.mode: localgateway.port: 18789gateway.bind: loopback

步骤 2：选择模型提供方，配置 Ollama 连接

在 Model/auth provider 列表中，选择 Ollama。

配置以下选项：

• Model/auth provider: Ollama
• Ollama base URL: http://127.0.0.1:11434（默认本地地址）
• Ollama mode: 选择 Local (Local models only)
• Default model: 选择已下载的模型，如 ollama/qwen2.5:7b (ctx 32k)

步骤 3：配置搜索提供方（可选）

选择搜索提供方，如 DuckDuckGo Search (experimental)（无需 API Key）。

步骤 5：完成配置并重启

配置完成后，选择 Restart 重启服务。

4.3 验证服务启动

服务启动成功后，终端会显示类似以下信息：

OpenClaw Gateway running on http://127.0.0.1:18789WebUI: http://127.0.0.1:18789/?token=YOUR_TOKEN

5. 访问 WebUI

服务启动后，可在浏览器中访问：

http://127.0.0.1:18789/?token=YOUR_TOKEN

或使用 localhost：

http://localhost:18789/?token=YOUR_TOKEN

WebUI 界面会显示当前使用的模型：Default (qwen2.5:7b - ollama)，表示已成功连接到本地 Ollama 服务。

注意： Token 在配置文件的 gateway.auth.token 字段中查看。

6. 常见问题

Q1: Ollama 服务无法启动？

检查端口占用：

$ lsof -i :11434

查看 Ollama 日志：

$ ollama serve 2>&1

检查环境变量：

# 如需修改监听地址
$ export OLLAMA_HOST=0.0.0.0:11434

Q2: 模型下载很慢？

可以配置镜像源加速下载：

# 设置环境变量使用镜像
$ export OLLAMA_MODELS=/path/to/models

或使用代理：

$ export HTTPS_PROXY=http://your-proxy:port
$ ollama pull qwen2.5:7b

Q3: 显存/内存不足？

减小模型大小：

• 使用量化版本（如 :q4_0 后缀）
• 选择更小的模型（如 7B 替代 13B）

配置 Ollama 使用 CPU：

$ export OLLAMA_NO_GPU=1
$ ollama serve

Q4: OpenClaw 无法连接到 Ollama？

检查 Ollama 服务状态：

$ curl http://127.0.0.1:11434/api/tags

检查配置文件中的 baseUrl：

• 确保 baseUrl 正确设置为 http://127.0.0.1:11434/v1
• 如果 Ollama 在远程服务器，使用对应 IP 地址

防火墙问题：

• 确保防火墙允许 11434 端口访问
• 检查 SELinux/AppArmor 设置

Q5: Token 忘记了怎么办？

查看配置文件：

$ cat .openclaw/openclaw.json | grep token

Q6: 如何更新模型？

# 重新拉取最新版本
$ ollama pull qwen2.5:7b

Q7: 如何删除模型？

$ ollama rm qwen2.5:7b