English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Maintenance

마이그레이션 가이드

OpenClaw는 세 가지 마이그레이션 경로를 지원합니다. 다른 에이전트 시스템에서 가져오기, 기존 설치를 새 머신으로 이동하기, Plugin을 제자리에서 업그레이드하기입니다.

다른 에이전트 시스템에서 가져오기

번들로 제공되는 마이그레이션 제공자를 사용해 지침, MCP 서버, skills, 모델 구성, 그리고 (선택 사항) API 키를 OpenClaw로 가져오세요. 모든 변경 전에 계획을 미리 볼 수 있고, 보고서에서는 비밀 정보가 마스킹되며, 적용 작업은 검증된 백업으로 보호됩니다.

Migrating from Claude

CLAUDE.md, MCP 서버, skills, 프로젝트 명령을 포함해 Claude Code와 Claude Desktop 상태를 가져옵니다.
Migrating from Hermes

Hermes 구성, 제공자, MCP 서버, 메모리, skills, 지원되는 .env 키를 가져옵니다.

CLI 진입점은 openclaw migrate입니다. 온보딩은 알려진 원본을 감지하면 마이그레이션을 제안할 수도 있습니다(openclaw onboard --flow import).

OpenClaw를 새 머신으로 이동하기

다음을 보존하려면 상태 디렉터리(기본값은 ~/.openclaw/)와 작업공간을 복사하세요.

  • 구성 — openclaw.json 및 모든 Gateway 설정.
  • 인증 — 에이전트별 auth-profiles.json(API 키와 OAuth 포함), 그리고 credentials/ 아래의 모든 채널 또는 제공자 상태.
  • 세션 — 대화 기록 및 에이전트 상태.
  • 채널 상태 — WhatsApp 로그인, Telegram 세션 등.
  • 작업공간 파일 — MEMORY.md, USER.md, skills, 프롬프트.

마이그레이션 단계

  • Stop the gateway and back up

    이전 머신에서 파일이 복사 중에 변경되지 않도록 Gateway를 중지한 다음 아카이브를 만드세요.

    openclaw gateway stop
cd ~
tar -czf openclaw-state.tgz .openclaw

    여러 프로필을 사용하는 경우(예: ~/.openclaw-work) 각각을 별도로 아카이브하세요.

  • Install OpenClaw on the new machine

    새 머신에 CLI(필요한 경우 Node도)를 설치하세요. 온보딩이 새 ~/.openclaw/를 만들어도 괜찮습니다. 다음 단계에서 덮어쓰게 됩니다.

  • Copy state directory and workspace

    scp, rsync -a 또는 외장 드라이브를 통해 아카이브를 전송한 다음 압축을 풉니다.

    cd ~
tar -xzf openclaw-state.tgz

    숨김 디렉터리가 포함되었는지, 파일 소유권이 Gateway를 실행할 사용자와 일치하는지 확인하세요.

  • Run doctor and verify

    새 머신에서 진단을 실행해 구성 마이그레이션을 적용하고 서비스를 복구합니다.

    openclaw doctor
openclaw gateway restart
openclaw status

    • Telegram 또는 Discord가 기본 env 폴백(TELEGRAM_BOT_TOKEN 또는 DISCORD_BOT_TOKEN)을 사용하는 경우, 마이그레이션된 상태 디렉터리 .env에 해당 키가 있는지 비밀 값을 출력하지 않고 확인합니다.

    awk -F= '/^(TELEGRAM_BOT_TOKEN|DISCORD_BOT_TOKEN)=/ { print $1 "=present" }' ~/.openclaw/.env

    openclaw doctor는 활성화된 기본 Telegram 또는 Discord 계정에 구성된 토큰이 없고 일치하는 env 변수를 doctor 프로세스에서 사용할 수 없을 때도 경고합니다.

    일반적인 문제

    Profile or state-dir mismatch

    이전 Gateway가 --profile 또는 OPENCLAW_STATE_DIR를 사용했지만 새 Gateway가 그렇지 않다면, 채널이 로그아웃된 것처럼 보이고 세션이 비어 있게 됩니다. 마이그레이션한 동일한 프로필 또는 상태 디렉터리로 Gateway를 시작한 다음 openclaw doctor를 다시 실행하세요.

    Copying only openclaw.json

    구성 파일만으로는 충분하지 않습니다. 모델 인증 프로필은 agents/<agentId>/agent/auth-profiles.json 아래에 있고, 채널 및 공급자 상태는 credentials/ 아래에 있습니다. 항상 전체 상태 디렉터리를 마이그레이션하세요.

    Permissions and ownership

    root로 복사했거나 사용자를 전환했다면 Gateway가 자격 증명을 읽지 못할 수 있습니다. 상태 디렉터리와 작업 영역을 Gateway를 실행하는 사용자가 소유하도록 하세요.

    Remote mode

    UI가 원격 Gateway를 가리키는 경우, 원격 호스트가 세션과 작업 영역을 소유합니다. 로컬 노트북이 아니라 Gateway 호스트 자체를 마이그레이션하세요. FAQ를 참고하세요.

    Secrets in backups

    상태 디렉터리에는 인증 프로필, 채널 자격 증명, 기타 공급자 상태가 포함되어 있습니다. 백업은 암호화해서 저장하고, 안전하지 않은 전송 채널을 피하며, 노출이 의심되면 키를 교체하세요.

    확인 체크리스트

    새 머신에서 다음을 확인합니다.

    • [ ] openclaw status에 Gateway가 실행 중으로 표시됩니다.
    • [ ] 채널이 여전히 연결되어 있습니다(다시 페어링할 필요 없음).
    • [ ] 대시보드가 열리고 기존 세션이 표시됩니다.
    • [ ] 작업 영역 파일(메모리, 구성)이 존재합니다.

    Plugin을 제자리에서 업그레이드

    제자리 Plugin 업그레이드는 동일한 Plugin id와 구성 키를 유지하지만, 온디스크 상태를 현재 레이아웃으로 이동할 수 있습니다. Plugin별 업그레이드 가이드는 해당 채널 옆에 있습니다.

    관련 항목