hermes-migrate 使用手册

cxr8282026-09-12 12:53

适用版本：v1.0.1 ｜ 平台：Linux / macOS / Windows（git-bash）

一句话定位：在任意两台电脑之间完整、可验证、可回滚地迁移 Hermes（密钥、记忆、会话、技能、皮肤、桌面插件、cron、checkpoints、profiles/ 全部带走）。

目录

  1. [能做什么 / 不能做什么](#能做什么 / 不能做什么)
  2. 环境要求
  3. 获取与启动
  4. [快速开始（30 秒版）](#快速开始（30 秒版）)
  5. 完整命令参考
  6. 场景一：完整迁移到新电脑
  7. 场景二：本机备份与灾难恢复
  8. 场景三：多台电脑部署同一套配置
  9. 校验原理：为什么可以信任它
  10. 加密传输
  11. 常见问题排查
  12. 安全注意事项
  13. 附录

1. 能做什么 / 不能做什么

能：

  • 旧电脑 Hermes 完全退出后 ，把整个主目录打包成 tar.gz + 逐文件 sha256 清单；
  • 新电脑先验货（verify，不动任何数据），再恢复；
  • 恢复采用"先验证后交换"：校验通过才动现有数据，失败则现有数据分毫未动；
  • 现有主目录自动改名备份（.pre-migration.bak），确认无误前随时可回滚；
  • 跨平台迁移：Windows ↔ Linux ↔ macOS 通用。

不能：

  • 不能打包 Hermes 安装本体 （hermes-agent/ 源码 + venv）。venv 按绝对路径编译，跨机器拷贝必坏。新电脑需重新安装 Hermes（建议同版本）；
  • 不能代替你核对版本：跨大版本 state.db 可能读不出，恢复时会提示，请先对齐版本再启动；
  • 不是增量备份：每次是全量快照。

2. 环境要求

依赖 是否硬性 说明
bash ✅ 硬性 Linux/macOS 自带；Windows 用 git-bash（装 Hermes 时已自带，或装 Git for Windows）
coreutils（find/grep/sort/comm/join/awk/sed/tr/xargs/du/df...） ✅ 硬性 三平台预装
tar ✅ 硬性 GNU tar / BSD tar 均可
sha256sum 或 shasum ✅（自动回退） Linux/git-bash 有 sha256sum；macOS 自动改用系统自带 shasum
openssl ⚪ 可选 仅 encrypt/decrypt 需要
hermes 本体 ⚪ 可选 拿不到版本号就写 "unknown"，不影响功能

不需要：Python、Node、网络连接、管理员/root 权限、任何编译过程。

Windows 注意 ：cmd / PowerShell 不能直接运行脚本；双击 hermes-migrate.bat 或打开 git-bash 运行。.bat 会自动检测 bash 并给出提示。

3. 获取与启动

把 release/ 里的 4 个文件（hermes-migrate.sh、hermes-migrate.bat、README.md、LICENSE）放到任意目录，例如 ~/tools/hermes-migrate/。

bash 复制代码 
# Linux / macOS
cd ~/tools/hermes-migrate
chmod +x hermes-migrate.sh          # 只需一次
./hermes-migrate.sh --version       # 确认可用

# Windows（git-bash 里同样；或双击 hermes-migrate.bat）
cd ~/tools/hermes-migrate
bash hermes-migrate.sh --version

换了一台新机器，先跑自检------用合成数据证明工具在这台机器上链路可用：

bash 复制代码 
bash hermes-migrate.sh selftest
# 输出 ✅ 自检通过 = 这台机器上开箱即用

4. 快速开始（30 秒版）

bash 复制代码 
# 旧电脑：完全退出 Hermes 后
bash hermes-migrate.sh export                      # → hermes-backup-<时间戳>.tar.gz + .sha256

# 把两个文件传到新电脑（网盘/邮件前建议先 encrypt，见第 10 节）

# 新电脑：先验货（无需退出 Hermes，不动任何数据）
bash hermes-migrate.sh verify hermes-backup-xxx.tar.gz hermes-backup-xxx.sha256   # ✅ 再继续

# 新电脑：完全退出 Hermes 后恢复
bash hermes-migrate.sh restore hermes-backup-xxx.tar.gz hermes-backup-xxx.sha256  # ✅ 校验通过 = 迁移完成

5. 完整命令参考

所有命令退出码：0 = 成功，1 = 错误（已中止，不会产生半成品），2 = 用法错误。

5.1 export ------ 打包（在源电脑执行）

复制代码 
hermes-migrate export [-o 名称] [--with-everything] [--ignore-running] [--home 路径]
参数 说明
-o 名称 输出文件前缀，生成 <名称>.tar.gz 与 <名称>.sha256。默认 hermes-backup-<时间戳>（生成在当前目录）
--with-everything 连缓存目录（audio_cache/image_cache/cache/lsp）一起打包，包更大更慢
--ignore-running 跳过"Hermes 正在运行"检查强制导出（不推荐------运行中导出的实时文件会使校验失败，见 11.4）
--home 路径 指定主目录（默认按 $HERMES_HOME → ~/.hermes → %LOCALAPPDATA%/hermes 自动查找）

示例：

bash 复制代码 
bash hermes-migrate.sh export
bash hermes-migrate.sh export -o /mnt/usb/hermes-20260908
bash hermes-migrate.sh export --home /data/hermes-home -o ~/Desktop/hermes

务必同时保留两个产物 ：.tar.gz（数据）和 .sha256（校验凭证）。清单很小，丢了它包就无法被验证，等于白传。

5.2 verify ------ 验货（在新电脑收包后先执行，不动主目录）

复制代码 
hermes-migrate verify <数据包.tar.gz> [清单.sha256]

清单参数可省略：默认找同名 .sha256（先试 .tar.gz 后缀替换，再试 .tgz）。会做：tar 结构检查 → 磁盘空间预检 → 临时解包 → 全量哈希比对。

bash 复制代码 
bash hermes-migrate.sh verify hermes-backup-20260908_143805.tar.gz
bash hermes-migrate.sh verify hermes-backup-20260908_143805.tar.gz hermes-backup-20260908_143805.sha256

✅ "包已验证可用，可以放心恢复" 之前，不要执行 restore。

5.3 restore ------ 恢复（在新电脑执行，Hermes 必须完全退出）

复制代码 
hermes-migrate restore <数据包.tar.gz> <清单.sha256> [--force] [--home 路径]
参数 说明
--force ① 已存在 .pre-migration.bak 时：先删除旧备份再生成新备份；② 残留临时区时：清理后重试
--home 路径 恢复到指定路径（全新机器首次恢复、Docker 挂载场景用）

执行流程（四阶段，失败自动回滚）：

  1. 检查 Hermes 未在运行 + 磁盘空间；
  2. 解包到临时区 .migrate-stage（不动现有数据）；
  3. 全量 sha256 校验------不通过立即中止，现有数据分毫未动；
  4. 通过后才把现有主目录改名备份为 .pre-migration.bak，新主目录就位。
bash 复制代码 
bash hermes-migrate.sh restore hermes-backup-20260908_143805.tar.gz hermes-backup-20260908_143805.sha256
# 全新机器（Hermes 还没装/主目录不存在）：
bash hermes-migrate.sh restore backup.tar.gz backup.sha256 --home /home/user/.hermes

5.4 info ------ 查看包内容摘要

复制代码 
hermes-migrate info <数据包.tar.gz> [清单.sha256]

显示：包大小、条目数（文件+空目录+符号链接）、清单头部（工具版本、源系统、Hermes 版本、文件数、目录数、导出时间）。

5.5 selftest ------ 本机环境自检

复制代码 
hermes-migrate selftest

用合成数据（含二进制 NUL、中文文件名、带空格文件名、空目录）跑通"打包→解包→比对 0/0/0 → 篡改检测"，全部通过才输出 ✅。换机器后、正式迁移前，先跑它。

5.6 encrypt / decrypt ------ 加密传输

复制代码 
hermes-migrate encrypt <文件> <输出> [密码]
hermes-migrate decrypt <加密文件> <输出> [密码]
  • 算法：AES-256-CBC + PBKDF2（openssl 标准格式）；
  • 密码也可以环境变量 HERMES_MIGRATE_PASSWORD 提供（脚本/CI 场景）；
  • 包内含明文 API 密钥，走网盘、邮件、聊天软件传输前建议先加密 ；.sha256 清单不含密钥，可明文随传。
bash 复制代码 
bash hermes-migrate.sh encrypt hermes-backup-xxx.tar.gz backup.enc '你的密码'
# 另一端：
bash hermes-migrate.sh decrypt backup.enc hermes-backup-xxx.tar.gz '你的密码'
bash hermes-migrate.sh verify hermes-backup-xxx.tar.gz hermes-backup-xxx.sha256

5.7 其它

复制代码 
hermes-migrate --help       # 用法
hermes-migrate --version    # 版本

5.8 环境变量

变量 作用
HERMES_MIGRATE_PASSWORD encrypt/decrypt 的密码（不传第 3 参数时读取）
HERMES_MIGRATE_HOME 指定主目录（等价 --home，优先级低于 --home）
HERMES_MIGRATE_SKIP_GUARD=1 仅供测试/CI：跳过"Hermes 正在运行"检查。正常使用不要设置

6. 场景一：完整迁移到新电脑

第 1 步：旧电脑准备

  1. 完全退出 Hermes：桌面 app 退出，所有终端里的 hermes/gateway 进程关闭；
  2. 确认版本（建议新电脑装同版本）：hermes --version；
  3. （可选）先自检：bash hermes-migrate.sh selftest。

第 2 步：旧电脑导出

bash 复制代码 
bash hermes-migrate.sh export

等待输出 ✅ 导出完成。产物在当前目录：

  • hermes-backup-20260908_143805.tar.gz
  • hermes-backup-20260908_143805.sha256

第 3 步：传输

  • 本地/局域网：U盘、scp、局域网共享------直接传，无需加密；
  • 网盘/邮件 ：先加密（第 10 节），再把 .enc 和 .sha256 两个文件传过去。

第 4 步：新电脑安装 Hermes（如未安装）

bash 复制代码 
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
  • 版本对齐：与旧电脑相同版本最稳（清单头部记录了旧机版本，恢复时也会比对提示）；
  • 先别聊天：装了之后直接进入第 5 步，避免先生成一套新数据。

第 5 步：新电脑验货

bash 复制代码 
bash hermes-migrate.sh verify hermes-backup-20260908_143805.tar.gz hermes-backup-20260908_143805.sha256

必须看到 ✅ 再继续。

第 6 步：新电脑恢复

完全退出 Hermes 后：

bash 复制代码 
bash hermes-migrate.sh restore hermes-backup-20260908_143805.tar.gz hermes-backup-20260908_143805.sha256

看到 ✅ 恢复完成 + 关键内容全部 ✓。

第 7 步：启动与核对

  1. 启动 Hermes；
  2. 功能核对：hermes doctor 看配置、hermes profile list 看 profile 是否齐全、会话里问一句旧机器的事确认记忆/会话在、设置里确认自定义 provider 还在；
  3. 确认无误后删除旧备份回收空间：rm -rf ~/.hermes.pre-migration.bak（Windows 为 %LOCALAPPDATA%\hermes.pre-migration.bak）。

7. 场景二：本机备份与灾难恢复

同一台机器上做定期快照 / 重装系统前备份：

bash 复制代码 
# 备份（建议退出 Hermes；不退出也能打，但实时文件会标红，见 11.4）
bash hermes-migrate.sh export -o /d/backups/hermes-$(date +%Y%m%d)

# 出事后的恢复（重装完系统 → 装好 Hermes → 验货 → 恢复）
bash hermes-migrate.sh verify /d/backups/hermes-20260908.tar.gz /d/backups/hermes-20260908.sha256
bash hermes-migrate.sh restore /d/backups/hermes-20260908.tar.gz /d/backups/hermes-20260908.sha256

恢复后当前机器原来的数据在 .pre-migration.bak 里------即"备份换回来"也随时可行（删掉新主目录、把 .bak 改回原名即可）。

8. 场景三：多台电脑部署同一套配置

把一台"标准机"的 Hermes 复制到任意数量电脑：

bash 复制代码 
# 标准机导出 → 每台目标机分别执行：
bash hermes-migrate.sh verify 标准包.tar.gz 标准包.sha256
bash hermes-migrate.sh restore 标准包.tar.gz 标准包.sha256

注意 ：包里含 .env/auth.json（密钥），分发等于把密钥交给所有人。只想分享"配置+技能+人格"而不分享密钥和记忆，请改用官方 hermes profile export / distribution 机制------那是为共享设计的，本工具是全量迁移。

9. 校验原理：为什么可以信任它

导出时对每一个文件 计算 sha256，写入清单；恢复/验货时对新解包的文件全部重算，四重比对：

检查 抓什么
缺失（清单有、树里没有） 漏拷的文件
多余（树里有、清单没有） 多出来的/错位的文件（错位会同时出现在缺失+多余）
内容不同（同名不同哈希） 传输损坏、被改写、半截文件
数量一致（清单声称数 = 实际数） 结构性偏差

任何一项不为 0，都列出具体文件路径，并拒绝恢复------不存在"看起来成功其实缺东西"的状态。内容被改一个字节都会被抓住（selftest 里专门验证了篡改检测）。

10. 加密传输

bash 复制代码 
# 发送端
bash hermes-migrate.sh encrypt hermes-backup-xxx.tar.gz backup.enc '设置一个强密码'
# 接收端（两个文件都收到后）
bash hermes-migrate.sh decrypt backup.enc hermes-backup-xxx.tar.gz '设置一个强密码'
bash hermes-migrate.sh verify hermes-backup-xxx.tar.gz hermes-backup-xxx.sha256
  • 密码用私聊另行告知，不要和文件走同一条通道；
  • 清单 .sha256 不含密钥，明文传输无妨；
  • 忘记密码 = 无法解密 = 数据丢失，务必妥善保管。

11. 常见问题排查

11.1 "✗ 检测到 Hermes 相关进程仍在运行"

完全退出桌面 app + 所有终端里的 hermes 进程后再试。Windows 下确认方法：任务管理器里没有 Hermes.exe；或 tasklist | grep -i hermes 无输出。

11.2 校验失败：缺失/多余/内容不同

差异文件会列出。按顺序排查：

  1. 传输损坏 → 重传，或改用加密 + 校验流程；
  2. 导出时 Hermes 没退干净 → 实时文件（state.db-wal、logs/agent.log、state/gateway.heartbeat 等）哈希对不上是典型特征------完全退出后重新导出；
  3. 重新 verify，确认 ✅ 后再 restore。

11.3 restore 报"已存在备份 xxx.pre-migration.bak"

上次恢复后没清理，或想重来。确认旧备份不需要后：rm -rf <路径>，或加 --force（先删旧备份再生成新备份）。

11.4 没退出 Hermes 就导出了会怎样？

不会坏，但校验会报"内容不同"------因为 state.db-wal 这类文件在打包瞬间还在写。这不是工具坏了，是校验在起作用。退出后重新导出即可。

11.5 找不到 Hermes 主目录

工具按 $HERMES_HOME → ~/.hermes → %LOCALAPPDATA%/hermes 查找。都不对就显式指定：--home <路径>（Docker 挂载、自定义安装位置都这样处理）。

11.6 新电脑还没装 Hermes 就恢复

先装 Hermes（同版本），不要 先运行/聊天，直接 restore --home <期望路径>（或让工具自动定位）。工具会把你刚生成的主目录先改名备份，不会覆盖丢失。

11.7 版本不一致警告

清单头部记录了旧机 Hermes 版本。跨大版本 state.db 可能不兼容：把新机 Hermes 重装到旧机同版本再启动。小版本差异一般可自动迁移（Hermes 启动时会做数据库迁移并留紧急备份）。

11.8 磁盘空间不足

verify/restore 需要约"包体积 × 3"的临时空间。清出空间重试；恢复的临时区是 .migrate-stage，失败会自动清理。

11.9 selftest 失败

说明这台机器的环境有问题（缺工具、tar 行为异常等）。把输出发出来排查；工具本身在 Windows 11 + git-bash、Linux、macOS 上验证通过。

12. 安全注意事项

  1. 包里是明文密钥 ：.env、auth.json 原样打包。传输走加密或可信通道；分享包给别人 = 把密钥给别人；
  2. 清单不含密钥，但含完整文件路径清单------介意路径信息泄露的也别明文乱传；
  3. 恢复后先确认一切正常再删 .pre-migration.bak；删了就回不去了；
  4. --ignore-running 和 HERMES_MIGRATE_SKIP_GUARD 都是绕过安全护栏的开关，正常使用不要碰；
  5. 收到陌生人的迁移包：先 verify 再 restore，且 verify 只能证明包与清单一致，不能证明包本身无害------只恢复自己信任来源的包（包内含 SOUL、skills、hooks，可能有恶意代码）。

13. 附录

13.1 排除清单（默认不打包的内容）

类别 内容 说明
安装树 hermes-agent/、bin/、node/、bootstrap-cache/、hermes-setup.exe、install_id、构建戳 venv 绝对路径编译，跨机必坏；新机重装同版本
运行态 gateway.pid、gateway.lock、auth.lock、gateway_state.json、gateway-starts.log、processes.json、.update_*、*.lock、*.tmp 启动时自动重建
缓存（--with-everything 时也打包） audio_cache/、image_cache/、cache/、document_cache/、lsp/ 可再生，不影响功能与参数

其余全部带走 ：.env、auth.json、SOUL.md、config.yaml、state.db、sessions/、memories/、skills/、skins/、desktop-plugins/、pets/、plugins/、hooks/、cron/、checkpoints/、profiles/（含全部子 profile）、空目录、符号链接。

13.2 清单格式

复制代码 
# tool: hermes-migrate 1.0.1        ← 生成工具版本
# os: MINGW64_NT-10.0-26220        ← 源系统
# hermes-version: Hermes Agent ...   ← 源 Hermes 版本（用于版本核对）
# files: 7692                       ← 文件数（校验基准之一）
# dirs: 141                         ← 空目录/符号链接数
# created: 2026-09-08 16:11:47 +0800
<64位sha256>  <相对路径>             ← 每个文件一行

13.3 恢复后的目录状态

复制代码 
%LOCALAPPDATA%\hermes\                 ← 新主目录（来自数据包）
%LOCALAPPDATA%\hermes.pre-migration.bak ← 恢复前的旧主目录（确认后删除）

13.4 快速核对清单（恢复完成后）

  • hermes --version 与旧机一致（或已确认跨版本可迁移）
  • hermes doctor 无红色错误
  • hermes profile list 子 profile 齐全
  • 会话历史可看到旧机器会话
  • 记忆（旧机器上的事项）能回忆起
  • 自定义 LLM provider 及密钥配置在位
  • 桌面皮肤/布局与旧机一致
  • 定时任务（cron）列表在：hermes cron list
相关推荐
仙魁XAN10 分钟前
【WorkBuddy·基础入门】第 四 篇 ：模式、技能、专家、连接器一次讲清
人工智能·workbuddy·workbuddy 基础入门·workbuddy 工具
呆萌很14 分钟前
torch.nan_to_num 函数
人工智能
2601_9583529017 分钟前
还要写 AEC 算法？0 代码 + 6 个引脚，F-18 让通话清晰度提升 300%
人工智能·算法·降噪消回音
千里码aicood25 分钟前
基于机器学习的雷达低慢小目标识别技术的研究
人工智能·机器学习
llilian_1628 分钟前
标准时间间隔发生器应用解决方案 脉冲发生器 时间测量仪
大数据·网络·人工智能·功能测试·单片机·嵌入式硬件·51单片机
世岩清上34 分钟前
展厅数字内容同质化严重，怎样打造专属叙事风格？
大数据·前端·javascript·人工智能·html·音视频·展厅改造
幻影123！36 分钟前
AlphaZero 五子棋实战(一):单卡从零自举,我的v36 最终版配置
人工智能·强化学习·马尔科夫·决策过程
固定资产管理系统软件38 分钟前
该去哪里找专业靠谱的智慧智能设备固定资产管理系统？
人工智能·python
具身AGI1 小时前
线缆绳索怎么操控，物理AI 物理推理 的新解法
人工智能
广州山泉婚姻1 小时前
列表初始化：C++11全新初始化体系
c++·人工智能
热门推荐
01国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）02蜘蛛磁力 搜索引擎大全，如何使用蜘蛛磁力查找磁力链接03GitHub 镜像站点04历年考研数学一、数学二、数学三真题试卷及答案PDF05【一等奖版】2026 国赛 A题 药材的烘干问题06微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新072026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？08如何新建文件夹？ 电脑新建文件夹的4种方法09ZCode 周末送额度活动开启：3 亿 Token 免费领取10人工智能（AI）发展史：详细里程碑