OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

快速开始

从 Hermes 迁移

内置的 Hermes 迁移提供商会检测 ~/.hermes 中的状态，在应用前预览每项更改，在计划和报告中隐去密钥，并在进行任何修改前写入并验证 OpenClaw 备份。

两种导入方式

新手引导向导

检测 ~/.hermes 中的 Hermes，并在应用前显示预览。

bash
openclaw onboard --flow import

或者指定特定来源：

bash
openclaw onboard --import-from hermes --import-source ~/.hermes

CLI

使用 openclaw migrate 执行脚本化或可重复运行。完整参考请参阅 openclaw migrate。

bash
openclaw migrate hermes --dry-run    # 仅预览openclaw migrate apply hermes --yes  # 跳过确认并应用

当 Hermes 位于 ~/.hermes 之外时，请添加 --from <path>。

导入的内容

模型配置
  • 从 Hermes config.yaml 导入默认模型选择。
  • 从 providers 和 custom_providers 导入已配置的模型提供商和自定义 OpenAI 兼容端点。
MCP 服务器

从 mcp_servers 或 mcp.servers 导入 MCP 服务器定义。

工作区文件
  • 将 SOUL.md 和 AGENTS.md 复制到 OpenClaw Agent 工作区。
  • 将 memories/MEMORY.md 和 memories/USER.md 追加到对应的 OpenClaw 记忆文件，而不是覆盖它们。
记忆配置

导入 OpenClaw 文件记忆的默认记忆配置。Honcho 等外部记忆提供商会记录为归档或需手动审查的项目，以便你有计划地迁移它们。

Skills

复制 skills/<name>/ 下包含 SKILL.md 文件的 Skills，并导入 skills.config 中各个 Skill 的配置值。

身份验证凭据

交互式 openclaw migrate 会在导入身份验证凭据前询问，且默认选中“是”。接受后，会从 OpenCode 的 auth.json 导入 OpenCode OpenAI OAuth 和 GitHub Copilot 条目，以及受支持的 Hermes .env 键。Hermes 自身 auth.json 中的 OAuth 条目属于旧版状态：它们会作为需要手动重新身份验证或由 Doctor 处理的项目显示，而不会导入实时身份验证配置。非交互式运行时使用 --include-secrets 导入凭据，使用 --no-auth-credentials 完全跳过凭据导入，或使用新手引导向导的 --import-secrets 标志。

仅保留在归档中的内容

提供商会将以下内容复制到迁移报告目录中供手动审查，但不会将其加载到实时 OpenClaw 配置或凭据中：

  • plugins/
  • sessions/
  • logs/
  • cron/
  • mcp-tokens/
  • state.db

OpenClaw 拒绝自动执行或信任这些状态，因为不同系统之间的格式和信任假设可能会发生偏差。查看归档后，手动迁移你需要的内容。

推荐流程

  • 预览计划

    bash
    openclaw migrate hermes --dry-run

    计划会列出将要发生的所有更改，包括冲突、跳过的项目和敏感项目。输出中嵌套的疑似密钥键会被隐去。

  • 备份后应用

    bash
    openclaw migrate apply hermes --yes

    OpenClaw 会在应用前创建并验证备份。此非交互式示例仅导入非敏感状态。运行时不加 --yes 可通过交互方式回答凭据提示，或添加 --include-secrets 以在无人值守运行中包含受支持的凭据。

  • 运行 Doctor

    bash
    openclaw doctor

    Doctor 会重新应用所有待处理的配置迁移，并检查导入过程中引入的问题。

  • 重启并验证

    bash
    openclaw gateway restartopenclaw status

    确认 Gateway 网关运行正常，并且导入的模型、记忆和 Skills 已加载。

    • 冲突处理

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

    全新安装中通常不会出现冲突。冲突一般发生在你对已有用户编辑的设置重新执行导入时。

    如果应用过程中出现冲突（例如配置文件发生意外竞争），Hermes 会将其余依赖配置项标记为 skipped，原因为 blocked by earlier apply conflict，而不会只写入其中一部分。迁移报告会记录每个被阻止的项目，以便你解决原始冲突并重新运行导入。

    密钥

    交互式 openclaw migrate 会询问是否导入检测到的身份验证凭据，且默认选中“是”。

    • 接受后，会从 OpenCode 的 auth.json 导入 OpenCode OpenAI OAuth 和 GitHub Copilot 条目，以及受支持的 .env 键。Hermes 自身 auth.json 中的 OAuth 条目则会记录下来，供手动重新进行 OpenAI 身份验证或由 Doctor 修复。
    • 使用 --no-auth-credentials，或在提示中回答“否”，以仅导入非敏感状态。
    • 使用 --include-secrets 在无人值守的 --yes 运行中导入凭据。
    • 使用新手引导向导的 --import-secrets 标志从向导导入凭据。

    用于自动化的 JSON 输出

    bash
    openclaw migrate hermes --dry-run --jsonopenclaw migrate apply hermes --json --yes

    同时使用 --json 且不使用 --yes 时，应用操作会输出计划但不修改状态，这是 CI 和共享脚本最安全的模式。

    故障排查

    应用操作因冲突而拒绝执行

    检查计划输出。每个冲突都会标明来源路径和现有目标。针对每个项目决定是跳过、编辑目标，还是使用 --overwrite 重新运行。

    Hermes 位于 ~/.hermes 之外

    传入 --from /actual/path（CLI）或 --import-source /actual/path（新手引导）。

    新手引导拒绝导入现有设置

    新手引导导入需要全新设置。你可以重置状态并重新执行新手引导，或者直接使用 openclaw migrate apply hermes，它支持 --overwrite 和显式备份控制。

    API 密钥未导入

    交互式 openclaw migrate 仅在你接受凭据提示后导入 API 密钥。非交互式 --yes 运行需要使用 --include-secrets；新手引导导入需要使用 --import-secrets。仅识别受支持的 .env 键，其他 .env 变量会被忽略。

    相关内容

    • openclaw migrate：完整的 CLI 参考、插件契约和 JSON 结构。
    • 新手引导：向导流程和非交互式标志。
    • 迁移：在计算机之间迁移 OpenClaw 安装。
    • Doctor：迁移后的健康检查。
    • Agent 工作区：SOUL.md、AGENTS.md 和记忆文件的存放位置。
    Was this useful?
    On this page

    On this page