Hermes Agent 安装教程（2026 完整版）

系统要求

Hermes Agent v2026.9.14 对环境的要求是“能跑 Python 3.10+ 和 Node.js 18+”就行。绝大多数 2020 年后的开发机都满足。

• 操作系统：macOS 12+（Intel / Apple Silicon）/ Ubuntu 20.04+ / Debian 11+ / Fedora 36+ / Arch / WSL2 Ubuntu
• Python：3.10 或更高版本（脚本检测到缺失会自动装 pyenv 并补齐）
• Node.js：18 或更高版本（同样自动安装）
• Git：2.30+（用来克隆 Skills registry）
• 磁盘空间：1.5 GB（包含 Skills 缓存）
• 网络：能访问 GitHub raw 与所选 LLM Provider 的 API

不满足任何一项，hermes doctor 会在安装结束时点名告诉你具体哪一项 + 怎么修。

一行命令安装（Mac + Linux）

把下面这条命令贴进终端回车就行。脚本会自动处理 Python / Node.js / 依赖 / Hermes CLI / PATH 配置。

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

1. 过程预览

   脚本会依次：检查 Python / Node 版本 → 安装到 ~/.hermes → 把 hermes 命令加进 PATH → 拉取 nous/core 默认 Skills registry → 输出 hermes 命令路径。

2. 什么时候完成

   看到 ✅ Hermes Agent installed at ~/.hermes 表示主流程已结束，整体耗时 1-3 分钟（取决于网络）。

3. 把 PATH 立即生效

   新开一个终端窗口（macOS Terminal / iTerm / Linux Terminal）就行，或者在当前终端跑 source ~/.zshrc（Mac 默认）/ source ~/.bashrc（多数 Linux）。

装完直接跑 hermes setup 进入交互式配置，然后 hermes 启动 Agent。下一节会展开。

Windows 用户必读

Hermes Agent 在 Windows 上不原生跑——必须经 WSL2（Windows Subsystem for Linux 2）。这不是 Hermes 的限制，而是 Python 生态对 Windows 路径处理 + 终端 ANSI 渲染长期的兼容性问题。

• Win10 21H2 / Win11 都内建 WSL2，开启耗时约 5 分钟
• 推荐发行版：Ubuntu 22.04 LTS（在 Microsoft Store 一键装）
• WSL Ubuntu 装好之后，在 Ubuntu 终端里跑上一节那条 install.sh
• VS Code 通过 Remote-WSL 扩展可以无缝编辑 WSL 内的项目

完整步骤（含 8 个 WSL 常见报错）见 /install/windows 专门指南。

安装验证：hermes doctor

装完跑这一条命令一键自检 12 项：Python / Node 版本、PATH、Skills registry 连通性、LLM Provider 连接、磁盘空间、文件权限。

hermes doctor

• ✅ 表示通过，不需要管
• ⚠️ 表示警告（不影响正常使用，但可能影响后续高级用法）
• ❌ 表示阻塞，必须解决
• 加 --verbose 看详细诊断；加 --fix 让脚本自动修可修的问题

完整 12 项含义和报错对照表，见 /cli/doctor 专题。

安装后必做 5 步

装完不是结束，下面 5 步是从“能启动”到“真正能干活”之间的距离。

1. 1. 配置 LLM Provider（必做）

   跑 hermes setup 进入交互式向导，国内推荐先选智谱 GLM-4 或 Kimi（无需代理、按量计费便宜）。海外用户用 Claude / OpenAI / OpenRouter 都行。详见 /providers/glm 与 /providers/kimi。

2. 2. 跑你的第一个 Agent 任务

   终端里直接 hermes，输入“给我列一下当前目录下所有 Python 文件的行数”，看 Agent 怎么调用 Skills 完成任务。这一步主要是确认 LLM 链路通了。

3. 3. 安装常用 Skills

   hermes skills install code-review 装一个代码审查 Skill；hermes skills list 看已安装清单。Hermes 自带 Skills Hub 共 bundled and community Skills，按需安装即可。

4. 4. 配置 Memory（可选但强烈建议）

   默认 Hermes 是无状态的。开启 Memory 后跨会话记住你的偏好和项目结构。hermes config memory enable + hermes memory init。

5. 5. 接入消息平台（可选）

   钉钉 / 飞书 / Slack 都可以通过 Hermes Gateway 接入，做团队 AI 助手或工单机器人。详见 /integrations/dingtalk 和 /integrations/feishu。

常见安装报错

90% 的安装报错都是这 6 类。挨个对照排查即可。

• curl: (60) SSL certificate problem

  原因 / Cause: 系统证书过期或被代理软件拦截（常见于公司网络）。

  修复 / Fix: 先 sudo apt-get install ca-certificates 或 brew install openssl 更新证书。仍报错就让网络管理员加 raw.githubusercontent.com 到白名单。

• Python: command not found

  原因 / Cause: macOS 12 默认不再带 python（只有 python3）。安装脚本会自动装 pyenv 但需要重启终端。

  修复 / Fix: 关掉当前终端窗口，新开一个再跑命令。或在当前终端跑 source ~/.zshrc。

• EACCES: permission denied 写入 /usr/local

  原因 / Cause: Linux 上脚本试图把 hermes 软链到 /usr/local/bin 但当前用户没权限。

  修复 / Fix: 不要用 sudo 跑安装脚本——脚本默认装到 ~/.hermes 不需要 root。如果之前不小心 sudo 过，先 sudo rm -rf ~/.hermes && rm -rf /usr/local/bin/hermes，再用普通用户重跑。

• WSL2 里跑安装脚本卡在 Installing Python deps

  原因 / Cause: WSL2 默认 DNS 用 Windows 主机解析，国内网络下 pypi.org 偶尔抽风。

  修复 / Fix: 在 WSL Ubuntu 里 echo "[network]\ngenerateResolvConf = false" | sudo tee /etc/wsl.conf 然后 wsl --shutdown 重启 WSL，再手动设置 /etc/resolv.conf 为 8.8.8.8。

• hermes: command not found（装完之后）

  原因 / Cause: PATH 没生效。脚本写到 ~/.zshrc 或 ~/.bashrc 但当前终端没重新加载。

  修复 / Fix: source ~/.zshrc（Mac 默认）/ source ~/.bashrc（多数 Linux）。或者重开终端。

• hermes doctor 报告 Skills registry unreachable

  原因 / Cause: GitHub raw 域名被拦或 DNS 污染。

  修复 / Fix: 中国大陆用户：让 Hermes 走代理。export HTTPS_PROXY=http://127.0.0.1:7890（你本地 Clash / V2Ray 端口）后再 hermes skills sync。或在 hermes config 里设置 skills.mirror 为社区镜像。

卸载

Hermes 把所有东西都装在 ~/.hermes，卸载干净一行命令搞定。

rm -rf ~/.hermes && unlink $(which hermes) 2>/dev/null

• ~/.zshrc 或 ~/.bashrc 里安装时追加的 export PATH 行可以手动删掉
• LLM Provider 的 API Key 存在 ~/.hermes/config.toml，rm 之后即不可恢复，重要 Key 先备份
• 已安装的 Skills 也都在 ~/.hermes/skills，会一起删掉

更新到最新版

日常升级一行命令；细节（版本切换、回滚、Beta 通道）见 /cli/update 专题。

hermes update

• 默认升级到当前 Stable 通道的最新版
• hermes update --version v2026.9.14 锁定到具体版本
• hermes update --rollback 回滚到上一个本机用过的版本
• hermes update --channel beta 切到 Beta 通道试新功能

升级前 Hermes 会自动备份 ~/.hermes/config.toml 到 ~/.hermes/backups/，不会丢配置。