1. OpenClaw Dashboard 白屏到底怎么回事先搞清 gateway 与 UI 的加载链路OpenClaw Dashboard 是 OpenClaw 网关自带的一套可视化管理界面用来查看会话、模型路由、工具调用记录和网关运行状态。它本质上是一个静态前端资源包由openclaw gateway进程在本地起一个 HTTP 服务对外提供。你打开浏览器看到的图表、设置面板、日志列表全部来自安装目录里的dist/control-ui文件夹。一旦这个文件夹缺失或者内容不完整网关进程照样能启动、端口照样能监听但浏览器请求首页时拿不到 HTML 和 JS结果就是一片白屏控制台里通常还会伴随 404 或者Failed to load resource的报错。这个问题的典型触发场景是版本升级。OpenClaw 在 v2026.3.22 这一版的发布包里漏掉了 Dashboard 的前端产物也就是说 npm 全局包里压根没有control-ui目录。很多朋友升级完执行openclaw gateway restart进程日志显示正常http://127.0.0.1:18789也能连上但页面就是空白。这时候你去跑pnpm ui:build是没用的因为源文件都不在构建工具找不到入口。重装又担心把已有的模型配置、API Key、会话历史弄丢所以最稳的思路是先用官方自带的doctor --repair做一次完整性修复再不行才手动补文件。判断自己是不是踩了这个坑可以按下面几步快速确认。先看网关进程在不在openclaw gateway status正常会输出 running 以及监听的 host 和 port。然后直接请求首页看返回的是不是空内容或者 404curl -i http://127.0.0.1:18789/如果返回HTTP/1.1 404 Not Found或者 body 长度几乎为 0基本可以确定是 UI 资源缺失。再进一步确认安装目录里有没有control-uils -l $(npm root -g)/openclaw/dist/这条命令会列出全局安装目录下dist的内容。如果里面只有openclaw.mjs之类的后端文件没有control-ui文件夹那就对上了。注意npm root -g在不同系统上路径不一样macOS 和 Linux 常见是/usr/local/lib/node_modules或~/.npm-global/lib/node_modulesWindows 则是%APPDATA%\npm\node_modules。用npm root -g让 npm 自己告诉你最省事。这里要提醒一句Dashboard 打不开不等于网关挂了。网关负责的是模型请求转发、工具调度这些后端逻辑UI 只是它的一个附属展示层。所以你在排查时不要一上来就kill进程或者删配置先分清是「服务没起来」还是「服务起来了但前端资源丢了」。前者看gateway status和端口占用后者看dist/control-ui是否存在。把这两件事分开排查效率会高很多。接下来第二节我们先说清楚在动手修之前需要准备什么包括版本确认和 TaoToken 这类模型接入侧的配置避免修完 UI 发现模型又连不上。2. 修复前的前置准备版本确认、TaoToken 接入与 gateway 配置基线动手之前先把环境摸清楚能省掉大量来回试错。第一件事是确认当前 OpenClaw 的版本因为doctor --repair的行为在不同版本间有差异openclaw --version npm ls -g openclaw第一条给出 CLI 版本第二条给出全局安装的实际包版本。如果两条对不上说明 PATH 里可能还有旧的可执行文件建议用which openclaw确认实际调用的是哪一个。确认版本后如果低于修复版本先升级npm update -g openclaw升级完再跑一次openclaw --version复核。这里有个小坑某些环境下 npm 全局目录权限不足npm update -g会静默失败或者报 EACCES。遇到这种情况不要用sudo npm硬来容易把文件属主搞乱更稳的做法是配置一个用户级全局目录或者用 nvm 管理 Node 版本让全局包落在用户目录下。第二件事是确认模型接入侧的配置没被动过。OpenClaw 的模型调用依赖一个 provider 配置通常写在~/.openclaw/config.json或者项目根目录的openclaw.config.json里。如果你用的是 TaoToken 这类聚合接入服务配置里需要体现 Base URL、API Key 和 Model ID 三件套。TaoToken 的 API 地址是https://taotoken.net/api控制台和密钥管理在https://taotoken.net/console模型列表和在线调试在https://taotoken.net/models。这些信息在修复 UI 的过程中不需要改动但建议先备份一份配置防止doctor --repair在某些版本下重置默认值cp ~/.openclaw/config.json ~/.openclaw/config.json.bak第三件事是确认 gateway 的监听配置。Dashboard 能不能访问取决于 gateway 绑定的 host 和 port。默认配置一般监听127.0.0.1:18789如果你之前改过端口或者绑到了0.0.0.0访问地址要相应调整。一个典型的 gateway 配置片段长这样可以放在~/.openclaw/config.json的gateway字段下{ gateway: { host: 127.0.0.1, port: 18789, ui: { enabled: true, path: dist/control-ui }, cors: { enabled: false, origins: [] } } }这里ui.enabled控制是否对外提供 Dashboardui.path指向前端资源目录默认就是安装目录下的dist/control-ui。如果你之前手动改过ui.path修复时要保证这个路径和实际文件位置一致否则即使文件补回来了网关也找不到。cors字段在本地访问时保持关闭即可只有你需要从别的域名页面调用网关接口时才需要开。第四件事是准备一个可回滚的版本号。手动补文件方案需要从旧版本包里提取control-ui所以提前记下一个确认带完整 UI 的版本比如 v2026.3.13。可以用npm view openclaw versions查看所有可用版本挑一个发布时间在出问题版本之前的稳定版。把这些前置信息准备好后面无论是走doctor --repair还是手动复制都能一次到位不会修到一半发现版本对不上或者路径写错。3. 可复制的修复配置doctor --repair 执行步骤与 gateway 配置片段这一节是核心操作区两条路线都给你优先走官方修复失败再手动补。先强调一个原则全程不要删除~/.openclaw目录你的模型配置、会话数据、API Key 都在里面删了就真丢了。路线一官方一键修复。确保已经升级到最新版后直接执行openclaw doctor --repair这个命令会做几件事校验安装包的完整性对比缺失的文件清单从官方源重新拉取缺失的control-ui资源并写回安装目录同时检查 gateway 配置里ui.path是否指向正确位置。执行过程中会打印每一步的结果重点看有没有repaired或者restored字样。如果输出里出现no issues found但你页面还是白的说明问题不在文件缺失而在配置或者缓存继续往下看。修复完成后重启网关openclaw gateway restart重启后确认进程状态和端口openclaw gateway status curl -i http://127.0.0.1:18789/这次curl应该返回HTTP/1.1 200 OK并且 body 里有 HTML 内容。如果还是 404进入路线二。路线二手动补文件。先从旧版本包里提取完整的control-uicd /tmp npm pack openclaw2026.3.13 tar -xzf openclaw-2026.3.13.tgz package/dist/control-ui第一条命令会在/tmp下生成一个 tgz 包第二条把里面的control-ui目录解出来。接着定位你的全局安装目录npm root -g假设输出是/home/user/.npm-global/lib/node_modules那么 OpenClaw 的安装目录就是它下面的openclaw。把提取出来的 UI 文件复制过去cp -r /tmp/package/dist/control-ui $(npm root -g)/openclaw/dist/复制完确认一下文件数量和入口文件存在ls $(npm root -g)/openclaw/dist/control-ui/ | head应该能看到index.html、assets之类的条目。然后重启网关openclaw gateway restart如果你在配置里自定义过ui.path记得把上面复制到的实际路径同步写进配置。下面这份 JSON 是修复后建议的 gateway 配置基线路径按你机器的实际npm root -g结果替换{ gateway: { host: 127.0.0.1, port: 18789, ui: { enabled: true, path: /home/user/.npm-global/lib/node_modules/openclaw/dist/control-ui } } }改完配置再openclaw gateway restart一次让配置生效。这里有个细节ui.path用绝对路径比相对路径稳因为网关进程的工作目录不一定是你执行命令的目录相对路径容易解析错。另外如果你同时装了多个 Node 版本npm root -g的结果会随当前 Node 版本变化复制文件前先node -v确认一下避免把文件补到了另一个版本的目录里。两条路线都做完后建议顺手把版本锁定一下避免下次npm update -g又升到有问题的版本。可以在项目里用package.json的overrides或者直接用npm install -g openclaw2026.3.13指定版本。等官方发布确认修复的版本后再放开升级。4. 验证请求与成功结果确认 Dashboard 真正可访问文件补完、网关重启不代表就万事大吉得用几个动作确认 UI 是真的活了而不是浏览器缓存骗了你。第一步命令行验证首页返回curl -s -o /dev/null -w %{http_code} %{size_download}\n http://127.0.0.1:18789/正常输出应该是200加上一个明显大于 0 的字节数比如200 4821。如果状态码是 200 但 size 很小可能是返回了一个占位页继续看下一步。第二步验证静态资源能加载curl -s http://127.0.0.1:18789/ | grep -o assets/[^]* | head这条会从首页 HTML 里抓出引用的 JS/CSS 路径。拿到路径后再请求一次确认返回 200curl -s -o /dev/null -w %{http_code}\n http://127.0.0.1:18789/assets/index-xxxx.js把index-xxxx.js换成上一步实际抓到的文件名。如果首页 200 但资源 404说明control-ui目录里的assets子目录没复制全回到第三节重新cp -r整个目录。第三步浏览器侧验证。打开http://127.0.0.1:18789如果还是白屏先强制刷新绕过缓存macOS 用CmdShiftRWindows/Linux 用CtrlShiftR。还不行就打开开发者工具的 Network 面板看有没有红色 404 请求Console 面板看有没有 JS 报错。常见的报错是Failed to load module script或者Unexpected token 前者说明 JS 文件没加载到后者说明服务器返回了 HTML 而不是 JS通常是路径配错导致网关把资源请求当成了路由请求。第四步验证 Dashboard 里的功能是否真的可用而不只是页面能显示。登录后重点看三个地方模型列表能不能拉到、会话列表有没有数据、设置页能不能保存。模型列表依赖网关调用 provider 接口如果你用的是 TaoToken 接入这里能正常列出模型就说明 Base URL 和 API Key 配置没问题。如果模型列表转圈或者报错去https://taotoken.net/models对照一下可用模型 ID确认配置里写的 Model ID 拼写一致。会话列表为空是正常的新装环境本来就没有历史会话。第五步确认网关日志没有异常。Dashboard 能打开但功能报错时日志是最直接的线索openclaw gateway logs --tail 50重点看有没有ECONNREFUSED、401、invalid api key这类字样。401 通常是 API Key 失效或者没带上ECONNREFUSED是网关连不上上游服务。把这几步都走完你就能确定 Dashboard 不只是「看起来回来了」而是真的能干活。如果验证过程中遇到报错下一节把常见错误和对应解法列清楚。5. 本篇常见错误排查401、local proxy failed、reading choices 与 OAuth 报错修复过程中最容易撞上的几类报错这里逐个拆。第一类401 Unauthorized。这个报错一般出现在 Dashboard 里操作模型相关功能时根因是网关调用上游模型接口时鉴权失败。排查顺序先确认配置文件里的 API Key 没有多余空格或换行JSON 里字符串不能带尾随空格再确认 Base URL 写的是https://taotoken.net/api而不是带路径的完整接口地址很多聚合服务的 Base URL 和具体 endpoint 是分开的写错就会 401 或者 404。如果你在 TaoToken 控制台重新生成过 Key记得同步更新本地配置并重启网关。验证 Key 是否有效可以直接用 curl 打一次模型列表接口curl -s https://taotoken.net/api/models \ -H Authorization: Bearer $TAOTOKEN_API_KEY | head返回 JSON 里有模型数组就说明 Key 没问题问题在 OpenClaw 的配置读取上。第二类local proxy failed。这个报错说明网关尝试通过本地代理转发请求但失败了。常见原因是配置里设置了proxy字段指向一个已经不在运行的本地端口或者环境变量HTTP_PROXY/HTTPS_PROXY指向了失效地址。检查配置里有没有proxy相关字段有的话先注释掉再检查 shell 环境env | grep -i proxy如果有输出且指向本地端口临时清掉再重启网关unset HTTP_PROXY HTTPS_PROXY openclaw gateway restart第三类reading choices或者Cannot read properties of undefined (reading choices)。这是解析模型响应时拿不到预期结构导致的通常意味着上游返回的不是标准 chat completion 格式而是错误对象。根因可能是 Model ID 写错请求打到了一个不存在的模型上游返回错误 JSON网关按成功响应去解析choices就崩了。解法是核对配置里的 Model ID去https://taotoken.net/models确认这个 ID 真实存在注意大小写和连字符。另外确认请求路径拼接正确Base URL 末尾不要多加/v1之类的后缀除非文档明确要求。第四类OAuth 相关报错比如OAuth token expired或invalid_grant。如果你用的是需要 OAuth 授权的模型提供方token 过期是常态。OpenClaw 一般会在配置里存 refresh token自动刷新失败时就会报这个。处理方式是重新走一次授权流程把新的 token 写回配置。如果你同时用 TaoToken 这类 API Key 方式接入建议把 OAuth 提供方和 API Key 提供方分开配置避免一个失效影响全部。检查配置里providers数组每个 provider 的auth字段类型要匹配API Key 用apiKeyOAuth 用oauth不要混。第五类Dashboard 能打开但一直转圈。这种多半是前端请求后端接口超时去 Network 面板看哪个请求 pending。常见的是/api/status或/api/models卡住根因还是网关到上游的连接问题回到第二类和第三类排查。另外浏览器插件有时会拦截本地请求用无痕窗口试一次能快速排除。把这几类报错和对应动作记下来下次再遇到白屏或者功能异常基本能对号入座。修完之后如果想让模型接入更省心可以到https://taotoken.net/api-keys管理密钥到https://taotoken.net/doc看接入文档把 Base URL、Key、Model ID 三件套一次配对减少后续排查成本。6. 修好之后怎么用得更顺把 Dashboard 接入与模型调用固化下来Dashboard 找回来只是第一步真正省心的是把接入配置和排查流程固化下次升级不再手忙脚乱。第一件事把 gateway 配置和 provider 配置纳入版本管理。在项目根目录建一个openclaw.config.example.json把 host、port、ui.path、provider 的 Base URL 和 Model ID 写进去API Key 用占位符真实 Key 放在环境变量或者本地不提交的openclaw.config.json里。这样换机器或者重装时照着 example 填一遍就能跑起来。第二件事把doctor --repair加进升级流程。每次npm update -g openclaw之后固定执行openclaw doctor --repair openclaw gateway restart openclaw gateway status这三条串起来升级、修复、重启、确认一步到位。如果doctor报出其他配置问题顺手一起修了比等到用的时候才发现强。第三件事模型调用侧建议统一走一个入口。如果你同时接多个模型提供方配置里 provider 一多排查 401 或者 Model ID 错误就很费劲。用 TaoToken 这类聚合接入的好处是 Base URL 统一、Key 统一、模型列表统一Dashboard 里切换模型只需要改 Model ID。长期做编码或者跑 Agent 任务的话可以了解下 Coding Plan 这类方案把常用模型的调用配额和路由固定下来减少临时配置的出错概率。需要在线验证某个模型能不能通直接用模型对话页面发一条测试消息最快。第四件事给 Dashboard 加一个健康检查习惯。不用很复杂浏览器书签存一个http://127.0.0.1:18789每次升级后点一下能打开就说明 UI 资源在。再配合一条 curl 命令写进 shell aliasalias oc-healthcurl -s -o /dev/null -w %{http_code}\n http://127.0.0.1:18789/ openclaw gateway status以后怀疑出问题敲一下oc-health状态码和进程状态一起出来几秒钟定位是 UI 丢了还是网关没起。最后说个实际经验OpenClaw 这类工具的 UI 和网关是解耦的UI 丢了不影响后端跑任务所以遇到白屏先别慌按「确认进程 → 确认资源目录 → doctor 修复 → 手动补文件 → 验证请求」这个顺序走基本三分钟内能定位。真正容易踩的坑不是修复本身而是修复过程中误删配置或者把文件补到了错误的 Node 版本目录。养成改配置前备份、复制文件前确认npm root -g的习惯这类问题以后就是小插曲。需要管理密钥或者看接入细节去https://taotoken.net/api-keys和https://taotoken.net/doc对照着配一遍把三件套写对Dashboard 和模型调用就都稳了。