openclaw migrate¶

通过插件拥有的迁移提供程序从另一个智能体系统导入状态。内置提供程序涵盖 Claude、Codex CLI 和 Hermes。插件可以注册其他提供程序。

命令¶

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 <provider> 会规划、预览，并在（TTY 中）应用前提示确认。openclaw migrate plan <provider> 和 openclaw migrate apply <provider> 将预览和应用拆分为具有相同标志的独立子命令。

共享标志在任一位置均有效，因此 openclaw migrate --no-auth-credentials apply hermes --yes 与 openclaw migrate apply hermes --no-auth-credentials --yes 行为相同。放在子命令上的标志会覆盖放在其前面的同一标志。--dry-run 是例外：openclaw migrate apply 会拒绝该标志而不是执行应用，因为 apply 总是会更改状态。

已注册迁移提供程序的名称，例如 hermes。运行 openclaw migrate list 可查看已安装的提供程序。

--dry-run boolean (path)

构建计划并退出，不更改状态。openclaw migrate apply 不接受该标志；请改用 openclaw migrate plan <provider>。

覆盖源状态目录。Hermes 遵循 $HERMES_HOME 和活动配置文件，然后使用平台默认值（~/.hermes 或 %LOCALAPPDATA%\hermes）。Codex 默认使用 ~/.codex（或 $CODEX_HOME），Claude 默认使用 ~/.claude。 导入到已配置的智能体。仅在配置的默认智能体是预期所有者时才可省略此参数。无效和未知的智能体 ID 将被拒绝。

--include-secrets boolean (path)

在无需 OpenClaw 确认提示的情况下导入支持的凭据。Codex 仍可能请求访问操作系统凭据存储，例如 macOS 钥匙串访问。交互式 apply 在检查和导入身份验证凭据之前会进行询问，默认选中 yes。非交互式 --yes 需要 --include-secrets 才能导入这些凭据。

--no-auth-credentials boolean (path)

跳过身份验证凭据的导入，包括交互式提示。

--overwrite boolean (path)

允许 apply 在计划报告冲突时替换现有目标。

--yes boolean (path)

跳过确认提示。非交互模式下必需。

按技能名称或条目 id 选择一个技能复制条目。重复该标志可迁移多个技能。省略时，交互式 Codex 迁移会显示复选框选择器，而非交互式迁移会保留所有已计划的技能。 按插件名称或条目 id 选择一个 Codex 插件安装条目。重复该标志可迁移多个 Codex 插件。省略时，交互式 Codex 迁移会显示原生 Codex 插件复选框选择器，而非交互式迁移会保留所有已计划的插件。仅适用于由 Codex app-server 清单发现、通过源安装的 openai-curated Codex 插件。 按其计划 ID 选择一个精确的迁移条目。重复该标志可迁移多个条目。例如，--item auth:openai 可将 Codex 迁移限制为已检测到的 OpenAI 凭据条目。

--verify-plugin-apps boolean (path)

仅适用于 Codex。在规划原生插件激活之前，强制重新读取源 Codex app-server 的 app/installed 快照。默认关闭，以保持迁移规划快速。

迁移前备份归档的路径或目录。传递给 openclaw backup create。

--no-backup boolean (path)

跳过 apply 前的备份。当本地 OpenClaw 状态存在时，需要 --force。

--force boolean (path)

当 apply 在其他情况下会拒绝跳过备份时，必须与 --no-backup 一起使用。

--json boolean (path)

将计划或 apply 结果以 JSON 形式打印。使用 --json 且未使用 --yes 时，apply 会打印计划且不修改状态。

安全模型¶

openclaw migrate 采用预览优先模式。

Claude 提供方¶

内置的 Claude 提供方默认在 ~/.claude 检测 Claude Code 状态。使用 --from <path> 导入特定的 Claude Code 主目录或项目根目录。

Claude 导入内容¶

• 来自 ~/.claude/projects/*/memory 以及用户配置的 autoMemoryDirectory 的 Claude Code 自动记忆 Markdown，复制到 memory/imports/claude-code/ 下，以便进行索引召回。
• 项目 CLAUDE.md 和 .claude/CLAUDE.md 导入到 OpenClaw 智能体工作区（AGENTS.md）。
• 用户 ~/.claude/CLAUDE.md 追加到工作区 USER.md。
• 来自项目 .mcp.json、Claude Code ~/.claude.json（包括其按项目划分的条目）以及 Claude Desktop claude_desktop_config.json 的 MCP 服务器定义。
• 包含 SKILL.md 的 Claude 技能目录（用户 ~/.claude/skills 和项目 .claude/skills）。
• Claude 命令 Markdown 文件（用户 ~/.claude/commands 和项目 .claude/commands）转换为仅可手动调用的 OpenClaw 技能。

归档与手动审核状态¶

Claude hooks、权限、环境默认值、项目 CLAUDE.local.md、.claude/rules、用户与项目 agents/ 目录，以及项目历史（~/.claude 下的 projects、cache、plans）会保留在迁移报告中，或作为手动审核项列出。OpenClaw 不会执行 hooks、复制宽泛的允许列表，也不会自动导入 OAuth/Desktop 凭据状态。

Codex 提供方¶

内置的 Codex 提供方默认在 ~/.codex 检测 Codex CLI 状态；若设置了 CODEX_HOME 环境变量，则在该路径检测。使用 --from <path> 盘点特定的 Codex 主目录。

当您迁移到 OpenClaw Codex harness 并希望有选择地引入有用的个人 Codex CLI 资产时，请使用此提供方。本地 Codex 应用服务器启动使用每个智能体独立的 CODEX_HOME，因此默认不会读取您的个人 ~/.codex。正常进程的 HOME 仍会被继承，因此 Codex 可以看到共享的 $HOME/.agents/* 技能/插件市场条目，子进程也能找到用户主目录中的配置和令牌。

Codex 凭据是敏感的迁移输入。初始凭据规划提供不检查原生凭据存储的导入。接受交互式凭据提示或传递 --include-secrets 允许检查和导入 Codex 所选存储中的凭据；macOS 可能会请求 Keychain 访问。原生插件清单发现会单独遵循 Codex 的认证行为，包括在试运行期间。默认的智能体作用域运行时不会直接使用复制或挂载的 auth.json。请显式地将这些凭据导入所属智能体的 OpenClaw 认证存储。将 <agent-id> 替换为已配置的该智能体 ID：

openclaw migrate plan codex --from <codex-home> --agent <agent-id> --include-secrets --item auth:openai
openclaw migrate apply codex --from <codex-home> --agent <agent-id> --include-secrets --item auth:openai --yes

对于嵌入 Codex 迁移提供方的调用方，显式设置 providerOptions.allowKeychainPrompt: false 会禁用认证导入的凭据检查，包括基于文件的导入，即使设置了 includeSecrets: true 也是如此。较早的标记版本可以在使用该覆盖设置时导入文件凭据。原生启动在 OpenClaw 能检查所选存储之前就可能访问凭据存储，因此当此覆盖设置为 false 时，认证导入步骤不会启动其原生读取器。常规迁移 CLI 和引导同意流程不会设置此覆盖。插件发现是独立的，仍可能请求操作系统凭据访问。

在交互式终端中运行 openclaw migrate codex 会预览完整计划，然后在最终 Apply 确认前打开复选框选择器。技能复制项会首先提示。使用 Toggle all on 或 Toggle all off 进行批量选择。按空格键切换行的开关，或按回车键激活高亮行并继续。计划中的技能默认选中，冲突技能默认未选中；Skip for now 会在本次运行中跳过技能复制，同时继续进入插件选择。当源安装的精选 Codex 插件可迁移且未提供 --plugin 时，迁移随后会按插件名称提示启用原生 Codex 插件。插件项默认选中，除非目标 OpenClaw Codex 插件配置中已有该插件。已存在的目标插件默认未选中，并显示冲突提示，如 conflict: plugin exists。选择 Toggle all off 可在本次运行中不迁移任何原生 Codex 插件；或选择 Skip for now 在应用前停止。

对于脚本化或精确运行，请显式选择一个或多个技能或插件：

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

Codex 导入内容¶

• 来自 Codex 所选原生存储的 ChatGPT OAuth 或 OpenAI API 密钥凭据，仅在设置 --include-secrets 时导入到智能体的 OpenClaw 认证存储。
• 来自 $CODEX_HOME/memories 的合并 Codex MEMORY.md 和 memory_summary.md，复制到 memory/imports/codex/ 下，以便进行索引召回。原始 rollout 记忆不会被导入。
• $CODEX_HOME/skills 下的 Codex CLI 技能目录，不包括 Codex 的 .system 缓存。
• $HOME/.agents/skills 下的个人 AgentSkills，复制到当前 OpenClaw 智能体工作区，以便按智能体拥有。
• 通过 Codex 应用服务器 plugin/installed 发现的源安装 openai-curated Codex 插件。规划阶段会为每个已启用的已安装插件读取 plugin/read。

Codex 会话和聊天记录不会被导入。整合后的记忆不是对话记录。迁移不会移动或删除您的源文件。

在引导过程中，迁移说明会在询问是否继续之前解释这一范围。继续将打开导入选项；凭据需要单独同意，可以选择技能和符合条件的插件，并且在应用之前需要最终确认。

基于应用的插件迁移有额外的门槛：

• 基于应用的插件要求源 Codex 应用服务器账号是 ChatGPT 订阅账号。非 ChatGPT 或缺失的账号响应会以 codex_subscription_required 跳过。
• 默认情况下，迁移不会读取源应用清单。因此，通过账号门槛的基于应用的插件会在未验证源应用可访问性的情况下进行规划。账号查找传输失败会以 codex_account_unavailable 跳过。
• 传递 --verify-plugin-apps 以强制获取最新的源 app/installed 快照，以及来自批量 app/read 的授权元数据。该模式要求每个拥有的应用在规划原生激活之前都必须存在、已启用且可访问。在该模式下，账号查找传输失败会转入源应用清单验证。快照仅保留在当前进程的内存中，绝不会写入迁移输出或目标配置。

已禁用的插件、无法读取的插件详情、受订阅门槛限制的源账号，以及（当设置 --verify-plugin-apps 时）缺失、已禁用或不可访问的应用，都会成为带有类型化原因的手动跳过项，而不是目标配置条目。Apply 会为每个选定的合格插件调用应用服务器 plugin/install，即使目标应用服务器已经报告该插件已安装并启用。迁移后的 Codex 插件只能在选择原生 Codex 执行器（harness）的会话中使用。它们不会暴露给 OpenClaw 提供程序运行、ACP 对话绑定或其他执行器。

手动审核的 Codex 状态¶

Codex config.toml、原生 hooks/hooks.json、非精选市场、并非源安装精选插件的缓存插件包，以及未通过源订阅门槛的源安装插件，都不会被自动激活。当设置 --verify-plugin-apps 时，未通过源应用清单门槛的插件也会被跳过。所有这些都会被复制或在迁移报告中列出，以供手动审核。

对于迁移的源安装精选插件，apply 会写入：

• plugins.entries.codex.enabled: true
• plugins.entries.codex.config.codexPlugins.enabled: true
• plugins.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"，并附带脱敏后的应用标识符。它们的显式配置条目会以禁用状态写入，直到您重新授权并启用它们。其他安装失败则是条目级的 error 结果。

如果在规划期间 Codex 应用服务器插件清单不可用，迁移会回退到缓存的捆绑包建议项，而不是使整个迁移失败。

Hermes 提供程序¶

捆绑的 Hermes 提供程序遵循 $HERMES_HOME 和活动配置文件，然后使用平台默认位置（~/.hermes 或 %LOCALAPPDATA%\hermes）。使用 --from <path> 覆盖发现逻辑。

Hermes 导入的内容¶

• 来自 config.yaml 的默认模型配置。--agent <id> 将模型应用于选定的代理，而不会更改共享默认值或其他代理。
• 来自 model、providers 和 custom_providers 的已配置模型提供程序以及自定义 OpenAI 兼容端点，包括受支持的 Hermes 传输别名、camelCase 字段和模型列表元数据。
• 来自 mcp_servers 或 mcp.servers 的 MCP 服务器定义。精确的 OpenClaw 映射涵盖默认 Streamable HTTP 路由、OAuth 范围、布尔 TLS 验证、单独的客户端证书/密钥路径，以及 Hermes 原生/资源/提示工具策略。不支持的 Hermes 专属运行时或凭据字段会报告为手动审核项。
• 将 SOUL.md 和 AGENTS.md 导入 OpenClaw 代理工作区。
• 将 memories/MEMORY.md 和 memories/USER.md 追加到工作区记忆文件。 仅记忆界面（引导记忆页面和 Control UI 记忆导入页面）则将这些文件复制到 memory/imports/hermes/ 下，以便进行索引回忆，而不会触及现有的工作区记忆。
• OpenClaw 文件记忆的记忆配置默认值，以及针对外部记忆提供程序（如 Honcho）的归档或手动审核项。
• 在 skills/ 的活动目录下包含 SKILL.md 文件的技能。嵌套技能会被扁平化到工作区技能目录中，组织镜像遵循 _org/.active_org。
• 来自 skills.config 的每技能配置值，以及来自 skills.disabled 的全局禁用状态。
• 当交互式凭据迁移被接受，或设置 --include-secrets 时，导入当前的 Hermes OpenAI Codex OAuth 凭据和 OpenCode OpenAI OAuth 凭据。不要让 Hermes 和 OpenClaw 继续使用同一个导入的刷新授权。
• 当交互式凭据迁移被接受，或设置 --include-secrets 时，导入来自 Hermes .env 和 OpenCode auth.json 的受支持 API 密钥和令牌。

受支持的 .env 键¶

AI_GATEWAY_API_KEY, ALIBABA_API_KEY, ALIBABA_CODING_PLAN_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, GLM_API_KEY, GOOGLE_API_KEY, GROQ_API_KEY, HF_TOKEN, HUGGINGFACE_HUB_TOKEN, KILOCODE_API_KEY, KIMICODE_API_KEY, KIMI_API_KEY, KIMI_CN_API_KEY, KIMI_CODING_API_KEY, MINIMAX_API_KEY, MINIMAX_CN_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.

仅归档状态¶

无法被 OpenClaw 安全解释的 Hermes 状态会被复制到迁移报告中，供人工审查。它不会被加载到实时 OpenClaw 配置或凭据中。这包括 plugins/、sessions/、logs/、cron/、mcp-tokens/、plans/、workspace/、skins/、kanban/、配对/平台状态、网关路由/进程状态，以及检测到的 Hermes SQLite 数据库。

应用后¶

openclaw doctor

插件契约¶

迁移源是插件。插件在 openclaw.plugin.json 中声明其 provider id：

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

在运行时，插件调用 api.registerMigrationProvider(...)。provider 实现 detect、plan 和 apply。Core 负责 CLI 编排、备份策略、提示、JSON 输出以及冲突预检。Core 将已审查的计划传入 apply(ctx, plan)；出于兼容性考虑，provider 仅在该参数缺失时才可重建计划。迁移项可以设置 applyPhase: "after-promotion"，用于外部激活效果，onboarding 必须将其延迟到暂存的本地数据被持久发布之后。这些 provider 必须声明 deferredApply: { retrySafe: true }，并确保每个延迟效果在进程中断后都可以安全重放。Onboarding 会拒绝未声明的延迟效果。幂等无操作应返回一个非变更项，并带有 deferredCompletion: true，以便恢复流程将其记录为已完成。独立的 openclaw migrate 仍会通过其正常的备份支持流程应用完整计划。

Provider 插件可以使用 openclaw/plugin-sdk/migration 进行迁移项构造和汇总计数，并使用 openclaw/plugin-sdk/migration-runtime 进行冲突感知的文件复制、仅归档报告复制、缓存的配置运行时包装器以及迁移报告。

在 JSON 模式下，如果 apply 以项错误或冲突结束，会写入一份完整的迁移报告，并以退出码 1 退出。检查 summary 和 items 以识别部分结果。

Onboarding 集成¶

当 provider 检测到已知源时，onboarding 可以提供迁移。openclaw onboard --flow import 和 openclaw setup --wizard --import-from hermes 都使用相同的插件迁移 provider，并且在应用前仍会显示预览。与独立迁移不同，面向新目标的 onboarding 路径会暂存本地工件和导入的凭据。它会在暂存环境中验证或修复导入的推理。然后，在提交配置之前提升工作区和 agent 状态。一个 mode-0600 的提升日志可让下一次运行完成或回滚一次中断的发布，包括任何延迟的外部激活，而无需重放导入的本地数据。

相关¶

• 从 Hermes 迁移：面向用户的操作指南。
• 从 Claude 迁移：面向用户的操作指南。
• 迁移：将 OpenClaw 迁移到新机器。
• Doctor：应用迁移后的健康检查。
• 插件：插件安装和注册。