Hermes Agent 安装踩坑手记:Intel Mac 与受限网络下的 5 个救命方案

島主发布于 2026-8-16 15:37 阅读：65 建站运维

最近在 Intel MacBook Pro 上安装 Hermes Agent(https://github.com/NousResearch/hermes-agent) 时遭遇了一连串"正常安装路径全失效"的问题:官方 install.sh 死锁、github.com 超时、cryptography 50.0.0 居然只发 arm64 wheel、www.openssl.org 实际 301 重定向到 github release…… 一路踩坑后我发现只要掌握 5 个关键绕行方案,哪怕硬件被放弃也能搞定。

先说结论:环境与预期落差

设备:MacBook Pro 16,2 (Intel Core i7 @ 2.3GHz) · 32GB RAM · macOS 13.7.8 (Ventura)
网络限制:github.com:443 连接超时,DuckDuckGo 不可达,brew 的 GitHub bottle 走不通
目标:安装 Hermes Agent v0.20.1,CLI 可用 + hermes doctor 通过

官方文档的 "curl | bash" 在我这台机器上会依次在 3 处卡死,需要逐个修补。

坑 1:官方安装器 git fetch 死锁

现象:运行 install.sh,输出停在 "Existing installation found, updating..." 几十分钟没反应,最后报 RPC failed; curl 28 Failed to connect to github.com port 443 after 75000 ms(exit code 128)。

根因:该环境对 github.com 做了屏蔽/延迟,HTTP 层面握手超时。官方安装器默认每次安装前先 git fetch origin main,即使你本地已经是最新代码也非要跑一遍。

救命方案:跳过安装器,确认你本地仓库是完整的即可。在我的案例里 ~/.hermes/hermes-agent/ 其实在之前已经克隆完成,且 uv / Node / Python 3.11 都装好了,就差建 venv 与装 Python 包。

# 本地检查:这 4 项齐全就可以跳过官方脚本,手动补后续步骤
ls ~/.hermes/hermes-agent/.git   # 仓库已克隆
~/.hermes/bin/uv --version       # uv 包管理器
~/.hermes/node/bin/node --version # Node.js v22
~/.hermes/hermes-agent/hermes    # CLI 入口脚本

坑 2:--extra all 249 包 + 依赖源码编译卡死

现象:运行 uv sync --extra all --locked 或 uv pip install -e '.[all]' 后,uv 进程 CPU 0.0%,日志不动达 3 分钟。ps aux | grep builds-v0 发现一个 python 子进程卡在编译环境里。

根因:[all] extra 会一次性引入 ML / 浏览器 / 语音 / 网关等重型 400+ 依赖栈,含大量 C / Rust native 扩展,任何一个缺 wheel 都会触发 sdist 编译,再加上部分包会拉取 git+https 依赖(对 github 超时),整个链路是"死锁 × 死锁"。

救命方案:最小化起步——先只装 CLI 核心依赖(uv pip install -e .,不带 extra),hermes 的核心功能(chat / model / config / setup / doctor / mcp / skills / gateway / cron)全部能用。以后真需要 TTS / 浏览器 / Telegram 网关时,再按需把那一层单独装回来。

cd ~/.hermes/hermes-agent
~/.hermes/bin/uv pip install --python ./venv/bin/python -e .

坑 3:cryptography 50.0.0 彻底放弃 Intel Mac(x86_64 无 wheel)

现象:最小化安装仍然失败。hermes-agent==0.20.1 在 dependencies 里精确锁了 cryptography==50.0.0(原因是修复多条 CVE: CVE-2026-69247 / GHSA-m2h6-j472-rp4c / CVE-2026-39892 等),而 PyPI 上 cryptography 50.0.0 的 macOS wheel 只有 arm64。

救命方案:Intel Mac 只能从源码编译 cryptography 的 Rust 部分,需要安装 Rust toolchain:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | \
  sh -s -- -y --default-toolchain stable --profile minimal

注:--profile minimal 只装 rustc/cargo/std,比默认 profile 小 50% 且对构建 cryptography 已够用。

坑 4:openssl-sys "找不到 OpenSSL",连 openssl.org 也在往 github 跳

现象:装完 Rust 后重跑,cargo 报 Could not find directory of OpenSSL installation,openssl-sys v0.9.117 build-script 退出 101。你想编译 OpenSSL 3.5.4 源码,www.openssl.org/source/openssl-3.5.4.tar.gz 下载超时——curl -vL 能看到 301 最终指向 github.com/openssl/openssl/releases/download/...,又被 github 屏障拦。

根因:cryptography 50.0.0 workspace 里的依赖是 openssl = "0.10.80"——没有启用 vendored feature。它期望你的系统提供 OpenSSL(比如 brew install openssl@3),但 macOS 系统不带开发头文件,而 Homebrew 在这台机器上虽然装了,它的 bottle 下载源一样会被 github 屏障影响。

救命方案:patch Cargo.toml → 给 openssl / openssl-sys 加 vendored feature(openssl-src crate 会自带 OpenSSL 源码,从 crates.io 下载——本环境 crates.io 是能通的!)。步骤:

# 1. 从 uv 的 sdist 缓存找到 cryptography 的源码复制到稳定位置
#    (uv 每次构建会重新解包,patch 后一定不能让它重新解包覆盖)
SRC_D=$(ls -d ~/.cache/uv/sdists-v9/pypi/cryptography/50.0.0/*/src | head -1)
cp -R "$SRC_D" /tmp/crypto-src

# 2. patch [workspace.dependencies]
sed -i '' 's|^openssl = "0.10.80"$|openssl = { version = "0.10.80", features = ["vendored"] }|' /tmp/crypto-src/Cargo.toml
sed -i '' 's|^openssl-sys = "0.9.116"$|openssl-sys = { version = "0.9.116", features = ["vendored"] }|' /tmp/crypto-src/Cargo.toml

# 3. 更新 Cargo.lock
cd /tmp/crypto-src && source ~/.cargo/env
cargo update --workspace

# 4. 直接从本地路径安装
~/.hermes/bin/uv pip install \
  --python ~/.hermes/hermes-agent/venv/bin/python /tmp/crypto-src

为什么不直接 brew install openssl@3?因为 brew install 的 bottle 会从 ghcr.io / github release 拉,同样会被 github 屏障挡住;而且你还得在每次 cargo build 时记住设置 OPENSSL_DIR。vendored 是自包含,彻底省心。

坑 5:uv pip 每次构建都重新解包 sdist,导致 patch 被覆盖

现象:把 ~/.cache/uv/sdists-v9/.../ 里的源码 patch 完后重跑 uv pip install -e .,仍然报"No usable OpenSSL"。diff 一看 patch 完好——uv 根本没用到你 patch 的那个目录,而是重新解出了另一个独立目录。

根因:uv 对 sdist 采取"每次构建独立解包目录"策略,保证构建环境可重现。

救命方案:把 patch 好的源码复制到稳定目录,直接用 uv pip install <本地路径>(即上面坑 4 的最后一步 /tmp/crypto-src 思路)。本项目里 cryptography wheel 编译完会缓存到 ~/.cache/uv/wheels-v*/,同版本再装就不会重编了。

收尾:装 shim + PATH,一键验证

核心依赖装完后,官方安装器的 setup_path 也不必再跑,手动写 shim 到 ~/.local/bin 即可:

# ~/.local/bin/hermes
#!/usr/bin/env bash
unset PYTHONPATH PYTHONHOME
exec "$HOME/.hermes/hermes-agent/venv/bin/python" \
  "$HOME/.hermes/hermes-agent/hermes" "$@"

同样再配 2 个姊妹脚本 hermes-agent(对应 run_agent.py)和 hermes-acp(对应 hermes acp 子命令),然后在 ~/.zshrc / ~/.zprofile 里加:

export PATH="$HOME/.local/bin:$PATH"
. "$HOME/.cargo/env"  # 如果未来仍要编 Rust

新终端里跑 hermes doctor——这次我跑出了全部核心通过:

✅ Python 3.11.15 / venv 激活 / 版本一致 0.20.1
✅ SSL CA 证书 / 必需包(OpenAI SDK / Rich / HTTPX / PyYAML / Croniter)齐全
✅ hermes chat -q "say ready" 正常响应(需先 hermes setup 配置提供商与 API Key)

经验总结:当官方安装器不工作时的排查顺序

步骤	查什么	关键命令 / 工具
1	到底卡在哪一步?	把 `curl \| bash` 改成下载脚本→读→本地执行,加重定向日志 `bash install.sh > /tmp/install.log 2>&1`
2	是不是网络屏障?	`curl -m 8` 依次查 github.com / files.pythonhosted.org / static.rust-lang.org / index.crates.io
3	是缺 wheel 还是编译工具链?	`pip download --no-deps --only-binary=:all: pkg==ver`;失败就看 PyPI 的 wheel file 列表
4	Rust / C 编译依赖什么?	perl、cc、make 是不是都有?vendored 能解决 90% 的"系统库找不到"
5	patch 是否真被吃到?	`find builds-v0 -name METADATA` 查实际编译路径,别在缓存目录里自嗨