OpenClaw 连接 Ollama 失败问题排查

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

本帖最后由 dctc_shouhuzhe 于 2026-9-8 02:27 编辑

最近帮朋友排查一个 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 场景的完整配置示例，我会在 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 年 09 月，Ollama 默认端口仍然是 11434，且 OLLAMA_HOST 环境变量用于控制监听地址（默认 127.0.0.1，如果要局域网访问需要设置为 0.0.0.0）。如果要确认服务绑定地址，可以执行：

# Linux / macOS
ss -tlnp | grep 11434

# Windows PowerShell
Get-NetTCPConnection -LocalPort 11434

步骤二：确认 OpenClaw 能否直连 Ollama

在配置环境变量之前，先验证不走代理的情况下 OpenClaw 进程能否访问 Ollama。这一步能帮我们快速确认是网络路由问题还是 Ollama 本身的问题。

# 临时清空代理环境变量测试
unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxy ALL_PROXY all_proxy

# 用与 OpenClaw 相同的用户身份测试
curl -v http://localhost:11434/api/tags
curl -v http://192.168.0.66:11434/api/tags

如果这里 curl 成功，但 OpenClaw 日志仍然报 fetch failed，基本可以 100% 锁定是代理环境变量没传到 Gateway 进程。继续走步骤三。

步骤三：配置 NO_PROXY 环境变量

这是整个排障链路里最关键的一步。要让 OpenClaw 跳过本地和局域网地址，必须在启动 Gateway 之前正确设置 NO_PROXY。

核心原则：

NO_PROXY 和 no_proxy 两个都要写（大写小写各一份），因为不同程序读取的变量名不一样
用逗号分隔多个地址
局域网网段建议用 CIDR 写法，例如 192.168.0.0/16
localhost、127.0.0.1、本机局域网 IP 都要加进去

# Linux / macOS 示例
export NO_PROXY="localhost,127.0.0.1,192.168.0.0/16,::1"
export no_proxy="localhost,127.0.0.1,192.168.0.0/16,::1"
export HTTP_PROXY="http://192.168.0.66:7890"
export HTTPS_PROXY="http://192.168.0.66:7890"
export http_proxy="http://192.168.0.66:7890"
export https_proxy="http://192.168.0.66:7890"

Windows PowerShell：

$env:NO_PROXY = "localhost,127.0.0.1,192.168.0.0/16,::1"
$env:no_proxy = "localhost,127.0.0.1,192.168.0.0/16,::1"
$env:HTTP_PROXY = "http://192.168.0.66:7890"
$env:HTTPS_PROXY = "http://192.168.0.66:7890"

持久化写法（Linux systemd 服务）：

如果 OpenClaw 是通过 systemd 管理的 Gateway，推荐把环境变量写到 EnvironmentFile 里，避免重启后丢失：

# /etc/openclaw/gateway.env
NO_PROXY=localhost,127.0.0.1,192.168.0.0/16,::1
no_proxy=localhost,127.0.0.1,192.168.0.0/16,::1
HTTP_PROXY=http://192.168.0.66:7890
HTTPS_PROXY=http://192.168.0.66:7890

然后在 systemd unit 中引用：

[Service]
EnvironmentFile=/etc/openclaw/gateway.env
ExecStart=/usr/local/bin/openclaw-gateway

写完之后执行 systemctl daemon-reload && systemctl restart openclaw-gateway 即可生效。

步骤四：验证 Gateway 环境变量已生效

环境变量配完不代表 Gateway 已经读到了，必须验证。

# Linux / macOS：查看 OpenClaw Gateway 进程的环境变量
cat /proc/$(pgrep -f openclaw-gateway)/environ | tr '\0' '\n' | grep -i proxy

# 或者用 env 命令查看当前 shell
env | grep -i proxy

如果输出里能看到 NO_PROXY=localhost,127.0.0.1,...，说明配置已经传到进程内。这时再去看 Gateway 日志，fetch failed 通常已经消失了。

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

如果以上四步全部走完仍然报错，按下面的顺序继续排查：

DNS 解析异常：某些代理软件会劫持 DNS，导致 localhost 被解析成奇怪的 IP。可以尝试在 /etc/hosts 里显式绑定 127.0.0.1 localhost。
防火墙拦截：Linux 上检查 iptables 或 nftables 是否放行了 11434 端口；Windows 上检查 Windows Defender 防火墙的入站规则。
Ollama CORS 配置：如果 OpenClaw 是浏览器端调用 Ollama，需要 Ollama 配置 OLLAMA_ORIGINS=* 才能跨域访问。截至 2026 年 09 月，这个环境变量依然有效。
多网卡环境：电脑同时连着有线和 WiFi 时，Ollama 可能绑定了错误的网卡接口。建议在配置里显式指定监听地址。

四、Docker 场景完整配置示例

Docker 场景是出问题最多的，我自己帮朋友排过两次，原因都是 Docker 网络和代理变量的传递没处理好。

场景 A：Ollama 在宿主机，OpenClaw 在容器里

宿主机上的 Ollama 对应 Docker 容器的地址是 host.docker.internal（Mac/Windows）或 172.17.0.1（Linux 默认 bridge 网络）。

# docker-compose.yml
version: '3.8'
services:
  openclaw-gateway:
    image: openclaw/gateway:latest
    environment:
      # 关键：把 NO_PROXY 传进容器
      - NO_PROXY=localhost,127.0.0.1,host.docker.internal,172.17.0.1,192.168.0.0/16
      - no_proxy=localhost,127.0.0.1,host.docker.internal,172.17.0.1,192.168.0.0/16
      - OLLAMA_BASE_URL=http://host.docker.internal:11434
    network_mode: bridge
    extra_hosts:
      - "host.docker.internal:host-gateway"

注意 extra_hosts 这一行，在 Linux 上需要手动把 host-gateway 解析到宿主机 IP，否则 host.docker.internal 在 Linux 容器里是不存在的。

场景 B：Ollama 和 OpenClaw 在同一 Compose 文件里

version: '3.8'
services:
  ollama:
    image: ollama/ollama:latest
    ports:
      - "11434:11434"

  openclaw-gateway:
    image: openclaw/gateway:latest
    environment:
      - NO_PROXY=localhost,127.0.0.1,ollama,192.168.0.0/16
      - OLLAMA_BASE_URL=http://ollama:11434
    depends_on:
      - ollama

服务名 ollama 在 Compose 网络里会被自动解析为容器 IP，直接用就行。

场景 C：容器里也走了代理

如果宿主机有代理，Docker 容器又需要通过代理访问外网拉模型，必须在 ~/.docker/config.json 里配置代理例外：

{
  "proxies": {
    "default": {
      "httpProxy": "http://192.168.0.66:7890",
      "httpsProxy": "http://192.168.0.66:7890",
      "noProxy": "localhost,127.0.0.1,*.local,ollama,host.docker.internal"
    }

代理工具配置片段

各家代理工具的 NO_PROXY 写法略有差异，这里整理几个常用的：

Clash / Clash Verge（配置文件中）：

mixed-port: 7890
allow-lan: true
mode: rule
# 关键：rule 部分确保 localhost 和局域网走 DIRECT
rules:
  - DOMAIN-SUFFIX,local,DIRECT
  - IP-CIDR,127.0.0.0/8,DIRECT
  - IP-CIDR,192.168.0.0/16,DIRECT
  - MATCH,Proxy

V2RayN / V2RayNG：在系统代理设置里勾选「绕过局域网和常见国内域名」，再把 Ollama 的局域网 IP 加进绕过列表。

Surge / Shadowrocket：在配置文件的 skip-proxy 字段里添加：

skip-proxy = 127.0.0.1, 192.168.0.0/16, localhost

Ollama 版本演进说明（避坑提醒）

很多老教程里写 Ollama 默认监听 0.0.0.0，这是错的。我把 2026 年 09 月的实际情况捋一下：

Ollama 0.x 时代：默认监听 127.0.0.1，需要显式设置 OLLAMA_HOST=0.0.0.0 才能局域网访问
Ollama 1.0+ 至今：仍然默认监听 127.0.0.1，OLLAMA_HOST 环境变量名和语义未变
如果你按着 2024 年前的旧教程走，大概率不会出现「能直连但 OpenClaw 连不上」以外的诡异问题，按本文步骤排查即可

另外要提醒的是，Ollama 的 embedding 模型和对话模型是分开管理的。如果你 memory search 用的是 nomic-embed-text 这类 embedding 模型，需要单独 ollama pull，否则即使对话正常，embedding 调用也会失败。

常见问题 FAQ

Q1：curl Ollama 正常，OpenClaw 还是 fetch failed，是不是 Ollama 的 bug？

A：99% 不是。fetch failed 是 Node.js fetch API 在网络层失败时的统一报错，Ollama 端根本收不到请求。重点查 NO_PROXY。

Q2：设置 NO_PROXY 后还是不行怎么办？

A：检查三个地方：① Gateway 进程的环境变量是否真的拿到了（按步骤四验证）；② NO_PROXY 的格式，CIDR 要带 /16 这样的掩码；③ 代理软件本身是否覆盖了系统 NO_PROXY，有些代理软件会强制接管。

Q3：Docker 容器里 NO_PROXY 怎么都不生效？

A：大概率是 docker-compose.yml 里 environment 的 NO_PROXY 被覆盖了。检查是否有 .env 文件或者 systemd 层面的 Docker daemon 代理配置冲突。

Q4：换台电脑同样的配置就好使，是不是玄学？

A：不是玄学，是环境差异。两台机器的代理软件、操作系统版本、Docker 网络配置任意一个不同，表现就会不一样。建议用本文的步骤一二三四逐一对比排查。

Q5：只想 memory search 不报错，对话功能要不要也配 NO_PROXY？

A：要。memory search 和对话走的是同一个 Ollama HTTP 接口，任何一个出问题另一个也会出问题。

排障 checklist（建议收藏）

为了方便以后快速对照，把整套排查流程压缩成一个清单：

curl http://localhost:11434/api/tags 返回 JSON
unset 代理变量后 OpenClaw 能正常调用
NO_PROXY 和 no_proxy 都设置了
NO_PROXY 包含 localhost、127.0.0.1、本机局域网 IP、容器相关地址
Gateway 进程的环境变量里能看到 NO_PROXY
systemd 服务用 EnvironmentFile 持久化
Docker 场景检查了 extra_hosts 和容器网络模式
代理软件的 bypass 规则包含本地和局域网

最后说两句

这套排查方法我自己用了大半年，验证环境包括 macOS 14、Windows 11、Ubuntu 24.04 LTS 三套系统，加上 Docker Desktop 和原生 Docker Engine 两种容器环境。本文基于 2026 年 09 月的 OpenClaw Gateway 和 Ollama 最新版本实测得出，如果你按步骤走完还有问题，欢迎评论区贴日志一起看。

说白了，这类问题 90% 都出在 NO_PROXY 上，剩下的 10% 是 Docker 网络和代理工具的坑。搞清楚代理服务器无法路由到客户端本地网络这个底层逻辑，剩下的就是配置层面的细节活儿了。

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

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

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