桌面电脑#

• 能正常访问 Hermes 官方站和所选模型提供商
• 至少准备一种模型登录方式或 API Key
• macOS CLI 安装需要 Git；没有时运行 xcode-select --install
• Windows 原生安装建议使用 Windows 10/11 和新版 PowerShell

官方安装器会处理 Python、uv、Node.js、ripgrep 和 ffmpeg 等依赖，不需要提前手动拼环境。

NAS#

• x86_64 或 ARM64 NAS
• Docker Engine 与 Docker Compose v2
• 可以通过 SSH 执行命令，或有等价的 Compose 项目管理界面
• 一个长期保存的目录，例如 /volume1/docker/hermes
• 至少约 1 GB 可用内存，推荐 2–4 GB；需要浏览器工具时至少准备 2 GB
• Telegram、Discord 等消息平台是可选入口；只使用 Dashboard 或 Desktop 远程连接也可以

WARNING

Hermes 可以读写文件并执行命令。第一次使用不要直接给它挂载整个 NAS 根目录，也不要把 Docker Socket 挂进容器。先只持久化 /opt/data，等确实需要访问某个工作目录时，再按最小权限单独添加只读或读写挂载。

方式一：Hermes Desktop（推荐）#

1. 打开 Hermes Agent 官网。
2. 下载 macOS 安装器并完成安装。
3. 首次启动后，根据向导选择模型提供商。
4. 如果只想先看界面，也可以选择稍后配置 Provider。

Desktop 和 CLI 共用同一套配置、会话、Skills 与记忆。装好桌面版后，终端里同样可以运行：

1
hermes desktop
2
hermes doctor

hermes doctor 没有报告阻断性错误，就说明核心环境已经可用。

方式二：只安装 CLI#

先确认当前是 Apple Silicon：

1
uname -m

官方 Tier 1 目标应显示 arm64。然后执行官方安装器：

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

安装完成后重新载入 Shell：

1
source ~/.zshrc
2
hermes doctor

如果提示 hermes: command not found，先关闭并重新打开终端；仍不生效时检查 ~/.local/bin 是否已经加入 PATH。

方式一：Hermes Desktop（推荐）#

从 Hermes Agent 官网 下载 Windows 安装器，按向导完成安装。它会同时准备桌面应用和 Hermes 运行时，适合大多数 Windows 10/11 用户。

首次启动建议先完成一次普通对话，不要一上来就配置网关、MCP、Cron 和很多 Skills。基础模型能稳定回复后，再逐层增加功能，排错会简单很多。

方式二：PowerShell 原生安装#

打开 PowerShell，执行官方命令：

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

安装完成后新开一个 PowerShell 窗口，验证：

1
hermes doctor
2
hermes --tui

Windows Terminal 会截获部分按键。原生 Windows 下需要多行输入时，优先使用 Ctrl+Enter，不要依赖 Alt+Enter。

方式三：WSL2#

如果日常开发已经在 Ubuntu / WSL2 中进行，可以先在管理员 PowerShell 安装 WSL2：

1
wsl --install -d Ubuntu

重启并进入 Ubuntu 后，按 Linux 路径安装：

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

不要把 Windows 原生安装和 WSL2 安装的配置目录混为一谈：它们是两个独立环境。选一个作为主要运行环境，能减少路径和凭据重复配置。

如果准备让 Gateway 在关闭 WSL 终端后继续运行，先在 WSL2 中启用 systemd：

1
sudo tee /etc/wsl.conf >/dev/null <<'EOF'
2
[boot]
3
systemd=true
4
EOF

随后在 Windows PowerShell 执行 wsl --shutdown，重新进入 Ubuntu，再运行 hermes gateway setup 安装 systemd 用户服务。还要注意：没有进程使用时，WSL2 虚拟机本身可能停止；需要全天候在线时，应按官方 WSL2 指南通过 Windows 任务计划程序在登录时启动并保持 WSL 实例，或者改用 NAS / Linux 主机常驻。

1. 创建目录#

SSH 登录 NAS：

1
mkdir -p ~/docker/hermes/data
2
cd ~/docker/hermes

群晖、QNAP、极空间等系统可以把目录换成自己的存储路径，例如 /volume1/docker/hermes。后续所有命令都在这个目录执行。

记录当前用户 UID 和 GID：

1
id -u
2
id -g

2. 生成 Compose 环境文件#

下面会自动生成随机 Dashboard 密码和会话签名密钥：

1
umask 077
2
printf 'HERMES_UID=%s\n' "$(id -u)" > .env
3
printf 'HERMES_GID=%s\n' "$(id -g)" >> .env
4
printf 'DASHBOARD_USER=hermes\n' >> .env
5
printf 'DASHBOARD_PASSWORD=%s\n' "$(openssl rand -hex 24)" >> .env
6
printf 'DASHBOARD_SECRET=%s\n' "$(openssl rand -hex 32)" >> .env
7
chmod 600 .env

把 .env 的密码保存到密码管理器。DASHBOARD_SECRET 必须长期保持不变，否则容器重启后已有登录会话会失效。

3. 创建 compose.yml#

1
services:
2
  hermes:
3
    image: nousresearch/hermes-agent:latest
4
    container_name: hermes
5
    restart: unless-stopped
6
    shm_size: "1gb"
7
    volumes:
8
      - ./data:/opt/data
9
    environment:
10
      HERMES_UID: ${HERMES_UID}
11
      HERMES_GID: ${HERMES_GID}
12
      HERMES_DASHBOARD: "1"
13
      HERMES_DASHBOARD_HOST: "0.0.0.0"
14
      HERMES_DASHBOARD_PORT: "9119"
15
      HERMES_DASHBOARD_BASIC_AUTH_USERNAME: ${DASHBOARD_USER}
16
      HERMES_DASHBOARD_BASIC_AUTH_PASSWORD: ${DASHBOARD_PASSWORD}
17
      HERMES_DASHBOARD_BASIC_AUTH_SECRET: ${DASHBOARD_SECRET}
18
    ports:
19
      - "9119:9119"
20
    command: ["gateway", "run"]

这个部署只持久化 ./data，容器内对应 /opt/data。配置、秘密、会话、Skills、记忆、Cron 和日志都保存在这里；镜像可以随时替换。

WARNING

不要为了“让 Hermes 管理容器”而挂载 /var/run/docker.sock。Docker Socket 等同于宿主机 root 权限。确有容器管理需求时，优先使用受限 SSH 账户、最小化 sudo 规则或专门的远程管理接口。

4. 首次初始化#

先验证 Compose：

1
docker compose config --quiet
2
docker compose pull

运行一次交互式 Setup：

1
docker compose run --rm --no-deps hermes setup

在向导里先完成模型配置，并按需要增加远程入口：

1. 必须配置一个能正常对话的模型 Provider
2. 可选配置 Telegram、Discord 等消息平台，或稍后运行 hermes gateway setup

Setup 写入的是 ./data，临时容器退出后配置不会丢失。

5. 启动并验证#

1
docker compose up -d
2
docker compose ps
3
docker compose logs --tail=100 hermes

再运行健康检查：

1
docker compose exec hermes hermes doctor

局域网浏览器打开：

1
http://NAS_IP:9119

页面应该先进入登录界面。用户名是 .env 里的 DASHBOARD_USER，密码是 DASHBOARD_PASSWORD。

检查认证是否生效：

1
curl -s http://127.0.0.1:9119/api/status

返回结果里的 auth_required 应为 true，认证提供商应包含 basic。如果页面无需登录就能看到管理内容，应立即停止对外访问并检查环境变量是否被 Compose 正确加载。

6. 让桌面应用连接 NAS（可选）#

在 Mac 或 Windows 的 Hermes Desktop 中进入：

1
Settings → Gateway → Remote gateway

在可信局域网或 VPN 内填写：

1
http://NAS_IP:9119

然后点击 Sign in，输入 Compose 项目根目录 .env 中的用户名和密码，保存并重连。这样桌面端只是操作界面，模型调用、工具执行、会话和 Skills 都保留在 NAS 上。这里的 9119 是 Dashboard / Desktop 远程后端端口，不是 8642 的 OpenAI 兼容 API 端口。

WARNING

Dashboard 能读取 API Key、修改配置并执行 Agent 任务。用户名密码方案只适合可信局域网或 VPN，不应直接暴露在公网。需要公网访问时，应使用可信 HTTPS 反向代理，并按官方文档配置 Nous Portal OAuth 或自建 OIDC；不要依赖一个裸露的 HTTP 端口。

管理工具#

1
hermes tools
2
hermes tools list

首次使用建议只打开确实需要的工具。启用高权限工具后，重新开始会话让配置生效。

浏览和安装 Skills#

1
hermes skills browse
2
hermes skills search docker
3
hermes skills list

Skills 不只是 Prompt 收藏夹。一个 Skill 可以包含步骤、命令、模板、脚本和参考资料，让 Agent 在发布博客、管理 GitHub PR、分析数据等重复任务中遵循固定流程。

macOS / Windows / Linux 安装#

Windows 原生环境更新前，应先退出 Desktop、关闭其他 Hermes CLI 会话并停止 Gateway，避免可执行文件或 .pyd 被占用；macOS 和 Linux 也建议先结束正在运行的 Hermes 任务。

1
hermes update
2
hermes doctor

Desktop 也会在后台检查更新，并提供一键升级。

Docker / NAS 安装#

Docker 版不使用 hermes update。应先把 compose.yml、Compose 项目根目录 .env 和整个 data/ 作为同一个部署单元备份，再拉取新镜像：

1
cd ~/docker/hermes
2
umask 077
3
docker compose stop
4
cd ..
5
BACKUP="hermes-backup-$(date +%Y%m%d-%H%M%S).tar.gz"
6
tar -czf "$BACKUP" hermes/compose.yml hermes/.env hermes/data
7
chmod 600 "$BACKUP"
8
cd hermes
9
docker compose pull
10
docker compose up -d
11
docker compose ps
12
docker compose logs --tail=100 hermes

这里有两个不同的秘密文件：项目根目录 .env 保存 Compose、Dashboard 与 UID/GID 参数；data/.env 对应容器内 Hermes 的 Provider Key 和 Token。二者都必须纳入备份。归档文件包含 API Key、OAuth Token、Dashboard 密码和会话，应限制权限，最好加密后再复制到另一块磁盘或另一台设备；只放在同一存储池不能防范磁盘故障。

需要恢复时，先停掉当前部署并保留故障现场，再解压完整归档：

1
cd ~/docker/hermes
2
docker compose down
3
cd ..
4
mv hermes "hermes.failed-$(date +%Y%m%d-%H%M%S)"
5
tar -xzf hermes-backup-YYYYMMDD-HHMMSS.tar.gz
6
cd hermes
7
chmod 600 .env
8
chown -R "$(id -u):$(id -g)" data
9
docker compose config --quiet
10
docker compose up -d
11
docker compose ps
12
curl -s http://127.0.0.1:9119/api/status

如果 chown 提示权限不足，在确认目录路径无误后使用 sudo chown。恢复后应确认 Dashboard 仍要求登录、模型可正常回复，并从真实 Telegram / Discord 消息验证 Gateway，而不是只看容器状态。

hermes: command not found#

重新打开终端，或载入 Shell 配置：

1
source ~/.bashrc
2
# macOS 常见为：source ~/.zshrc

仍有问题时检查 ~/.local/bin 是否在 PATH。

安装完成，但模型不回复#

按这个顺序检查：

1
hermes doctor
2
hermes model
3
hermes --tui

常见原因是 OAuth 过期、API Key 错误、模型名称不匹配，或自建模型上下文小于 64K。先修好普通对话，再排查网关和工具。

NAS 容器反复重启#

1
docker compose ps -a
2
docker compose logs --tail=200 hermes

重点检查：

• ./data 是否可写
• .env 中 UID / GID 是否正确
• YAML 缩进和变量名是否正确
• NAS 架构是否有对应镜像
• 磁盘空间是否充足

不要先删除 data 目录重装。它是唯一持久数据源，排错时应先备份并保留。

Dashboard 打不开或无法登录#

先在 NAS 本机验证：

1
curl -s http://127.0.0.1:9119/api/status
2
docker compose logs --tail=100 hermes

• 本机也不通：检查容器和 Dashboard 进程
• 本机可达、其他设备不通：检查端口映射和 NAS 防火墙
• 返回 401：核对用户名密码
• 每次重启都掉登录：确认 HERMES_DASHBOARD_BASIC_AUTH_SECRET 没有变化

消息平台没有回复#

1
hermes gateway status

然后检查对应平台的 Bot Token、允许用户列表和权限。容器运行中不等于平台已经连接成功，最终要以真实消息往返为准。