OpenClaw 连接 Ollama 失败问题排查

dctc_shouhuzhe · 发表于 2026-3-18 06:02

本帖最后由 dctc_shouhuzhe 于 2026-8-8 23:32 编辑

最近帮朋友排查一个 OpenClaw 调 Ollama 的问题，发现这类故障在开发者圈子里简直不要太多。说真的，搜索一下 OpenClaw Ollama "fetch failed"，你会发现大家踩过的坑都长得差不多——本地 Ollama 服务明明跑得好好的，curl 一切正常，OpenClaw 内部就是死活连不上。这篇文章就把我自己实测过的完整排查链路整理出来，从根因原理到 Docker 容器场景都覆盖一遍，争取一篇搞定。

先放一张错误速查表，方便快速对号入座：

错误关键字	最可能的原因	推荐跳转章节
`fetch failed`	通用网络错误，多为代理拦截	根因分析
`ECONNREFUSED`	代理无法到达本地 / Ollama 未启动	步骤一 + 步骤三
`ETIMEDOUT`	网络路径阻塞 / DNS 解析异常	步骤三 + 进阶排查
`proxy` / 502 Bad Gateway	代理软件主动拒绝转发	步骤三 + 代理工具配置

一、现象描述

OpenClaw 运行过程中，Gateway 日志频繁出现 fetch failed 或连接超时错误，memory search 功能完全失效。手动测试 curl Ollama 接口正常，但 OpenClaw 内部无法通信。这种情况在用户部署本地大语言模型时极为常见，尤其是当 OpenClaw 部署在具有代理环境的服务器或桌面上时。

值得注意的是，问题往往出现在系统正常运行一段时间后突然发生，或者在重启 Gateway 后初次使用时触发，这往往与系统环境变量的持久化配置密切相关。许多用户在排查初期会误以为是 Ollama 服务本身的问题，但实际根源往往在于网络路由层面的配置冲突。

老实讲，我自己第一次遇到这个问题时，第一反应也是去 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 网络和代理排除规则，否则容器内的请求同样会被代理影响。关于 Docker 场景的完整配置示例，我会在进阶排查章节展开讲。

三、解决步骤

步骤一：确认 Ollama 服务状态

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 服务未启动或监听端口有误。

截至 2026 年 08 月，Ollama 默认端口仍然是 11434，且 OLLAMA_HOST 环境变量用于控制监听地址（默认 127.0.0.1，如果要局域网访问需要设置为 0.0.0.0）。如果要确认服务绑定地址，可以执行：

ss -tlnp | grep 11434
# 或
netstat -tlnp | grep 11434

步骤二：检查 Gateway 日志

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 地址加入代理排除列表

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

写入系统级配置：

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"

验证配置：

cat /etc/environment | grep -i proxy

配置补充说明：除了上述方案外，还可以选择在代理软件中设置排除规则（详见下方代理工具配置片段章节）。如果使用 systemd 管理 OpenClaw Gateway 服务，需要在服务配置文件中设置 Environment 变量，而不仅仅是 /etc/environment。对于 Docker 环境，则需要在容器启动时通过 -e 参数传入 NO_PROXY 变量。

小提示：很多库的内部实现只识别小写的 no_proxy，所以建议两个都写上（大小写一起配），兼容 Node.js / Python / Go 各家运行时。踩过坑的都懂这种小细节有多破防。

代理工具配置片段

不同代理客户端对"不走代理"的语法略有差异，下面是截至 2026 年 08 月依然主流的几款工具配置示例，可以直接复用：

Clash / Clash Verge / mihomo（rules 段）

rules:
  - DOMAIN-SUFFIX,localhost,DIRECT
  - IP-CIDR,127.0.0.1/32,DIRECT,no-resolve
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - MATCH,PROXY

V2Ray / Xray（routing.rules 段）

{
  "type": "field",
  "ip": [
    "127.0.0.1/32",
    "192.168.0.0/16",
    "10.0.0.0/8"
  ],
  "outboundTag": "direct"
}

Surge（Rule 段）

DOMAIN-SUFFIX,localhost,DIRECT
IP-CIDR,127.0.0.1/32,DIRECT
IP-CIDR,192.168.0.0/16,DIRECT
FINAL,PROXY

修改完代理规则后记得重启代理客户端或重新加载配置，让规则立刻生效。

步骤四：验证修复结果

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 而非经过代理。

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

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

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

进阶排查项目

DNS 解析问题：某些代理软件会修改 DNS 解析，导致本地服务域名解析异常。可以尝试直接使用 IP 地址而非域名访问 Ollama
SSL 证书问题：如果 Ollama 配置了 HTTPS（通过 Caddy、Nginx 反向代理），可能存在证书验证问题。此时需要在 Gateway 配置中忽略证书验证或安装正确的证书
并发限制：Ollama 默认的并发连接数有限，当 OpenClaw 短时间内发起大量请求时可能触发限流。早期版本通过 OLLAMA_MAX_CONCURRENT 参数控制，新版本（截至 2026 年 08 月的 0.5.x 系列起）已统一改用 OLLAMA_NUM_PARALLEL，可通过调整该参数解决限流问题，例如 OLLAMA_NUM_PARALLEL=4

Docker 场景完整配置示例

容器里的 OpenClaw 调宿主机的 Ollama，这是问题最集中的场景。核心思路有两个：一是通过环境变量告诉容器内进程不要走代理；二是用 host.docker.internal（Docker Desktop / Linux 较新版支持）或 host-gateway 来定位宿主机。

docker-compose.yml 片段

services:
  openclaw:
    image: openclaw:latest
    restart: unless-stopped
    environment:
      - NO_PROXY=localhost,127.0.0.1,host.docker.internal,192.168.0.66,192.168.1.1
      - no_proxy=localhost,127.0.0.1,host.docker.internal,192.168.0.66,192.168.1.1
      - HTTP_PROXY=http://192.168.0.66:7890
      - HTTPS_PROXY=http://192.168.0.66:7890
    extra_hosts:
      - "host.docker.internal:host-gateway"

关键点说明：

extra_hosts 让容器内可以通过 host.docker.internal 解析到宿主机 gateway IP（Linux Docker 需要这一行）
容器内 Ollama 地址推荐写 http://host.docker.internal:11434，比 localhost 更稳
如果 Ollama 在另一个容器里，建议两个容器加入同一自定义网络（如 app_net），用服务名互相访问

容器内连通性验证命令

# 进入容器
docker exec -it openclaw-container bash

# 在容器内测 Ollama
curl -sv http://host.docker.internal:11434/api/tags
curl -sv http://192.168.0.66:11434/api/tags

如果返回了 JSON，说明网络层通了，剩下的就是 OpenClaw 内部配置的事；如果仍然超时，多半是 NO_PROXY 没配对，回去检查 environment 字段。

四、预防措施与最佳实践

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

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

一个完整的 systemd unit 示例：

[Service]
EnvironmentFile=/etc/openclaw/environment
ExecStart=/usr/local/bin/openclaw gateway start
Restart=always

/etc/openclaw/environment 文件内容：

NO_PROXY=localhost,127.0.0.1,192.168.0.66,host.docker.internal
no_proxy=localhost,127.0.0.1,192.168.0.66,host.docker.internal

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

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

五、常见问题 FAQ

Q1：NO_PROXY 和 no_proxy 有区别吗？

A：大多数 Unix 工具对小写 no_proxy 更敏感，部分 Node.js / Go 库内部只读取小写版本。最稳的做法是两个都写。

Q2：NO_PROXY 都配了，为什么还是连不上？

A：按这个顺序排查：(1) 代理客户端本身的规则是否覆盖了本地地址；(2) OpenClaw 是否真正读取了你配的环境变量（systemctl show openclaw | grep -i proxy）；(3) DNS 解析是否异常；(4) 是否有 systemd / Docker 覆盖了 /etc/environment。

Q3：OLLAMA_MAX_CONCURRENT 在新版本里还有效吗？

A：截至 2026 年 08 月的 Ollama 主线版本中，并发控制已迁移到 OLLAMA_NUM_PARALLEL。如果你用的是较新版本，建议直接用新参数。

Q4：怎么确认 OpenClaw 内部确实绕过了代理？

A：可以在 OpenClaw 的 debug 日志中观察请求 URL 和实际出口 IP；或者在代理客户端（如 Clash）的连接日志里搜索 Ollama 的地址，如果完全没出现，说明已经直连。

Q5：embedding 模型应该选哪个？

A：截至 2026 年 08 月，社区主流仍是 nomic-embed-text（约 137M 参数，768 维向量，体积小、速度快，适合本地部署）、mxbai-embed-large（约 335M，1024 维，效果更好但占用显存更高）、all-minilm（约 33M，384 维，最轻量）。如果显存紧张建议 nomic-embed-text，效果要求高就选 mxbai-embed-large。

六、小结

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

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

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

【标签】
OpenClaw, Ollama, fetch failed 排查, NO_PROXY 配置, 代理冲突解决, Gateway 日志分析, Ollama 11434 端口, OLLAMA_NUM_PARALLEL, Docker 网络配置, systemd EnvironmentFile

【相关阅读】

Ollama 局域网部署与多机推理实战
OpenClaw 多模型集成配置指南（2026 版）
Docker 容器内访问宿主机服务的三种方式

来源华强北商行 · 数码科技资讯

		自动登录	找回密码
密码			立即注册

[求助] OpenClaw 连接 Ollama 失败问题排查