1. 为什么 Windows 跑 Hermes Agent 接飞书总卡在 WebSocket
很多人第一次在 Windows 上折腾 Hermes Agent 接飞书，卡点几乎一模一样：飞书后台事件订阅填了回调地址，本地却没有公网 IP，消息永远推不过来；或者用 WSL2 装好了 Hermes，网关一启动就报连接超时，日志里反复刷 WebSocket handshake failed。我自己在 Windows 11 + WSL2 Ubuntu 22.04 上把这条链路完整跑通过一遍，核心结论是：别碰回调模式，直接用 WebSocket 长连接，让 Hermes 主动连飞书，这样不需要备案域名、不需要端口映射，家用宽带也能稳定收发消息。
Hermes Agent 是一个带长记忆、可自进化的 AI 智能体，本地命令行能对话，接上飞书之后就能在飞书里私聊机器人、自动问答、执行任务。它适合谁？适合想在 Windows 上低成本搭一个私人办公助手的人，比如写周报、查资料、跑代码片段，全在飞书聊天框里完成。这篇指南交付的是可复制的 WSL2 网络配置、飞书事件订阅参数、TaoToken 接入 settings.json / config.toml 骨架，以及连通性验证动作，目标是让你一次跑通消息收发链路。
需要提前说明的是，Hermes 本身要调用大模型接口，如果你手上有多个模型 Key，管理起来会很乱。我这边统一走 TaoToken 的 API 通道，一个 Key 覆盖多种模型，配置进 Hermes 之后不用来回改环境变量。下面从环境准备开始，一步步来。
2. 前置准备：WSL2、Hermes 与 TaoToken 通道
2.1 WSL2 环境确认
Windows 上跑 Hermes，我建议直接用 WSL2 的 Ubuntu，不要用原生 Windows 终端，原因是 Hermes 的网关脚本和 systemd 服务在 Linux 下更顺。先确认 WSL2 装好：
wsl --list --verbose输出里 VERSION 那一列必须是 2。如果是 1，执行wsl --set-version Ubuntu 2升级。接着进 Ubuntu 终端，确认网络能通：
curl -I https://taotoken.net/api返回 200 或 401 都算通，401 只是没带 Key。如果这里就超时，先解决 WSL2 的 DNS，编辑/etc/resolv.conf加上nameserver 8.8.8.8再试。
2.2 安装 Hermes Agent
在 WSL2 里装 Hermes，按官方脚本走：
curl -fsSL https://hermes-agent.dev/install.sh | bash source ~/.bashrc hermes --version能打印版本号就说明装好了。如果提示 command not found，检查~/.local/bin是否在 PATH 里。
2.3 TaoToken 前置：拿 Key 与确认通道
Hermes 要调模型，得先有可用的 API 通道。我统一用 TaoToken，原因是它把多家模型的调用收敛到一个 Key 上，Hermes 的配置文件里只写一个 base_url 和一个 api_key 就行，换模型不用改代码。
操作路径：打开 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite 登录后创建一个 API Key，复制出来形如sk-xxxx。这个 Key 后面要写进 Hermes 的 settings.json。
注意：Key 只在创建时完整显示一次，先存到密码管理器里，别直接贴在聊天窗口。
TaoToken 的 API 基地址是https://taotoken.net/api，注意这个地址不带任何查询参数，配置时原样填入即可。如果你不确定模型名怎么写，可以先去模型对话页面确认一下可用模型列表：https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite
3. 飞书开放平台：创建应用与事件订阅参数
3.1 创建企业自建应用
打开飞书开放平台，登录后新建「企业自建应用」，名字随意，比如「Hermes机器人」。创建完进入「凭证与基础信息」，记下两个值：
| 参数 | 说明 | 示例 |
|---|---|---|
| App ID | 应用唯一标识 | cli_a1b2c3d4e5f6g7h8 |
| App Secret | 应用密钥 | xxxxxxxxxxxxxxxx |
这两个值后面在hermes gateway setup里要依次录入，抄的时候注意别带空格。
3.2 批量导入权限
进入「权限管理」，点「批量导入权限」，粘贴下面这段 JSON：
{ "scopes": { "tenant": [ "contact:user.base:readonly", "im:chat", "im:chat:read", "im:chat:update", "im:message", "im:message.group_at_msg:readonly", "im:message.p2p_msg:readonly", "im:message:send_as_bot", "im:resource", "contact:contact.base:readonly" ], "user": [] } }导入后确认权限列表里im:message:send_as_bot和im:message.p2p_msg:readonly都在。少一个都会导致机器人收不到私聊消息。
3.3 添加机器人能力与事件订阅
左侧「添加应用能力」里选「机器人」并添加。然后进「事件与回调」，订阅方式选长连接，保存。这一步是关键，选长连接就不需要填回调地址，也就绕开了公网 IP 的问题。
接着点「添加事件」，在「消息与群组」分类里勾选im.message.receive_v1（接收消息），确定。最后进「版本管理与发布」，创建版本、填版本号、发布。发布后权限才真正生效。
4. 可复制配置：Hermes 网关与 TaoToken 接入骨架
4.1 执行网关配置命令
回到 WSL2 终端：
hermes gateway setup平台列表里选feishu。接下来按提示录入：
- 飞书 App ID：粘贴刚才记的
- 飞书 App Secret：粘贴
- 连接模式：选WebSocket 长连接
- 配对审批：选 DM 配对审批
- 群组回复：选仅被 @ 时回复
- 家庭聊天 ID：可留空
- 安装为 systemd 服务：输入
y
WebSocket 模式的意义在于，Hermes 主动向飞书建立长连接，你的电脑不需要公网 IP，也不需要端口映射，家用网络下就能跑。
4.2 settings.json 接入 TaoToken
Hermes 的模型配置在~/.hermes/settings.json。用编辑器打开，把模型段改成走 TaoToken：
{ "model": { "provider": "openai-compatible", "base_url": "https://taotoken.net/api", "api_key": "sk-你的TaoToken密钥", "model_name": "claude-sonnet-4-20250514", "max_tokens": 4096, "temperature": 0.7 }, "gateway": { "platform": "feishu", "mode": "websocket" } }base_url一定写https://taotoken.net/api，不要多加斜杠或路径。model_name按你在 TaoToken 模型列表里看到的实际名称填。
4.3 config.toml 补充网关参数
部分版本的 Hermes 用~/.hermes/config.toml管理网关，骨架如下：
[gateway] platform = "feishu" mode = "websocket" auto_reconnect = true reconnect_interval = 5 [gateway.feishu] app_id = "cli_你的AppID" app_secret = "你的AppSecret" event_key = "im.message.receive_v1" [model] base_url = "https://taotoken.net/api" api_key = "sk-你的TaoToken密钥" model_name = "claude-sonnet-4-20250514"auto_reconnect = true建议打开，WSL2 偶尔网络抖动，自动重连能省不少事。
5. 验证请求：从启动网关到飞书收到回复
5.1 启动网关并看日志
hermes gateway start hermes gateway status hermes logs gateway -f日志里出现飞书网关已连接、WebSocket 已就绪、监听消息中三行，说明长连接建立成功。如果卡在connecting，往下看第 6 节的排查。
5.2 用户授权配对
打开飞书，搜索你创建的应用，发一条「你好」。机器人会返回一个配对码，回到终端执行：
hermes pairing approve feishu 你的配对码提示「已允许该用户与机器人对话」即授权成功。
5.3 连通性验证动作
先验证模型通道是否通，直接在终端问一句：
hermes chat "用一句话说明你现在用的是哪个模型"如果返回正常内容，说明 TaoToken 通道没问题。再回飞书发「帮我写一段 Python 读取 CSV 的代码」，机器人能流式回复，整条链路就通了。我实测下来，从发消息到首字回复大概 1 到 2 秒，取决于模型本身。
6. 本篇常见错排查
6.1 飞书发消息机器人不回复
先查三处：权限是否全部导入并发布版本；事件订阅是否选的长连接且勾了im.message.receive_v1；用户是否执行过hermes pairing approve。这三处任一缺失都会导致消息石沉大海。
6.2 WebSocket handshake failed
日志里刷这个错，多半是 WSL2 的 DNS 或时间不同步。执行：
sudo hwclock -s curl -I https://open.feishu.cn时间偏差超过几分钟，飞书的签名校验会直接拒绝。DNS 问题就改/etc/resolv.conf。
6.3 Hermes 提示 Key 错误
核对settings.json里的api_key是否完整，base_url是否为https://taotoken.net/api。常见坑是复制 Key 时带上了换行或空格。可以这样快速验证：
curl https://taotoken.net/api/v1/models \ -H "Authorization: Bearer sk-你的密钥"返回模型列表就说明 Key 有效，问题在 Hermes 配置侧。
6.4 能收到消息但不回答
这通常是模型调用失败。看hermes logs gateway -f里有没有 401 或 429。401 是 Key 无效，429 是额度或频率限制。确认 TaoToken 账户余额正常，再检查model_name是否拼写正确。
6.5 WSL 重启后连不上
WSL2 重启后 systemd 服务不一定自动拉起，执行：
hermes gateway status hermes gateway start如果经常重启，确认安装时选了 systemd 服务，并执行systemctl --user enable hermes-gateway。
7. 长期编码与 Agent 场景的通道选择
如果你只是偶尔在飞书里问问题，上面的配置就够了。但如果你打算把 Hermes 当长期编码助手或 Agent 用，比如让它持续跑任务、维护记忆、频繁调用模型，那单次按量计费的 Key 管理起来会比较碎。这种场景我建议看一下 Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite
它的思路是把编码类高频调用打包，配合 Hermes 的长记忆做持续任务时，不用每次担心额度。配置方式不变，还是把base_url指向https://taotoken.net/api，只是 Key 换成 Coding Plan 对应的那个。
另外，如果你在接入过程中遇到报错，或者想确认某个模型名是否可用，可以直接在模型对话页面发一条测试消息：https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite 这样能快速区分是通道问题还是 Hermes 配置问题。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite 里面有各语言的调用示例，对着改 settings.json 就行。
最后提醒一句：WSL2 里跑网关时，终端窗口别关，关了长连接就断。用 systemd 服务方式启动可以后台常驻，开机自启，这是长期使用最省心的方式。
