Raspberry Pi

Raspberry Pi에서 지속적으로 상시 실행되는 OpenClaw Gateway를 운영하세요. Pi는 게이트웨이 역할만 하고 모델은 API를 통해 클라우드에서 실행되므로, 보급형 Pi로도 워크로드를 충분히 처리할 수 있습니다. 일반적인 하드웨어 비용은 일회성 $35~80이며 월별 요금은 없습니다.

하드웨어 호환성

Pi 모델	RAM	작동 여부	참고
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	불가	권장하지 않습니다.

최소 사양: RAM 1GB, 코어 1개, 디스크 여유 공간 500MB, 64비트 OS. 권장 사양: RAM 2GB 이상, SD 카드 16GB 이상(또는 USB SSD), 이더넷.

사전 요구 사항

RAM 2GB 이상의 Raspberry Pi 4 또는 5(4GB 권장)
MicroSD 카드(16GB 이상) 또는 USB SSD(성능이 더 좋음)
공식 Pi 전원 공급 장치
네트워크 연결(이더넷 또는 WiFi)
64비트 Raspberry Pi OS(필수 — 32비트는 사용하지 마세요)
약 30분

설정

OS 플래시

헤드리스 서버에는 데스크톱이 필요하지 않으므로 **Raspberry Pi OS Lite (64-bit)**를 사용하세요.

Raspberry Pi Imager를 다운로드합니다.
OS로 **Raspberry Pi OS Lite (64-bit)**를 선택합니다.
설정 대화 상자에서 다음을 미리 구성합니다.
- 호스트 이름: gateway-host
- SSH 활성화
- 사용자 이름과 비밀번호 설정
- WiFi 구성(이더넷을 사용하지 않는 경우)
SD 카드 또는 USB 드라이브에 플래시하고, Pi에 삽입한 후 부팅합니다.

SSH로 연결

ssh user@gateway-host

시스템 업데이트

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

# 시간대 설정(Cron 및 미리 알림에 중요)
sudo timedatectl set-timezone America/Chicago

Node.js 24 설치

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

스왑 추가(2GB 이하에서 중요)

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

# RAM이 적은 장치에서 스왑 사용 성향 낮추기
echo 'vm.swappiness=10' | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

OpenClaw 설치

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

온보딩 실행

openclaw onboard --install-daemon

마법사의 안내를 따르세요. 헤드리스 장치에는 OAuth보다 API 키를 권장합니다. 처음 시작하기에는 Telegram이 가장 간편한 채널입니다.

확인

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

제어 UI에 접근

컴퓨터에서 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는 성능을 크게 개선하고 더 많은 쓰기 주기를 견딜 수 있습니다. OS를 SD 카드에 유지하는 경우 OPENCLAW_STATE_DIR에 USB SSD를 사용하세요. Pi USB 부팅 안내서를 참조하세요. 모듈 컴파일 캐시 활성화 — 성능이 낮은 Pi 호스트에서 반복적인 CLI 호출 속도를 높입니다. OPENCLAW_NO_RESPAWN=1은 일반적인 Gateway 재시작을 동일 프로세스 내에서 수행하여 추가 프로세스 전환을 방지하고 소형 호스트에서 PID 추적을 단순하게 유지합니다.

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

/tmp가 아닌 /var/tmp를 사용하세요. 일부 배포판은 부팅 시 /tmp를 비워 준비된 캐시가 삭제됩니다. 메모리 사용량 줄이기 — 헤드리스 구성에서는 GPU 메모리를 확보하고 사용하지 않는 서비스를 비활성화하세요.

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

안정적인 재시작을 위한 systemd 드롭인 — 이 Pi에서 주로 OpenClaw를 실행한다면 서비스 드롭인을 추가하세요.

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

그런 다음 systemctl --user daemon-reload && systemctl --user restart openclaw-gateway.service를 실행하세요. 헤드리스 Pi에서는 사용자가 로그아웃한 후에도 사용자 서비스가 유지되도록 lingering도 한 번 활성화하세요: sudo loginctl enable-linger "$(whoami)".

권장 모델 설정

Pi는 Gateway만 실행하므로 클라우드 호스팅 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 빌드가 없는 바이너리는 일반적으로 Skills에서 제공하는 선택적 Go/Rust CLI 도구입니다. uname -m으로 아키텍처를 확인한 후(aarch64가 표시되어야 함), 소스에서 직접 빌드하기 전에 누락된 바이너리의 릴리스 페이지에서 linux-arm64 / aarch64 아티팩트가 있는지 확인하세요.

데이터 유지 및 백업

OpenClaw 상태는 다음 경로에 저장됩니다.

~/.openclaw/ — openclaw.json, 에이전트별 auth-profiles.json, 채널/공급자 상태, 세션.
~/.openclaw/workspace/ — 에이전트 작업 공간(SOUL.md, 메모리, 아티팩트).

이 데이터는 재부팅 후에도 유지되며, 성능과 수명 측면에서 SD 카드보다 SSD를 사용하는 것이 좋습니다. 다음 명령으로 이동 가능한 스냅샷을 생성하세요.

openclaw backup create

문제 해결

메모리 부족 — free -h로 스왑이 활성화되어 있는지 확인하세요. 사용하지 않는 서비스를 비활성화하세요(sudo systemctl disable cups bluetooth avahi-daemon). API 기반 모델만 사용하세요. 느린 성능 — SD 카드 대신 USB SSD를 사용하세요. 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 바이너리 문제 — Skills가 “exec format error” 오류와 함께 실패한다면 해당 바이너리에 ARM64 빌드가 있는지 확인하세요. uname -m으로 아키텍처를 확인하세요(aarch64가 표시되어야 함). WiFi 연결 끊김 — WiFi 전원 관리를 비활성화하세요: sudo iwconfig wlan0 power off.

다음 단계

채널 — Telegram, WhatsApp, Discord 등을 연결
Gateway 구성 — 모든 구성 옵션
업데이트 — OpenClaw를 최신 상태로 유지

Install overview

Maintenance

Containers

Hosting

Advanced setup

하드웨어 호환성

사전 요구 사항

설정

성능 최적화 팁

권장 모델 설정

ARM 바이너리 참고 사항

데이터 유지 및 백업

문제 해결

다음 단계

관련 문서

​하드웨어 호환성

​사전 요구 사항

​설정

​성능 최적화 팁

​권장 모델 설정

​ARM 바이너리 참고 사항

​데이터 유지 및 백업

​문제 해결

​다음 단계

​관련 문서

하드웨어 호환성

사전 요구 사항

설정

성능 최적화 팁

권장 모델 설정

ARM 바이너리 참고 사항

데이터 유지 및 백업

문제 해결

다음 단계

관련 문서