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_a965ae2a3688594ccc）
App Secret （如 WpzMqXxI35356467567fhdfzgfvBvkX）

2.3 开通应用能力

左侧菜单 → 添加应用能力 → 开通 机器人

2.4 配置权限

左侧菜单 → 权限管理，搜索并开通以下权限：

权限名称	用途
`im:chat:readonly`	读取群组信息
`im:message`	发送单聊消息
`im:message.group`	发送群聊消息
`contact:user.base:readonly`	读取用户基本信息

2.5 发布应用

左侧菜单 → 版本管理与发布 → 创建版本 → 填写更新说明 → 发布

首次发布需要企业管理员审批，请联系管理员通过。

三、服务器端安装 Hermes

3.1 一键安装

bash 复制代码

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

安装完成后，确认命令可用：

bash 复制代码

which hermes
# 输出示例: /home/ubuntu/.local/bin/hermes

3.2 配置飞书对接

bash 复制代码

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:               # 可选，用于定时通知

配置完成后，验证凭证文件：

bash 复制代码

cat ~/.hermes/.env

应包含以下内容：

ini 复制代码

FEISHU_APP_ID=cli_xxxxxxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxx
FEISHU_DOMAIN=feishu
FEISHU_CONNECTION_MODE=websocket
FEISHU_ALLOW_ALL_USERS=true

四、安装飞书依赖

Hermes 安装脚本使用 uv 管理虚拟环境，后续安装依赖必须使用 uv pip：

bash 复制代码

cd ~/.hermes/hermes-agent

# 安装飞书 SDK 和 WebSocket 库
uv pip install lark-oapi websockets

# 验证安装
/home/ubuntu/.hermes/hermes-agent/venv/bin/python -c "import lark_oapi; print('ok')"

⚠️ 注意：不要用标准 pip install，否则包会安装到用户目录而非 venv，导致 Hermes 找不到。

五、部署为 systemd 系统服务

5.1 解决 sudo 找不到 hermes 命令

bash 复制代码

sudo ln -s /home/ubuntu/.local/bin/hermes /usr/local/bin/hermes

5.2 安装系统服务

bash 复制代码

sudo hermes gateway install --system --run-as-user ubuntu

5.3 加载飞书凭证到 systemd

systemd 服务默认不自动读取用户目录的 .env，需显式配置：

bash 复制代码

sudo systemctl edit hermes-gateway.service

粘贴以下内容：

ini 复制代码

[Service]
EnvironmentFile=/home/ubuntu/.hermes/.env

5.4 启动服务

bash 复制代码

sudo systemctl daemon-reload
sudo systemctl enable --now hermes-gateway.service

5.5 验证运行状态

bash 复制代码

sudo systemctl status hermes-gateway.service

正常应显示：

复制代码

Active: active (running) since Mon 2026-04-27 08:43:06 UTC

查看实时日志：

bash 复制代码

sudo journalctl -u hermes-gateway.service -f

六、服务管理命令速查

bash 复制代码

# 启动
sudo systemctl start hermes-gateway.service

# 停止
sudo systemctl stop hermes-gateway.service

# 重启
sudo systemctl restart hermes-gateway.service

# 查看状态
sudo systemctl status hermes-gateway.service

# 查看最近 50 条日志
sudo journalctl -u hermes-gateway.service -n 50

# 实时跟踪日志
sudo journalctl -u hermes-gateway.service -f

# 开机自启
sudo systemctl enable hermes-gateway.service

# 取消开机自启
sudo systemctl disable hermes-gateway.service

七、常见问题排查

现象	原因	解决方案
`sudo: hermes: command not found`	npm 全局包不在 root PATH	`sudo ln -s /home/ubuntu/.local/bin/hermes /usr/local/bin/hermes`
`lark-oapi not installed`	依赖未安装	`cd ~/.hermes/hermes-agent && uv pip install lark-oapi`
`Defaulting to user installation`	使用了标准 `pip`	改用 `uv pip install`
`FEISHU_APP_ID/SECRET not set`	systemd 未加载 `.env`	`sudo systemctl edit` 添加 `EnvironmentFile=/home/ubuntu/.hermes/.env`
服务反复重启 `status=1/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/.env：

ini 复制代码

FEISHU_ALLOW_ALL_USERS=false
FEISHU_ALLOWED_USERS=ou_xxxxxxxx,ou_yyyyyyyy

修改后重启服务生效：

bash 复制代码

sudo systemctl restart hermes-gateway.service

文档整理时间：2026-04-27

基于 Hermes 最新版本实际部署经验