最近被問得最多的問題不是 OpenClaw 怎么配模型而是OpenClaw 部署完之后瀏覽器打開 Web UI 地址屏幕上只有一行 not found。第一次遇到我還以為是用戶把路徑記錯(cuò)了結(jié)果連續(xù)聊了幾個(gè)案例才發(fā)現(xiàn)同樣是“Web UI 無法訪問 not found”背后原因能差出十萬八千里有人是 Windows 上一鍵腳本跑完頁(yè)面直接打不開有人是 Linux 下二進(jìn)制正常啟動(dòng)、日志也沒報(bào)紅管理界面卻始終 404還有人頁(yè)面能開但一點(diǎn)功能就報(bào)unexpected status 404 not found: the model ... does not exist。這幾種看著都是 not found其實(shí)沒有一個(gè)是同一個(gè)病因。這篇文章把我排查這類問題的完整思路整理出來包括怎么區(qū)分 404 的類型、怎么用命令行確認(rèn)服務(wù)和端口狀態(tài)、Windows 和 Linux 下各自容易踩的坑以及一套能直接照著操作的排查順序。內(nèi)容偏實(shí)操適合剛部署完 OpenClaw 但卡在“頁(yè)面進(jìn)不去”這一關(guān)的朋友參考。1. 先把 not found 分成三類別急著去改配置not found 這個(gè)詞太容易混淆了。它可能出現(xiàn)在瀏覽器頁(yè)面、控制臺(tái)接口也可能出現(xiàn)在 agent 的日志里而每一處出現(xiàn)的 404含義都不一樣。排查第一步不是改配置而是先把看到的報(bào)錯(cuò)歸類。1.1 頁(yè)面 404服務(wù)在響應(yīng)但路徑下沒有東西瀏覽器里輸入http://服務(wù)器IP:端口/頁(yè)面返回一個(gè) 404 Not Found通常還有服務(wù)器軟件的標(biāo)識(shí)或者框架自帶的錯(cuò)誤頁(yè)樣式。這說明 HTTP 服務(wù)本身是通的——請(qǐng)求發(fā)出去了程序也回應(yīng)了只是這個(gè)路徑下沒有對(duì)應(yīng)的資源。也就是說進(jìn)程是活著的你訪問的路徑不對(duì)或者路徑對(duì)應(yīng)的前端文件沒放上去。這種 404 的特征是頁(yè)面有內(nèi)容、有響應(yīng)頭不是瀏覽器報(bào)“無法連接”。遇到它要懷疑的是路由前綴、靜態(tài)資源目錄、Nginx 反代規(guī)則而不是進(jìn)程有沒有起來。1.2 連接被拒絕服務(wù)根本沒監(jiān)聽另一種情況是瀏覽器直接提示“無法訪問此網(wǎng)站”“ERR_CONNECTION_REFUSED”或者“連接超時(shí)”。這跟 404 嚴(yán)格說不是一回事但很多人口語上也會(huì)說“not found”“打不開”。它的本質(zhì)是沒有任何進(jìn)程在監(jiān)聽你訪問的地址和端口或者網(wǎng)絡(luò)路徑被防火墻、安全組攔截了。這種情況下改 Web UI 配置是白費(fèi)的應(yīng)該先去看進(jìn)程是否存活、端口是否監(jiān)聽、防火墻是否放行。很多人把這兩類混在一起對(duì)著配置文件折騰半天結(jié)果服務(wù)壓根沒起來。1.3 API 層面的 404服務(wù)正常資源或權(quán)限不對(duì)還有一種 404 出現(xiàn)在頁(yè)面能打開之后。比如操作 agent 時(shí)返回unexpected status 404 not found: the model gpt-6-sol does not exist or you do not have access。這種報(bào)錯(cuò)是后端調(diào)用外部模型時(shí)被模型服務(wù)方返回的 404。它意味著 OpenClaw 的 Web UI 本身沒問題問題出在模型名寫錯(cuò)、API Key 沒有對(duì)應(yīng)模型權(quán)限或者 provider 路由配置不對(duì)。這屬于“后端和上游服務(wù)之間的交互失敗”跟頁(yè)面打不開是兩碼事。如果你把它當(dāng)成 Web UI 故障去重裝那就跑偏了。1.4 用一張表把三種癥狀的病灶分清瀏覽器/日志表現(xiàn)本質(zhì)優(yōu)先排查方向頁(yè)面返回 404 Not Found樣式完整服務(wù)已響應(yīng)資源缺失路由前綴、靜態(tài)資源目錄、反代規(guī)則ERR_CONNECTION_REFUSED / 無法訪問 / 超時(shí)服務(wù)未監(jiān)聽或網(wǎng)絡(luò)不通進(jìn)程狀態(tài)、端口監(jiān)聽、防火墻、容器端口映射頁(yè)面能開操作時(shí)報(bào) model 404 / API 404后端與上游資源交互失敗模型名、API Key 權(quán)限、provider 配置排查的任何階段都要把完整報(bào)錯(cuò)原文截圖或者復(fù)制下來不要只記得“not found”兩個(gè)單詞。因?yàn)?not found 只是結(jié)果真正決定病因的是它出現(xiàn)在哪個(gè)環(huán)節(jié)以及響應(yīng)碼是誰返回的。2. 服務(wù)活著卻 404端口、路徑和前端資源三大盲區(qū)進(jìn)程在跑端口也有監(jiān)聽但訪問就是 404。這種情況最迷惑人因?yàn)閺谋砻婵匆磺姓?。?shí)際上問題往往集中在三個(gè)地方監(jiān)聽地址、訪問路徑、靜態(tài)資源。2.1 監(jiān)聽地址默認(rèn)綁在 127.0.0.1外部訪問當(dāng)然不通很多框架默認(rèn)把 HTTP 服務(wù)綁定在 127.0.0.1 這個(gè)回環(huán)地址上OpenClaw 這類本地優(yōu)先的框架更是常見。好處是本機(jī)訪問安全壞處是——如果服務(wù)部署在服務(wù)器上你用局域網(wǎng) IP 或者公網(wǎng) IP 去訪問連接請(qǐng)求被系統(tǒng)直接丟棄表現(xiàn)就是瀏覽器拒絕連接或者反代層返回 404。驗(yàn)證方法很簡(jiǎn)單。Linux 上執(zhí)行ss -lntp | grep 3000Windows 上執(zhí)行netstat -ano | findstr :3000。如果監(jiān)聽地址是127.0.0.1:3000說明服務(wù)只在本地回環(huán)口上待著外部根本進(jìn)不去。解決辦法是在 OpenClaw 的配置里把 host 改成0.0.0.0然后重啟進(jìn)程。WSL2 環(huán)境里這個(gè)坑尤其明顯。WSL2 本身是一個(gè)獨(dú)立的虛擬網(wǎng)絡(luò)環(huán)境Windows 瀏覽器訪問 localhost 不一定能落到 WSL 里的服務(wù)上。最省事的方案是讓服務(wù)監(jiān)聽 0.0.0.0再?gòu)?Windows 側(cè)直接用 WSL 的 IP 訪問。2.2 Docker 端口映射和容器內(nèi)監(jiān)聽是兩件事如果 OpenClaw 跑在 Docker 容器里那么“能訪問”需要同時(shí)滿足兩個(gè)條件容器內(nèi)的進(jìn)程監(jiān)聽 0.0.0.0以及宿主機(jī)做了-p 3000:3000端口映射。漏掉任何一個(gè)外面都訪問不到。尤其容易忽視的是第一種情況容器里服務(wù)默認(rèn)監(jiān)聽 127.0.0.1即使你寫了-p 3000:3000流量進(jìn)到容器之后也沒有進(jìn)程在容器內(nèi)的 0.0.0.0:3000 上接收連接表現(xiàn)依舊是拒絕連接。我見過多次docker ps顯示容器運(yùn)行中瀏覽器卻打不開的場(chǎng)景最后都收斂到這兩個(gè)條件缺一個(gè)。2.3 控制臺(tái)端口和路徑不一定是你以為的那個(gè)Web UI 的訪問地址要以 OpenClaw 啟動(dòng)日志里打印的那行為準(zhǔn)而不是憑記憶猜 3000 或 8080。很多框架啟動(dòng)時(shí)會(huì)輸出類似web UI available at http://localhost:3000的提示。如果日志明確寫了地址就應(yīng)該原樣打開不要自己組合。另外管理面板的路徑未必是根路徑。有些版本把面板掛在/admin、/ui這種子路徑下直接訪問根路徑就會(huì)得到 404。我排查過一個(gè)案例用戶始終訪問http://IP:3000/得到 404但日志里清清楚楚寫著http://IP:3000/ui才是面板地址改一下 URL 立刻正常。2.4 前端靜態(tài)資源缺失后端進(jìn)程正常文件目錄是空的OpenClaw 的 Web UI 本質(zhì)上是靜態(tài)資源HTML/JS/CSS加后端 API。如果部署過程中前端資源沒有完整生成或者解壓中斷、磁盤被寫滿靜態(tài)資源目錄可能整個(gè)是空的。這時(shí)候后端 API 進(jìn)程正常監(jiān)聽端口但訪問首頁(yè)時(shí)找不到 index.html自然返回 404。驗(yàn)證方法不復(fù)雜找到 UI 靜態(tài)資源目錄看一眼里面有沒有 index.html。如果有說明前端文件在如果沒有就得重跑安裝流程或者重新構(gòu)建前端。在 Windows 上這種中斷概率比 Linux 高不少解壓被殺毒軟件打斷、腳本被系統(tǒng)彈窗卡住都可能留下一個(gè)殘缺的安裝目錄。2.5 配置項(xiàng)被改掉或覆蓋Web 開關(guān)、端口、環(huán)境變量還有一類隱蔽情況配置文件中有一個(gè)類似web.enabledfalse或serve_ui的開關(guān)被某些安裝腳本默認(rèn)關(guān)掉了或者 .env 文件里的 PORT 和主配置文件里的端口不一致你按照 .env 的端口去訪問但服務(wù)實(shí)際監(jiān)聽的是另一個(gè)端口。排查方式是打開實(shí)際運(yùn)行的配置文件把 host、port、enabled 這三個(gè)字段全部核對(duì)一遍并且確認(rèn)沒有多個(gè)配置文件在互相覆蓋。改完配置后必須重啟進(jìn)程這一步很多人會(huì)忘改完發(fā)現(xiàn)還是不行其實(shí)是新配置壓根沒生效。3. Windows 部署翻車重災(zāi)區(qū)進(jìn)程假活、文件鎖與缺失的 PythonWindows 上部署 OpenClawWeb UI 打不開的原因和 Linux 有很大不同。最典型的問題有三個(gè)全都屬于“看起來部署成功實(shí)際上服務(wù)沒進(jìn)入可用狀態(tài)”。3.1 一鍵腳本的“假啟動(dòng)”窗口一閃而過服務(wù)其實(shí)沒起來Windows 上下載 release 包或者使用一鍵安裝腳本雙擊后黑色命令行窗口一閃而過瀏覽器里自然是打不開的。這不是 OpenClaw 特有幾乎所有命令行服務(wù)在 Windows 上都有這個(gè)問題。窗口一閃而過意味著程序啟動(dòng)后立刻退出你根本看不到錯(cuò)誤信息。常見原因有三個(gè)依賴的 Python 不在 PATH端口被別的程序占用后啟動(dòng)失敗安全軟件攔截了進(jìn)程的網(wǎng)絡(luò)監(jiān)聽。我的建議是不要只依賴雙擊腳本而是打開命令提示符或 PowerShell切到安裝目錄手動(dòng)運(yùn)行啟動(dòng)命令讓輸出停留在屏幕上?？吹酵暾麍?bào)錯(cuò)日志再判斷缺什么依賴。很多人連錯(cuò)誤信息都沒看到上來就懷疑 Web UI 路由配置方向完全錯(cuò)了。3.2 session file lockedtimeout 60000ms舊實(shí)例沒死透Windows 上很容易遇到一個(gè)日志agent failed before reply: session file locked (timeout 60000ms)。這個(gè)報(bào)錯(cuò)的含義是OpenClaw 為會(huì)話文件加了鎖防止多個(gè)進(jìn)程同時(shí)寫同一個(gè)會(huì)話。上一次啟動(dòng)沒有正常退出鎖沒釋放新實(shí)例啟動(dòng)時(shí)拿不到鎖等了 60 秒超時(shí)agent 直接失敗Web UI 所在的進(jìn)程根本沒起來。處理辦法分三步打開任務(wù)管理器結(jié)束所有 openclaw 相關(guān)進(jìn)程進(jìn)入會(huì)話數(shù)據(jù)目錄刪除殘留的 .lock 文件重新啟動(dòng)。注意不要在有其他實(shí)例正在運(yùn)行的時(shí)候去刪鎖文件否則另一個(gè)進(jìn)程正寫到一半刪鎖會(huì)引出更麻煩的數(shù)據(jù)問題。正確順序永遠(yuǎn)是先確認(rèn)全部進(jìn)程退出再清理鎖。3.3 python was not found 會(huì)導(dǎo)致前端構(gòu)建鏈斷掉Win10/11 上有句經(jīng)典報(bào)錯(cuò)python was not found; run without arguments to install from the Microsoft Store。這是系統(tǒng)里沒有 Python或者安裝 Python 時(shí)沒有勾選“Add Python to PATH”。OpenClaw 的安裝腳本或者前端構(gòu)建步驟一旦調(diào)用 Python這個(gè)報(bào)錯(cuò)就會(huì)中斷整個(gè)流程前端資源自然生成不出來。后果就是后端進(jìn)程可能在跑但靜態(tài)資源目錄是空的訪問首頁(yè)返回 404。解決辦法不是從微軟商店裝一個(gè)湊合的版本而是安裝官方 Python 安裝包時(shí)把“Add Python to PATH”勾上裝完重開一個(gè)終端窗口再跑安裝腳本。如果是環(huán)境受限的機(jī)器可以換成官方預(yù)編譯版本或 Docker 方案繞開本地構(gòu)建環(huán)節(jié)。4. Linux 上連一級(jí)頁(yè)面都見不到先查 glibc 和運(yùn)行日志Linux 服務(wù)器上部署 OpenClaw我更推薦用官方推薦的 Docker 或者 Linux 原生安裝步驟。無論走哪條路一個(gè)典型的“頁(yè)面打不開”原因很容易被忽略glibc 版本不滿足要求。4.1 glibc_2.28 not found二進(jìn)制在當(dāng)前系統(tǒng)上根本起不來直接下載編譯好的二進(jìn)制到服務(wù)器上運(yùn)行有時(shí)會(huì)得到這樣的報(bào)錯(cuò)./openclaw: /lib/x86_64-linux-gnu/libc.so.6: version GLIBC_2.28 not found。意思是這個(gè)二進(jìn)制是在更新版本的 glibc 環(huán)境里編譯的而當(dāng)前系統(tǒng)的 glibc 太舊程序無法啟動(dòng)。Ubuntu 18.04 和 Debian 9 默認(rèn)的 glibc 版本不足 2.28如果你下載的 release 包要求 2.28 以上那這個(gè)服務(wù)在當(dāng)前系統(tǒng)上根本跑不起來。服務(wù)沒起來訪問端口當(dāng)然就是 not found 或者拒絕連接。這屬于運(yùn)行環(huán)境不滿足要求跟配置文件一點(diǎn)關(guān)系沒有改 host、改端口都沒有意義。4.2 用三個(gè)命令確認(rèn)是不是 glibc 的鍋先看系統(tǒng) glibc 版本ldd --version。再看二進(jìn)制依賴哪些版本strings ./openclaw | grep GLIBC_2這個(gè)能看到它引用了哪些版本的符號(hào)。也可以直接ldd ./openclaw如果輸出里有 not found 的共享庫(kù)那就說明缺依賴。如果確認(rèn)是 glibc 版本不夠有三個(gè)繞開方式升級(jí)到受支持的發(fā)行版Ubuntu 20.04 以上、Debian 10 以上找 musl 靜態(tài)編譯的版本使用官方 Docker 鏡像。千萬不要試圖手動(dòng)替換系統(tǒng)的 libc.so.6 文件那會(huì)直接把整個(gè)系統(tǒng)的命令全搞掛我見過有人這樣操作之后只能進(jìn)恢復(fù)模式修補(bǔ)引導(dǎo)。4.3 Docker 能繞開大多數(shù)環(huán)境問題但端口映射別忘如果官方提供了 Docker 鏡像優(yōu)先用鏡像。鏡像把 glibc、Python、Node 這些依賴都打包好了基本不會(huì)出現(xiàn)“版本不對(duì)”的悲劇。但 Docker 部署同樣有翻車點(diǎn)最常見的是docker run -d openclaw跑完忘了加-p 3000:3000容器在跑宿主機(jī)卻永遠(yuǎn)訪問不到。另外還是要重申 2.2 提到的點(diǎn)容器內(nèi)服務(wù)如果默認(rèn)監(jiān)聽 127.0.0.1端口映射寫了也無效。容器起來后用docker logs 容器名看啟動(dòng)日志里的 UI 地址確認(rèn)監(jiān)聽情況再?zèng)Q定從宿主機(jī)哪個(gè)地址訪問。5. 一條完整的排查鏈路不靠猜按證據(jù)定位 404前面拆了很多可能原因但到了實(shí)際排查場(chǎng)景最忌諱的是東試一下西試一下。我自己的習(xí)慣是按一條固定的證據(jù)鏈往下走每一步都拿到確定性的信息再?zèng)Q策。5.1 第一步用 curl 復(fù)現(xiàn)別讓瀏覽器緩存干擾你瀏覽器有緩存、DNS 緩存、Service Worker 等一系列干擾因素。你看到的 404 可能是瀏覽器緩存里存的也可能是本地代理干擾的不一定是服務(wù)真實(shí)狀態(tài)。排查 404 第一步我建議直接用命令行打curl -i http://127.0.0.1:3000/。返回HTTP/1.1 404說明服務(wù)活著只是資源路徑不對(duì)返回Connection refused說明服務(wù)沒監(jiān)聽這個(gè)端口返回301/302說明有重定向看 Location 再跟進(jìn)訪問。curl 是繞過“瀏覽器玄學(xué)”最可靠的驗(yàn)證手段。Windows 下注意用curl.exe -i因?yàn)?PowerShell 里的curl默認(rèn)是別名行為不一樣。5.2 第二步用一條命令確認(rèn)端口和監(jiān)聽地址Linux 上執(zhí)行ss -lntp | grep 3000Windows 上執(zhí)行netstat -ano | findstr :3000。看監(jiān)聽地址是 127.0.0.1、0.0.0.0 還是具體的容器 IP再看 PID 是不是 openclaw 的進(jìn)程。這個(gè)步驟還能發(fā)現(xiàn)一種特殊情況端口被別的程序占用了。比如另一套服務(wù)搶占了 3000 端口OpenClaw 啟動(dòng)失敗或者換了端口但你訪問 3000 時(shí)看到的是別人家的 404 頁(yè)面。這種“張冠李戴”最容易誤導(dǎo)人明明是別人的服務(wù)在 404你卻以為是 OpenClaw 的 Web UI 壞了。5.3 第三步翻日志找三處關(guān)鍵詞日志是最終證據(jù)。我重點(diǎn)關(guān)注三處web UI available at或者包含http://的地址行確認(rèn)服務(wù)準(zhǔn)備監(jiān)聽哪個(gè)端口、哪個(gè)路徑session file locked (timeout 60000ms)說明有鎖問題進(jìn)程可能卡住或退出了unexpected status 404 not found: the model ... does not exist這是 API 404不是頁(yè)面 404要去模型配置里改模型名或檢查 key 權(quán)限。啟動(dòng)時(shí)最好順手把日志重定向到文件里./openclaw openclaw.log 21。這樣窗口再怎么滾動(dòng)你也能翻到啟動(dòng)那幾行的完整上下文。Windows PowerShell 下用./openclaw.exe * openclaw.log也能做到。另外如果日志里出現(xiàn)pprof相關(guān)端口那通常是內(nèi)置的調(diào)試接口不是主 Web UI別訪問錯(cuò)。5.4 一個(gè)完整的修復(fù)案例從 session lock 到頁(yè)面正常舉一個(gè)我最近幫人排查的完整過程。環(huán)境是 Windows現(xiàn)象是 Web UI 無法訪問瀏覽器顯示無法連接。我沒有讓他改任何配置只做了三步打開任務(wù)管理器發(fā)現(xiàn)有兩個(gè) openclaw 進(jìn)程在跑一個(gè)是上一次沒退出干凈的殘留進(jìn)程查看日志里面正好是session file locked (timeout 60000ms)結(jié)束所有 openclaw 相關(guān)進(jìn)程刪除會(huì)話目錄下的 .lock 文件重新啟動(dòng)。重啟后 curl 返回 200瀏覽器正常打開面板。整個(gè)過程大約十分鐘沒動(dòng)任何配置。這個(gè)案例說明很多 Web UI not found 的根因不是配置而是進(jìn)程狀態(tài)和鎖文件問題這類原因應(yīng)該排在“改端口、改路由”之前優(yōu)先排查。補(bǔ)充一種頁(yè)面能開但操作時(shí)報(bào) 404 的案例日志里出現(xiàn)the model gpt-6-sol does not exist。這種情況通常是把模型名寫錯(cuò)了或者當(dāng)前 provider 的 API Key 沒有該模型的訪問權(quán)限。比如接入千問這類模型時(shí)模型名必須和你在 provider 后臺(tái)開通的一致大小寫都不能錯(cuò)。修復(fù)方式是去模型配置里改成實(shí)際可用、權(quán)限正確的模型名跟 Web UI 路由毫無關(guān)系。6. 部署 OpenClaw 之前我建議你先準(zhǔn)備好這張清單排查做多了就會(huì)發(fā)現(xiàn)大部分 not found 是部署階段埋下的雷與其事后排查不如部署前多花三分鐘自檢。6.1 環(huán)境預(yù)檢五件事系統(tǒng)版本與 glibcUbuntu 20.04 以上或 Debian 10 以上跑ldd --version確認(rèn)Python3.10 以上且已加入 PATHWindows 上重點(diǎn)檢查端口確認(rèn) 3000 或你計(jì)劃使用的端口沒被占用防火墻與安全組服務(wù)器需要放行對(duì)應(yīng)端口的入站規(guī)則數(shù)據(jù)目錄給會(huì)話和配置目錄留出可寫權(quán)限Windows 下不要放在 Program Files 這類受限目錄。6.2 遇到 not found 時(shí)按這個(gè)順序自問進(jìn)程起來了嗎是正常存活還是已經(jīng)退出了端口監(jiān)聽了嗎監(jiān)聽的是 127.0.0.1 還是 0.0.0.0我訪問的地址、端口、路徑和日志里打印的完全一致嗎UI 靜態(tài)資源目錄里有 index.html 嗎日志里有沒有 session lock 或 model 404 關(guān)鍵字按這個(gè)順序走絕大多數(shù) not found 都能在五到十分鐘內(nèi)收斂到一個(gè)具體原因。不要跳過第一個(gè)問題直接去改配置那是本末倒置。6.3 一個(gè)小技巧能讓你下次少走彎路把啟動(dòng)日志重定向到文件里再開始排錯(cuò)哪怕只是臨時(shí)做一次。命令行窗口的輸出會(huì)被新內(nèi)容刷掉尤其日志量大的時(shí)候關(guān)鍵信息一閃而過。存成文件之后用文本編輯器搜“404”“l(fā)ocked”“error”這些關(guān)鍵字比肉眼看屏幕高效得多。踩過幾次坑之后我自己的體會(huì)是看到 not found 先別急著懷疑 OpenClaw 本身它大概率是“某個(gè)中間環(huán)節(jié)沒起來”的信號(hào)——可能是進(jìn)程可能是端口可能是路徑也可能是前置的 glibc、Python、Docker 環(huán)境。先按證據(jù)鏈走一遍通常比重裝三遍更有用。希望這篇能幫你省下對(duì)著 localhost 反復(fù)刷新的一兩個(gè)小時(shí)。