Hermes migration

Hermes Agent 迁移

将 Hermes Agent 从一台服务器完整迁移到另一台，覆盖所有持久化状态。

什么时候用

• 服务器迁移 / 换机器
• 灾难恢复（从备份恢复 Hermes）
• 克隆一个 Hermes 实例到新环境
• 定期备份

核心洞察：哪些必须迁移 vs 可重装

~/.hermes/ 可能超过 1GB，但大部分可重建：

• hermes-agent/ 源码（~900MB）— 可 git clone 或 pip install
• bin/（~80MB）— 安装时自动生成
• cache/（~1MB）— 自动重新生成
• logs/ — 不需要迁移
• 核心数据（~30MB）— 必须迁移

快速使用

导出（源服务器）

hermes gateway stop                              # 停止 gateway 保证数据一致
bash ~/.hermes/skills/autonomous-ai-agents/hermes-migration/scripts/hermes-export.sh
# 输出: ~/hermes-migration-YYYYMMDD_HHMMSS.tar.gz (~13MB)

导入（目标服务器）

scp hermes-migration-*.tar.gz user@target:~/
scp ~/.hermes/skills/autonomous-ai-agents/hermes-migration/scripts/hermes-{import,verify}.sh user@target:~/

# 目标服务器上：
bash hermes-import.sh hermes-migration-*.tar.gz  # 一键导入
bash hermes-verify.sh                            # 21 项验证
hermes doctor                                    # 最终检查
hermes gateway start                             # 启动

迁移内容清单

核心（必须）：

• config.yaml — 主配置（模型、provider、代理等）
• .env — API keys 和 secrets
• auth.json — OAuth 令牌、凭证池
• SOUL.md — Agent 身份定义

数据与能力：

• memories/ — MEMORY.md（AI 记忆）+ USER.md（用户画像）
• skills/ — 所有已安装/自建 Skills + .usage.json 使用统计 + .curator_state
• state.db + WAL — 会话数据库（SQLite，所有对话历史）
• sessions/ — JSONL 会话转录文件

自动化与集成：

• cron/jobs.json — 定时任务
• plugins/ + hooks/ — 自定义插件和 Shell hooks
• gateway_state.json + channel_directory.json — 平台连接状态
• weixin/、platforms/、pairing/、shared/ — 平台特定状态
• kanban.db — 多 Agent 协作看板

脚本说明

脚本	用途	关键特性
hermes-export.sh	源服务器导出	自动打包所有数据，记录环境元信息
hermes-import.sh	目标服务器导入	自动安装 Hermes + 恢复数据 + 依赖检测
hermes-verify.sh	迁移后验证	21 项检查（文件/数据库/依赖/网络）

Pitfalls

1. Gateway 必须先停止 — 运行中的 gateway 持有 SQLite WAL 锁，可能导致导出的 state.db 不一致
2. set -e + bash 算术 — ((PASS++)) 在 PASS=0 时返回 exit code 1（bash 中 0 是 falsy），验证脚本用 set +e 规避
3. Skills 合并非覆盖 — 导入用 cp -rn，不会覆盖目标已有的 skills；元数据文件（.usage.json 等）会覆盖以保留源状态
4. API Key 可能受限 — .env 中的 key 可能有 IP 白名单或内网限制，迁移后需验证
5. OAuth 令牌可能过期 — auth.json 迁移后需 hermes auth 重新认证
6. 内网环境 — 字节跳动等内网需单独配置 bnpm registry、Mihomo 代理，脚本会检测并提示
7. SQLite WAL checkpoint — 导入后首次启动 Hermes 会自动 checkpoint WAL，state.db-wal 会变小
8. read -p 管道问题 — 非交互运行时用 echo "y" | bash script.sh，脚本中已用 read -rp 避免反斜杠问题

高级用法

HERMES_HOME=/opt/hermes bash hermes-import.sh archive.tar.gz  # 自定义目录
SKIP_INSTALL=1 bash hermes-import.sh archive.tar.gz           # 跳过安装
DRY_RUN=1 bash hermes-import.sh archive.tar.gz                # 只预览

Hermes 内置 Profile 导出

Hermes 有 hermes profile export NAME / hermes profile import FILE，但只覆盖单个 profile，不包含全局 config、memories、auth、cron、gateway 状态。完整迁移请用本 skill 的脚本。

定期备份建议

# crontab: 每周日凌晨 3 点备份
0 3 * * 0 bash ~/.hermes/skills/autonomous-ai-agents/hermes-migration/scripts/hermes-export.sh ~/hermes-backups/