Shell / BashAI
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