라즈베리 파이에 OpenClaw 설치 및 실행 튜토리얼

들어가며

라즈베리 파이는 OpenClaw를 실행하기에 경제적인 선택입니다. 저전력, 소형 크기로 24시간 연중무휴 운영에 전혀 부담이 없습니다. 본 문서에서는 라즈베리 파이 4 또는 라즈베리 파이 5에서 OpenClaw를 배포하여 전용 AI 어시스턴트 서버를 구축하는 방법을 상세히 안내합니다.

하드웨어 요구 사항

모델	실행 경험	설명
라즈베리 파이 5 (8GB)	원활	권장 모델, 충분한 성능
라즈베리 파이 5 (4GB)	양호	기본 요구 사항 충족
라즈베리 파이 4 (8GB)	양호	가성비 좋은 선택
라즈베리 파이 4 (4GB)	사용 가능	불필요한 서비스 비활성화 권장
라즈베리 파이 4 (2GB)	간신히	비권장, 메모리 부족

기타 부품

MicroSD 카드: 최소 16GB, 32GB Class 10 이상 권장
전원 어댑터: 라즈베리 파이 5는 5V/5A USB-C, 라즈베리 파이 4는 5V/3A USB-C 필요
방열판 또는 팬 (장시간 운영 시 저온 유지를 위해 권장)
이더넷 케이블 또는 Wi-Fi 연결

1단계: 운영 체제 준비

시스템 이미지 굽기

OpenClaw는 그래픽 인터페이스가 필요 없으므로 Raspberry Pi OS Lite(64비트) 사용을 권장합니다.

Raspberry Pi Imager를 다운로드합니다
MicroSD 카드를 삽입합니다
운영 체제 선택: Raspberry Pi OS Lite (64-bit)
고급 설정에서 다음을 구성합니다:
- 호스트명 (예: openclaw)
- SSH 로그인 (활성화 및 비밀번호 또는 키 설정)
- Wi-Fi 정보 (이더넷 케이블을 사용하지 않는 경우)
- 시간대 및 언어
"쓰기"를 클릭하여 굽기를 완료합니다

첫 부팅 및 연결

MicroSD 카드를 라즈베리 파이에 삽입하고 전원을 연결합니다. 약 1분 후 SSH로 연결합니다.

ssh [email protected]
# 또는 IP 주소 사용
ssh [email protected]

시스템 업데이트

sudo apt update && sudo apt upgrade -y

2단계: Node.js 22 (ARM) 설치

라즈베리 파이는 ARM 아키텍처 프로세서를 사용하므로 ARM 버전의 Node.js를 설치해야 합니다.

방법 1: NodeSource 저장소 사용 (권장)

# NodeSource 저장소 추가
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -

# Node.js 설치
sudo apt install -y nodejs

# 설치 확인
node --version
npm --version

방법 2: nvm 사용

# nvm 설치
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc

# Node.js 22 설치
nvm install 22
nvm alias default 22

# 확인
node --version

아키텍처 확인

Node.js가 ARM64 아키텍처에서 정상 작동하는지 확인합니다.

node -e "console.log(process.arch)"
# 출력: arm64

3단계: OpenClaw 설치

sudo npm install -g openclaw@latest

설치 확인:

openclaw --version

4단계: 초기 구성

openclaw onboard

구성 마법사에서 모델과 채널 설정을 완료합니다. 라즈베리 파이의 성능이 제한적이므로 몇 가지 권장 사항이 있습니다.

모델 선택: 로컬 모델 대신 클라우드 API(Claude, OpenAI, Gemini) 사용을 권장합니다
채널 수: 초기에는 너무 많은 채널을 동시에 연동하지 말고 실제 부하에 따라 점진적으로 추가하십시오
로그 레벨: 디스크 쓰기를 줄이기 위해 warn으로 설정하는 것을 권장합니다

구성 파일 위치:

~/.config/openclaw/openclaw.json5

5단계: 시작 및 테스트

openclaw up

진단을 실행하여 모든 것이 정상인지 확인합니다.

openclaw doctor

6단계: systemd 자동 시작 설정

라즈베리 파이에서 systemd를 사용하여 OpenClaw 서비스를 관리하는 것이 가장 좋은 방법입니다.

systemd 서비스 파일 생성

sudo tee /etc/systemd/system/openclaw.service > /dev/null << 'EOF'
[Unit]
Description=OpenClaw AI Assistant Platform
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=pi
Group=pi
WorkingDirectory=/home/pi
ExecStart=/usr/bin/openclaw up
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal
Environment=NODE_ENV=production

# 리소스 제한 (선택 사항)
MemoryMax=1G
CPUQuota=80%

[Install]
WantedBy=multi-user.target
EOF

nvm으로 설치한 Node.js를 사용하는 경우 ExecStart의 경로를 전체 경로로 수정해야 합니다.

# openclaw 실제 경로 찾기
which openclaw
# 예: /home/pi/.nvm/versions/node/v22.x.x/bin/openclaw

서비스 활성화 및 시작

# systemd 구성 리로드
sudo systemctl daemon-reload

# 부팅 시 자동 시작 활성화
sudo systemctl enable openclaw

# 서비스 시작
sudo systemctl start openclaw

# 상태 확인
sudo systemctl status openclaw

로그 확인

# 실시간 로그 확인
sudo journalctl -u openclaw -f

# 최근 100줄 확인
sudo journalctl -u openclaw -n 100

성능 최적화

메모리 사용량 줄이기

/etc/systemd/system/openclaw.service를 편집하고 ExecStart에 Node.js 메모리 매개변수를 추가합니다.

ExecStart=/usr/bin/node --max-old-space-size=512 /usr/bin/openclaw up

swap으로 메모리 확장

메모리가 부족한 경우 swap 공간을 늘릴 수 있습니다.

# 기본 swap 비활성화
sudo dphys-swapfile swapoff

# swap 크기를 1GB로 변경
sudo sed -i 's/CONF_SWAPSIZE=.*/CONF_SWAPSIZE=1024/' /etc/dphys-swapfile

# 재초기화 및 활성화
sudo dphys-swapfile setup
sudo dphys-swapfile swapon

# 확인
free -h

SD 카드 쓰기 줄이기

잦은 쓰기는 SD 카드 수명을 단축시키므로 다음을 권장합니다.

# 임시 파일 디렉토리를 메모리에 마운트
echo 'tmpfs /tmp tmpfs defaults,noatime,nosuid,nodev,size=100m 0 0' | sudo tee -a /etc/fstab

# 로그 쓰기 빈도 줄이기
sudo sed -i 's/#Storage=auto/Storage=volatile/' /etc/systemd/journald.conf
sudo sed -i 's/#RuntimeMaxUse=/RuntimeMaxUse=50M/' /etc/systemd/journald.conf
sudo systemctl restart systemd-journald

불필요한 서비스 비활성화

# 블루투스 비활성화 (필요 없는 경우)
sudo systemctl disable bluetooth
sudo systemctl stop bluetooth

# avahi 비활성화 (.local 도메인 해석이 필요 없는 경우)
sudo systemctl disable avahi-daemon
sudo systemctl stop avahi-daemon

온도 모니터링

장시간 운영 시 CPU 온도 모니터링을 권장합니다.

# 현재 온도 확인
vcgencmd measure_temp

# 정기 모니터링 스크립트 설정
cat > ~/check_temp.sh << 'SCRIPT'
#!/bin/bash
TEMP=$(vcgencmd measure_temp | grep -oP '\d+\.\d+')
if (( $(echo "$TEMP > 75" | bc -l) )); then
    echo "[WARNING] CPU 온도가 너무 높습니다: ${TEMP}°C"
fi
SCRIPT
chmod +x ~/check_temp.sh

# crontab에 추가하여 5분마다 확인
(crontab -l 2>/dev/null; echo "*/5 * * * * ~/check_temp.sh >> ~/temp.log") | crontab -

온도가 지속적으로 높은 경우 (70°C 초과) 방열판과 팬을 설치하십시오.

헤드리스 모드 운영 팁

라즈베리 파이는 보통 헤드리스 모드(모니터 없이)로 운영되며, 다음 팁이 유용합니다.

tmux를 사용한 세션 관리

# tmux 설치
sudo apt install -y tmux

# OpenClaw 전용 세션 생성
tmux new-session -d -s openclaw 'openclaw up'

# 세션에 연결하여 출력 확인
tmux attach -t openclaw

# 세션 분리 (Ctrl+B 후 D 누르기)

고정 IP 설정

/etc/dhcpcd.conf에 다음을 추가합니다.

interface eth0
static ip_address=192.168.1.100/24
static routers=192.168.1.1
static domain_name_servers=8.8.8.8 8.8.4.4

그런 다음 네트워크를 재시작합니다.

sudo systemctl restart dhcpcd

문제 해결

문제	해결 방법
npm install에서 메모리 부족 오류	swap을 1GB 이상으로 늘리기
시작 후 즉시 충돌	`journalctl -u openclaw` 로그 확인
네트워크 연결 시간 초과	DNS 설정 및 방화벽 확인
SD 카드 읽기 전용	파일 시스템 손상, `fsck` 복구 시도
CPU 온도 과열	방열판 설치, CPUQuota 낮추기

마무리

라즈베리 파이는 OpenClaw를 실행하기에 훌륭한 선택입니다. 저전력, 저비용으로 24시간 안정적으로 운영할 수 있습니다. systemd 자동 시작과 적절한 성능 최적화를 결합하면 라즈베리 파이 AI 어시스턴트 서버가 장기간 안정적으로 작동합니다. 최상의 경험을 위해 라즈베리 파이 5 (8GB) 사용을 권장합니다.