ARTICLE · 1199400
Hermes Agent 安装指南(macOS 12 Monterey 实测版)
> 适用环境：macOS 12 (Monterey) · Intel x86_64（darwin-x64）
> 内容来源：官方安装器实测排障记录 + 官方资料核验（补丁 sha256 已与 nodejs.org 官方 SHASUMS256.txt 核对一致）
---
1. 文档说明与适用范围
本文档整理了在 macOS 12 (Monterey) 上首次安装 **Hermes Agent（Nous Research 开源 AI Agent）** 的完整流程，重点解决一个实测中必然遇到的已知问题：
- **现象**：依赖安装阶段 node 二进制启动失败（`dyld: Symbol not found`），安装器报 `pm install failed`
- **根因**：安装器默认拉取的 node 版本（v26.7.0）最低系统要求高于 macOS 12
- **修复**：将 node 固定到 22.11.0 后重新安装
> 适用范围说明：本文档针对 **Intel Mac（darwin-x64）** 实测。Apple Silicon（darwin-arm64）思路相同，需替换补丁中的 URL 与 sha256（见第 4.4 节）。
---
2. 前置条件
| 项目 | 要求 | 说明 |
|---|---|---|
| 操作系统 | macOS 12 (Monterey) | 本文档针对 12.x 实测 |
| 硬件架构 | x86_64（Intel） | 安装器按平台选择 node 产物 |
| 必备工具 | git、curl | 安装器自检通过即可（`✓ prerequisites ok (git, curl)`） |
| 网络 | 可访问 nodejs.org 与 hermes-agent.nousresearch.com | 依赖下载必需 |
| 磁盘空间 | 预留约 500 MB | uv / python / node / ffmpeg 等依赖 |
---
3. 标准安装流程
3.1 官方安装命令
```bash
curl -fsSL https://link.wtturl.cn/?target=https%3A%2F%2Fhermes-agent.nousresearch.com%2Finstall.sh&scene=im&aid=582478&lang=zh | bash
```
等效直连地址（同一脚本）：
```bash
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
```
3.2 安装器执行阶段
| 阶段 | 内容 | 实测输出 |
|---|---|---|
| 1. 环境自检 | 检查 git、curl | `✓ prerequisites ok (git, curl)` |
| 2. 拉取仓库 | 更新到 `/Users/<用户>/.hermes/hermes-agent` 最新稳定版 | `v0.22.2` |
| 3. 准备运行时 | 安装 uv、bootstrap Python | `uv 0.12.3` |
| 4. 安装依赖 | 按 `uv.lock`（hash 校验）安装 ffmpeg、node、npm、python、ripgrep | 任一步失败即 `exit 1` |
| 5. 日志记录 | 完整安装日志 | `~/.hermes/logs/install.log` |
---
4. 已知问题：node 依赖安装失败（macOS 12 必现）
4.1 报错现象
安装器输出（节选）：
```text
✗ Installing dependencies (hash-verified via uv.lock) failed (exit 1). Last output:
✓ ffmpeg
node: 100.0% 30.6 MiB / 30.6 MiB
node: unpacking
✗ node: staged entry failed verification: .../tree/bin/node --version exited -6:
dyld[94703]: Symbol not found: (__ZNSt3__122__libcpp_verbose_abortEPKcz)
Referenced from: '.../tree/bin/node'
Expected in: '/usr/lib/libc++.1.dylib'
✗ pm install failed
```
4.2 报错信息解读
| 报错片段 | 含义 |
|---|---|
| `staged entry failed verification: node --version exited -6` | 安装器对暂存区 node 二进制做冒烟验证时异常退出（`-6` = SIGABRT） |
| `Symbol not found: __ZNSt3__122__libcpp_verbose_abortEPKcz` | node 引用了系统 libc++ 中不存在的符号（`std::__1::__libcpp_verbose_abort`，来自新版 libc++） |
| `Expected in: '/usr/lib/libc++.1.dylib'` | macOS 12 自带的 C++ 标准库版本过旧 |
| `retry, or run hermes pm doctor` | 安装器给出的标准排障入口 |
4.3 根因分析
1. **版本断层**：安装器默认拉取 node **v26.7.0**。Node.js 官方迁移文档（v22 → v24）明确：**自 Node.js 24 起，macOS 预编译二进制的最低系统要求为 macOS 13.5**。因此 v26.7.0 在 macOS 12 上根本无法启动。
2. **链接失败**：新版 node 由更新的 Xcode / libc++ 工具链构建，二进制引用了 `__libcpp_verbose_abort` 等新符号；macOS 12 系统自带的 `/usr/lib/libc++.1.dylib` 缺少这些符号 → dyld 动态链接失败 → 进程 SIGABRT。
3. **与 Hermes 安装器无关**：这是 node 二进制与系统版本不兼容的通用问题，同类报错也出现在其他使用新版工具链构建的二进制上。
**结论：在 macOS 12 上安装，必须把 node 固定到仍支持旧系统版本的 22.x 系列（Node 22 官方支持 macOS 10.15+）。**
### 4.4 解决方案：将 node 固定到 22.11.0
**步骤①：备份依赖清单**
```bash
cd ~/.hermes/hermes-agent
cp pm/lock.json pm/lock.json.bak
```
**步骤②：用脚本把 node 版本从 26.7.0 改为 22.11.0**
```bash
python3 - <<'PYEOF'
import json
p = 'pm/lock.json'
d = json.load(open(p))
n = d['packages']['node']
n['version'] = '22.11.0'
dx = n['artifacts']['darwin-x64']
dx['url'] = 'https://nodejs.org/dist/v22.11.0/node-v22.11.0-darwin-x64.tar.xz'
dx['sha256'] = 'ab28d1784625d151e3f608a9412a009118f376118ed842ae643f8c2efdfb0af6'
json.dump(d, open(p, 'w'), indent=2)
print('patched: node 26.7.0 -> 22.11.0')
PYEOF
```
脚本说明：
- `d['packages']['node']`：定位 node 包定义；
- `artifacts.darwin-x64`：Intel Mac 产物，URL 与 sha256 均来自 nodejs.org 官方分发（sha256 已与官方 `SHASUMS256.txt` 核对一致）；
- **Apple Silicon 用户**：将 `darwin-x64` 改为 `darwin-arm64`，并将 URL / sha256 同步替换为 `node-v22.11.0-darwin-arm64` 对应值；
- 如需更换其他 22.x 版本，在 <https://nodejs.org/dist/> 对应目录的 `SHASUMS256.txt` 中取官方 sha256。
**步骤③：重新安装依赖**
```bash
hermes pm install
```
若提示 `hermes: command not found`（命令未进入 PATH），直接重跑官方安装脚本即可，安装器会识别已存在的 v0.22.2 checkout 并继续：
```bash
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
```
**步骤④：验证安装结果**
```bash
hermes --version
# 或
hermes pm doctor
```
依赖安装阶段应不再出现 `✗ node: staged entry failed verification`，全部组件 `✓` 通过。
---
5. 安装后的初始化配置
```bash
# 可选：关闭遥测上报
hermes config set telemetry.shared_metrics.enabled false
# 安装并启动 gateway（交互式向导）
hermes gateway install
```
交互式向导会依次要求：
1. **选择 provider**（模型服务商）；
2. **填写 API key**（对应服务商的密钥）。
---
6. 排障速查表
| 现象 | 处理方式 |
|---|---|
| `node: staged entry failed verification` / `dyld: Symbol not found` | 按第 4.4 节将 node 降级至 22.11.0 后重新 `hermes pm install` |
| `hermes: command not found` | 重跑官方安装脚本；检查 `~/.hermes` 相关 PATH 配置 |
| 想查看完整安装日志 | `~/.hermes/logs/install.log` |
| 依赖环境自检 | `hermes pm doctor` |
| 想恢复默认依赖清单 | `cp pm/lock.json.bak pm/lock.json` 后重新 `hermes pm install` |
---
7. 版本信息对照
| 组件 | 原始（安装失败） | 修复后 |
|---|---|---|
| hermes-agent | v0.22.2 | v0.22.2（不变） |
| uv | 0.12.3 | 0.12.3（不变） |
| node | 26.7.0（macOS 12 无法运行） | 22.11.0（LTS，支持 macOS 10.15+） |
| node 产物 | node-v26.7.0-darwin-x64 | node-v22.11.0-darwin-x64.tar.xz |
---
8. 参考来源
- Node.js 官方迁移文档（v22 → v24）：macOS 预编译二进制最低要求 macOS 13.5 — <https://nodejs.org/en/blog/migrations/v22-to-v24>
- node-v22.11.0-darwin-x64.tar.xz 官方 sha256 核验：<https://nodejs.org/dist/v22.11.0/SHASUMS256.txt>
- Node.js v22.11.0 发布说明：<https://nodejs.org/ko/blog/release/v22.11.0>
