# Hermes Migration

> Migrate or backup Hermes Agent between servers — export/import/verify the full state (config, memories, skills, sessions, cron, gateway). Class-level skill covering any Hermes relocation scenario.

- Skill: `tyrantlucifer/hermes-migration` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add tyrantlucifer/hermes-migration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tyrantlucifer/hermes-migration/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: TyrantLucifer (https://skillmd.com/u/tyrantlucifer)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/tyrantlucifer/hermes-migration

---


# Hermes Agent 迁移

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

## 什么时候用

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

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

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

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

## 快速使用

### 导出（源服务器）

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

### 导入（目标服务器）

```bash
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` 避免反斜杠问题

## 高级用法

```bash
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 的脚本。

## 定期备份建议

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