TimeAmber
剪藏#剪藏#流年的Agent

Nas版Hermes Agent：升级、排障与日常维护

2026 年 6 月 8 日 约 1 分钟
分享Twitter / XTelegram微博

**本文是「Hermes Agent 群晖 NAS 部署系列」共 4 篇中的第 4 篇（最后一篇）。**① 📖 Hermes Agent 是什么？ ② 🔧 Hermes Agent 群晖 NAS 安装实战 ③ ⚙️ Hermes Agent 必做配置与调试 ④ 🛠️ Hermes Agent 运维手册：升级、排障与日常维护（本文）

Hermes Agent（GitHub: github.com/NousResearch/hermes-agent）是由 Nous Research 开发的开源 AI Agent 框架，支持持久记忆、技能自学习和 15+ 消息平台接入。

一、踩坑记录与问题排查

以下是实际部署中遇到的问题和解决方案，按严重程度排序。

🔴 坑 1：群晖 Docker 构建报 seccomp 错误

JAVASCRIPT
seccomp: config provided but seccomp not supported

解决：DOCKER_BUILDKIT=0 docker compose build --no-cache

这是群晖 NAS 最常见的问题。所有docker compose build 命令都必须加 DOCKER_BUILDKIT=0 前缀。详见本系列《Hermes Agent 群晖 NAS 安装实战》中的群晖特殊注意事项。

🔴 坑 2：Codex 流式响应 response.output is empty

解决： 升级到 v0.7.0+（官方已在 commit 37bf19a 中修复）。

经验：遇到 API 相关问题，先查官方仓库最近的 commits 和 issues，Hermes 社区响应很快。

🟠 坑 3：Vision 视觉功能路由错误

解决： 升级到最新版。视觉功能的 Provider 路由在早期版本中存在 Bug。

🟠 坑 4：构建时大量红字 npm 警告

处理： 是警告不是错误，不影响运行。常见的有：

  • npm warn EBADENGINE —— Node.js 版本不完全匹配，不影响

  • pip Running as root —— Docker 构建中正常

  • deprecated 提示 —— 依赖库内部的过时警告

只要构建最终没有报 error 或 FATAL，都可以正常使用。

🟡 坑 5：pip 安装超时

解决： Dockerfile 中配置国内镜像源（清华 pypi 镜像）。详见本系列《Hermes Agent 群晖 NAS 安装实战》中的 Dockerfile 定制部分。

🟡 坑 6：国内 API 走代理变慢

解决： 设置 NO_PROXY 环境变量，将国内 API 端点排除在代理之外：

JAVASCRIPT
NO_PROXY=localhost,127.0.0.1,192.168.0.0/16,camofox,api.minimaxi.com,open.bigmodel.cn,api.fal.ai,msg-frontier.feishu.cn

🟡 坑 7：Camoufox Dockerfile 不兼容群晖 Docker

JAVASCRIPT
the --mount option requires BuildKit

原因： Camoufox 官方 Dockerfile 使用了 RUN --mount=type=bind 语法，需要 BuildKit。群晖 Docker 不支持 BuildKit（缺少 buildx 组件），DOCKER_BUILDKIT=1 也无效。

解决： 使用改造过的 Dockerfile.nas，将 --mount=type=bind 替换为 COPY 命令。详见本系列第三篇 Camoufox 部署章节。

🟡 坑 8：Camofox 容器部署后 check_camofox_available() 返回 False

JAVASCRIPT
Camofox mode: True
Camofox available: False

原因： Hermes 容器设了 HTTP_PROXY，发往 http://camofox:9377 的请求也走了代理。代理无法解析 Docker 内部域名 camofox。

解决：NO_PROXY 里加 camofox：NO_PROXY=localhost,camofox,...

🟡 坑 9：Camofox 配了代理但浏览器依然访问不了 Google

原因： Node.js 的 HTTP_PROXY 环境变量只影响 Camofox 服务端进程，不影响 Camoufox 浏览器本身。浏览器有独立的代理通道。

解决： 使用 Camofox 的浏览器级代理环境变量 PROXY_HOST 和 PROXY_PORT（不是 HTTP_PROXY）。

二、版本升级

Hermes 迭代很快，建议定期升级。我们提供了一个一键升级脚本，把 5 步手动操作自动化。

⚠️ 适用范围：以下升级脚本专为《群晖 NAS 安装实战》中的本地源码构建部署方式设计。如果你使用的是官方预构建镜像（docker pull）或其他部署方式，请勿使用此脚本，否则可能覆盖你的配置。预构建镜像的升级方式是 docker compose pull && docker compose up -d。

2.1 一键升级脚本（推荐）

🎁 独家福利： 篇幅有限，文章中就不贴冗长的 Shell 源码了。我已经为你准备好了现成的脚本文件，关注公众号后台回复【Hermes脚本】，即可获取完整的 hermes-upgrade.sh 文件下载链接。

下载后，将升级脚本上传或放置在 NAS 的 Hermes 安装目录中：

JAVASCRIPT
# 将下载的脚本放到 NAS 对应目录下
scp hermes-upgrade.sh root@NAS_IP:/volume1/docker/hermes-agent/ # SSH 到 NAS 执行
ssh admin@NAS_IP
sudo -i
cd /volume1/docker/hermes-agent # 如果需要代理访问 GitHub：
GIT_PROXY=http://你的代理地址:端口 bash hermes-upgrade.sh # 如果不需要代理（使用国内 Git 镜像等）：
bash hermes-upgrade.sh

脚本会自动完成以下步骤：

  1. ✅ 备份 data 目录（带时间戳，如 data.bak.20260409_090000）

  2. ✅ 备份当前 Docker 镜像（打 tag hermes-agent:pre-upgrade-时间戳）

  3. ✅ git fetch + reset --hard 更新源码到最新

  4. ✅ 重新写入定制 Dockerfile（国内镜像源 + debian:12-slim）

  5. ✅ DOCKER_BUILDKIT=0 构建镜像（自动禁用 BuildKit）

  6. ✅ 启动容器并验证运行状态

  7. ✅ 构建失败时打印回滚命令

脚本执行完毕后会显示构建耗时、新版本 commit、备份位置和回滚方法。

以后每次升级只需要一条命令：sudo bash hermes-upgrade.sh

2.2 手动升级步骤（参考）

如果你不想用脚本，手动步骤如下：

JAVASCRIPT
cd /volume1/docker/hermes-agent # 1. 备份
cp -a data data.bak.$(date +%Y%m%d)
docker tag hermes-agent:latest hermes-agent:pre-upgrade # 2. 更新源码
cd hermes-agent-source
git stash && git fetch --depth=1 origin main && git reset --hard origin/main # 3. 重写定制 Dockerfile（内容同《Hermes Agent 群晖 NAS 安装实战》中的 Dockerfile 定制） # 4. 重建并启动
cd .. && docker compose down
DOCKER_BUILDKIT=0 docker compose build --no-cache
docker compose up -d # 5. 验证
sleep 15 && docker compose logs --tail 40

2.3 回滚

JAVASCRIPT
docker compose down
rm -rf data && cp -a data.bak.时间戳 data
# 修改 docker-compose.yml image 为 hermes-agent:pre-upgrade-时间戳
docker compose up -d

三、日常维护速查

查看日志 docker compose logs --tail 50 -f
重启 docker compose restart
进入容器 docker exec -it hermes-agent bash
查看版本 docker exec hermes-agent grep version /opt/hermes/pyproject.toml
运行诊断 docker exec hermes-agent hermes doctor
一键升级 sudo bash hermes-upgrade.sh

四、架构全景图

JAVASCRIPT
┌────────────────────────────────────────────────────────────┐
│                        群晖 NAS                             │
│                                                            │
│  ┌──────────────────────────────────────────┐              │
│  │          hermes-agent 容器               │              │
│  │                                          │              │
│  │  LLM 主力 ←→ LLM 备用（自动切换）       │              │
│  │  飞书 Bot · 定时任务 · Skills            │              │
│  └────────────┬───────────┬─────────────────┘              │
│       ┌───────▼──────┐    │  CAMOFOX_URL                   │
│       │   ./data/    │    │                                │
│       │ config/SOUL  │    ▼                                │
│       │ memories     │  ┌──────────────────────┐           │
│       └──────────────┘  │  camofox-browser 容器 │           │
│                         │  Camoufox + Xvfb     │           │
│                         │  REST API :9377      │           │
│                         └──────────┬───────────┘           │
│                                    │                       │
│    国内 API（直连）            PROXY_HOST                   │
│    MiniMax / 智谱 等          ↓ mihomo 分流                 │
│                          国内站直连 / 国外站走代理           │
└────────────────────────────────────────────────────────────┘

五、使用感受与建议

优点

  • 🌟 功能极其全面，可能是目前最丰富的开源 AI Agent 框架

  • 🌟 灵活性高：20+ Provider、15+ 消息平台自由组合

  • 🌟 记忆 + 技能闭环学习设计理念先进，实际体验稳定可靠

  • 🌟 社区活跃，Bug 修复快

  • 🌟 Gateway 模式非常适合 NAS 场景

需要注意的地方

  • ⚠️ 核心功能需要配置才能发挥价值：安装完只是一个基础 Bot，需要跟着本系列《Hermes Agent 必做配置与调试》做完配置才能体验到记忆、学习等特色功能。不过这比 OpenClaw 的原生配置已经简单很多，基本上照着文档走一遍就 OK

  • ⚠️ 官方文档偏英文、偏技术向：对国内用户友好度不够（这也是本系列文章存在的原因）

  • ⚠️ 任何 LLM API 变更都可能影响体验：这是所有 Agent 框架（包括 OpenClaw）的共同问题——当上游 LLM 提供商修改了 API 格式（如 OpenAI 调整流式响应结构），Agent 可能会临时出现故障。好在 Hermes 社区响应很快，通常几天内就会修复

建议

  1. 先确认 LLM 选择和网络环境——只用国内 Provider 会简单很多

  2. 新手先用官方预构建镜像——升级只需 docker compose pull

  3. 需要自定义才选源码构建——准备好 1.5+ 小时的构建时间

  4. 务必配置 SOUL.md——这是让 Agent "变成你的 Agent" 的关键

  5. 保持更新——Hermes 迭代非常快

  6. **群晖用户永远记得 **DOCKER_BUILDKIT=0

系列文章总览

第一篇：Hermes Agent 是什么？ 项目介绍、与 OpenClaw 对比、核心能力 ~5 分钟
第二篇：Hermes Agent 群晖 NAS 安装实战 部署方案对比、硬件评估、网络配置、Docker 构建 ~15 分钟
第三篇：Hermes Agent 必做配置与调试 LLM、飞书、人格、记忆、技能、审批、优化 ~15 分钟
第四篇：Hermes Agent 运维手册（本文） 踩坑排查、升级、回滚、日常维护 ~10 分钟

参考链接

Hermes Agent GitHub：github.com/NousResearch/hermes-agent

官方文档：hermes-agent.nousresearch.com/docs/

飞书开放平台：open.feishu.cn

AgentSkills.io（技能市场）：agentskills.io

Nous Research Discord：discord.gg/NousResearch

Mihomo 官方 Wiki：wiki.metacubex.one

原文地址: https://mp.weixin.qq.com/s?__biz=MzY4NDI2MzA0OQ==&mid=2247483675&idx=1&sn=36cc2c9ae143af25032c07173fa6d493&chksm=f2ff64ad9083f65691897d5dc2c0dc990de141d83ac6b5672e236015594fa70eaf62a3270141&mpshare=1&scene=1&srcid=0608JCExMSzB96XVUHEpxbNz&sharer_shareinfo=4171a4b24736800502ac09c5a78777aa&sharer_shareinfo_first=4171a4b24736800502ac09c5a78777aa#rd

相关文章