行业百科

分享最新的AI行业干货文章

行业百科>Hermes agent部署windows教程，三种方案保姆级配置全记录

Hermes agent部署windows教程，三种方案保姆级配置全记录

2026-04-13 00:30:19

Hermes Agent 是由 Nous Research 开发的“自进化”AI 智能体框架，采用 MIT 许可开源，能从任务中自动提炼技能、跨会话持久记忆用户偏好，越用越懂你。在 Windows 上部署 Hermes Agent 的核心价值在于：即使官方声明“原生 Windows 不支持”，你依然可以通过 WSL2、社区适配脚本或 Docker 三条成熟路径，让这只会自我成长的人工智能“宠物”在 Windows 环境下稳定跑起来。

本文大纲

👉 一、部署前必读：Windows 用户的两条路

👉 二、方案一：WSL2 + 官方一键安装（最稳定，强烈推荐）

👉 三、方案二：Windows 原生 PowerShell 脚本（社区适配版）

👉 四、方案三：Docker Desktop 容器化部署（环境隔离）

👉 五、配置大模型与首次对话

👉 六、接入消息平台（以飞书为例）

👉 七、Windows 特有踩坑与解决方案

👉 八、总结与选型建议

👉 九、实在Agent推荐

Hermes agent部署windows教程——从WSL2到Docker，三种方案保姆级配置全记录_图1

图源：AI生成示意图

一、部署前必读：Windows 用户的两条路

在动手之前，有一件关键的事情需要先搞清楚：Hermes Agent 官方明确声明“Native Windows is not supported”，不支持 Windows 原生环境。

这意味着你在 Windows 上部署 Hermes Agent，有两条路可走：

方案	实现方式	优点	缺点
WSL2（官方推荐）	在 Windows 子系统 Linux 中运行	官方完全支持，体验与原生 Linux 一致，一键安装	需先安装 WSL2，有一定门槛
Windows 原生脚本（社区方案）	使用 PowerShell 一键脚本	无需 WSL，直接在 PowerShell 中运行	存在兼容性问题，部分功能（如微信接入）不稳定

简而言之：如果你追求稳定和完整的官方生态，走 WSL2 路线；如果你只想快速体验、不想折腾 WSL，可以尝试原生 PowerShell 脚本，但要做好遇到兼容性问题的心理准备。

下面分别展开三种方案的详细步骤。

Hermes agent部署windows教程——从WSL2到Docker，三种方案保姆级配置全记录_图2

图源：AI生成示意图

二、方案一：WSL2 + 官方一键安装（最稳定，强烈推荐）

这是官方推荐、社区验证最稳定的 Windows 部署方案。

第 1 步：安装 WSL2（Windows 子系统 Linux）

如果你的 Windows 还没有安装 WSL2，先完成这一步。

以管理员身份打开 PowerShell，运行：

wsl --install

安装完成后重启电脑，WSL2 会默认安装 Ubuntu 发行版。重启后可以在开始菜单找到 Ubuntu 应用，打开后设置用户名和密码即可。

第 2 步：在 WSL2 终端中运行官方一键安装脚本

打开 Ubuntu 终端，运行以下命令：

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

安装脚本会自动完成以下所有工作：

检测/安装 Python 3.11
检测/安装 Node.js v22（浏览器自动化和微信桥接需要）
检测/安装 ripgrep（高速文件搜索）
检测/安装 ffmpeg（音视频处理）
创建独立的 Python 虚拟环境（位于 ~/.hermes/hermes-agent/venv）
克隆代码仓库
安装所有依赖包
将 hermes 命令添加到 PATH

整个过程约 3-5 分钟，耐心等待即可。

第 3 步：重新加载 Shell 并验证安装

source ~/.bashrc
hermes doctor

hermes doctor 会检查所有依赖和配置项，输出类似以下内容即表示安装成功：

✓ Python 3.11.9
✓ Node.js v22.4.0
✓ uv 0.4.1
✓ ripgrep 14.1.0
✓ ffmpeg 6.1.1
✓ ~/.hermes 目录结构
✓ ~/.hermes/.env 配置文件
⚠ 未检测到 API Key，请运行 hermes setup

第 4 步：运行初始化配置向导

hermes setup

在交互向导中选择 Quick setup，按提示配置模型供应商和 API Key。模型配置的详细步骤见本文第五部分。

Hermes agent部署windows教程——从WSL2到Docker，三种方案保姆级配置全记录_图3

图源：AI生成示意图

三、方案二：Windows 原生 PowerShell 脚本（社区适配版）

如果你不想安装 WSL2，社区提供了直接运行在 Windows PowerShell 中的一键脚本。注意：该方案非官方出品，存在部分兼容性问题，仅推荐用于快速体验。 使用前请确保已手动安装 Git。

第 1 步：以管理员身份打开 PowerShell

右键点击开始菜单 → “Windows PowerShell（管理员）”。

第 2 步：运行一键安装命令

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

脚本会自动检测并安装 Python、Node.js、Git、ripgrep 等所有依赖，耐心等待完成即可。

第 3 步：完成初始配置

安装完成后会自动进入配置向导，直接选第一项 Quick setup，按提示选择模型供应商并输入 API Key。向导中的消息平台列表暂时跳过，后续通过 Gateway 单独配置。

第 4 步：验证安装

hermes --version

如果正确显示版本号，说明安装成功。

Hermes agent部署windows教程——从WSL2到Docker，三种方案保姆级配置全记录_图4

图源：AI生成示意图

四、方案三：Docker Desktop 容器化部署（环境隔离）

如果你已经安装了 Docker Desktop，可以通过容器化的方式运行 Hermes Agent，最大程度避免 Windows 环境兼容性问题。

第 1 步：确认 Docker Desktop 已安装并运行

docker --version

第 2 步：拉取官方 Docker 镜像

docker pull nousresearch/hermes-agent:latest

第 3 步：创建数据目录（用于持久化记忆和配置）

mkdir $env:USERPROFILE\.hermes

该目录用于存储配置文件、对话记忆和日志数据，非常重要。

第 4 步：初始化配置

docker run -it --rm -v $env:USERPROFILE\.hermes:/opt/data nousresearch/hermes-agent setup

执行后会进入交互式配置流程，你需要填写 LLM 提供商、API Key 和模型名称。

第 5 步：启动 Web 服务

docker run -d --name hermes --restart always -p 8000:8000 -v $env:USERPROFILE\.hermes:/opt/data nousresearch/hermes-agent hermes gateway run

访问 http://localhost:8000 即可通过浏览器使用 Hermes Agent。

第 6 步：CLI 模式体验（可选）

docker run -it --rm -v $env:USERPROFILE\.hermes:/opt/data nousresearch/hermes-agent bash

适合调试或快速测试。

五、配置大模型与首次对话

无论选择哪种部署方案，完成安装后都需要配置大语言模型才能让 Hermes 真正“活起来”。

5.1 选择模型供应商

运行以下命令进入交互式配置向导：

hermes setup

在向导中选择你的模型供应商。以下是几种常见选择：

供应商	说明	适用场景
OpenRouter	聚合 200+ 模型，一个密钥通吃	国内用户首选，支持 DeepSeek、Kimi、GLM 等
Anthropic	Claude 系列直连	追求编码和推理能力
OpenAI	GPT 系列直连	已有 OpenAI API Key
Nous Portal	官方订阅服务，OAuth 登录	官方生态最佳体验
Ollama	本地模型	隐私优先、零 API 成本

5.2 输入 API Key 并选择默认模型

选择供应商后，向导会提示输入 API Key。密钥会被保存到 ~/.hermes/.env 中，权限自动设为 0600（仅所有者可读写），不会意外泄露。输入后选择默认模型即可完成配置。

5.3 启动对话

hermes

进入交互式终端 UI 后，输入第一条消息，Hermes 会实时流式输出思考和工具调用过程。

5.4 随时切换模型

无需重新运行完整向导，直接使用以下命令即可切换模型：

hermes model

六、接入消息平台（以飞书为例）

让 Hermes Agent 接入飞书，你就能在手机上随时召唤它。以下步骤在 WSL2 和 Windows 原生环境下基本一致。

6.1 飞书开放平台侧配置

访问飞书开放平台 https://open.feishu.cn/，创建企业自建应用。
添加“机器人”能力。
在“权限管理”中至少添加 im:message 和 im:resource 两个权限。
在“凭证与基础信息”中记录 App ID 和 App Secret。
在“事件与回调”中订阅 im.message.receive_v1 事件，订阅方式选择“长连接”。
发布应用。

6.2 Hermes 侧配置 Gateway

运行以下命令进入 Gateway 配置流程：

hermes gateway setup

在渠道列表中选择 飞书（Feishu），按提示依次填写：

App ID 和 App Secret
Domain：国内版填 feishu，海外版填 lark
Connection mode：默认 websocket，直接回车
允许的 User ID：留空；鉴权中选择 1（不限制对话人），这样群里所有人都可以与机器人交互

6.3 启动 Gateway

hermes gateway start

配置完成后，在飞书 App 中搜索你创建的应用名称，找到机器人并发送消息，首次对话会要求配对授权，完成后即可正常对话。

七、Windows 特有踩坑与解决方案

Windows 环境下部署 Hermes Agent，可能会遇到以下兼容性问题，提前知道能省不少时间。

🐛 坑一：模型未被识别，名称显示为空

现象：安装完成后，启动 Hermes 发现模型名称显示为空。

解决方案：在对话中输入 /model 命令手动指定模型，看到模型名称正确显示即代表设置成功。该问题在 Windows 环境下出现概率较高。

🐛 坑二：status.py 的 Windows 兼容性 Bug（仅 Gateway 模式）

现象：飞书 Gateway 启动后，群聊里 @ 机器人没有任何响应。

问题根源：status.py 中使用 os.kill(pid, 0) 检查进程是否存活，但在 Windows 上这个调用会抛出 WinError 11，原始代码没有捕获该异常，导致整个 Gateway 进程异常退出。

修复方案：在 PowerShell 中运行以下 patch 命令，将 OSError 加入异常捕获范围：

python -c "path = r'C:\Users\<用户名>\AppData\Local\hermes\hermes-agent\gateway\status.py'; with open(path, 'r', encoding='utf-8') as f: content = f.read(); content = content.replace('except (ProcessLookupError, PermissionError):', 'except (ProcessLookupError, PermissionError, OSError):'); with open(path, 'w', encoding='utf-8') as f: f.write(content); print('Done')"

注意：请将路径中的 <用户名> 替换为你自己的 Windows 用户名。

🐛 坑三：Gateway 日志中文乱码

现象：Gateway 日志中的 Unicode 符号显示为乱码。

解决方案：启动 Gateway 时加上以下环境变量：

$env:PYTHONIOENCODING='utf-8'
hermes gateway start

🐛 坑四：config.yaml 缺少飞书配置段

现象：patch 后机器人依然没有响应，检查 config.yaml 发现根本没有飞书配置段。

解决方案：编辑 ~/.hermes/config.yaml，添加以下配置段：

gateway:
  feishu:
    app_id: 'cli_xxx'
    app_secret: 'xxx'
    domain: 'feishu'
    connection_mode: 'websocket'
    allowed_users: []
    group_policy: 'allowlist'

注意将 FEISHU_GROUP_POLICY 从默认的 allowlist 改为 open 或手动添加允许的用户 ID。

八、总结与选型建议

在 Windows 上部署 Hermes Agent，核心是绕开“不支持原生 Windows”的官方限制。综合三种方案的优缺点，给出以下选型建议：

你的情况	推荐方案
追求稳定性，愿意花 10 分钟装 WSL2	方案一：WSL2 + 官方一键安装
只想快速体验，不想折腾 WSL	方案二：原生 PowerShell 脚本
已安装 Docker Desktop，习惯容器化部署	方案三：Docker Desktop 部署
需要接入微信等消息平台	强烈推荐方案一（Windows 原生环境微信接入不稳定）

快速命令速查表

操作	命令
检查依赖和配置	hermes doctor
启动配置向导	hermes setup
切换模型	hermes model
启动对话	hermes
配置消息平台	hermes gateway setup
启动 Gateway	hermes gateway start
更新 Hermes	hermes update

如果你想把 Hermes Agent 这类开源 Agent 框架的能力，与 RPA 流程编排、跨系统数据同步和企业内部自动化工作流深度集成，可以了解一下「实在Agent」。它能把大模型调用、业务流程和数据流转串成一条线，让你的 AI 助手从“会聊天”升级为“能干活”的生产力中枢。

上一篇文章

Hermes agent和cc是一家公司的吗？身世大揭秘

下一篇文章

Hermes agent小米的模型怎么用？三模全家桶完整攻略

金融服务商

通信运营商

零售电商

跨境电商

政府及公共服务

能源及制造业

医药行业

更多行业客户

Hermes agent部署windows教程，三种方案保姆级配置全记录

本文大纲

一、部署前必读：Windows 用户的两条路

二、方案一：WSL2 + 官方一键安装（最稳定，强烈推荐）

第 1 步：安装 WSL2（Windows 子系统 Linux）

第 2 步：在 WSL2 终端中运行官方一键安装脚本

第 3 步：重新加载 Shell 并验证安装

第 4 步：运行初始化配置向导

三、方案二：Windows 原生 PowerShell 脚本（社区适配版）

第 1 步：以管理员身份打开 PowerShell

第 2 步：运行一键安装命令

第 3 步：完成初始配置

第 4 步：验证安装

四、方案三：Docker Desktop 容器化部署（环境隔离）

第 1 步：确认 Docker Desktop 已安装并运行

第 2 步：拉取官方 Docker 镜像

第 3 步：创建数据目录（用于持久化记忆和配置）

第 4 步：初始化配置

第 5 步：启动 Web 服务

第 6 步：CLI 模式体验（可选）

五、配置大模型与首次对话

5.1 选择模型供应商

5.2 输入 API Key 并选择默认模型

5.3 启动对话

5.4 随时切换模型

六、接入消息平台（以飞书为例）

6.1 飞书开放平台侧配置

6.2 Hermes 侧配置 Gateway

6.3 启动 Gateway

七、Windows 特有踩坑与解决方案

🐛 坑一：模型未被识别，名称显示为空

🐛 坑二：status.py 的 Windows 兼容性 Bug（仅 Gateway 模式）

🐛 坑三：Gateway 日志中文乱码

🐛 坑四：config.yaml 缺少飞书配置段

八、总结与选型建议

快速命令速查表