一份从零到用的保姆级教程附带踩坑实录一、什么是 Hermes AgentHermes Agent 是 Nous Research 开源的 AI Agent 框架支持 CLI 和多种消息平台飞书、Telegram、Discord 等。可以对接到 DeepSeek、OpenAI、Anthropic 等任意 LLM 提供商。核心特性跨平台 Gateway — 同一 Agent 通过飞书/Telegram/Discord 等 10 平台使用Provider 无关 — 换模型只需一行命令Skills 系统 — Agent 从经验中学习持久化可复用流程持久化 Memory — 跨会话记住用户偏好和环境细节官方文档https://hermes-agent.nousresearch.com/docs/二、安装 Hermes Agent2.1 一键安装curl-fsSLhttps://hermes-agent.nousresearch.com/install.sh|bash安装完成后会自动创建~/.hermes/目录包含配置文件和 venv。2.2 配置模型以 DeepSeek 为例# 设置 API KeyechoDEEPSEEK_API_KEYsk-your-key-here~/.hermes/.env# 选择模型hermes model在交互界面中选择deepseek作为 Provider选择模型如deepseek-v4-pro。也可以通过命令行hermes configsetmodel.provider deepseek hermes configsetmodel.default deepseek-v4-pro2.3 验证安装hermes doctor# 检查依赖和配置hermes chat-q你好# 测试对话三、接入飞书3.1 创建飞书应用打开 飞书开放平台创建企业自建应用在「凭证与基础信息」页面获取App ID和App Secret3.2 开启机器人能力「应用功能 → 机器人」→ 启用3.3 配置权限进入「权限管理」开通以下权限权限说明必需im:message获取与发送单聊、群组消息✅im:message.p2p_msg:readonly读取用户发给机器人的单聊消息✅im:message.group_at_msg:readonly获取群组中用户机器人消息群聊需要im:message.group_msg获取群组中所有消息敏感权限可选im:resource获取与上传图片或文件资源✅3.4 配置事件订阅「开发配置 → 事件订阅」→ 添加事件im.message.receive_v1注意WebSocket 模式不需要配置回调地址但事件必须订阅3.5 发布应用⚠️这是最容易漏掉的一步添加权限和事件后必须创建新版本并发布才能生效「版本管理与发布 → 创建版本 → 申请发布」不发布的话权限修改不会生效机器人收不到消息。四、配置 Gateway .env编辑~/.hermes/.env# Feishu / LarkFEISHU_APP_IDcli_xxxxxxxxxxxxFEISHU_APP_SECRETyour_app_secretFEISHU_DOMAINfeishu# 飞书用 feishuLark 用 larkFEISHU_CONNECTION_MODEwebsocket# 推荐 WebSocket无需公网 URL# 访问控制开发阶段打开生产环境改用白名单GATEWAY_ALLOW_ALL_USERStrue依赖安装pip3installlark-oapi websockets五、启动 Gateway# 前台启动推荐先这样看日志hermes gateway run# 后台启动WSL 推荐 tmuxtmux new-shermeshermes gateway run# 检查状态hermes gateway status成功启动后日志会显示✓ feishu connected Gateway running with 1 platform(s)六、遇到的问题与解决方案问题 1飞书机器人不回复消息现象Gateway 启动正常飞书显示连接成功但给机器人发消息完全没反应。排查过程检查 Gateway 日志tail-f~/.hermes/logs/gateway.log发现警告No user allowlists configured. All unauthorized users will be denied.原因Gateway 默认拒绝所有用户。需要开放访问或配置白名单。解决在.env中添加GATEWAY_ALLOW_ALL_USERStrue并重启 Gateway。问题 2加了白名单还是没反应现象GATEWAY_ALLOW_ALL_USERStrue已配置重启后仍然收不到消息。排查Gateway 日志没有新的错误。问题指向飞书 App 侧。检查清单✅ 权限管理中im:message已开通✅ 事件订阅已添加im.message.receive_v1❌ 缺少im:message.p2p_msg:readonly权限 — 读取单聊消息需要这个解决添加im:message.p2p_msg:readonly权限。问题 3加了权限还没用现象补上p2p_msg:readonly权限后仍然不回复。原因飞书开放平台上修改权限和事件订阅后必须重新创建版本并发布这是最容易漏的一步。解决版本管理与发布 → 创建版本 → 发布。发布后立即生效。问题 4Cron Job 投递失败现象创建 cron job 设置了deliverall但飞书没收到消息。日志no delivery target resolved for deliverall原因没有配置FEISHU_HOME_CHANNELdeliverall找不到投递目标。解决先在飞书给机器人发一条消息从日志中获取chat_id在.env中设置FEISHU_HOME_CHANNELoc_xxxxxxxxxxxxxx重启 Gateway之后也可以用命令行直接发消息hermes send-tfeishu-f/path/to/message.txt七、验证全链路在飞书中找到你的机器人发送 “你好”应该收到 Hermes 的回复如果 Gateway 日志中有info gateway.run: inbound message: platformfeishu ... info gateway.run: response ready: platformfeishu ...说明全链路通了。八、常用命令速查# 配置hermes model# 选模型hermes config edit# 编辑配置hermes doctor# 健康检查# Gatewayhermes gateway run# 启动hermes gateway status# 状态hermes gateway restart# 重启# Cron定时任务hermescronlist# 查看任务hermescronrunid# 手动触发# 直接推送hermes send-tfeishu消息内容# 推送到飞书hermes send-tfeishu-ffile.txt# 从文件推送# 日志tail-f~/.hermes/logs/gateway.log# Gateway 日志tail-f~/.hermes/logs/agent.log# Agent 日志九、总结接入飞书的关键步骤链路创建飞书应用 → 启用机器人 → 配置权限 → 订阅事件 → ⚠️发布版本 ↓ 配置 .envAPP_ID SECRET ALLOW_ALL_USERS ↓ 安装依赖lark-oapi websockets ↓ 启动 Gateway → 检查日志中 feishu connected ↓ 飞书发消息测试 → 收到回复 ✅最容易被遗漏的三件事im:message.p2p_msg:readonly权限— 单聊必须发布版本— 修改权限/事件后必须重新发布GATEWAY_ALLOW_ALL_USERStrue— 开发阶段必须开放