OpenClaw 树莓派部署终极避坑指南：解决OpenClaw Gateway仪表盘登录问题

🚀 OpenClaw 树莓派部署终极避坑指南：解决OpenClaw Gateway仪表盘登录问题

在树莓派上部署 OpenClaw 时，很多开发者会遭遇一连串的“拦路虎”：从局域网无法访问，到跨域报错，再到 HTTPS 安全上下文限制，最后是设备配对验证。

本文完整复盘了我遇到的四个核心问题及其解决方案，按发生顺序排列，助您一次性打通所有关卡，顺利运行 AI 代理网关。

在其他类型系统上的解决方案基本一致

📋 目录

1. 第一关：局域网无法访问 (端口监听问题)
2. 第二关：跨域错误 CORS (白名单配置)
3. 第三关：安全上下文限制 (必须启用 HTTPS)
4. 第四关：Pairing Required (设备身份验证)
5. 总结：完整配置清单

🔌 第一关：局域网无法访问 (端口监听问题)

❌ 现象描述

树莓派上的 OpenClaw Gateway 服务已启动，日志显示正常监听 18789 端口。但在同一局域网的其他电脑浏览器中输入 http://<树莓派IP>:18789，却显示无法连接或连接超时。

💡 原因分析

默认情况下，某些服务可能只绑定在 localhost (127.0.0.1) 上，这意味着它只接受来自树莓派内部的请求，拒绝外部局域网设备的访问。

✅ 解决方案：修改 Bind 模式

需要修改网关配置文件，将其监听地址改为 0.0.0.0（允许所有网卡接口访问）。

1. 验证：现在应该可以在局域网其他设备上通过 http://<IP>:18789 访问了（虽然接下来可能会报跨域错误，但这证明网络通了）。

保存并重启服务：

sudo openclaw gateway restart 

找到 gateway 的 bind 部分，修改 bind 模式为 lan：

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

编辑配置文件（通常位于 ~/.openclaw/openclaw.json）：

sudovi ~/.openclaw/openclaw.json 

🌐 第二关：跨域错误 CORS (白名单配置)

❌ 现象描述

网页能打开了，但会话界面显示错误信息，页面功能异常，提示类似：

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

中文翻译：

`“来源不被允许（请从网关主机打开控制界面，或在 gateway.controlUi.allowedOrigins 配置项中允许该来源）”``

💡 原因分析

浏览器的同源策略 (Same-Origin Policy) 阻止了网页向不同源（即使只是 IP 不同）发起请求。OpenClaw 默认可能只允许特定的域名访问，或者未配置允许的 Origin 列表。

✅ 解决方案：配置 Gateway 白名单

在配置文件中明确添加您的局域网 IP 或允许所有来源（测试环境）。

1. 结果：跨域报错消失，但页面可能会提示新的错误：

重启服务：

sudo openclaw gateway restart 

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

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

再次编辑配置文件：

sudovi ~/.openclaw/openclaw.json 

🔒 第三关：安全上下文限制 (必须启用 HTTPS)

❌ 现象描述

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

Control UI requires device identity (use HTTPS or localhost secure context)
中文翻译
控制界面需要设备身份验证（请使用 HTTPS 或 localhost 安全上下文）

或者浏览器控制台报错：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 \-days365-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:truecertFile:"/home/pi/.openclaw/certs/cert.pem"keyFile:"/home/pi/.openclaw/certs/key.pem"

3. 重启服务并信任证书

sudo openclaw gateway restart 

注意：浏览器会提示“连接不安全”，因为是自签名证书。请点击“高级” -> “继续访问”即可。

此时，访问地址变为 https://<IP>: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 机器人网关！如有其他问题，欢迎评论区交流。