Hermes Agent 安装指南与使用教程 for Mac

Hermes Agent 安装指南与使用教程中国大陆网络环境整理时间2026-07-23安装环境macOSApple 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 接入等能力。中文社区提供了国内镜像版安装器对大陆网络做了适配。二、系统要求依赖要求本次实际Python3.11安装器自动处理3.11.15uv 管理Git任意现代版本2.27.0Node.jsv22仅浏览器等可选组件需要v22.22.2ripgrep / 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.cnCloudflare❌ 慢27 KB/s需预置Python 独立构建res1.hermesagent.org.cnCloudflare❌ 慢需预置脚本有两个可利用的检测机制install_uv()函数发现~/.hermes/bin/uv已存在且可执行时直接跳过下载uv 创建 venv 时发现缓存中已有对应 Python 版本时不会重复下载因此把慢速依赖换成国内高速源预置即可。3.5 完整安装步骤可复现# 步骤 1下载镜像版安装脚本到本地不要直接 curl | bashcurl-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_MIRRORhttps://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:$PATHhermes 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/hermesPATH 已自动写入~/.zshrc、~/.zprofile、~/.profile程序代码~/.hermes/hermes-agent/git 克隆自 cnb.cool 镜像配置文件~/.hermes/config.yaml、~/.hermes/.env数据目录~/.hermes/sessions/、logs/、cron/、memories/、skills/ 等内置 Skills78 个已同步到~/.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/.envOPENROUTER_API_KEYsk-or-v1-your-key-hereFIRECRAWL_API_KEYfc-your-key# 可选网络搜索抓取FAL_KEYyour-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.md6.4 故障排除问题解决方案hermes: command not foundsource ~/.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.cnCloudflare~27KB/s ├── uv 二进制 ──→ 改用清华 PyPIpip install uv绕过 └── Python 3.11 ──→ 改用 npmmirrorUV_PYTHON_INSTALL_MIRROR https://registry.npmmirror.com/-/binary/python-build-standalone 其余链路cnb.cool / 清华 PyPI / npmmirror镜像版脚本默认已是国内源无需处理。