OpenClaw 树莓派部署:解决 Gateway 仪表盘登录问题
本文介绍在树莓派上部署 OpenClaw Gateway 时遇到的四个核心问题及解决方案。首先解决局域网端口监听问题,将 bind 模式改为 lan;其次配置跨域白名单 allowedOrigins;第三启用 HTTPS 安全上下文并生成自签名证书;最后通过命令行审批设备配对请求。完成上述配置后,即可正常访问控制界面。

本文介绍在树莓派上部署 OpenClaw Gateway 时遇到的四个核心问题及解决方案。首先解决局域网端口监听问题,将 bind 模式改为 lan;其次配置跨域白名单 allowedOrigins;第三启用 HTTPS 安全上下文并生成自签名证书;最后通过命令行审批设备配对请求。完成上述配置后,即可正常访问控制界面。

在树莓派上部署 OpenClaw 时,很多开发者会遭遇一连串的拦路虎:从局域网无法访问,到跨域报错,再到 HTTPS 安全上下文限制,最后是设备配对验证。
本文完整复盘了四个核心问题及其解决方案,按发生顺序排列,助您一次性打通所有关卡,顺利运行 AI 代理网关。
树莓派上的 OpenClaw Gateway 服务已启动,日志显示正常监听 18789 端口。但在同一局域网的其他电脑浏览器中输入 http://<树莓派 IP>:18789,却显示无法连接或连接超时。
默认情况下,某些服务可能只绑定在 localhost (127.0.0.1) 上,这意味着它只接受来自树莓派内部的请求,拒绝外部局域网设备的访问。
需要修改网关配置文件,将其监听地址改为 0.0.0.0(允许所有网卡接口访问)。
保存并重启服务:
sudo openclaw gateway restart
找到 gateway 的 bind 部分,修改 bind 模式为 lan:
"gateway": {"port": 18789, "mode": "local", "bind": "lan"}
编辑配置文件(通常位于 ~/.openclaw/openclaw.json):
sudo vi ~/.openclaw/openclaw.json
网页能打开了,但会话界面显示错误信息,页面功能异常,提示类似:
origin not allowed (open the Control UI from the gateway host or allow it in gateway.controlUi.allowedOrigins)
浏览器的同源策略 (Same-Origin Policy) 阻止了网页向不同源(即使只是 IP 不同)发起请求。OpenClaw 默认可能只允许特定的域名访问,或者未配置允许的 Origin 列表。
在配置文件中明确添加您的局域网 IP 或允许所有来源(测试环境)。
重启服务:
sudo openclaw gateway restart
找到 controlUi 的 allowedOrigins 部分,添加树莓派的访问地址:
"controlUi": {"allowedOrigins": ["http://localhost:18789", "http://127.0.0.1:18789", "https://192.168.5.5:18789"]}
再次编辑配置文件:
sudo vi ~/.openclaw/openclaw.json
跨域问题解决后,页面弹出红色警告或无法建立 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。
在树莓派上运行以下命令(注意国家代码必须是 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)
编辑配置文件,启用 SSL 并指向证书路径:
"tls": {
"enabled": true,
"certFile": "/home/pi/.openclaw/certs/cert.pem",
"keyFile": "/home/pi/.openclaw/certs/key.pem"
}
sudo openclaw gateway restart
注意:浏览器会提示'连接不安全',因为是自签名证书。请点击'高级' -> '继续访问'即可。
此时,访问地址变为 https://:18789。安全上下文问题解决,但你会遇到最后一个关卡:配对。
一切配置就绪,HTTPS 也通了,但页面显示:
disconnected (1008): pairing required
或者
Pairing required

这是 OpenClaw 的零信任安全机制。即使通过了 HTTPS 验证,网关仍不认识这台浏览器设备。首次连接必须经过管理员显式批准,防止未授权控制。
这是最标准、最安全的解决方式。
保持浏览器页面打开(触发请求),在终端执行:
openclaw devices list
输出示例:
┌──────────────────────────────────────┬──────────────┬─────────────────────┐
│ Request ID │ Role │ Created At │
├──────────────────────────────────────┼──────────────┼─────────────────────┤
│ 4f9db1bd-a1cc-4d3f-b643-2c195262464e │ browser │ 2026-03-10 22:22:01 │
└──────────────────────────────────────┴──────────────┴─────────────────────┘
复制 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"

微信公众号「极客日志」,在微信中扫描左侧二维码关注。展示文案:极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具,RSA密钥对生成器在线工具,online
基于 Mermaid.js 实时预览流程图、时序图等图表,支持源码编辑与即时渲染。 在线工具,Mermaid 预览与可视化编辑在线工具,online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具,Base64 字符串编码/解码在线工具,online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具,Base64 文件转换器在线工具,online
将 Markdown(GFM)转为 HTML 片段,浏览器内 marked 解析;与 HTML 转 Markdown 互为补充。 在线工具,Markdown 转 HTML在线工具,online
将 HTML 片段转为 GitHub Flavored Markdown,支持标题、列表、链接、代码块与表格等;浏览器内处理,可链接预填。 在线工具,HTML 转 Markdown在线工具,online