大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。



本文档用于指导你在 Windows 11 本地环境中部署 NousResearch/hermes-agent，并接入 飞书 作为消息入口，使你可以直接在飞书里和 Hermes Agent 对话。

本教程基于 Hermes Agent 官方文档整理，并针对 Win11 + WSL2 + 飞书 场景做了适配。

Hermes Agent 不支持原生 Windows 直接运行。

官方推荐方式是：

• 在 Windows 11 上安装 WSL2
• 在 WSL2 的 Linux 环境中安装和运行 Hermes Agent
• 使用 飞书 WebSocket 模式 接入

这是你本地环境里最稳、最省事的方案，因为：

• 不需要公网服务器
• 不需要配置反向代理
• 不需要暴露 Webhook 地址
• 飞书消息可以直接通过官方 SDK 的长连接推送到本地 Hermes

推荐部署结构如下：

• Windows 11：你的宿主系统
• WSL2 Ubuntu：运行 Hermes Agent
• LLM 提供商：如 OpenAI、OpenRouter、Anthropic、Gemini、Qwen 等
• 飞书应用：作为消息入口
• Hermes Gateway：在 WSL2 中启动，接收飞书消息并调用模型响应

数据流大致如下：

1. 你在飞书里给机器人发消息
2. 飞书通过 WebSocket 把事件推送给 Hermes
3. Hermes 调用你配置的 LLM
4. Hermes 把结果再发回飞书

开始前，你需要准备以下内容。

4.1 Windows 侧前置条件

你需要：

• Windows 11
• 管理员权限 PowerShell
• 稳定的网络环境
• 一个可用的飞书账号
• 一个可用的 LLM API Key

4.2 模型侧前置条件

Hermes Agent 不是纯本地聊天壳，它必须连接一个大模型提供商。

官方要求：

• 模型上下文窗口至少 64K

推荐你优先选择以下任一提供商：

• OpenRouter
• OpenAI
• Anthropic
• Gemini
• Qwen
• DeepSeek

如果你只是想先跑通流程，推荐使用：

• OpenRouter

原因：

• 接入简单
• 可选模型多
• 容易先验证 Hermes 是否工作正常

5.1 打开管理员 PowerShell

在开始菜单搜索 PowerShell，右键选择“以管理员身份运行”。

5.2 安装 WSL2

执行：

wsl --install 

如果你想显式安装 Ubuntu，也可以执行：

wsl --install -d Ubuntu 

安装完成后，按提示重启电脑。

5.3 初始化 Ubuntu

重启后打开 Ubuntu，系统会要求你创建：

• Linux 用户名
• Linux 密码

记住这组用户名和密码，后面会用到。

5.4 验证 WSL 状态

回到 PowerShell，执行：

wsl -l -v 

你应该看到类似：

 NAME STATE VERSION * Ubuntu Running 2 

确认 VERSION 是 2。

进入 Ubuntu 终端，执行：

sudo apt update sudo apt install -y curl git 

说明：

• curl 用于拉取 Hermes 官方安装脚本
• git 便于后续查看源码或更新

7.1 使用官方安装脚本

在 WSL2 里执行：

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

官方说明中明确指出：

• 支持 Linux、macOS、WSL2
• Windows 原生不支持

该安装脚本通常会自动完成：

• 安装 uv
• 创建虚拟环境
• 安装 Hermes Agent
• 配置命令入口

7.2 重新加载 shell

安装结束后执行：

source ~/.bashrc 

如果你使用的是 zsh，则执行：

source ~/.zshrc 

7.3 验证 Hermes 是否安装成功

执行：

hermes --help 

如果命令可用，说明安装成功。

你也可以执行：

hermes doctor 

用于检查当前 Hermes 环境状态。

这是官方非常强调的一点：

如果 Hermes 连基础对话都跑不通，不要先接网关和消息平台。

所以推荐顺序是：

1. 先安装 Hermes
2. 先配置模型
3. 先在终端里聊天验证成功
4. 再接飞书

8.1 交互式配置模型

执行：

hermes model 

该命令会引导你选择：

• 提供商
• 模型
• API Key
• 其他必要配置

8.2 推荐方案：使用 OpenRouter

如果你走 OpenRouter，通常你需要准备：

• OPENROUTER_API_KEY

Hermes 会把配置自动分别写入：

• 密钥类配置：~/.hermes/.env
• 普通配置：~/.hermes/config.yaml

8.3 手动配置方式

如果你不想走交互式流程，也可以手动写入配置。

Hermes 官方约定：

• ~/.hermes/.env：存放密钥和令牌
• ~/.hermes/config.yaml：存放非敏感配置

例如你可以通过命令设置：

hermes config set OPENROUTER_API_KEY sk-or-xxx 

再设置模型：

hermes config set model openrouter/openai/gpt-4o-mini 

注意：

• 具体模型名以你实际可用的 provider/model 为准
• 必须选择上下文窗口不少于 64K 的模型

8.4 在终端验证基础聊天

执行：

hermes 

进入 CLI 后，输入一条简单消息，例如：

你好，请简单介绍一下你自己。 

如果能正常回复，说明：

• Hermes 安装成功
• 模型配置成功
• API Key 正常

只有这一步成功后，再继续接飞书。

你有两种方式创建飞书应用。

9.1 推荐方式：使用 Hermes 向导自动创建

执行：

hermes gateway setup 

然后：

• 选择 Feishu / Lark
• 使用飞书手机客户端扫码

根据官方文档，若扫码创建流程可用，Hermes 会：

• 自动创建机器人应用
• 自动配置正确权限
• 自动保存凭据

这是最省事的方式，优先推荐。

9.2 备用方式：手动在飞书开放平台创建

如果自动创建不可用，则手动创建。

飞书开放平台地址：

• 中国飞书：https://open.feishu.cn/
• 国际版 Lark：https://open.larksuite.com/

手动创建步骤如下。

9.2.1 创建应用

在开放平台中：

• 新建一个应用
• 为应用设置名称和图标

9.2.2 获取凭据

在应用的 Credentials & Basic Info 页面，记录：

• App ID
• App Secret

后续 Hermes 需要用到这两个值。

9.2.3 开启 Bot 能力

在应用功能中启用 Bot。

如果没有开启 Bot，Hermes 无法作为机器人接收和发送消息。

飞书接入 Hermes 有两种模式：

• WebSocket 模式
• Webhook 模式

10.1 推荐：WebSocket 模式

对于你当前场景，强烈建议使用 WebSocket 模式。

原因：

• 本地 Win11 + WSL2 非常适合 WebSocket
• 不需要公网地址
• 不需要内网穿透
• 不需要 HTTPS 证书
• 官方推荐笔记本、工作站、私有服务器使用此模式

配置值为：

FEISHU_CONNECTION_MODE=websocket 

10.2 什么情况下才选 Webhook 模式

只有在以下条件都满足时，才建议用 Webhook：

• 你已经有可公网访问的服务地址
• 你已经能处理 HTTPS、反向代理、端口暴露
• 你需要飞书主动回调你的 HTTP 接口

对于本地 Win11 测试或个人部署，通常没有必要。

你可以用两种方式配置。

11.1 推荐方式：交互式配置

执行：

hermes gateway setup 

然后按提示填写飞书相关参数。

这是最推荐的方式，因为 Hermes 会把值写到正确位置。

11.2 手动配置 ~/.hermes/.env

如果你想手动配置，在 WSL2 中编辑：

nano ~/.hermes/.env 

填入以下内容：

FEISHU_APP_ID=cli_xxx FEISHU_APP_SECRET=secret_xxx FEISHU_DOMAIN=feishu FEISHU_CONNECTION_MODE=websocket FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy FEISHU_HOME_CHANNEL=oc_xxx 

各字段说明如下。

11.2.1 FEISHU_APP_ID

飞书应用的 App ID。

11.2.2 FEISHU_APP_SECRET

飞书应用的 App Secret。

不要泄露这个值，它等同于应用密钥。

11.2.3 FEISHU_DOMAIN

用于区分中国飞书和国际 Lark。

可选值：

• feishu：中国飞书
• lark：国际版 Lark

如果你用的是国内飞书，填写：

FEISHU_DOMAIN=feishu 

11.2.4 FEISHU_CONNECTION_MODE

推荐填写：

FEISHU_CONNECTION_MODE=websocket 

11.2.5 FEISHU_ALLOWED_USERS

用于限制哪些飞书用户可以使用该机器人。

例如：

FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy 

官方明确建议：生产环境一定要设置 allowlist。

否则任何能接触到该机器人入口的人，都可能调用你的 Hermes。

11.2.6 FEISHU_HOME_CHANNEL

用于指定默认的 Home Chat，便于：

• 定时任务回传
• 跨平台通知回传

这个值也可以后续在飞书里通过命令设置，不一定要提前写。

飞书群聊场景下，官方默认策略是：

FEISHU_GROUP_POLICY=allowlist 

意思是：

• 只允许白名单用户在群里触发机器人
• 且通常需要 @机器人 才会处理消息

建议你保留默认安全策略。

如果你要显式配置，可以在 ~/.hermes/.env 里加入：

FEISHU_GROUP_POLICY=allowlist 

官方说明：

• open：开放
• allowlist：仅白名单
• disabled：禁用群聊处理

对于带终端能力的 Agent，不要轻易设成开放模式。

完成模型配置和飞书配置后，执行：

hermes gateway 

该命令会以前台方式启动消息网关。

启动后你应该看到 Hermes 进入监听状态，然后你就可以去飞书里给机器人发消息。

验证顺序建议如下：

14.1 私聊机器人测试

先做最简单验证：

• 在飞书里找到你的机器人
• 发一条简单消息

例如：

你好，请回复“飞书接入成功”。 

如果机器人能回复，说明链路已打通。

14.2 群聊测试

如果你把机器人拉进群里，请注意：

• 很多情况下需要 @机器人
• 如果你设置了 FEISHU_ALLOWED_USERS，只有白名单用户能触发

14.3 设置 Home Chat

在飞书聊天窗口中发送：

/set-home 

这样可以把当前会话设为默认通知通道。

如果你想最快跑通，建议至少满足以下配置。

15.1 WSL2 已安装

确认 Ubuntu 运行在 WSL2。

15.2 Hermes 已安装

执行以下命令不报错：

hermes --help hermes doctor 

15.3 模型已配置

以下命令能成功进入对话：

hermes 

15.4 飞书凭据已配置

至少包含：

FEISHU_APP_ID=... FEISHU_APP_SECRET=... FEISHU_DOMAIN=feishu FEISHU_CONNECTION_MODE=websocket 

15.5 白名单已配置

建议至少配置：

FEISHU_ALLOWED_USERS=ou_xxx 

下面是最常见的故障点。

16.1 问题：Windows 里直接装 Hermes 失败

原因：

• 官方不支持原生 Windows

解决：

• 改到 WSL2 里安装和运行

16.2 问题：Hermes 能启动，但飞书不回消息

优先排查以下几项：

• 模型是否已经配置成功
• FEISHU_APP_ID 是否正确
• FEISHU_APP_SECRET 是否正确
• 是否选择了正确的 FEISHU_DOMAIN
• 是否把自己加入了 FEISHU_ALLOWED_USERS
• 是否在群里正确 @机器人

16.3 问题：CLI 能聊，飞书不能聊

通常说明：

• Hermes 主程序正常
• 飞书侧配置不完整

重点排查：

• Bot 能力是否已开启
• 飞书应用是否配置正确
• Gateway 是否确实在运行

16.4 问题：Gateway 启动时报缺少依赖

官方文档里的相关报错包括：

• lark-oapi not installed
• websockets not installed; websocket mode unavailable
• aiohttp not installed; webhook mode unavailable

如果你是通过官方安装脚本正常安装，通常不会缺。

如果真的缺，可以在当前 Hermes 环境里补装对应依赖。

但更推荐的处理方式是：

• 先执行 hermes doctor
• 再考虑重新执行官方安装流程

16.5 问题：白名单导致自己也不能用

如果你设置了：

FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy 

那只有这些 open_id 的用户能调用机器人。

如果你的账号不在里面，机器人就不会处理你的消息。

16.6 问题：Webhook 配置失败

如果你使用 Webhook 模式，还可能遇到：

• 验证 token 不匹配
• 签名校验失败
• 本地地址不可达

对于你的本地 Win11 场景，最简单的方案就是：

• 不要用 Webhook
• 直接用 WebSocket

官方推荐的恢复顺序非常实用。

如果你感觉状态混乱，可以按这个顺序检查：

hermes doctor hermes model hermes setup hermes sessions list hermes --continue hermes gateway status 

对于你当前场景，我建议重点使用这几个命令：

hermes doctor hermes model hermes gateway setup hermes gateway 

如果你后续需要用到更复杂的飞书能力，还要注意额外配置。

18.1 交互式卡片

如果你要使用飞书卡片按钮等能力，官方文档说明需要完成三步：

1. 在事件订阅中添加 card.action.trigger
2. 在 Bot 功能中启用 Interactive Card
3. 如果是 Webhook 模式，还要配置 Message Card Request URL

如果缺少这些步骤，点击卡片按钮可能会报错。

18.2 更细粒度群权限控制

Hermes 支持在 config.yaml 中配置更细粒度的群规则，例如：

• 某些群允许白名单用户触发
• 某些群只允许管理员触发
• 某些群完全禁用

如果你后续需要团队化运营，再去细化这部分即可。

结合你的环境，我建议使用以下方案。

19.1 推荐方案

• 系统：Windows 11
• 运行环境：WSL2 Ubuntu
• Hermes 连接飞书方式：WebSocket
• 模型提供商：OpenRouter 或你已有可用 API 的平台
• 运行方式：先前台跑通，再考虑常驻

19.2 不推荐方案

当前阶段不建议你直接做：

• 原生 Windows 安装 Hermes
• 本地 Webhook 暴露公网
• 一开始就把群权限放开
• 模型都没跑通就先接飞书

你可以严格按下面顺序操作。

阶段 1：跑通 Hermes 本体

1. 安装 WSL2
2. 安装 Hermes
3. 执行 hermes model
4. 执行 hermes
5. 确认终端对话正常

阶段 2：接飞书

1. 执行 hermes gateway setup
2. 选择 Feishu / Lark
3. 优先使用扫码自动创建应用
4. 选择 WebSocket 模式
5. 配置白名单
6. 执行 hermes gateway
7. 到飞书里测试收发消息

阶段 3：增强稳定性

1. 设置 /set-home
2. 收紧 FEISHU_ALLOWED_USERS
3. 视需要增加群策略
4. 长期运行时再考虑 WSL 常驻或 Linux 服务器化

下面给你一份最小命令流程，方便照着执行。

21.1 Windows 管理员 PowerShell

wsl --install -d Ubuntu 

21.2 WSL2 Ubuntu

sudo apt update sudo apt install -y curl git curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash source ~/.bashrc hermes doctor hermes model hermes 

确认终端聊天没问题后，再执行：

hermes gateway setup hermes gateway 

这是一个适合飞书 WebSocket 的最小示例。请把值替换成你自己的。

FEISHU_APP_ID=cli_xxxxxxxxxx FEISHU_APP_SECRET=secret_xxxxxxxxxx FEISHU_DOMAIN=feishu FEISHU_CONNECTION_MODE=websocket FEISHU_ALLOWED_USERS=ou_xxxxxxxxxx FEISHU_GROUP_POLICY=allowlist 

如果你还想配置 Home Chat：

FEISHU_HOME_CHANNEL=oc_xxxxxxxxxx 

这个部分非常重要。

23.1 一定要设置白名单

建议至少设置：

FEISHU_ALLOWED_USERS=ou_xxx 

因为 Hermes Agent 具备工具调用能力，安全边界不能放太松。

23.2 不要泄露 .env

以下文件不要提交到公开仓库，也不要发给别人：

• ~/.hermes/.env

因为里面可能包含：

• 飞书密钥
• 模型 API Key
• 其他敏感令牌

23.3 群聊里尽量用 @机器人

这样更可控，也符合官方默认设计。

Hermes 官方文档提供了 Linux 和 macOS 的服务管理方式。

但你当前是 Win11 + WSL2，建议分两步走：

24.1 第一阶段

先手动运行：

hermes gateway 

确认功能和权限都没问题。

24.2 第二阶段

如果你后续想长期在线，更推荐：

• 迁移到 Linux 云服务器
• 或认真配置 WSL2 的常驻与自启动策略

对个人本地使用来说，先跑通比“服务化”更重要。

如果你的目标是：

• 在 Win11 本地快速部署
• 接入飞书
• 尽快可用

那最优路径就是：

• WSL2 + Ubuntu
• Hermes 官方安装脚本
• 先配置模型并验证 CLI
• 再用 hermes gateway setup 接飞书
• 飞书选择 WebSocket 模式
• 配置 FEISHU_ALLOWED_USERS 做安全收敛

这是当前官方文档下，最适合你的落地方案。

建议你马上按下面顺序执行：

1. 在 Win11 安装 WSL2
2. 在 Ubuntu 里安装 Hermes
3. 先执行 hermes model
4. 先执行 hermes 验证能聊天
5. 再执行 hermes gateway setup
6. 选择 Feishu / Lark
7. 选择 WebSocket
8. 启动 hermes gateway
9. 去飞书里私聊机器人测试