Hermes Agent 安装总结报告
安装时间:2026-08-16
最终版本:Hermes Agent v0.20.1 (2026.8.13)
设备:MacBook Pro 16,2 · Intel Core i7 2.3GHz · macOS 13.7.8 (Ventura)
安装方式:手动补全官方安装器(因 GitHub 网络屏蔽与 Intel 平台 wheel 缺失)
一、安装结果验证
$ hermes --version
Hermes Agent v0.20.1 (2026.8.13)
Install directory: /Users/zxyvent/.hermes/hermes-agent
Python: 3.11.15
OpenAI SDK: 2.24.0hermes doctor 健康检查:全部核心项目通过。
- ✅ Python 3.11.15 / Virtual env 激活 / 版本文件一致 0.20.1
- ✅ SSL CA 证书有效 / 无安全告警 / 无已退役模型
- ✅ 必需包:OpenAI SDK / Rich / python-dotenv / PyYAML / HTTPX / Croniter
- ⚠ 可选包:python-telegram-bot / discord.py 未安装(按需网关功能)
- ⚠ 未配置:~/.hermes/.env / config.yaml(下一步
hermes setup生成) - ⚠ 未登录:Nous Portal / OpenAI Codex / MiniMax OAuth / xAI OAuth(选模型时决定)
二、安装中遇到的问题与修复路径
| # | 故障现象 | 根因 | 处理方式 |
|---|---|---|---|
| 1 | 官方 install.sh 在 git fetch origin main 时卡死 |
本环境 github.com:443 连接超时(网络屏蔽) |
跳过 git 更新,直接用已有 ~/.hermes/hermes-agent 源码(仓库已在 8/15 克隆完成) |
| 2 | uv sync --extra all --locked 失败后,不带 --locked 也卡在源码编译 |
400 包全量含大量 native 编译,且 cryptography 50.0.0 无 macOS x86_64 wheel |
改用 uv pip install -e . 最小化核心安装 |
| 3 | 最小安装也卡编译;maturin get_requires 报 ["puccinialin"] 子进程 CPU 0% |
cryptography==50.0.0 的 Rust 依赖 openssl-sys 0.9.117 找不到系统 OpenSSL |
先安装 Rust toolchain(rustup stable 1.97.1,最小 profile) |
| 4 | 装了 Rust 后仍报 openssl-sys build 失败 |
cryptography workspace Cargo.toml 里 openssl = "0.10.80" 未启用 vendored;本机无 OpenSSL 开发文件 |
patch Cargo.toml + 更新 Cargo.lock,启用 openssl / openssl-sys 的 vendored feature(内置 OpenSSL 源码本地编译) |
| 5 | patch 后重新 uv pip install 仍报 No usable OpenSSL |
uv 每次构建从 sdist 重新提取干净目录,覆盖了我 patch 的临时目录 | 把 patch 好的源码复制到稳定位置 /tmp/crypto-src,用 uv pip install /tmp/crypto-src 直接从本地路径构建 |
三、安装位置与产物清单
~/.hermes/
├── hermes-agent/ # 源码 + Python venv (核心)
│ ├── venv/ # Python 3.11.15 虚拟环境,127 个包
│ ├── hermes # CLI 入口脚本
│ └── run_agent.py # agent 运行入口
├── node/ # Hermes 管理的 Node.js v22.22.3(浏览器 / 网关工具)
└── bin/ # Hermes 管理的 uv / uvx
~/.cargo/bin/ # Rust stable 1.97.1 (rustc/cargo)
~/.rustup/ # Rust toolchain 安装目录(Intel Mac 编译 cryptography 必需)
~/.local/bin/
├── hermes # 用户可调用的 hermes shim
├── hermes-agent # hermes run_agent.py 封装
├── hermes-acp # hermes acp 子命令封装
├── node → ~/.hermes/node/bin/node
├── npm → ~/.hermes/node/bin/npm
├── npx → ~/.hermes/node/bin/npx
└── python3.11 → ~/.local/share/uv/python/cpython-3.11-macos-x86_64-none/bin/python3.11Shell 配置已写入
~/.zshrc(新建):导出$HOME/.local/bin到 PATH + source$HOME/.cargo/env~/.zprofile(追加):同样内容,确保登录 shell 也可用
新终端里 hermes / cargo / rustc / node / npm 均可直接调用。
四、下一步:配置 LLM 模型与使用
1) 配置提供商 + API Key(必做,否则无法聊天)
hermes setup # 全流程向导(推荐)
hermes model # 仅选模型/提供商
hermes setup --portal # 若有 Nous Portal 订阅(一站集成 300+ 模型+工具网关)2) 冒烟测试(配完后)
source ~/.zshrc # 若当前终端还没加载新配置
hermes doctor # 再次确认环境健康
hermes chat -q "say ready" # 简单对话测试3) 其他常用命令
hermes chat # 进入交互聊天(默认命令)
hermes model # 切换默认模型
hermes config get / set KEY=VAL # 查看/修改单项配置
hermes gateway setup # 接 Telegram / Discord / Slack / WhatsApp
hermes cron # 定时任务
hermes skills # Skills 管理(核心扩展机制)
hermes mcp # MCP 连接管理(接 GitHub/数据库/内网工具)
hermes dashboard # 打开网页仪表板
hermes desktop # 安装/启动桌面版五、可选优化建议
A. 补齐 ffmpeg(TTS 语音需要)
hermes doctor 提示 ffmpeg 缺失。你的 ~/.zprofile 里已有 Homebrew 配置,新开终端后:
brew install ffmpeg注:Homebrew 的 3 个环境变量已写在
~/.zprofile(阿里云镜像),它会影响 bottle 下载镜像与 pypi 索引。
B. 选装消息网关依赖
cd ~/.hermes/hermes-agent && \
source ~/.cargo/env && \
~/.hermes/bin/uv pip install --python ./venv/bin/python \
python-telegram-bot discord.pyC. 装桌面版
hermes desktop # 会拉取 Hermes Desktop 安装器D. Rust 工具链说明(如需卸载)
为了在 Intel Mac 上编译 cryptography 50.0.0 的 Rust 代码,安装了 Rust stable 1.97.1 用户级。占空间约 350MB(toolchain)+ cargo 缓存。若未来升级 hermes 时 cryptography 出了 x86_64 wheel,不再需要 Rust 可卸载:
rustup self uninstall然后在 ~/.zshrc / ~/.zprofile 里删掉 . "$HOME/.cargo/env" 两行。
六、重要注意事项
- github.com 在本环境超时 — 官方安装器的
git fetch、Homebrew 的 GitHub release 下载、hermes update未来拉取更新都可能受影响。如果需要更新 hermes 源码,考虑走 gitee 镜像或配置 git 代理。 - cryptography 50.0.0 + Intel Mac 无 wheel — 本机是通过 patch 加 vendored OpenSSL + Rust 编译搞定的。未来如果升级 hermes 时 cryptography 版本更新,可能需要重新 patch(或看新版本是否恢复了 x86_64 wheel 发布)。编译好的 wheel 已缓存于
~/.cache/uv/wheels-v*/,同版本重装无需再编译。 - 官方安装幂等性 — 如果未来网络畅通,直接重新运行官方安装器是安全的:它会跳过已存在的 uv / python / node / git 组件,并把 PATH 配置再写一遍(不会破坏当前安装)。
hermes doctor关于 SQLite WAL-reset bug 警告 — Python 3.11.15 自带的 SQLite 3.50.4 含一个已知 WAL 重置 bug。修复方案是hermes update或升级 Python 到带 SQLite 3.50.7+ 的版本。影响较低,仅极端情况下 session 数据损坏。
报告生成时间:2026-08-16 · 由 Trae 安装执行助手生成
文章导出
生成预览中...
