OpenClaw 업데이트 가이드

도구가 빠르게 발전하는 것은 반가운 일이지만, 업데이트를 할 때마다 기존 설정이 꼬이거나 서비스가 멈추지는 않을지 걱정될 때가 많습니다. 특히 매일 사용하는 개발 인프라라면 업데이트 과정이 간단하고 명확해야 마음이 편하죠.

OpenClaw는 현재 1.0 릴리스 전 단계로 매우 빠르게 변하고 있습니다. 업데이트를 인프라 배포처럼 생각하고 ‘업데이트 → 체크 → 재시작 → 확인’ 순서를 지키는 것이 좋습니다. 안전하게 최신 버전을 유지하는 방법을 정리해 드릴게요.

필요한 것

업데이트를 시작하기 전에 다음 사항들을 먼저 확인해 주세요.

• 설치 방식 확인: Global 설치(npm/pnpm)인지, Source 설치(git clone)인지 확인이 필요합니다.
• Gateway 실행 방식 확인: 터미널에서 직접 실행 중인지, 서비스(launchd/systemd)로 관리 중인지 확인하세요.
• 데이터 백업: ~/.openclaw/openclaw.json (설정), ~/.openclaw/credentials/ (인증 정보), ~/.openclaw/workspace (워크스페이스)를 미리 복사해 두면 안전합니다.

빠른 시작

가장 권장하는 방법은 웹사이트의 인스톨러를 다시 실행하는 것입니다. 기존 설치를 감지해서 제자리에서 업그레이드하고, 필요한 경우 openclaw doctor까지 알아서 실행해 줍니다.

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

팁:

• 온보딩 가이드를 다시 보고 싶지 않다면 --no-onboard 플래그를 추가하세요.
• Source 설치 사용자는 다음 명령어를 사용하세요:

  curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --no-onboard

업데이트 방법

1. Global 설치 (npm/pnpm)

패키지 매니저를 사용하는 경우 다음 중 하나를 선택해서 실행하세요.

npm i -g openclaw@latest
# 또는
pnpm add -g openclaw@latest

참고: Gateway 런타임으로 Bun을 사용하는 것은 권장하지 않습니다 (WhatsApp/Telegram 관련 버그 발생 가능).

업데이트 채널을 변경하고 싶다면 다음 명령어를 사용하세요:

openclaw update --channel beta
openclaw update --channel dev
openclaw update --channel stable

설치가 끝나면 아래 명령어로 상태를 점검하고 재시작합니다.

openclaw doctor
openclaw gateway restart
openclaw health

2. Source 설치 (git checkout)

리포지토리를 직접 클론해서 사용 중이라면 openclaw update 명령어가 가장 편합니다.

openclaw update

이 명령어는 작업 트리가 깨끗한지 확인한 뒤, 선택된 채널로 전환하고 git pull --rebase를 수행합니다. 이후 의존성 설치, 빌드, openclaw doctor 실행까지 한 번에 처리하고 Gateway를 재시작합니다.

수동으로 진행하고 싶다면 다음 순서를 따르세요:

git pull
pnpm install
pnpm build
pnpm ui:build
openclaw doctor
openclaw health

Always Run: openclaw doctor

업데이트 후에는 항상 openclaw doctor를 실행하는 습관을 들이는 것이 좋습니다. 이 명령어는 다음과 같은 작업을 수행하여 시스템을 안정화합니다.

• 오래된 설정 키나 파일 위치를 최신 기준으로 마이그레이션합니다.
• Gateway 상태를 점검하고 필요한 경우 재시작을 제안합니다.
• 리눅스에서 시스템 종료 후에도 Gateway가 유지되도록 systemd 설정을 확인합니다.
• 보안상 위험할 수 있는 DM 정책 설정을 감사하고 경고를 보냅니다.

문제 해결

업데이트 중 문제가 발생하면 다음 내용을 확인해 보세요.

• 업데이트 실패: openclaw update 실행 시 rebase 오류가 발생하면 Gateway는 업데이트를 적용하지 않고 기존 상태로 재시작합니다. 작업 트리에 커밋되지 않은 변경 사항이 있는지 확인하세요.
• 서비스 재시작 문제: Gateway가 서비스로 실행 중이라면 프로세스를 직접 강제 종료하기보다 openclaw gateway restart 명령어를 사용하는 것이 좋습니다.
• 설치 방식 혼선: Global 설치와 Source 설치 사이를 전환했다면 openclaw doctor를 실행하세요. 현재 설치된 버전에 맞게 서비스 엔트리포인트를 다시 작성해 줍니다.

도움이 더 필요하신가요? AI Setup Assistant에게 질문해 보세요.

다음 단계

• Doctor 상세 가이드
• Gateway 운영 가이드
• 개발 채널 안내
• 문제 해결 FAQ