OpenClaw 树莓派部署：Gateway 仪表盘登录与网络配置排查

找到 controlUi 部分，添加树莓派的访问地址：

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

重启服务：

sudo openclaw gateway restart

跨域报错消失后，页面可能会提示新的错误。

第三关：安全上下文限制（必须启用 HTTPS）

现象描述

跨域问题解决后，页面弹出红色警告或无法建立 WebSocket 连接，提示：

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

或者浏览器控制台报错：WebSocket connection failed: Mixed Content / Secure Context required。

原因分析

现代浏览器（Chrome, Edge, Safari 等）出于安全考虑，禁止在非安全上下文（即非 HTTPS 且非 localhost）中使用某些敏感 API（如麦克风、摄像头、剪贴板，以及 OpenClaw 所需的某些身份验证机制）。由于您是通过局域网 IP (http://192.168.x.x) 访问，不属于 localhost，因此必须启用 HTTPS。

解决方案：生成自签名证书并启用 HTTPS

1. 生成自签名证书

在树莓派上运行以下命令（注意国家代码必须是 2 位，Common Name 必须是您的 IP）：

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"

(请将 CN=192.168.5.5 替换为您的实际 IP)

2. 配置 Gateway 使用证书

编辑配置文件，启用 SSL 并指向证书路径：

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

3. 重启服务并信任证书

sudo openclaw gateway restart

注意：浏览器会提示'连接不安全'，因为是自签名证书。请点击'高级' -> '继续访问'即可。此时，访问地址变为 https://:18789。安全上下文问题解决，但你会遇到最后一个关卡：配对。

第四关：Pairing Required（设备身份验证）

现象描述

一切配置就绪，HTTPS 也通了，但页面显示：

disconnected (1008): pairing required 或者 Pairing required

原因分析

这是 OpenClaw 的零信任安全机制。即使通过了 HTTPS 验证，网关仍不认识这台浏览器设备。首次连接必须经过管理员显式批准，防止未授权控制。

解决方案：命令行审批法

这是最标准、最安全的解决方式。

1. 查看待审批设备

保持浏览器页面打开（触发请求），在终端执行：

openclaw devices list

输出示例：

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

2. 批准设备

复制 Request ID 并执行：

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

看到 ✓ Approved 后，刷新浏览器页面，即可正常进入控制界面！

总结：完整配置清单

为了方便大家对照检查，以下是解决所有问题后的 openclaw.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": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    },
    "tailscale": {
      "mode": "off",
      "resetOnExit": false
    }
  }
}

排错路线图

1. 连不上？查 host: 0.0.0.0
2. 跨域报错？查 allowedOrigins
3. 安全上下文报错？配置 TLS/HTTPS
4. 配对报错？运行 openclaw devices approve

希望这篇完整的指南能帮您少走弯路，顺利搭建属于自己的 AI 机器人网关。