Hermes Agent 安装教程：Windows、macOS、Linux 与 VPS 一键安装命令

怎么用本页

按系统复制一行命令，装完用同一套标准验收

本页是 Hermes Agent 的安装教程：先按系统选一条路线执行命令，再按下面的四步跑通第一轮。装好以后想接 Provider、Gateway 和 VPS 长期运行，再看部署路线专题。

打开 Hermes Agent 部署路线

前置条件

✓ Git 可用（Linux 另需 curl 和 xz-utils）
✓ 准备一个模型 Provider：Nous Portal 浏览器登录，或国内、海外 Provider 的 API Key
✓ 装完重新加载 shell，hermes --version 能运行
✓ 日志目录可写
✓ Windows 原生和 WSL2 二选一，不要混用

Platform install

Windows、Linux、macOS 怎么选

新手不要先纠结所有安装方式。按系统选一条主线，安装后统一用 setup、doctor、model 和 skills 命令验收。

安装路线怎么选

Windows 原生（PowerShell）

官方支持

v0.21 起原生 Windows 10/11 正式支持，CLI、Gateway、TUI 和工具都能原生运行，不需要 WSL。安装脚本会自动装好 Python、Node.js、ripgrep、ffmpeg 和一份便携 Git Bash，不需要管理员权限。想要图形界面，可以到官网下载 Hermes Desktop 安装包，或者装完命令行后运行 hermes desktop。

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

# 安装后新开一个 PowerShell
hermes --version
hermes

✓ 原生安装的数据在 %LOCALAPPDATA%\hermes，WSL2 的在 ~/.hermes，两边不要混用。
✓ 杀毒软件把 uv.exe 当成恶意程序是已知误报（官方文档有说明），需要放行。
✓ 只有仪表盘里的内置终端窗格还需要 WSL2，其他功能都能原生用。

Windows 上用 WSL2

可选

需要完整的 Linux 环境，或者本来就习惯 Linux 工具链时再选它。先用 PowerShell 启用 WSL2，再在 Ubuntu 终端里按 Linux 方式安装。

wsl --install
wsl --set-default-version 2

# 打开 Ubuntu 终端后执行
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
source ~/.bashrc
hermes

✓ Windows 原生和 WSL2 的配置目录不同，不要混用。
✓ 路径、shell、工具调用和日志行为和 Linux 一致。

macOS

Apple Silicon

官方只支持 Apple Silicon（M 系列芯片）的 Mac，Intel Mac 不在支持范围内。可以到官网下载 Hermes Desktop 安装包（同时装好命令行和桌面版），也可以只装命令行：

git --version
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
source ~/.zshrc
hermes

✓ 默认终端是 zsh，命令找不到时先 source ~/.zshrc。
✓ 只装了命令行、想加装桌面版，运行 hermes desktop。

Linux / VPS

长期运行

适合 Linux 桌面、Ubuntu/Debian VPS 和团队部署。个人上手用普通用户，长期运行再补低权限用户、日志和进程守护。

sudo apt update
sudo apt install -y git curl xz-utils
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
source ~/.bashrc
hermes

✓ VPS 不建议长期用 root 跑工作流。
✓ 网关要开机自启，装成系统服务：sudo hermes gateway install --system。
✓ 不需要浏览器自动化的服务器，可以加 --skip-browser 跳过 Playwright 浏览器下载。

1. 先装到本地终端

不要一开始就上 VPS。先在自己的电脑跑通 CLI，问题会少很多。Python 和 Node.js 不用自己装，安装脚本会处理。

git --version
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
source ~/.bashrc
hermes --version

2. 配置模型 Provider

安装脚本最后会进入设置向导；跳过了也可以随时运行 hermes setup。国内用户选 Full setup，再选国内 Provider；Key 会写进 ~/.hermes/.env。

hermes setup
hermes model
hermes doctor

3. 只读跑通第一轮

第一轮只让 Hermes 读文件、总结资料或生成草稿。不要立刻接删除、付款、群发这类动作。

hermes
/model
/skills
请根据当前项目生成一份只读检查清单

4. 再迁到长期运行环境

CLI 稳定后再接 Gateway 和 VPS。长期运行要有低权限用户、日志、重启策略和人工确认边界。

hermes gateway setup
hermes gateway run        # 先前台跑一次，确认能收发消息
hermes gateway install    # 再装成后台服务（VPS 上加 sudo 和 --system）
hermes gateway status
hermes logs gateway

环境变量怎么放

✓ API Key 只放在服务端环境变量或 Hermes 配置目录，不写进前端页面。

✓ 开发、测试、生产使用不同 Key，方便限额和撤销。

✓ 高权限 Token 单独命名，先不给 Agent 默认使用。

✓ Hermes 以 ~/.hermes/.env 为准，它会覆盖 shell 里 export 的同名变量；改完重开会话，网关要 hermes gateway restart。

hermes config set OPENROUTER_API_KEY sk-or-...   # 写进 ~/.hermes/.env
hermes config env-path                          # 看 .env 文件在哪
hermes doctor                                   # 检查 Key 和依赖
# Nous Portal 不用 Key，浏览器登录：hermes setup --portal

成本与安全提醒

模型 API、VPS、消息平台和第三方 SaaS 会产生费用。不要把生产数据库写权限、付款权限或群发权限直接交给 Agent。

VPS 长期运行 checklist

✓ 创建低权限运行用户，不用 root 长期跑任务。
✓ 把 Hermes 工作目录、日志目录和备份目录分开。
✓ 使用进程守护，失败后自动重启，并限制重启频率。
✓ 日志至少保留 7 天，方便排查 Gateway、模型和工作流问题。
✓ 消息平台只允许指定用户或频道调用。
✓ 涉及写文件、发消息、改表格、开工单的动作先加人工确认。

安装完成怎么验收

模型已配置：`hermes model` 能看到当前模型并完成一次短对话。

记忆可用：内置记忆默认开启，在一次会话里让它记住一条偏好，新开会话能读到。

Skills 可用：`hermes skills list` 能列出内置技能。

消息入口已连接：目标消息平台能收到测试回复。

工作流已通过：至少一个真实工作流完整跑通并留下日志。

运维项已就绪：重启、日志、限额和人工确认规则都已检查。