跳转至

从 Claude 迁移

OpenClaw 通过内置的 Claude 迁移提供程序导入 Claude 本地状态。该提供程序会在更改状态前预览每一项，并在计划和报告中对机密信息进行脱敏。独立的 openclaw migrate 会创建经过验证的备份；全新 onboarding 流程会暂存导入内容，并且仅在验证成功后发布。

Note

Onboarding 导入需要全新的 OpenClaw 环境。如果你已经有本地 OpenClaw 状态，请先重置配置、凭据、会话和工作区，或者审阅计划后直接使用带 --overwrite 的 openclaw migrate。

两种导入方式

向导在检测到本地 Claude 状态时会提供 Claude 选项。

openclaw onboard --flow import

或者指定特定源：

openclaw onboard --import-from claude --import-source ~/.claude

对于脚本化或可重复运行的情况，请使用 openclaw migrate。完整参考请参阅 openclaw migrate。

openclaw migrate claude --dry-run
openclaw migrate apply claude --yes

添加 --from <path> 可导入特定的 Claude Code 主目录或项目根目录。

会导入哪些内容

指令与记忆
  • 项目 CLAUDE.md 和 .claude/CLAUDE.md 内容会被复制或追加到 OpenClaw agent 工作区的 AGENTS.md。
  • 用户 ~/.claude/CLAUDE.md 内容会被追加到工作区的 USER.md。
MCP 服务器

当存在时，MCP 服务器定义会从项目 .mcp.json、Claude Code 的 ~/.claude.json 以及 Claude Desktop 的 claude_desktop_config.json（若存在）导入。

技能与命令
  • 带有 SKILL.md 文件的 Claude 技能会被复制到 OpenClaw 工作区的技能目录。
  • 位于 .claude/commands/ 或 ~/.claude/commands/ 下的 Claude 命令 Markdown 文件会被转换为 OpenClaw 技能，并带有 disable-model-invocation: true。

哪些内容仅作为存档保留

提供程序会将这些内容复制到迁移报告中供人工审阅，但不会将它们加载到活跃的 OpenClaw 配置中：

  • Claude 钩子
  • Claude 权限和宽泛的工具允许列表
  • Claude 环境默认值
  • CLAUDE.local.md
  • .claude/rules/
  • .claude/agents/ 或 ~/.claude/agents/ 下的 Claude 子代理
  • Claude Code 缓存、计划及项目历史目录
  • Claude Desktop 扩展和操作系统存储的凭据

OpenClaw 不会自动执行钩子、信任权限允许列表，或解码不透明的 OAuth 和 Desktop 凭据状态。审阅存档后，请手动转移你需要的内容。

选择导入源

如果不指定 --from，OpenClaw 会检查位于 ~/.claude 的默认 Claude Code 主目录、Claude Code 的 ~/.claude.json 状态文件，以及 macOS 上的 Claude Desktop MCP 配置。

当 --from 指向项目根目录时，OpenClaw 仅导入该项目的 Claude 文件，例如 CLAUDE.md、.claude/settings.json、.claude/commands/、.claude/skills/ 和 .mcp.json。在项目根目录导入期间，它不会读取你的全局 Claude 主目录。

1. 预览计划

openclaw migrate claude --dry-run

计划会列出所有将要更改的内容，包括冲突、跳过的项目，以及从嵌套 MCP env 或 headers 字段中隐去的敏感值。

2. 应用更改并创建备份

openclaw migrate apply claude --yes

OpenClaw 会在应用前创建并验证备份。

3. 运行 doctor

openclaw doctor

导入完成后，Doctor 会检查配置或状态问题。

4. 重启并验证

openclaw gateway restart
openclaw status

确认网关运行正常，且已加载你导入的指令、MCP 服务器和技能。

冲突处理

当计划报告存在冲突（目标位置已存在某个文件或配置值）时，apply 会拒绝继续。

Warning

只有在有意替换现有目标时才应使用 --overwrite 重新运行。

在覆盖由 Claude 命令生成的技能之前，OpenClaw 会备份其整个目录，并将该路径记录到 report.json 中该项的 details.backupPath 字段。如果覆盖失败，该路径仍然可用。如果无法读取命令源，迁移会报告错误，而不会更改现有技能。

对于全新的 OpenClaw 安装，冲突并不常见。它们通常出现在你对已经包含用户编辑的环境重新运行导入时。

面向自动化的 JSON 输出

openclaw migrate claude --dry-run --json
openclaw migrate apply claude --json --yes

在非交互式终端中运行 migrate apply 时必须使用 --yes；否则 OpenClaw 会报错而不是应用，因此脚本和 CI 必须显式传递 --yes。请先使用 --dry-run --json 预览，等计划看起来正确后，再使用 --json --yes 应用。

故障排查

Claude 状态位于 ~/.claude 之外

请传入 --from /actual/path（CLI）或 --import-source /actual/path（onboarding）。

Onboarding 在已有环境上拒绝导入

Onboarding 导入需要全新环境。你可以重置状态后重新执行 onboard，或直接使用 openclaw migrate apply claude，该命令支持 --overwrite 和显式的备份控制。

来自 Claude Desktop 的 MCP 服务器未导入

Claude Desktop 会从平台特定的路径读取 claude_desktop_config.json。如果 OpenClaw 未能自动检测到该文件，请将 --from 指向该文件所在的目录。

Claude 命令变成了禁用模型调用的技能

这是设计使然。Claude 命令由用户触发，因此 OpenClaw 会将它们作为带有 disable-model-invocation: true 的技能导入。如果你希望 agent 自动调用它们，请编辑每个技能的前置元数据（frontmatter）。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw