Hermes Deployer — 服务器部署与运维 Skill#

概述#

Hermes Agent 是 Nous Research 开源的自我改进 AI Agent，支持接入微信、企微、Telegram、Discord 等平台，通过 Gateway 模式在服务器上 24/7 运行。

本 Skill 覆盖从零部署到日常运维的全流程。

前提条件#

项目要求操作系统Ubuntu 22.04+ / Debian 12+Python3.11+ （推荐 3.12）内存≥ 1GB（轻量应用服务器即可）网络需要访问 GitHub、PyPI、LLM APISSH 访问需要能 SSH 到目标服务器

安装流程#

Phase 1: 环境准备#

bash

# 1. 确认 Python 版本
python3 --version  # 需要 3.11+

# 2. 安装系统依赖
sudo apt update && sudo apt install -y python3-venv python3-pip git nodejs npm

# 3. 克隆 hermes-agent
cd /home/$USER
git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

# 4. 创建 venv 并安装
python3 -m venv venv
source venv/bin/activate
pip install -e .

# 5. 验证安装
hermes --version

Phase 2: 配置 LLM Provider#

Hermes 支持多种 LLM provider。 推荐方式是 provider: "custom" + 环境变量。

创建 ~/.hermes/.env

bash

mkdir -p ~/.hermes

cat > ~/.hermes/.env << 'ENV'
# === LLM Provider ===
# 方式一：OpenAI 兼容接口（腾讯云 LKEAP、DeepSeek、智谱 等）
OPENAI_API_KEY=sk-your-api-key-here
OPENAI_BASE_URL=https://api.lkeap.cloud.tencent.com/v3

# 方式二：智谱 AI 原生（免费额度）
# GLM_API_KEY=your-glm-api-key

# 方式三：Anthropic
# ANTHROPIC_API_KEY=sk-ant-xxx

# === 平台配置（按需启用）===
# -- 微信 iLink --
# WEIXIN_ACCOUNT_ID=xxx@im.bot
# WEIXIN_TOKEN=xxx@im.bot:token
# WEIXIN_BASE_URL=https://ilinkai.weixin.qq.com
# WEIXIN_CDN_BASE_URL=https://novac2c.cdn.weixin.qq.com/c2c
# WEIXIN_DM_POLICY=open
# WEIXIN_GROUP_POLICY=open
# WEIXIN_HOME_CHANNEL=user_openid@im.wechat
# GATEWAY_ALLOW_ALL_USERS=true

# -- Telegram --
# TELEGRAM_BOT_TOKEN=xxx
# TELEGRAM_ALLOWED_USERS=user_id
# TELEGRAM_HOME_CHANNEL=user_id
ENV

创建 ~/.hermes/config.yaml

yaml

# Hermes Agent Configuration

model:
  default: "glm-5"           # 模型名
  provider: "custom"          # 使用 custom provider
  base_url: "https://api.lkeap.cloud.tencent.com/v3"  # API 地址

permissions:
  mode: bypassPermissions     # 服务器部署建议 bypass

# 模型别名（可选，方便在聊天中用 /model flash 切换）
model_aliases:
  flash:
    model: glm-4-flash
    provider: zai
  think:
    model: glm-z1-flash
    provider: zai

# 消息平台
platforms:
  weixin:
    enabled: true
    extra:
      dm_policy: "open"
      group_policy: "open"
  # wecom:
  #   enabled: true
  #   extra:
  #     bot_id: "your-bot-id"
  #     secret: "your-bot-secret"
  #     websocket_url: "wss://openws.work.weixin.qq.com"
  #     dm_policy: "open"
  #     group_policy: "open"

# System prompt
system_prompt: |
  你是一个有用的 AI 助手。

# 技能系统
skills:
  auto_create: true
  auto_improve: true

# 记忆系统
memory:
  enabled: true
  provider: local

context:
  memory_char_limit: 20000
  user_char_limit: 3000

Phase 3: 测试运行#

bash

# 前台运行测试（Ctrl+C 停止）
cd /home/$USER/hermes-agent
./venv/bin/hermes gateway run -v

确认看到：

• ✓ weixin connected（或其他平台）
• Gateway running with N platform(s)
• 手机上发消息能正常收到回复

Phase 4: 创建 systemd 服务#

bash

sudo tee /etc/systemd/system/hermes-gateway.service > /dev/null << 'SVC'
[Unit]
Description=Hermes Agent Gateway
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=$USER
Group=$USER
WorkingDirectory=/home/$USER/hermes-agent
ExecStart=/home/$USER/hermes-agent/venv/bin/hermes gateway run --replace
Environment=HOME=/home/$USER
Environment=PATH=/home/$USER/hermes-agent/venv/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
Environment=HERMES_HOME=/home/$USER/.hermes
Restart=on-failure
RestartSec=15
KillMode=mixed
KillSignal=SIGTERM
TimeoutStopSec=30
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target
SVC

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

⚠️ 关键注意事项：

• ExecStart 必须用 venv 内的绝对路径（如 /home/$USER/hermes-agent/venv/bin/hermes），不要用系统 Python
• 上面模板中的 $USER 需要替换为实际的 Linux 用户名（如 ubuntu）
• --replace 参数确保旧进程残留时能自动接管
• Restart=on-failure + RestartSec=15：失败时重试，间隔 15 秒避免 crash 风暴
• 如果依赖其他服务（如 API proxy），用 Wants=（软依赖）， 绝对不要用 Requires=（硬依赖会连带杀进程）

Phase 5: 验证部署#

bash

# 检查服务状态
sudo systemctl status hermes-gateway.service

# 查看日志
tail -30 ~/.hermes/logs/agent.log

# 查看错误日志
tail -20 ~/.hermes/logs/errors.log

# 确认进程存活
ps aux | grep 'hermes.*gateway' | grep -v grep

配置参考#

Provider 配置方式#

Hermes 支持以下 provider：

Provider slug说明认证方式openaiOpenAI 官方OPENAI_API_KEYanthropicAnthropic ClaudeANTHROPIC_API_KEYopenrouterOpenRouter 聚合OPENROUTER_API_KEYzai智谱 AI (ZhipuAI)GLM_API_KEYcustom自定义 OpenAI 兼容接口OPENAI_API_KEY + base_url

⚠️ 自定义 Provider 的正确配置方式

方式一（推荐）：在 model 段直接写 provider: "custom" + base_url

yaml

model:
  default: "glm-5"
  provider: "custom"
  base_url: "https://api.lkeap.cloud.tencent.com/v3"

方式二：用 custom_providers 列表（注意是 列表 格式！）

yaml

custom_providers:
  - name: "Tencent Cloud LKEAP"
    base_url: "https://api.lkeap.cloud.tencent.com/v3"
    key_env: "OPENAI_API_KEY"

model:
  default: "glm-5"
  provider: "custom:tencent-cloud-lkeap"   # slug = custom: + 小写连字符化的 name

❌ 错误方式：不要用 providers: 字典格式

yaml

# 这样写 hermes 不认！会报 "Unknown provider"
providers:
  tencent-cloud:
    name: "xxx"
    api: "xxx"

消息平台配置#

微信（Weixin iLink）

需要先在 iLink 平台 注册 bot，获取 account_id 和 token。

env

WEIXIN_ACCOUNT_ID=your_account@im.bot
WEIXIN_TOKEN=your_account@im.bot:your_token_hex
WEIXIN_BASE_URL=https://ilinkai.weixin.qq.com
WEIXIN_CDN_BASE_URL=https://novac2c.cdn.weixin.qq.com/c2c
WEIXIN_DM_POLICY=open
WEIXIN_GROUP_POLICY=open
WEIXIN_HOME_CHANNEL=user_openid@im.wechat
GATEWAY_ALLOW_ALL_USERS=true

config.yaml:

yaml

platforms:
  weixin:
    enabled: true
    extra:
      dm_policy: "open"
      group_policy: "open"

企业微信（WeCom）

需要在企微后台创建智能 bot，获取 bot_id 和 secret。

yaml

platforms:
  wecom:
    enabled: true
    extra:
      bot_id: "your-wecom-bot-id"
      secret: "your-wecom-bot-secret"
      websocket_url: "wss://openws.work.weixin.qq.com"
      dm_policy: "open"
      group_policy: "open"

Telegram

env

TELEGRAM_BOT_TOKEN=your-bot-token
TELEGRAM_ALLOWED_USERS=your_user_id
TELEGRAM_HOME_CHANNEL=your_user_id

yaml

platforms:
  telegram:
    enabled: true

日常运维#

常用命令#

bash

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

# 重启服务
sudo systemctl restart hermes-gateway.service

# 停止服务
sudo systemctl stop hermes-gateway.service

# 查看实时日志
tail -f ~/.hermes/logs/agent.log

# 查看错误日志
tail -f ~/.hermes/logs/errors.log

# 查看 systemd 日志
sudo journalctl -u hermes-gateway.service --no-pager -n 50

# 手动前台运行（调试用）
sudo systemctl stop hermes-gateway.service
/home/$USER/hermes-agent/venv/bin/hermes gateway run -v

升级 Hermes#

bash

sudo systemctl stop hermes-gateway.service
cd /home/$USER/hermes-agent
git pull
source venv/bin/activate
pip install -e .
hermes --version  # 确认新版本
sudo systemctl start hermes-gateway.service

切换模型#

在聊天中发送 /model 查看当前模型和可用选项，或直接编辑 config.yaml。

排障指南#

问题：Gateway 反复重启（5 秒循环）#

症状：日志中快速出现 "Starting Hermes Gateway..." → "Stopping gateway..." 循环

排查步骤：

1. 检查是否有残留进程： bash

   ps aux | grep 'hermes.*gateway' | grep -v grep
   
   

   如果有多个 gateway 进程，全部杀掉再重启： bash

   sudo systemctl stop hermes-gateway.service
   pkill -f 'hermes.*gateway'
   sleep 2
   pkill -9 -f 'hermes.*gateway'  # 强杀
   rm -f ~/.hermes/gateway.pid
   sudo systemctl start hermes-gateway.service
   
   

2. 检查依赖服务： 如果 service 配置了 Requires=xxx.service，xxx 挂了会连带杀 gateway。改成 Wants=： bash

   sudo systemctl status xxx.service
   # 如果 xxx 在 crash，先修它
   # 然后把 Requires 改成 Wants
   sudo sed -i 's/Requires=xxx.service/Wants=xxx.service/' /etc/systemd/system/hermes-gateway.service
   sudo systemctl daemon-reload
   
   

3. 检查端口冲突（如有依赖服务）： bash

   sudo lsof -i :PORT
   # 杀掉占端口的残留进程
   sudo kill <PID>
   
   

问题："Unknown provider" / "Provider authentication failed"#

原因：config.yaml 中 provider 配置语法错误

修复：

yaml

# ✅ 正确 — 用 custom + base_url
model:
  default: "model-name"
  provider: "custom"
  base_url: "https://your-api.com/v1"

# ❌ 错误 — 不要用 providers 字典
providers:
  my-provider:
    ...

确保 .env 里有对应的 API key（ OPENAI_API_KEY 用于 custom provider）。

问题："No response generated"#

可能原因：

1. API key 无效或过期 → 检查 .env 中的 key
2. 模型名称写错 → 确认 API 支持该模型
3. API 额度用完 → 检查账户余额
4. Gateway 不稳定，处理消息前就被杀 → 参考上面的重启循环排查

快速测试 API 连通性：

bash

curl -s https://api.lkeap.cloud.tencent.com/v3/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"glm-5","messages":[{"role":"user","content":"hi"}],"max_tokens":10}' | python3 -m json.tool

问题：systemd service 启动失败（exit-code 1）#

排查：

bash

# 查看详细错误
sudo journalctl -u hermes-gateway.service --no-pager -n 20

# 常见原因：
# 1. ExecStart 路径错误 — 必须用 venv 内的绝对路径
# 2. hermes_cli 找不到 — 不要用系统 Python
# 3. 权限问题 — User 字段要和文件所有者一致

问题：微信/企微连不上#

1. 检查 token 是否过期（iLink 平台查看）
2. 检查 .env 中的配置是否完整
3. 检查 config.yaml 中 platforms 是否 enabled
4. 检查网络连通性（是否能访问 ilinkai.weixin.qq.com）

文件结构#

text

/home/$USER/
├── hermes-agent/                 # 代码目录
│   ├── venv/                     # Python 虚拟环境
│   │   └── bin/hermes            # CLI 入口
│   ├── gateway/                  # Gateway 核心代码
│   ├── agent/                    # Agent 核心代码
│   ├── hermes_cli/               # CLI 命令
│   └── pyproject.toml
│
├── .hermes/                      # 运行时目录（HERMES_HOME）
│   ├── config.yaml               # 主配置
│   ├── .env                      # 环境变量（API keys）
│   ├── logs/
│   │   ├── agent.log             # 主日志
│   │   └── errors.log            # 错误日志
│   ├── sessions/                 # 会话存储
│   ├── memories/                 # 记忆存储
│   ├── skills/                   # 自学技能
│   ├── gateway.pid               # PID 文件
│   ├── gateway_state.json        # Gateway 状态
│   ├── state.db                  # SQLite 状态数据库
│   ├── SOUL.md                   # 人格文件（可选）
│   ├── IDENTITY.md               # 身份文件（可选）
│   └── USER.md                   # 用户档案（可选）
│
└── /etc/systemd/system/
    └── hermes-gateway.service    # systemd 服务文件