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

目录

• 1. Hermes Agent 是什么
• 2. 官方资料入口
• 3. 安装路径选择
• 4. 安装前准备
• 4.1 通用准备
• 4.2 依赖说明
• 4.3 模型/API 准备
• 5. Linux 安装
• 5.1 安装基础工具
• 5.2 执行官方安装脚本
• 5.3 Linux 安装目录
• 5.4 Linux 无 sudo/服务账号安装
• 6. macOS 安装
• 6.1 安装 Git 和命令行工具
• 6.2 执行官方安装脚本
• 6.3 macOS 注意事项
• 7. Windows 安装
• 7.1 推荐方案：Windows + WSL2
• 7.2 Windows 原生 PowerShell 安装：early beta
• 8. Android Termux 安装
• 8.1 安装 Termux
• 8.2 更新 Termux 并安装基础工具
• 8.3 执行官方安装脚本
• 8.4 Termux 注意事项
• 9. Nix/NixOS 安装
• 10. PyPI 安装方式
• 11. 初始配置
• 12. 验证安装是否成功
• 12.1 基础检查
• 12.2 启动聊天
• 12.3 测试会话恢复
• 12.4 测试工具能力
• 13. 常用功能开通
• 13.1 Gateway 消息平台
• 13.2 Skills
• 13.3 MCP 服务器
• 13.4 Docker/远程终端隔离
• 13.5 Voice 模式
• 14. 更新
• 15. 卸载
• 16. 常见问题
• 16.1hermes: command not found
• 16.2API key not set
• 16.3 模型能连上但回答异常
• 16.4 Gateway 启动但收不到消息
• 16.5hermes –continue找不到旧会话
• 16.6 Playwright/Chromium 安装失败
• 16.7 Windows 原生编码或终端异常
• 17. 安全注意事项
• 18. 推荐完整安装流程
• 19. 速查命令
• 20. 最后建议

适用日期：2026-05-18

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

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

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

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

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

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

• 官方仓库：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

使用场景	推荐安装方式	说明
Linux 桌面/服务器	官方 install.sh	官方主推荐路径，跟踪 main 分支
macOS	官方 install.sh	推荐在 zsh/bash 终端执行
Windows 稳定使用	WSL2 + Ubuntu + install.sh	当前最稳妥的 Windows 方案
Windows 原生	PowerShell install.ps1	官方标注为 early beta，适合愿意排障的用户
Android 手机/平板	Termux + install.sh	官方有 Termux 感知安装流程
Nix/NixOS	官方 Nix/NixOS 路径	建议按官方 Nix 指南走，不要混装
想固定 PyPI 版本	pip install hermes-agent	跟随 PyPI/tagged release，不追 main 每次提交
无 sudo 服务账号	普通用户安装 + 管理员补系统库	适合 systemd service、服务器机器人

安装前确认：

git --version
curl --version

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

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

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

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

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

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

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

提供方	准备内容
Nous Portal	按 hermes model 向导登录/配置
OpenAI/Codex	按向导 OAuth 或准备相关 API/账号能力
Anthropic	OAuth 或 Anthropic API key
OpenRouter	OPENROUTER_API_KEY
Z.AI/GLM	GLM_API_KEY 或 ZAI_API_KEY
Kimi/Moonshot	KIMI_API_KEY 或 KIMI_CN_API_KEY
Alibaba Cloud Qwen/DashScope	DASHSCOPE_API_KEY
Hugging Face Router	HF_TOKEN
AWS Bedrock	IAM 权限或 aws configure

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

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

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

验证：

git --version
curl --version

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

安装结束后重新加载 shell：

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

验证命令是否可用：

hermes --version
hermes doctor

普通用户安装通常为：

代码目录：~/.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。

如果 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

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

xcode-select --install

也可以使用 Homebrew 安装 Git：

brew install git

验证：

git --version
curl --version

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

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

source ~/.zshrc

验证：

hermes --version
hermes doctor

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

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

这是当前更稳妥的 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 原生安装互不冲突。

官方文档标注 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%hermeshermes-agent
Git 目录：%LOCALAPPDATA%hermesgit
数据目录：%LOCALAPPDATA%hermes

原生 Windows 当前注意事项：

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

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

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

pkg update
pkg upgrade
pkg install git curl

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

官方文档说明 Termux 路径会：

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

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

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

注意事项：

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

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

pip install hermes-agent
hermes postinstall

说明：

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

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

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 等扩展能力。

hermes --version
hermes doctor

hermes

进入后输入：

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

退出后执行：

hermes --continue
# 或
hermes -c

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

在 Hermes 对话中输入：

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

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

基础聊天成功后再配置：

hermes gateway setup

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

排查状态：

hermes gateway status

搜索技能：

hermes skills search kubernetes

安装技能：

hermes skills install openai/skills/k8s

也可在聊天中使用 /skills。

示例配置片段：

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

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

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

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

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

官方 quickstart 中的示例：

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

然后在 CLI 中：

/voice on

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

常规更新：

hermes update

检查更新：

hermes update --check

更新前备份：

hermes update --backup

更新后重启 gateway：

hermes update --restart-gateway

注意事项：

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

常规卸载：

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、旧配置导致的问题，优先检查数据目录是否残留。

处理：

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

仍不行则检查：

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

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

运行：

hermes model

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

hermes config set OPENROUTER_API_KEY your_key

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

可能原因：

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

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

hermes model
hermes doctor
hermes

检查：

hermes gateway status
hermes gateway setup

重点看：

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

检查：

hermes sessions list

可能原因：

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

常见原因：

• 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

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

原生排查可尝试：

$env:HERMES_DISABLE_WINDOWS_UTF8="1"
hermes doctor

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

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 轮换。

新用户按这个顺序最稳：

# 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 终端中执行。

目的	命令
启动聊天	hermes
恢复最近会话	hermes --continue 或 hermes -c
环境诊断	hermes doctor
完整设置向导	hermes setup
配置模型	hermes model
配置工具	hermes tools
配置消息平台	hermes gateway setup
查看 gateway 状态	hermes gateway status
搜索技能	hermes skills search <keyword>
安装技能	hermes skills install <skill>
更新	hermes update
更新前备份	hermes update --backup
卸载	hermes uninstall
完全卸载	hermes uninstall --full

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

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

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

以上就是20256年Hermes Agent的安装全流程说明的详细内容，更多关于Hermes Agent安装的资料请关注风君子博客其它相关文章！