部署自己的智能伙伴——基于Rocky linux的Hermes-Agent 原生安装手册

 💡系统: Rocky Linux 9.x      部署方式: 原生安装（uv + Python 3.11）      消息通道: 飞书 WebSocket 长连接      大模型: DeepSeek / Kimi / OpenAI 兼容      版本: Hermes Agent 0.16.0

📋 目录

1. [环境准备]2. [安装 Hermes]3. [配置大模型与飞书]4. [飞书开放平台配置]5. [systemd 服务配置]6. [验证与排查]7. [常见问题]8. [日常运维]9. [升级指南]10. [目录结构]11. [关键经验]

 环境准备

 系统更新与依赖安装

sudo dnf update -ysudo dnf install -y git curl wget vim \\    gcc gcc-c++ make \\    libffi-devel openssl-devel bzip2-devel zlib-devel sqlite-devel \\    python3.11 python3.11-pip python3.11-develpython3.11 --version   # 确认 3.11.x

安装 uv 包管理器

curl -LsSf <https://astral.sh/uv/install.sh> | shsource$HOME/.local/bin/envuv --version

处理 SELinux ⚠️

Rocky Linux 9 默认启用 SELinux，必须处理，否则 systemd 无法读取 .env

# 查看 SELinux 状态getenforce   # 输出 Enforcing 表示启用# 给 Hermes 目录添加正确标签sudo chcon -R -t usr_t /home/.hermes/sudo semanage fcontext -a -t bin_t "/home/.hermes/hermes-agent/.venv/bin/hermes" 2>/dev/null || truesudo restorecon -v /home/.hermes/hermes-agent/.venv/bin/hermes

安装 Hermes

创建目录并上传源码

下载源码包：GitHub - NousResearch/hermes-agent: The agent that grows with you · GitHub^[1]

mkdir -p /home/.hermescd /home/.hermes# 上传 hermes-agent 源码包到 /home/.hermes/ 并解压unzip hermes-agent-main.zipmv hermes-agent-main hermes-agent# 最终结构：# /home/.hermes/# └── hermes-agent/#     ├── pyproject.toml#     ├── src/#     └── ...

创建虚拟环境并安装

cd /home/.hermes/hermes-agentuv venv --python 3.11source .venv/bin/activateuv pip install -e .

配置环境变量

cat >> ~/.bashrc << 'EOF'export PATH="/home/.hermes/hermes-agent/.venv/bin:$PATH"export HERMES_HOME="/home/.hermes"export PYTHONPATH="/home/.hermes/hermes-agent"EOFsource ~/.bashrc

配置大模型与飞书

⚠️ 强烈建议使用 hermes setup 交互式配置，不要手动编辑 .env

运行配置向导

hermes setup

 配置选项

配置完成后检查

# 确认 .env 已生成cat /home/.hermes/.env# 确认权限正确chmod 644 /home/.hermes/.env

飞书开放平台配置

登录 飞书开放平台^[2]，进入你的应用：

添加机器人能力

左侧导航 → 添加应用能力 → 选择 机器人 → 点击添加

开通权限（必须全部开通）

进入 权限管理 → 搜索并勾选：

配置事件订阅

• 事件与回调 → 订阅方式选择 长连接
• 添加事件 → 勾选 im.message.receive_v1

发布应用

版本管理与发布 → 创建版本 → 填写版本号 → 申请发布

企业应用需管理员审批

获取凭证

凭证与基础信息 → 记录 App ID 和 App Secret

systemd 服务配置

sudo tee /etc/systemd/system/hermes-agent.service << 'EOF'[Unit]Description=Hermes AgentAfter=network-online.targetWants=network-online.target[Service]Type=simpleUser=rootWorkingDirectory=/home/.hermes/hermes-agentEnvironment="PATH=/home/.hermes/hermes-agent/.venv/bin:/usr/local/bin:/usr/bin:/bin"Environment="HERMES_HOME=/home/.hermes"Environment="PYTHONPATH=/home/.hermes/hermes-agent"EnvironmentFile=/home/.hermes/.envExecStart=/home/.hermes/hermes-agent/.venv/bin/hermes gateway runRestart=alwaysRestartSec=5TimeoutStopSec=300sStandardOutput=journalStandardError=journal[Install]WantedBy=multi-user.targetEOFsudo systemctl daemon-reloadsudo systemctl enable --now hermes-agent

TimeoutStopSec=300s

 必须 ≥ 210s，否则 Hermes 排水时可能会被 SIGKILL

验证与排查

查看服务状态

sudo systemctl status hermes-agent --no-pager

查看实时日志

sudo journalctl -u hermes-agent -f

✅ 成功标志：

[Lark] [INFO] connected to wss://msg-frontier.feishu.cn/ws/v2...

飞书测试

1. 在飞书搜索机器人，发送消息（如"你好"）
2. 观察日志是否有 im.message.receive_v1 事件
3. 机器人应回复消息

配置中文回复

echo'HERMES_SYSTEM_PROMPT="请始终使用中文回复。"' >> /home/.hermes/.envsudo systemctl restart hermes-agent

常见问题

日常运维

升级指南

cd /home/.hermes/hermes-agentgit pull --recurse-submodules  # 或重新上传源码source .venv/bin/activateuv pip install -e .sudo systemctl restart hermes-agent

目录结构

/home/.hermes/├── .env                          # 环境变量配置├── hermes-agent/                 # 源码目录│   ├── .venv/                    # Python 虚拟环境│   ├── pyproject.toml│   └── ...├── skills/                       # 学习的技能（自动创建）├── memories/                     # 持久记忆（自动创建）├── sessions/                     # 对话历史（自动创建）├── logs/                         # 运行日志（自动创建）└── node/                         # Node.js 运行时（自动安装）

关键经验

1. 不要用 root 以外的用户运行，避免权限混乱
2. 必须用 hermes setup 配置，手动编辑 .env 容易格式错误
3. SELinux 必须处理，否则 systemd 无法读取文件
4. TimeoutStopSec ≥ 300s，避免 Hermes 被 SIGKILL
5. 飞书权限必须全部开通，且变更后必须重新发布应用
6. 残留进程必须清理，否则报 Gateway already running

📅 文档整理时间：2026-06-17

💡 基于实际部署踩坑经验编写

参考资料

本文使用 Notion Nice 排版一键生成