树莓派设置

本指南介绍如何在树莓派上安装和运行 ZeroClaw。

该运行时足够小巧，可在任何 Pi 上流畅运行。唯一的限制是在设备上从源码构建：Rust 的链接器对内存需求较高（fat LTO 可能导致低内存开发板出现 OOM），因此设备端构建路径需要交换空间和更轻量的配置。大多数用户应直接使用预构建的二进制文件，从而跳过这一切。

硬件兼容性

任何能运行 64 位（aarch64）或 32 位（armv7）Raspberry Pi OS 的 Pi 都可以运行此预编译二进制文件；运行时没有实际的内存下限。这些预编译的 Pi 二进制文件来自以下发布目标（用于 64 位 Raspberry Pi OS 的 64 位 aarch64，用于 32 位系统的 32 位 armv7/arm）：

• aarch64-unknown-linux-gnu（64 位）
• arm-unknown-linux-gnueabihf（32 位）
• armv7-unknown-linux-gnueabihf（32 位）

选项 1：预构建二进制文件（推荐）

最快路径。无需编译器，无需交换空间，无 OOM 风险。

使用安装脚本

Unix 快速路径

curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | sh

此路由为非交互式，不会打开选择器。

它会优先使用匹配的预构建二进制文件，并在需要时回退到源代码构建。

预构建归档可能包含 zerocode；非交互式源代码回退会安装默认应用，而不打开选择器。

该命令使用固定的特征集。

如果需要从源代码构建，且系统中缺少 Rust，安装程序可以自动安装 Rust。

在 Unix 上，安装程序会在允许的情况下更新 shell 配置文件；在依赖新的 PATH 之前，请重新加载父 shell。

安装程序会跳过设置，并打印 zeroclaw quickstart 作为下一步。

Unix 指导路径

git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw
./install.sh

此路由带有引导功能，可能会提供受支持的选项。

在受支持的目标平台上，它提供预构建安装或从源代码安装。

预构建归档可能包含 zerocode；源选择默认会选中它，并允许应用选择。

源路径还允许你选择可选的 Cargo 特性。

如果需要从源代码构建，且系统中缺少 Rust，安装程序可以自动安装 Rust。

在 Unix 上，安装程序会在允许的情况下更新 shell 配置文件；在依赖新的 PATH 之前，请重新加载父 shell。

对于未配置的安装，它提供 zeroclaw quickstart 或基于浏览器的快速入门。

该脚本会自动检测你的架构（aarch64、armv7 或 armv6），并将匹配的发行版二进制文件安装到 $CARGO_HOME/bin/zeroclaw（默认为 ~/.cargo/bin/zeroclaw）。请确保该目录已包含在你的 PATH 中。

当脚本从源代码构建而不是使用预构建的二进制文件时，它还会根据开发板的可用内存来调整构建：

当 install.sh 在 Linux 上从源码构建时，它会从 /proc/meminfo 读取 MemTotal，并在 RAM 低于 12 GiB 的主机上于构建前导出 CARGO_PROFILE_RELEASE_LTO=thin。Fat LTO（[profile.release] 的默认值）在跨 crate 类型处理阶段的 RSS 峰值可能超过 7 GB，从而使低 RAM 的开发板发生 OOM；thin LTO 以二进制体积的小幅增加换取了大幅降低的构建时内存峰值。

只有在你尚未固定该变量时，此切换才会生效。可显式覆盖任一方向：

# 即使在低内存主机上也强制使用 fat LTO（生成更小的二进制文件，但构建时占用更多内存）
export CARGO_PROFILE_RELEASE_LTO=fat

# 在大内存主机上强制使用 thin LTO（降低构建内存占用）
export CARGO_PROFILE_RELEASE_LTO=thin

手动下载

从最新版本中选择匹配的 tarball：

# 64 位（运行 64 位 Raspberry Pi OS 的 Pi 4/5）
curl -LO https://github.com/zeroclaw-labs/zeroclaw/releases/latest/download/zeroclaw-aarch64-unknown-linux-gnu.tar.gz
tar xzf zeroclaw-aarch64-unknown-linux-gnu.tar.gz
sudo install -m 0755 zeroclaw /usr/local/bin/

# 32 位（Pi Zero 2 W、运行 32 位操作系统的较旧 Pi 3）
curl -LO https://github.com/zeroclaw-labs/zeroclaw/releases/latest/download/zeroclaw-armv7-unknown-linux-gnueabihf.tar.gz
tar xzf zeroclaw-armv7-unknown-linux-gnueabihf.tar.gz
sudo install -m 0755 zeroclaw /usr/local/bin/

检查您的架构

uname -m
# aarch64 → 64 位（使用 aarch64-unknown-linux-gnu 二进制文件）
# armv7l  → 32-bit (use the armv7-unknown-linux-gnueabihf binary)
# armv6l  → Pi 1 / Zero / Zero W（使用 arm-unknown-linux-gnueabihf 二进制文件）

选项 2：从另一台机器进行交叉编译

如果你已经有一台性能更强的机器，交叉编译会比直接在 Pi 上构建更快。

# 安装交叉编译目标
rustup target add aarch64-unknown-linux-gnu

# 安装 Linux GNU 交叉工具链——与 Arduino Uno Q 指南使用的模式相同
brew tap messense/macos-cross-toolchains
brew install aarch64-unknown-linux-gnu

# 构建
CC_aarch64_unknown_linux_gnu=aarch64-unknown-linux-gnu-gcc \
CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER=aarch64-unknown-linux-gnu-gcc \
cargo build --release --target aarch64-unknown-linux-gnu

# Copy to your Pi
scp target/aarch64-unknown-linux-gnu/release/zeroclaw pi@raspberrypi:~/

# 安装交叉编译工具链
sudo apt-get install -y gcc-aarch64-linux-gnu

# 添加目标
rustup target add aarch64-unknown-linux-gnu

# 配置链接器
# [target.aarch64-unknown-linux-gnu]
# linker = "aarch64-linux-gnu-gcc"

# 构建
cargo build --release --target aarch64-unknown-linux-gnu

# 复制到 Pi
scp target/aarch64-unknown-linux-gnu/release/zeroclaw pi@raspberrypi:~/

选项 3：在树莓派上构建

在设备上自行编译的代理。可在任何配备交换空间并使用正确构建配置的 Pi 上运行；在内存较低的板卡上速度会较慢。

步骤 1：安装 Rust 工具链

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

步骤 2：添加交换分区

胖 LTO（Fat LTO）在最终链接阶段达到内存占用峰值；如果没有交换空间，低内存的开发板会在链接过程中因内存不足（OOM）而被强制终止。

# 创建 4 GB 交换文件
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# 验证
free -h

# 使配置在重启后保持生效
echo /swapfile none swap sw 0 0 | sudo tee -a /etc/fstab

步骤 3：构建

根据可用内存选择构建配置。release 使用完整 LTO（生成最优的二进制文件，但链接时开销最大）；release-fast 提高 codegen-units 以减轻链接负担；ci 使用精简 LTO 实现内存占用最低的链接。（install.sh 会自动选择此项；参见 Using the install script。）

git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw

cargo build --release           # 更高内存的开发板
cargo build --profile release-fast   # 中等内存板
cargo build --profile ci        # 低内存 / 资源受限开发板

# 安装你构建的二进制文件：
sudo install -m 0755 target/release/zeroclaw /usr/local/bin/
# （或 target/release-fast/zeroclaw，或 target/ci/zeroclaw）

GPIO 支持

要从技能驱动 Pi GPIO，请使用相关的 peripherals 功能标志进行构建。大多数 agent 工作负载并不需要它；请参阅 Peripherals design。

容器化部署（推荐使用 Podman 而非 Docker）

在内存受限的 Pi 上，容器运行时的选择至关重要：与 ZeroClaw 一同堆叠运行的所有组件都在争用同一个固定的内存池，因此没有花在容器基础设施上的内存，就是 agent 能够使用的内存。

为什么在 Pi 上选择 Podman 而非 Docker：

1. 默认无 root 运行。 没有 root 守护进程；容器以你的用户身份运行，这对暴露在外的边缘设备尤为重要。
2. 通过 Quadlet 实现 systemd 原生集成。 由 systemd 直接管理的 .container 单元文件，无需独立的 docker.service 或日志层。
3. 没有常驻守护进程。 Docker 会让 dockerd 常驻内存；Podman 则不会，从而在不丧失隔离性的前提下释放了内存中最大的一块占用。

权衡之处：Podman 的无根网络（slirp4netns/pasta）比 Docker 的桥接网络要慢。但对于 ZeroClaw 的“一两个长期运行的代理容器“模式而言，这点差异微不足道，而在受限硬件上，省去守护进程所带来的优势更为显著。

快速安装（Raspberry Pi OS Bookworm/Trixie）

sudo apt-get install -y podman
# 可选：更短的别名 —— 许多 docker-compose 流程使用 podman-compose 即可正常工作
sudo apt-get install -y podman-compose

在 Podman 下运行 ZeroClaw

已发布的 OCI 镜像无需修改即可在 Podman 下运行：

podman pull ghcr.io/zeroclaw-labs/zeroclaw:latest

podman run --rm -d \
  --name zeroclaw \
  -p 42617:42617 \
  -v ~/.zeroclaw:/root/.zeroclaw \
  ghcr.io/zeroclaw-labs/zeroclaw:latest \
  daemon --host 0.0.0.0 --port 42617

绑定陷阱： ZeroClaw 默认将网关绑定到 127.0.0.1。在容器内部，这意味着主机无法访问该网关。在容器中运行时，请始终传入 --host 0.0.0.0（或设置 ZEROCLAW_BIND=0.0.0.0）。

通过 Quadlet 作为 systemd 单元运行

将 .container 文件放入 /etc/containers/systemd/（系统级）或 ~/.config/containers/systemd/（无 root 用户级）：

# ~/.config/containers/systemd/zeroclaw.container
[Unit]
Description=ZeroClaw gateway
After=network-online.target
Wants=network-online.target

[Container]
Image=ghcr.io/zeroclaw-labs/zeroclaw:latest
ContainerName=zeroclaw
PublishPort=42617:42617
Environment=ZEROCLAW_BIND=0.0.0.0
Exec=daemon --host 0.0.0.0 --port 42617
Volume=zeroclaw-data:/root/.zeroclaw

[Service]
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target default.target

systemctl --user daemon-reload
systemctl --user start zeroclaw.service

对于无 root 权限的配置，还需运行 loginctl enable-linger $USER，以便服务在你登录前启动。

安装后：原生（非容器）设置

1. 初始化 ZeroClaw

zeroclaw quickstart

此流程将引导您完成提供商身份验证、网关配置，并创建您的 ZeroClaw 配置。

2. 验证其是否正常工作

zeroclaw doctor
zeroclaw agent -a assistant -m "2+2 等于几？"

3. 作为持久化服务运行

# 安装并启动 systemd 用户服务
zeroclaw service install
systemctl --user enable --now zeroclaw

# 以便在注销/重启后仍然保留：
loginctl enable-linger $USER

4. 作为前台守护进程运行

用于开发/调试：

zeroclaw daemon --host 0.0.0.0 --port 42617

5. 启用通道

ZeroClaw 可以连接到聊天平台（Matrix、Mattermost、Discord、Telegram 等）。参见 Channels → Overview。大多数通道传输方式在树莓派上运行良好；最耗资源的是某些语音通道使用的 WebRTC 协议栈，它可能在通话建立期间导致 CPU 使用率飙升。

GPIO 与硬件外设

如果你想让技能驱动 GPIO 引脚（LED、按钮、传感器等）：

1. 将您的用户添加到 gpio 组：

   sh

   sudo usermod -aG gpio $USER
   # 注销并重新登录以使组更改生效
   

2. 使用技能中 peripherals crate 的 GPIO 绑定。有关抽象模型，请参阅 硬件 → 外设设计。

故障排除

• 构建期间被 OOM 终止： 添加交换空间（选项 3 步骤 2）、切换到更轻量的配置（release-fast 或 ci），或使用预构建的二进制文件 / 交叉编译。
• 构建速度极慢： 在内存较低的开发板上属于正常现象；如果你很在意，可以使用交叉编译（选项 2）。
• 预编译二进制文件出现 “Exec format error”（可执行文件格式错误）： 架构不匹配。运行 uname -m 并获取匹配的二进制文件（aarch64 = 64 位，armv7l = 32 位）。
• GPIO 权限被拒绝： 你不在 gpio 组中；请执行 sudo usermod -aG gpio $USER，然后重新登录。
• 重启后服务无法启动： 执行 loginctl enable-linger $USER，让用户服务在注销后仍能保持运行。
• **容器无法从主机访问网关：**网关绑定的是 127.0.0.1；请传入 --host 0.0.0.0（或设置 ZEROCLAW_BIND=0.0.0.0）。

性能优化建议

• 使用 SSD 或高速 SD 卡。 编译是 I/O 密集型任务；在 Pi 4/5 上使用 USB 3.0 SSD 可显著缩短构建时间。
• 以无头模式运行： sudo systemctl set-default multi-user.target。
• 为构建产物使用 tmpfs（需有足够的 RAM + swap 空间）：export CARGO_TARGET_DIR=/tmp/zeroclaw-target。
• 检查 clk_ignore_unused，如果你使用自定义镜像，请确认它不在内核 cmdline 中；它会抑制时钟门控并增加空闲功耗。标准的 Raspberry Pi OS 不会设置它。

相关

• Linux 设置：非 Pi 专用的 Linux 设置，安装二进制文件后此处同样适用
• 服务管理：systemd 模式，比上述内容更深入
• 硬件 → 外设设计：GPIO 与外设 crate
• 硬件 → 添加开发板和工具：扩展硬件支持