Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

Configuración de Raspberry Pi

Esta guía cubre la instalación y ejecución de ZeroClaw en Raspberry Pi.

El runtime es lo suficientemente pequeño como para ejecutarse cómodamente en cualquier Pi. La única limitación es compilar desde el código fuente en el dispositivo: el enlazador de Rust consume mucha memoria (el fat LTO puede provocar un OOM en una placa con poca RAM), por lo que la ruta de compilación en el dispositivo necesita swap y un perfil más ligero. La mayoría de los usuarios deberían usar el binario precompilado y omitir todo eso.

Compatibilidad de hardware

Cualquier Pi que pueda ejecutar Raspberry Pi OS de 64 bits (aarch64) o de 32 bits (armv7) ejecuta el binario precompilado; no hay un mínimo de memoria significativo para el runtime. Los binarios precompilados para Pi provienen de estos targets de release (aarch64 de 64 bits para Raspberry Pi OS de 64 bits, armv7/arm de 32 bits para el OS de 32 bits):

  • aarch64-unknown-linux-gnu (64-bit)
  • arm-unknown-linux-gnueabihf (32 bits)
  • armv7-unknown-linux-gnueabihf (32 bits)

Opción 1: Binario precompilado (recomendado)

Ruta más rápida. Sin compilador, sin swap, sin riesgo de OOM.

Usar el script de instalación

Ruta rápida de Unix

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

Esta ruta no es interactiva y no abre un selector.

Prefiere un binario precompilado compatible y recurre a una compilación desde el código fuente cuando es necesario.

Un archivo precompilado puede contener zerocode; una alternativa no interactiva desde el código fuente instala la aplicación predeterminada sin abrir un selector.

El comando utiliza un conjunto fijo de funcionalidades.

Si se necesita una compilación desde el código fuente, el instalador puede configurar Rust automáticamente cuando no está disponible.

En Unix, el instalador actualiza el perfil del shell cuando se permite; recarga el shell padre antes de depender del nuevo PATH.

El instalador omite la configuración e imprime zeroclaw quickstart como el siguiente paso.

Ruta guiada de Unix

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

Esta ruta es guiada y puede ofrecer opciones compatibles.

En los destinos compatibles, ofrece instalación de paquetes precompilados o desde el código fuente.

Un archivo precompilado puede contener zerocode; una selección del origen lo selecciona de forma predeterminada y permite seleccionar la aplicación.

La ruta de origen también permite seleccionar características opcionales de Cargo.

Si se necesita una compilación desde el código fuente, el instalador puede configurar Rust automáticamente cuando no está disponible.

En Unix, el instalador actualiza el perfil del shell cuando se permite; recarga el shell padre antes de depender del nuevo PATH.

Para una instalación sin configurar, ofrece zeroclaw quickstart o un inicio rápido desde el navegador.

El script detecta automáticamente tu arquitectura (aarch64, armv7 o armv6) e instala el binario de la versión correspondiente en $CARGO_HOME/bin/zeroclaw (por defecto ~/.cargo/bin/zeroclaw). Asegúrate de que ese directorio esté en tu PATH.

Cuando el script compila desde el código fuente en lugar de usar un binario precompilado, también adapta la compilación a la memoria disponible de la placa:

Cuando install.sh compila desde el código fuente en Linux, lee MemTotal de /proc/meminfo y, en hosts con menos de 12 GiB de RAM, exporta CARGO_PROFILE_RELEASE_LTO=thin antes de compilar. El LTO fat (el valor por defecto de [profile.release]) puede superar los 7 GB de RSS durante el paso de tipos entre crates y provocar un OOM en una placa con poca RAM; el LTO thin compensa un pequeño aumento del tamaño del binario con un pico de memoria mucho menor en tiempo de compilación.

El conmutador solo se aplica cuando aún no has fijado la variable. Anula cualquiera de las dos direcciones explícitamente:

# Forzar LTO completo incluso en un host con poca RAM (binario más pequeño, mayor RAM de compilación)
export CARGO_PROFILE_RELEASE_LTO=gordo

# Forzar LTO ligero (thin LTO) en un host con mucha RAM (menor consumo de RAM en la compilación)
export CARGO_PROFILE_RELEASE_LTO=thin

Descarga manual

Elige el tarball correspondiente de la última versión:

sh

# 64 bits (Pi 4/5 con Raspberry Pi OS de 64 bits)
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-bit (Pi Zero 2 W, Pi 3 más antiguas con SO de 32 bits)
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/

Verifica tu arquitectura

sh

uname -m
# aarch64 → 64 bits (use el binario aarch64-unknown-linux-gnu)
# armv7l  → 32-bit (use the armv7-unknown-linux-gnueabihf binary)
# armv6l  → Pi 1 / Zero / Zero W (use el binario arm-unknown-linux-gnueabihf)

Opción 2: Compilación cruzada desde otra máquina

Si ya tienes una máquina más potente, la compilación cruzada es más rápida que compilar en la Pi.

macOS (Apple Silicon o Intel)

# Instalar el target de compilación cruzada
rustup target add aarch64-unknown-linux-gnu

# Instalar una cadena de herramientas cruzada GNU para Linux — el mismo patrón utilizado por la guía de Arduino Uno Q
brew tap messense/macos-cross-toolchains
brew install aarch64-unknown-linux-gnu

# Construir
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:~/

Nota: los borradores anteriores de esta guía sugerían aarch64-elf-gcc de Homebrew. Esa toolchain produce binarios ELF bare-metal y enlaza contra newlib, no glibc. No producirá un binario funcional para Raspberry Pi OS. Usa el tap messense/macos-cross-toolchains indicado arriba (una toolchain Linux GNU/glibc real), o recurre a la Opción 3 (compilar en la Pi).

Linux x86_64

# Instalar la cadena de herramientas de compilación cruzada
sudo apt-get install -y gcc-aarch64-linux-gnu

# Agregar destino
rustup target add aarch64-unknown-linux-gnu

# Configurar el enlazador
# [target.aarch64-unknown-linux-gnu]
# linker = "aarch64-linux-gnu-gcc"

# Construir
cargo build --release --target aarch64-unknown-linux-gnu

# Copiar a la Pi
scp target/aarch64-unknown-linux-gnu/release/zeroclaw pi@raspberrypi:~/

Opción 3: Compilar en la Pi

El agente compilándose a sí mismo en el dispositivo. Funciona en cualquier Pi con swap y el perfil de compilación adecuado; más lento en placas con menos RAM.

Paso 1: Instalar la cadena de herramientas de Rust

sh

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

Paso 2: Agregar swap

Fat LTO alcanza su pico de consumo durante el enlazado final; sin swap, una placa con poca RAM mata el proceso por OOM a mitad del enlazado.

sh

# Crear un archivo de intercambio de 4 GB
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# Verificar
free -h

# Hacer persistente entre reinicios
echo /swapfile none swap sw 0 0 | sudo tee -a /etc/fstab

Paso 3: Compilación

Elige un perfil según la RAM disponible. release usa LTO completo (mejor binario, enlazado más pesado); release-fast aumenta codegen-units para un enlazado más ligero; ci usa LTO thin para el enlazado con menor consumo de memoria. (install.sh lo selecciona automáticamente; consulta Using the install script.)

sh

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

cargo build --release           # placa con más RAM
cargo build --profile release-fast   # Placa de RAM media
cargo build --profile ci        # placa con poca RAM / recursos limitados

# Instala el binario que compilaste:
sudo install -m 0755 target/release/zeroclaw /usr/local/bin/
# (o target/release-fast/zeroclaw, o target/ci/zeroclaw)

Compatibilidad con GPIO

Para controlar los GPIO de Pi desde skills, compila con el feature flag peripherals correspondiente. La mayoría de las cargas de trabajo de agentes no lo necesitan; consulta Diseño de periféricos.

Despliegue en contenedores (se recomienda Podman en lugar de Docker)

En una Pi con memoria limitada, la elección del runtime de contenedores importa: todo lo que apiles junto a ZeroClaw compite por el mismo grupo fijo, así que la memoria que no se gasta en infraestructura de contenedores es memoria que recibe el agente.

Por qué Podman en lugar de Docker en una Pi:

  1. Rootless por defecto. Sin daemon root; los contenedores se ejecutan como tu usuario, lo cual es importante en un dispositivo edge expuesto.
  2. Nativo de systemd mediante Quadlets. Archivos de unidad .container que systemd gestiona directamente, sin un docker.service separado ni capa de registro.
  3. Sin demonio persistente. Docker mantiene dockerd residente; Podman no, liberando el mayor bloque de memoria sin perder aislamiento.

La contrapartida: la red rootless de Podman (slirp4netns/pasta) es más lenta que el bridge de Docker. Para el patrón de “uno o dos contenedores de agentes de larga duración” de ZeroClaw eso es insignificante, y el ahorro por la ausencia de daemon predomina en hardware con recursos limitados.

Instalación rápida (Raspberry Pi OS Bookworm/Trixie)

sh

sudo apt-get install -y podman
# Opcional: alias más cortos — muchos flujos de docker-compose funcionan directamente con podman-compose
sudo apt-get install -y podman-compose

Ejecutar ZeroClaw con Podman

La imagen OCI publicada funciona bajo Podman sin modificaciones:

sh

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

Problema con bind: ZeroClaw usa 127.0.0.1 de forma predeterminada para el gateway. Dentro de un contenedor, eso significa que el gateway es inaccesible desde el host. Pasa siempre --host 0.0.0.0 (o define ZEROCLAW_BIND=0.0.0.0) cuando se ejecuta en un contenedor.

Ejecución como una unidad de systemd mediante Quadlet

Coloca un archivo .container en /etc/containers/systemd/ (sistema) o ~/.config/containers/systemd/ (usuario sin privilegios de 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

sh

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

Para configuraciones rootless, también ejecuta loginctl enable-linger $USER para que el servicio se inicie antes de iniciar sesión.

Posterior a la instalación: Configuración nativa (sin contenedor)

1. Inicializar ZeroClaw

sh

zeroclaw quickstart

Esto te guía a través de la autenticación del proveedor, la configuración del gateway y crea tu configuración de ZeroClaw.

2. Verifica que funciona

sh

zeroclaw doctor
zeroclaw agent -a assistant -m ¿cuánto es 2+2?

3. Ejecutar como un servicio persistente

sh

# Instalar e iniciar el servicio de usuario systemd
zeroclaw service install
systemctl --user enable --now zeroclaw

# Para que sobreviva al cierre de sesión / reinicio:
loginctl enable-linger $USER

4. Ejecutar como un daemon en primer plano

Para desarrollo / depuración:

sh

zeroclaw daemon --host 0.0.0.0 --port 42617

5. Habilitar canales

ZeroClaw puede conectarse a plataformas de chat (Matrix, Mattermost, Discord, Telegram, etc.). Consulta Channels → Overview. La mayoría de los transportes de canales funcionan bien en una Pi; el más pesado es la pila de WebRTC que usan algunos canales de voz, que puede provocar picos de CPU durante el establecimiento de llamadas.

GPIO y periféricos de hardware

Si quieres que las skills controlen pines GPIO (LEDs, botones, sensores, etc.):

  1. Agrega tu usuario al grupo gpio:

    sh

    sudo usermod -aG gpio $USER
# Cierra sesión y vuelve a iniciarla para que el cambio de grupo surta efecto

  2. Usa los enlaces GPIO del crate peripherals de tus habilidades. Consulta Hardware → Diseño de periféricos para conocer el modelo de abstracción.

Solución de problemas

  • Terminado por OOM durante la compilación: agrega swap (Opción 3, Paso 2), cambia a un perfil más ligero (release-fast o ci), o usa el binario precompilado / compila de forma cruzada.
  • Compilación extremadamente lenta: es lo esperado en placas con poca RAM; realice compilación cruzada (Opción 2) si es importante.
  • “Exec format error” en binario precompilado: discrepancia de arquitectura. Ejecuta uname -m y descarga el binario correspondiente (aarch64 = 64 bits, armv7l = 32 bits).
  • Permiso de GPIO denegado: no perteneces al grupo gpio; ejecuta sudo usermod -aG gpio $USER y luego vuelve a iniciar sesión.
  • El servicio no inicia después de reiniciar: loginctl enable-linger $USER para que el servicio de usuario sobreviva al cierre de sesión.
  • El contenedor no puede alcanzar el gateway desde el host: el gateway se vincula a 127.0.0.1; pase --host 0.0.0.0 (o ZEROCLAW_BIND=0.0.0.0).

Consejos de rendimiento

  • Usa un SSD o una tarjeta SD rápida. La compilación está limitada por E/S; un SSD USB 3.0 en una Pi 4/5 reduce significativamente el tiempo de compilación.
  • Ejecutar sin interfaz gráfica: sudo systemctl set-default multi-user.target.
  • tmpfs para artefactos de compilación (con margen de RAM + swap): export CARGO_TARGET_DIR=/tmp/zeroclaw-target.
  • Verifica que clk_ignore_unused no esté en la línea de comandos del kernel si usas una imagen personalizada; inhibe el clock gating y aumenta el consumo de energía en reposo. Raspberry Pi OS de fábrica no lo establece.

Relacionado