백업 작업은 성공으로 표시되는데 복원해도 에이전트 상태를 확인할 수 없나요? SQLite와 에이전트 경로, 설정, 자격 증명, 작업 공간을 점검한 뒤 새 격리 경로에서 복원하고 서비스까지 확인해야 백업을 승인할 수 있습니다.
이 글은 OpenClaw 게이트웨이와 에이전트 데이터를 맡은 IT 담당자를 위한 복구 runbook입니다.
원격 맥 실행 환경을 운영하는 플랫폼 담당자와 자격 증명 보호를 맡은 보안 담당자도 복원 범위와 증거를 점검할 수 있습니다.
마지막 검토: 2026년 10월 14일. 버전과 복구 절차는 OpenClaw 공식 릴리스 색인, 백업 및 데이터베이스 문서를 기준으로 대조했습니다.
SECTION 01복구 목표 설정: 파일이 아니라 서비스 상태
복구 목표는 SQLite 파일 하나를 되찾는 일이 아니라, 필요한 데이터와 설정을 갖춘 OpenClaw를 다시 실행할 수 있는 상태입니다. 공식 데이터베이스 배치 문서에 따라 공유 상태와 에이전트별 데이터의 실제 위치를 확인하고, 사용자가 지정한 경로도 별도로 기록하세요.
장애 유형마다 필요한 복구 범위는 다릅니다. 맥 호스트가 손상됐다면 실행 환경과 관련 데이터 전체를 재구성해야 할 수 있지만, 업그레이드 이후 되돌리는 경우에는 버전 호환성 확인이 먼저입니다. 실수로 파일을 삭제했다면 삭제된 항목과 그 항목에 의존하는 설정을 특정해야 합니다.
| 장애 상황 | 먼저 확인할 대상 | 복구 범위 판단 |
|---|---|---|
| 호스트 손상 또는 교체 | 공유 상태, 에이전트별 데이터, 사용자 지정 경로, 설정 | 필요한 실행 환경과 데이터가 모두 보호되는지 확인합니다. |
| 업그레이드 뒤 되돌리기 | 백업 시점의 버전과 데이터 구조 | 복원 전 공식 호환성 안내와 사전 점검을 확인합니다. |
| 데이터나 설정의 오삭제 | 삭제된 항목, 연관된 작업 공간과 자격 증명 | 필요한 항목만 복구해도 서비스 상태가 성립하는지 확인합니다. |
사례: 새 맥으로 옮긴 뒤 공유 데이터베이스는 열리지만, 사용자 지정 경로에 있던 에이전트 작업 공간이 연결되지 않는다면 파일 복원 성공만으로는 인수 검수를 통과할 수 없습니다.
SECTION 02백업 시점: 보호 범위와 방식 대조
공식 OpenClaw 백업 안내는 백업과 복원 경로를 설명하며, CLI 백업 문서는 명령줄 백업 절차를 안내합니다. 문서에 있는 전체 보관, SQLite 스냅샷, 버전 관리 방식은 서로 다른 백업 경로입니다. 하나를 선택했다는 사실만으로 설정 파일, 에이전트 폴더, 자격 증명, 작업 공간까지 모두 포함된다고 단정하지 마세요.
| 백업 선택지 | 검수할 항목 | 단독으로 대체하지 못하는 점 |
|---|---|---|
| 전체 보관 | 문서가 정한 보관 범위와 실제 포함 목록 | 사용자 지정 경로가 범위에 들어가는지 별도 대조해야 합니다. |
| SQLite 스냅샷 | 데이터베이스 백업 절차와 결과물 검증 | 설정, 자격 증명, 작업 공간의 포함 여부는 따로 확인해야 합니다. |
| 버전 관리 백업 경로 | 저장 대상과 버전별 데이터 변경 사항 | 저장소에 없는 외부 파일이나 경로를 자동으로 보호한다고 보장할 수 없습니다. |
실행 중인 SQLite 주 파일을 파일 복사로만 보관하지 마세요. WAL에 기록된 변경 내용과 일관성 문제를 고려해 공식 백업 절차를 따르세요. 데이터베이스별 저장 위치와 변경 이력은 공식 데이터베이스 구조 안내 및 구조 변경 문서에서 확인할 수 있습니다.
백업 목록에는 공유 데이터베이스뿐 아니라 설정된 각 에이전트의 데이터, 사용자 지정 에이전트 디렉터리, 작업 공간, 자격 증명과 인증 설정을 적으세요. 맥을 옮길 때는 기존 경로와 새 호스트의 경로가 달라지는지 확인하고, 새 위치를 복원 절차에 반영해야 합니다.
SECTION 03백업 직후: 산출물과 민감 정보 검증
작업 결과는 다음처럼 구분해 기록하세요.
- 파일이 만들어졌다는 사실은 산출물의 존재만 보여줍니다.
- 공식 절차의 검증을 통과했다는 결과는 해당 검증이 확인하는 항목만 증명합니다.
- 격리 환경에서 서비스가 시작되고 데이터가 확인된 결과가 복원 가능성을 보여주는 핵심 증거입니다.
각 백업에 식별자, 생성 시각, 보호 범위, 저장 위치, 공식 검증 결과를 연결하세요. 자격 증명, 인증 설정, 대화 기록이 포함될 수 있으므로 백업 저장소에도 온라인 상태 디렉터리에 적용하는 접근 제한과 암호화 기준을 적용해야 합니다. 검증이 통과해도 민감 정보가 안전하게 보관된다는 뜻은 아니므로 권한과 저장 정책을 따로 승인하세요.
복원 전 선택 기준
- 백업 대상과 실제 데이터 경로가 모두 일치하면 공식 백업 절차로 복원합니다.
- 데이터베이스만 확인됐고 에이전트 경로나 작업 공간이 확인되지 않았다면, 승인을 보류하고 누락 범위를 보완합니다.
- 대상 OpenClaw 버전이 백업 당시와 다르면, 공식 구조 변경 및 사전 점검 안내를 먼저 확인합니다.
- 백업 검증 결과가 없거나 접근 권한이 불명확하면 운영 복원에 사용하지 말고 격리 환경에서 원인을 확인합니다.
백업 검증 통과, 저장소 권한 승인, 실제 복원 성공은 서로 다른 증거입니다. 한 항목의 성공으로 나머지 검수를 대신하지 마세요.
중간 점검 FAQ
WAL 데이터가 빠지지 않도록 하려면 무엇을 확인해야 하나요?
실행 중인 데이터베이스의 주 파일만 복사하지 말고, OpenClaw의 공식 백업 경로를 사용하세요. 어떤 절차가 WAL과 일관성을 처리하는지는 공식 백업 문서의 지침과 맞춰 확인해야 합니다.
API 자격 증명이나 대화 기록도 백업에 들어가나요?
선택한 백업 방식과 실제 저장 경로를 대조해야 합니다. 자격 증명과 대화 기록이 포함될 수 있다고 보고 접근 제한과 암호화 기준을 적용하되, 문서와 산출물 확인 없이 포함 범위를 단정하지 마세요.
새 맥에서 별도로 대조할 에이전트 데이터는 무엇인가요?
설정에 등록된 모든 에이전트의 저장 경로, 사용자 지정 디렉터리, 작업 공간을 확인하세요. 기존 호스트와 새 호스트의 경로 매핑이 다르면 복원 대상과 서비스 설정이 같은 위치를 가리키는지 검수해야 합니다.
SECTION 04격리 복원 시점: 운영 상태와 분리
복구 시험은 새롭고 비어 있는 임시 경로에서 수행하세요. 운영 중인 상태 디렉터리에 덮어쓰면 원본을 손상시키거나 시험 결과를 구분하기 어려워집니다. 복원 준비 시점부터 활성화까지 다음 순서로 기록합니다.
준비 단계: 백업 식별자와 범위, 검증 결과를 확인합니다. 대상 맥의 OpenClaw 버전과 사용자 지정 에이전트 경로를 대조하고, 필요한 디스크 공간이 확보됐는지 직접 확인합니다. 출처 없는 용량이나 소요 시간 추정은 승인 기준으로 쓰지 마세요.
복원 단계: 운영 데이터와 분리된 새 경로를 지정하고 공식 복원 절차를 따릅니다. 백업이 복원 대상으로 삼는 경로와 새 호스트의 사용자 지정 경로가 일치하는지 확인합니다. 대상 버전이 다르면 구조 변경 관련 사전 점검을 완료하기 전에는 데이터베이스를 활성화하지 마세요.
| 복원 확인 지점 | 통과 증거 | 미통과 시 조치 |
|---|---|---|
| 백업 범위와 경로 | 각 대상이 기록된 범위에 있고 새 경로와 대응합니다. | 경로 목록을 수정하고 다시 복원합니다. |
| 데이터베이스와 보관 구조 | 공식 절차의 검증 결과와 복원 후 상태를 기록합니다. | 운영 활성화를 멈추고 오류와 버전 조건을 확인합니다. |
| 에이전트 자산 | 필요한 에이전트 데이터와 작업 공간을 확인합니다. | 누락 경로와 백업 범위를 보완합니다. |
서비스 확인 단계: 데이터베이스와 파일 확인만으로 끝내지 마세요. 다음 단계에서 필요한 진단을 실행하고, 서비스 쓰기 작업을 통제한 상태로 복원 상태를 전환합니다. 중간에 운영 데이터가 바뀌지 않도록 전환 전후의 대상 경로를 기록하세요.
SECTION 05활성화 전후: 서비스와 외부 의존성 확인
복원 상태를 활성화하기 전에는 관련 쓰기 작업을 멈추고, 공식 복원 절차가 요구하는 진단을 실행하세요. 데이터가 바뀌는 동안 원본과 복원본이 섞이지 않도록 전환 대상을 다시 대조합니다.
시작한 뒤에는 게이트웨이의 건강 상태, 에이전트 목록, 기존 세션의 가시성, 주요 통합을 확인하세요. 데이터베이스 복원 성공은 메시지 채널, 플러그인, 외부 인증까지 복구됐다는 뜻이 아닙니다. 각 외부 의존성은 연결 상태와 인증을 별도 항목으로 검증해야 합니다.
과거 상태로 돌아가면 대기 중이던 승인이나 메시지 중복 방지 상태가 현재 시스템과 달라질 수 있습니다. 정확한 동작은 버전과 복구 대상의 상태에 따라 달라질 수 있으므로, 이를 일반 규칙으로 단정하지 말고 복원 직후 관련 대기 항목과 외부 채널 상태를 확인해 기록하세요.
SECTION 06복구 승인 시점: 증거와 책임자 기록
복구 시험 결과는 다음 항목을 한 기록에 남기세요.
- 백업 식별자와 생성 시각
- 공유 상태, 에이전트별 데이터, 사용자 지정 경로 등 보호 범위
- 백업 산출물 검증 결과와 저장 위치
- 격리 복원 대상, 사용한 버전, 경로 매핑
- 데이터베이스, 에이전트, 세션, 통합별 확인 결과
- 실패 항목, 후속 조치, 승인 책임자
판정은 세 가지로 나눌 수 있습니다. 필요한 데이터와 서비스 확인이 모두 통과했다면 승인합니다. 복구는 가능하지만 문서화나 일부 확인이 부족하다면 담당자와 시정 기한을 지정합니다. 필수 경로 누락, 복원 실패, 외부 의존성의 필수 검증 실패가 남으면 에이전트 작업 부하를 확대하지 말고 백업 범위나 절차를 다시 수정하세요.
현재의 로컬 맥은 물리적 통제와 주변 장치 접근이 필요한 업무에 유리하지만, 장비 조달과 유지 관리, 원격 팀의 실행 환경 제공은 별도로 관리해야 합니다. 원격 실행 환경은 팀이 사용할 맥을 제공하는 방식이 될 수 있지만, 이 글의 검수만으로 MACNOX의 구성, 복구 절차, 서비스 수준을 보증할 수는 없습니다. 먼저 격리 복원 시험을 통과시키고, 지속적으로 실행할 맥 환경이 필요하다면 MACNOX 이용 조건과 가격을 확인한 뒤 맥 이용 신청 정보에서 실제 제공 조건을 검토하세요. 팀에 물리 장비가 필요하거나 장기간 고정 부하를 직접 통제해야 한다면 자체 맥 운영을 비교 대상으로 남겨 두세요.
SECTION 07자주 묻는 질문 FAQ
실행 중인 SQLite 파일을 그대로 복사해도 되나요?
실행 중인 데이터베이스의 주 파일만 복사하면 WAL에 남은 변경 내용이 빠지거나 일관성이 보장되지 않을 수 있습니다. OpenClaw가 안내하는 백업 경로를 사용하고, WAL을 포함한 데이터베이스 처리 방식은 공식 백업 문서에 맞춰 확인하세요. 백업 파일의 존재 여부만으로는 복구 가능성을 입증할 수 없습니다.
복원 뒤 에이전트 대화와 설정은 무엇으로 확인하나요?
격리된 새 경로에서 복원한 뒤 데이터베이스 상태와 설정 파일을 확인하고, 필요한 에이전트 디렉터리와 작업 공간이 실제로 연결되는지 점검하세요. 이어 게이트웨이를 시작해 에이전트와 세션이 보이는지 확인해야 합니다. 채널, 플러그인, 외부 인증까지 정상이라는 뜻은 아니므로 각각 별도 검증 항목으로 기록하세요.
OpenClaw 백업에는 API 자격 증명과 대화 기록도 들어가나요?
백업에 포함되는 항목은 선택한 백업 방식과 실제 데이터 경로에 따라 달라집니다. 데이터베이스, 인증 설정, 자격 증명 파일, 작업 공간을 목록으로 대조하고, 민감 정보가 포함될 수 있다는 전제로 저장소 접근 권한과 암호화 기준을 적용하세요. 범위를 확인하지 않은 채 백업이 모든 비밀 정보를 포함한다고 가정하지 마세요.
맥을 옮길 때 별도로 확인할 에이전트 경로가 있나요?
기본 경로만 확인하지 말고 설정된 각 에이전트의 데이터와 사용자 지정 에이전트 디렉터리, 작업 공간을 대조하세요. 새 맥에서 사용자 지정 경로가 기존 위치와 다르면 복원 대상에 올바르게 매핑되는지 확인해야 합니다. 경로가 누락되거나 권한이 달라지면 파일이 복구되어도 에이전트가 필요한 데이터를 찾지 못할 수 있습니다.