1. 为什么要在本地跑一个飞书机器人飞书机器人这东西很多人第一反应是「得有个公网服务器吧」。其实不一定。Hermes Agent 提供了一条 WebSocket 长连接通道你的笔记本、家里的迷你主机、公司内网的开发机只要能出网就能把机器人跑起来不需要公网 IP不需要在路由器上做端口映射也不需要折腾反向代理和证书。这套方案适合谁我梳理了三类一是想给自己团队做个内部问答助手的开发者二是想拿飞书当入口接大模型做实验的 AI 爱好者三是手上已经有 Hermes Agent、想把它接到日常办公 IM 里的同学。整个链路的核心就三件事飞书开放平台建应用拿 App ID 和 App Secret、Hermes 侧用hermes gateway setup初始化网关、把大模型通道指向一个统一的 Key 服务。这里有个容易被忽略的点Hermes Agent 本身要调用大模型才能回复消息而模型通道的配置如果每个项目都单独申请 Key、单独改 base_url维护起来很碎。我这次的做法是把模型调用统一走 TaoToken 的 API 通道一个 Key 覆盖对话模型Hermes 的 config 里只填一次后面换模型、加 Agent 都不用再动凭证。官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 两个地址分工不同后面配置环节会具体说填哪个。下面按「飞书侧配置 → Hermes 网关初始化 → 模型通道接入 → 消息链路验证 → 排障」的顺序走一遍每一步都给可复制的配置和命令。你照着做大概十五到二十分钟能跑通私聊对话。2. 飞书开放平台建应用、加机器人、订阅事件2.1 创建企业自建应用并添加机器人能力打开飞书开放平台 https://open.feishu.cn/app 点「创建企业自建应用」填个名字比如 Hermes选个图标确认创建。进到应用详情页后左侧找到「添加应用能力」选「机器人」点添加。这一步做完你的应用才具备收发消息的身份。接着是权限。进「权限管理」用「批量导入」把下面这段 JSON 粘进去比一个个勾选快得多{ scopes: { tenant: [ im:message:send_as_bot, im:message.p2p_msg:readonly, im:message.group_at_msg:readonly, im:message.group_msg, im:message:readonly, im:resource, im:chat:read, im:chat.members:read ], user: [] } }几个权限的作用值得说清楚im:message:send_as_bot是机器人主动发消息的通行证没有它机器人只能收不能回im:message.p2p_msg:readonly管私聊读取im:message.group_at_msg:readonly管群里被 的消息im:resource是拿图片、文件这类富媒体资源用的。少一个对应场景就哑火。2.2 事件订阅是整条链路的关键进「事件与回调」→「事件配置」点「添加事件」搜索 receive把「接收消息 v2.0」事件标识im.message.receive_v1加进去。这一步是整个配置里最容易漏的。飞书是事件推送模型用户发消息飞书得知道推给谁。只有订阅了这个事件飞书才会把消息推给你的应用Hermes 才「听得到」。顺手在「回调配置」里把「卡片回传交互」也加上后面如果要做按钮、表单这类交互卡片会用到现在加省得回头再改。2.3 拿凭证并发布版本进「凭证与基础信息」把 App ID 和 App Secret 复制出来先放记事本里等下终端要用。然后点「创建版本」→ 保存 → 申请发布。企业自建应用如果只给内部用不勾「外部」一般能直接发布勾了外部要走管理员审批。发布成功后飞书客户端里就能看到这个机器人了。注意应用没发布之前事件不会真正推送到你的服务机器人也不会出现在聊天列表里。很多人卡在「配置都对但没反应」八成是版本没发。3. Hermes 网关初始化hermes gateway setup 全流程3.1 启动配置向导回到终端确认 Hermes 装好了hermes --version有版本号输出就继续。然后启动网关配置向导hermes gateway setup向导会列出可选的平台找到「飞书 / Feishu」输入对应编号通常是 10回车。Linux 和 macOS 用方向键选Windows 建议在 WSL 里操作步骤一致只是.env路径不同。3.2 填凭证、选 WebSocket 模式向导问凭证来源时选「手动输入已有的 App ID 和 App Secret」把刚才复制的两个值分别粘进去。接着会问连接模式这里选 WebSocket。为什么是 WebSocket 而不是 Webhook对比一下就清楚模式需要公网 IP需要配防火墙适用场景WebSocket不需要不需要本地开发、内网部署Webhook需要需要云服务器、生产环境WebSocket 模式下是你的本地服务主动连出去飞书顺着这条长连接把消息推回来所以内网机器也能跑。后面的选项一路回车用默认值等网关重启完成。3.3 验证连接状态看到类似下面的输出说明长连接建起来了[feishu] Gateway connected via WebSocket [feishu] Listening for messages...如果没看到先别急着改配置用状态命令确认一下hermes gateway status4. 接入 TaoToken 统一 Keyconfig.toml 与 settings.json 骨架4.1 为什么模型通道要单独配网关通了只代表「消息能进来」机器人要「回得出话」还得有可用的大模型。Hermes 的模型配置集中在config.toml凭证类信息放.env或settings.json。我建议把模型调用统一指向 TaoToken 的 API 通道好处是一个 Key 管所有模型换模型只改 model 字段不用重新申请凭证。先去控制台建一个 Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 在 API Keys 页面创建https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。拿到形如sk-开头的字符串妥善保存。4.2 config.toml 骨架在 Hermes 配置目录一般是~/.hermes/config.toml里模型段这样写[model] provider openai-compatible base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY model claude-sonnet-4-20250514 max_tokens 4096 temperature 0.7 [gateway] platform feishu mode websocketbase_url填https://taotoken.net/api注意这里不带任何查询参数就是纯 API 入口。api_key_env表示 Key 从环境变量读不硬编码在配置文件里这样配置可以进版本库、可以分享Key 不会泄露。4.3 settings.json 与 .env凭证放.envLinux/macOS 在~/.hermes/.envWindows 在%LOCALAPPDATA%\hermes\.envTAOTOKEN_API_KEYsk-你的Key GATEWAY_ALLOW_ALL_USERStrue API_SERVER_KEYa12345678GATEWAY_ALLOW_ALL_USERStrue是让网关接受未单独授权的飞书用户本地自用阶段先开着等稳定了再收紧。API_SERVER_KEY是网关本地 API 的密钥随便设个字符串即可。如果你的 Hermes 版本用settings.json管理网关参数骨架如下{ gateway: { platform: feishu, mode: websocket, allow_all_users: true, log_level: info }, model: { base_url: https://taotoken.net/api, api_key_env: TAOTOKEN_API_KEY } }改完重启网关hermes gateway restart5. 验证请求从发消息到看到回复5.1 先验模型通道再验消息链路排障的顺序很重要先确认模型能通再确认消息能通。如果模型不通机器人收到了消息也回不出来你会误以为是飞书配置问题。用前台模式跑网关日志实时可见hermes gateway run另开一个终端直接对模型通道发一个最小请求curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: 只回复两个字收到}] }返回体里choices[0].message.content是「收到」说明 Key 和通道都没问题。这一步过了再回飞书给机器人发消息。5.2 私聊与群聊分别测私聊直接发「你好」前台终端应该能看到入站事件和出站请求的日志飞书里几秒内收到回复。群聊测试要把机器人拉进群然后 它提问比如「Hermes 帮我写个 Python 快排」。群聊走的是im.message.group_at_msg这条权限如果私聊通、群聊不通基本就是权限没批或者事件没订阅全。想验证模型切换是否生效可以在飞书里问「你现在用的是什么模型」或者在 config 里把model换成另一个重启后再问一次对比回复风格。模型对话的在线体验入口在 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 可以先用它确认某个模型名拼写正确再写进 config省得在终端反复试错。6. 本篇常见错排查6.1 重启网关报 User not authorized现象是网关起不来或者起来后拒绝服务日志里出现未授权字样。原因是 Hermes 默认只允许已授权用户对话而飞书用户还没被登记。解决办法是在.env末尾补两行GATEWAY_ALLOW_ALL_USERStrue API_SERVER_KEYa12345678Linux/macOS 一条命令追加echo -e GATEWAY_ALLOW_ALL_USERStrue\nAPI_SERVER_KEYa12345678 ~/.hermes/.envWindows 用记事本打开%LOCALAPPDATA%\hermes\.env手动加。改完hermes gateway restart。6.2 机器人不回复消息按这个顺序查别跳步hermes gateway status tail -50 ~/.hermes/logs/gateway.log hermes model第一条看网关活没活第二条看日志里有没有入站事件第三条确认模型配置读到了。如果日志里压根没有入站事件问题在飞书侧检查im.message.receive_v1是否订阅、权限是否审批通过、应用版本是否已发布。三者缺一消息都进不来。6.3 WebSocket 频繁断开Hermes 有自动重连短暂断开不用管。如果长时间连不上先hermes gateway restart。想彻底省心把它装成后台服务hermes gateway install这样开机自启、断连自恢复不用每次手动拉。日志里如果反复出现权限相关报错回飞书开放平台确认权限都启用了、审批都过了部分权限需要管理员点确认。6.4 模型返回 401 或 404401 一般是 Key 没读到检查.env里变量名和 config 里api_key_env是否一致以及改完有没有重启网关。404 多半是base_url写错了正确值是https://taotoken.net/api不要多加/v1之外的路径也不要把控制台地址填进去。接入细节和参数说明可以对照文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。如果你后面打算长期跑编码类 Agent、或者把 Hermes 接到更多自动化流程里可以考虑 Coding Plan 这类按周期计费的方案比单次调用更好控成本https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。Claude Code 相关的接入说明在 https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 有需要可以一并看。最后留个实操习惯调通之后别急着关前台终端先让它跑一晚上第二天看日志里有没有异常重连或超时。我自己的经验是本地网络抖动导致的断连比配置错误更常见装成后台服务加自动重连比反复手动重启省事得多。