OpenClaw 樹莓派部署終極避坑指南之快速解決OpenClaw Gateway儀表盤登錄問題
我要評論?? OpenClaw 樹莓派部署終極避坑指南：解決OpenClaw Gateway儀表盤登錄問題
在樹莓派上部署 OpenClaw 時(shí)，很多開發(fā)者會遭遇一連串的“攔路虎”：從局域網(wǎng)無法訪問，到跨域報(bào)錯(cuò)，再到 HTTPS 安全上下文限制，最后是設(shè)備配對驗(yàn)證。
本文完整復(fù)盤了我遇到的四個(gè)核心問題及其解決方案，按發(fā)生順序排列，助您一次性打通所有關(guān)卡，順利運(yùn)行 AI 代理網(wǎng)關(guān)。
在其他類型系統(tǒng)上的解決方案基本一致
?? 第一關(guān)：局域網(wǎng)無法訪問 (端口監(jiān)聽問題)
? 現(xiàn)象描述
樹莓派上的 OpenClaw Gateway 服務(wù)已啟動(dòng)，日志顯示正常監(jiān)聽 18789 端口。但在同一局域網(wǎng)的其他電腦瀏覽器中輸入 http://<樹莓派IP>:18789，卻顯示無法連接或連接超時(shí)。
?? 原因分析
默認(rèn)情況下，某些服務(wù)可能只綁定在 localhost (127.0.0.1) 上，這意味著它只接受來自樹莓派內(nèi)部的請求，拒絕外部局域網(wǎng)設(shè)備的訪問。
? 解決方案：修改 Bind 模式
需要修改網(wǎng)關(guān)配置文件，將其監(jiān)聽地址改為 0.0.0.0（允許所有網(wǎng)卡接口訪問）。
- 編輯配置文件（通常位于
~/.openclaw/openclaw.json）：sudo vi ~/.openclaw/openclaw.json
- 找到
gateway的bind部分，修改bind模式為lan："gateway": { "port": 18789, "mode": "local", "bind": "lan", - 保存并重啟服務(wù)：
sudo openclaw gateway restart
- 驗(yàn)證：現(xiàn)在應(yīng)該可以在局域網(wǎng)其他設(shè)備上通過
http://<IP>:18789訪問了（雖然接下來可能會報(bào)跨域錯(cuò)誤，但這證明網(wǎng)絡(luò)通了）。
?? 第二關(guān)：跨域錯(cuò)誤 CORS (白名單配置)
? 現(xiàn)象描述
網(wǎng)頁能打開了，但會話界面顯示錯(cuò)誤信息，頁面功能異常，提示類似：
`origin not allowed (open the Control UI from the gateway host or allow it in gateway.controlUi.allowedOrigins)
中文翻譯：
`“來源不被允許（請從網(wǎng)關(guān)主機(jī)打開控制界面，或在 gateway.controlUi.allowedOrigins 配置項(xiàng)中允許該來源）”``
?? 原因分析
瀏覽器的同源策略 (Same-Origin Policy) 阻止了網(wǎng)頁向不同源（即使只是 IP 不同）發(fā)起請求。OpenClaw 默認(rèn)可能只允許特定的域名訪問，或者未配置允許的 Origin 列表。
? 解決方案：配置 Gateway 白名單
在配置文件中明確添加您的局域網(wǎng) IP 或允許所有來源（測試環(huán)境）。
- 再次編輯配置文件：
sudo vi ~/.openclaw/openclaw.json
- 找到
gateway的allowedOrigins部分，添加樹莓派的訪問地址："controlUi": { "allowedOrigins": [ "http://localhost:18789", "http://127.0.0.1:18789", "https://192.168.5.5:18789" ] }, - 重啟服務(wù)：
sudo openclaw gateway restart
- 結(jié)果：跨域報(bào)錯(cuò)消失，但頁面可能會提示新的錯(cuò)誤：
?? 第三關(guān)：安全上下文限制 (必須啟用 HTTPS)
? 現(xiàn)象描述
跨域問題解決后，頁面彈出紅色警告或無法建立 WebSocket 連接，提示：
Control UI requires device identity (use HTTPS or localhost secure context)中文翻譯控制界面需要設(shè)備身份驗(yàn)證（請使用 HTTPS 或 localhost 安全上下文）
或者瀏覽器控制臺報(bào)錯(cuò)：
WebSocket connection failed: Mixed Content/Secure Context required
?? 原因分析
現(xiàn)代瀏覽器（Chrome, Edge, Safari 等）出于安全考慮，禁止在非安全上下文（即非 HTTPS 且非 localhost）中使用某些敏感 API（如麥克風(fēng)、攝像頭、剪貼板，以及 OpenClaw 所需的某些身份驗(yàn)證機(jī)制）。
由于您是通過局域網(wǎng) IP (http://192.168.x.x) 訪問，不屬于 localhost，因此必須啟用 HTTPS。
? 解決方案：生成自簽名證書并啟用 HTTPS
1. 生成自簽名證書
在樹莓派上運(yùn)行以下命令（注意國家代碼必須是 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 替換為您的實(shí)際 IP)
2. 配置 Gateway 使用證書
編輯配置文件，啟用 SSL 并指向證書路徑：
server:
tls:
enabled: true
certFile: "/home/pi/.openclaw/certs/cert.pem"
keyFile: "/home/pi/.openclaw/certs/key.pem"3. 重啟服務(wù)并信任證書
sudo openclaw gateway restart
注意：瀏覽器會提示“連接不安全”，因?yàn)槭亲院灻C書。請點(diǎn)擊“高級” -> “繼續(xù)訪問”即可。
此時(shí)，訪問地址變?yōu)?https://<IP>:18789。安全上下文問題解決，但你會遇到最后一個(gè)關(guān)卡：配對。
?? 第四關(guān)：Pairing Required (設(shè)備身份驗(yàn)證)
? 現(xiàn)象描述
一切配置就緒，HTTPS 也通了，但頁面顯示：
disconnected (1008): pairing required
或者Pairing required
?? 原因分析
這是 OpenClaw 的零信任安全機(jī)制。即使通過了 HTTPS 驗(yàn)證，網(wǎng)關(guān)仍不認(rèn)識這臺瀏覽器設(shè)備。首次連接必須經(jīng)過管理員顯式批準(zhǔn)，防止未授權(quán)控制。
? 解決方案：命令行審批法
這是最標(biāo)準(zhǔn)、最安全的解決方式。
1. 查看待審批設(shè)備
保持瀏覽器頁面打開（觸發(fā)請求），在終端執(zhí)行：
openclaw devices list
輸出示例：
┌──────────────────────────────────────┬──────────────┬─────────────────────┐ │ Request ID │ Role │ Created At │ ├──────────────────────────────────────┼──────────────┼─────────────────────┤ │ 4f9db1bd-a1cc-4d3f-b643-2c195262464e │ browser │ 2026-03-10 22:22:01 │ └──────────────────────────────────────┴──────────────┴─────────────────────┘
2. 批準(zhǔn)設(shè)備
復(fù)制 Request ID 并執(zhí)行：
openclaw devices approve 4f9db1bd-a1cc-4d3f-b643-2c195262464e
看到 ? Approved 后，刷新瀏覽器頁面，即可正常進(jìn)入控制界面！??
?? 總結(jié)：完整配置清單
為了方便大家對照檢查，以下是解決所有問題后的 openclaw.json 核心配置參考：
"gateway": {
"port": 18789,
"mode": "local",
"bind": "lan",
"tls": {
"enabled": true,
"certFile": "/home/pi/.openclaw/certs/cert.pem", // 路徑根據(jù)實(shí)際情況修改
"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
}
},??? 排錯(cuò)路線圖
- 連不上？ ?? 查
host: 0.0.0.0 - 跨域報(bào)錯(cuò)？ ?? 查
allowedOrigins - 安全上下文報(bào)錯(cuò)？ ?? 配置
TLS/HTTPS - 配對報(bào)錯(cuò)？ ?? 運(yùn)行
openclaw devices approve
希望這篇完整的指南能幫您少走彎路，順利搭建屬于自己的 AI 機(jī)器人網(wǎng)關(guān)！如有其他問題，歡迎評論區(qū)交流。
到此這篇關(guān)于OpenClaw 樹莓派部署終極避坑指南之快速解決OpenClaw Gateway儀表盤登錄問題的文章就介紹到這了,更多相關(guān)OpenClaw 樹莓派部署內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章，希望大家以后多多支持腳本之家！
相關(guān)文章
本文主要介紹了在樹莓派上安裝Git和Node.js并配置OpenClaw并調(diào)用Ollama大模型的步驟，文中通過示例代碼介紹的非常詳細(xì)，對大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價(jià)值，需要2026-03-03
本文詳細(xì)介紹了在Windows本地（PowerShell）一鍵部署OpenClaw的步驟,包括安裝OpenClaw、配置飛書機(jī)器人、啟動(dòng)網(wǎng)關(guān)服務(wù)以及驗(yàn)證部署,需要的朋友可以參考下2026-03-12
OpenClaw 是一款終端式 AI 助手,支持多模型適配、多渠道接入,既可本地部署,也支持云端一鍵安裝這篇文章主要介紹了OpenClaw快速部署及使用方法指南的相關(guān)資料,文中通過代碼2026-03-10
本文給大家分享本地部署OpenClaw安裝配置使用教程，本文給大家介紹的非常詳細(xì)，對大家的學(xué)習(xí)或工作具有一定的參考借鑒價(jià)值，需要的朋友參考下吧2026-03-09
