Hermes Agent 安装避坑指南:从零到一搞定 AI 助手部署

全网最全 Hermes Agent 安装问题汇总，新手也能轻松上手

写在前面

最近不少小伙伴在尝试部署 Hermes Agent 时遇到了各种问题：有的安装后找不到 hermes 命令，有的在 Windows 上怎么也跑不起来，还有的被各种依赖报错搞得焦头烂额。

今天，我把这些常见问题一次性整理出来，希望能帮你少走弯路。

一、Hermes Agent 是什么?

用官网的话来说：

部署在你的服务器上，连接你的消息账号，它就成为你的持久个人智能体——学习你的项目、自动构建技能、随时随地触达你。不是聊天机器人，不是代码补全工具，而是一个住在你机器上、每天都在变聪明的智能体。

二、安装方式选择：第一步就走对

错误做法

在原生 Windows（PowerShell 或 CMD）中直接运行安装命令。

直接给你来个大❌❌❌

正确做法

方案一（强烈推荐）：使用 WSL2 + Ubuntu

在 WSL2 Ubuntu 中执行以下命令：

命令：

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

方案二：Windows PowerShell 实验性支持
命令：

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

三、安装后常见问题及解决方案

问题1：hermes: command not found

原因：PATH 环境变量未及时刷新。

解决方案：

source ~/.bashrc （bash 用户）
source ~/.zshrc （zsh 用户）

如果仍然找不到，执行：

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

问题2：Python 版本不兼容

要求：Python 3.10 或更高版本。

解决方案：

检查当前版本：python3 --version

如果版本过低，使用 pyenv 安装：

curl https://pyenv.run | bash
pyenv install 3.11
pyenv global 3.11

问题3：依赖安装失败

解决方案：

cd ~/hermes-agent
./venv/bin/python -m pip install pyyaml python-dotenv
./venv/bin/python -m pip install -e ".[all]"

如果不需要多媒体功能，可以最小化安装：

./venv/bin/python -m pip install -e "."

四、WSL2 配置问题

问题：虚拟化未启用

解决方案（以管理员身份运行 PowerShell）：

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

重启电脑，并在 BIOS 中启用 Intel VT-x 或 AMD-V。

问题：WSL2 内存不足

在用户目录创建 .wslconfig 文件，内容如下：

[wsl2]
memory=6GB
swap=2GB
localhostForwarding=true

然后执行 wsl --shutdown 重启 WSL。

五、网络相关问题

问题：GitHub 访问超时

解决方案（使用镜像仓库）：

git clone https://gitcode.com/GitHub_Trending/he/hermes-agent.git ~/.hermes/hermes-agent
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

问题：DNS 解析失败

执行：echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf

六、API Key 配置问题

问题：401 Unauthorized

解决方案：

查看当前配置：hermes config list

交互式配置：hermes model

直接设置：hermes config set OPENROUTER_API_KEY "sk-or-xxx"

常见 API Key 环境变量对照表：

• OpenRouter：OPENROUTER_API_KEY

• OpenAI：OPENAI_API_KEY

• 阿里云 DashScope：DASHSCOPE_API_KEY

七、机器人网关问题

问题：用户白名单警告

警告内容：No user allowlists configured. All unauthorized users will be denied.

解决方案：在 ~/.hermes/.env 文件中添加一行：

GATEWAY_ALLOW_ALL_USERS=true

问题：飞书 SDK 缺失

找到 venv 路径后执行：

uv pip install lark-oapi --python "路径/venv/bin/python"

问题：QQ Bot 认证失败

错误信息：invalid appid or secret

解决方案：

1. 确认 AppID 和 AppSecret 正确

2. 检查机器人是否已通过审核

3. 临时跳过：在 .env 中添加 QQ_BOT_ENABLED=false

八、实用诊断命令

查看版本：hermes --version

运行诊断：hermes doctor

查看配置：hermes config list

查看日志：hermes logs --last 20

测试聊天：hermes chat -q "Hello"

九、完全重装（终极方案）

如果以上方法都无法解决，建议完全清理后重装：

1. 清理旧文件
   rm -rf ~/.hermes ~/bin/hermes /usr/local/bin/hermes

2. 清理 Python 缓存
   rm -rf ~/.cache/pip

3. 重新安装
   curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

4. 刷新环境变量
   source ~/.bashrc

5. 验证安装
   hermes doctor

十、快速排障流程图

写在最后

Hermes Agent 是一个强大的 AI 助手框架，但部署过程中的确会遇到一些坑。希望这篇文章能帮你顺利跨越这些障碍。

如果你在安装过程中遇到了本文未覆盖的问题，欢迎在评论区留言交流！

小贴士：建议首次安装时使用 WSL2 + Ubuntu 环境，这是最稳定、问题最少的方式。