Migrate

기준일: 2026-07-26
공식 기준: Migrate

Migrate 문서는 OpenClaw 공식 문서(cli/migrate)를 한국어로 정리한 가이드입니다. CLI reference for openclaw migrate (import state from another agent system) 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

CLI reference for openclaw migrate (import state from another agent system)

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

문서 구성

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

• 명령
• Safety model
• Claude provider
• What Claude imports
• Archive and manual-review state
• Codex provider
• What Codex imports
• Manual-review Codex state
• Hermes provider
• What Hermes imports
• Supported .env keys
• Archive-only state
• After applying
• Plugin contract
• Onboarding integration
• 관련 문서

상세 내용

openclaw migrate

Import state from another agent system through a plugin-owned migration provider. Bundled providers cover Claude, Codex CLI, and Hermes; plugins can register additional providers.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

명령

Running openclaw migrate with no other flags plans, previews, and (in a TTY) prompts before applying. openclaw migrate plan and openclaw migrate apply split preview and apply into separate subcommands with the same flags.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

openclaw migrate list
openclaw migrate claude --dry-run
openclaw migrate codex --dry-run
openclaw migrate codex --skill gog-vault77-google-workspace
openclaw migrate codex --plugin google-calendar --dry-run
openclaw migrate codex --plugin google-calendar --verify-plugin-apps --dry-run
openclaw migrate hermes --dry-run
openclaw migrate hermes
openclaw migrate apply codex --yes --skill gog-vault77-google-workspace
openclaw migrate apply codex --yes --plugin google-calendar
openclaw migrate apply codex --yes
openclaw migrate apply claude --yes
openclaw migrate apply hermes --yes
openclaw migrate apply hermes --include-secrets --yes
openclaw onboard --flow import
openclaw onboard --import-from claude --import-source ~/.claude
openclaw onboard --import-from hermes --import-source ~/.hermes

Safety model

The provider returns an itemized plan before anything changes, including conflicts, skipped items, and sensitive items. JSON plans, apply output, and migration reports redact nested secret-looking keys such as API keys, tokens, authorization headers, cookies, and passwords.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Claude provider

The bundled Claude provider detects Claude Code state at ~/.claude by default. Use --from to import a specific Claude Code home or project root.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

What Claude imports

user-configured autoMemoryDirectory, copied under memory/imports/claude-code/ for indexed recall.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Claude Code auto-memory Markdown from ~/.claude/projects/*/memory and a
• Project CLAUDE.md and .claude/CLAUDE.md into the OpenClaw agent workspace (AGENTS.md).
• User ~/.claude/CLAUDE.md appended to workspace USER.md.
• MCP server definitions from project .mcp.json, Claude Code ~/.claude.json (including its per-project entries), and Claude Desktop claude_desktop_config.json.
• Claude skill directories that include SKILL.md (user ~/.claude/skills and project .claude/skills).
• Claude command Markdown files (user ~/.claude/commands and project .claude/commands) converted into OpenClaw skills with manual invocation only.

Archive and manual-review state

Claude hooks, permissions, environment defaults, project CLAUDE.local.md, .claude/rules, user and project agents/ directories, and project history (projects, cache, plans under ~/.claude) are preserved in the migration report or reported as manual-review items. OpenClaw does not execute hooks, copy broad allowlists, or import OAuth/Desktop credential state automatically.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Codex provider

The bundled Codex provider detects Codex CLI state at ~/.codex by default, or at CODEX_HOME when that environment variable is set. Use --from to inventory a specific Codex home.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

openclaw migrate codex --dry-run --skill gog-vault77-google-workspace
openclaw migrate apply codex --yes --skill gog-vault77-google-workspace
openclaw migrate codex --dry-run --plugin google-calendar
openclaw migrate apply codex --yes --plugin google-calendar

What Codex imports

$CODEX_HOME/memories, copied under memory/imports/codex/ for indexed recall. Raw rollout memory is not imported.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Consolidated Codex MEMORY.md and memory_summary.md from
• Codex CLI skill directories under $CODEX_HOME/skills, excluding Codex's .system cache.
• Personal AgentSkills under $HOME/.agents/skills, copied into the current OpenClaw agent workspace for per-agent ownership.
• Source-installed openai-curated Codex plugins discovered through Codex app-server plugin/list. Planning reads plugin/read for each enabled installed plugin.
• App-backed plugins require the source Codex app-server account to be a ChatGPT subscription account. Non-ChatGPT or missing account responses are skipped with codex_subscription_required.
• By default, migration does not call source app/list, so app-backed plugins that pass the account gate are planned without source app-accessibility verification, and account-lookup transport failures skip with codex_account_unavailable.
• Pass --verify-plugin-apps to force a fresh source app/list snapshot and require every owned app to be present, enabled, and accessible before planning native activation. In that mode, account-lookup transport failures fall through to source app-inventory verification. The snapshot is kept in memory for the current process only; it is never written to migration output or target config.

Manual-review Codex state

Codex config.toml, native hooks/hooks.json, non-curated marketplaces, cached plugin bundles that are not source-installed curated plugins, and source-installed plugins that fail the source subscription gate are not activated automatically. When --verify-plugin-apps is set, plugins that fail the source app-inventory gate are also skipped. All of these are copied or reported in the migration report for manual review.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• plugins.entries.codex.enabled: true
• plugins.entries.codex.config.codexPlugins.enabled: true
• plugins.entries.codex.config.codexPlugins.allow_destructive_actions: true
• one explicit plugin entry with marketplaceName: "openai-curated" and pluginName for each selected plugin

Hermes provider

The bundled Hermes provider follows $HERMES_HOME and the active profile, then uses the platform default (~/.hermes or %LOCALAPPDATA%\hermes). Use --from to override discovery.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

What Hermes imports

Memory-only surfaces (the onboarding memory page and the Control UI Memory import page) instead copy these files under memory/imports/hermes/ for indexed recall without touching existing workspace memory.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Default model configuration from config.yaml.
• Configured model providers and custom OpenAI-compatible endpoints from model, providers, and custom_providers.
• MCP server definitions from mcp_servers or mcp.servers. Exact OpenClaw mappings cover default Streamable HTTP routing, OAuth scope, boolean TLS verification, separate client certificate/key paths, and Hermes native/resource/prompt tool policy. Unsupported Hermes-only runtime or credential fields are reported for manual review.
• SOUL.md and AGENTS.md into the OpenClaw agent workspace.
• memories/MEMORY.md and memories/USER.md appended to workspace memory files.
• Memory config defaults for OpenClaw file memory, plus archive or manual-review items for external memory providers such as Honcho.
• Skills that include a SKILL.md file anywhere under skills/; nested skills are flattened into the workspace skill directory.
• Per-skill config values from skills.config.
• Current Hermes OpenAI Codex OAuth credentials and OpenCode OpenAI OAuth credentials when interactive credential migration is accepted, or when --include-secrets is set. Do not keep Hermes and OpenClaw using the same imported refresh grant.
• Supported API keys and tokens from Hermes .env and OpenCode auth.json when interactive credential migration is accepted, or when --include-secrets is set.

Supported .env keys

AI_GATEWAY_API_KEY, ALIBABA_API_KEY, ANTHROPIC_API_KEY, ARCEEAI_API_KEY, CEREBRAS_API_KEY, CHUTES_API_KEY, CLOUDFLARE_AI_GATEWAY_API_KEY, COPILOT_GITHUB_TOKEN, DASHSCOPE_API_KEY, DEEPINFRA_API_KEY, DEEPSEEK_API_KEY, FIREWORKS_API_KEY, GEMINI_API_KEY, GH_TOKEN, GITHUB_TOKEN, GLM_API_KEY, GOOGLE_API_KEY, GROQ_API_KEY, HF_TOKEN, HUGGINGFACE_HUB_TOKEN, KILOCODE_API_KEY, KIMICODE_API_KEY, KIMI_API_KEY, KIMI_CODING_API_KEY, MINIMAX_API_KEY, MINIMAX_CODING_API_KEY, MISTRAL_API_KEY, MODELSTUDIO_API_KEY, MOONSHOT_API_KEY, NVIDIA_API_KEY, OPENAI_API_KEY, OPENCODE_API_KEY, OPENCODE_GO_API_KEY, OPENCODE_ZEN_API_KEY, OPENROUTER_API_KEY, QIANFAN_API_KEY, QWEN_API_KEY, TOGETHER_API_KEY, VENICE_API_KEY, XAI_API_KEY, XIAOMI_API_KEY, ZAI_API_KEY, Z_AI_API_KEY.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Archive-only state

Hermes state that OpenClaw cannot safely interpret is copied into the migration report for manual review, but it is not loaded into live OpenClaw config or credentials. This includes plugins/, sessions/, logs/, cron/, mcp-tokens/, plans/, workspace/, skins/, kanban/, pairing/platform state, gateway routing/process state, and the detected Hermes SQLite databases.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

After applying

openclaw doctor

Plugin contract

Migration sources are plugins. A plugin declares its provider ids in openclaw.plugin.json:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

{
  "contracts": {
    "migrationProviders": ["hermes"]
  }
}

Onboarding integration

Onboarding can offer migration when a provider detects a known source. Both openclaw onboard --flow import and openclaw setup --wizard --import-from hermes use the same plugin migration provider and still show a preview before applying. Unlike standalone migration, the fresh-target onboarding path stages local artifacts and imported credentials, verifies or repairs imported inference inside staging, then promotes workspace and agent state before committing configuration. A mode-0600 promotion journal lets the next run finish or roll back an interrupted publish, including any deferred external activation, without replaying imported local data.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

관련 문서

주요 항목:

• Migrating from Hermes: user-facing walkthrough.
• Migrating from Claude: user-facing walkthrough.
• Migrating: move OpenClaw to a new machine.
• Doctor: health check after applying a migration.
• Plugins: plugin install and registration.

실습 체크리스트

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

자주 쓰는 명령·설정 예시

openclaw migrate list
openclaw migrate claude --dry-run
openclaw migrate codex --dry-run
openclaw migrate codex --skill gog-vault77-google-workspace
openclaw migrate codex --plugin google-calendar --dry-run
openclaw migrate codex --plugin google-calendar --verify-plugin-apps --dry-run
openclaw migrate hermes --dry-run
openclaw migrate hermes
openclaw migrate apply codex --yes --skill gog-vault77-google-workspace
openclaw migrate apply codex --yes --plugin google-calendar
openclaw migrate apply codex --yes
openclaw migrate apply claude --yes
openclaw migrate apply hermes --yes
openclaw migrate apply hermes --include-secrets --yes
openclaw onboard --flow import
openclaw onboard --import-from claude --import-source ~/.claude
openclaw onboard --import-from hermes --import-source ~/.hermes

openclaw migrate codex --dry-run --skill gog-vault77-google-workspace
openclaw migrate apply codex --yes --skill gog-vault77-google-workspace
openclaw migrate codex --dry-run --plugin google-calendar
openclaw migrate apply codex --yes --plugin google-calendar

openclaw doctor

{
  "contracts": {
    "migrationProviders": ["hermes"]
  }
}

관련 링크

• 공식 원문: cli/migrate
• OpenClaw 문서 홈

이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·플래그 이름은 설치 버전에 따라 달라질 수 있습니다.