메인 콘텐츠로 건너뛰기

​
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 하에 있습니다.

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

​
Step 0 — 백업 만들기 (기존 기기)

기존 기기에서, 게이트웨이를 먼저 중지하십시오, 파일이 복사 중에 변경되지 않도록: 
openclaw gateway stop
(선택 사항이지만 권장) 상태 디렉터리와 작업 공간을 아카이브하세요: 
# 프로필 또는 커스텀 위치를 사용하는 경우 경로 조정
cd ~
tar -czf openclaw-state.tgz .openclaw

tar -czf openclaw-workspace.tgz .openclaw/workspace
여러 프로필/상태 디렉터리 (예: ~/.openclaw-main, ~/.openclaw-work)가 있는 경우 각각 아카이브하십시오.

​
Step 1 — 새 기기에 OpenClaw 설치하기

새로운 기기에서, CLI (필요 시 Node도) 설치하세요: 이 단계에서는 온보딩이 새로운 ~/.openclaw/를 생성해도 괜찮습니다 — 다음 단계에서 덮어쓸 것입니다.

​
Step 2 — 상태 디렉터리 + 작업 공간을 새 기기로 복사하기

둘 다 복사하세요:
  • $OPENCLAW_STATE_DIR (기본값 ~/.openclaw/)
  • 작업 공간 (기본값 ~/.openclaw/workspace/)
일반적인 방법:
  • tarball을 scp로 전송하고 추출
  • rsync -a를 통해 SSH 전송
  • 외장 드라이브 사용
복사 후, 다음을 확인하십시오:
  • 숨김 디렉터리에 포함되었는지 확인 (예: .openclaw/)
  • 게이트웨이를 실행하는 사용자의 파일 소유권이 올바른지 확인

​
Step 3 — 닥터 실행하기 (마이그레이션 + 서비스 복구)

새 기기에서: 
openclaw 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 폴더를 마이그레이션하십시오.

​
실수: 권한 / 소유권

루트로 복사하거나 사용자를 변경한 경우, 게이트웨이가 자격증명/세션을 읽지 못할 수 있습니다. 수정 방법: 상태 디렉터리 + 작업 공간이 게이트웨이를 실행하는 사용자에게 소유되어 있는지 확인하십시오.

​
실수: 원격/로컬 모드 사이의 마이그레이션

  • UI (WebUI/TUI)가 원격 게이트웨이를 가리키는 경우, 원격 호스트가 세션 저장소 + 작업 공간을 소유합니다.
  • 노트북을 마이그레이션해도 원격 게이트웨이의 상태는 이동되지 않습니다.
원격 모드에 있는 경우, 게이트웨이 호스트를 마이그레이션하십시오.

​
실수: 백업의 비밀

$OPENCLAW_STATE_DIR에는 비밀 (API 키, OAuth 토큰, WhatsApp 크레덴셜)이 포함됩니다.백업을 다음과 같이 취급하세요:
  • 암호화하여 저장
  • 안전하지 않은 채널을 통한 공유를 피함
  • 노출이 의심되는 경우 키 회전

​
검증 체크리스트

새 기기에서, 다음을 확인하십시오:
  • openclaw status가 게이트웨이가 실행 중임을 보여줌
  • 채널이 여전히 연결되어 있음 (예: WhatsApp이 재페어링을 요구하지 않음)
  • 대시보드가 열리고 기존 세션이 표시됨
  • 작업 공간 파일 (메모리, 설정)이 존재함

​
관련 문서