Hermes接入飞书保姆级教程：打造全天候AI私人助理
通过Hermes工具以WebSocket模式将大模型接入飞书，无需公网回调地址。步骤包括创建飞书企业自建应用、获取凭证、开通机器人与消息权限、配置事件订阅、发布应用，再在服务器安装依赖并设置环境变量，最后注册系统服务启动，即可实现全天候AI助手。
想在飞书中嵌入一个24小时在线、随叫随到的AI助手？这一想法看似遥远，实际操作并不复杂。本指南将详细讲解如何使用 Hermes 工具，通过 WebSocket 模式将大模型无缝接入飞书。关键是无需配置公网回调地址，大幅简化流程。
前置准备工作（Prerequisites）
动手前，请确认以下资源已准备就绪，避免中途受阻：
- 云服务器： 一台拥有公网IP的机器（如 Ubuntu），用于长期稳定运行服务。
- 环境要求： 服务器已安装 Python 和包管理工具（本教程主要使用轻量级工具
uv）。 - 飞书权限： 需拥有飞书账号，并具备“创建企业自建应用”的权限（通常由管理员授予）。
一、在飞书开发者后台创建并配置应用
1.1 创建企业自建应用
打开 飞书开发者后台，登录后点击“创建企业自建应用”。为应用命名、填写描述，确认创建即可。
1.2 获取应用凭证（App ID / App Secret）
创建应用后，在左侧菜单找到“凭证与基础信息”。此处可获取 App ID 和 App Secret。请妥善保存，它们是应用的“身份证”与“密码”，切勿泄露至非测试环境。
1.3 开通机器人能力与消息权限
在左侧菜单找到“添加应用能力”，开启“机器人”能力。
接着进入“权限管理”页面，点击“开通权限”，搜索“获取与发送单聊、群组消息”，勾选并确认开通。若缺少该权限，机器人将无法收发消息。
1.4 配置事件订阅
为使机器人响应消息，需配置事件通知。在左侧“事件与回调” → “添加事件”中，勾选“消息与群组”下的“接收消息”事件即可。
1.5 创建版本并发布
完成上述配置后，必须发布才能生效。进入“版本管理与发布”，点击“创建版本”，填写版本详情并保存，最后点击“确认发布”。不发布则所有设置无效。
二、服务器端环境准备与依赖安装
飞书侧配置完成后，切换至云服务器。首先进入 Hermes 安装目录，使用 uv 安装飞书相关依赖：lark-oapi 和 websockets。
在终端中执行以下命令：
cd ~/.hermes/hermes-agentuv pip install lark-oapi websockets
三、配置 Hermes 环境变量
接下来将飞书凭证告知 Hermes。推荐使用交互式引导进行配置，操作简便。在终端运行：
hermes gateway setup
按提示逐步操作：
- 在应用列表中选择 Feishu / Lark。
- 输入之前复制的 App ID，按回车。
- 输入 App Secret（终端默认不显示输入内容，直接复制粘贴后按回车即可）。
- 遇到
Domain和Connection mode提示时，直接按回车使用默认值。 - Allowed user IDs： 强烈建议填写您自己的飞书 Open ID，这样仅您本人能使用该机器人，避免被他人滥用。
- Home chat ID： 暂时留空，直接按回车。待机器人启动后，在飞书中私聊它或将其拉入群聊，然后发送命令
/set-home。Hermes 接收后会将此聊天窗口设为“主阵地”，用于接收定时任务和报警通知。
四、注册系统服务与启动
配置最后一步，终端会询问“是否安装网关为系统服务？”，选择“是”。根据部署场景选择：
- 安装在个人笔记本（非 7×24 小时运行）：选第一项。
- 安装在云服务器/VPS 上，需全天候运行：选第二项。
接着按提示执行以下两条命令，注册并启动服务：
sudo hermes gateway install --system --run-as-user ubuntusudo hermes gateway start --system
看到成功提示后，即可在飞书中发送消息进行测试。机器人应已在线。
五、常见问题与排错（FAQ）
实际操作中可能遇到一些常见问题，现列出解决方法，助您少走弯路。
Q1：执行注册启动命令时，报错 sudo 可执行文件或 hermes 找不到，怎么办？
这是因为 sudo 提权后默认路径可能无法找到个人环境中安装的 hermes 或 uv。解决办法是使用 $(which uv) 明确指定执行环境：
- 先切换至项目目录：
cd ~/.hermes/hermes-agent - 然后执行：
sudo $(which uv) run hermes gateway install --system --run-as-user ubuntusudo $(which uv) run hermes gateway start --system
Q2：不想使用交互式配置，或事后需要手动修改深层参数，如何操作？
可直接编辑主目录下的 .env 文件：~/.hermes/.env。找到或添加以下内容：
FEISHU_APP_ID=你的_App_IDFEISHU_APP_SECRET=你的_App_SecretFEISHU_DOMAIN=feishuFEISHU_CONNECTION_MODE=websocket# 【强烈建议配置】你的飞书 Open ID，用于限制只有你可以使用该机器人# FEISHU_ALLOWED_USERS=ou_xxxxxx
修改后需重启系统服务。
结语
至此，大模型的核心能力已成功接入飞书。接下来，您可以为其配置个性化工作流：定时抓取指定网站、推送监控日志报警，或充当智能问答知识库。立即着手搭建属于您自己的高效工作助手吧！
