OpenClaw는 빠르게 움직였습니다: Moltbot에서 Clawdbot으로 이름 변경 혼란을 겪은 후 안정적인 정체성을 확립하고 커뮤니티의 채택이 빠르게 증가했습니다. 이 글을 읽고 있다면, 아마도 한 가지 실용적인 결과를 원할 것입니다: 집이나 엣지 환경에서 신뢰할 수 있는 **라즈베리 파이에서 실행되는 안정적인 OpenClaw 노드**입니다.
이 가이드는 심층적인 기술 빌더를 위한 것입니다. OpenClaw를 다음과 같이 설정할 것입니다:
- 재현 가능한 시스템 의존성,
- 서비스 격리,
- 심박수 기반 상태 확인 (값싼 확인 먼저),
- 선택적 모델 호출,
- 선택적 보안 샌드박싱 패턴,
- 그리고 API 수준의 관측 가능성.
이 과정에서 **Apidog**가 OpenClaw 엔드포인트 검증, 회귀 테스트 구축, 팀 사용을 위한 로컬 API 표면 문서화에 어떻게 도움이 되는지 보여드리겠습니다.
1) 설치 전 아키텍처 결정
apt를 건드리기 전에, 라즈베리 파이가 추론 워크플로우를 어떻게 실행할지 결정하세요.
옵션 A: Pi를 오케스트레이터로, 모델은 오프로드
RAM이 제한적인 Raspberry Pi 4/5에 가장 적합합니다.
- OpenClaw는 오케스트레이션, 스케줄링, 플러그인, 심박수를 로컬에서 실행합니다.
- 무거운 LLM 추론은 원격 제공업체 또는 LAN 모델 서버로 라우팅됩니다.
- 낮은 열 부하, 더 나은 가동 시간.
옵션 B: 경량 로컬 모델 전용 Pi
엄격한 프라이버시 및 오프라인 작업에 좋습니다.
- 컴팩트한 모델 (양자화된, 작은 컨텍스트 창)을 사용하세요.
- 무거운 파이프라인과 긴 체인을 제한하세요.
- 지연 시간 트레이드오프를 예상하세요.
옵션 C: 하이브리드 라우팅
가장 실용적인 아키텍처.
- 먼저 저렴한 결정적 확인을 수행합니다.
- 필요할 때만 모델 호출로 확장합니다.
- 낮은 위험의 작업은 로컬로, 높은 복잡도의 작업은 원격으로 라우팅합니다.
이 "저렴한 확인 먼저, 필요할 때만 모델 사용" 패턴은 비용, 열 압력 및 지연 시간 급증을 제어하므로 핵심 OpenClaw 안정성 전략이 되었습니다.
2) 하드웨어 및 OS 기준
권장 하드웨어
- Raspberry Pi 5 (8GB) 권장
- Raspberry Pi 4 (4GB 이상)는 가벼운 워크로드에 적합
- 내구성을 위해 microSD 대신 NVMe 또는 고품질 SSD
- 안정적인 전원 공급 장치 및 액티브 쿨링
OS
Raspberry Pi OS Lite (64비트) 또는 ARM64용 Ubuntu Server 24.04를 사용하세요.
그런 다음 업데이트:
bash sudo apt update && sudo apt upgrade -y sudo reboot
호스트 이름 및 시간 동기화 설정 (로그 및 토큰 만료에 중요):
bash sudo hostnamectl set-hostname openclaw-pi sudo timedatectl set-ntp true
3) 런타임 의존성 설치
OpenClaw 스택은 플러그인에 따라 일반적으로 Python 및/또는 Node 워커를 사용합니다. 진화하는 모듈과 호환성을 유지하기 위해 둘 다 설치하세요.
sudo apt install -y git curl wget jq build-essential pkg-config python3 python3-venv python3-pip nodejs npm redis-server sqlite3버전 확인:
bash python3 --version node --version npm --version redis-server --version
Redis + SQLite를 사용하는 이유는?
- Redis: 낮은 지연 시간의 큐/상태 신호.
- SQLite: 단일 노드 설정에 적합한 경량 로컬 영속성.
나중에 멀티 노드인 경우, 영속성을 Postgres로 마이그레이션하세요.
4) 전용 서비스 사용자 생성
pi 또는 root로 에이전트를 실행하지 마세요.
sudo useradd -m -s /bin/bash openclaw sudo usermod -aG sudo openclaw sudo mkdir -p /opt/openclaw sudo chown -R openclaw:openclaw /opt/openclaw
사용자 전환:
bash sudo su - openclaw cd /opt/openclaw
5) OpenClaw 복제 및 구성
bash git clone https://github.com//.git app cd app
OpenClaw 프로젝트 페이지의 현재 공식 저장소 경로로 바꾸세요.
Python 환경 생성:
python3 -m venv .venv source .venv/bin/activate pip install --upgrade pip pip install -r requirements.txtNode 서비스가 있는 경우:
npm ci환경 템플릿 복사:
cp .env.example .env일반적인 .env 형태:
env OPENCLAW_HOST=0.0.0.0 OPENCLAW_PORT=8080 OPENCLAW_LOG_LEVEL=info
STATE_BACKEND=redis REDIS_URL=redis://127.0.0.1:6379 DB_URL=sqlite:////opt/openclaw/app/data/openclaw.db
MODEL_ROUTER=hybrid LOCAL_MODEL_ENABLED=true REMOTE_MODEL_ENABLED=true REMOTE_MODEL_API_KEY=your_key_here
HEARTBEAT_INTERVAL_SEC=15 HEARTBEAT_TIMEOUT_SEC=5 CHEAP_CHECKS_ENABLED=true
SANDBOX_MODE=on SANDBOX_PROVIDER=process비밀을 보호하려면 chmod 600 .env를 사용하세요.
6) 안정성을 위한 systemd 서비스 추가
/etc/systemd/system/openclaw.service 생성:
ini [Unit] Description=OpenClaw Agent Service After=network-online.target redis.service Wants=network-online.target
[Service] Type=simple User=openclaw WorkingDirectory=/opt/openclaw/app Environment="PYTHONUNBUFFERED=1" ExecStart=/opt/openclaw/app/.venv/bin/python -m openclaw.server Restart=always RestartSec=3 TimeoutStartSec=30 TimeoutStopSec=20기본 강화
NoNewPrivileges=true PrivateTmp=true ProtectSystem=full ProtectHome=true ReadWritePaths=/opt/openclaw/app/data /opt/openclaw/app/logs
[Install] WantedBy=multi-user.target
활성화 및 시작:
sudo systemctl daemon-reload sudo systemctl enable openclaw sudo systemctl start openclaw sudo systemctl status openclaw로그 테일링:
bash journalctl -u openclaw -f
7) 심박수 전략 구현 (저렴한 확인 먼저)
반복되는 커뮤니티의 교훈: 명백한 실패를 감지하기 위해 모델 토큰을 낭비하지 마세요.
권장 계층형 심박수
- L0 프로세스 확인: 서비스 활성 상태, 포트 열림.
- L1 의존성 확인: Redis/DB 도달 가능, 큐 지연 허용 가능.
- L2 결정론적 작업 확인: 정적 유효성 검사 스크립트 실행.
- L3 모델 기반 프로브: 이전 확인이 통과했지만 신뢰도가 낮은 경우에만.
예시 유사 구성:
yaml heartbeat: interval_sec: 15 timeout_sec: 5 stages: - name: process type: tcp target: 127.0.0.1:8080 - name: deps type: internal checks: [redis_ping, db_read] - name: deterministic type: task command: "python scripts/selfcheck.py" - name: model_probe type: llm enabled_on: degraded_only
이 패턴은 제한된 하드웨어에서 가동 시간을 보호하면서 비용과 오탐을 줄입니다.
8) 샌드박스 경계를 사용한 보안 실행
OpenClaw가 도구 (쉘, 브라우저, 파일 쓰기)를 실행하는 경우, 실행을 격리하세요.
Pi에서의 최소 기준:
- 비특권 사용자 하에서 도구 실행,
- 광범위한 파일 시스템 쓰기 거부,
- 디렉토리 화이트리스트 지정,
- 하위 프로세스 타임아웃 및 메모리 제한 설정.
스택이 강화된 샌드박스 (보안 에이전트 샌드박스 모델과 유사)를 지원하는 경우, 신뢰할 수 없는 도구 호출에 사용하세요.
실용적인 보호 장치:
env TOOL_EXEC_TIMEOUT_MS=12000 TOOL_MAX_STDOUT_KB=256 TOOL_ALLOWED_PATHS=/opt/openclaw/app/workdir TOOL_BLOCK_NETWORK_BY_DEFAULT=true
네트워크가 활성화된 도구의 경우, 명시적인 호스트 목록만 허용하세요.
9) Apidog로 OpenClaw API 검증
OpenClaw가 작동하면, 다른 API 제품처럼 다루세요: 계약을 정의하고, 동작을 테스트하며, 회귀를 추적하세요.
여기서 Apidog를 사용하는 이유
Apidog를 사용하여 다음을 수행할 수 있습니다:
- OpenClaw OpenAPI 스펙을 가져오거나 설계,
- 로컬 Pi 엔드포인트에 대해 자동화된 테스트 실행,
- 심박수 페이로드에 대한 시각적 어설션 생성,
- 오프라인 디버깅을 위한 다운스트림 의존성 모의,
- 팀원을 위한 대화형 문서 게시.
예시 상태 엔드포인트 테스트
엔드포인트를 가정:
GET /healthz
예상 응답:
{ "status": "ok", "checks": { "redis": "ok", "db": "ok", "queue_lag_ms": 12 } }
Apidog에서 테스트 시나리오를 생성하세요:
- HTTP 200을 어설션합니다.
status == ok를 어설션합니다.checks.queue_lag_ms < 100을 어설션합니다.- Redis가 중지된 부정적인 환경을 추가하고, 저하된 상태를 예상합니다.
이것은 "괜찮아 보임"을 반복 가능한 API 품질 게이트로 전환합니다.
10) Raspberry Pi 성능 튜닝
CPU 및 열 제어
모니터링:
bash vcgencmd measure_temp uptime top
온도가 안전한 지속 한계를 초과하면 스로틀링으로 인해 추론 지연 시간이 급증할 것입니다.
메모리 압력
필요하다면 zram 또는 적당한 스왑을 활성화하세요. 하지만 실시간 흐름에는 스왑 의존적인 워크로드를 피하세요.
큐 및 동시성
보수적으로 시작:
env WORKER_CONCURRENCY=1 MAX_INFLIGHT_TASKS=4
그런 다음 p95 지연 시간과 오류율을 관찰한 후 늘리세요.
로그 순환
SD/SSD 마모 방지:
bash sudo apt install -y logrotate
/opt/openclaw/app/logs/*.log에 대한 순환 규칙을 추가하세요.
11) 문제 해결 플레이북
서비스가 몇 초마다 불안정하게 작동함
- 잘못된 환경 변수 키 또는 누락된 API 키를 확인하세요.
- venv 내부에서 앱을 수동으로 실행하여 전체 추적을 확인하세요.
bash sudo su - openclaw cd /opt/openclaw/app source .venv/bin/activate python -m openclaw.server
Redis 연결 거부됨
bash sudo systemctl status redis redis-cli ping
PONG이 아니면 OpenClaw를 디버깅하기 전에 Redis를 수정하세요.
몇 분 후 높은 지연 시간 발생
열 스로틀링 또는 메모리 압력일 가능성이 높습니다.
- 모델 컨텍스트를 줄이세요.
- 워커 동시성을 낮추세요.
- 무거운 호출을 원격 모델로 옮기세요.
심박수는 통과하지만 작업이 실패함
확인이 너무 얕습니다. 실제 워크플로우를 모방하는 결정론적 작업 프로브 (파일 읽기, 구문 분석, 요약, 응답 인코딩)를 추가하세요.
12) 거의 프로덕션 수준의 엣지 사용을 위한 강화 체크리스트
- 전용 사용자 (
openclaw), 루트 런타임 없음 - systemd 재시작 정책 및 리소스 제약
- 엄격한 권한을 가진
.env파일의 비밀 - 리버스 프록시를 통한 TLS 종료 (Caddy/Nginx)
- 방화벽 허용 목록 (LAN/VPN만)
- 모델 프로브 확장이 있는 심박수 계층
- 도구 샌드박스 제한
- Apidog의 API 계약 테스트
- 구성 변경을 위한 CI/CD의 자동화된 테스트 실행
백엔드, QA, 프론트엔드 팀 간에 협업하는 경우, OpenClaw API 스펙을 공유 Apidog 워크스페이스에 넣으세요. 그러면 스키마 변경, 테스트, 모의 및 문서를 도구 전반에 걸쳐 흩뿌리지 않고 동기화 상태로 유지할 수 있습니다.
13) 노출해야 할 예시 엔드포인트 맵
표면을 작고 명시적으로 유지하세요:
GET /healthz— 기본 상태GET /readyz— 의존성 준비 상태GET /metrics— Prometheus 호환 메트릭POST /v1/tasks— 작업 제출GET /v1/tasks/{id}— 상태 폴링POST /v1/chat/completions— 선택적 호환성 엔드포인트
이것들을 OpenAPI에 문서화하세요. 그런 다음 Apidog의 스키마 우선 워크플로우를 사용하여 응답 일관성을 강제하고 OpenClaw 모듈이 진화할 때 소비자를 중단시키는 것을 방지하세요.
결론
제약을 고려하여 설계하면 라즈베리 파이에서 OpenClaw를 실행하는 것이 완전히 가능합니다:
- 로컬에서 오케스트레이션하고, 선택적으로 추론합니다.
- 저렴한 확인 우선으로 심박수 계층을 사용합니다.
- 도구 실행을 샌드박싱합니다.
- 로컬 에이전트를 테스트 및 문서가 있는 실제 API 서비스로 다룹니다.
이 조합은 일상적인 자동화에 충분히 저렴하고, 비공개적이며, 안정적인 노드를 제공합니다.
다음 단계로 깔끔하게 나아가고 싶다면, OpenClaw 엔드포인트를 Apidog로 가져와 오늘 healthz, readyz, 그리고 하나의 종단 간 작업 흐름이라는 세 가지 자동화된 테스트를 생성하세요. 이렇게 하면 회귀를 조기에 감지하고 에이전트 스택이 성장함에 따라 Pi 배포를 신뢰할 수 있게 유지할 수 있습니다.