PKM SYSTEM
Hermes Agent 保姆级安装教程（Windows / macOS / Linux）
如果你在找一个能跑在本地的 AI Agent——能连 Telegram、Discord、Slack，能调浏览器，能挂 MCP 服务，还能自己设定时任务——那 Hermes 是目前开源选项里完成度最高的一个。
但它的安装对新手不够友好。尤其 Windows 用户，坑多。
这篇教程把三个平台的安装步骤拆开讲，每一步都标注了容易踩的坑，看完照着敲命令就行。
安装前，先搞清三件事
第一，Hermes 不是一个 Docker 镜像扔上去就跑的东西。 它是一套本地运行的 Agent 框架，依赖 Python 3.11+、Node.js 22、ripgrep、ffmpeg 这一整套工具链。好消息是官方安装脚本会帮你全部搞定，不用你手动装。
第二，不同平台的体验差别很大。 macOS 和 Linux 最稳，Windows 原生支持还在早期 Beta——官方自己都建议 Windows 用户优先走 WSL2。
第三，安装方式决定了后续的升级路径。 官方推荐用 Git 安装器（一条 curl 命令），而不是 pip install。原因很简单：pip 安装的版本更新慢，Git 安装器跟踪 main 分支，能第一时间拿到新功能。
Linux / macOS 安装（最稳路线）
这两条路线体验基本一致，官方安装脚本一条命令搞定所有依赖。
STEP
第一步：确认 Git 已安装
git --version没装的话：
• macOS：xcode-select --install（会弹出系统安装窗口）
• Ubuntu/Debian：sudo apt install git -y
• Fedora：sudo dnf install git -y
• Arch：sudo pacman -S git
STEP
第二步：运行安装脚本
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash这条命令会自动干这些事：
• 装 uv（Python 包管理器）
• 用 uv 装 Python 3.11
• 装 Node.js 22
• 装 ripgrep 和 ffmpeg
• 把 Hermes 仓库克隆到 ~/.hermes/hermes-agent/
• 创建 Python 虚拟环境
• 把 hermes 命令链接到 ~/.local/bin/hermes
整个过程大概 3-5 分钟，取决于网络。中间会看到大量输出，正常，不用管。
STEP
第三步：刷新 shell 配置
source ~/.bashrc # 如果你用 bash
source ~/.zshrc # 如果你用 zsh（macOS 默认）或者直接关掉终端重新打开。
STEP
第四步：启动
hermes第一次运行会引导你配 LLM 提供商和模型。如果你已经有 API Key，也可以直接：
hermes model # 选模型
hermes config set OPENROUTER_API_KEY sk-or-xxx # 直接设 key然后 hermes chat 就能开始对话了。
踩坑点（Linux / macOS）
1. 装完后 hermes: command not found
安装脚本把 hermes 放在了 ~/.local/bin/，但这个路径不一定在你的 PATH 里。手动加一下：
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc如果还不行，echo $PATH 看一下输出里有没有 /home/你的用户名/.local/bin。
2. macOS 上遇到 xcrun: error
说明 Xcode Command Line Tools 没装或版本太老。跑一下 xcode-select --install，装完再执行安装脚本。
3. 安装脚本中途报网络错误
Hermes 的依赖下载走 GitHub 和 PyPI。uv 有缓存，重试不会从头下。
“
注意：网络问题自行解决。
4. 如果不需要浏览器自动化
加上 --skip-browser 跳过 Playwright 和 Chromium 依赖，能省不少时间和磁盘：
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash -s -- --skip-browserWindows 安装（Beta，但能用）
Windows 原生支持还在早期阶段。官方原话：“early beta”。最稳的方案是用 WSL2，在里面走 Linux 安装流程。
但如果你不想装 WSL，原生 PowerShell 也能跑。
STEP
方案一：WSL2（推荐）
先在 PowerShell 里装 WSL：
wsl --install重启电脑，进 WSL 的 Ubuntu 终端，然后走上面 Linux 的安装流程。WSL2 里的体验和原生 Linux 几乎一样——包括那个只有 POSIX PTY 才能跑的仪表盘 /chat 终端面板。
WSL2 的一个坑：systemd 不完整。 如果你要用 hermes gateway 做系统服务，WSL2 的 systemd 支持可能有问题（GitHub issue #28880）。建议 gateway 前台跑，别挂 systemd 服务。
STEP
方案二：原生 PowerShell
在 PowerShell 里跑：
iex (irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1)脚本会自动处理：
• 装 uv、Python 3.11、Node.js 22
• 装 ripgrep、ffmpeg
• 如果系统没 Git，自动下载 PortableGit（约 50MB），解压到 %LOCALAPPDATA%hermesgit
• 把仓库克隆到 %LOCALAPPDATA%hermeshermes-agent
• 把 hermes 加进用户 PATH
装完必须重启终端，不然 PATH 没刷新，会提示找不到 hermes。
STEP
Windows 原生能跑什么？
• hermes chat、hermes setup、hermes gateway —— 原生
• Gateway（Telegram、Discord、Slack 连接）—— 原生，以后台 PowerShell 进程运行
• Cron 定时任务 —— 原生
• 浏览器工具（通过 Node.js 调 Chromium）—— 原生
• MCP 服务器（stdio 和 HTTP）—— 原生
• 仪表盘 /chat 终端面板 —— 不支持（依赖 POSIX PTY，Windows 没这玩意）
踩坑点（Windows）
1. PowerShell 执行策略拦截脚本
如果报 running scripts is disabled，先改执行策略：
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser2. 装完后终端里 hermes 不识别
重启终端，别只重开一个 tab，彻底关掉再打开。Windows 的 PATH 刷新机制有时候就是需要完全重启终端进程。
3. 编码乱码
如果终端里 Hermes 输出的中文或特殊字符乱码，设一个环境变量：
$env:HERMES_DISABLE_WINDOWS_UTF8 = "1"或者永久加到系统环境变量里。
4. 32 位 Windows 的限制
如果你还在用 32 位 Windows，安装脚本会回退到 MinGit（而不是 PortableGit），一些依赖 bash 的功能会不可用。简单说：能用 64 位就别用 32 位。
5. 杀毒软件误报
PortableGit 和 uv 下载的二进制文件偶尔会被 Windows Defender 拦截。不是病毒，加白名单就行。路径一般在 %LOCALAPPDATA%hermes 下面。
装完之后
不管你用哪个平台，装完第一件事是跑这个：
hermes doctor它会告诉你缺了什么、哪里配置不对、怎么修。比如：
• 某个 API key 没设
• 某个依赖版本太旧
• 配置文件需要迁移
常用配置命令：
hermes model # 选 LLM 提供商和模型
hermes tools # 开关各种工具
hermes gateway setup # 配 Telegram / Discord / Slack
hermes config set # 改单个配置项
hermes setup # 完整配置向导更新 Hermes：
hermes update它会自动检测你的安装方式（pip / Git / Homebrew / Nix），告诉你对应的更新命令。
常见问题速查
hermes: command not found | ~/.local/bin | source ~/.bashrc |
API key not set | hermes modelhermes config set | |
hermes config checkhermes config migrate | ||
/restart 失败 | /restart | |
HERMES_DISABLE_WINDOWS_UTF8=1 | ||
ModuleNotFoundError: No module named 'dotenv' | ~/.local/bin 在最前面 |
最后
Hermes 的安装脚本已经帮你处理了绝大多数脏活累活。真正容易出问题的不是安装本身，而是装完之后的配置和平台兼容性。
三个建议：
• macOS / Linux 用户：直接 curl 一把梭，基本不会翻车。遇到问题先跑 hermes doctor。
• Windows 用户：优先 WSL2。原生 PowerShell 能用，但别期望和 Linux 一样顺滑——尤其那个仪表盘终端面板，Windows 上跑不了。
• 不想折腾浏览器自动化的：加 --skip-browser，省时间省磁盘，后面需要了再单独装。
Hermes更新很快，GitHub 上每天都有新 commit。如果安装遇到文档里没写的问题，直接去开源项目的Issues页面搜——大概率已经有人踩过同样的坑了。
