从 OpenClaw 迁移

本文将为您提供从 OpenClaw 或 Clawdbot 平台完整迁移到 Hermes Agent 的详细步骤。涵盖数据迁移范围、配置文件映射方法，以及迁移完成后必须执行的验证与检查流程。

📌 一、迁移概览

项目	OpenClaw / Clawdbot	Hermes Agent
核心架构	基于 Python + Discord/Telegram 等 Bot 框架	基于 MCP（Model Control Protocol）+ 多 Agent 协作系统
配置管理	YAML/JSON 文件 + 环境变量	`config.yaml` + `env` 文件 + CLI/HTTP API
数据存储	SQLite / MongoDB / 自定义数据库	支持 PostgreSQL / MySQL / SQLite / Redis（可选）
插件机制	内置插件 + 手动脚本扩展	Agent Skills + Plugin Registry（如 agentskills.io）
多平台支持	有限（主要限于 Telegram/Discord）	全面支持：Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Mattermost, DingTalk, Feishu, WeCom 等

✅ 结论：Hermes Agent 是下一代 AI Agent 架构，具备更强的可扩展性、模块化设计和跨平台能力。

🔄 二、哪些内容会被迁移？

✅ 可迁移内容（自动或半自动）

类型	是否支持迁移	说明
用户权限列表（角色/权限组）	✅	映射为 Hermes Agent 中的 `roles` 和 `permissions`
聊天历史记录（部分）	⚠️ 有条件支持	若使用兼容数据库（如 PostgreSQL），可通过脚本导出并导入到 Hermes 的 `chat_history` 表中
自定义命令（Command Handlers）	✅	转换为 Hermes Agent 的 `Skill` 或 `Action` 插件
机器人行为规则（如触发词、响应逻辑）	✅	通过 `rules.json` 导入至 Hermes 的 `rule_engine` 模块
Webhook 配置	✅	迁移为 Hermes 的 `webhook_handler` 配置项
通知模板（邮件/SMS/消息模板）	✅	转换为 Hermes 的 `template` 模板系统
任务调度（Cron Jobs）	✅	使用 Hermes 的 `scheduler` 模块重新配置

❌ 不支持直接迁移的内容

类型	原因	替代方案
旧版自定义 Python 脚本（非标准插件）	架构不兼容	重写为符合 Hermes Skill 规范的 `.py` 插件
本地缓存文件（如 `cache.db`, `temp/`）	无结构化定义	清理或重建
未文档化的私有功能模块	缺乏接口描述	评估是否必要，否则建议弃用

🔧 三、配置映射表（Config Mapping）

以下为关键配置项的迁移对照表：

OpenClaw / Clawdbot 配置项	Hermes Agent 对应项	迁移方式
`bot_token`	`agent.bot.token`	直接复制
`admin_ids`	`agent.security.admins`	列表格式转换
`database_url`	`storage.database.url`	更新连接字符串（支持 PostgreSQL/MySQL）
`plugins.enabled`	`skills.enabled`	逐个启用对应 Skill
`command_prefix`	`agent.command.prefix`	修改为新前缀
`webhook_url`	`webhook.endpoint`	配置 HTTPS 地址
`language`	`agent.locale`	如 `zh-CN`, `en-US`
`log_level`	`logging.level`	`info`, `debug`, `warn` 等
`api_key` (OpenAI etc.)	`providers.openai.api_key`	在 `env` 文件中设置
`model.default`	`agent.default_model`	如 `gpt-4o`, `claude-3-opus`
`max_context_length`	`agent.max_tokens`	调整数值

💡 提示：推荐使用 hermes-migrate-tool 工具（GitHub）自动化生成初始 config.yaml。

🛠 四、迁移步骤详解

步骤 1：备份原始环境

# 备份数据库
cp ./clawdb.sqlite ./backup/clawdb_$(date +%Y%m%d).sqlite

# 备份配置文件
cp config.yaml config_backup.yaml
cp plugins/*.py ./backup/plugins/

步骤 2：安装 Hermes Agent

git clone https://github.com/hermes-agent/hermes-agent.git
cd hermes-agent
pip install -r requirements.txt

步骤 3：创建新配置

# config.yaml
agent:
  name: "MyHermesBot"
  token: "YOUR_SECRET_TOKEN"
  prefix: "/"
  locale: "zh-CN"
  default_model: "gpt-4o"
  max_tokens: 4096

security:
  admins:
    - 123456789
    - 987654321

storage:
  database:
    url: "postgresql://user:pass@localhost/hermes_db"
  cache: "redis://localhost:6379"

providers:
  openai:
    api_key: "YOUR_OPENAI_API_KEY"
  openrouter:
    api_key: "YOUR_OPENROUTER_API_KEY"
  nous:
    api_key: "YOUR_NOUS_API_KEY"

skills:
  enabled:
    - chat
    - weather
    - calculator
    - file_upload
    - rule_engine

📝 注意：请将示例占位值替换为实际密钥，避免泄露。

步骤 4：迁移自定义技能

将原有 plugins/*.py 中的函数封装为 Hermes Skill：

# skills/weather.py
from hermes_agent import Skill

class WeatherSkill(Skill):
    def __init__(self):
        super().__init__("weather", "获取天气信息")

    async def handle(self, query: str) -> str:
        # 替换为真实 API 调用
        return f"当前天气：晴朗，温度 25°C"

注册到 skills/ 目录，并在 config.yaml 中启用。

步骤 5：启动 Hermes Agent

python main.py --config config.yaml

✅ 五、迁移后必查清单（Post-Migration Checklist）

检查项	是否完成	说明
✅ 机器人成功启动并登录	☐	查看日志输出是否有 `Bot is online`
✅ 所有管理员账号可访问控制台	☐	测试 `/admin` 命令
✅ 自定义命令正常响应	☐	输入 `/help` 或 `/weather 北京`
✅ 通知模板已生效	☐	触发事件测试邮件/SMS/消息推送
✅ Webhook 接收测试成功	☐	使用 `curl` 发送模拟请求
✅ 数据库连接正常	☐	查看 `logs/db.log` 是否报错
✅ 日志级别正确	☐	确保生产环境为 `info`
✅ 安全密钥已移除明文	☐	检查 `config.yaml` 是否包含硬编码密钥
✅ 多平台消息通道可用	☐	测试 Telegram/Discord 消息收发
✅ 任务调度器运行正常	☐	查看定时任务是否按计划执行

📚 六、进阶建议

启用身份认证
使用 JWT 或 OAuth2 保护 Admin API，防止未授权访问。
集成监控系统
推荐接入 Prometheus + Grafana，监控模型调用延迟、错误率等指标。
使用 AgentSkills.io 注册你的 Skill
让社区共享你的插件：👉 https://agentskills.io
启用模型路由策略
根据负载自动切换模型（如低优先级用 gpt-3.5-turbo，高精度用 gpt-4o）。
定期审计权限与日志
使用 hermes audit 命令分析用户行为与操作记录。

📞 七、遇到问题？如何求助

官方文档：https://docs.hermes-agent.org
社区支持：
- Discord: https://discord.gg/hermes-agent
- GitHub Issues: https://github.com/hermes-agent/hermes-agent/issues
商业支持（企业版）：contact@hermes-agent.com

🎯 总结

项目	结果
是否能完全迁移？	✅ 可实现大部分功能平滑过渡
是否需要重写代码？	⚠️ 自定义插件需重构为 Skill 格式
是否更强大？	✅ 支持多 Agent、跨平台、可扩展性强
是否推荐迁移？	✅ 强烈推荐！Hermes Agent 是未来方向

🚀 立即行动：现在就用 hermes-migrate-tool 开始迁移，体验下一代 AI Agent 的强大能力！

📌 附录：

从 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`	`AGENTS.md` 中的 `--workspace-target`	需要启用 `--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`	标准输入输出传输
`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`
网关认证令牌	`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 jobs） | | BOOTSTRAP.md | archive/workspace/BOOTSTRAP.md | 使用上下文文件或技能（skills） | | 定时任务（Cron jobs） | archive/cron-config.json | 使用 hermes cron create 重建 | | 插件（Plugins） | archive/plugins-config.json | 参见插件指南 | | 钩子/回调（Hooks/webhooks） | archive/hooks-config.json | 使用 hermes webhook 或网关钩子 | | 记忆后端（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 的日志配置部分设置 | | 多代理列表（Multi-agent list） | archive/agents-list.json | 使用 Hermes 配置文件 | | 通道绑定（Channel bindings） | archive/bindings.json | 按平台手动设置 | | 复杂通道（Complex channels） | archive/channels-deep-config.json | 手动进行平台配置 |

API 密钥解析

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

配置值 — models.providers.*.apiKey 和 TTS 提供商密钥位于 openclaw.json
环境文件 — ~/.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。

📌 一、迁移概览​

🔄 二、哪些内容会被迁移？​

✅ 可迁移内容（自动或半自动）​

❌ 不支持直接迁移的内容​

🔧 三、配置映射表（Config Mapping）​

🛠 四、迁移步骤详解​

步骤 1：备份原始环境​

步骤 2：安装 Hermes Agent​

步骤 3：创建新配置​

步骤 4：迁移自定义技能​

步骤 5：启动 Hermes Agent​

✅ 五、迁移后必查清单（Post-Migration Checklist）​

📚 六、进阶建议​

📞 七、遇到问题？如何求助​

🎯 总结​

从 OpenClaw 迁移

快速开始​

选项​

迁移内容​

人物设定、记忆与指令​

技能（4 种来源）​

模型与提供方配置​

代理行为​

会话重置策略​

MCP 服务器​

TTS（文本转语音）​

消息平台​

其他配置​

已归档（无直接对应的 Hermes 功能）​

API 密钥解析​

支持的密钥目标​

SecretRef 处理​

迁移后操作​

故障排除​

“未找到 OpenClaw 目录”​

“未找到提供方 API 密钥”​

迁移后技能未显示​

TTS 语音未迁移成功​

📌 一、迁移概览

🔄 二、哪些内容会被迁移？

✅ 可迁移内容（自动或半自动）

❌ 不支持直接迁移的内容

🔧 三、配置映射表（Config Mapping）

🛠 四、迁移步骤详解

步骤 1：备份原始环境

步骤 2：安装 Hermes Agent

步骤 3：创建新配置

步骤 4：迁移自定义技能

步骤 5：启动 Hermes Agent

✅ 五、迁移后必查清单（Post-Migration Checklist）

📚 六、进阶建议

📞 七、遇到问题？如何求助

🎯 总结

快速开始

选项

迁移内容

人物设定、记忆与指令

技能（4 种来源）

模型与提供方配置

代理行为

会话重置策略

MCP 服务器

TTS（文本转语音）

消息平台

其他配置

已归档（无直接对应的 Hermes 功能）

API 密钥解析

支持的密钥目标

SecretRef 处理

迁移后操作

故障排除

“未找到 OpenClaw 目录”

“未找到提供方 API 密钥”

迁移后技能未显示

TTS 语音未迁移成功