OpenClaw 버전 업그레이드 및 업데이트 튜토리얼

들어가며

OpenClaw는 활발한 오픈소스 프로젝트(GitHub 100k+ stars)로 버전 업데이트가 빈번하며, 새 버전에는 일반적으로 기능 개선, 성능 최적화 및 보안 수정이 포함됩니다. 본 문서에서는 안전하게 버전을 업그레이드하는 방법, 업데이트 전 준비 작업, 다양한 설치 방식별 업데이트 방법, 그리고 문제 발생 시 롤백 전략을 소개합니다.

업그레이드 전 준비

업그레이드 작업을 수행하기 전에 반드시 다음 준비 작업을 완료하십시오.

현재 버전 확인

openclaw --version

최신 버전 및 변경 로그 확인

# npm에서 최신 버전 확인
npm view openclaw version

# 모든 사용 가능한 버전 확인
npm view openclaw versions --json

# 변경 로그 확인
npm view openclaw changelog

GitHub의 Releases 페이지에서도 각 버전의 상세 업데이트 설명을 확인할 수 있습니다.

https://github.com/openclaw/openclaw/releases

현재 구성 점검

현재 실행 상태가 정상인지 확인합니다.

openclaw doctor

구성 및 데이터 백업

가장 중요한 단계이므로 건너뛰지 마십시오.

# 백업 디렉토리 생성
mkdir -p ~/openclaw-backup/$(date +%Y%m%d)

# 구성 파일 백업
cp -r ~/.config/openclaw ~/openclaw-backup/$(date +%Y%m%d)/config

# 스킬 파일 백업
cp -r ~/.openclaw ~/openclaw-backup/$(date +%Y%m%d)/openclaw-data

# 현재 버전 번호 기록
openclaw --version > ~/openclaw-backup/$(date +%Y%m%d)/version.txt

echo "백업 완료: ~/openclaw-backup/$(date +%Y%m%d)"

향후 편리하게 사용할 수 있도록 간단한 백업 스크립트를 작성할 수도 있습니다.

cat > ~/openclaw-backup.sh << 'EOF'
#!/bin/bash
BACKUP_DIR="$HOME/openclaw-backup/$(date +%Y%m%d_%H%M%S)"
mkdir -p "$BACKUP_DIR"
cp -r ~/.config/openclaw "$BACKUP_DIR/config" 2>/dev/null
cp -r ~/.openclaw "$BACKUP_DIR/openclaw-data" 2>/dev/null
openclaw --version > "$BACKUP_DIR/version.txt" 2>/dev/null
echo "백업이 저장되었습니다: $BACKUP_DIR"
EOF
chmod +x ~/openclaw-backup.sh

npm 방식 업데이트

최신 버전으로 업데이트

# OpenClaw 중지
openclaw restart  # 또는 먼저 수동으로 중지

# 최신 버전으로 업데이트
npm install -g openclaw@latest

# 버전 확인
openclaw --version

# 재시작
openclaw up

특정 버전으로 업데이트

최신 버전으로 바로 이동하고 싶지 않다면 특정 버전 번호를 지정할 수 있습니다.

npm install -g [email protected]

사용 가능한 업데이트 확인

npm outdated -g openclaw

출력 예시:

Package    Current  Wanted  Latest  Location
openclaw   2.4.3    2.5.1   2.5.1   global

• Current: 현재 설치된 버전
• Wanted: 버전 범위를 만족하는 최신 버전
• Latest: npm의 최신 버전

Homebrew 방식 업데이트

Homebrew로 설치한 경우 업데이트 과정이 매우 간단합니다.

# Homebrew 인덱스 업데이트
brew update

# OpenClaw 업데이트 가용 여부 확인
brew outdated openclaw

# OpenClaw 업그레이드
brew upgrade openclaw

# 서비스 재시작
openclaw restart

Docker 방식 업데이트

Docker 이미지 업데이트

# 최신 이미지 풀
docker pull openclaw/openclaw:latest

# 기존 컨테이너 중지 및 삭제
docker stop openclaw
docker rm openclaw

# 새 이미지로 컨테이너 재생성
docker run -d \
  --name openclaw \
  --restart always \
  -p 18789:18789 \
  -v /path/to/config:/app/config \
  -v /path/to/data:/app/data \
  -e OPENCLAW_CONFIG=/app/config/openclaw.json5 \
  -e TZ=Asia/Shanghai \
  openclaw/openclaw:latest

docker-compose 방식 업데이트

cd /path/to/openclaw-compose

# 최신 이미지 풀
docker-compose pull

# 컨테이너 재생성
docker-compose up -d

# 이전 이미지 정리
docker image prune -f

특정 Docker 버전으로 업데이트

docker pull openclaw/openclaw:2.5.0

그런 다음 docker-compose.yml의 image 태그를 수정하거나 docker run 명령어에서 버전 번호를 지정합니다.

업그레이드 후 검증

어떤 방식으로 업그레이드하든 완료 후 검증을 수행해야 합니다.

# 버전 번호 확인
openclaw --version

# 진단 실행
openclaw doctor

# 로그에 오류가 있는지 확인
openclaw logs

# Dashboard 접근 가능 여부 테스트
curl -s http://localhost:18789/health

검증 체크리스트

이전 버전으로 롤백

새 버전에 문제가 발생하면 빠르게 롤백할 수 있습니다.

npm 롤백

# 특정 이전 버전 설치
npm install -g [email protected]

# 백업한 구성 파일 복원
cp -r ~/openclaw-backup/20260318/config/* ~/.config/openclaw/

# 재시작
openclaw restart

Docker 롤백

# 이전 버전 이미지로 컨테이너 재생성
docker stop openclaw
docker rm openclaw
docker run -d \
  --name openclaw \
  --restart always \
  -p 18789:18789 \
  -v /path/to/config:/app/config \
  -v /path/to/data:/app/data \
  openclaw/openclaw:2.4.3

Homebrew 롤백

Homebrew는 직접적인 롤백을 지원하지 않지만, npm을 통해 특정 버전을 설치할 수 있습니다.

brew uninstall openclaw
npm install -g [email protected]

자동 업데이트 전략

cron을 사용한 정기 업데이트 확인

업데이트 확인 스크립트를 생성합니다.

cat > ~/openclaw-check-update.sh << 'SCRIPT'
#!/bin/bash
CURRENT=$(openclaw --version 2>/dev/null)
LATEST=$(npm view openclaw version 2>/dev/null)

if [ "$CURRENT" != "$LATEST" ]; then
    echo "[$(date)] OpenClaw 새 버전 사용 가능: $CURRENT -> $LATEST"
    # 선택 사항: 알림 전송
fi
SCRIPT
chmod +x ~/openclaw-check-update.sh

# 매일 한 번 확인
(crontab -l 2>/dev/null; echo "0 9 * * * ~/openclaw-check-update.sh >> ~/openclaw-update.log") | crontab -

Docker Watchtower 자동 업데이트

Watchtower를 사용하면 Docker 컨테이너를 자동으로 업데이트할 수 있습니다.

docker run -d \
  --name watchtower \
  --restart always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower \
  --interval 86400 \
  openclaw

이렇게 하면 24시간마다 OpenClaw 이미지 업데이트를 확인하고 자동으로 새 이미지를 풀하여 컨테이너를 재시작합니다.

메이저 버전 업그레이드 주의 사항

메이저 버전 업그레이드(예: 1.x에서 2.x)를 수행할 때는 특히 주의해야 합니다.

1. Release Notes를 꼼꼼히 읽기 — 메이저 버전에는 일반적으로 호환성을 깨는 변경 사항이 포함됩니다
2. 구성 파일 형식 변경 사항 확인 — 새 버전에서 구성 파일 구조가 변경될 수 있습니다
3. 구성 마이그레이션 도구 실행 (있는 경우):

openclaw migrate

4. 테스트 환경에서 먼저 검증 — 프로덕션 환경이 아닌 곳에서 새 버전을 테스트합니다
5. 롤백 방안 준비 — 완전한 백업이 있는지 확인합니다

업데이트 주기 권장 사항

마무리

버전 업그레이드는 OpenClaw를 안정적이고 안전하게 운영하기 위한 중요한 과정입니다. 핵심 원칙은 백업 우선, 검증 후속, 롤백 대비입니다. 정기적으로 업데이트를 확인하는 습관을 기르고 보안 취약점을 적시에 수정하되, 무분별하게 최신 버전을 추구하여 프로덕션 환경의 안정성에 영향을 주지 않도록 하십시오.