Hermes Agent 安装指南与使用教程（中国大陆网络环境）
整理时间：2026-07-23
安装环境：macOS（Apple Silicon / aarch64）、zsh
安装版本：Hermes Agent v0.19.0 (2026.7.20)，Python 3.11.15
官方文档：https://hermesagent.org.cn/docs/getting-started/installation
一、Hermes Agent 简介
Hermes Agent 是 Nous Research 出品的开源 AI 智能体（Agent）框架，支持 Skills 扩展、记忆、定时任务、MCP 接入等能力。中文社区提供了国内镜像版安装器，对大陆网络做了适配。
二、系统要求
| 依赖 | 要求 | 本次实际 |
|---|---|---|
| Python | 3.11+（安装器自动处理） | 3.11.15（uv 管理） |
| Git | 任意现代版本 | 2.27.0 |
| Node.js | v22+（仅浏览器等可选组件需要） | v22.22.2 |
| ripgrep / ffmpeg | 非必需 | 未安装（镜像精简模式跳过） |
三、安装过程实录（含遇到的问题与解决方案）
3.1 问题一：官方链路从 GitHub 下载，卡死
中文社区文档给出的官方一键命令，其引导器（bootstrap）会从GitHub下载install.sh和 uv 运行时。安装日志显示：
[bootstrap] downloading install.sh for main from GitHub → Installing managed uv into /Users/a2/.hermes/bin ... （9 分钟后）cancellation received — killing childuv 安装阶段卡住 9 分钟，最终被取消。
3.2 问题二：社区镜像站速度过慢
改用中文社区镜像版脚本https://res1.hermesagent.org.cn/install.sh后，实测该站（Cloudflare 节点）下载速度仅约 27 KB/s。uv 二进制约 52MB，照此速度需 20 分钟以上。
3.3 问题三：curl | bash非交互模式静默失败
直接执行curl -fsSL ... | bash时完全无输出即退出。原因：脚本在非 TTY 标准输入下，read -p遇到 EOF 会触发set -e静默中止。正确做法是先把脚本下载到本地再执行。
3.4 解决方案：利用预置检测机制 + 国内高速镜像
分析镜像版install.sh源码后发现其下载源分布：
| 资源 | 默认来源 | 速度 | 对策 |
|---|---|---|---|
| git 仓库 | cnb.cool（腾讯 CNB 镜像） | ✅ 快（7-9 MB/s） | 无需处理 |
| pip 包 | 清华 PyPI 镜像 | ✅ 快 | 无需处理 |
| npm 包 | npmmirror（淘宝） | ✅ 快 | 无需处理 |
| uv 二进制 | res1.hermesagent.org.cn（Cloudflare） | ❌ 慢（27 KB/s） | 需预置 |
| Python 独立构建 | res1.hermesagent.org.cn（Cloudflare） | ❌ 慢 | 需预置 |
脚本有两个可利用的检测机制：
install_uv()函数：发现~/.hermes/bin/uv已存在且可执行时，直接跳过下载- uv 创建 venv 时：发现缓存中已有对应 Python 版本时，不会重复下载
因此把慢速依赖换成国内高速源预置即可。
3.5 完整安装步骤（可复现）
# 步骤 1：下载镜像版安装脚本到本地（不要直接 curl | bash）curl-fsSL--connect-timeout15--max-time60\https://res1.hermesagent.org.cn/install.sh-o/tmp/hermes_install.sh# 步骤 2：预置 uv（走清华 PyPI 镜像，秒级完成）python3-mvenv /tmp/uv-venv /tmp/uv-venv/bin/pipinstall-ihttps://pypi.tuna.tsinghua.edu.cn/simple uvmkdir-p~/.hermes/bincp/tmp/uv-venv/bin/uv /tmp/uv-venv/bin/uvx ~/.hermes/bin/ ~/.hermes/bin/uv--version# 验证：uv 0.11.31# 步骤 3：预置 Python 3.11 到 uv 缓存（走 npmmirror，约 3 秒）UV_PYTHON_INSTALL_MIRROR="https://registry.npmmirror.com/-/binary/python-build-standalone"\~/.hermes/bin/uv pythoninstall3.11# 步骤 4：运行安装脚本（全链路国内镜像，约 48 秒完成）bash/tmp/hermes_install.sh --skip-setup --skip-browser --non-interactive# 步骤 5：验证安装exportPATH="$HOME/.local/bin:$PATH"hermes version# 显示版本即成功hermes doctor# 环境诊断3.6 安装参数说明
| 参数 | 作用 |
|---|---|
--non-interactive | 跳过需要人工输入的阶段（脚本化执行时必需） |
--skip-setup | 跳过交互式配置向导，API Key 留到装完后用hermes setup配置 |
--skip-browser | 跳过 Chromium/浏览器自动化组件（体积大、易受外网影响，镜像版默认已跳过） |
四、安装结果
- 版本：Hermes Agent v0.19.0 (2026.7.20) · upstream e0b9ab5a
- 启动命令：
~/.local/bin/hermes（PATH 已自动写入~/.zshrc、~/.zprofile、~/.profile） - 程序代码：
~/.hermes/hermes-agent/（git 克隆自 cnb.cool 镜像） - 配置文件：
~/.hermes/config.yaml、~/.hermes/.env - 数据目录：
~/.hermes/（sessions/、logs/、cron/、memories/、skills/ 等） - 内置 Skills：78 个，已同步到
~/.hermes/skills/ - 诊断：
hermes doctor全部关键项通过
目录结构一览
~/.hermes/ # 数据与配置根目录 ├── bin/ # 托管 uv 二进制 ├── hermes-agent/ # 主程序代码（含 venv） ├── skills/ # 78 个内置技能 ├── config.yaml # 主配置 ├── .env # API 密钥 ├── SOUL.md # 人格自定义 ├── sessions/ logs/ cron/ memories/ ... ~/.local/bin/hermes # 全局启动命令五、注意事项
- PATH 生效：安装后需新开终端，或在当前终端执行
source ~/.zshrc，否则提示hermes: command not found。 - 交互命令不要脚本化执行：
hermes setup、hermes config migrate、hermes model都是交互式的，通过管道或非 TTY 方式调用会卡住或被终止。 - 镜像精简模式未安装的可选组件：浏览器自动化（Chromium）、Telegram/Discord 机器人、WhatsApp 桥接、ripgrep、ffmpeg。核心功能不受影响，后续需要时可在 hermes 中让它自行补装。
- 配置版本提示：
hermes doctor可能提示Config version outdated (v0 → v33)，属正常，运行hermes config migrate升级即可（交互式，会顺带询问 API Key）。 - 网络环境：本方案适用于中国大陆网络。全部下载走 cnb.cool + 清华 PyPI + npmmirror，零 GitHub 访问。
六、使用教程
6.1 首次使用：配置 API Key
打开新终端，运行交互式向导：
hermes setup或按需单独配置：
hermes model# 选择大语言模型提供商和具体模型hermes tools# 配置启用哪些工具hermes gateway setup# 设置消息平台接入hermes configsetOPENROUTER_API_KEY sk-or-v1-你的key# 直接写入单个配置支持的部分提供商：OpenRouter、OpenAI、Google Gemini、DeepSeek、xAI、Kimi、智谱 GLM、MiniMax 等（完整列表见hermes status）。
也可以直接编辑密钥文件：~/.hermes/.env
OPENROUTER_API_KEY=sk-or-v1-your-key-hereFIRECRAWL_API_KEY=fc-your-key# 可选：网络搜索抓取FAL_KEY=your-fal-key# 可选：图像生成6.2 日常使用
hermes# 进入交互式聊天hermes chat-q"你好"# 单次提问hermes status# 查看当前配置与 API Key 状态hermes doctor# 环境诊断（出问题先跑这个）hermes config# 查看/编辑配置hermes config edit# 在编辑器中打开配置hermes update# 更新到最新版本hermes gatewayinstall# 安装网关服务（消息平台 + 定时任务）hermes auth# 第三方账号授权登录6.3 人格与技能自定义
- 编辑
~/.hermes/SOUL.md可自定义 Agent 人格 - 技能目录：
~/.hermes/skills/，可添加自定义 SKILL.md
6.4 故障排除
| 问题 | 解决方案 |
|---|---|
hermes: command not found | source ~/.zshrc或新开终端；确认~/.local/bin在 PATH 中 |
API key not set | 运行hermes model配置，或hermes config set OPENROUTER_API_KEY 你的key |
| 更新后配置丢失 | 先hermes config check，再hermes config migrate |
| 其他异常 | 运行hermes doctor，它会明确指出缺什么、怎么修 |
七、卸载方法（完整清理）
Hermes 安装涉及以下位置，卸载时需逐一清理：
# 1. 主目录（代码、配置、数据、缓存、内置 node，约数百 MB）~/.hermes/# 2. 全局命令与符号链接（~/.local/bin/ 下）~/.local/bin/hermes ~/.local/bin/node ~/.local/bin/npm ~/.local/bin/npx# 指向 hermes 内置 node 的软链~/.local/bin/python3.11# 指向 uv 管理的 Python 软链# 3. uv 运行时缓存（为安装预置的 Python 3.11）~/.local/share/uv/ ~/.cache/uv/# 4. Shell 配置中的 PATH 行（特征：带 "# Hermes Agent" 注释的两行）# ~/.zshrc、~/.zprofile、~/.profile 中：# # Hermes Agent — ensure ~/.local/bin is on PATH# export PATH="$HOME/.local/bin:$PATH"# 5. 临时文件/tmp/hermes_install.sh /tmp/uv-venv/建议用「移到废纸篓」代替rm -rf，删除前可先备份~/.hermes。清理 shell 配置后执行source ~/.zshrc使改动生效。
附：加速安装原理速查
慢速瓶颈：res1.hermesagent.org.cn（Cloudflare，~27KB/s） ├── uv 二进制 ──→ 改用清华 PyPI：pip install uv（绕过） └── Python 3.11 ──→ 改用 npmmirror：UV_PYTHON_INSTALL_MIRROR= https://registry.npmmirror.com/-/binary/python-build-standalone 其余链路（cnb.cool / 清华 PyPI / npmmirror）镜像版脚本默认已是国内源，无需处理。
