← 返回 Skills 市场
hanxueyuan

Hermes Upgrade

作者 hanxueyuan · GitHub ↗ · v1.0.3 · MIT-0
cross-platform ⚠ suspicious
115
总下载
0
收藏
0
当前安装
4
版本数
在 OpenClaw 中安装
/install hermes-upgrade
功能描述
Hermes Agent 完整手册 - 包含安装、配置、部署、运维和常见问题排查的完整指南
使用说明 (SKILL.md)

Hermes Agent 升级与部署技能

📋 技能概述

本技能提供 Hermes Agent 从旧版本升级到最新版本的完整流程，包括：

  • 版本检查与下载
  • 配置迁移
  • systemd 服务配置
  • 开机自启设置
  • 常见问题排查

🎯 适用场景

  1. 升级 Hermes - 从旧版本升级到最新版本
  2. 迁移配置 - 保留旧配置到新版本
  3. 配置开机自启 - 设置 systemd 服务
  4. 故障排查 - 解决启动失败、模型配置等问题

📖 操作流程

步骤 1：检查当前版本

# 检查已安装版本
pip show hermes-agent | grep Version

# 检查 GitHub 最新版本
curl -s https://api.github.com/repos/NousResearch/hermes-agent/releases/latest | grep '"tag_name"'

# 检查当前运行状态
systemctl status hermes-gateway.service

步骤 2：下载并安装最新版本

2.1 修复 git 配置（如需要）

# 如果系统配置了 ghproxy 代理但不可用，修复 git 配置
cat > ~/.gitconfig \x3C\x3C 'EOF'
[user]
    name = OpenClaw
    email = openclaw@localhost
[url "https://github.com/"]
    insteadOf = https://ghproxy.com/
EOF

2.2 下载安装包

# 获取最新版本号
LATEST_VERSION=$(curl -s https://api.github.com/repos/NousResearch/hermes-agent/releases/latest | grep '"tag_name"' | cut -d'"' -f4)

# 下载源码包（使用 curl，支持重试）
cd /tmp
rm -rf hermes*
curl -sL --max-time 600 --connect-timeout 120 --retry 5 --retry-delay 30 \
    "https://github.com/NousResearch/hermes-agent/archive/refs/tags/${LATEST_VERSION}.tar.gz" \
    -o hermes.tar.gz

# 验证下载
ls -lh hermes.tar.gz
file hermes.tar.gz

2.3 解压并安装

# 解压
tar -xzf hermes.tar.gz
cd hermes-agent-*

# 使用 pip 安装
pip install --upgrade . 2>&1 | tail -30

# 验证安装
hermes --version
which hermes

步骤 3：迁移配置文件

3.1 备份旧配置

# 检查旧配置位置
OLD_HERMES_DIR="/workspace/projects/hermes"  # 或实际路径

# 查看需要迁移的文件
ls -la $OLD_HERMES_DIR/.env $OLD_HERMES_DIR/auth.json $OLD_HERMES_DIR/cli-config.yaml 2>/dev/null

3.2 迁移到新位置

# 新版本配置目录
NEW_HERMES_HOME="$HOME/.hermes"
mkdir -p $NEW_HERMES_HOME

# 迁移配置文件
cp $OLD_HERMES_DIR/.env $NEW_HERMES_HOME/.env
chmod 600 $NEW_HERMES_HOME/.env

cp $OLD_HERMES_DIR/auth.json $NEW_HERMES_HOME/auth.json
chmod 600 $NEW_HERMES_HOME/auth.json

cp $OLD_HERMES_DIR/cli-config.yaml $NEW_HERMES_HOME/cli-config.yaml
chmod 600 $NEW_HERMES_HOME/cli-config.yaml

echo "✅ 配置迁移完成"

3.3 修复模型配置

# 检查并修复模型格式（旧格式 qwen/qwen-3.5-plus → 新格式 qwen3.5-plus）
sed -i 's/qwen\/qwen-3.5-plus/qwen3.5-plus/g' ~/.hermes/.env
sed -i 's/qwen\/qwen-3.5-plus/qwen3.5-plus/g' ~/.hermes/cli-config.yaml

# 验证
grep -i "MODEL" ~/.hermes/.env

3.4 创建 config.yaml

# Hermes 0.8.0 需要 config.yaml 在 HERMES_HOME 或工作目录
mkdir -p /workspace/projects/hermes

cat > /workspace/projects/hermes/config.yaml \x3C\x3C 'EOF'
model:
  default: "qwen3.5-plus"
  provider: "custom"
  base_url: "https://coding.dashscope.aliyuncs.com/v1"
  api_key_env: "OPENROUTER_API_KEY"

terminal:
  backend: "local"
  cwd: "."
  timeout: 300

gateway:
  enabled: true
  port: 5001
  
  feishu:
    enabled: true
    app_id: "cli_xxx"
    app_secret: "xxx"
    allowed_users:
      - "ou_xxx"
    dm_policy: "allow"
    group_policy: "open"
    require_mention: false

memory:
  enabled: true
  max_memory_tokens: 2200
  max_user_tokens: 1375
EOF

步骤 4：配置 systemd 服务

4.1 创建服务文件

cat > /etc/systemd/system/hermes-gateway.service \x3C\x3C 'EOF'
[Unit]
Description=Hermes Gateway Service
Documentation=https://github.com/NousResearch/hermes-agent
After=network.target
Wants=network-online.target

[Service]
Type=simple
User=root
WorkingDirectory=/root

# 环境变量
Environment="PATH=/usr/local/bin:/usr/local/sbin:/usr/bin:/usr/sbin:/bin"
Environment="PYTHONUNBUFFERED=1"

# 启动命令
ExecStart=/usr/local/bin/hermes gateway run

# 重启策略
Restart=always
RestartSec=10

# 超时设置
TimeoutStartSec=180
TimeoutStopSec=120

# 资源限制
LimitNOFILE=65535
Nice=-5

# 日志
StandardOutput=journal
StandardError=journal
SyslogIdentifier=hermes-gateway

# 进程管理
KillMode=mixed
KillSignal=SIGTERM
SendSIGKILL=yes
FinalKillSignal=SIGKILL

[Install]
WantedBy=multi-user.target
EOF

4.2 启用并启动服务

# 重新加载 systemd 配置
systemctl daemon-reload

# 启用开机自启
systemctl enable hermes-gateway.service

# 启动服务
systemctl start hermes-gateway.service

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

步骤 5：安装依赖（如需要）

# 飞书 SDK
pip install lark-oapi 2>&1 | tail -5

# 验证
python3 -c "import lark_oapi; print('✅ lark-oapi installed')"

步骤 6：飞书用户配对

# 当收到配对码时执行
hermes pairing approve feishu \x3CPAIRING_CODE>

# 示例
# hermes pairing approve feishu VRP8RX8B

🔍 常见问题排查

问题 1：GitHub 下载失败

症状：

fatal: unable to access 'https://github.com/...': Failed to connect
curl: (56) Recv failure: Connection reset by peer

解决方案：

# 方案 A：增加重试和超时
curl -sL --max-time 600 --connect-timeout 120 --retry 5 --retry-delay 30 \
    "https://github.com/.../hermes-agent-xxx.tar.gz" -o hermes.tar.gz

# 方案 B：使用本地下载后上传
# 1. 在本地机器下载
curl -L https://github.com/NousResearch/hermes-agent/archive/refs/tags/v2026.4.8.tar.gz -o hermes.tar.gz
# 2. 上传到服务器
scp hermes.tar.gz root@server:/tmp/
# 3. 在服务器上安装
ssh root@server "cd /tmp && tar -xzf hermes.tar.gz && cd hermes-agent-* && pip install ."

问题 2：模型配置错误

症状：

API call failed after 3 retries: HTTP 400: model `` is not supported.

原因： 模型格式不正确或配置文件未读取

解决方案：

# 1. 检查配置位置
hermes config show | grep -A5 "◆ Model"

# 2. 修复模型格式（移除 qwen/ 前缀）
sed -i 's/qwen\/qwen-3.5-plus/qwen3.5-plus/g' ~/.hermes/.env
sed -i 's/qwen\/qwen-3.5-plus/qwen3.5-plus/g' /workspace/projects/hermes/config.yaml

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

# 4. 验证配置
hermes config show | grep "Model:"

问题 3：systemd 服务启动失败

症状：

Failed with result 'exit-code'
status=226/NAMESPACE

原因： 安全配置导致命名空间问题

解决方案：

# 1. 创建必要的目录
mkdir -p /root/.cache/hermes /root/.hermes

# 2. 简化 systemd 配置（移除 ProtectSystem 等）
# 编辑 /etc/systemd/system/hermes-gateway.service
# 移除或注释掉以下行：
# ProtectSystem=strict
# ProtectHome=read-only
# ReadWritePaths=...

# 3. 重新加载并重启
systemctl daemon-reload
systemctl restart hermes-gateway.service

问题 4：飞书连接失败

症状：

WARNING gateway.run: Feishu: lark-oapi not installed

解决方案：

# 安装飞书 SDK
pip install lark-oapi

# 验证配置
cat ~/.hermes/.env | grep FEISHU

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

问题 5：用户未配对

症状：

Hi~ I don't recognize you yet!
Here's your pairing code: XXXXX

解决方案：

# 执行配对命令
hermes pairing approve feishu \x3CPAIRING_CODE>

# 验证配对状态
hermes pairing list
cat ~/.hermes/channel_directory.json

⚠️ 重要：为什么每次升级后都要重新配对？

原因： 同一个用户在不同飞书应用下的 open_id 是不同的。

旧应用的用户 ID: ou_5cb8fb7d3a8bfa563563becf58984cd6
新应用的用户 ID: ou_4b069f29bfbc9afd47a3f8c9deae2c62
                 ↑ 不匹配！需要重新配对

如果升级后飞书应用（App ID）变了：

  1. 必须重新配对
  2. 旧配对数据存储在 /workspace/projects/hermes/platforms/pairing/
  3. 如果保持相同的飞书应用，则无需重新配对

避免重复配对的方案：

# 方案 A：保持飞书应用不变（推荐）
# 在 ~/.hermes/.env 中使用相同的 FEISHU_APP_ID

# 方案 B：升级时保留配对数据
cp /workspace/projects/hermes/platforms/pairing/* ~/.hermes/platforms/pairing/
# 注意：仅当 App ID 相同时有效

📋 验证清单

完成后执行以下检查：

# 1. 版本检查
hermes --version
# 应显示：Hermes Agent v0.8.0 (2026.4.8)

# 2. 服务状态
systemctl status hermes-gateway.service
# 应显示：active (running)

# 3. 开机自启
systemctl is-enabled hermes-gateway.service
# 应显示：enabled

# 4. 配置检查
hermes config show | grep -A3 "◆ Model"
# 应显示正确的模型配置

# 5. 飞书连接
journalctl -u hermes-gateway.service --since "5 minutes ago" | grep -i "connected"
# 应显示：[INFO] connected to wss://msg-frontier.feishu.cn/ws/v2

# 6. 内存占用
ps aux | grep hermes | grep -v grep
# 正常：100-200MB

🗑️ 清理旧版本

确认新版本正常运行后：

# 1. 备份重要配置（如未迁移）
cp /workspace/projects/hermes/.env ~/.hermes/.env 2>/dev/null

# 2. 删除旧目录
rm -rf /workspace/projects/hermes/

# 3. 清理 uv 缓存
rm -rf /root/.cache/uv/archive-v0/*hermes*

# 4. 验证清理
ls /workspace/projects/ | grep hermes || echo "✅ 旧版本已清理"

📝 管理命令速查

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

# 查看日志
journalctl -u hermes-gateway.service -f

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

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

# 启动服务
systemctl start hermes-gateway.service

# 禁用开机自启
systemctl disable hermes-gateway.service

# 查看配置
hermes config show

# 用户配对
hermes pairing approve feishu \x3CCODE>

# 查看已配对用户
cat ~/.hermes/channel_directory.json

📚 参考资源

最后更新：2026-04-11 适用版本：Hermes Agent 0.8.0 (v2026.4.8)

安全使用建议
This skill is an instruction-only upgrade guide that largely matches its stated purpose, but it performs system-wide, root-level changes and references undeclared credentials and config values. Before running any commands: (1) review every command line-by-line instead of running the whole script; (2) do not blindly overwrite your ~/.gitconfig or copy auth.json/.env without inspecting them for secrets; (3) prefer running in a test VM or container first; (4) confirm the GitHub repository and release URL you will download from (the guide uses NousResearch/hermes-agent) and verify the tarball checksum if available; (5) check the example base_url (coding.dashscope.aliyuncs.com) and OPENROUTER_API_KEY usage — ensure you understand where credentials would be sent; and (6) perform backups of existing configs and service unit files so you can roll back. If you need a lower-privilege installation, adapt the steps to a per-user install and avoid writing to /etc or /root.
功能分析
Type: OpenClaw Skill Name: hermes-upgrade Version: 1.0.3 The skill performs high-risk system administration tasks, including modifying the global git configuration and creating a systemd service in `/etc/systemd/system/hermes-gateway.service` that runs with root privileges. While these actions are consistent with the stated purpose of deploying and upgrading the Hermes Agent (referencing the legitimate NousResearch/hermes-agent repository), the ability to establish root-level persistence and modify system-wide configurations via instructions in `SKILL.md` represents a significant security risk if the agent is misdirected.
能力评估
ℹ Purpose & Capability
The skill's name/description (Hermes upgrade/deploy) align with the provided instructions: checking releases, downloading a tarball from GitHub, pip-installing, migrating config, and adding a systemd service. However, the guide assumes system-wide/root installation (writes to /etc/systemd/system, /root, enables services) and includes an example config that points to an external base_url (coding.dashscope.aliyuncs.com) and API key env name (OPENROUTER_API_KEY) that are not documented in the registry metadata — these are plausible for some deployments but are not justified by the metadata.
⚠ Instruction Scope
SKILL.md contains many concrete shell commands that touch system-wide resources: modifying ~/.gitconfig, downloading and extracting archives, pip installing, copying auth.json and .env from an OLD_HERMES_DIR, writing /etc/systemd/system/hermes-gateway.service, enabling and starting systemd services, and creating /root/.cache and /root/.hermes. It also suggests copying auth.json (which may contain credentials) without prompting to inspect or redact secrets. The guide references environment variable names (OPENROUTER_API_KEY) and feishu app_id/app_secret placeholders not declared elsewhere. Overwriting a user's ~/.gitconfig and copying potentially sensitive files are actions beyond passive guidance and should not be run blindly.
✓ Install Mechanism
No install spec or code files are executed by the skill itself — this is instruction-only. The guide instructs using curl to download a GitHub release tarball and pip to install, which is expected for this purpose. Because the skill only provides commands (no embedded downloads/installers), there is low install-spec risk from the registry side.
⚠ Credentials
Registry metadata declares no required env vars, but SKILL.md references OPENROUTER_API_KEY and shows placeholders for feishu app_id/app_secret and allowed_users. It also instructs copying auth.json and .env (files that often contain secrets) without guidance about exposing or redacting sensitive values. The skill asks to modify ~/.gitconfig and set a username/email to OpenClaw — an unexpected change to user identity config. These undeclared credential/environment references are disproportionate to the metadata and should be made explicit to users.
⚠ Persistence & Privilege
While always:false and autonomous invocation are normal, the steps require elevated privileges (writing /etc/systemd/system, enabling services, creating files under /root) and will create a persistent systemd service that restarts automatically. The skill does not explicitly state that root permissions are required in the registry, and instructions include actions that will persist across reboots and affect system-wide behavior — users should only run these with explicit consent and understanding of privilege changes.
如何使用
  1. 确保已安装 OpenClaw（本地或 Docker 部署）
  2. 在对话框中输入安装命令：/install hermes-upgrade
  3. 安装完成后，直接呼叫该 Skill 的名称或使用 /hermes-upgrade 触发
  4. 根据 Skill 的参数说明提供必要输入，即可获得结构化输出
版本历史
v1.0.3
Add Feishu pairing troubleshooting guide - explains why re-pairing is needed after upgrade
v1.0.2
Rename to hermes-handbook - more accurate name for comprehensive guide
v1.0.1
Remove username suffix from skill name
v1.0.0
Initial release: 完整指南，涵盖 Hermes Agent 从升级到部署的所有关键步骤。 - 升级流程详细拆解：版本检查、下载与安装、配置迁移。 - 包含 systemd 服务配置与开机自启设置方法。 - 提供飞书配对、常见问题排查和依赖安装指引。 - 附验证清单与一站式命令速查，方便维护和运维。
元数据
Slug hermes-upgrade
版本 1.0.3
许可证 MIT-0
累计安装 1
当前安装数 0
历史版本数 4
常见问题

Hermes Upgrade 是什么？

Hermes Agent 完整手册 - 包含安装、配置、部署、运维和常见问题排查的完整指南. 它是一个面向 Claude Code / OpenClaw 的 AI Agent Skill 插件，目前累计下载 115 次。

如何安装 Hermes Upgrade？

在 OpenClaw 或 Claude Code 对话框中运行命令「/install hermes-upgrade」即可一键安装，无需额外配置。

Hermes Upgrade 是免费的吗？

是的，Hermes Upgrade 完全免费，采用 MIT-0 许可证，可自由下载、安装和使用。

Hermes Upgrade 支持哪些平台？

Hermes Upgrade 跨平台运行，可在任意部署了 OpenClaw / Claude Code 的环境中使用（cross-platform）。

谁开发了 Hermes Upgrade？

由 hanxueyuan（@hanxueyuan）开发并维护，当前版本 v1.0.3。

推荐 Skills
self-improving agent
Captures learnings, errors, and corrections to enable continuous improvement. Use when: (1) A command or operation fails unexpectedly, (2) User corrects Clau...
⬇ 463283 · by pskoett
Skill Vetter
Security-first skill vetting for AI agents. Use before installing any skill from ClawdHub, GitHub, or other sources. Checks for red flags, permission scope, and suspicious patterns.
⬇ 259410 · by spclaudehome
Polymarket
Query Polymarket prediction markets. Check odds, find trending markets, search events, track price movements.
⬇ 232503 · by joelchance
Self-Improving + Proactive Agent
Self-reflection + Self-criticism + Self-learning + Self-organizing memory. Agent evaluates its own work, catches mistakes, and improves permanently. Use when...
⬇ 200423 · by ivangdavila
Github
Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.
⬇ 191115 · by steipete
ontology
Typed knowledge graph for structured agent memory and composable skills. Use when creating/querying entities (Person, Project, Task, Event, Document), linkin...
⬇ 190156 · by oswalpalash

💬 留言讨论