Skill: dengjiawei1226/hermes-deployer (version 1.0.0)

--- name: "hermes-deployer" version: "1.0.0" description: "在 Linux 服务器上安装、配置、部署和运维 Hermes Agent（Nous Research 出品的自我改进 AI Agent）。触发词：hermes、hermes agent、部署 hermes、安装 hermes、hermes gateway、hermes 运维、hermes 排障、hermes 配置、hermes 重启、微信 bot 部署、企微 bot 部署、聊天机器人部署。" --- # 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: 环境准备 ```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=[REDACTED_SECRET] # WEIXIN_TOKEN=[REDACTED_SECRET]: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=[REDACTED_SECRET] # 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" # [REDACTED_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 | 说明 | 认证方式 | |--------------|------|---------| | `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` ```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 平台](https://ilinkai.weixin.qq.com) 注册 bot，获取 account_id 和 token。 ```env WEIXIN_ACCOUNT_ID=[REDACTED_SECRET] WEIXIN_TOKEN=[REDACTED_SECRET]: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=[REDACTED_SECRET] 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" [REDACTED_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） ## 文件结构 ``` /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 服务文件 ```


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)