20256年Hermes Agent的安装全流程说明

适用日期：2026-05-18

适用对象：需要在 Windows、macOS、Linux、WSL2、Android Termux、Nix/NixOS 或服务器环境中安装 Hermes Agent 的用户。

主要参考：NousResearch/hermes-agent 官方仓库与官方文档。安装命令、平台状态和功能支持可能随版本变化，执行前建议再打开官方文档确认一次。

1. Hermes Agent 是什么

Hermes Agent 是 NousResearch 开源的个人 AI agent。它可以在命令行中对话、调用本地工具、执行终端任务、连接消息平台、安装技能、使用 MCP 服务，并支持长期会话、网关、计划任务等功能。

本说明聚焦“从零安装到可用”的完整流程，包含：

• 各操作系统安装路径；
• 环境依赖与目录说明；
• 模型/API 配置；
• 安装后验证；
• 更新、卸载、迁移与排障；
• 安全和注意事项。

2. 官方资料入口

建议优先阅读官方资料，避免使用来源不明的第三方安装脚本。

• 官方仓库：https://github.com/NousResearch/hermes-agent
• 官方安装文档：https://github.com/NousResearch/hermes-agent/blob/main/website/docs/getting-started/installation.md
• 官方快速开始：https://github.com/NousResearch/hermes-agent/blob/main/website/docs/getting-started/quickstart.md
• 官方 CLI 命令参考：https://github.com/NousResearch/hermes-agent/blob/main/website/docs/reference/cli-commands.md

3. 安装路径选择

4. 安装前准备

4.1 通用准备

安装前确认：

git --version
curl --version

官方 Git 安装器的核心前提是能访问 GitHub，并且能拉取：

https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh

如果网络环境无法访问 GitHub raw 域名，安装脚本会失败。国内网络环境建议提前准备代理或镜像方案，但不要随意运行未知第三方脚本。

4.2 依赖说明

官方安装器会自动处理大部分依赖：

• uv：Python 包和虚拟环境管理；
• Python 3.11；
• Node.js 22；
• ripgrep；
• ffmpeg；
• Playwright/Chromium 相关浏览器能力；
• Hermes 仓库克隆、虚拟环境、全局 hermes 命令；
• 初始模型/工具配置向导。

通常不需要手动安装 Python、Node.js、ripgrep、ffmpeg。真正需要提前确认的是 git、curl、网络访问和终端权限。

4.3 模型/API 准备

Hermes Agent 安装后需要配置至少一个模型提供方。常见选择：

推荐先只配置一个稳定可用的模型，完成 CLI 聊天验证后，再添加 gateway、cron、skills、voice、MCP 等高级能力。

5. Linux 安装

以下适用于 Ubuntu、Debian、Fedora、Arch、openSUSE 等主流 Linux。命令以 Debian/Ubuntu 为例。

5.1 安装基础工具

sudo apt update
sudo apt install -y git curl ca-certificates

验证：

git --version
curl --version

5.2 执行官方安装脚本

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

安装结束后重新加载 shell：

source ~/.bashrc
# 如果使用 zsh：
source ~/.zshrc

验证命令是否可用：

hermes --version
hermes doctor

5.3 Linux 安装目录

普通用户安装通常为：

代码目录：~/.hermes/hermes-agent/
命令入口：~/.local/bin/hermes
数据目录：~/.hermes/

如果用 root/system-wide 方式安装，官方文档说明可能使用：

代码目录：/usr/local/lib/hermes-agent/
命令入口：/usr/local/bin/hermes
root 数据：/root/.hermes/ 或 HERMES_HOME 指定目录

建议个人电脑使用普通用户安装，不要默认用 sudo curl ... | sudo bash。

5.4 Linux 无 sudo/服务账号安装

如果 Hermes 要作为独立服务账号运行，例如 hermes 用户无 sudo 权限：

管理员先安装 Chromium/Playwright 所需系统库：

sudo npx playwright install-deps chromium

切换到服务用户执行普通安装：

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

确认 ~/.local/bin 在 PATH 中：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

验证：

hermes doctor

如果不需要浏览器自动化，可以跳过浏览器组件：

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash -s -- --skip-browser

6. macOS 安装

6.1 安装 Git 和命令行工具

macOS 通常需要先安装 Xcode Command Line Tools：

xcode-select --install

也可以使用 Homebrew 安装 Git：

brew install git

验证：

git --version
curl --version

6.2 执行官方安装脚本

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

macOS 默认 shell 多为 zsh，安装后执行：

source ~/.zshrc

验证：

hermes --version
hermes doctor

6.3 macOS 注意事项

• 如果终端提示 hermes: command not found，先重新打开终端，或确认 ~/.local/bin 是否在 PATH 中。
• 如果 Playwright/Chromium 下载失败，多半是网络问题，先解决 GitHub/npm/Playwright 的访问。
• 如果系统弹出安全提示，确认你运行的是官方 GitHub 仓库脚本，不要放行不明来源脚本。

7. Windows 安装

Windows 有两条路：推荐 WSL2，或使用原生 PowerShell beta 安装。

7.1 推荐方案：Windows + WSL2

这是当前更稳妥的 Windows 路径，适合长期使用。

7.1.1 安装 WSL2

以管理员身份打开 PowerShell：

wsl --install

如需指定 Ubuntu：

wsl --install -d Ubuntu

安装完成后重启电脑，打开 Ubuntu 终端，创建 Linux 用户。

7.1.2 在 WSL2 中安装基础工具

在 Ubuntu/WSL2 终端执行：

sudo apt update
sudo apt install -y git curl ca-certificates

7.1.3 在 WSL2 中安装 Hermes Agent

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
source ~/.bashrc
hermes doctor

7.1.4 WSL2 注意事项

• Windows 文件系统路径如 C:\Users\... 在 WSL 中通常映射到 /mnt/c/Users/...。
• 如果要让 Hermes 操作项目文件，建议把项目放在 WSL 的 Linux 文件系统内，例如 ~/projects，性能和权限更稳定。
• WSL2 安装的数据位于 Linux 用户的 ~/.hermes，与 Windows 原生安装互不冲突。

7.2 Windows 原生 PowerShell 安装：early beta

官方文档标注 Windows 原生支持仍是 early beta。普通用户建议优先使用 WSL2。确实要原生安装时，打开 PowerShell 执行：

irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex

安装器会处理：

• uv；
• Python 3.11；
• Node.js 22；
• ripgrep；
• ffmpeg；
• PortableGit/Git Bash；
• Hermes 仓库和虚拟环境；
• 用户 PATH 中的 hermes 命令。

安装完成后关闭并重新打开 PowerShell：

hermes --version
hermes doctor

原生 Windows 默认目录：

代码目录：%LOCALAPPDATA%\hermes\hermes-agent
Git 目录：%LOCALAPPDATA%\hermes\git
数据目录：%LOCALAPPDATA%\hermes

原生 Windows 当前注意事项：

• 官方文档说明大部分 CLI、gateway、cron、browser tool、MCP 能力可原生运行；
• Dashboard 的 /chat 终端面板依赖 POSIX PTY，官方说明仍需要 WSL2；
• 若遇到编码问题，可按官方说明尝试设置 HERMES_DISABLE_WINDOWS_UTF8=1 排查；
• 不建议在 Windows CMD 中执行安装命令，使用 PowerShell。

8. Android Termux 安装

Hermes Agent 官方安装脚本会自动识别 Termux，并切换到 Android/Termux 流程。

8.1 安装 Termux

建议从 F-Droid 安装新版 Termux，不建议使用长期未更新的应用商店旧版。

8.2 更新 Termux 并安装基础工具

pkg update
pkg upgrade
pkg install git curl

8.3 执行官方安装脚本

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

官方文档说明 Termux 路径会：

• 使用 pkg 安装系统依赖；
• 用 python -m venv 创建虚拟环境；
• 自动设置 Android wheel 构建所需环境；
• 优先安装 Termux 相关 extras；
• 默认跳过未经充分验证的浏览器/WhatsApp 引导。

8.4 Termux 注意事项

• 手机端性能、内存、后台保活都比桌面/服务器弱；
• 不建议一开始启用过多后台 gateway；
• 如果需要 24/7 在线，优先考虑 VPS 或家用服务器。

9. Nix/NixOS 安装

如果你使用 NixOS、macOS + Nix、Linux + Nix，建议按官方 Nix/NixOS 指南走 flake 或 declarative module 路径。

注意事项：

• 不要同时混用 Nix 管理的 Python/Node 与普通安装器生成的虚拟环境，除非你明确知道 PATH 和依赖来源；
• NixOS 上浏览器、系统库、服务权限建议全部写入配置；
• 如果只是普通用户试用，非 Nix 系统可优先使用官方 install.sh。

10. PyPI 安装方式

如果你希望安装 PyPI 发布版本，而不是跟踪 main 分支：

pip install hermes-agent
hermes postinstall

说明：

• PyPI 版本通常跟随 tagged release，不一定包含 main 最新提交；
• hermes postinstall 会安装/配置 Node.js、浏览器、ripgrep、ffmpeg 等后置组件；
• 适合追求可复现版本的环境；
• 如果你需要最新功能，官方 quickstart 推荐使用 Git 安装器。

11. 初始配置

安装完成后，先运行完整向导：

hermes setup

或只配置模型：

hermes model

也可以分别配置：

hermes tools
hermes gateway setup
hermes config set

推荐顺序：

1. hermes doctor 检查环境；
2. hermes model 配置一个模型；
3. hermes 进入聊天；
4. 让它回答一个简单问题；
5. 再配置 gateway、skills、MCP、voice 等扩展能力。

12. 验证安装是否成功

12.1 基础检查

hermes --version
hermes doctor

12.2 启动聊天

hermes

进入后输入：

你好，简单介绍一下你当前能使用的工具。

12.3 测试会话恢复

退出后执行：

hermes --continue
# 或
hermes -c

如果能恢复上一段对话，说明基础会话保存正常。

12.4 测试工具能力

在 Hermes 对话中输入：

查看当前目录下有哪些文件。

如果 Hermes 能调用终端并返回结果，说明 terminal tool 基础能力可用。

13. 常用功能开通

13.1 Gateway 消息平台

基础聊天成功后再配置：

hermes gateway setup

可按官方支持情况连接 Telegram、Discord、Slack、WhatsApp、Signal、Email、Home Assistant、Microsoft Teams 等平台。

排查状态：

hermes gateway status

13.2 Skills

搜索技能：

hermes skills search kubernetes

安装技能：

hermes skills install openai/skills/k8s

也可在聊天中使用 /skills。

13.3 MCP 服务器

示例配置片段：

mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"

注意：不要把真实 token 提交到 Git 仓库。建议使用环境变量、密钥管理器或本机私有配置文件。

13.4 Docker/远程终端隔离

如果担心 agent 直接操作本机，可考虑把 terminal backend 放到 Docker 或远程服务器：

hermes config set terminal.backend docker
hermes config set terminal.backend ssh

实际启用前应确认 Docker/SSH 的权限边界、挂载目录和网络访问范围。

13.5 Voice 模式

官方 quickstart 中的示例：

cd ~/.hermes/hermes-agent
uv pip install -e ".[voice]"

然后在 CLI 中：

/voice on

按官方说明可用快捷键录音。语音依赖较多，如安装失败，先确保基础 CLI 和模型可用。

14. 更新

常规更新：

hermes update

检查更新：

hermes update --check

更新前备份：

hermes update --backup

更新后重启 gateway：

hermes update --restart-gateway

注意事项：

• 更新前建议先运行 hermes doctor，记录当前状态；
• 长期运行的 gateway 建议在低峰期更新；
• 如果本地修改过 Hermes 源码，git pull 可能因工作区变更而失败；
• 重要生产环境建议先备份 HERMES_HOME。

15. 卸载

常规卸载：

hermes uninstall

删除配置和数据：

hermes uninstall --full

无人值守确认：

hermes uninstall --full --yes

卸载前建议备份：

cp -a ~/.hermes ~/.hermes.backup.$(date +%Y%m%d)

Windows 原生安装的配置/数据在：

%LOCALAPPDATA%\hermes

WSL2/Linux/macOS 通常在：

~/.hermes

如果卸载后重装仍出现旧 profile、旧 session、旧配置导致的问题，优先检查数据目录是否残留。

16. 常见问题

16.1hermes: command not found

处理：

source ~/.bashrc
# 或
source ~/.zshrc

仍不行则检查：

echo $PATH
ls -l ~/.local/bin/hermes

Windows 原生安装后需要关闭并重新打开 PowerShell。

16.2API key not set

运行：

hermes model

或使用配置命令写入对应 key，例如：

hermes config set OPENROUTER_API_KEY your_key

更推荐用交互向导，避免 key 名写错。

16.3 模型能连上但回答异常

可能原因：

• base URL 写错；
• model name 写错；
• 代理服务并非真正 OpenAI-compatible；
• provider fallback 或 routing 配置过于复杂。

建议先关闭高级路由，只保留一个模型，运行：

hermes model
hermes doctor
hermes

16.4 Gateway 启动但收不到消息

检查：

hermes gateway status
hermes gateway setup

重点看：

• bot token 是否正确；
• allowlist 是否限制了用户；
• 平台 webhook/权限是否配置完成；
• gateway 是否在正确 profile 下运行。

16.5hermes --continue找不到旧会话

检查：

hermes sessions list

可能原因：

• 切换了 profile；
• 旧会话没有保存；
• HERMES_HOME 指到了另一个目录；
• WSL2 与 Windows 原生安装混用，数据目录不同。

16.6 Playwright/Chromium 安装失败

常见原因：

• Linux 缺少系统库；
• 无 sudo 权限；
• 网络无法下载浏览器；
• 企业网络拦截 npm/Playwright 下载。

可选方案：

sudo npx playwright install-deps chromium

或跳过浏览器能力：

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash -s -- --skip-browser

16.7 Windows 原生编码或终端异常

先确认是否必须原生运行。如果不是，建议改用 WSL2。

原生排查可尝试：

$env:HERMES_DISABLE_WINDOWS_UTF8="1"
hermes doctor

如果问题消失，再考虑把该环境变量写入用户环境变量。

17. 安全注意事项

1. 只运行官方仓库脚本，安装前确认 URL 是 NousResearch/hermes-agent。
2. 不要把 API key、GitHub token、SSH key 写进公开仓库。
3. 第一次运行 agent 时，不要直接给它全盘写权限；先在测试目录里验证。
4. 生产服务器建议使用独立低权限用户运行 Hermes。
5. 需要浏览器、文件、终端、网络能力时，逐项开启，不要一次性 开放全部工具。
6. 重要目录操作前先备份。
7. 如果让 Hermes 连接 Telegram/Discord/Slack 等平台，务必设置 allowlist 或等价权限控制。
8. 对长期在线的 gateway，要关注日志、更新节奏和 token 轮换。

18. 推荐完整安装流程

新用户按这个顺序最稳：

# 1. 检查基础工具
git --version
curl --version

# 2. 安装 Hermes Agent
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

# 3. 重新加载 shell
source ~/.bashrc

# 4. 检查环境
hermes doctor

# 5. 配置模型
hermes model

# 6. 启动聊天
hermes

# 7. 测试恢复会话
hermes --continue

Windows 用户推荐把第 2 步放到 WSL2 的 Ubuntu 终端中执行。

19. 速查命令

20. 最后建议

不要一装完就同时开启 gateway、cron、voice、browser、MCP 和多个 provider。最稳的方式是：

1. 先让 CLI 能稳定回答；
2. 再让 terminal tool 正常工作；
3. 再配置一个消息平台；
4. 再加 skills/MCP；
5. 最后考虑长期后台运行和隔离策略。

这样出问题时，每一步都有清晰的回退点。

以上就是20256年Hermes Agent的安装全流程说明的详细内容，更多关于Hermes Agent安装的资料请关注脚本之家其它相关文章！

最新评论