fnOS 部署 Hermes Agent 保姆级教程-龍騰博客

适用场景：飞牛 fnOS（Docker Compose 方式），本地已有 llama.cpp/Vulkan 推理服务的用户可直接对接本地模型，没有的话教程里也给了云端 API 的备选方案。

一、准备工作

1. 确认前置条件

fnOS 已开启 Docker/容器套件（应用中心 → 搜索"Docker"→ 确认已安装）
存储空间预留至少 10GB（镜像 + 数据）
内存预留：容器本身不重，1-2GB 足够，但要留意跟你现有的 Frigate/CompreFace 等容器叠加后的总占用

2. 开启 SSH（如果还没开）

打开 fnOS 控制台 → 「设置」→「终端和SNMP」
勾选「启用 SSH 服务」
记下端口号（默认 22）
给你的管理账户授权 SSH 权限（fnOS 1.1.19+ 版本需要单独授权）

3. 准备模型接入方式（二选一）

方案 A（推荐，你已有这个环境）：直接用你 SER8 上跑的 llama.cpp/Vulkan 本地服务，走 OpenAI 兼容协议，不用额外申请 API Key
方案 B：注册一个云端模型 API Key（如 DeepSeek、Kimi），作为备选或者对比测试用

二、创建项目目录

打开 fnOS「文件管理」
进入你平时放 Docker 项目的共享文件夹（比如 /vol1/docker/）
新建文件夹，命名为 hermes
在 hermes 文件夹内，再新建一个子文件夹 data（用于持久化 Hermes 的配置和记忆文件，不要跟其他容器共用目录）

目录结构长这样：

/vol1/docker/hermes/
  └── data/

三、编写 docker-compose.yml

在 fnOS 打开「Docker」应用 →「Compose」标签页
点击「新建项目」
项目名称填 hermes
路径选择刚才新建的 /vol1/docker/hermes 文件夹
来源选择「创建 docker-compose.yml」
把下面的内容粘贴进去（路径记得替换成你自己的实际路径）：

services:
  hermes:
    image: nousresearch/hermes-agent:latest
    container_name: hermes
    restart: unless-stopped
    command: gateway run
    stdin_open: true
    tty: true
    ports:
      - "8642-8670:8642-8670"
    volumes:
      - /vol1/docker/hermes/data:/opt/data
    environment:
      - HERMES_HOME=/opt/data
      - TZ=Asia/Shanghai
    mem_limit: 2g

  hermes-webui:
    image: ekkoye8888/hermes-web-ui:latest
    container_name: hermes-webui
    entrypoint: ["node", "dist/server/index.js"]
    depends_on:
      - hermes
    ports:
      - "6060:6060"
    volumes:
      - /vol1/docker/hermes/data:/opt/data
      - /vol1/docker/hermes/data/hermes-web-ui-data:/app/dist/data
    environment:
      - PORT=6060
      - UPSTREAM=http://hermes:8642
      - HERMES_HOME=/opt/data
      - HERMES_BIN=/opt/hermes/.venv/bin/hermes
      - AUTH_DISABLED=false
    mem_limit: 512m
    restart: unless-stopped

⚠️ 重要提醒：

YAML 对缩进极其敏感，复制粘贴后如果报错，检查是不是缩进被打乱了（fnOS 网页粘贴有时会吃掉空格）
AUTH_DISABLED 我改成了 false（社区教程默认是 true，等于关闭登录认证——不建议在内网也这样设置，除非你对内网访问的人完全信任）
mem_limit 是我按你现有内存预算给的建议值，可以根据实际运行情况调整

勾选「创建项目后立即启动」
点击「确认」，等待镜像拉取（第一次可能要几分钟到十几分钟，取决于网络）

四、检查容器状态

回到 Docker 应用的「容器」标签页
确认 hermes 和 hermes-webui 两个容器状态都是绿色的「运行中」
如果有红色/异常状态，点进容器看日志，常见问题：
- 端口冲突（8642-8670 或 6060 被其他容器占用）→ 改左边的宿主机端口
- 路径不存在 → 回去检查 compose 里的路径是否跟你实际创建的目录一致

五、首次登录配置

浏览器打开：http://你的NAS内网IP:6060
默认账号：admin，默认密码：123456
登录后第一件事：立刻改密码（右上角设置或个人中心里改）
首次登录默认没有配置任何大模型，这时候尝试对话会报错，属正常现象，往下走配置模型

六、配置模型

方案 A：接入你的本地 llama.cpp 服务

进入「模型配置」→「添加 Provider」
类型选 OpenAI 兼容（Custom / OpenAI-compatible）
Base URL 填你 SER8 上 llama.cpp 服务的地址，比如 http://192.168.x.x:端口/v1
API Key 可以随便填一个占位符（本地服务通常不校验）
模型 ID 填你实际跑的模型名（比如 Qwen3.6-35B 对应的 model 标识）
保存

方案 B：接入云端 API（如 DeepSeek）

「添加 Provider」→ 选择 DeepSeek（或其他支持的厂商）
粘贴你申请到的 API Key
保存

配置完成后，回到对话界面，发一条测试消息，能正常回复就说明模型接通了。

七、安全加固（务必做）

不要把 6060/8642 端口直接做公网端口转发。Hermes 拥有文件读写、命令执行等高权限，一旦暴露，等于把 NAS 控制权交出去
如果需要远程访问，用你已有的 VPN（Shadowrocket/WireGuard 那套），或者用内网穿透工具做 HTTPS 隧道映射，不要裸暴露端口
AUTH_DISABLED 保持关闭状态（即上面配置里的 false），确保 WebUI 有登录认证
在「模型配置」旁边一般会有「工作目录/权限」设置，务必只授权它能访问必要的文件夹（比如你要它整理的下载目录），不要给整个 NAS 存储的读写权限
定期看容器日志，观察有没有异常的命令执行记录

八、（可选）接入飞书/企业微信等 IM

进入容器终端（Docker 应用里点 hermes 容器 →「终端」）
执行配置命令，例如飞书：

hermes config set feishu_app_id 你的AppID
hermes config set feishu_app_secret 你的AppSecret

重启 hermes 容器使配置生效
具体各平台的 App ID/Secret 需要先去对应平台的开发者后台创建机器人应用获取

九、常见问题

问题	排查方向
对话没反应/报错	检查模型 Provider 是否配置正确，Base URL 能否被容器内部访问到
容器一直重启	看日志，多数是路径权限或环境变量写错
WebUI 打不开	确认端口没被占用，确认容器状态是运行中
内存占用持续升高	检查是否有任务卡死在循环里，必要时降低 mem_limit 让它自然重启

跑起来之后建议先观察一两周的资源占用曲线，跟你现有的 Frigate/CompreFace 等容器互不干扰再考虑扩展更多功能（比如后续要不要再装 OpenClaw 做互补）。

十、上下文参数不匹配问题

Error: Model /models/Qwen3.6-35B-A3B-Uncensored-HauhauCS-Aggressive-Q4_K_M.gguf has a context window of 32,768 tokens, which is below the minimum 64,000 required by Hermes Agent. Choose a model with at least 64K context. If your server reports a window smaller than the model's true window, set model.context_length in config.yaml to the real value (this must be at least 64K).

这是 Hermes Agent 自己的最低要求——它要求接入的模型上下文窗口至少 64K，而你之前为了解决 OOM 把 LLAMA_ARG_CTX_SIZE 从 131072 降到了 32768，正好卡在这条线以下。

不建议的做法

错误提示里说的"在 config.yaml 里改 model.context_length 骗过去"这条路不要走——那只是告诉 Hermes"这个模型有 64K 窗口"，但 llama-server 实际还是按 32768 截断。一旦对话/任务真用到 32K 以上的上下文，服务端会直接报错或截断丢失内容，比现在这个报错更难排查。

正确做法：把真实的 ctx-size 提上去

好消息是你不需要退回到之前 OOM 的 131072，只要满足 Hermes 要求的 64K 下限就行，把 LLAMA_ARG_CTX_SIZE 改成 65536（正好是 131072 的一半，之前 OOM 时你还没加 Docker 内存限制，现在有限制兜底，风险小很多）：

yaml

  qwen36:
    ...
    mem_limit: 26g          # 上下文翻倍，KV cache 也会跟着涨，内存上限适当松一点
    memswap_limit: 26g
    environment:
      ...
      - LLAMA_ARG_CTX_SIZE=65536   # 从 32768 提到满足 Hermes 最低要求的 64K

为什么内存上限也要跟着松一点

KV cache 大小跟上下文长度基本是线性关系，上下文翻倍，KV cache 占用也会接近翻倍。你现在四个容器加起来是 8+24+1+4=37GB，宿主机总共 48GB，理论上还有富余，但之前爆过一次 OOM，建议这次改完先小心观察：

改完执行 docker compose up -d qwen36，只重启这一个服务
用 docker stats llama-qwen36 盯着实际内存占用几分钟，尤其是发几轮长对话之后
如果稳定在 26g 以内没有触顶重启，就没问题；如果又开始逼近上限，再考虑把 LLAMA_ARG_CACHE_TYPE_K/V 压得更狠一点（比如都改成 q4_0）来换取同样上下文下更小的内存占用

改完之后回到 Hermes 的模型配置里重新测试一次，应该就不会再报这个错了。

目录CONTENT

fnOS 部署 Hermes Agent 保姆级教程