本文详细介绍如何在 Windows 系统上部署功能强大的 AI 智能体框架 Hermes Agent，包含 Windows 原生环境部署和官方推荐的 WSL2 部署两种方式，帮你避开常见的坑，快速上手。

📖 目录

• Hermes Agent 简介

• 准备工作

• 方案一：Windows 原生部署

• 方案二：WSL2 部署（推荐）

• 配置阿里云通义千问模型

• 启动 Web UI 和 Gateway

• 常见问题与解决方案

• 总结

---

简介

Hermes Agent 是一个开源 AI 智能体框架，支持多模型调用、文件操作、代码执行、终端命令、消息平台接入等功能。它提供了一个命令行 TUI 和一个可选的 Web UI 界面，方便日常使用。

• GitHub 地址：https://github.com/NousResearch/hermes-agent

• 官方文档：https://hermes-agent.nousresearch.com

本文会带你分别在 Windows 原生环境（有一定限制）和 WSL2 环境（官方推荐，稳定性更好）中完成部署，并连接阿里云的通义千问模型。

---

准备工作

1. 一台联网的 Windows 10/11 电脑

2. 阿里云百炼 API Key（获取方式：登录阿里云百炼控制台 → API-KEY 管理 → 创建 API Key）

3. 稳定的网络（部分步骤需要访问 GitHub 等国际资源）

---

方案一：Windows 原生部署

⚠️ 注意：Hermes 的部分高级功能（如 Gateway 后台服务、某些插件）在 Windows 原生环境下支持不完整。如果你遇到奇怪的 shell 报错，建议直接跳转到方案二（WSL2）。

1. 安装依赖环境

• Python 3.10+（官网下载）

• Git for Windows（官网下载），安装时勾选“Git Bash Here”

• Node.js 18+（官网下载）

安装完成后，重启电脑确保环境变量生效。

2. 安装 Hermes Agent

以管理员身份打开 PowerShell，设置执行策略并运行安装脚本：

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force
irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex

安装完成后，关闭并重新打开 PowerShell，测试命令：

hermes --version

3. 配置阿里云模型

hermes model

在交互菜单中选择 custom (direct API)，然后填写：

• Base URL: https://dashscope.aliyuncs.com/compatible-mode/v1

• API Key: 你的阿里云百炼 API Key

• 模型名: qwen-plus（或 qwen-turbo / qwen-max）

4. 启动 Web UI

由于 Windows 原生环境下 hermes gateway 不能作为后台服务，你需要打开两个 PowerShell 窗口：

窗口1（Gateway）：

hermes gateway

保持运行，不要关闭。

窗口2（Web UI）：

hermes-web-ui start

浏览器访问 http://localhost:8648 即可使用。

💡 如果 Web UI 显示“未连接”，请参考后面的“常见问题”章节。

---

方案二：WSL2 部署（推荐）

WSL2 提供一个完整的 Linux 内核，Hermes 的所有功能都能完美运行，是官方推荐的方式。

1. 安装 WSL2

以管理员身份打开 PowerShell，执行

wsl --install

重启电脑。重启后，启动 Ubuntu，设置用户名和密码。

2. 安装 Hermes Agent

在 Ubuntu 终端中执行一键安装脚本：

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

3. 配置阿里云模型

同样使用 hermes model 命令，选择 custom (direct API) 并填写相同的信息。

4. 启动 Gateway 和 Web UI

打开两个 Ubuntu 终端窗口：

终端1（Gateway）：

hermes gateway

终端2（Web UI）：

hermes-web-ui start

然后在 Windows 浏览器中访问 http://localhost:8648。

---

配置阿里云通义千问模型（通用）

无论哪种部署方式，配置模型的步骤都是一样的。也可以直接编辑配置文件：

yaml

model:
  default: qwen-plus
  provider: custom
  base_url: https://dashscope.aliyuncs.com/compatible-mode/v1
  api_key: sk-xxxxxx
  context_length: 128000

测试连通性：

hermes chat -q "你好"

如果正常回复，说明模型配置成功。

---

启动 Web UI 和 Gateway

Web UI 需要 Gateway 的 API 服务才能工作。Gateway 默认 API 端口为 8642，Web UI 默认端口为 8648。

Gateway 启动注意事项

• 在 WSL2 中：直接运行 hermes gateway 即可，API 服务器默认监听 127.0.0.1:8642。如果从 Windows 浏览器访问，需要将 api_server.host 改为 0.0.0.0（编辑 ~/.hermes/config.yaml）。

• 在 Windows 原生中：Gateway 不能后台运行，必须保持前台窗口。另外，需要手动开启 API 服务器：在 .env 文件中添加 API_SERVER_ENABLED=true 和 API_SERVER_KEY=你的密钥，然后在 Web UI 设置中填入相同的密钥。

解决 Web UI “未连接”

1. 确保 Gateway 正在运行（查看对应终端窗口是否有日志输出）。

2. 检查 API 地址是否正确：在浏览器访问 http://localhost:8642/health，应返回 {"status":"ok"}。

3. 如果返回“Unauthorized”，说明需要设置 API Key。在 .env 中配置 API_SERVER_KEY，并在 Web UI 的设置中填入相同的值。

---

常见问题与解决方案

❌ 报错：Service installation not supported on this platform

• 原因：Windows 原生环境不支持 hermes gateway install。

• 解决：使用前台运行 hermes gateway 窗口。

❌ 报错：Failed to spawn shell "/bin/bash": File not found

• 原因：Git Bash 未安装或未加入 PATH，或 Web UI 硬编码了 Linux 路径。

• 解决：安装 Git for Windows，并将其 bin 目录添加到系统 PATH；或切换到 WSL2 部署。

❌ 报错：API call failed: Arrearage

• 原因：阿里云账户欠费。

• 解决：登录阿里云控制台，充值并结清欠费。

❌ WSL2 中无法 clone 仓库（TLS 错误）

• 原因：网络问题导致无法访问 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

❌ Web UI 一直显示“未连接”

• 排查步骤：

  1. 确认 Gateway 窗口有 API server listening on ... 日志。

  2. 在浏览器测试 http://localhost:8642/health。

  3. 如果返回 401，配置 API Key 并同步到 Web UI。

  4. 在 WSL2 中设置 api_server.host: 0.0.0.0。

❌ 文件操作失效（Agent 说创建成功但看不到文件）

• 原因：Agent 使用了容器后端（如 docker）。

• 解决：执行 hermes config set terminal.backend local，然后重启 Gateway。

---

总结

本文详细介绍了 Hermes Agent 在 Windows 原生环境和 WSL2 环境下的部署方法，以及如何配置阿里云通义千问模型。经过大量测试，强烈推荐使用 WSL2 方案，它能够完美支持所有功能，避免很多 Windows 原生环境下的兼容性问题。

部署完成后，你就可以通过 Web UI 或命令行与 Hermes 进行对话，让它帮你执行代码、管理文件、自动化任务等。后续你还可以接入 Telegram、Discord 等平台，打造个人专属的 AI 助手。

如果在部署过程中遇到其他问题，欢迎在评论区留言交流！