Hermes 接入飞书（Feishu/Lark）部署文档

一、前置准备一台 Ubuntu 22.04 云服务器建议有公网 IP飞书账号具备「创建企业自建应用」权限服务器已安装curl、bash等基础工具二、飞书应用配置2.1 创建企业自建应用打开 飞书开发者后台点击创建企业自建应用如果有这个提示框则可以一键创建 获取到App ID 与 App Secret 直接跳到第三步安装hermes填写应用名称如hermes和描述上传应用图标240×240 px 以上2.2 获取应用凭证左侧菜单 →凭证与基础信息复制并保存App ID如cli_a965ae2a3688594cccApp Secret如WpzMqXxI35356467567fhdfzgfvBvkX2.3 开通应用能力左侧菜单 →添加应用能力→ 开通机器人2.4 配置权限左侧菜单 →权限管理搜索并开通以下权限权限名称用途im:chat:readonly读取群组信息im:message发送单聊消息im:message.group发送群聊消息contact:user.base:readonly读取用户基本信息2.5 发布应用左侧菜单 →版本管理与发布→ 创建版本 → 填写更新说明 →发布首次发布需要企业管理员审批请联系管理员通过。三、服务器端安装 Hermes3.1 一键安装curl-fsSLhttps://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh|bash安装完成后确认命令可用whichhermes# 输出示例: /home/ubuntu/.local/bin/hermes3.2 配置飞书对接hermes gateway setup按交互提示输入App ID: cli_xxxxxxxxxxxxxxxx App Secret: xxxxxxxxxxxxxxxx Domain: feishu # 国内版用 feishu国际版用 larksuite Connection Mode: websocket # 选择 WebSocket 模式无需公网回调 Open DM access: yes # 允许私聊 Group chats: yes # 允许群聊需 机器人 Home chat ID: # 可选用于定时通知配置完成后验证凭证文件cat~/.hermes/.env应包含以下内容FEISHU_APP_IDcli_xxxxxxxxxxxxxxxx FEISHU_APP_SECRETxxxxxxxxxxxxxxxx FEISHU_DOMAINfeishu FEISHU_CONNECTION_MODEwebsocket FEISHU_ALLOW_ALL_USERStrue四、安装飞书依赖Hermes 安装脚本使用uv管理虚拟环境后续安装依赖必须使用uv pipcd~/.hermes/hermes-agent# 安装飞书 SDK 和 WebSocket 库uv pipinstalllark-oapi websockets# 验证安装/home/ubuntu/.hermes/hermes-agent/venv/bin/python-cimport lark_oapi; print(ok)⚠️ 注意不要用标准pip install否则包会安装到用户目录而非 venv导致 Hermes 找不到。五、部署为 systemd 系统服务5.1 解决 sudo 找不到 hermes 命令sudoln-s/home/ubuntu/.local/bin/hermes /usr/local/bin/hermes5.2 安装系统服务sudohermes gatewayinstall--system--run-as-user ubuntu5.3 加载飞书凭证到 systemdsystemd 服务默认不自动读取用户目录的.env需显式配置sudosystemctl edit hermes-gateway.service粘贴以下内容[Service] EnvironmentFile/home/ubuntu/.hermes/.env5.4 启动服务sudosystemctl daemon-reloadsudosystemctlenable--nowhermes-gateway.service5.5 验证运行状态sudosystemctl status hermes-gateway.service正常应显示Active: active (running) since Mon 2026-04-27 08:43:06 UTC查看实时日志sudojournalctl-uhermes-gateway.service-f六、服务管理命令速查# 启动sudosystemctl start hermes-gateway.service# 停止sudosystemctl stop hermes-gateway.service# 重启sudosystemctl restart hermes-gateway.service# 查看状态sudosystemctl status hermes-gateway.service# 查看最近 50 条日志sudojournalctl-uhermes-gateway.service-n50# 实时跟踪日志sudojournalctl-uhermes-gateway.service-f# 开机自启sudosystemctlenablehermes-gateway.service# 取消开机自启sudosystemctl disable hermes-gateway.service七、常见问题排查现象原因解决方案sudo: hermes: command not foundnpm 全局包不在 root PATHsudo ln -s /home/ubuntu/.local/bin/hermes /usr/local/bin/hermeslark-oapi not installed依赖未安装cd ~/.hermes/hermes-agent uv pip install lark-oapiDefaulting to user installation使用了标准pip改用uv pip installFEISHU_APP_ID/SECRET not setsystemd 未加载.envsudo systemctl edit添加EnvironmentFile/home/ubuntu/.hermes/.env服务反复重启status1/FAILURE存在残留前台进程或配置错误sudo pkill -f hermes后重新排查ModuleNotFoundError: No module named lark_oapi包安装到了错误 Python 版本路径确认使用uv pip install --python /home/ubuntu/.hermes/hermes-agent/venv/bin/python八、飞书端验证在飞书搜索你的机器人名称如fae的hermes进入私聊发送任意消息机器人应正常回复表示 Gateway 运行正常如需限制访问用户修改~/.hermes/.envFEISHU_ALLOW_ALL_USERSfalse FEISHU_ALLOWED_USERSou_xxxxxxxx,ou_yyyyyyyy修改后重启服务生效sudosystemctl restart hermes-gateway.service文档整理时间2026-04-27基于 Hermes 最新版本实际部署经验