乐于分享
好东西不私藏

Mac 安装 Hermes 完整教程(附command not found: hermes 解决方案)

Mac 安装 Hermes 完整教程(附command not found: hermes 解决方案)
完整教程
Mac 安装 Hermes
从零开始,一步一步
附 command not found: hermes 解决方案
Apple SiliconmacOSAI AgentClaude Code
目录
01Xcode Tools
02Homebrew
03Node.js
04uv 安装
05Python
06工作目录
07虚拟环境
08安装验证
09报错解析
10懒人方案
1
Xcode Command Line Tools

先检查是否已安装:

xcode-select -p
输出 /Library/Developer/CommandLineTools 说明已安装,跳过此步。

未安装则执行:

xcode-select --install

2
安装 Homebrew
/bin/bash -c "$(curl -fsSL \
  https://raw.githubusercontent.com/Homebrew/\
install/HEAD/install.sh)"

安装后验证:

brew -v
有版本号即成功。

3
安装 Node.js

Hermes 需要 Node 环境:

brew install node
node -v
npm -v
推荐版本Node 22+  ·  npm 10+

4
安装 uv

AI Agent 生态常用的 Python 环境管理工具,Hermes 依赖它:

brew install uv
uv --version

5
安装 Python
brew install python@3.12
python3 --version
✓ Python 3.11✓ Python 3.12✗ 3.13 beta

6
创建工作目录

建议单独放一个目录,方便后续管理:

mkdir -p ~/AI/hermes
cd ~/AI/hermes
推荐目录结构 ~/AI/ 下可以放 hermes、projects、models、scripts、sandbox,后续接入 Claude Code / MCP / 本地模型都会方便很多。

7
创建并激活虚拟环境

创建虚拟环境:

uv venv

激活(关键步骤):

source .venv/bin/activate
激活成功后,终端前面会出现 (.venv),例如:

(.venv) MacBook-Pro hermes %

8
安装并验证 Hermes
安装
uv pip install hermes-agent
验证
which hermes
hermes --version
/Users/你的用户名/AI/hermes/.venv/bin/hermes
有版本号,安装成功!执行 hermes 即可启动。

9
command not found 解析

这是最多人遇到的问题,原因很简单:

报错原因 Hermes 安装在 .venv/bin/ 里,不是系统全局命令。你没有激活虚拟环境,shell 找不到它。

每次打开终端的正确流程:

进入目录
cd ~/AI/hermes
激活环境
source .venv/bin/activate
确认有 (.venv) 前缀
启动
hermes

10
懒人方案:配置 alias

每次 cd → source → hermes 太繁琐?一行 alias 搞定:

nano ~/.zshrc

在文件末尾加入:

~/.zshrc
alias hm='cd ~/AI/hermes && \ source .venv/bin/activate && hermes'
source ~/.zshrc
以后只需输入 hm 即可一键启动 Hermes。

如果 source ~/.zshrc 报错:

source: no such file or directory 说明 .zshrc 里有错误的 source 路径。

将可能不存在的 source 改为:

[ -f xxx ] && source xxx
文件不存在时不会报错。

一句话总结
Hermes 装在 Python 虚拟环境里,不是系统全局命令
报 command not found,大概率是没有 activate venv
看终端有没有 (.venv) 前缀,有就对了

相关学习资料