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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 登录后创建一个 API Key复制出来形如sk-xxxx。这个 Key 后面要写进 Hermes 的 settings.json。注意Key 只在创建时完整显示一次先存到密码管理器里别直接贴在聊天窗口。TaoToken 的 API 基地址是https://taotoken.net/api注意这个地址不带任何查询参数配置时原样填入即可。如果你不确定模型名怎么写可以先去模型对话页面确认一下可用模型列表https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite3. 飞书开放平台创建应用与事件订阅参数3.1 创建企业自建应用打开飞书开放平台登录后新建「企业自建应用」名字随意比如「Hermes机器人」。创建完进入「凭证与基础信息」记下两个值参数说明示例App ID应用唯一标识cli_a1b2c3d4e5f6g7h8App 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 服务输入yWebSocket 模式的意义在于Hermes 主动向飞书建立长连接你的电脑不需要公网 IP也不需要端口映射家用网络下就能跑。4.2 settings.json 接入 TaoTokenHermes 的模型配置在~/.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-20250514auto_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 Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite它的思路是把编码类高频调用打包配合 Hermes 的长记忆做持续任务时不用每次担心额度。配置方式不变还是把base_url指向https://taotoken.net/api只是 Key 换成 Coding Plan 对应的那个。另外如果你在接入过程中遇到报错或者想确认某个模型名是否可用可以直接在模型对话页面发一条测试消息https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 这样能快速区分是通道问题还是 Hermes 配置问题。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 里面有各语言的调用示例对着改 settings.json 就行。最后提醒一句WSL2 里跑网关时终端窗口别关关了长连接就断。用 systemd 服务方式启动可以后台常驻开机自启这是长期使用最省心的方式。