从 OpenClaw 迁移

hermes claw migrate 命令可将你的 OpenClaw（或旧版 Clawdbot/Moldbot）设置导入到 Hermes。本指南详细说明了迁移内容、配置键映射关系，以及迁移后需要验证的事项。

快速开始

# Preview what would happen (no files changed)
hermes claw migrate --dry-run

# Run the migration (secrets excluded by default)
hermes claw migrate

# Full migration including API keys
hermes claw migrate --preset full

迁移默认从 ~/.openclaw/ 读取数据。如果你仍保留旧版的 ~/.clawdbot/ 或 ~/.moldbot/ 目录，系统会自动检测。同样，旧版配置文件名（如 clawdbot.json、moldbot.json）也会被自动识别。

选项

选项	描述
`--dry-run`	预览将要迁移的内容，但不写入任何数据。
`--preset <name>`	`full`（默认，包含密钥）或 `user-data`（不包含 API 密钥）。
`--overwrite`	在发生冲突时覆盖现有的 Hermes 文件（默认：跳过）。
`--migrate-secrets`	包含 API 密钥（当使用 `--preset full` 时默认开启）。
`--source <path>`	自定义 OpenClaw 目录路径。
`--workspace-target <path>`	指定 `AGENTS.md` 的存放位置。
`--skill-conflict <mode>`	`skip`（默认）、`overwrite` 或 `rename`。
`--yes`	跳过确认提示。

迁移内容

人格、记忆与指令

内容	OpenClaw 源路径	Hermes 目标路径	说明
人格设定	`workspace/SOUL.md`	`~/.hermes/SOUL.md`	直接复制
工作区指令	`workspace/AGENTS.md`	`--workspace-target` 指定的 `AGENTS.md`	需要 `--workspace-target` 标志
长期记忆	`workspace/MEMORY.md`	`~/.hermes/memories/MEMORY.md`	解析为条目，与现有内容合并，去重。使用 `§` 作为分隔符。
用户档案	`workspace/USER.md`	`~/.hermes/memories/USER.md`	与记忆相同的条目合并逻辑
每日记忆文件	`workspace/memory/*.md`	`~/.hermes/memories/MEMORY.md`	所有每日文件合并至主记忆文件

所有工作区文件还会检查 workspace.default/ 作为备用路径。

技能（4 个来源）

来源	OpenClaw 位置	Hermes 目标位置
工作区技能	`workspace/skills/`	`~/.hermes/skills/openclaw-imports/`
管理/共享技能	`~/.openclaw/skills/`	`~/.hermes/skills/openclaw-imports/`
个人跨项目技能	`~/.agents/skills/`	`~/.hermes/skills/openclaw-imports/`
项目级共享技能	`workspace/.agents/skills/`	`~/.hermes/skills/openclaw-imports/`

技能冲突由 --skill-conflict 处理：skip 保留现有 Hermes 技能，overwrite 替换之，rename 创建 -imported 复制版本。

模型与提供方配置

内容	OpenClaw 配置路径	Hermes 目标路径	说明
默认模型	`agents.defaults.model`	`config.yaml` → `model`	可为字符串或 `{primary, fallbacks}` 对象
自定义提供方	`models.providers.*`	`config.yaml` → `custom_providers`	映射 `baseUrl`、`apiType`（"openai"→"chat_completions"，"anthropic"→"anthropic_messages"）
提供方 API 密钥	`models.providers.*.apiKey`	`~/.hermes/.env`	需启用 `--migrate-secrets`。详见下方 API 密钥解析

代理行为

内容	OpenClaw 配置路径	Hermes 配置路径	映射关系
最大轮次	`agents.defaults.timeoutSeconds`	`agent.max_turns`	`timeoutSeconds / 10`，上限为 200
详细模式	`agents.defaults.verboseDefault`	`agent.verbose`	"off" / "on" / "full"
思考力度	`agents.defaults.thinkingDefault`	`agent.reasoning_effort`	"always"/"high" → "high"，"auto"/"medium" → "medium"，"off"/"low"/"none"/"minimal" → "low"
压缩功能	`agents.defaults.compaction.mode`	`compression.enabled`	"off" → false，其他值 → true
压缩模型	`agents.defaults.compaction.model`	`compression.summary_model`	直接复制字符串
人类延迟	`agents.defaults.humanDelay.mode`	`human_delay.mode`	"natural" / "custom" / "off"
人类延迟时间	`agents.defaults.humanDelay.minMs` / `.maxMs`	`human_delay.min_ms` / `.max_ms`	直接复制
时区	`agents.defaults.userTimezone`	`timezone`	直接复制字符串
执行超时	`tools.exec.timeoutSec`	`terminal.timeout`	直接复制（字段为 `timeoutSec`，非 `timeout`）
Docker沙箱	`agents.defaults.sandbox.backend`	`terminal.backend`	"docker" → "docker"
Docker 镜像	`agents.defaults.sandbox.docker.image`	`terminal.docker_image`	直接复制

会话重置策略

OpenClaw 配置路径	Hermes 配置路径	说明
`session.reset.mode`	`session_reset.mode`	"daily"、"idle" 或两者兼有
`session.reset.atHour`	`session_reset.at_hour`	每日重置的小时数（0–23）
`session.reset.idleMinutes`	`session_reset.idle_minutes`	无操作分钟数

注意：OpenClaw 还有 session.resetTriggers（一个简单的字符串数组，如 ["daily", "idle"]）。如果未找到结构化 session.reset，迁移将回退至从 resetTriggers 推断。

MCP 服务器

OpenClaw 字段	Hermes 字段	说明
`mcp.servers.*.command`	`mcp_servers.*.command`	Stdio 传输
`mcp.servers.*.args`	`mcp_servers.*.args`
`mcp.servers.*.env`	`mcp_servers.*.env`
`mcp.servers.*.cwd`	`mcp_servers.*.cwd`
`mcp.servers.*.url`	`mcp_servers.*.url`	HTTP/SSE 传输
`mcp.servers.*.tools.include`	`mcp_servers.*.tools.include`	工具过滤
`mcp.servers.*.tools.exclude`	`mcp_servers.*.tools.exclude`

TTS（文本转语音）

TTS 设置从两个 OpenClaw 配置位置读取，优先级如下：

messages.tts.providers.{provider}.*（标准位置）
顶层 talk.providers.{provider}.*（回退位置）
旧版扁平键 messages.tts.{provider}.*（最旧格式）

项目	Hermes 目标位置
提供商名称	`config.yaml` → `tts.provider`
ElevenLabs 语音 ID	`config.yaml` → `tts.elevenlabs.voice_id`
ElevenLabs 模型 ID	`config.yaml` → `tts.elevenlabs.model_id`
OpenAI 模型	`config.yaml` → `tts.openai.model`
OpenAI 语音	`config.yaml` → `tts.openai.voice`
Edge TTS 语音	`config.yaml` → `tts.edge.voice`
TTS 资产	`~/.hermes/tts/`（文件复制）

消息平台

平台	OpenClaw 配置路径	Hermes `.env` 变量	说明
Telegram	`channels.telegram.botToken`	`TELEGRAM_BOT_TOKEN`	Token 可为字符串或 SecretRef
Telegram	`credentials/telegram-default-allowFrom.json`	`TELEGRAM_ALLOWED_USERS`	从 `allowFrom[]` 数组中以逗号连接
Discord	`channels.discord.token`	`DISCORD_BOT_TOKEN`
Discord	`channels.discord.allowFrom`	`DISCORD_ALLOWED_USERS`
Slack	`channels.slack.botToken`	`SLACK_BOT_TOKEN`
Slack	`channels.slack.appToken`	`SLACK_APP_TOKEN`
Slack	`channels.slack.allowFrom`	`SLACK_ALLOWED_USERS`
WhatsApp	`channels.whatsapp.allowFrom`	`WHATSAPP_ALLOWED_USERS`	通过 Baileys QR 配对认证（非 token）
Signal	`channels.signal.account`	`SIGNAL_ACCOUNT`
Signal	`channels.signal.httpUrl`	`SIGNAL_HTTP_URL`
Signal	`channels.signal.allowFrom`	`SIGNAL_ALLOWED_USERS`
Matrix	`channels.matrix.botToken`	`MATRIX_ACCESS_TOKEN`	通过 deep-channels 迁移
Mattermost	`channels.mattermost.botToken`	`MATTERMOST_BOT_TOKEN`	通过 deep-channels 迁移

其他配置

项目	OpenClaw 路径	Hermes 路径	说明
审批模式	`approvals.exec.mode`	`config.yaml` → `approvals.mode`	"auto"→"off", "always"→"manual", "smart"→"smart"
命令白名单	`exec-approvals.json`	`config.yaml` → `command_allowlist`	模式合并并去重
浏览器 CDP URL	`browser.cdpUrl`	`config.yaml` → `browser.cdp_url`
浏览器无头模式	`browser.headless`	`config.yaml` → `browser.headless`
Brave 搜索密钥	`tools.web.search.brave.apiKey`	`.env` → `BRAVE_API_KEY`	需启用 `--migrate-secrets`
网关认证 token	`gateway.auth.token`	`.env` → `HERMES_GATEWAY_TOKEN`	需启用 `--migrate-secrets`
工作目录	`agents.defaults.workspace`	`.env` → `MESSAGING_CWD`

已归档（无直接 Hermes 对应项）

这些配置将保存至 ~/.hermes/migration/openclaw/<timestamp>/archive/ 以供手动审查：

项目	归档文件	如何在 Hermes 中重建
`IDENTITY.md`	`archive/workspace/IDENTITY.md`	合并至 `SOUL.md`
`TOOLS.md`	`archive/workspace/TOOLS.md`	Hermes 内置工具说明
`HEARTBEAT.md`	`archive/workspace/HEARTBEAT.md`	使用 cron 任务实现周期性任务
`BOOTSTRAP.md`	`archive/workspace/BOOTSTRAP.md`	使用上下文文件或技能
Cron 任务	`archive/cron-config.json`	使用 `hermes cron create` 重建
插件	`archive/plugins-config.json`	参见插件指南
钩子/Webhook	`archive/hooks-config.json`	使用 `hermes webhook` 或网关钩子
内存后端	`archive/memory-backend-config.json`	通过 `hermes honcho` 配置
技能注册表	`archive/skills-registry-config.json`	使用 `hermes skills config`
UI/身份	`archive/ui-identity-config.json`	使用 `/skin` 命令
日志	`archive/logging-diagnostics-config.json`	在 `config.yaml` 的 logging 部分设置
多代理列表	`archive/agents-list.json`	使用 Hermes 配置文件
通道绑定	`archive/bindings.json`	按平台手动设置
复杂通道	`archive/channels-deep-config.json`	手动平台配置

API 密钥解析

当启用 --migrate-secrets 时，API 密钥将按优先级从 三个来源 收集：

配置值 — models.providers.*.apiKey 和 openclaw.json 中 TTS 提供商密钥
环境文件 — ~/.openclaw/.env（如 OPENROUTER_API_KEY、ANTHROPIC_API_KEY 等）
认证配置文件 — ~/.openclaw/agents/main/agent/auth-profiles.json（按代理的凭据）

配置值具有最高优先级。.env 文件用于填充缺失的值。认证配置文件则用于填充剩余的空白。

支持的键目标

OPENROUTER_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, DEEPSEEK_API_KEY, GEMINI_API_KEY, ZAI_API_KEY, MINIMAX_API_KEY, ELEVENLABS_API_KEY, TELEGRAM_BOT_TOKEN, VOICE_TOOLS_OPENAI_KEY

不在上述允许列表中的键将永远不会被复制。

SecretRef 处理

OpenClaw 配置中用于令牌和 API 密钥的值可以采用三种格式：

// Plain string
"channels": { "telegram": { "botToken": "123456:ABC-DEF..." } }

// Environment template
"channels": { "telegram": { "botToken": "${TELEGRAM_BOT_TOKEN}" } }

// SecretRef object
"channels": { "telegram": { "botToken": { "source": "env", "id": "TELEGRAM_BOT_TOKEN" } } }

迁移过程会解析这三种格式。对于环境模板和 source: "env" 的 SecretRef 对象，它会从 ~/.openclaw/.env 中查找对应值。而 source: "file" 或 source: "exec" 的 SecretRef 对象无法自动解析——这些值必须在迁移后手动添加到 Hermes 中。

迁移后操作

检查迁移报告 —— 迁移完成后会打印报告，包含已迁移、跳过和冲突项的数量。
审查归档文件 —— ~/.hermes/migration/openclaw/<timestamp>/archive/ 中的任何内容都需要手动处理。
验证 API 密钥 —— 运行 hermes status 以检查各服务商的认证状态。
测试消息功能 —— 如果你迁移了平台令牌，请重启网关：systemctl --user restart hermes-gateway
检查会话策略 —— 确认 hermes config get session_reset 的值符合你的预期。
重新配对 WhatsApp —— WhatsApp 使用二维码配对（Baileys），不支持令牌迁移。请运行 hermes whatsapp 来完成配对。

故障排除

“未找到 OpenClaw 目录”

迁移过程会依次检查 ~/.openclaw/、~/.clawdbot/、~/.moldbot/。如果你的安装路径不同，请使用 --source /path/to/your/openclaw 指定路径。

“未找到任何服务商 API 密钥”

密钥可能位于你的 .env 文件中，而非 openclaw.json。迁移过程会同时检查两者——请确保 ~/.openclaw/.env 存在且包含所需密钥。如果密钥使用了 source: "file" 或 source: "exec" 的 SecretRef，则无法自动解析。

迁移后技能未出现

导入的技能会存放在 ~/.hermes/skills/openclaw-imports/。要使这些技能生效，请启动一个新的会话，或运行 /skills 命令以确认它们已加载。

TTS 语音未被迁移

OpenClaw 将 TTS 设置存储在两个位置：messages.tts.providers.* 和顶层的 talk 配置。迁移过程会检查这两个位置。如果你的语音 ID 是通过 OpenClaw UI 设置的（存储在其他路径），可能需要手动设置：hermes config set tts.elevenlabs.voice_id YOUR_VOICE_ID。

快速开始​

选项​

迁移内容​

人格、记忆与指令​

技能（4 个来源）​

模型与提供方配置​

代理行为​

会话重置策略​

MCP 服务器​

TTS（文本转语音）​

消息平台​

其他配置​

已归档（无直接 Hermes 对应项）​

API 密钥解析​

支持的键目标​

SecretRef 处理​

迁移后操作​

故障排除​

“未找到 OpenClaw 目录”​

“未找到任何服务商 API 密钥”​

迁移后技能未出现​

TTS 语音未被迁移​