OpenClaw连接本地Ollama模型配置指南

要在OpenClaw中配置运行在本地Docker容器内的Ollama模型，核心在于确保网络互通与正确的API端点配置。以下是根据现有资料整理的详细步骤、配置要点及常见问题解决方案。

寧瀞致逺

1199人浏览 · 2026-03-22 15:43:09

寧瀞致逺 · 2026-03-22 15:43:09 发布

1. 核心配置步骤与流程

整个配置流程可概括为：部署Ollama -> 拉取并运行模型 -> 在OpenClaw中添加Ollama作为模型提供商并配置对应端点。

步骤	关键操作	说明/目标
1. Ollama容器部署	使用Docker启动Ollama服务	确保Ollama API（默认端口11434）在本地可访问。
2. 模型拉取与运行	在Ollama容器内拉取并启动模型	必须保证模型已成功加载并可通过API调用。
3. OpenClaw配置Ollama提供商	在Web UI的“模型提供商”中添加Ollama	将Ollama作为本地模型源接入OpenClaw。
4. 模型端点配置	填写正确的API Base URL和模型名称	确保OpenClaw能正确路由请求到Ollama容器的模型。
5. 上下文长度调优	设置`OLLAMA_NUM_CTX`环境变量	避免因上下文过短导致对话被静默截断。
6. 测试与验证	在OpenClaw中选择配置的模型进行对话	验证整个配置链路是否成功。

2. 详细配置说明与代码示例

2.1 启动Ollama容器并加载模型

首先，确保Docker已安装并运行。使用以下命令启动一个Ollama容器，并暴露其API端口：

# 拉取并运行Ollama官方镜像，将容器内的11434端口映射到主机的11434端口
docker run -d -v ollama_data:/root/.ollama -p 11434:11434 --name ollama ollama/ollama

注意：-v ollama_data:/root/.ollama 参数将模型数据持久化存储，防止容器重启后模型丢失。

容器运行后，进入容器内部拉取并运行一个兼容的模型。OpenClaw要求模型上下文窗口至少为16K tokens，推荐使用如qwen2.5:14b、qwen2.5:32b或qwen3:14b等模型。

# 进入容器内部
docker exec -it ollama bash
# 在容器内拉取并运行模型（例如qwen2.5:14b）
ollama run qwen2.5:14b

你也可以在宿主机直接通过ollama命令操作，前提是宿主机安装了Ollama。通过以下命令验证模型API是否可用：

# 调用Ollama的API，测试模型列表
curl http://localhost:11434/api/tags

成功的响应应包含已加载的模型信息。

2.2 在OpenClaw中配置Ollama提供商

假设你的OpenClaw服务已通过Docker或其它方式部署完成。登录OpenClaw的Web管理界面。

导航到 设置 (Settings) -> 模型提供商 (Model Providers)。
点击 添加提供商 (Add Provider)。
在提供商列表中找到并选择 Ollama。

关键的配置项如下表所示：

配置项	填写值（示例）	重要说明
Provider Name	`Local-Ollama`	自定义名称，用于标识。
API Key	留空或任意填写	Ollama本地API通常无需鉴权，但部分版本或配置可能需要。可尝试留空、填`ollama`或任意字符。若遇到401错误，可在此填入`ollama`作为变通。
API Base URL	`http://host.docker.internal:11434` 或 `http://<宿主机IP>:11434`	这是容器间通信的关键。 • 如果OpenClaw也运行在Docker中，使用`host.docker.internal`指向宿主机网络。 • 如果OpenClaw直接运行在宿主机（非容器），使用`http://localhost:11434`。 • 在Linux Docker环境中，可能需要使用宿主机在Docker网桥上的IP（如`
172.17.0.1`）。
Model Name	`qwen2.5:14b`	必须与Ollama容器内实际运行的模型名称完全一致。

配置完成后，保存设置。通常OpenClaw会自动测试连接或列出可用模型。

2.3 环境变量与高级配置

为了避免上下文截断问题，强烈建议在启动Ollama容器时，通过环境变量扩展其上下文长度。OpenClaw在处理长对话或复杂任务时，需要足够的上下文窗口。

# 在启动容器时设置上下文长度环境变量（例如设为24576）
docker run -d \
  -v ollama_data:/root/.ollama \
  -p 11434:11434 \
  -e OLLAMA_NUM_CTX=24576 \  # 关键环境变量，扩大上下文窗口
  --name ollama \
  ollama/ollama

此配置能有效防止模型在处理长文本时发生“静默截断”。

3. 常见问题与解决方案

在配置过程中，你可能会遇到以下问题，解决方法如下：

问题现象	可能原因	解决方案
OpenClaw无法连接到Ollama，报“Connection Error”或“Network Error”	1. 网络不通。 2. `API Base URL`配置错误。 3. Ollama容器未运行或端口未暴露。	1. 检查Ollama容器状态：`docker ps` 确认容器正在运行。 2. 在容器内测试API：`docker exec ollama curl -s localhost:11434/api/tags`。 3. 验证宿主机API：在宿主机执行 `curl http://localhost:11434/api/tags`。 4. 修正`API Base URL`：根据OpenClaw的运行环境选择正确的地址（见上表）。对于Docker Compose部署，可使用服务名（如`http://ollama:11434`）。
请求模型时返回“401 Unauthorized”错误	Ollama API启用了身份验证，但OpenClaw未提供有效的API Key。	1. 在OpenClaw配置页面的 API Key 字段尝试填入 `ollama`。 2. 或者，检查Ollama是否以需要认证的模式启动，考虑改为无认证模式运行。
对话响应不完整或突然中断，尤其是长文本	模型上下文窗口 (`OLLAMA_NUM_CTX`) 设置过小，导致文本被静默截断。	1. 重新启动Ollama容器并设置更大的`OLLAMA_NUM_CTX`值（如16384、24576或32768）。命令见2.3节。 2. 选择原生支持长上下文的模型，如 `qwen2.5:32b`。
OpenClaw中看不到已配置的Ollama模型	1. 模型名称不匹配。 2. 连接测试失败，提供商未激活。	1. 核对模型名称：在Ollama容器内执行 `ollama list`，确保OpenClaw中填写的`Model Name`与此列表中的名称完全一致（包括冒号和标签）。 2. 检查OpenClaw提供商配置页面，确保连接测试通过，状态为可用。
Ollama容器运行模型时GPU未调用，速度很慢	Docker容器未正确挂载GPU驱动。	1. 确保宿主机已安装NVIDIA驱动和`nvidia-container-toolkit`。 2. 使用 `--gpus all` 参数运行容器： `docker run -d --gpus all -v ollama_data:/root/.ollama -p 11434:11434 --name ollama ollama/ollama`。
配置成功后，OpenClaw调用模型无响应或超时	1. 模型本身响应慢。 2. 资源（CPU/内存/GPU显存）不足。 3. 模型文件损坏。	1. 查看容器日志：`docker logs ollama` 检查Ollama容器的推理日志。 2. 监控资源使用：使用`docker stats ollama`或`nvidia-smi`检查资源瓶颈。 3. 重新拉取模型：在Ollama容器内执行 `ollama rm <model_name>` 然后 `ollama pull <model_name>` 重新下载模型文件。