背景
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 - 解决: 改用符号链接方案，让所有硬编码路径透明解析到外部硬盘
