OpenClaw 树莓派安装配置文档

环境：Raspberry Pi aarch64 · Debian 12 (bookworm) · OpenClaw 2026.2.26

---

需要技术支持加Q
QQ: 1308137826

一、环境准备

确认系统架构

uname -m && cat /etc/os-release

安装 Node.js 22+（官方要求 >= 22）

curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
apt-get install -y nodejs
node -v  # 确认版本

---

二、安装 OpenClaw

⚠️ aarch64 架构需要加 CFLAGS 环境变量，否则 @discordjs/opus 编译失败

env CFLAGS='-DOPUS_ARM_MAY_HAVE_NEON_INTR' npm install -g openclaw@latest

---

三、初始化配置

openclaw onboard --install-daemon

按向导完成 API Key、频道绑定等配置。

---

四、配置文件

路径：~/.openclaw/openclaw.json

{
  "meta": {
    "lastTouchedVersion": "2026.2.26",
    "lastTouchedAt": "2026-02-27T01:49:00.437Z"
  },
  "agents": {
    "defaults": {
      "workspace": "/root/.openclaw/workspace",
      "compaction": {
        "mode": "safeguard"
      }
    }
  },
  "commands": {
    "native": "auto",
    "nativeSkills": "auto",
    "restart": true,
    "ownerDisplay": "raw"
  },
  "gateway": {
    "mode": "local",
    "bind": "lan",
    "port": 18789,
    "auth": {
      "mode": "token",
      "token": "你的token"
    },
    "controlUi": {
      "allowedOrigins": [
        "https://raspberrypi.tai2l9bb220be.ts.net"
      ],
      "allowInsecureAuth": true,
      "dangerouslyDisableDeviceAuth": true
    }
  }
}

---

五、启动 Gateway

openclaw gateway --port 18789

验证是否正常运行：

curl http://127.0.0.1:18789/
openclaw gateway status

---

六、远程访问配置（Tailscale HTTPS）

为什么需要 HTTPS

浏览器在非安全上下文（HTTP + 局域网 IP）下会禁用 WebCrypto API，导致 OpenClaw Control UI 无法生成设备身份，报错：

control ui requires device identity (use HTTPS or localhost secure context)

安装 Tailscale

curl -fsSL https://tailscale.com/install.sh | sh

登录 Tailscale

tailscale up
# 浏览器打开输出的链接完成授权

配置 HTTPS 反向代理

tailscale serve --bg http://127.0.0.1:18789

申请 TLS 证书（重要！否则浏览器报 ERR_CONNECTION_CLOSED）

tailscale cert raspberrypi.tail9b1b0be.ts.net

验证 HTTPS

tailscale serve status
curl -v https://raspberrypi.tail91bb0be.ts.net/

Windows 客户端

1. 下载安装 Tailscale：https://tailscale.com/download/windows
2. 登录同一个 Tailscale 账号
3. 浏览器访问 https://raspberrypi.tail91bb0be.ts.net/

⚠️ 重启树莓派后需要重新执行 tailscale serve --bg http://127.0.0.1:18789 和 gateway 启动命令

---

七、首次访问配对流程

首次从新设备访问 Control UI 需要完成配对：

第一步： 在浏览器页面输入 token（同 openclaw.json 中的 token 值）

第二步： 在树莓派上查看待批准的设备

openclaw devices list

第三步： 批准设备

openclaw devices approve <requestId>

配对成功后该设备会被记住，后续访问无需重复配对。

---

八、常见问题排查

报错	原因	解决方案
control ui requires device identity	HTTP 非安全上下文，WebCrypto 被禁用	改用 HTTPS（Tailscale）访问
device identity required	dangerouslyDisableDeviceAuth 未生效	需同时设置 allowInsecureAuth: true，并重启 gateway
ERR_CONNECTION_CLOSED	Tailscale HTTPS 证书未签发	执行 tailscale cert <域名>
too many failed authentication attempts	多次认证失败被限流	重启 gateway，等待限流解除
pairing required	新设备首次访问需要配对	执行 openclaw devices list 然后 approve
Serve is not enabled on your tailnet	Tailscale Serve 功能未开启	访问输出的链接启用，只需一次

---

九、卸载

# 停止并卸载守护进程
openclaw daemon uninstall

# 卸载 npm 包
npm uninstall -g openclaw

# 删除配置和数据
rm -rf ~/.openclaw

# 清理 npm 缓存（可选）
npm cache clean --force

---

十、Tailscale 代理原理

Windows 浏览器
     ↓ HTTPS (443)
https://raspberrypi.tail91bb10be.ts.net
     ↓ Tailscale 加密 P2P 隧道
树莓派 Tailscale 守护进程
     ↓ 本地转发 HTTP
http://127.0.0.1:18789
     ↓
OpenClaw Gateway

Tailscale 在两台设备间建立加密 P2P 隧道，流量不经过云服务器。tailscale serve 负责 HTTPS 终结并自动管理 Let’s Encrypt 证书，浏览器识别为安全上下文，WebCrypto API 正常可用。