Hermes Deployer

在 Linux 服务器上安装、配置、部署和运维 Hermes Agent（Nous Research 出品的自我改进 AI Agent）。触发词：hermes、hermes agent、部署 hermes、安装 hermes、hermes gateway、hermes 运维、hermes 排障、hermes 配置...

Security Scan

The instructions match a legitimate Hermes Agent deployment, but the skill omits declaring the many sensitive credentials it asks you to store and recommends permissive settings (auto_improve / bypassPermissions / allow-all) that increase risk — review before installing.

Purpose & Capability

The SKILL.md content (git clone, venv, pip install, systemd service, platform tokens) is coherent with the stated purpose of deploying and operating Hermes Agent on a Linux server.

Instruction Scope

Instructions are explicit and limited to deployment/ops tasks (clone repo, create ~/.hermes/.env, configure providers/platforms, create systemd service). However the guide recommends enabling 'bypassPermissions', 'auto_create' and 'auto_improve' and setting GATEWAY_ALLOW_ALL_USERS=true, which broadens the agent's powers and network/interaction surface — this increases operational risk and should be treated as a configurable decision, not a default.

Install Mechanism

No automatic installer; user-run steps use git clone from GitHub and pip install -e . (standard). There are no downloads from unknown URLs or archive extraction in the skill itself.

Credentials

The skill runtime asks you to create ~/.hermes/.env with numerous sensitive API keys and platform tokens (OPENAI_API_KEY, GLM_API_KEY, ANTHROPIC_API_KEY, WEIXIN_TOKEN, TELEGRAM_BOT_TOKEN, etc.), but the registry metadata declares no required env vars — this mismatch is an incoherence. While these credentials are expected for a full Hermes deployment, the skill should have declared them and documented minimal required keys. Also recommending allow-all users and bypassing permission checks amplifies the risk from those credentials.

Persistence & Privilege

The guide instructs creating a systemd service (requires sudo) so Hermes runs persistently and restarts on failure — that is expected for a 24/7 agent. It does not set always:true. Because the service runs continuously and may use privileged tokens and network access, confirm user ownership, ExecStart paths, and service user before enabling.

What to consider before installing

This Skill appears to be a genuine deployment guide for Hermes Agent, but take these precautions before proceeding: - Confirm the upstream repository (https://github.com/NousResearch/hermes-agent) is the official project and review its code and recent commits yourself before running pip install -e . - The SKILL.md asks you to create a file containing many secrets but the skill metadata did not declare them — treat that as a warning: only add keys you trust and need. - Do NOT turn on 'auto_improve' or 'bypassPermissions' or 'GATEWAY_ALLOW_ALL_USERS' unless you understand and accept the risk of an agent that can self-modify or interact broadly; keep these disabled in production. - Store API keys securely (use a secrets manager or restrict file permissions to the service user), and avoid placing highly privileged credentials in a world-readable ~/.hermes/.env. - When creating the systemd unit: replace $USER with a dedicated low-privilege service user, verify ExecStart absolute paths, and inspect the unit before enabling it. - If possible, test the deployment in an isolated environment (VM or container) first, and monitor outbound network calls and logs for unexpected behavior. If you want higher confidence, provide the exact GitHub repo commit/sha you plan to install or ask for a code review of the hermes-agent repository and the precise configuration you intend to use.

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

概述

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

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

前提条件

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

安装流程

Phase 1: 环境准备

# 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

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=[e-mail]
# WEIXIN_TOKEN=[e-mail]: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=[e-mail]
# GATEWAY_ALLOW_ALL_USERS=true

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

创建 ~/.hermes/config.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: 测试运行

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

确认看到：

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

Phase 4: 创建 systemd 服务

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: 验证部署

# 检查服务状态
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	说明	认证方式
openai	OpenAI 官方	OPENAI_API_KEY
anthropic	Anthropic Claude	ANTHROPIC_API_KEY
openrouter	OpenRouter 聚合	OPENROUTER_API_KEY
zai	智谱 AI (ZhipuAI)	GLM_API_KEY
custom	自定义 OpenAI 兼容接口	OPENAI_API_KEY + base_url

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

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

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

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

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: 字典格式

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

消息平台配置

微信（Weixin iLink）

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

WEIXIN_ACCOUNT_ID=[e-mail]
WEIXIN_TOKEN=[e-mail]: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=[e-mail]
GATEWAY_ALLOW_ALL_USERS=true

config.yaml:

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

企业微信（WeCom）

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

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

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

platforms:
  telegram:
    enabled: true

日常运维

常用命令

# 查看服务状态
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

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. 检查是否有残留进程：

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

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

   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=：

   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. 检查端口冲突（如有依赖服务）：

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

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

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

修复：

# ✅ 正确 — 用 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 连通性：

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）

排查：

# 查看详细错误
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）

文件结构

/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 服务文件