Raspberry Pi

Raspberry Pi 문서는 OpenClaw 공식 문서(install/raspberry-pi)를 한국어로 정리한 가이드입니다. Host OpenClaw on a Raspberry Pi for always-on self-hosting 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Host OpenClaw on a Raspberry Pi for always-on self-hosting

한국어 가이드 범위: install/raspberry-pi 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Hardware compatibility
사전 요구사항
설정
Performance tips
Recommended model setup
ARM binary notes
Persistence and backups
트러블슈팅
다음 단계
관련 문서

상세 내용

본문

Run a persistent, always-on OpenClaw Gateway on a Raspberry Pi. Since the Pi is just the gateway (models run in the cloud via API), even a modest Pi handles the workload well -- typical hardware cost is $35-80 one-time, no monthly fees.

Hardware compatibility

Pi model	RAM	Works?	Notes
Pi 5	4/8 GB	Best	Fastest, recommended.
Pi 4	4 GB	Good	Sweet spot for most users.
Pi 4	2 GB	OK	Add swap.
Pi 4	1 GB	Tight	Possible with swap, minimal config.
Pi 3B+	1 GB	Slow	Works but sluggish.
Pi Zero 2 W	512 MB	No	Not recommended.

사전 요구사항

주요 항목:

Raspberry Pi 4 or 5 with 2 GB+ RAM (4 GB recommended)
MicroSD card (16 GB+) or USB SSD (better performance)
Official Pi power supply
Network connection (Ethernet or WiFi)
64-bit Raspberry Pi OS (required -- do not use 32-bit)
About 30 minutes

설정

Use Raspberry Pi OS Lite (64-bit) -- no desktop needed for a headless server.

주요 항목:

Hostname: gateway-host
Enable SSH
Set username and password
Configure WiFi (if not using Ethernet)

ssh user@gateway-host

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

    # Set timezone (important for cron and reminders)
    sudo timedatectl set-timezone America/Chicago

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

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

Performance tips

Use /var/tmp, not /tmp -- some distros clear /tmp on boot, which drops the warmed cache.

grep -q 'NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache' ~/.bashrc || cat >> ~/.bashrc <<'EOF' # pragma: allowlist secret

mkdir -p /var/tmp/openclaw-compile-cache

EOF
source ~/.bashrc

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

systemctl --user edit openclaw-gateway.service

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

Recommended model setup

Since the Pi only runs the gateway, use cloud-hosted API models -- do not run local LLMs on a Pi, even small models are too slow to be useful:

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

ARM binary notes

Most OpenClaw features work on ARM64 without changes (Node.js, Telegram, WhatsApp/Baileys, Chromium). The binaries that occasionally lack ARM builds are typically optional Go/Rust CLI tools shipped by skills. Verify architecture with uname -m (should show aarch64), then check a missing binary's release page for linux-arm64 / aarch64 artifacts before falling back to building from source.

Persistence and backups

These survive reboots and benefit from SSD over SD card for both performance and longevity. Take a portable snapshot with:

주요 항목:

~/.openclaw/ -- openclaw.json, per-agent auth-profiles.json, channel/provider state, sessions.
~/.openclaw/workspace/ -- agent workspace (SOUL.md, memory, artifacts).

openclaw backup create

트러블슈팅

Out of memory -- Verify swap is active with free -h. Disable unused services (sudo systemctl disable cups bluetooth avahi-daemon). Use API-based models only.

Slow performance -- Use a USB SSD instead of an SD card. Check for CPU throttling with vcgencmd get_throttled (should return 0x0).

Service will not start -- Check logs with journalctl --user -u openclaw-gateway.service --no-pager -n 100 and run openclaw doctor --non-interactive. If this is a headless Pi, also verify lingering is enabled: sudo loginctl enable-linger "$(whoami)".

ARM binary issues -- If a skill fails with "exec format error", check whether the binary has an ARM64 build. Verify architecture with uname -m (should show aarch64).

WiFi drops -- Disable WiFi power management: sudo iwconfig wlan0 power off.

다음 단계

주요 항목:

Channels -- connect Telegram, WhatsApp, Discord, and more
Gateway configuration -- all config options
Updating -- keep OpenClaw up to date

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/install/raspberry-pi
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

ssh user@gateway-host

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

    # Set timezone (important for cron and reminders)
    sudo timedatectl set-timezone America/Chicago

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

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

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

openclaw onboard --install-daemon

Raspberry Pi

핵심 요약

Host OpenClaw on a Raspberry Pi for always-on self-hosting

한국어 가이드 범위: install/raspberry-pi 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Hardware compatibility
사전 요구사항
설정
Performance tips
Recommended model setup
ARM binary notes
Persistence and backups
트러블슈팅
다음 단계
관련 문서

상세 내용

본문

Hardware compatibility

Pi model	RAM	Works?	Notes
Pi 5	4/8 GB	Best	Fastest, recommended.
Pi 4	4 GB	Good	Sweet spot for most users.
Pi 4	2 GB	OK	Add swap.
Pi 4	1 GB	Tight	Possible with swap, minimal config.
Pi 3B+	1 GB	Slow	Works but sluggish.
Pi Zero 2 W	512 MB	No	Not recommended.

사전 요구사항

주요 항목:

Raspberry Pi 4 or 5 with 2 GB+ RAM (4 GB recommended)
MicroSD card (16 GB+) or USB SSD (better performance)
Official Pi power supply
Network connection (Ethernet or WiFi)
64-bit Raspberry Pi OS (required -- do not use 32-bit)
About 30 minutes

설정

Use Raspberry Pi OS Lite (64-bit) -- no desktop needed for a headless server.

주요 항목:

Hostname: gateway-host
Enable SSH
Set username and password
Configure WiFi (if not using Ethernet)

ssh user@gateway-host

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

    # Set timezone (important for cron and reminders)
    sudo timedatectl set-timezone America/Chicago

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

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

Performance tips

Use /var/tmp, not /tmp -- some distros clear /tmp on boot, which drops the warmed cache.

grep -q 'NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache' ~/.bashrc || cat >> ~/.bashrc <<'EOF' # pragma: allowlist secret

mkdir -p /var/tmp/openclaw-compile-cache

EOF
source ~/.bashrc

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

systemctl --user edit openclaw-gateway.service

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

Recommended model setup

Since the Pi only runs the gateway, use cloud-hosted API models -- do not run local LLMs on a Pi, even small models are too slow to be useful:

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

ARM binary notes

Persistence and backups

These survive reboots and benefit from SSD over SD card for both performance and longevity. Take a portable snapshot with:

주요 항목:

~/.openclaw/ -- openclaw.json, per-agent auth-profiles.json, channel/provider state, sessions.
~/.openclaw/workspace/ -- agent workspace (SOUL.md, memory, artifacts).

openclaw backup create

트러블슈팅

Out of memory -- Verify swap is active with free -h. Disable unused services (sudo systemctl disable cups bluetooth avahi-daemon). Use API-based models only.

Slow performance -- Use a USB SSD instead of an SD card. Check for CPU throttling with vcgencmd get_throttled (should return 0x0).

ARM binary issues -- If a skill fails with "exec format error", check whether the binary has an ARM64 build. Verify architecture with uname -m (should show aarch64).

WiFi drops -- Disable WiFi power management: sudo iwconfig wlan0 power off.

다음 단계

주요 항목:

Channels -- connect Telegram, WhatsApp, Discord, and more
Gateway configuration -- all config options
Updating -- keep OpenClaw up to date

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/install/raspberry-pi
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

ssh user@gateway-host

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

    # Set timezone (important for cron and reminders)
    sudo timedatectl set-timezone America/Chicago

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

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

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

openclaw onboard --install-daemon

Raspberry Pi

핵심 요약

문서 구성

상세 내용

본문

Hardware compatibility

사전 요구사항

설정

Performance tips

Recommended model setup

ARM binary notes

Persistence and backups

트러블슈팅

다음 단계

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Raspberry Pi

핵심 요약

문서 구성

상세 내용

본문

Hardware compatibility

사전 요구사항

설정

Performance tips

Recommended model setup

ARM binary notes

Persistence and backups

트러블슈팅

다음 단계

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드