Appearance
从 Hermes 迁移到 OpenClaw 时，使用内置迁移提供程序可安全导入模型配置、MCP 服务器、工作区文件（SOUL.md、AGENTS.md）、记忆配置和技能。推荐先执行 openclaw migrate hermes --dry-run 预览变更计划，再用 openclaw migrate apply hermes --yes 应用，后者会自动创建和验证备份。注意：导入需要全新的 OpenClaw 环境，已有数据需先重置或使用 --overwrite 覆盖。API 密钥默认不导入，需额外加 --include-secrets。
OpenClaw 从 Hermes 迁移导入指南
OpenClaw 通过一个捆绑的迁移提供程序导入 Hermes 状态。该提供程序在变更状态前会预览所有操作，在计划和报告中脱敏敏感信息，并在应用前创建经过验证的备份。
INFO
导入需要全新的 OpenClaw 环境。如果本地已有 OpenClaw 状态，请先重置配置、凭证、会话和工作区，或者查看计划后直接使用 openclaw migrate 加 --overwrite 运行。
两种导入方式
向导式导入
最快的方式。向导会自动检测 `~/.hermes` 下的 Hermes 配置，并在应用前显示预览。
```bash
openclaw onboard --flow import
```
或者指定特定源目录：
```bash
openclaw onboard --import-from hermes --import-source ~/.hermes
```
CLI 命令
使用 `openclaw migrate` 适合脚本化或可重复执行。完整参考见 [`openclaw migrate`](/ai/ai-tools/openclaw/cli/migrate)。
```bash
openclaw migrate hermes --dry-run # 仅预览
openclaw migrate apply hermes --yes # 跳过确认直接应用
```
如果 Hermes 不在 `~/.hermes` 下，添加 `--from <路径>`。
自动导入的内容
模型配置
- Hermes `config.yaml` 中的默认模型选择。
- 已配置的模型提供商和自定义 OpenAI 兼容端点（来自 `providers` 和 `custom_providers`）。
MCP 服务器
`mcp_servers` 或 `mcp.servers` 中的 MCP 服务器定义。
工作区文件
- `SOUL.md` 和 `AGENTS.md` 会被复制到 OpenClaw 智能体工作区。
- `memories/MEMORY.md` 和 `memories/USER.md` 会**追加**到 OpenClaw 对应的记忆文件末尾，而非覆盖。
记忆配置
OpenClaw 文件记忆的记忆配置默认值。外部记忆提供商（如 Honcho）会被记录为归档或手动审查项，需要你自行决定是否迁移。
技能
包含 `SKILL.md` 文件的技能（位于 `skills/<name>/` 下）会被复制，同时还会导入 `skills.config` 中每个技能的配置值。
API 密钥（需显式启用）
设置 `--include-secrets` 后，导入支持的 `.env` 密钥：`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`。不加该标志，密钥永远不会被复制。
仅归档不导入的内容
这些内容会被复制到迁移报告目录中供手动审查，但不会加载到 OpenClaw 的实时配置或凭证中：
plugins/sessions/logs/cron/mcp-tokens/auth.jsonstate.db
OpenClaw 不会自动信任这些状态，因为格式和安全假设可能在系统间漂移。审查归档后，根据需要手动迁移。
推荐迁移流程
预览计划
```bash
openclaw migrate hermes --dry-run
```
计划会列出所有将要变更的项目，包括冲突、跳过的项目以及敏感项。输出会对嵌套的敏感键进行脱敏。
应用并创建备份
```bash
openclaw migrate apply hermes --yes
```
OpenClaw 会在应用前创建并验证备份。如果需要导入 API 密钥，加上 `--include-secrets`。
运行健康检查
```bash
openclaw doctor
```
[Doctor](/ai/ai-tools/openclaw/gateway/doctor) 会重新应用待处理的配置迁移，并检查导入过程中引入的问题。
重启并验证
```bash
openclaw gateway restart
openclaw status
```
确认网关正常运行，并且导入的模型、记忆和技能已加载。
冲突处理
当计划报告冲突（目标位置已存在文件或配置值）时，apply 操作会停止。
WARNING
仅在有意替换现有目标时才加上 --overwrite 重新运行。提供程序仍可能为覆盖的文件在迁移报告目录中写入项目级备份。
对于全新的 OpenClaw 安装，冲突很少见。通常在已有人工编辑的配置上重新运行导入时出现。
如果冲突在应用过程中发生（例如配置文件上的意外竞争），Hermes 会将剩余依赖配置项标记为 skipped，原因设为 blocked by earlier apply conflict，而非部分写入。迁移报告会记录每个被阻塞的项目，以便你解决原始冲突后重新运行导入。
密钥配置注意事项
密钥默认不会被导入。
- 先执行
openclaw migrate apply hermes --yes导入非密钥状态。 - 如果还需要复制支持的
.env密钥，重新运行并加上--include-secrets。 - 对于 SecretRef 管理的凭证，请在导入完成后配置 SecretRef 源。
JSON 输出用于自动化
bash
openclaw migrate hermes --dry-run --json
openclaw migrate apply hermes --json --yes使用 --json 且不加 --yes 时，apply 只会打印计划而不改变状态。这是 CI 和共享脚本的最安全模式。
常见问题排查
Apply 操作因冲突拒绝执行怎么办？
检查计划输出。每个冲突都会标明源路径和现有的目标路径。对每个项目决定是跳过、编辑目标还是加上 `--overwrite` 重新运行。
Hermes 不在 ~/.hermes 目录下？
通过 `--from /实际路径`（CLI）或 `--import-source /实际路径`（向导）指定位置。
向导提示无法在已有环境上导入？
向导导入需要全新环境。要么重置状态后重新运行向导，要么直接使用 `openclaw migrate apply hermes`，该命令支持 `--overwrite` 和显式备份控制。
API 密钥没有导入？
必须加上 `--include-secrets`，且只有上文列出的密钥会被识别。`.env` 中的其他变量会被忽略。
常见问题
从 Hermes 迁移后 API 密钥没有导入怎么办？
默认不会导入任何 API 密钥。需要重新运行 openclaw migrate apply hermes --yes --include-secrets 才会导入支持的 .env 密钥。注意该命令只识别 OPENAI_API_KEY、ANTHROPIC_API_KEY 等列出的密钥，其他变量会被忽略。
迁移时提示冲突无法继续怎么处理？
先运行 openclaw migrate hermes --dry-run 查看具体冲突文件和目标位置。如果确定要覆盖目标内容，可重新执行 openclaw migrate apply hermes --yes --overwrite。如果只想跳过冲突项，需要手动编辑目标文件或删除冲突项后再运行。
Hermes 不在默认的 ~/.hermes 目录下怎么办？
在 CLI 命令中加上 --from /实际路径，例如 openclaw migrate hermes --dry-run --from /home/user/.hermes；使用向导时加 --import-source /实际路径。
相关文档
openclaw migrate：完整 CLI 参考、插件合约和 JSON 格式。- 向导导入：向导流程和非交互式参数。
- 迁移 OpenClaw 实例：在不同机器间迁移 OpenClaw 安装。
- 健康检查：迁移后的状态检查。
- 智能体工作区：
SOUL.md、AGENTS.md和记忆文件的存放位置。