OpenClaw를 새 머신으로 마이그레이션

이 가이드는 온보딩을 다시 하지 않고 OpenClaw 게이트웨이를 한 머신에서 다른 머신으로 마이그레이션합니다.

개념적으로는 간단합니다:

상태 디렉토리 ($OPENCLAW_STATE_DIR, 기본값: ~/.openclaw/)를 복사합니다. 설정, 인증, 세션, 채널 상태가 포함됩니다.
워크스페이스 (기본값 ~/.openclaw/workspace/)를 복사합니다. 에이전트 파일(메모리, 프롬프트 등)이 포함됩니다.

하지만 프로필, 권한, 부분 복사 관련 흔한 함정들이 있습니다.

시작 전 (마이그레이션 대상 파악)

1) 상태 디렉토리 확인

대부분의 설치는 기본값을 사용합니다:

상태 디렉토리: ~/.openclaw/

하지만 다음을 사용하는 경우 다를 수 있습니다:

--profile <name> (보통 ~/.openclaw-<profile>/이 됨)
OPENCLAW_STATE_DIR=/some/path

확실하지 않다면 이전 머신에서 실행합니다:

openclaw status

출력에서 OPENCLAW_STATE_DIR / 프로필 관련 언급을 찾으세요. 여러 게이트웨이를 운영한다면 각 프로필에 대해 반복하세요.

2) 워크스페이스 확인

일반적인 기본값:

~/.openclaw/workspace/ (권장 워크스페이스)
직접 생성한 커스텀 폴더

워크스페이스에는 MEMORY.md, USER.md, memory/*.md 같은 파일들이 있습니다.

3) 보존되는 항목 이해

상태 디렉토리와 워크스페이스 둘 다 복사하면 다음이 유지됩니다:

게이트웨이 설정 (openclaw.json)
인증 프로필 / API 키 / OAuth 토큰
세션 이력 + 에이전트 상태
채널 상태 (예: WhatsApp 로그인/세션)
워크스페이스 파일 (메모리, 스킬 노트 등)

워크스페이스만 복사하면(예: Git을 통해) 다음은 유지되지 않습니다:

세션
인증 정보
채널 로그인

이것들은 $OPENCLAW_STATE_DIR 아래에 있습니다.

마이그레이션 단계 (권장)

0단계 — 백업 (이전 머신)

이전 머신에서 파일이 복사 중에 변경되지 않도록 먼저 게이트웨이를 중지합니다:

openclaw gateway stop

(선택이지만 권장) 상태 디렉토리와 워크스페이스를 아카이브합니다:

# 프로필이나 커스텀 위치를 사용하는 경우 경로를 조정하세요
cd ~
tar -czf openclaw-state.tgz .openclaw

tar -czf openclaw-workspace.tgz .openclaw/workspace

여러 프로필/상태 디렉토리(예: ~/.openclaw-main, ~/.openclaw-work)가 있다면 각각 아카이브하세요.

1단계 — 새 머신에 OpenClaw 설치

새 머신에서 CLI(필요하면 Node도)를 설치합니다:

참고: 설치

이 단계에서 온보딩이 새 ~/.openclaw/를 생성해도 괜찮습니다. 다음 단계에서 덮어씁니다.

2단계 — 상태 디렉토리 + 워크스페이스를 새 머신으로 복사

둘 다 복사합니다:

$OPENCLAW_STATE_DIR (기본값 ~/.openclaw/)
워크스페이스 (기본값 ~/.openclaw/workspace/)

일반적인 방법:

scp로 타르볼 전송 후 추출
SSH를 통한 rsync -a
외장 드라이브

복사 후 확인 사항:

숨김 디렉토리가 포함되었는지 (예: .openclaw/)
게이트웨이를 실행하는 사용자에 맞게 파일 소유권이 올바른지

3단계 — Doctor 실행 (마이그레이션 + 서비스 수리)

새 머신에서:

openclaw doctor

Doctor는 “안전하고 지루한” 명령어입니다. 서비스를 수리하고, 설정 마이그레이션을 적용하고, 불일치를 경고합니다.

이후:

openclaw gateway restart
openclaw status

흔한 함정 (그리고 방지 방법)

함정: 프로필 / 상태 디렉토리 불일치

이전 게이트웨이를 프로필(또는 OPENCLAW_STATE_DIR)로 실행했는데 새 게이트웨이가 다른 것을 사용하면 다음과 같은 증상이 나타납니다:

설정 변경이 적용되지 않음
채널 누락 / 로그아웃됨
빈 세션 이력

수정: 마이그레이션한 것과 동일한 프로필/상태 디렉토리로 게이트웨이/서비스를 실행한 뒤 다시 실행합니다:

openclaw doctor

함정: `openclaw.json`만 복사

openclaw.json만으로는 부족합니다. 많은 프로바이더가 다음 위치에 상태를 저장합니다:

$OPENCLAW_STATE_DIR/credentials/
$OPENCLAW_STATE_DIR/agents/<agentId>/...

항상 $OPENCLAW_STATE_DIR 폴더 전체를 마이그레이션하세요.

함정: 권한 / 소유권

root로 복사했거나 사용자를 변경한 경우, 게이트웨이가 인증 정보/세션을 읽지 못할 수 있습니다.

수정: 상태 디렉토리 + 워크스페이스가 게이트웨이를 실행하는 사용자 소유인지 확인하세요.

함정: 원격/로컬 모드 간 마이그레이션

UI(WebUI/TUI)가 원격 게이트웨이를 가리키면 원격 호스트가 세션 저장소 + 워크스페이스를 소유합니다.
노트북을 마이그레이션해도 원격 게이트웨이의 상태는 옮겨지지 않습니다.

원격 모드라면 게이트웨이 호스트를 마이그레이션하세요.

함정: 백업 속 시크릿

$OPENCLAW_STATE_DIR에는 시크릿(API 키, OAuth 토큰, WhatsApp 인증 정보)이 포함됩니다. 백업을 프로덕션 시크릿처럼 취급하세요:

암호화하여 저장
안전하지 않은 채널로 공유 금지
노출 의심 시 키 로테이션

검증 체크리스트

새 머신에서 확인:

openclaw status에서 게이트웨이가 실행 중으로 표시
채널이 여전히 연결되어 있음 (예: WhatsApp이 재페어링 불필요)
대시보드가 열리고 기존 세션이 표시됨
워크스페이스 파일(메모리, 설정)이 존재함