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