OpenClaw 백업 가이드: 데이터 아카이브 생성 및 검증

openclaw backup

열심히 설정해둔 개발 환경이 한순간에 날아갈까 봐 걱정해 본 적 있나요? 공들여 쌓은 state나 복잡한 config를 잃어버리는 건 정말 끔찍한 일이죠. 이럴 때를 대비해 OpenClaw는 아주 간단하고 확실한 백업 방법을 제공해요.

OpenClaw의 state, config, credentials, sessions, 그리고 선택적으로 workspaces까지 포함된 로컬 백업 아카이브를 생성하는 방법을 알아볼게요.

openclaw backup create
openclaw backup create --output ~/Backups
openclaw backup create --dry-run --json
openclaw backup create --verify
openclaw backup create --no-include-workspace
openclaw backup create --only-config
openclaw backup verify ./2026-03-09T00-00-00.000Z-openclaw-backup.tar.gz

참고 사항

• 아카이브에는 소스 경로와 아카이브 레이아웃 정보가 담긴 manifest.json 파일이 포함돼요.
• 기본 출력물은 현재 작업 디렉토리에 타임스탬프가 찍힌 .tar.gz 아카이브로 생성돼요.
• 만약 현재 작업 디렉토리가 백업 대상인 소스 트리 안에 있다면, OpenClaw는 기본 아카이브 위치를 홈 디렉토리로 변경해요.
• 기존에 생성된 아카이브 파일은 절대 덮어쓰지 않아요.
• 자기 자신을 포함하는 문제를 방지하기 위해, 소스 state나 workspace 트리 내부의 출력 경로는 거부돼요.
• openclaw backup verify <archive> 명령은 아카이브에 루트 manifest가 하나만 있는지 확인하고, traversal 스타일의 경로를 거부하며, manifest에 선언된 모든 페이로드가 tarball 안에 실제로 존재하는지 검증해요.
• openclaw backup create --verify를 사용하면 아카이브를 생성한 직후에 바로 이 검증 과정을 실행해요.
• openclaw backup create --only-config 옵션은 현재 활성화된 JSON config 파일만 백업해요.

백업 대상

openclaw backup create 명령은 로컬 OpenClaw 설치 환경에서 다음과 같은 소스들을 백업하도록 계획해요.

• OpenClaw의 로컬 state resolver가 반환하는 state 디렉토리 (보통 ~/.openclaw)
• 활성화된 config 파일 경로
• OAuth 및 credentials 디렉토리
• 현재 config에서 발견된 workspace 디렉토리 (단, --no-include-workspace를 사용하지 않은 경우)

--only-config 옵션을 사용하면 state, credentials, workspace 탐색을 건너뛰고 활성화된 config 파일 경로만 아카이브해요.

OpenClaw는 아카이브를 만들기 전에 경로를 정규화(canonicalize)해요. 만약 config, credentials, workspace가 이미 state 디렉토리 안에 들어있다면, 별도의 상위 백업 소스로 중복해서 만들지 않아요. 존재하지 않는 경로는 알아서 건너뛰고요.

아카이브 페이로드는 이러한 소스 트리에서 가져온 파일 내용들을 저장하며, 함께 포함된 manifest.json에는 각 자산에 사용된 절대 소스 경로와 아카이브 레이아웃이 기록돼요.

유효하지 않은 설정(Config) 시 동작

openclaw backup은 복구 작업 중에도 도움을 줄 수 있도록 일반적인 config preflight 과정을 의도적으로 우회해요. 하지만 workspace 탐색은 유효한 config에 의존하기 때문에, config 파일이 존재하지만 내용이 잘못되었고 workspace 백업이 활성화되어 있다면 openclaw backup create는 즉시 실패하게 돼요.

이런 상황에서 부분적인 백업이라도 만들고 싶다면 다음 명령을 실행해 보세요.

openclaw backup create --no-include-workspace

이렇게 하면 workspace 탐색은 완전히 건너뛰면서 state, config, credentials는 안전하게 챙길 수 있어요.

config 파일 자체가 손상되었을 때 config 파일의 복사본만 필요한 경우에도 --only-config 옵션이 유용해요. 이 옵션은 workspace 탐색을 위해 config를 파싱할 필요가 없기 때문이죠.

크기 및 성능

OpenClaw는 백업 크기나 파일당 크기 제한을 따로 두지 않아요.

실제적인 제한은 로컬 장비와 대상 파일 시스템의 성능에 달려 있어요.

• 임시 아카이브 작성 및 최종 아카이브 저장을 위한 여유 공간
• 대규모 workspace 트리를 탐색하고 .tar.gz로 압축하는 데 걸리는 시간
• openclaw backup create --verify 또는 openclaw backup verify 실행 시 아카이브를 다시 스캔하는 시간
• 대상 경로의 파일 시스템 동작. OpenClaw는 덮어쓰지 않는 hard-link 방식을 선호하며, hard-link를 지원하지 않으면 exclusive copy 방식으로 전환해요.

아카이브 크기가 커지는 주된 원인은 보통 대용량 workspace예요. 더 작고 빠른 백업을 원한다면 --no-include-workspace 옵션을 사용하세요.

가장 가벼운 아카이브가 필요하다면 --only-config가 정답이에요.

AI Setup Assistant

다음 단계

• Restore Guide
• Configuration Reference