OpenClaw Web UI 404排查指南：从端口、路径到环境一次理清

最近被问得最多的问题不是 OpenClaw 怎么配模型而是OpenClaw 部署完之后浏览器打开 Web UI 地址屏幕上只有一行 not found。第一次遇到我还以为是用户把路径记错了结果连续聊了几个案例才发现同样是“Web UI 无法访问 not found”背后原因能差出十万八千里有人是 Windows 上一键脚本跑完页面直接打不开有人是 Linux 下二进制正常启动、日志也没报红管理界面却始终 404还有人页面能开但一点功能就报unexpected status 404 not found: the model ... does not exist。这几种看着都是 not found其实没有一个是同一个病因。这篇文章把我排查这类问题的完整思路整理出来包括怎么区分 404 的类型、怎么用命令行确认服务和端口状态、Windows 和 Linux 下各自容易踩的坑以及一套能直接照着操作的排查顺序。内容偏实操适合刚部署完 OpenClaw 但卡在“页面进不去”这一关的朋友参考。1. 先把 not found 分成三类别急着去改配置not found 这个词太容易混淆了。它可能出现在浏览器页面、控制台接口也可能出现在 agent 的日志里而每一处出现的 404含义都不一样。排查第一步不是改配置而是先把看到的报错归类。1.1 页面 404服务在响应但路径下没有东西浏览器里输入http://服务器IP:端口/页面返回一个 404 Not Found通常还有服务器软件的标识或者框架自带的错误页样式。这说明 HTTP 服务本身是通的——请求发出去了程序也回应了只是这个路径下没有对应的资源。也就是说进程是活着的你访问的路径不对或者路径对应的前端文件没放上去。这种 404 的特征是页面有内容、有响应头不是浏览器报“无法连接”。遇到它要怀疑的是路由前缀、静态资源目录、Nginx 反代规则而不是进程有没有起来。1.2 连接被拒绝服务根本没监听另一种情况是浏览器直接提示“无法访问此网站”“ERR_CONNECTION_REFUSED”或者“连接超时”。这跟 404 严格说不是一回事但很多人口语上也会说“not found”“打不开”。它的本质是没有任何进程在监听你访问的地址和端口或者网络路径被防火墙、安全组拦截了。这种情况下改 Web UI 配置是白费的应该先去看进程是否存活、端口是否监听、防火墙是否放行。很多人把这两类混在一起对着配置文件折腾半天结果服务压根没起来。1.3 API 层面的 404服务正常资源或权限不对还有一种 404 出现在页面能打开之后。比如操作 agent 时返回unexpected status 404 not found: the model gpt-6-sol does not exist or you do not have access。这种报错是后端调用外部模型时被模型服务方返回的 404。它意味着 OpenClaw 的 Web UI 本身没问题问题出在模型名写错、API Key 没有对应模型权限或者 provider 路由配置不对。这属于“后端和上游服务之间的交互失败”跟页面打不开是两码事。如果你把它当成 Web UI 故障去重装那就跑偏了。1.4 用一张表把三种症状的病灶分清浏览器/日志表现本质优先排查方向页面返回 404 Not Found样式完整服务已响应资源缺失路由前缀、静态资源目录、反代规则ERR_CONNECTION_REFUSED / 无法访问 / 超时服务未监听或网络不通进程状态、端口监听、防火墙、容器端口映射页面能开操作时报 model 404 / API 404后端与上游资源交互失败模型名、API Key 权限、provider 配置排查的任何阶段都要把完整报错原文截图或者复制下来不要只记得“not found”两个单词。因为 not found 只是结果真正决定病因的是它出现在哪个环节以及响应码是谁返回的。2. 服务活着却 404端口、路径和前端资源三大盲区进程在跑端口也有监听但访问就是 404。这种情况最迷惑人因为从表面看一切正常。实际上问题往往集中在三个地方监听地址、访问路径、静态资源。2.1 监听地址默认绑在 127.0.0.1外部访问当然不通很多框架默认把 HTTP 服务绑定在 127.0.0.1 这个回环地址上OpenClaw 这类本地优先的框架更是常见。好处是本机访问安全坏处是——如果服务部署在服务器上你用局域网 IP 或者公网 IP 去访问连接请求被系统直接丢弃表现就是浏览器拒绝连接或者反代层返回 404。验证方法很简单。Linux 上执行ss -lntp | grep 3000Windows 上执行netstat -ano | findstr :3000。如果监听地址是127.0.0.1:3000说明服务只在本地回环口上待着外部根本进不去。解决办法是在 OpenClaw 的配置里把 host 改成0.0.0.0然后重启进程。WSL2 环境里这个坑尤其明显。WSL2 本身是一个独立的虚拟网络环境Windows 浏览器访问 localhost 不一定能落到 WSL 里的服务上。最省事的方案是让服务监听 0.0.0.0再从 Windows 侧直接用 WSL 的 IP 访问。2.2 Docker 端口映射和容器内监听是两件事如果 OpenClaw 跑在 Docker 容器里那么“能访问”需要同时满足两个条件容器内的进程监听 0.0.0.0以及宿主机做了-p 3000:3000端口映射。漏掉任何一个外面都访问不到。尤其容易忽视的是第一种情况容器里服务默认监听 127.0.0.1即使你写了-p 3000:3000流量进到容器之后也没有进程在容器内的 0.0.0.0:3000 上接收连接表现依旧是拒绝连接。我见过多次docker ps显示容器运行中浏览器却打不开的场景最后都收敛到这两个条件缺一个。2.3 控制台端口和路径不一定是你以为的那个Web UI 的访问地址要以 OpenClaw 启动日志里打印的那行为准而不是凭记忆猜 3000 或 8080。很多框架启动时会输出类似web UI available at http://localhost:3000的提示。如果日志明确写了地址就应该原样打开不要自己组合。另外管理面板的路径未必是根路径。有些版本把面板挂在/admin、/ui这种子路径下直接访问根路径就会得到 404。我排查过一个案例用户始终访问http://IP:3000/得到 404但日志里清清楚楚写着http://IP:3000/ui才是面板地址改一下 URL 立刻正常。2.4 前端静态资源缺失后端进程正常文件目录是空的OpenClaw 的 Web UI 本质上是静态资源HTML/JS/CSS加后端 API。如果部署过程中前端资源没有完整生成或者解压中断、磁盘被写满静态资源目录可能整个是空的。这时候后端 API 进程正常监听端口但访问首页时找不到 index.html自然返回 404。验证方法不复杂找到 UI 静态资源目录看一眼里面有没有 index.html。如果有说明前端文件在如果没有就得重跑安装流程或者重新构建前端。在 Windows 上这种中断概率比 Linux 高不少解压被杀毒软件打断、脚本被系统弹窗卡住都可能留下一个残缺的安装目录。2.5 配置项被改掉或覆盖Web 开关、端口、环境变量还有一类隐蔽情况配置文件中有一个类似web.enabledfalse或serve_ui的开关被某些安装脚本默认关掉了或者 .env 文件里的 PORT 和主配置文件里的端口不一致你按照 .env 的端口去访问但服务实际监听的是另一个端口。排查方式是打开实际运行的配置文件把 host、port、enabled 这三个字段全部核对一遍并且确认没有多个配置文件在互相覆盖。改完配置后必须重启进程这一步很多人会忘改完发现还是不行其实是新配置压根没生效。3. Windows 部署翻车重灾区进程假活、文件锁与缺失的 PythonWindows 上部署 OpenClawWeb UI 打不开的原因和 Linux 有很大不同。最典型的问题有三个全都属于“看起来部署成功实际上服务没进入可用状态”。3.1 一键脚本的“假启动”窗口一闪而过服务其实没起来Windows 上下载 release 包或者使用一键安装脚本双击后黑色命令行窗口一闪而过浏览器里自然是打不开的。这不是 OpenClaw 特有几乎所有命令行服务在 Windows 上都有这个问题。窗口一闪而过意味着程序启动后立刻退出你根本看不到错误信息。常见原因有三个依赖的 Python 不在 PATH端口被别的程序占用后启动失败安全软件拦截了进程的网络监听。我的建议是不要只依赖双击脚本而是打开命令提示符或 PowerShell切到安装目录手动运行启动命令让输出停留在屏幕上。看到完整报错日志再判断缺什么依赖。很多人连错误信息都没看到上来就怀疑 Web UI 路由配置方向完全错了。3.2 session file lockedtimeout 60000ms旧实例没死透Windows 上很容易遇到一个日志agent failed before reply: session file locked (timeout 60000ms)。这个报错的含义是OpenClaw 为会话文件加了锁防止多个进程同时写同一个会话。上一次启动没有正常退出锁没释放新实例启动时拿不到锁等了 60 秒超时agent 直接失败Web UI 所在的进程根本没起来。处理办法分三步打开任务管理器结束所有 openclaw 相关进程进入会话数据目录删除残留的 .lock 文件重新启动。注意不要在有其他实例正在运行的时候去删锁文件否则另一个进程正写到一半删锁会引出更麻烦的数据问题。正确顺序永远是先确认全部进程退出再清理锁。3.3 python was not found 会导致前端构建链断掉Win10/11 上有句经典报错python was not found; run without arguments to install from the Microsoft Store。这是系统里没有 Python或者安装 Python 时没有勾选“Add Python to PATH”。OpenClaw 的安装脚本或者前端构建步骤一旦调用 Python这个报错就会中断整个流程前端资源自然生成不出来。后果就是后端进程可能在跑但静态资源目录是空的访问首页返回 404。解决办法不是从微软商店装一个凑合的版本而是安装官方 Python 安装包时把“Add Python to PATH”勾上装完重开一个终端窗口再跑安装脚本。如果是环境受限的机器可以换成官方预编译版本或 Docker 方案绕开本地构建环节。4. Linux 上连一级页面都见不到先查 glibc 和运行日志Linux 服务器上部署 OpenClaw我更推荐用官方推荐的 Docker 或者 Linux 原生安装步骤。无论走哪条路一个典型的“页面打不开”原因很容易被忽略glibc 版本不满足要求。4.1 glibc_2.28 not found二进制在当前系统上根本起不来直接下载编译好的二进制到服务器上运行有时会得到这样的报错./openclaw: /lib/x86_64-linux-gnu/libc.so.6: version GLIBC_2.28 not found。意思是这个二进制是在更新版本的 glibc 环境里编译的而当前系统的 glibc 太旧程序无法启动。Ubuntu 18.04 和 Debian 9 默认的 glibc 版本不足 2.28如果你下载的 release 包要求 2.28 以上那这个服务在当前系统上根本跑不起来。服务没起来访问端口当然就是 not found 或者拒绝连接。这属于运行环境不满足要求跟配置文件一点关系没有改 host、改端口都没有意义。4.2 用三个命令确认是不是 glibc 的锅先看系统 glibc 版本ldd --version。再看二进制依赖哪些版本strings ./openclaw | grep GLIBC_2这个能看到它引用了哪些版本的符号。也可以直接ldd ./openclaw如果输出里有 not found 的共享库那就说明缺依赖。如果确认是 glibc 版本不够有三个绕开方式升级到受支持的发行版Ubuntu 20.04 以上、Debian 10 以上找 musl 静态编译的版本使用官方 Docker 镜像。千万不要试图手动替换系统的 libc.so.6 文件那会直接把整个系统的命令全搞挂我见过有人这样操作之后只能进恢复模式修补引导。4.3 Docker 能绕开大多数环境问题但端口映射别忘如果官方提供了 Docker 镜像优先用镜像。镜像把 glibc、Python、Node 这些依赖都打包好了基本不会出现“版本不对”的悲剧。但 Docker 部署同样有翻车点最常见的是docker run -d openclaw跑完忘了加-p 3000:3000容器在跑宿主机却永远访问不到。另外还是要重申 2.2 提到的点容器内服务如果默认监听 127.0.0.1端口映射写了也无效。容器起来后用docker logs 容器名看启动日志里的 UI 地址确认监听情况再决定从宿主机哪个地址访问。5. 一条完整的排查链路不靠猜按证据定位 404前面拆了很多可能原因但到了实际排查场景最忌讳的是东试一下西试一下。我自己的习惯是按一条固定的证据链往下走每一步都拿到确定性的信息再决策。5.1 第一步用 curl 复现别让浏览器缓存干扰你浏览器有缓存、DNS 缓存、Service Worker 等一系列干扰因素。你看到的 404 可能是浏览器缓存里存的也可能是本地代理干扰的不一定是服务真实状态。排查 404 第一步我建议直接用命令行打curl -i http://127.0.0.1:3000/。返回HTTP/1.1 404说明服务活着只是资源路径不对返回Connection refused说明服务没监听这个端口返回301/302说明有重定向看 Location 再跟进访问。curl 是绕过“浏览器玄学”最可靠的验证手段。Windows 下注意用curl.exe -i因为 PowerShell 里的curl默认是别名行为不一样。5.2 第二步用一条命令确认端口和监听地址Linux 上执行ss -lntp | grep 3000Windows 上执行netstat -ano | findstr :3000。看监听地址是 127.0.0.1、0.0.0.0 还是具体的容器 IP再看 PID 是不是 openclaw 的进程。这个步骤还能发现一种特殊情况端口被别的程序占用了。比如另一套服务抢占了 3000 端口OpenClaw 启动失败或者换了端口但你访问 3000 时看到的是别人家的 404 页面。这种“张冠李戴”最容易误导人明明是别人的服务在 404你却以为是 OpenClaw 的 Web UI 坏了。5.3 第三步翻日志找三处关键词日志是最终证据。我重点关注三处web UI available at或者包含http://的地址行确认服务准备监听哪个端口、哪个路径session file locked (timeout 60000ms)说明有锁问题进程可能卡住或退出了unexpected status 404 not found: the model ... does not exist这是 API 404不是页面 404要去模型配置里改模型名或检查 key 权限。启动时最好顺手把日志重定向到文件里./openclaw openclaw.log 21。这样窗口再怎么滚动你也能翻到启动那几行的完整上下文。Windows PowerShell 下用./openclaw.exe * openclaw.log也能做到。另外如果日志里出现pprof相关端口那通常是内置的调试接口不是主 Web UI别访问错。5.4 一个完整的修复案例从 session lock 到页面正常举一个我最近帮人排查的完整过程。环境是 Windows现象是 Web UI 无法访问浏览器显示无法连接。我没有让他改任何配置只做了三步打开任务管理器发现有两个 openclaw 进程在跑一个是上一次没退出干净的残留进程查看日志里面正好是session file locked (timeout 60000ms)结束所有 openclaw 相关进程删除会话目录下的 .lock 文件重新启动。重启后 curl 返回 200浏览器正常打开面板。整个过程大约十分钟没动任何配置。这个案例说明很多 Web UI not found 的根因不是配置而是进程状态和锁文件问题这类原因应该排在“改端口、改路由”之前优先排查。补充一种页面能开但操作时报 404 的案例日志里出现the model gpt-6-sol does not exist。这种情况通常是把模型名写错了或者当前 provider 的 API Key 没有该模型的访问权限。比如接入千问这类模型时模型名必须和你在 provider 后台开通的一致大小写都不能错。修复方式是去模型配置里改成实际可用、权限正确的模型名跟 Web UI 路由毫无关系。6. 部署 OpenClaw 之前我建议你先准备好这张清单排查做多了就会发现大部分 not found 是部署阶段埋下的雷与其事后排查不如部署前多花三分钟自检。6.1 环境预检五件事系统版本与 glibcUbuntu 20.04 以上或 Debian 10 以上跑ldd --version确认Python3.10 以上且已加入 PATHWindows 上重点检查端口确认 3000 或你计划使用的端口没被占用防火墙与安全组服务器需要放行对应端口的入站规则数据目录给会话和配置目录留出可写权限Windows 下不要放在 Program Files 这类受限目录。6.2 遇到 not found 时按这个顺序自问进程起来了吗是正常存活还是已经退出了端口监听了吗监听的是 127.0.0.1 还是 0.0.0.0我访问的地址、端口、路径和日志里打印的完全一致吗UI 静态资源目录里有 index.html 吗日志里有没有 session lock 或 model 404 关键字按这个顺序走绝大多数 not found 都能在五到十分钟内收敛到一个具体原因。不要跳过第一个问题直接去改配置那是本末倒置。6.3 一个小技巧能让你下次少走弯路把启动日志重定向到文件里再开始排错哪怕只是临时做一次。命令行窗口的输出会被新内容刷掉尤其日志量大的时候关键信息一闪而过。存成文件之后用文本编辑器搜“404”“locked”“error”这些关键字比肉眼看屏幕高效得多。踩过几次坑之后我自己的体会是看到 not found 先别急着怀疑 OpenClaw 本身它大概率是“某个中间环节没起来”的信号——可能是进程可能是端口可能是路径也可能是前置的 glibc、Python、Docker 环境。先按证据链走一遍通常比重装三遍更有用。希望这篇能帮你省下对着 localhost 反复刷新的一两个小时。