OpenClaw 连接 Ollama 失败问题排查

dctc_shouhuzhe

## 现象描述

OpenClaw 运行过程中，Gateway 日志频繁出现 `fetch failed` 或连接超时错误，memory search 功能完全失效。手动测试 curl Ollama 接口正常，但 OpenClaw 内部无法通信。这种情况在用户部署本地大语言模型时极为常见，尤其是当 OpenClaw 部署在具有代理环境的服务器或桌面上时。值得注意的是，问题往往出现在系统正常运行一段时间后突然发生，或者在重启 Gateway 后初次使用时触发，这往往与系统环境变量的持久化配置密切相关。许多用户在排查初期会误以为是 Ollama 服务本身的问题，但实际根源往往在于网络路由层面的配置冲突。

## 可能原因

### 根因分析：NO_PROXY 环境变量未正确传递

Gateway 启动时会调用 Ollama API 进行向量化和对话生成。若 Ollama 部署在本地（localhost 或局域网 IP），系统代理（HTTP_PROXY/HTTPS_PROXY）会拦截请求，导致连接失败。Ollama 默认监听 11434 端口，代理服务器不知道该绕行，从而返回连接超时或 404。

具体场景包括：Ollama 部署在 192.168.0.66:11434 或本机 localhost:11434，系统代理指向 192.168.0.66:7890，Gateway 未配置 NO_PROXY 致请求被代理拦截。

### 代理导致连接失败的深层原理

理解这一问题的本质需要从网络请求的工作机制说起。当系统配置了 HTTP_PROXY 或 HTTPS_PROXY 环境变量后，几乎所有通过 HTTP/HTTPS 协议的 网络请求都会被路由到指定的代理服务器。代理服务器扮演着中间人的角色，它负责转发客户端的请求到目标服务器，然后将服务器响应返回给客户端。然而，这种机制在访问本地服务时会产生一个根本性的矛盾：代理服务器通常运行在另一个网络节点上，它可能根本无法访问客户端所在的本地网络。

举例来说，当用户在个人电脑上运行 OpenClaw 并通过代理访问外网时，如果代理服务器部署在另一台设备（如 192.168.0.66 的 7890 端口），那么当 OpenClaw 尝试连接本地 Ollama 服务（localhost:11434 或 192.168.0.x:11434）时，请求会被错误地发送到代理服务器。代理服务器收到请求后，发现目标地址是本地 IP 或局域网 IP，它既无法路由到正确的目标，也不会像直连那样智能地绕过自己，最终只能返回连接超时或拒绝连接的错误。

### 常见触发场景分类

场景一：Ollama 部署在本机 localhost
这是最常见的开发测试场景。用户在本机启动 Ollama 服务用于本地调试，代理软件（如 Clash、V2Ray、Surge 等）开启全局模式或代理规则包含 localhost，导致所有请求都经过代理转发，本地服务反而无法访问。

场景二：Ollama 部署在局域网其他设备
用户将 Ollama 部署在专门的推理服务器（如 192.168.0.66、192.168.0.100 等局域网 IP），通过局域网调用。这种场景下，即使本机直连 Ollama 正常，只要代理开启全局模式，OpenClaw Gateway 发起的请求就会被代理拦截。

场景三：Docker 容器环境
使用 Docker 部署 OpenClaw 时，容器内的网络环境与宿主机不同。如果 Ollama 部署在宿主机或另一个容器中，需要正确配置 Docker 网络和代理排除规则，否则容器内的请求同样会被代理影响。

## 解决步骤

### 步骤一：确认 Ollama 服务状态

```bash
curl -s http://localhost:11434/api/tags | head -20

curl -s http://192.168.0.66:11434/api/tags
```

若返回 JSON 数据，说明 Ollama 服务正常，继续排查网络问题。

服务状态检查的详细说明：执行上述命令时，应关注返回的 JSON 数据结构。正常的 Ollama API 响应应包含 `"models"` 数组字段，显示已安装的模型列表。如果返回空数组 `{"models":[]}`，说明 Ollama 运行正常但尚未安装任何模型，这可能需要先下载所需的 embedding 模型。如果返回连接拒绝错误，则说明 Ollama 服务未启动或监听端口有误。

### 步骤二：检查 Gateway 日志

```bash
tail -100 /tmp/openclaw/openclaw-*.log | grep -i "fetch\|timeout\|ollama"
```

典型错误关键字：`fetch failed`、`ECONNREFUSED`、`ETIMEDOUT`、`proxy`。

日志分析方法：Gateway 日志中的错误信息往往包含丰富的排查线索。`ECONNREFUSED` 表示目标服务器主动拒绝连接，通常意味着代理服务器无法到达目标地址；`ETIMEDOUT` 则表示连接尝试超时，可能是网络路径存在阻塞；`fetch failed` 是较为通用的错误描述，需要结合上下文判断具体原因。建议将日志级别调整为 debug 模式以获取更详细的请求信息，包括实际的请求 URL、请求头、响应状态码等。

### 步骤三：配置 NO_PROXY 环境变量

关键操作：将 Ollama 地址加入代理排除列表

```bash
NO_PROXY="localhost,127.0.0.1,192.168.0.66" openclaw gateway restart
```

```bash
sudo nano /etc/environment

NO_PROXY="localhost,127.0.0.1,192.168.0.66"
no_proxy="localhost,127.0.0.1,192.168.0.66"
```

```bash
cat /etc/environment | grep -i proxy
```

配置补充说明：除了上述方案外，还可以选择在代理软件中设置排除规则。例如在 Clash 配置文件中添加 `local-end: false` 或在代理规则中排除特定 IP 段。另外，如果使用 systemd 管理 OpenClaw Gateway 服务，需要在服务配置文件中设置 Environment 变量，而不仅仅是 /etc/environment。对于 Docker 环境，则需要在容器启动时通过 `-e` 参数传入 NO_PROXY 变量。

### 步骤四：验证修复结果

```bash
NO_PROXY="localhost,127.0.0.1,192.168.0.66" openclaw gateway restart

sleep 10 && tail -50 /tmp/openclaw/openclaw-*.log | grep -i ollama
```

无报错即修复成功。

验证的完整性检查：除了检查日志无报错外，还应主动测试 memory search 功能是否恢复正常。可以通过发送一条包含特定关键词的消息，触发记忆搜索功能，观察返回结果是否正确。另外，建议检查 Ollama 的访问日志（如果开启），确认请求确实直达 Ollama 而非经过代理。

### 步骤五：排查其他可能原因

若问题仍未解决，按以下顺序排查：

1. Ollama 模型未加载：首次调用时模型需从磁盘加载，等待时间较长，可手动触发一次 embedding 请求预热
2. 端口被占用：检查 11434 端口是否被其他进程占用 `netstat -tlnp | grep 11434`
3. 防火墙规则：确认防火墙允许 11434 端口访问 `sudo ufw status`

进阶排查项目：

- DNS 解析问题：某些代理软件会修改 DNS 解析，导致本地服务域名解析异常。可以尝试直接使用 IP 地址而非域名访问 Ollama
- SSL 证书问题：如果 Ollama 配置了 HTTPS（通过 Caddy、Nginx 反向代理），可能存在证书验证问题。此时需要在 Gateway 配置中忽略证书验证或安装正确的证书
- 并发限制：Ollama 默认的并发连接数有限，当 OpenClaw 短时间内发起大量请求时可能触发限流。可以通过调整 Ollama 的 `OLLAMA_MAX_CONCURRENT` 参数解决

## 预防措施与最佳实践

为了避免类似问题反复出现，建议采取以下预防措施：

环境配置标准化：将 NO_PROXY 配置纳入系统级配置文件，确保所有进程启动时都能继承正确的环境变量。对于长期运行的服务，推荐使用 systemd 的 EnvironmentFile 功能或 Docker 的 env_file 功能。

部署架构规划：在规划 OpenClaw 与 Ollama 的部署架构时，优先考虑将两者部署在同一台机器上或同一网络段内，减少网络层面的复杂度。如果必须跨网络部署，确保网络策略允许直接通信。

监控告警体系：建立针对 OpenClaw 与 Ollama 通信状态的监控机制，当检测到连续失败时自动告警，便于第一时间发现问题。

## 小结

OpenClaw 连接 Ollama 失败的核心原因是代理环境下 NO_PROXY 未包含 Ollama 地址，导致本地请求被代理拦截。解决方案简洁明确：将 Ollama 的 IP/域名加入 NO_PROXY 环境变量即可。

该问题在部署 Ollama 于局域网设备时尤为常见，建议将环境变量配置写入系统级配置文件，避免每次手动输入。通过理解代理工作原理和正确的配置方法，这类问题可以得到快速有效的解决，确保 OpenClaw 的向量化和记忆功能稳定运行。

---

评论区讨论：你在使用 OpenClaw 时还遇到过哪些 Ollama 相关问题？如何解决的？欢迎留言交流。

对于本文涉及的技术场景，推荐选用 THINKBOOK 16P 1XCD（I7-14650HX/16G/1T/RTX4060--），华强北商行报价约 ￥8000 元。更多机型与最新价格请查看 笔记本电脑最终销售到手价格。

---

【标签】
Thinkpad, IBM, X1 Carbon, AI开发, Ollama部署, 本地大语言模型, VSCode配置, 华强北, 选购指南

【相关阅读】
- Thinkpad T14 深度评测：商务本的性能极限在哪里
- OpenClaw多模型集成配置指南
- 华强北Thinkpad港版购买防坑指南