OpenClaw 常见报错与解决方案

[一、openclaw 安装部署](#一、openclaw 安装部署)
二、常见报错与解决方案
- 2.1 "npm install failed; showing last log lines"
- 2.2 "openclaw: command not found"
- 2.3 "origin not allowed (open the Control UI from the gateway host or allow it in gateway.controlUi.allowedOrigins)"
- 2.4 "disconnected (1008): pairing required"
- 2.5 "control ui requires device identity (use HTTPS or localhost secure context)"
- [2.6 "device identity required"/ "connect failed"](#2.6 "device identity required"/ "connect failed")
- 2.7 "⚠️ Agent failed before reply"
附录：
- SSH隧道连接服务器

一、openclaw 安装部署

详细安装教程，请参考其他作者。本文以安装时遇到的常见报错为主 ，给出对应的解决方案。

详细安装可以参考：OpenClaw 云服务器/虚拟机部署安装教程+常见报错与解决方案（2026最新版，保姆级教程）

macOS / Linux / WSL2 快速部署

bash 复制代码

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

Windows 快速部署

bash 复制代码

iwr -useb https://openclaw.ai/install.ps1 | iex

npm/pnpm 部署

bash 复制代码

pnpm add -g openclaw@latest
pnpm approve-builds -g        # approve openclaw, node-llama-cpp, sharp, etc.
openclaw onboard --install-daemon

源码安装部署

bash 复制代码

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build
pnpm build
pnpm link --global
openclaw onboard --install-daemon

二、常见报错与解决方案

2.1 "npm install failed; showing last log lines"

首次安装可能会出现以下错误：这是由于你的网络不稳定，导致下载失败。多试几次或者开启科学上网。

bash 复制代码

! npm install failed for openclaw@latest
  Command: env SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm --loglevel error --silent --no-fund --no-audit install -g openclaw@latest
  Installer log: /tmp/tmp.Wss3PytzSv
! npm install failed; showing last log lines
! npm install failed; retrying

解决方案：

多试几次或者开启科学上网

2.2 "openclaw: command not found"

使用快速开始安装

在 快速开始 安装过程中，可能会出现丢失环境变量的⚠️警告（"PATH missing npm global bin dir: /home/ubuntu/.npm-global/bin"）,实际上该指令已经安装并且环境变量已经添加到 PATH 环境变量中了，只是当前窗口未识别到。导致的后果就是（"openclaw: command not found"）

bash 复制代码

[3/3] Finalizing setup
! PATH missing npm global bin dir: /home/ubuntu/.npm-global/bin
  This can make openclaw show as "command not found" in new terminals.
  Fix (zsh: ~/.zshrc, bash: ~/.bashrc):
    export PATH="/home/ubuntu/.npm-global/bin:$PATH"

在终端执行以下指令，让配置生效（或者关闭当前窗口，重新连接服务器）：

bash 复制代码

source ~/.bashrc

如果你是使用源码安装

在终端执行以下指令即可解决：

bash 复制代码

pnpm link --global

2.3 "origin not allowed (open the Control UI from the gateway host or allow it in gateway.controlUi.allowedOrigins)"

这是 openclaw 不允许访问原点（需从网关主机打开控制界面，或在 gateway.controlUi.allowedOrigins 中允许该原点）

打开 openclaw 的配置文件： openclaw.json

bash 复制代码

vim .openclaw/openclaw.json

找到 gateway , 修改 bind 的值为： lan , 并且在 bind 下面添加以下内容：

bash 复制代码

"gateway": {
  "bind": "lan",
  "controlUi": {
    "allowedOrigins": [
      "http://localhost:18789",
      "http://127.0.0.1:18789",
      "https://<your-domain.com>"
    ]
  },
}

之后，重启网关即可。

bash 复制代码

openclaw gateway restart

2.4 "disconnected (1008): pairing required"

这是设备配对（首次连接）时的提醒。当你从新浏览器或设备连接到控制 UI 时，Gateway 网关需要一次性配对批准 ，即使你在同一个 Tailnet 上且 gateway.auth.allowTailscale: true。这是防止未授权访问的安全措施。

方法一：批准设备：

bash 复制代码

# 列出待处理的请求
openclaw devices list

# 按请求 ID 批准
openclaw devices approve <requestId>

方法二：关闭设备认证（生产环境不建议关闭）

将 gateway.controlUi.dangerouslyDisableDeviceAuth 设置为 true ，没有就手动添加。

bash 复制代码

"gateway": {
  "bind": "lan",
  "controlUi": {
    "allowedOrigins": [
      "http://localhost:18789",
      "http://127.0.0.1:18789",
      "https://<your-domain.com>"
    ],
    "allowInsecureAuth": true,
    "dangerouslyDisableDeviceAuth": true
  },
}

2.5 "control ui requires device identity (use HTTPS or localhost secure context)"

控制用户界面需要设备身份信息（请使用 HTTPS 或本地主机安全环境）。说明你是直接使用 IP 地址登录的，IP 地址登录是 http 模式，不安全，你可以使用域名或者使用 ssh 隧道连接。

解决方案

方法一：使用域名登录 + nginx 反向代理（推荐）

见文章：三、Nginx 反向代理

方法二：使用 ssh 隧道连接，参数解释见文章附录

bash 复制代码

ssh -N -L 18789:127.0.0.1:18789 ubuntu@<服务器IP地址>

方法三：关闭设备认证（生产环境不建议关闭）

将 gateway.controlUi.dangerouslyDisableDeviceAuth 设置为 true ，没有就手动添加。

bash 复制代码

"gateway": {
  "bind": "lan",
  "controlUi": {
    "allowedOrigins": [
      "http://localhost:18789",
      "http://127.0.0.1:18789",
      "https://<your-domain.com>"
    ],
    "dangerouslyDisableDeviceAuth": true
  },
}

2.6 "device identity required"/ "connect failed"

如果你通过纯 HTTP 打开仪表板（例如 http://<lan-ip>:18789/ 或 http://<tailscale-ip>:18789/），浏览器运行在非安全上下文中，会阻止 WebCrypto，因此无法生成设备身份。

换句话说，就是你使用IP进行访问（默认是http协议），他认为不安全，在网络层直接给你拦截了，所以你无法访问。

方法一： 使用域名访问

具体操作，见文章 三、Nginx 反向代理 。

方法二： 使用SSH连接，临时测试。（小白推荐）

bash 复制代码

# 打开仪表盘
openclaw dashboard

输出示例：

提取信息：

bash 复制代码

# ============================ 提取信息 =========================================
# 这一行是使用ssh连接你的云服务器，并做端口转发。类似于nginx的反向代理。具体参数可查看文章附录
ssh -N -L 18789:127.0.0.1:18789 ubuntu@<这里修改为你的云服务器IP地址>

# 这一行无需修改。通过ssh连接到服务器后，直接粘贴至浏览器即可打开
http://localhost:18789/#token=3fd4fd42abf4298f700ce5d27992bc68b4c140b62aa4951e
# ==============================================================================

步骤：

打开cmd, 使用ssh 连接云服务器。

bash 复制代码

ssh -N -L 18789:127.0.0.1:18789 ubuntu@<这里修改为你的云服务器IP地址>

如果你之前连接过，那么这一步你可能会报错，如果出现错误，执行以下指令，删除 known_hosts 中主机名[你自己的主机IP] 的密钥记录。然后重新输入上述指令，再次连接。（无报错，此步跳过）
bash 复制代码
```
ssh-keygen -R <这里修改为你的云服务器IP地址>
ssh -N -L 18789:127.0.0.1:18789 ubuntu@<这里修改为你的云服务器IP地址>
```

在浏览器输入访问地址

bash 复制代码

http://localhost:18789/#token=3fd4fd42abf4298f700ce5d27992bc68b4c140b62aa4951e

输出示例：

2.7 "⚠️ Agent failed before reply"

错误输出完整版：

⚠️ Agent failed before reply: OAuth token refresh failed for qwen-portal: Qwen OAuth refresh token expired or invalid. Re-authenticate with openclaw models auth login --provider qwen-portal... Please try again or re-authenticate.

Logs: openclaw logs --follow

这个错误信息表示 通义千问（Qwen）的登录凭证已过期，导致智能助手无法正常工作。你需要重新登录验证，根据据报错提示，在终端中执行以下命令：

bash 复制代码

openclaw models auth login --provider qwen-portal

附录：

SSH隧道连接服务器

指令示例：

bash 复制代码

# ssh -N -L 18789:127.0.0.1:18789 ubuntu@<服务器IP地址>
ssh -N -L 18789:127.0.0.1:18789 ubuntu@123.45.67.89

参数说明：

部分	含义
`ssh`	基础的 SSH 远程连接命令
`-N`	仅建立连接，不执行远程命令、不打开终端（端口转发专用，节省资源）------这个参数专门为「端口转发（隧道）」场景设计，因为端口转发只需要建立连接通道，不需要操作服务器。
`-L`	Local（本地）端口转发的标识，是核心参数
`18789:localhost:18789`	转发规则：`本地端口:目标主机:目标端口` - 前一个 18789：你本地电脑的端口 - localhost（127.0.0.1）：相对「服务器」而言的本机（即 123.45.67.89 自身） - 后一个 18789：服务器上运行服务的端口
`ubuntu@123.45.67.89`	登录服务器的用户名（ubuntu）+ 服务器 IP（123.45.67.89）

如果出现错误，执行以下指令，删除 known_hosts 中主机名[你自己的主机IP] 的密钥记录。然后重新执行上述指令进行连接。

bash 复制代码

# ssh-keygen -R <服务器IP地址>
ssh-keygen -R 123.45.67.89

END

你好，少年，未来可期~