从 OpenClaw 迁移

hermes claw migrate 可以把你的 OpenClaw（或旧版 Clawdbot / Moldbot）配置导入到 Hermes 中。本指南会精确说明会迁移哪些内容、配置键如何映射，以及迁移完成后应检查什么。

快速开始

# Preview then migrate (always shows a preview first, then asks to confirm)
hermes claw migrate

# Preview only, no changes
hermes claw migrate --dry-run

# Full migration including API keys, skip confirmation
hermes claw migrate --preset full --yes

迁移在真正写入之前，总是会先展示一份完整预览，告诉你哪些内容会被导入。请先核对，再确认继续。

默认会从 ~/.openclaw/ 读取。旧版目录 ~/.clawdbot/ 和 ~/.moltbot/ 也会被自动检测；旧版配置文件名（如 clawdbot.json、moltbot.json）同样会自动识别。

选项

Option	Description
`--dry-run`	仅预览，不做任何修改
`--preset <name>`	`full`（默认，包含密钥）或 `user-data`（不含 API key）
`--overwrite`	发生冲突时覆盖已有 Hermes 文件（默认是跳过）
`--migrate-secrets`	包含 API key（`--preset full` 默认启用）
`--source <path>`	指定自定义 OpenClaw 目录
`--workspace-target <path>`	指定 `AGENTS.md` 放置位置
`--skill-conflict <mode>`	`skip`（默认）、`overwrite` 或 `rename`
`--yes`	预览后跳过确认提示

会迁移什么

Persona、记忆和指令

What	OpenClaw source	Hermes destination	Notes
Persona	`workspace/SOUL.md`	`~/.hermes/SOUL.md`	直接复制
Workspace instructions	`workspace/AGENTS.md`	`--workspace-target` 下的 `AGENTS.md`	需要显式提供 `--workspace-target`
Long-term memory	`workspace/MEMORY.md`	`~/.hermes/memories/MEMORY.md`	解析为条目，与现有内容合并并去重，使用 `§` 分隔符
User profile	`workspace/USER.md`	`~/.hermes/memories/USER.md`	与 memory 相同的条目合并逻辑
Daily memory files	`workspace/memory/*.md`	`~/.hermes/memories/MEMORY.md`	所有日记式 memory 文件会合并进主记忆

此外，迁移程序还会尝试在 workspace.default/ 和 workspace-main/ 中查找 workspace 文件，作为回退路径（OpenClaw 近版本把 workspace/ 重命名成了 workspace-main/，多 agent 模式则使用 workspace-{agentId}）。

技能（4 个来源）

Source	OpenClaw location	Hermes destination
Workspace skills	`workspace/skills/`	`~/.hermes/skills/openclaw-imports/`
Managed/shared skills	`~/.openclaw/skills/`	`~/.hermes/skills/openclaw-imports/`
Personal cross-project	`~/.agents/skills/`	`~/.hermes/skills/openclaw-imports/`
Project-level shared	`workspace/.agents/skills/`	`~/.hermes/skills/openclaw-imports/`

技能冲突由 --skill-conflict 控制：skip 会保留 Hermes 现有技能，overwrite 会替换它，rename 会创建一个 -imported 副本。

模型与 provider 配置

What	OpenClaw config path	Hermes destination	Notes
Default model	`agents.defaults.model`	`config.yaml` -> `model`	可以是字符串，也可以是 `{primary, fallbacks}` 对象
Custom providers	`models.providers.*`	`config.yaml` -> `custom_providers`	映射 `baseUrl`、`apiType`/`api`，同时处理短格式（如 `"openai"`、`"anthropic"`）和带连字符格式（如 `"openai-completions"`、`"anthropic-messages"`、`"google-generative-ai"`）
Provider API keys	`models.providers.*.apiKey`	`~/.hermes/.env`	需要 `--migrate-secrets`。详见下方 API key resolution

Agent 行为

What	OpenClaw config path	Hermes config path	Mapping
Max turns	`agents.defaults.timeoutSeconds`	`agent.max_turns`	使用 `timeoutSeconds / 10`，上限 200
Verbose mode	`agents.defaults.verboseDefault`	`agent.verbose`	`"off"` / `"on"` / `"full"`
Reasoning effort	`agents.defaults.thinkingDefault`	`agent.reasoning_effort`	`"always"` / `"high"` / `"xhigh"` -> `"high"`；`"auto"` / `"medium"` / `"adaptive"` -> `"medium"`；`"off"` / `"low"` / `"none"` / `"minimal"` -> `"low"`
Compression	`agents.defaults.compaction.mode`	`compression.enabled`	`"off"` -> false，其它任意值 -> true
Compression model	`agents.defaults.compaction.model`	`compression.summary_model`	直接复制字符串
Human delay	`agents.defaults.humanDelay.mode`	`human_delay.mode`	`"natural"` / `"custom"` / `"off"`
Human delay timing	`agents.defaults.humanDelay.minMs` / `.maxMs`	`human_delay.min_ms` / `.max_ms`	直接复制
Timezone	`agents.defaults.userTimezone`	`timezone`	直接复制字符串
Exec timeout	`tools.exec.timeoutSec`	`terminal.timeout`	直接复制（字段名是 `timeoutSec`，不是 `timeout`）
Docker sandbox	`agents.defaults.sandbox.backend`	`terminal.backend`	`"docker"` -> `"docker"`
Docker image	`agents.defaults.sandbox.docker.image`	`terminal.docker_image`	直接复制

Session reset 策略

OpenClaw config path	Hermes config path	Notes
`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 servers

OpenClaw field	Hermes field	Notes
`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（text-to-speech）

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

messages.tts.providers.{provider}.*（规范位置）
顶层 talk.providers.{provider}.*（回退位置）
旧式平铺键 messages.tts.{provider}.*（更老的格式）

What	Hermes destination
Provider name	`config.yaml` -> `tts.provider`
ElevenLabs voice ID	`config.yaml` -> `tts.elevenlabs.voice_id`
ElevenLabs model ID	`config.yaml` -> `tts.elevenlabs.model_id`
OpenAI model	`config.yaml` -> `tts.openai.model`
OpenAI voice	`config.yaml` -> `tts.openai.voice`
Edge TTS voice	`config.yaml` -> `tts.edge.voice`（OpenClaw 曾把 `"edge"` 重命名为 `"microsoft"`，两种写法都能识别）
TTS assets	`~/.hermes/tts/`（文件复制）

消息平台

Platform	OpenClaw config path	Hermes `.env` variable	Notes
Telegram	`channels.telegram.botToken` 或 `.accounts.default.botToken`	`TELEGRAM_BOT_TOKEN`	token 可以是字符串，也可以是 SecretRef。同时支持扁平布局和 accounts 布局
Telegram	`credentials/telegram-default-allowFrom.json`	`TELEGRAM_ALLOWED_USERS`	从 `allowFrom[]` 数组拼接成逗号分隔
Discord	`channels.discord.token` 或 `.accounts.default.token`	`DISCORD_BOT_TOKEN`
Discord	`channels.discord.allowFrom` 或 `.accounts.default.allowFrom`	`DISCORD_ALLOWED_USERS`
Slack	`channels.slack.botToken` 或 `.accounts.default.botToken`	`SLACK_BOT_TOKEN`
Slack	`channels.slack.appToken` 或 `.accounts.default.appToken`	`SLACK_APP_TOKEN`
Slack	`channels.slack.allowFrom` 或 `.accounts.default.allowFrom`	`SLACK_ALLOWED_USERS`
WhatsApp	`channels.whatsapp.allowFrom` 或 `.accounts.default.allowFrom`	`WHATSAPP_ALLOWED_USERS`	认证依赖 Baileys QR 配对，迁移后需要重新配对
Signal	`channels.signal.account` 或 `.accounts.default.account`	`SIGNAL_ACCOUNT`
Signal	`channels.signal.httpUrl` 或 `.accounts.default.httpUrl`	`SIGNAL_HTTP_URL`
Signal	`channels.signal.allowFrom` 或 `.accounts.default.allowFrom`	`SIGNAL_ALLOWED_USERS`
Matrix	`channels.matrix.accessToken` 或 `.accounts.default.accessToken`	`MATRIX_ACCESS_TOKEN`	使用的是 `accessToken`，不是 `botToken`
Mattermost	`channels.mattermost.botToken` 或 `.accounts.default.botToken`	`MATTERMOST_BOT_TOKEN`

其它配置

What	OpenClaw path	Hermes path	Notes
Approval mode	`approvals.exec.mode`	`config.yaml` -> `approvals.mode`	`"auto"` -> `"off"`，`"always"` -> `"manual"`，`"smart"` -> `"smart"`
Command allowlist	`exec-approvals.json`	`config.yaml` -> `command_allowlist`	模式会合并并去重
Browser CDP URL	`browser.cdpUrl`	`config.yaml` -> `browser.cdp_url`
Browser headless	`browser.headless`	`config.yaml` -> `browser.headless`
Brave search key	`tools.web.search.brave.apiKey`	`.env` -> `BRAVE_API_KEY`	需要 `--migrate-secrets`
Gateway auth token	`gateway.auth.token`	`.env` -> `HERMES_GATEWAY_TOKEN`	需要 `--migrate-secrets`
Working directory	`agents.defaults.workspace`	`.env` -> `MESSAGING_CWD`

已归档（没有直接对应的 Hermes 等价项）

这些内容会被保存到 ~/.hermes/migration/openclaw/<timestamp>/archive/，供你手动复查：

What	Archive file	How to recreate in 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`	用 context files 或技能替代
Cron jobs	`archive/cron-config.json`	用 `hermes cron create` 手动重建
Plugins	`archive/plugins-config.json`	参考 plugins guide
Hooks/webhooks	`archive/hooks-config.json`	用 `hermes webhook` 或 gateway hooks 重新搭建
Memory backend	`archive/memory-backend-config.json`	通过 `hermes honcho` 等方式配置
Skills registry	`archive/skills-registry-config.json`	用 `hermes skills config`
UI/identity	`archive/ui-identity-config.json`	用 `/skin` 命令
Logging	`archive/logging-diagnostics-config.json`	在 `config.yaml` 的 logging 段配置
Multi-agent list	`archive/agents-list.json`	用 Hermes profiles
Channel bindings	`archive/bindings.json`	每个平台手动重新设置
Complex channels	`archive/channels-deep-config.json`	手动平台配置

API key 解析

启用 --migrate-secrets 后，API key 会按优先级从 四个来源 收集：

配置值 —— openclaw.json 中 models.providers.*.apiKey 和 TTS provider keys
环境文件 —— ~/.openclaw/.env（如 OPENROUTER_API_KEY、ANTHROPIC_API_KEY 等）
配置里的 env 子对象 —— openclaw.json -> "env" 或 "env"."vars"（有些版本把密钥放这里而不是单独的 .env）
Auth profiles —— ~/.openclaw/agents/main/agent/auth-profiles.json（按 agent 保存的凭据）

优先使用配置值。后续来源只会补齐前面没填上的空缺。

支持的密钥目标

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

不在这个 allowlist 里的 key 永远不会被复制。

SecretRef 处理

OpenClaw 中 token 和 API key 可能有三种格式：

// 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" } } }

迁移程序会解析这三种格式。对于 env 模板和 source: "env" 的 SecretRef，它会去 ~/.openclaw/.env 与 openclaw.json 的 env 子对象中查值。对于 source: "file" 或 source: "exec" 的 SecretRef，无法自动解析；迁移过程会给出警告，这些值需要你之后通过 hermes config set 手动补上。

迁移后要做什么

查看迁移报告 —— 迁移结束时会打印迁移、跳过和冲突项目的统计
检查归档文件 —— ~/.hermes/migration/openclaw/<timestamp>/archive/ 中的内容都需要人工确认
开启新会话 —— 导入的技能和记忆只会在新会话中生效，不会影响当前会话
验证 API key —— 运行 hermes status 检查 provider 认证情况
测试消息平台 —— 如果迁移了平台 token，请重启 gateway：systemctl --user restart hermes-gateway
检查 session 策略 —— 用 hermes config get session_reset 确认结果符合预期
重新配对 WhatsApp —— WhatsApp 用的是 Baileys QR 配对，不支持 token 迁移。请运行 hermes whatsapp
清理归档 —— 确认一切正常后，可以运行 hermes claw cleanup，把遗留 OpenClaw 目录重命名为 .pre-migration/，避免后续状态混淆

故障排除

"OpenClaw directory not found"

迁移会依次检查 ~/.openclaw/、~/.clawdbot/ 和 ~/.moltbot/。如果你的安装不在这些位置，请显式使用 --source /path/to/your/openclaw。

"No provider API keys found"

不同版本的 OpenClaw 会把 key 放在不同位置：可能直接嵌在 openclaw.json 的 models.providers.*.apiKey，也可能在 ~/.openclaw/.env、openclaw.json 的 "env" 子对象里，或者 agents/main/agent/auth-profiles.json 中。迁移程序会检查这四处。如果 key 使用的是 source: "file" 或 source: "exec" SecretRef，就无法自动解析，需要你之后用 hermes config set 手动添加。

迁移后技能没有出现

导入后的技能会放到 ~/.hermes/skills/openclaw-imports/。请启动一个新会话让它们生效，或者执行 /skills 确认它们是否已加载。

TTS voice 没有迁移过来

OpenClaw 的 TTS 设置有两个可能位置：messages.tts.providers.* 和顶层 talk 配置。迁移程序都会检查。如果你的 voice ID 是通过 OpenClaw UI 设置的（存放在不同路径），可能需要手动补上，例如：

hermes config set tts.elevenlabs.voice_id YOUR_VOICE_ID

快速开始​

选项​

会迁移什么​

Persona、记忆和指令​

技能（4 个来源）​

模型与 provider 配置​

Agent 行为​

Session reset 策略​

MCP servers​

TTS（text-to-speech）​

消息平台​

其它配置​

已归档（没有直接对应的 Hermes 等价项）​

API key 解析​

支持的密钥目标​

SecretRef 处理​

迁移后要做什么​

故障排除​

"OpenClaw directory not found"​

"No provider API keys found"​

迁移后技能没有出现​

TTS voice 没有迁移过来​