Skip to main content

​
Raspberry Pi

在 Raspberry Pi 上运行一个持久化、始终在线的 OpenClaw Gateway 网关。由于 Pi 仅用作 Gateway 网关（模型通过 API 在云端运行），即使是配置较低的 Pi 也足以胜任这项工作。

​
前置条件

  • Raspberry Pi 4 或 5，内存 2 GB 以上（推荐 4 GB）
  • MicroSD 卡（16 GB 以上）或 USB SSD（性能更好）
  • 官方 Pi 电源
  • 网络连接（以太网或 WiFi）
  • 64 位 Raspberry Pi OS（必需 —— 不要使用 32 位）
  • 大约 30 分钟

​
设置

1

刷写操作系统

使用 Raspberry Pi OS Lite（64 位） —— 作为无头服务器，不需要桌面环境。
  1. 下载 Raspberry Pi Imager。
  2. 选择操作系统：Raspberry Pi OS Lite（64 位）。
  3. 在设置对话框中预先配置：
    • 主机名：gateway-host
    • 启用 SSH
    • 设置用户名和密码
    • 配置 WiFi（如果不使用以太网）
  4. 将系统刷写到 SD 卡或 USB 驱动器，插入后启动 Pi。
2

通过 SSH 连接

ssh user@gateway-host
3

更新系统

sudo apt update && sudo apt upgrade -y
sudo apt install -y git curl build-essential

# 设置时区（对 cron 和提醒很重要）
sudo timedatectl set-timezone America/Chicago
4

安装 Node.js 24

curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt install -y nodejs
node --version
5

添加 swap（对 2 GB 或更低内存很重要）

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

# 降低低内存设备的 swappiness
echo 'vm.swappiness=10' | sudo tee -a /etc/sysctl.conf
sudo sysctl -p
6

安装 OpenClaw

curl -fsSL https://openclaw.ai/install.sh | bash
7

运行新手引导

openclaw onboard --install-daemon
按照向导操作。对于无头设备，推荐使用 API 密钥而不是 OAuth。Telegram 是最容易开始的渠道。
8

验证

openclaw status
systemctl --user status openclaw-gateway.service
journalctl --user -u openclaw-gateway.service -f
9

访问 Control UI

在你的电脑上，从 Pi 获取 dashboard URL：
ssh user@gateway-host 'openclaw dashboard --no-open'
然后在另一个终端中创建 SSH 隧道：
ssh -N -L 18789:127.0.0.1:18789 user@gateway-host
在本地浏览器中打开打印出的 URL。有关始终在线的远程访问，请参见 Tailscale 集成。

​
性能提示

使用 USB SSD —— SD 卡速度慢且容易磨损。USB SSD 能显著提升性能。参见 Pi USB 启动指南。 启用模块编译缓存 —— 可在较低功耗的 Pi 宿主机上加速重复的 CLI 调用： 
grep -q 'NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache' ~/.bashrc || cat >> ~/.bashrc <<'EOF' # pragma: allowlist secret
export NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache
mkdir -p /var/tmp/openclaw-compile-cache
export OPENCLAW_NO_RESPAWN=1
EOF
source ~/.bashrc
降低内存使用 —— 对于无头部署，可释放 GPU 内存并禁用未使用的服务： 
echo 'gpu_mem=16' | sudo tee -a /boot/config.txt
sudo systemctl disable bluetooth

​
故障排除

内存不足 —— 使用 free -h 验证 swap 是否已启用。禁用未使用的服务（sudo systemctl disable cups bluetooth avahi-daemon）。仅使用基于 API 的模型。 性能缓慢 —— 使用 USB SSD，而不是 SD 卡。运行 vcgencmd get_throttled 检查 CPU 是否降频（应返回 0x0）。 服务无法启动 —— 使用 journalctl --user -u openclaw-gateway.service --no-pager -n 100 检查日志，并运行 openclaw doctor --non-interactive。如果这是无头 Pi，也请验证 lingering 是否已启用：sudo loginctl enable-linger "$(whoami)"。 ARM 二进制问题 —— 如果某个 skill 失败并提示 “exec format error”，请检查该二进制是否有 ARM64 构建版本。使用 uname -m 验证架构（应显示 aarch64）。 WiFi 掉线 —— 禁用 WiFi 省电管理：sudo iwconfig wlan0 power off。

​
后续步骤