企业官网建设流程全解析

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。然后直接请求首页，看返回的是不是空内容或者 404：

curl -i http://127.0.0.1:18789/

如果返回HTTP/1.1 404 Not Found，或者 body 长度几乎为 0，基本可以确定是 UI 资源缺失。再进一步确认安装目录里有没有control-ui：

ls -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_modules，Windows 则是%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控制是否对外提供 Dashboard，ui.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-ui：

cd /tmp npm pack openclaw@2026.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 openclaw@2026.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 路径。拿到路径后再请求一次，确认返回 200：

curl -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 用Cmd+Shift+R，Windows/Linux 用Ctrl+Shift+R。还不行就打开开发者工具的 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 用apiKey，OAuth 用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 alias：

alias oc-health='curl -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 和模型调用就都稳了。