Appearance
openclaw migrate 命令将其他智能体系统（Claude Code、Codex CLI、Hermes）的状态导入 OpenClaw 自托管网关。执行前会自动生成详尽的迁移计划并提示确认，默认不导入任何密钥。使用 --dry-run 仅预览，--yes 跳过确认，--include-secrets 导入支持的凭据。迁移前自动备份当前 OpenClaw 状态（除非同时指定 --no-backup 和 --force）。迁移后运行 openclaw doctor 检查健康状态。
openclaw migrate 迁移命令参考
通过插件提供的迁移 provider 将其他智能体系统的状态导入 OpenClaw。内置 provider 支持 Codex CLI、Claude 和 Hermes；第三方插件可以注册额外的 provider。
用户指南
面向用户的迁移操作指南参见 从 Claude 迁移 和 从 Hermes 迁移。迁移入口页 汇总了所有迁移路径。
命令概览
bash
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参数说明
<provider>(string) 已注册的迁移 provider 名称，例如hermes。运行openclaw migrate list查看已安装的 provider。--dry-run(boolean) 只构建迁移计划，不改变状态即退出。--from <path>(string) 覆盖源状态目录。Hermes 默认为~/.hermes。--include-secrets(boolean) 导入支持的凭据。默认关闭。--overwrite(boolean) 允许 apply 在计划报告冲突时替换已有目标。--yes(boolean) 跳过确认提示。非交互模式下必须指定。--skill <name>(string) 按技能名称或项目 ID 选择一项技能复制项。可重复使用该标志迁移多个技能。省略时，交互式 Codex 迁移会显示复选框选择器，非交互式迁移则保留所有计划中的技能。--plugin <name>(string) 按插件名称或项目 ID 选择一个 Codex 插件安装项。可重复使用该标志迁移多个 Codex 插件。省略时，交互式 Codex 迁移会显示原生 Codex 插件复选框选择器，非交互式迁移保留所有计划中的插件。仅适用于由 Codex 应用服务器清单发现的源安装openai-curatedCodex 插件。--verify-plugin-apps(boolean) 仅用于 Codex。强制在规划本地插件激活之前重新遍历源 Codex 应用服务器的app/list。默认关闭以保持迁移规划速度。--no-backup(boolean) 跳过 apply 前的备份。当本地已有 OpenClaw 状态时需要同时指定--force。--force(boolean) 当 apply 被禁止跳过备份时必须与--no-backup共同使用。--json(boolean) 将计划或 apply 结果输出为 JSON。配合--json且不带--yes时，apply 仅打印计划而不修改状态。
安全模型
openclaw migrate 始终先预览后执行。
预览后再 apply
provider 会在任何变更发生前返回详细的逐项计划，包括冲突、跳过的项目及敏感项。JSON 计划、apply 输出和迁移报告会隐藏嵌套的类密钥内容（如 API 密钥、令牌、授权头、cookie 和密码）。
openclaw migrate apply <provider> 在改变状态前会预览计划并提示确认，除非指定了 --yes。非交互模式下 apply 必须使用 --yes。
备份
apply 在应用迁移前会创建并校验 OpenClaw 备份。如果本地尚无 OpenClaw 状态，则跳过备份步骤并继续执行迁移。要跳过后台已有状态的备份，需同时传入 --no-backup 和 --force。
冲突
当计划中存在冲突时，apply 会拒绝继续执行。请先审查计划，如果确认需要替换已有目标，可重新运行并添加 --overwrite。Provider 仍可能将覆盖文件的逐项备份写入迁移报告目录。
密钥
默认情况下绝不导入密钥。使用 --include-secrets 可导入支持的凭据。
Claude provider
内置的 Claude provider 默认检测 ~/.claude 中 Claude Code 的状态。使用 --from <path> 可指定特定的 Claude Code 主目录或项目根目录。
用户指南
面向用户的迁移操作指南参见 从 Claude 迁移。
Claude 导入的内容
- 项目中的
CLAUDE.md和.claude/CLAUDE.md导入到 OpenClaw 工作区。 - 用户
~/.claude/CLAUDE.md追加到工作区USER.md。 - MCP 服务器定义（来自项目
.mcp.json、Claude Code~/.claude.json、Claude Desktopclaude_desktop_config.json）。 - 包含
SKILL.md的 Claude 技能目录。 - Claude 命令 Markdown 文件，转换为只允许手动调用的 OpenClaw 技能。
归档与手动审查项
Claude 的 hooks、权限、环境默认值、本地内存、路径作用域规则、子智能体、缓存、计划和项目历史将保留在迁移报告或标记为手动审查项。OpenClaw 不会执行 hooks、复制宽泛的 allow list 或自动导入 OAuth/桌面凭据状态。
Codex provider
内置的 Codex provider 默认检测 ~/.codex 中的 Codex CLI 状态，或者当设置了 CODEX_HOME 环境变量时读取该路径。使用 --from <path> 可指定其它 Codex 主目录。
当你迁入 OpenClaw Codex 框架时使用本 provider，以便有意地挑选手头有用的个人 Codex CLI 资产。本地 Codex 应用服务器启动使用每个智能体的 CODEX_HOME，因此默认不读取你的个人 ~/.codex。不过进程的 HOME 环境变量仍会继承，所以 Codex 能够看到共享的 $HOME/.agents/* 技能/插件市场条目，子进程也能找到用户主目录下的配置和令牌。
在交互式终端中运行 openclaw migrate codex 将预览完整计划，然后在最终 apply 确认前打开复选框选择器。技能复制项会首先提示。可以使用 Toggle all on 或 Toggle all off 批量选择。按空格切换行，按 Enter 激活高亮行并继续。计划中的技能默认已勾选，冲突技能默认未勾选。Skip for now 跳过本次运行的技能复制，但仍继续到插件选择步骤。当源安装的 curated Codex 插件可迁移且未提供 --plugin 时，迁移会接着按插件名称提示原生 Codex 插件激活。插件项默认已勾选，除非目标 OpenClaw Codex 插件配置中已存在该插件。已存在的目标插件默认未勾选并显示冲突提示（如 conflict: plugin exists）。选择 Toggle all off 可跳过该次运行的原生 Codex 插件迁移，或选择 Skip for now 在 apply 前停止。对于脚本化或精确运行，可为每个技能传递一次 --skill <name>，例如：
bash
openclaw migrate codex --dry-run --skill gog-vault77-google-workspace
openclaw migrate apply codex --yes --skill gog-vault77-google-workspace使用 --plugin <name> 可非交互地将原生 Codex 插件迁移限制为一个或多个源安装的 curated 插件：
bash
openclaw migrate codex --dry-run --plugin google-calendar
openclaw migrate apply codex --yes --plugin google-calendarCodex 导入的内容
- Codex CLI 技能目录（位于
$CODEX_HOME/skills，不包括 Codex 的.system缓存）。 - 个人 AgentSkills（位于
$HOME/.agents/skills），在你需要每个智能体独自拥有它们时，会复制到当前 OpenClaw 工作区。 - 通过 Codex 应用服务器
plugin/list发现的源安装openai-curatedCodex 插件。规划时会为每个启用的已安装插件调用plugin/read。需要应用服务器账号响应的插件要求该账号为 ChatGPT 订阅账号；非 ChatGPT 或缺失账号响应的项会被跳过并标记codex_subscription_required。默认情况下，迁移不会调用源app/list，因此通过账号验证的基于应用的插件在规划时不会验证源应用可访问性，账号查询传输失败会跳过并标记codex_account_unavailable。当需要迁移强制在规划原生激活之前获取最新的源app/list快照并要求每个拥有的应用都存在、已启用且可访问时，可使用--verify-plugin-apps。在此模式下，账号查询传输失败会回退到源应用清单验证。源应用清单快照保留在进程内存中，不会写入迁移输出或目标配置。禁用的插件、无法读取详情的插件、需要订阅的源账号，以及在启用验证时缺失的应用、已禁用的应用、不可访问的应用或源应用清单失败，都会成为手动跳过的项目（附有类型原因），而不是目标配置条目。 - Apply 会为每个选中的符合资格的插件调用应用服务器的
plugin/install，即使目标应用服务器已报告该插件已安装并启用。迁移后的 Codex 插件仅在使用原生 Codex 框架的会话中可用，不会暴露给 Pi、常规 OpenAI provider 运行、ACP 会话绑定或其他框架中。
需要手动审查的 Codex 状态
Codex config.toml、原生 hooks/hooks.json、非 curated 的市场、未通过源订阅验证的缓存插件包，以及未通过 --verify-plugin-apps 验证的插件，不会自动激活。它们会被复制或报告在迁移报告中供手动审查。
对于迁移的源安装 curated 插件，apply 会写入：
plugins.entries.codex.enabled: trueplugins.entries.codex.config.codexPlugins.enabled: trueplugins.entries.codex.config.codexPlugins.allow_destructive_actions: true- 每个选中的插件一条显式条目，包含
marketplaceName: "openai-curated"和pluginName
迁移从不写入 plugins["*"]，也从不存储本地市场缓存路径。源端订阅失败的项以手动项目形式报告，附有类型原因，例如 codex_subscription_required、codex_account_unavailable、plugin_disabled 或 plugin_read_unavailable。使用 --verify-plugin-apps 时，源应用清单失败也可能出现 app_inaccessible、app_disabled、app_missing 或 app_inventory_unavailable。跳过的插件不会写入目标配置。目标端需要认证才可安装的插件会在相关插件项上报告 status: "skipped"、reason: "auth_required" 和脱敏后的应用标识符。其显式配置条目会被写入但禁用，直到你重新授权并启用。其他安装失败是 item 级别的 error 结果。
如果规划时 Codex 应用服务器的插件清单不可用，迁移会回退到缓存包建议项，不会导致整个迁移失败。
Hermes provider
内置的 Hermes provider 默认检测 ~/.hermes 中的状态。如果 Hermes 位于其他位置，使用 --from <path> 指定。
Hermes 导入的内容
config.yaml中的默认模型配置。providers和custom_providers中配置的模型提供商及自定义兼容 OpenAI 的端点。mcp_servers或mcp.servers中的 MCP 服务器定义。SOUL.md和AGENTS.md导入到 OpenClaw 工作区。memories/MEMORY.md和memories/USER.md追加到工作区记忆文件。- OpenClaw 文件记忆的记忆配置默认值，以及外部记忆提供者（如 Honcho）的归档或手动审查项。
skills/<name>/下包含SKILL.md的技能。skills.config中的每技能配置值。- 支持环境变量中的 API 密钥，但仅在使用
--include-secrets时导入。
支持的环境变量密钥
OPENAI_API_KEY, ANTHROPIC_API_KEY, OPENROUTER_API_KEY, GOOGLE_API_KEY, GEMINI_API_KEY, GROQ_API_KEY, XAI_API_KEY, MISTRAL_API_KEY, DEEPSEEK_API_KEY。
仅归档的状态
Hermes 中 OpenClaw 无法安全解释的状态会被复制到迁移报告中供手动审查，不会加载到活跃的 OpenClaw 配置或凭据中。这样可以保留不透明或不安全的状态，而不假装 OpenClaw 可以自动执行或信任它们：
plugins/sessions/logs/cron/mcp-tokens/auth.jsonstate.db
应用后检查
bash
openclaw doctor插件契约
迁移源是以插件形式提供的。插件在 openclaw.plugin.json 中声明其 provider ID：
json
{
"contracts": {
"migrationProviders": ["hermes"]
}
}运行时插件调用 api.registerMigrationProvider(...)。provider 实现 detect、plan 和 apply 方法。核心负责 CLI 编排、备份策略、提示、JSON 输出和冲突预检。核心将审查后的计划传入 apply(ctx, plan)，而 provider 仅当参数缺失以保持兼容性时才可重新构建计划。
Provider 插件可以使用 openclaw/plugin-sdk/migration 进行项目构建和摘要计数，以及 openclaw/plugin-sdk/migration-runtime 进行冲突感知的文件复制、仅归档的报告复制、缓存配置运行时包装器和迁移报告。
与引导集成
引导流程可以在检测到已知源时提供迁移。openclaw onboard --flow import 和 openclaw setup --wizard --import-from hermes 都使用相同的插件迁移 provider，并且在应用前仍会显示预览。
引导导入要求
引导导入需要全新的 OpenClaw 配置。如果本地已有状态，请先重置配置、凭据、会话和工作区。备份覆盖或合并导入对于已有设置的场景是功能受限功能。
相关文档
- 从 Hermes 迁移：面向用户的操作指南。
- 从 Claude 迁移：面向用户的操作指南。
- 迁移 OpenClaw 实例：将 OpenClaw 迁移到新机器。
- 检查健康状态：迁移后运行健康检查。
- 插件：插件安装与注册。
常见问题
如何从 Claude Code 迁移到 OpenClaw？
使用 openclaw migrate claude 命令，默认检测 ~/.claude 目录。可以先添加 --dry-run 预览将要导入的项（如 CLAUDE.md、MCP 服务器、技能等），确认后去掉 --dry-run 执行 apply。如需指定其他目录，使用 --from <path>。
迁移时如何保留 Hermes 的 API 密钥？
在 openclaw migrate hermes 或 openclaw migrate apply hermes 命令中添加 --include-secrets 参数。注意默认不导入任何密钥，安全模型确保密钥不会意外暴露。Hermes 支持的环境变量包括 OPENAI_API_KEY、ANTHROPIC_API_KEY 等。
迁移前需要备份当前 OpenClaw 状态吗？
迁移 apply 会自动创建并验证 OpenClaw 备份（除非本地尚无状态）。如果已有状态且要跳过备份，必须同时使用 --no-backup 和 --force。建议保留默认备份行为，出现问题时可通过备份恢复。