跳转至

Raspberry Pi

在 Raspberry Pi 上运行持久、常驻的 OpenClaw Gateway。由于 Pi 仅作为网关（模型通过 API 在云端运行），即使是性能一般的 Pi 也能很好地处理负载——典型硬件成本为 一次性 35-80 美元，无月费。

硬件兼容性

Pi 型号 内存 可用? 备注
Pi 5 4/8 GB 最佳 最快，推荐。
Pi 4 4 GB 良好 大多数用户的最佳选择。
Pi 4 2 GB 可行 需要添加交换空间。
Pi 4 1 GB 紧张 配合交换空间可行，配置需最简。
Pi 3B+ 1 GB 慢速 可以工作但反应迟缓。
Pi Zero 2 W 512 MB 不行 不推荐。

最低要求： 1 GB 内存、1 核、500 MB 空闲磁盘、64 位操作系统。 推荐配置： 2 GB 以上内存、16 GB 以上 SD 卡（或 USB SSD）、有线网络。

先决条件

  • 配备 2 GB 以上内存的 Raspberry Pi 4 或 5（推荐 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. 在设置对话框中预配置：
  4. 主机名：gateway-host
  5. 启用 SSH
  6. 设置用户名和密码
  7. 配置 WiFi（如果未使用以太网）
  8. 烧录到 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

# Set your timezone (important for cron and reminders).
# Replace America/Chicago with your own IANA zone (`timedatectl list-timezones`).
sudo timedatectl set-timezone America/Chicago

4. 安装 Node.js 24 LTS

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

5. 添加交换空间（对于 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

# Reduce swappiness for low-RAM devices
echo 'vm.swappiness=10' | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

6. 安装 OpenClaw

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard

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. 访问控制界面

在您的电脑上，从 Pi 获取仪表盘 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 能显著提升性能并承受更多写入周期；如果您将操作系统保留在 SD 卡上，请将其用于 OPENCLAW_STATE_DIR。请参阅 Pi USB 启动指南。

启用模块编译缓存——在低功耗 Pi 主机上加速重复的 CLI 调用。OPENCLAW_NO_RESPAWN=1 让常规的 Gateway 重启保持在进程内完成，避免额外的进程交接，并在小型主机上简化 PID 跟踪：

grep -q 'NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache' ~/.bashrc || cat >> ~/.bashrc <<'EOF'
export NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache
mkdir -p /var/tmp/openclaw-compile-cache
export OPENCLAW_NO_RESPAWN=1
EOF
source ~/.bashrc

请使用 /var/tmp，而不是 /tmp——某些发行版在启动时会清空 /tmp，导致已预热的缓存丢失。

降低内存占用——对于无头设置，释放 GPU 内存并禁用未使用的服务：

echo 'gpu_mem=16' | sudo tee -a /boot/config.txt
sudo systemctl disable bluetooth

用于主机特定启动调优的 systemd drop-in——受管单元负责通用的重启策略（Restart=always、RestartSec=5）。如果这台 Pi 主要运行 OpenClaw，请仅添加一个用于主机特定启动设置的服务 drop-in：

systemctl --user edit openclaw-gateway.service

[Service]
Environment=OPENCLAW_NO_RESPAWN=1
Environment=NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache
TimeoutStartSec=90

然后执行 systemctl --user daemon-reload && systemctl --user restart openclaw-gateway.service。在无头 Pi 上，还需要启用一次 lingering（驻留），以便用户服务在注销后依然存在：sudo loginctl enable-linger "$(whoami)"。

由于 Pi 只运行网关，请使用云端托管的 API 模型——不要在 Pi 上运行本地 LLM，即使是小模型也慢到难以实际使用：

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-sonnet-4-6",
        "fallbacks": ["openai/gpt-5.4-mini"]
      }
    }
  }
}

ARM 二进制文件说明

大多数 OpenClaw 功能在 ARM64 上无需修改即可正常工作（Node.js、Telegram、WhatsApp/Baileys、Chromium）。偶尔缺少 ARM 构建的二进制文件通常是技能附带的可选 Go/Rust CLI 工具。使用 uname -m 验证架构（应显示 aarch64），然后在回退到从源码构建之前，检查缺失二进制文件的发布页面是否有 linux-arm64 / aarch64 构件。

持久化与备份

OpenClaw 状态数据存放在以下位置：

  • ~/.openclaw/ -- openclaw.json、共享及每个智能体（agent）的 SQLite 认证存储、渠道/提供方状态、会话。
  • ~/.openclaw/workspace/ -- 智能体工作区（SOUL.md、记忆、工件）。

这些数据在重启后仍然保留，并且相比 SD 卡，使用 SSD 在性能和寿命上都更有优势。使用以下命令创建备份归档：

openclaw backup create
openclaw backup restore <archive.tar.gz> --target <fresh-directory>

绝对符号链接会保留其原始目标位置，包括指向单独备份的配置或凭据的链接。在另一台主机或另一个路径上激活状态之前，请检查这些链接；参见备份符号链接注意事项。恢复操作会验证并解压到一个全新的暂存目录中；激活是一个独立的离线步骤。有关回滚警告和激活顺序，请参见恢复完整归档。

故障排除

内存不足 -- 使用 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。如果是无头（headless）Pi，还要确认已启用 lingering：sudo loginctl enable-linger "$(whoami)"。

ARM 二进制文件问题 -- 如果某个技能（skill）报错 "exec format error"，请检查该二进制文件是否有 ARM64 版本。使用 uname -m 验证架构（应显示 aarch64）。

WiFi 掉线 -- 禁用 WiFi 电源管理：sudo iwconfig wlan0 power off。

后续步骤

  • 渠道 -- 连接 Telegram、WhatsApp、Discord 等
  • 网关配置 -- 所有配置选项
  • 更新 -- 让 OpenClaw 保持最新

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw