部署教程

VPS 部署 Hermes Agent：安装、飞书接入与备份恢复

发布于 2026-10-03

在 Debian VPS 安装 Hermes Agent，以普通用户和 systemd 运行网关，配置飞书长连接、白名单与备份恢复。

让 Hermes 在 VPS 上持续接收消息

把 Hermes 放到 VPS 上，最常见的用法是：在飞书里发一句任务，服务器负责查资料、处理文件、执行脚本，做完把结果发回来。电脑关机后，消息入口和定时任务还能继续运行。

安装之后还有几件事要确认：SSH 断开后进程还在不在，群里哪些人能调用它，命令审批按钮能不能收到回调，以及换一台服务器后，积累的记忆和技能还能不能找回来。

这次用了和上一篇 OpenClaw VPS 教程相同的 Debian 测试机，安装 Hermes Agent 0.21.5，对应 v2026.9.24。走的是普通用户安装、systemd 托管、管理页通过 SSH 隧道访问的路线。模型 API Key 和飞书应用凭据没有接入，因此实测覆盖安装、网页访问、服务重启和本机独立目录恢复；飞书消息收发按对应版本的官方说明配置，不能算已完成真人聊天测试。

先确定要让它做什么，再买服务器

Hermes 的记忆、技能和会话记录保存在自己的数据目录里。它可以把任务经验整理成技能，下一次再加载使用；这不会替你训练或更新底层大模型。模型能否正确调用工具、遵守要求，仍然取决于你选用的模型和任务本身。

如果只是想在飞书里问问题，机器主要承担网关和工具进程，模型推理交给外部 API。要它开浏览器、处理音视频、同时执行多个任务，内存和磁盘需求就会增加。打算在 VPS 本地运行大模型，则是另一套选型，不能沿用下面的配置建议。

对于个人使用，我会从 2 核、4 GB 内存、20 GB 以上 SSD 起步。这是给安装、网页构建和少量工具任务留余量的购买建议，并非官方最低配置。只跑消息入口可以尝试更小的机器，但不建议拿“空闲时能启动”推算浏览器任务也够用。

选地域时，检查服务器能否同时访问模型服务、GitHub/Python 软件源和飞书接口。你到 VPS 的 SSH 延迟只是其中一段；机器人回复一条消息，还要经过模型调用、工具执行和消息发送。看中某条建站线路后，也要确认它能访问你选的模型服务。

可以从本站的雨云购买入口或 Evoxt 购买入口比较当前套餐。雨云推荐码是 KuZhuJi。先看机房、内存、续费规则和退款条件，不必为了机器人额外追求家宽 IP；这里也不把某个套餐写成所有模型服务都能使用的保证。

查看雨云云服务器 ↗

注册推荐码：KuZhuJi

查看 Evoxt 虚拟机 ↗

VPS 租金与模型调用费用分开计算。把程序放到自己的服务器上，聊天内容仍可能随模型请求发往服务商，搜索、浏览器等外部工具也可能有各自的费用。先配置一套能用的模型和必要工具，其他能力用到时再加。

用普通用户安装，别让机器人拿着管理员权限干活

以下命令适用于 Debian/Ubuntu，由有 sudo 权限的管理员执行。测试机的精简系统最初缺 Git，补上以后又在编译工具检查处中断，因此把基础依赖一次装好：

bash；使用前请核对本文前提。如内容超出，可左右滑动，键盘使用方向键或 Home/End 查看。

仅复制文本，不会执行。

sudo apt-get update
sudo apt-get install -y git curl xz-utils build-essential libatomic1 less
sudo useradd --create-home --shell /bin/bash hermes
sudo -iu hermes

后面的安装、模型配置、飞书配置和备份，都在 hermes 用户下操作。不要给这个账户额外加 sudo 权限。使用本地终端后端时，Hermes 执行的命令具有这个用户的文件访问权限，适合放在独立测试环境里，别和生产数据库、网站管理密钥混在一个账户下。

本文固定安装脚本和代码版本，方便复现这次测试。先下载脚本，查看后再运行：

bash；使用前请核对本文前提。如内容超出，可左右滑动，键盘使用方向键或 Home/End 查看。

仅复制文本，不会执行。

curl -fL \
  https://raw.githubusercontent.com/NousResearch/hermes-agent/v2026.9.24/scripts/install.sh \
  -o /tmp/hermes-install.sh
less /tmp/hermes-install.sh
bash /tmp/hermes-install.sh \
  --branch v2026.9.24 \
  --skip-browser \
  --skip-computer-use \
  --non-interactive
export PATH="$HOME/.local/bin:$PATH"
hermes --version

--non-interactive 会跳过需要输入的设置环节，安装完成后仍要配置模型和消息渠道。两个 --skip 参数用于暂缓 Playwright/Chromium 和 Computer Use 驱动的安装，不代表已经验证浏览器工具可用。脚本仍会准备所需的 Node 环境。

如果要直接采用当时的最新安装流程，可以使用官方安装页提供的入口。但它会随项目更新，不要一边运行最新脚本，一边照着旧版的虚拟环境路径修复依赖。本文后续涉及 venv 的命令都针对 v2026.9.24。

官方安装页 ↗

这个版本在普通用户下的目录关系如下：

左右滑动查看全部字段

路径	放什么
~/.local/bin/hermes	命令入口
~/.hermes/hermes-agent/	代码和这个版本的 Python 虚拟环境
~/.hermes/config.yaml	模型、工具、网关等配置
~/.hermes/.env	模型 Key、飞书凭据和环境变量
~/.hermes/memories/	持久记忆
~/.hermes/skills/	技能文件
~/.hermes/state.db	会话等状态数据

需要快速文件检索或语音处理时，再由管理员安装 ripgrep、ffmpeg。测试中，普通账户无法自行安装系统软件，脚本明确提示文件检索会使用备用方式、部分音频能力受限。安装结束的成功提示并不等于所有可选工具都已准备好。

上述布局和参数可以对照该发布版的安装说明与安装脚本。

该发布版的安装说明 ↗

安装脚本 ↗

模型先在终端里跑通

在 hermes 用户下运行配置命令：

bash；使用前请核对本文前提。如内容超出，可左右滑动，键盘使用方向键或 Home/End 查看。

仅复制文本，不会执行。

hermes model
hermes tools
hermes doctor

用 hermes model 选择服务商和模型，再用 hermes tools 开启需要的工具。自己的兼容接口，也按向导填写实际的 Base URL、模型 ID 和凭据。别只确认 Key 保存成功，还要启动 hermes，发一条简单消息，确认服务商接受请求、返回内容正常，再尝试一个小工具任务。

终端里就报模型不存在、鉴权失败或额度不足，先解决模型服务；终端能回答、飞书不回，再去检查消息接入。

工作目录也最好单独设置：

bash；使用前请核对本文前提。如内容超出，可左右滑动，键盘使用方向键或 Home/End 查看。

仅复制文本，不会执行。

mkdir -p "$HOME/work"
hermes config set terminal.backend local
hermes config set terminal.cwd "$HOME/work"

terminal.backend local 表示命令在这台 VPS 上执行。工作目录方便收拢任务文件，但它本身不是文件系统沙箱；这个用户能读取的其他目录，终端命令也可能访问。文件写入保护和命令审批能减少误操作，不能替代操作系统权限或隔离环境。

需要 Docker 终端后端时，先阅读终端后端配置和Docker 部署说明。Hermes 程序在容器里运行，与工具命令在 Docker 沙箱里执行，是两种不同的部署方式。也不要为了省事就把 Docker socket 交给一个存放生产密钥的机器人账户。

终端后端配置 ↗

Docker 部署说明 ↗

飞书接入要配两处回调

最省事的入口是：

bash；使用前请核对本文前提。如内容超出，可左右滑动，键盘使用方向键或 Home/End 查看。

仅复制文本，不会执行。

hermes gateway setup

选择 Feishu / Lark。该版本支持扫码创建应用；如果当前租户或创建流程不能使用扫码方式，再走手动输入。首次配置飞书可能需要补装 Python 依赖，本文测试另外安装并确认加载了 lark-oapi 1.6.8。

对于本文固定的版本，想提前准备依赖，可以执行：

bash；使用前请核对本文前提。如内容超出，可左右滑动，键盘使用方向键或 Home/End 查看。

仅复制文本，不会执行。

cd ~/.hermes/hermes-agent
~/.hermes/bin/uv pip install \
  --python venv/bin/python \
  -e '.[feishu]'

这一步只安装 SDK 和相关包，不会自动替你创建飞书应用、发布版本或完成连接。

手动创建企业自建应用

打开飞书开放平台，创建企业自建应用，启用机器人能力，记下 App ID 和 App Secret。Hermes 需要的是应用凭据，群自定义机器人的 webhook 地址不能代替它们。

飞书开放平台 ↗

按照这个版本的飞书接入说明，消息、附件和群信息相关的基础权限包括：

飞书接入说明 ↗

左右滑动查看全部字段

权限	用途
im:message	接收和读取消息
im:message:send_as_bot	以机器人身份发送消息
im:resource	获取用户发来的图片、文件和音频
im:chat	访问群聊信息
im:chat:readonly	读取群列表与成员信息

官方还列出 im:message.reactions:readonly、admin:app.info:readonly、contact:user.id:readonly，分别用于表情事件、机器人身份识别和用户 ID 解析。按要使用的功能添加，权限最终能否生效还受租户审批影响。普通聊天不必顺手开通云文档编辑或整盘文件访问。

事件订阅和卡片回调分开配置

推荐使用长连接 WebSocket。连接由 VPS 主动发起，无须为收消息购买域名，也无须把管理页端口开放到公网。

飞书后台有两个不同的页签，都要看：

事件配置：选择使用长连接，订阅 im.message.receive_v1，用来接收消息。
回调配置：同样选择长连接，添加 card.action.trigger，用来接收卡片按钮点击。机器人设置中还要确认交互卡片能力可用。

第二项容易漏掉。聊天文字能收发，并不表示命令审批卡片也能工作。如果“允许一次”“拒绝”等按钮点击后没反应，或出现 200340，先检查回调配置及应用版本有没有发布。把 card.action.trigger 当普通消息事件添加，不能替代卡片回调配置。

长连接保存时如果提示应用尚未建立连接，先让配置好凭据的 Hermes 网关在前台运行，再回飞书后台保存。完成权限、事件和回调设置后，创建并发布应用版本；企业应用可能还需要管理员审批。最后确认自己在应用的可用范围内，再打开机器人聊天。

让自己的账号先通过白名单

向导保存的设置可以在 ~/.hermes/.env 中核对。下面展示的是需要检查的字段，cli_xxx、secret_xxx、ou_xxx 都要换成实际值；编辑已有文件时保留原来的模型配置，不要整份覆盖：

ini；使用前请核对本文前提。如内容超出，可左右滑动，键盘使用方向键或 Home/End 查看。

仅复制文本，不会执行。

FEISHU_APP_ID=cli_xxx
FEISHU_APP_SECRET=secret_xxx
FEISHU_DOMAIN=feishu
FEISHU_CONNECTION_MODE=websocket
FEISHU_ALLOWED_USERS=ou_xxx
FEISHU_GROUP_POLICY=allowlist
FEISHU_REQUIRE_MENTION=true
FEISHU_ALLOW_ALL_USERS=false
GATEWAY_ALLOW_ALL_USERS=false

中国版飞书用 FEISHU_DOMAIN=feishu，国际版 Lark 用 lark。FEISHU_ALLOWED_USERS 填当前应用对应的用户 Open ID，通常以 ou_ 开头；多个用户用英文逗号分隔。不要拿 oc_ 开头的群聊 ID 填用户白名单，也不要照抄另一个应用里查到的 Open ID。

私聊第一次遇到未授权用户时，可以使用配对流程：让自己的账号给机器人发消息，按返回的配对码在服务器上批准。

bash；使用前请核对本文前提。如内容超出，可左右滑动，键盘使用方向键或 Home/End 查看。

仅复制文本，不会执行。

hermes pairing list
hermes pairing approve feishu 配对码

群聊还会经过飞书适配器的群策略检查。默认 allowlist 下，空的 FEISHU_ALLOWED_USERS 会挡住普通用户的群消息；个人部署直接填自己的 Open ID 更容易检查。私聊已配对，不代表任何群里、任何用户都获得了相同权限。

不要用 GATEWAY_ALLOW_ALL_USERS=true 来临时“修好”白名单问题。那会放宽网关的用户授权；群策略、@ 提及和应用可用范围仍各自有作用，也可能让排错变得更混乱。

把机器人加入群以后，用真正的 @机器人发一条短消息。本文保留 FEISHU_REQUIRE_MENTION=true，避免机器人把所有群消息都当任务。config.yaml 中的 group_sessions_per_user: true 可以按发送者分开群会话历史，但同一个操作系统账户执行工具时，仍会共享它能访问的文件，不能把会话分开当成多租户隔离。

私聊授权的实际检查顺序以网关安全说明为准；群消息的筛选则可以核对飞书适配器代码。这也解释了为什么仅看“长连接已建立”还不能确认机器人能回复你。

网关安全说明 ↗

飞书适配器代码 ↗

SSH 断开后，由 systemd 接着运行

先用前台模式排错：

bash；使用前请核对本文前提。如内容超出，可左右滑动，键盘使用方向键或 Home/End 查看。

仅复制文本，不会执行。

hermes gateway run

观察日志，确认模型和飞书配置没有明显错误。前台模式随终端退出而结束；准备长期运行时，先按 Ctrl+C 停掉它，再安装后台服务，不要同时运行两个处理同一应用消息的网关。

回到管理员账户，为 hermes 用户启用 linger：

bash；使用前请核对本文前提。如内容超出，可左右滑动，键盘使用方向键或 Home/End 查看。

仅复制文本，不会执行。

sudo loginctl enable-linger hermes
sudo -iu hermes
export PATH="$HOME/.local/bin:$PATH"
export XDG_RUNTIME_DIR="/run/user/$(id -u)"
hermes gateway install --start-now --start-on-login
hermes gateway status

这里安装的是用户级 systemd 服务。linger 让用户管理器在没有 SSH 会话时也能保留运行，并支持随系统启动；这次测试确认了服务启用和重启，没有实际重启整台服务器。

日常操作都在同一个 hermes 用户下执行：

bash；使用前请核对本文前提。如内容超出，可左右滑动，键盘使用方向键或 Home/End 查看。

仅复制文本，不会执行。

hermes gateway restart
hermes gateway status
journalctl --user -u hermes-gateway.service -n 80 --no-pager

查看状态时，要同时看进程和渠道连接。测试中，即使没有启用任何消息平台，网关也会继续运行以承载 cron 功能，所以 active (running) 本身不能证明飞书在线，更不能证明模型调用成功。

重启采用优雅退出，可能等待当前任务和清理过程。命令显示正在等待时，先看日志，不要马上再开一个网关。完整管理命令见对应版本的网关说明。

对应版本的网关说明 ↗

管理页通过 SSH 隧道打开

飞书作为日常入口后，管理页主要用来查看状态、日志、配置和会话。它需要单独启动，网关服务运行并不代表网页服务也已运行。

在服务器上的 hermes 用户终端运行：

bash；使用前请核对本文前提。如内容超出，可左右滑动，键盘使用方向键或 Home/End 查看。

仅复制文本，不会执行。

hermes dashboard --host 127.0.0.1 --port 9119 --no-open

首次启动可能构建网页界面，等终端打印可访问地址。在自己的电脑上建立 SSH 隧道，把你的SSH账户@服务器IP 替换成已有的登录方式：

bash；使用前请核对本文前提。如内容超出，可左右滑动，键盘使用方向键或 Home/End 查看。

仅复制文本，不会执行。

ssh -N -L 127.0.0.1:59119:127.0.0.1:9119 你的SSH账户@服务器IP

然后打开 http://127.0.0.1:59119。网页端口留在服务器本机，不需要增加 9119 的公网放行规则。SSH 隧道断开后，浏览器就无法通过这个本地转发访问它。

下面是测试机通过隧道访问的管理页。左侧显示网关 Running，版本是 0.21.5；会话为空，因为这次没有接入模型进行聊天。

通过 SSH 隧道连接的 Hermes Agent 后台 — 测试机后台已通过 SSH 隧道连接。模型和飞书消息收发未在本次测试中验证。

如果确实需要给远程客户端长期提供网页服务，应按官方管理页说明配置受支持的鉴权方式。这个版本的 --insecure 已经是弃用的无效参数，不能拿它当关闭鉴权的办法。

官方管理页说明 ↗

备份的是积累的数据，换机还要安装程序

这台测试机当晚就到期，因此安装完成后还做了备份恢复。机器人用得越久，记忆、技能、会话和凭据越值得保留；重新下载程序，只能拿回一套空的安装。

Hermes 自带完整备份命令。为了便于确认边界，第一次备份可以在没有任务运行时，停下网关，并退出已经打开的管理页服务：

bash；使用前请核对本文前提。如内容超出，可左右滑动，键盘使用方向键或 Home/End 查看。

仅复制文本，不会执行。

hermes gateway stop
hermes dashboard --stop
umask 077
mkdir -p "$HOME/backups"
hermes backup --output "$HOME/backups" --keep 0
hermes gateway start

--output 指向已存在的目录时，会在其中创建带时间戳的 ZIP。--keep 0 表示这次不自动清理旧备份，后续要做轮转再单独安排。观察终端的 Backup complete 和退出状态；如果显示 incomplete，即使 ZIP 已生成，也不能把它当完整备份。

这类备份包含 .env 等凭据文件，要按密钥文件保存。不要放公开 Git 仓库，也不要把 ZIP 当普通附件转发给别人。备份下载到自己的电脑或私有存储后，再检查文件能否解压、能否恢复，放在即将到期的同一台 VPS 上不算已经带走。

换机时，先在新机的独立用户下安装相应版本的 Hermes，把备份传给这个用户，确认没有其他网关同时使用该数据目录，再导入：

bash；使用前请核对本文前提。如内容超出，可左右滑动，键盘使用方向键或 Home/End 查看。

仅复制文本，不会执行。

hermes gateway stop
hermes dashboard --stop
hermes import "$HOME/hermes-backup-待恢复文件.zip"
hermes doctor
hermes gateway status

导入会涉及已有文件的替换，运行前核对文件名和目标账户。不要为了跳过提示而在有现成数据的机器上直接加 --force。导入流程可能尝试恢复网关服务，完成后先查看状态与日志，确认路径、凭据和任务安排，再决定是否启动或重启。

还有三个容易混淆的地方：

hermes backup 是数据备份，不包含 hermes-agent 代码仓库，不能代替新机安装。
hermes profile export 用来导出单个 profile，凭据默认排除。分享 profile 很方便，但拿它做整机恢复会漏掉登录信息。
任务工作目录、外部挂载盘、独立浏览器资料目录及外部服务的数据，应另外检查备份覆盖范围。不要仅凭“完整备份”四个字就认定整台 VPS 的文件都在 ZIP 里。

官方命令使用 SQLite 的安全复制方式处理数据库，可以在运行中备份；本文实际验证的是停下服务后的备份。恢复到同一台服务器的一个新 HERMES_HOME 后，配置和 .env 与原文件一致，手工放入的记忆、技能测试标记保留，恢复出来的数据库通过 quick_check。这次没有跨机器导入，也没有用模型生成一段聊天历史再恢复。

备份的包含项与排除项可以对照CLI 命令参考和迁移 FAQ。

CLI 命令参考 ↗

迁移 FAQ ↗

安装以后，记忆和定时任务怎么用

记忆不是把每一句聊天都塞进一个文件。默认内置记忆保存在 ~/.hermes/memories/MEMORY.md 与 USER.md，会话检索另有数据库记录。技能则是可以检查、修改的文件，适合保存反复使用的任务步骤。

第一次让它记住一个工作目录或写作要求，别只看回复中的“已经记住”。检查文件是否真的出现了对应内容。刚保存的记忆不一定会立刻进入当前会话最初加载的快照；一个任务做完，在飞书里用 /new 开始新任务，比把所有事情塞进一条无限增长的对话更容易管理。

持久记忆说明 ↗

定时任务的结果还需要有明确的投递位置。飞书会话里可用 /set-home 设置 Home Chat，或配置 FEISHU_HOME_CHANNEL=oc_xxx。这里填的是聊天 ID，和用户白名单里的 ou_xxx 用途不同。

刚接入时，可以让它执行一次很短的定时任务，查看任务列表、执行结果，以及飞书里是否收到消息。模型调用会产生费用，不建议拿高频定时任务测试“它是不是活着”。

服务检查与常见故障

测试环境是 Debian 13.7、4 vCPU、约 7.8 GiB 内存、40 GB 系统盘。Hermes 安装在没有 sudo 权限的 hermeslab 用户下，版本 0.21.5，源码修订为 f97608f178d1ffeca59860195ab7da295f7c8e5f。安装器复用了系统 Python 3.13.5，并下载了 Node 26.10.0。

已确认的结果包括：命令入口可用；用户级 systemd 服务启用并运行；重启前后网关 PID 改变，服务重新进入运行状态；管理页只监听本机地址，通过 SSH 隧道可以实际打开；飞书 SDK 安装并能导入；备份恢复保留测试标记、配置和凭据文件结构，4 个恢复后的数据库 quick_check 均为 ok。

网关稳定运行后，约 12 秒内的 6 次 systemd MemoryCurrent 采样平均约 159.4 MiB。这里没有连接消息平台、调用模型或运行任务，管理页也属于另一个进程，这个数只说明本次空闲网关的占用，不能拿来估算完整任务的峰值。

hermes doctor 有一项值得单独看：系统 Python 链接的 SQLite 为 3.46.1，提示 WAL-reset 问题。这次新建数据库的日志显示 Hermes 使用了 journal_mode=DELETE，以避开启用有问题的 WAL。它不是“数据库测试全部没有警告”。SQLite 官方说明列出的修复版本包括 3.51.3，以及回移修复的 3.50.7、3.44.6；修复时要确认 Hermes 实际使用的 Python 链接到的 SQLite，而不是只看系统 sqlite3 命令的版本。已有数据库也不要在其他进程仍持有连接时手动改日志模式。

SQLite 官方说明 ↗

如果部署时卡住，可以按症状查：

左右滑动查看全部字段

现象	先检查什么
安装器提示 Git 或 C++ compiler 不存在	管理员有没有装 git、build-essential；普通用户不能靠自己的权限补系统包
hermes: command not found	当前用户是否正确，~/.local/bin 是否在 PATH 中
systemd 用户服务提示无法连接 bus	linger 是否启用，当前账户及 XDG_RUNTIME_DIR 是否指向该用户的运行目录
网关 Running，飞书仍不回	渠道连接状态、模型配置、用户授权、应用发布与可用范围
私聊能用，群里不回	是否真正 @ 机器人，发送者 Open ID 是否在白名单，群策略是否拒绝
卡片能看到，点击没反应	回调页签有没有 card.action.trigger，回调模式和应用发布版本是否正确
重启后 Key 或会话像丢了	是否换了运行用户、profile 或 HERMES_HOME，是否误读另一个账户的数据目录
备份导入后仍没有模型或飞书回复	程序是否已安装，路径和凭据是否有效，服务有没有恢复，别只检查 ZIP 文件存在

升级前先做一份备份。hermes update 会更新源安装，可能改变运行环境和依赖，不能把本文固定版本的成功记录当成未来版本的验收。升级后重新检查版本、doctor、服务状态，再做一次模型响应和飞书消息测试。

已经装过 OpenClaw，也不用为了尝试 Hermes 先删掉原服务。用独立账户和数据目录做验证；如果要迁移旧配置，可以先用 hermes claw migrate --dry-run 查看范围，再决定哪些数据需要带过来。两套机器人先各自跑通，比同时改模型、平台和部署方式更容易找到问题。