Hermes Agent迁移至外部硬盘完整教程2026

背景

Hermes Agent 默认会把所有数据都塞进 ~/.hermes/ 这个目录里——包括程序本体（venv、node_modules）和用户数据（sessions、memories、skills 等）。用着用着你就会发现，这个目录越长越胖。如果你的 Mac 内置 SSD 空间紧张，本教程就是为你准备的：把整个 Hermes 数据迁移到外部硬盘上，轻松释放宝贵的内置空间。

前提条件

动手之前，先确认两件事：

• 外部硬盘的格式必须是 APFS 或 Mac OS Extended (HFS+)。NTFS 和 exFAT 就别想了，它们不支持符号链接和 Unix 权限，用不了。
• 外部硬盘上有足够的可用空间。目前 Hermes 大概占 1 GB，但这个数字会随着使用慢慢涨上去。

迁移步骤

Step 1: 停止 Hermes

# 检查一下 Hermes 是不是还在跑
ps aux | grep -i hermes | grep -v grep
# 如果还在运行，先停掉
hermes stop
# 或者直接强制终止
pkill -f hermes

重要：一定要等 Hermes 完全停止后再进行下一步操作。否则，数据损坏的风险可不是闹着玩的。

Step 2: 确认外部硬盘状态

# 看看外部硬盘挂载在哪儿了
ls /Volumes/

# 确认文件系统类型（必须是 APFS 或 HFS+）
diskutil info /Volumes/你的硬盘名 | grep "File System"

# 看看还剩多少空间
df -h /Volumes/你的硬盘名

Step 3: 移动数据到外部硬盘

# 把 ~/.hermes 整个目录搬到外部硬盘（目录名可以自己定义）
mv ~/.hermes /Volumes/你的硬盘名/.hermes

为什么用 mv 而不是 cp？

在同一文件系统内，mv 是瞬间完成的，因为它只改了个指针。跨文件系统时，它本质上就是 cp + rm，但写法更简洁。一步到位，没毛病。

Step 4: 创建符号链接

# 在原位置创建一个指向外部硬盘的符号链接
ln -s /Volumes/你的硬盘名/.hermes ~/.hermes

为什么不用 HERMES_HOME 环境变量，非得用符号链接？

关键在于 Hermes 的 Python 虚拟环境（venv）里，所有脚本的 shebang 都硬编码了路径，比如#!/Users/你的用户名/.hermes/hermes-agent/venv/bin/python3。如果你用 HERMES_HOME 指向新位置，venv 内部的全部路径都会断裂，hermes 命令直接就废了。

符号链接的效果就是：让系统“以为”数据还在 ~/.hermes/ 里，所有硬编码路径都能正常解析。这才是真正无损的方案。

Step 5: 验证

# 确认符号链接指向正确
ls -la ~/.hermes
# 输出应该类似: ~/.hermes -> /Volumes/你的硬盘名/.hermes

# 确认 hermes 命令可用
hermes --version

# 确认配置文件也能正常访问
cat ~/.hermes/config.yaml

推出外部硬盘前的操作

务必先停止 Hermes，再推出硬盘！ 否则后果很严重：

• Hermes 进程可能崩溃或挂起，无法读写数据
• macOS 直接拒绝推出硬盘，提示“磁盘正在使用中”
• 最坏的情况：数据库文件（state.db）损坏，数据全白干

安全推出流程

# 1. 停止 Hermes
hermes stop 2>/dev/null
pkill -f hermes 2>/dev/null

# 2. 确认没有进程在访问外部硬盘
lsof +D /Volumes/你的硬盘名/.hermes 2>/dev/null

# 如果有输出，说明还有进程在用，逐一关闭或 kill
# 例如：kill 

# 3. 安全推出
diskutil eject /Volumes/你的硬盘名
# 或者在 Finder 里点推出按钮也行

重新插入硬盘后

插入硬盘后，符号链接会自动重新生效，Hermes 直接恢复可用。不需要额外操作，直接运行 hermes 就行，省心。

回滚（迁移回内置硬盘）

万一想迁回内置硬盘，操作也很简单：

# 1. 停止 Hermes
hermes stop 2>/dev/null && pkill -f hermes 2>/dev/null

# 2. 删除符号链接
rm ~/.hermes

# 3. 把数据搬回来
mv /Volumes/你的硬盘名/.hermes ~/.hermes

# 4. 验证一下
hermes --version

目录结构参考

~/.hermes/ → 符号链接到外部硬盘
├── hermes-agent/ (程序本体 ~1 GB)
│ ├── venv/ (Python 虚拟环境, ~538 MB)
│ ├── ui-tui/ (TUI 界面, ~191 MB)
│ ├── node_modules/ (Node.js 依赖, ~146 MB)
│ ├── skills/ (内置技能)
│ └── agent/ (核心袋里逻辑)
├── skills/ (自定义/学习到的技能, 会增长)
├── sessions/ (会话历史, 会增长)
├── memories/ (跨会话记忆, 会增长)
├── audio_cache/ (语音缓存, 会增长)
├── image_cache/ (图片缓存, 会增长)
├── config.yaml (配置文件)
├── SOUL.md (Agent 人格定义)
├── auth.json (API 密钥)
└── state.db (状态数据库)

重命名外部硬盘上的目录

如果你对外部硬盘上的目录名不满意——比如想把 hermes-data 改成 .hermes——随时可以重命名：

# 1. 停止 Hermes
hermes stop 2>/dev/null && pkill -f hermes 2>/dev/null

# 2. 删除旧的符号链接
rm ~/.hermes

# 3. 重命名外部硬盘上的目录
mv /Volumes/你的硬盘名/旧目录名 /Volumes/你的硬盘名/新目录名

# 4. 重新创建符号链接指向新名称
ln -s /Volumes/你的硬盘名/新目录名 ~/.hermes

# 5. 验证
ls -la ~/.hermes
hermes --version

注意：. 开头的目录在 Finder 中是默认隐藏的。按 Cmd + Shift + . 可以切换显示隐藏文件。

操作记录

初次迁移 (2026-04-22)

• 源路径: ~/.hermes/ (1.0 GB, 71213 个文件)
• 目标路径: /Volumes/WDBlueSN5000/hermes-data/
• 外部硬盘: WD Blue SN5000 (931 GB APFS)
• 方案: 符号链接（~/.hermes → 外部硬盘）
• 验证: rsync 复制后对比文件数量一致，hermes v0.10.0 正常运行

目录重命名 (2026-04-22)

• 操作: 将外部硬盘上的 hermes-data 重命名为 .hermes
• 步骤: 删除符号链接 → mv 重命名 → 重建符号链接
• 最终路径: ~/.hermes → /Volumes/WDBlueSN5000/.hermes
• 验证: hermes v0.10.0 正常运行

踩坑记录：为什么不能用 HERMES_HOME 环境变量

• 最初尝试设置 export HERMES_HOME="/Volumes/WDBlueSN5000/hermes-data" 并直接 mv 整个目录
• 结果: hermes 命令无法运行，因为 venv 内脚本的 shebang 硬编码了 #!/Users/cc/.hermes/hermes-agent/venv/bin/python3
• 解决: 改用符号链接方案，让所有硬编码路径透明解析到外部硬盘