OpenClaw 安装报错完全解决手册（2026）：missing control ui assets / spawn einval / brew not installed

本文专门解决安装和启动 OpenClaw 时遇到的常见报错。如果你在找部署教程，请看：宿主机直装 vs Docker 或 1Panel Docker 版教程。

先跑这一条（解决 80% 的问题）

遇到任何问题，第一步永远是：

openclaw doctor --fix

它会自动检测并修复大部分环境问题。修复后重启：

openclaw gateway restart

如果还有问题，再对照下面的报错手册逐一排查。

报错一：Missing Control UI assets. Build them with pnpm ui:build

出现场景：宿主机直装，或自定义构建 Docker 镜像时。

原因：安装脚本下载了 OpenClaw 但跳过了前端 UI 构建步骤（需要 pnpm）。

解决方法：

# 第一步：确认 pnpm 是否安装
which pnpm

# 如果没有（Debian/Ubuntu）
apt update && apt install -y nodejs npm
npm install -g pnpm

# 第二步：进入 OpenClaw 目录执行构建
# 位置通常是 ~/.openclaw 或 /root/.openclaw
cd ~/.openclaw
pnpm ui:build

# 第三步：重启
openclaw gateway restart

验证是否解决：

openclaw status
# Gateway 一行应显示 running，不再报 UI 相关错误

⚠️ 如果用的是官方预编译 Docker 镜像（openclaw/openclaw:latest），不会出现此报错，无需处理。

报错二：openclaw: command not found

原因：安装成功但 openclaw 可执行文件不在 $PATH 里。

解决方法：

# 找到 openclaw 安装在哪里
find /usr /root /home -name "openclaw" -type f 2>/dev/null | head -5

# 常见位置
ls ~/.local/bin/openclaw
ls /usr/local/bin/openclaw

# 临时修复（立刻生效）
export PATH="$HOME/.local/bin:$PATH"

# 永久修复
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# 验证
which openclaw
openclaw --version

如果找不到 openclaw 文件，说明安装未完成，重新安装：

curl -fsSL https://openclaw.ai/install.sh | bash

报错三：[openclaw] failed to start cli: error: spawn einval 或 spawn npm ENOENT

原因：Node.js 未安装，或版本低于 18（OpenClaw 需要 Node.js 18+）。

解决方法：

# 查看当前版本
node --version

# 版本低于 18 或没有安装，用 nvm 安装
curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.bashrc
nvm install --lts
nvm use --lts

node --version  # 应输出 v20.x.x 或更高

# 重新安装 openclaw
curl -fsSL https://openclaw.ai/install.sh | bash

Debian/Ubuntu apt 方式（不想用 nvm）：

curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
apt install -y nodejs
node --version

报错四：skill "model-usage" missing brew formula 或 brew not installed

重要提示：这不是致命报错，OpenClaw 主程序可以正常运行。

原因：部分 Skills 依赖 Homebrew（brew），Linux 默认没有。

三种处理方式：

方式 A（推荐新手）：直接忽略，先用起来

这个报错不影响 Telegram/Discord 聊天、模型调用、基础命令执行。等真正需要用到那个 Skill 时再处理。

方式 B：查看哪些 Skill 可用，哪些需要 brew

openclaw doctor
# 输出里会列出：
# Skills status
#   Eligible: 3        ← 这些可以直接用
#   Missing requirements: 46   ← 这些缺依赖

方式 C：安装 Homebrew for Linux（真的需要那个 Skill）

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装完把 brew 加入 PATH
echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> ~/.bashrc
source ~/.bashrc

brew --version  # 验证

报错五：gateway did not become ready

原因：端口被占用、Node.js 进程崩溃，或网络配置问题。

排查步骤：

# 第一步：看详细日志
openclaw logs --follow

# 或者看 systemd 日志（宿主机安装）
journalctl --user -u openclaw-gateway -n 50 --no-pager

# 第二步：检查 18789 端口是否被其他进程占用
ss -tlnp | grep 18789

# 如果有其他进程占用，找到它并停掉
# 第三步：强制启动
openclaw gateway start --force

# 还不行就让 doctor 修复
openclaw doctor --fix
openclaw gateway restart

报错六：openclaw disconnected (1006): no reason

原因：WebSocket 连接断开，常见于网络不稳定或 Gateway 崩溃后重启。

解决方法：

# 重启 Gateway
openclaw gateway restart

# 如果频繁出现，配置 systemd 自动重启
systemctl --user edit openclaw-gateway

在编辑器中加入：

[Service]
Restart=always
RestartSec=10

报错七：spawn tailscale ENOENT

原因：配置里有 Tailscale 相关设置，但服务器没装 Tailscale。

解决方法：

# 方式 A：安装 Tailscale
curl -fsSL https://tailscale.com/install.sh | sh

# 方式 B：不用 Tailscale，从配置里移除
openclaw config unset gateway.tailscale
openclaw gateway restart

报错八：Control UI 打开显示 502 或白屏

排查顺序：

# 1. 检查 Gateway 是否在跑
openclaw status

# 2. 检查端口响应
curl http://127.0.0.1:18789/

# 3. 端口没响应 → 重启 Gateway
openclaw gateway restart

# 4. 端口有响应但白屏 → UI 资源问题，参考报错一的解决方法

报错九：[openclaw] failed to start cli: error: spawn npm ENOENT

和报错三同因。OpenClaw 找不到 npm，通常是 Node.js 未安装或 PATH 不对。

# 确认 npm 位置
which npm

# 如果 npm 安装了但找不到，修复 PATH
export PATH="/usr/local/bin:$HOME/.local/bin:$PATH"
echo 'export PATH="/usr/local/bin:$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

1Panel OpenClaw Docker 部署更新版（2026）

原有教程（1Panel 安装 Moltbot Docker 版）基于旧版 Moltbot，以下是更名为 OpenClaw 后的更新流程。

操作步骤

第一步：1Panel → 应用商店 → 搜索 openclaw 或 moltbot → 安装

第二步：进入已安装应用 → 找到容器 → 点击进入安装目录，打开终端执行初始化：

# 新版 OpenClaw 的初始化命令（替换了旧版的 moltbot-cli）
docker exec -it openclaw openclaw onboard

第三步：编辑配置文件，允许非 HTTPS 访问控制台（内网环境）

找到 openclaw.json（通常在 data/conf/ 目录），添加：

{
  "gateway": {
    "controlUi": {
      "allowInsecureAuth": true
    }
  }
}

第四步：获取访问 Token

在同一个 openclaw.json 中找到：

"gateway": {
  "auth": {
    "mode": "token",
    "token": "你的token"
  }
}

第五步：重建容器后访问

1Panel → 已安装应用 → OpenClaw → 重建

浏览器访问：http://你的IP:端口?token=你的token

新旧版本差异对照

常见坑（更新版）

坑 1：Google Gemini API 地区限制

韩国/部分亚洲 VPS 仍然可能遇到 User location is not supported。

解决：换 OpenAI / Anthropic API，或配合 CLIProxyAPI 转发绕过地区限制（参考CLIProxyAPI 教程）。

坑 2：Telegram 初始化卡住

初始化时 Telegram 授权不了，换 WhatsApp 或 Discord 先跑通，再让 AI 帮你配置 Telegram：

帮我配置 Telegram 渠道，Token 是 xxx

坑 3：missing control ui assets 在 Docker 里

官方镜像已预编译 UI，如果出现此报错说明用的是非官方镜像或自建镜像，执行：

docker exec -it openclaw pnpm ui:build
docker compose restart

快速诊断流程

出问题了？
     ↓
openclaw status          → 看 Gateway 和渠道是否正常
     ↓（有问题）
openclaw doctor --fix    → 自动修复
     ↓（还有问题）
openclaw logs --follow   → 看实时报错
     ↓（对照本文查报错）
还没解决 → Discord 社区：https://discord.com/invite/clawd

相关文章

• 重新开始安装 OpenClaw：宿主机直装 vs Docker
• 1Panel 安装 Moltbot（原Clawdbot）Docker 版完整教程（旧版参考）
• OpenClaw CLI 命令完全指南
• CLIProxyAPI：解决 Gemini/Claude 地区限制