将 Hermes Agent 部署到阿里云并接入飞书 // Longhui Blog

Hermes Agent 是 Nous Research 开源的个人 AI Agent，可以调用模型与工具，也可以通过消息网关接入飞书。把它部署到阿里云 ECS 后，即使本地电脑关机，仍能在飞书私聊或群聊中使用。

本文采用官方推荐的 WebSocket 长连接：Hermes 从服务器主动连接飞书，不需要域名、HTTPS 证书、Nginx 或公网 Webhook 端口，特别适合个人服务器。

最终架构

飞书客户端
   │ 消息事件
   ▼
飞书开放平台
   ▲ WebSocket 长连接（服务器主动建立）
   │
阿里云 ECS ── Hermes Gateway ── LLM API / Tools

服务器只需要访问公网 443。入方向通常只保留用于运维的 SSH 22 端口，并限制为自己的固定公网 IP。

一、准备阿里云 ECS

个人使用建议从 2 核 2 GB、40 GB 系统盘起步，系统选择 Ubuntu 24.04 LTS。Hermes 本身不在服务器本地运行大模型，主要资源消耗来自 Python 环境、工具和并发会话；如果要运行浏览器或多个 MCP 服务，应增加内存。

安全组建议：

入方向 TCP 22 仅允许自己的公网 IP，不要长期开放 0.0.0.0/0。
WebSocket 模式不需要开放 80、443、8765 等入方向端口。
出方向允许 HTTPS/WSS 443，以访问飞书、模型供应商和软件源。

从本机连接服务器：

ssh <用户名>@<ECS公网IP>

首次连接要核对主机指纹。推荐使用 SSH 密钥而不是密码，并及时安装系统安全更新。

二、准备普通运行用户

不要让拥有工具执行能力的 Agent 长期以 root 身份运行。建议直接使用创建 ECS 时配置的普通运维用户（例如 ecs-user），该用户应能通过 sudo 完成系统维护。Hermes 的配置、记忆和服务都将归属于当前用户。

先安装基础依赖：

sudo apt update
sudo apt install -y curl git ca-certificates build-essential

确认当前不是 root：

whoami

如果实例目前只能使用 root 登录，应先按照阿里云的账户与 SSH 指南创建普通用户、配置密钥和 sudo 权限，再继续安装。不要把 Hermes 安装在 root 的主目录后又切换用户运行，否则配置路径和 systemd 服务会互相错位。

三、安装与初始化 Hermes

使用官方安装脚本：

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
source ~/.bashrc
hermes --version
hermes doctor

安装脚本会管理 Hermes 自己的运行环境。不要在同一个目录里再手动创建一套不受管理的虚拟环境，否则更新和 systemd 服务可能引用到不同的 Python。

运行初始化向导：

hermes setup

根据提示选择 LLM 供应商、模型并填写 API Key。先在终端验证基础对话：

hermes chat -q "只回复：Hermes 服务正常"

如果这里失败，先处理模型 Key、余额或服务器出网问题，不要急着配置飞书。飞书网关最终仍要调用同一套模型配置。

四、创建飞书机器人

最简单的方式是运行：

hermes gateway setup

选择 Feishu / Lark。当前 Hermes 支持扫码创建应用：用飞书手机客户端扫描终端显示的二维码，Hermes 会自动创建机器人、申请所需权限并保存凭据。如果当前租户不允许自动创建，向导会回退到手动输入 App ID 和 App Secret。

手动创建方式

打开飞书开放平台，创建企业自建应用。
在“凭证与基础信息”复制 App ID 和 App Secret。
添加“机器人”应用能力。
在权限管理中添加消息读取、机器人发送、资源访问和群信息等权限。
在事件与回调中选择“使用长连接接收事件”，订阅消息接收事件。
创建版本并发布应用，确保当前测试用户在可用范围内。

Hermes 官方列出的核心权限包括：

im:message
im:message:send_as_bot
im:resource
im:chat
im:chat:readonly

实际控制台可能根据功能拆分更多细粒度权限，应以 hermes gateway setup 的提示和飞书审核结果为准。

五、确认 Hermes 飞书配置

交互向导会把配置保存到 ~/.hermes/。手动配置时，在 ~/.hermes/.env 中加入：

FEISHU_APP_ID=cli_xxxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxx
FEISHU_DOMAIN=feishu
FEISHU_CONNECTION_MODE=websocket

# 生产环境强烈建议设置
FEISHU_ALLOWED_USERS=ou_xxxxxxxxxxxxx

飞书国内版使用 FEISHU_DOMAIN=feishu，Lark 国际版使用 lark。不要把 App Secret 上传到 Git 仓库，并限制配置文件权限：

chmod 600 ~/.hermes/.env

FEISHU_ALLOWED_USERS 填写允许使用机器人的飞书 Open ID，多个值用英文逗号分隔。测试阶段也不要把机器人开放给整个组织；可以先把应用可用范围限制为自己，确认 Open ID 后立即配置白名单。

六、前台启动并联调

先在 SSH 终端以前台方式启动：

hermes gateway

看到飞书连接成功后，在飞书里私聊机器人。私聊消息会直接触发回复；在群聊中默认需要 @机器人。如果需要把当前会话设为定时任务和通知的默认投递位置，在聊天中发送：

/set-home

前台联调通过后按 Ctrl+C 停止，再安装后台服务。

七、使用 systemd 长期运行

阿里云这类无头服务器推荐安装 system 级服务，它不依赖 SSH 登录会话：

sudo hermes gateway install --system
sudo hermes gateway start --system
sudo hermes gateway status --system

实时查看日志：

sudo journalctl -u hermes-gateway -f

如果选择普通用户服务，则必须启用 linger，否则退出 SSH 后用户级 systemd 可能停止：

hermes gateway install
sudo loginctl enable-linger "$USER"
hermes gateway start
journalctl --user -u hermes-gateway -f

服务器只保留一种服务模式即可，不要同时启动 user 与 system 两套网关，否则可能重复消费事件或让状态命令指向错误实例。

八、常见问题

飞书中没有任何回复

依次检查机器人能力是否启用、应用是否已经发布、当前用户是否在可用范围、消息事件是否订阅，以及 Gateway 日志中是否出现 WebSocket 连接成功。群聊必须先 @机器人。

能收到消息但模型不回答

运行 hermes doctor 和终端测试命令，检查模型 API Key、余额、区域网络与 DNS。飞书连接成功只代表消息已经到达 Hermes，不代表上游模型可用。

日志提示 App ID 或 App Secret 无效

确认复制的是同一个应用的凭证，FEISHU_DOMAIN 与国内飞书/Lark 匹配。修改 .env 后重启 Gateway。

退出 SSH 后机器人离线

说明仍在前台运行，或使用了未开启 linger 的用户服务。ECS 推荐使用 sudo hermes gateway install --system。

WebSocket 依赖缺失

先运行 hermes update 与 hermes doctor，再重新执行 hermes gateway setup。不要直接向系统 Python 随意安装包，以免与 Hermes 管理的环境分离。

九、日常维护与安全

定期运行 hermes update，更新后重启 Gateway 并做一次飞书回归测试。
使用 journalctl 观察重连、模型错误和工具执行记录，但不要把含密钥的日志公开。
App Secret 或模型 Key 泄露时立即在对应平台轮换，而不只是修改本地文件。
为工具配置最小权限和命令审批，不让 Agent 读写无关目录。
备份 ~/.hermes/ 中的配置、记忆和自定义技能，备份文件也要加密。
将飞书用户白名单和应用可用范围同时收紧，群聊中避免共享敏感上下文。

WebSocket 模式把部署复杂度降得很低：服务器负责稳定运行，飞书负责消息入口，Hermes Gateway 负责把两端连接起来。真正需要长期关注的不是开放更多端口，而是密钥、用户白名单、工具权限和服务日志。