树莓派跑 OpenClaw 网关仪表盘全链路排坑｜局域网访问 / 跨域 / HTTPS 安全校验 / 设备配对四大卡死问题一站式落地根治方案

前言

市面上绝大多数 OpenClaw 部署教程只讲树莓派基础安装、环境依赖配置，完全没有覆盖网关仪表盘远程登录的连锁故障。

不少玩家把服务正常启动后，接连撞上四层连环壁垒：局域网 IP 无法连通、浏览器跨域拦截 WebSocket、安全上下文强制要求 HTTPS、最后设备配对校验阻断登录。

我基于树莓派 4B/5B 实测完整复现整套故障链路，按访问流程顺序拆解每一层报错底层诱因，配套可直接复制的配置、命令、证书生成脚本，一次性解决全部登录障碍，x86 服务器部署通用这套排错逻辑。

第一关：网关端口仅本地监听，局域网设备无法访问面板

故障现象

树莓派终端执行openclaw gateway start，日志正常输出监听 18789 端口；同局域网电脑、手机浏览器输入http://树莓派IP:18789，页面超时、拒绝连接，完全无法入网。

底层根源

OpenClaw 网关默认监听地址为127.0.0.1本地回环地址，仅允许树莓派本机程序访问 18789 端口，局域网其他设备网卡流量会被直接拦截，这是嵌入式设备部署最容易忽略的底层绑定规则。

落地修复操作

编辑全局配置文件

bash

运行

sudo vi ~/.openclaw/openclaw.json

修改 gateway 绑定模式，切换为局域网全网卡监听

json

"gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "lan"
}

重载网关服务生效

bash

运行

sudo openclaw gateway restart

校验标准

再次使用局域网 IP 访问，页面不再提示连接超时，能加载出空白页面或跨域报错，代表网络链路彻底打通。

第二关：CORS 跨域拦截，控制面板功能完全失效

故障现象

浏览器成功加载页面框架，控制台抛出核心报错：

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

页面按钮、会话列表、指令发送全部失效，WebSocket 握手直接中断。

底层根源

浏览器同源安全策略限制跨 IP 前端请求；OpenClaw 控制面板默认仅放行本机localhost来源，未把局域网 HTTPS/HTTP 访问地址加入信任白名单，前端接口请求被浏览器拦截。

落地修复操作

再次打开配置文件，补充信任访问源列表，填入自己树莓派局域网 IP

json

"controlUi": {
    "allowedOrigins": [
        "http://localhost:18789",
        "http://127.0.0.1:18789",
        "https://192.168.5.5:18789"
    ]
}

替换192.168.5.5为你的树莓派实际内网 IP，多设备访问可追加多条 IP 记录

重启网关服务

bash

运行

sudo openclaw gateway restart

校验标准

跨域报错消失，页面正常渲染，但会弹出安全上下文相关红色告警，进入下一层校验。

第三关：非 HTTPS 无安全上下文，WebSocket 连接持续失败

故障现象

页面完整展示，控制台红色警告，WebSocket 反复断开重连，提示关键信息：

Control UI requires device identity (use HTTPS or localhost secure context)

浏览器日志附带：Mixed Content、Secure Context required 混合内容报错。

底层根源

Chrome、Edge、Safari 等现代浏览器强制安全规则：非localhost的内网 IP 明文 HTTP 地址不属于安全上下文，禁止调用设备身份校验、长连接 WebSocket 等敏感接口，OpenClaw 仪表盘身份验证依赖该机制，必须配置 TLS 证书启用 HTTPS。

全套落地修复步骤

bash

运行

mkdir -p ~/.openclaw/certs

一键生成自签名 SSL 证书（复制整条命令，修改 CN 后的内网 IP）

bash

运行

openssl req -x509 -newkey rsa:4096 \
  -keyout ~/.openclaw/certs/key.pem \
  -out ~/.openclaw/certs/cert.pem \
  -days 365 -nodes \
  -subj "/C=CN/ST=Beijing/L=Haidian/O=HomeLab/CN=192.168.5.5"

C=CN 固定两位国家代码
CN = 后替换为树莓派局域网 IP

配置文件开启 TLS 加密，填入证书绝对路径

json

"tls": {
    "enabled": true,
    "certFile": "/home/pi/.openclaw/certs/cert.pem",
    "keyFile": "/home/pi/.openclaw/certs/key.pem"
}

重启网关，切换 HTTPS 地址访问

bash

运行

sudo openclaw gateway restart

访问地址改为：https://树莓派IP:18789

浏览器提示不安全属于自签名证书正常现象，点击高级→继续访问即可跳过警告。

校验标准

安全上下文告警消失，长连接正常建立，仅剩设备配对校验拦截。

第四关：设备配对校验阻断，页面提示 disconnected pairing required

故障现象

HTTPS、跨域、端口全部正常，页面顶部提示断开连接：disconnected (1008): pairing required，无法进入管理界面操作 Agent。

底层根源

OpenClaw 内置零信任安全配对机制，陌生浏览器设备首次连接网关，必须管理员手动审批设备请求，防止局域网内未授权设备操控 AI 代理网关，属于主动安全防护策略。

标准安全落地审批流程

保持浏览器页面处于打开状态（持续发起配对请求），树莓派终端执行设备列表查询

bash

运行

openclaw devices list

输出示例：

plaintext

┌──────────────────────────────────────┬──────────────┬─────────────────────┐
│ Request ID                           │ Role         │ Created At          │
├──────────────────────────────────────┼──────────────┼─────────────────────┤
│ 4f9db1bd-a1cc-4d3f-b643-2c195262464e │ browser      │ 2026-03-10 22:22:01 │
└──────────────────────────────────────┴──────────────┴─────────────────────┘

复制 Request ID，执行设备审批命令

bash

运行

openclaw devices approve 4f9db1bd-a1cc-4d3f-b643-2c195262464e

终端出现✓ Approved即代表审批完成，刷新浏览器页面，完整解锁仪表盘全部功能。

修复完成后完整 openclaw.json 网关标准配置（树莓派专用，直接复制修改 IP 即可）

json

"gateway": {
     "port": 18789,
     "mode": "local",
     "bind": "lan",
     "tls": {
         "enabled": true,
         "certFile": "/home/pi/.openclaw/certs/cert.pem",
         "keyFile": "/home/pi/.openclaw/certs/key.pem"
     },
     "controlUi": {
       "allowedOrigins": [
         "http://localhost:18789",
         "http://127.0.0.1:18789",
         "https://192.168.5.5:18789"
       ]
     },
     "auth": {
       "mode": "token",
       "token": "自定义高强度安全密钥"
     },
     "tailscale": {
       "mode": "off",
       "resetOnExit": false
     }
}

极简排错速查路线图（快速定位故障层级）

浏览器无法连接页面 → 检查 bind 配置是否为 lan、监听 0.0.0.0
页面打开但接口报错跨域 → 补全 controlUi.allowedOrigins 内网 HTTPS 地址
WebSocket 频繁断开、提示安全上下文 → 生成自签名证书开启 tls 加密
HTTPS 正常但提示配对必填 → 终端查询并审批浏览器设备

补充说明

整套排错逻辑不局限树莓派 ARM 嵌入式设备，x86 云服务器、本地 Windows/Linux 主机部署 OpenClaw 网关仪表盘，出现相同四类报错均可直接套用本文配置与命令，仅证书文件路径、系统用户名按需微调即可。