Mac 安装 Hermes（本机复盘版）

机器时间：2026-05-27
适用对象：macOS 用户（zsh）

1. 本机当前状态（真实检查结果）

• hermes可执行文件：/Users/xutao/.local/bin/hermes
• 版本：Hermes Agent v0.10.0 (2026.4.16)
• 项目目录：/Users/xutao/.hermes/hermes-agent
• Python：3.11.14
• OpenAI SDK：2.32.0
• 状态提示：Update available: 3303 commits behind（可执行hermes update）

结论：本机已经安装成功，可直接使用；下面给的是完整安装与排雷流程，方便重装和迁移。

2. 一次性安装步骤（推荐）

步骤 1：执行官方安装脚本

curl-fsSLhttps://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh|bash

步骤 2：刷新 shell 环境

source~/.zshrc

步骤 3：验证安装

whichhermes hermes--version

期望：which hermes输出~/.local/bin/hermes（或你自定义位置）。

步骤 4：首次初始化

hermes setup

按向导配置模型提供商（如 OpenAI/OpenRouter/Nous Portal 等）和 API Key。

步骤 5：健康检查

hermes doctor

如果这里全绿，说明基本可用。

3. 本机踩坑与排雷记录（重点）

坑 1：Homebrew 缓存权限报错

现象（本机出现过）：

• brew报Operation not permitted，路径在~/Library/Caches/Homebrew/api/*.json

影响：

• 会影响brew更新/查询，但不一定阻塞hermes运行。

排雷：

# 先确认目录权限ls-ld~/Library/Caches/Homebrew ~/Library/Caches/Homebrew/api# 修正归属（把用户名改成你的）sudochown-R$(whoami):staff ~/Library/Caches/Homebrew# 再试brew update

坑 2：pip 缓存目录权限告警

现象（本机出现过）：

• WARNING: The directory '~/Library/Caches/pip' ... is not writable

影响：

• 安装速度慢、缓存不可用；通常不致命。

排雷：

sudochown-R$(whoami):staff ~/Library/Caches/pip

坑 3：pipx不存在

现象（本机出现过）：

• zsh: command not found: pipx

说明：

• Hermes 官方脚本并不依赖 pipx，因此这个报错不是 Hermes 安装失败的直接原因。

坑 4：hermes能运行但命令找不到

常见原因：

• ~/.local/bin没进PATH。

排雷：

echo'export PATH="$HOME/.local/bin:$PATH"'>>~/.zshrcsource~/.zshrcwhichhermes

坑 5：版本落后很多提交

现象（本机出现过）：

• Update available: xxxx commits behind

处理：

hermes update hermes--version

4. 注意事项（建议）

• 不要混用多个 Python 环境去手动覆盖~/.hermes/hermes-agent/venv，容易导致依赖漂移。
• 升级后建议执行一次hermes doctor做体检。
• 首次使用建议先只开必要工具权限，避免一上来给过大执行权限。
• 如果要长期用，建议备份：

hermes backup

5. 简单使用步骤（3 分钟上手）

1) 启动交互

hermes

2) 选择模型

hermes model

3) 开始提问

直接在终端输入任务，例如：

• “帮我写一个 Python 脚本，统计当前目录文件大小”
• “给我生成一个 README 模板”

4) 查看状态与日志

hermes status hermes logs

5) 常用维护命令

hermes doctor hermes update hermes backup

6. 可选：完全重装（当环境乱了时）

hermes uninstallrm-rf~/.hermes/hermes-agentcurl-fsSLhttps://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh|bashsource~/.zshrc hermes setup hermes doctor

注意：uninstall/删除前先执行hermes backup，避免丢失配置和历史。