Migration guide

Migration guide 문서는 OpenClaw 공식 문서(install/migrating)를 한국어로 정리한 가이드입니다. Migration hub: cross-system imports, machine-to-machine moves, and plugin upgrades 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Migration hub: cross-system imports, machine-to-machine moves, and plugin upgrades

한국어 가이드 범위: install/migrating 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Import from another agent system
Move OpenClaw to a new machine
Migration steps
Common pitfalls
Verification checklist
Upgrade a plugin in place
관련 문서

상세 내용

본문

OpenClaw supports three migration paths: importing from another agent system, moving an existing install to a new machine, and upgrading a plugin in place.

Import from another agent system

Bundled migration providers bring instructions, MCP servers, skills, model config, and (opt-in) API keys into OpenClaw. Plans are previewed before any change and secrets are redacted in reports. Standalone openclaw migrate is backed by a verified backup; fresh onboarding imports instead stage and verify local artifacts before publishing them with configuration committed before any irreversible external activation.

Move OpenClaw to a new machine

Copy the state directory (~/.openclaw/ by default) and your workspace to preserve:

주요 항목:

Config — openclaw.json and all gateway settings.
Auth — per-agent auth-profiles.json (API keys plus OAuth), plus any channel or provider state under credentials/.
Sessions — conversation history and agent state.
Channel state — WhatsApp login, Telegram session, and similar.
Workspace files — MEMORY.md, USER.md, skills, and prompts.

Migration steps

On the old machine, stop the gateway so files are not changing mid-copy, then archive:

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

cd ~
    tar -xzf openclaw-state.tgz

openclaw doctor
    openclaw gateway restart
    openclaw status

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

Common pitfalls

If the old gateway used --profile or OPENCLAW_STATE_DIR and the new one does not, channels will appear logged out and sessions will be empty. Launch the gateway with the same profile or state-dir you migrated, then rerun openclaw doctor.

Verification checklist

주요 항목:

openclaw status shows the gateway running.
Channels are still connected (no re-pairing needed).
The dashboard opens and shows existing sessions.
Workspace files (memory, configs) are present.

Upgrade a plugin in place

In-place plugin upgrades preserve the same plugin id and config keys but may move on-disk state into the current layout. Plugin-specific upgrade guides live alongside their channels:

주요 항목:

Matrix migration: encrypted-state recovery limits, automatic snapshot behavior, and manual recovery commands.

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/install/migrating
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

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

cd ~
    tar -xzf openclaw-state.tgz

openclaw doctor
    openclaw gateway restart
    openclaw status

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

Migration guide

핵심 요약

Migration hub: cross-system imports, machine-to-machine moves, and plugin upgrades

한국어 가이드 범위: install/migrating 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Import from another agent system
Move OpenClaw to a new machine
Migration steps
Common pitfalls
Verification checklist
Upgrade a plugin in place
관련 문서

상세 내용

본문

OpenClaw supports three migration paths: importing from another agent system, moving an existing install to a new machine, and upgrading a plugin in place.

Import from another agent system

Move OpenClaw to a new machine

Copy the state directory (~/.openclaw/ by default) and your workspace to preserve:

주요 항목:

Config — openclaw.json and all gateway settings.
Auth — per-agent auth-profiles.json (API keys plus OAuth), plus any channel or provider state under credentials/.
Sessions — conversation history and agent state.
Channel state — WhatsApp login, Telegram session, and similar.
Workspace files — MEMORY.md, USER.md, skills, and prompts.

Migration steps

On the old machine, stop the gateway so files are not changing mid-copy, then archive:

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

cd ~
    tar -xzf openclaw-state.tgz

openclaw doctor
    openclaw gateway restart
    openclaw status

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

Common pitfalls

Verification checklist

주요 항목:

openclaw status shows the gateway running.
Channels are still connected (no re-pairing needed).
The dashboard opens and shows existing sessions.
Workspace files (memory, configs) are present.

Upgrade a plugin in place

In-place plugin upgrades preserve the same plugin id and config keys but may move on-disk state into the current layout. Plugin-specific upgrade guides live alongside their channels:

주요 항목:

Matrix migration: encrypted-state recovery limits, automatic snapshot behavior, and manual recovery commands.

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/install/migrating
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

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

cd ~
    tar -xzf openclaw-state.tgz

openclaw doctor
    openclaw gateway restart
    openclaw status

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

Migration guide

핵심 요약

문서 구성

상세 내용

본문

Import from another agent system

Move OpenClaw to a new machine

Migration steps

Common pitfalls

Verification checklist

Upgrade a plugin in place

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Migration guide

핵심 요약

문서 구성

상세 내용

본문

Import from another agent system

Move OpenClaw to a new machine

Migration steps

Common pitfalls

Verification checklist

Upgrade a plugin in place

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드