QNAP Agent

基于 PicoClaw 的 QNAP QTS 专属 AI 管理助手
以 QPKG 插件形式安装，深度适配 QTS 5.x 非标准 Linux 环境。

为什么要做这个

QNAP QTS 是 QNAP 基于 Linux 内核深度定制的闭源系统，与标准 Linux 差异显著——没有 apt/yum，没有 systemctl，配置路径不一样，大量 QNAP 专有命令。通用 AI 对 QTS 了解有限，经常给出无效甚至危险的操作建议。

这个项目基于自己多年使用QNAP NAS的经验，从中获取一些积累，最终的代码实现、文档整理设计交给 AI Agent 完成。我们要做的是把控安全策略：要求 Agent 在 QNAP 这种非标准 Linux 环境中，以更安全、更稳定、更克制的方式运行，尽量遵循QNAP NAS系统的特有命令代码。

之前有一次郁闷的经历，曾经因为以为给 AI 足够高的系统权限，它可以更好管理系统。当 AI 获得权限的第一时间，为了测试拦截机制是否生效，执行了 rm -rf /，而那次拦截代码恰好有一个变量失效 —— 7T 数据就此消失，数据恢复历时一周。
这让我想起《三体》里章北海拿到"自然选择号"指挥权的第一时间，下令：前进四！

因此 qnap-agent 的核心目标不是让 AI "什么都能做"，而是让 AI 在明确边界内做正确的事。

功能特性

能力 说明
🧠 QTS 专属知识库 内置 QNAP 系统知识技能包，理解 QTS 与标准 Linux 的差异
📁 文件管理 共享文件夹的文件搜索、整理、批量操作、权限管理
🎬 媒体管理 影音文件分析、媒体库整理、格式识别、流媒体服务管理
🐳 Docker 管理 容器部署、状态查询、日志分析、Compose 项目管理
☁️ OpenList 网盘 40+ 存储源文件管理、直链获取、分享链接、离线下载、存储挂载
🔍 系统诊断 QTS 日志分析、磁盘健康、内存/CPU 监控
🔒 命令安全沙箱 基于正则黑白名单拦截危险命令，防止误操作损坏系统
🗑️ 安全删除工具 safe-rm.sh 将文件移至 @Recycle 回收站而非永久删除
📡 MCP 工具集成 通过 QNAP MCP Assistant 无需完整 Shell 权限即可安全操作 NAS
💬 多渠道接入 Web 界面（18800 端口）/ 微信 / QQ Bot / Telegram Bot
⏰ 定时心跳巡检 每 30 分钟自动检查磁盘空间、容器状态、系统日志异常
🔄 持续学习 Agent 将操作中学到的新知识自动整理为技能包，持续积累
♻️ 自升级机制 看门狗自动完成二进制升级与回滚，无需手动干预

系统要求

项目 要求
QNAP QTS 版本 ≥ 5.0.0
CPU 架构 x86_64、arm64、armv7（含 arm-x31 / arm-x41）
内存 建议 ≥ 2GB 可用
存储空间 ≥ 200MB（安装路径）
网络 需能访问外部 LLM API
可选依赖 Container Station（使用 Docker 管理功能时需要）

安装方法

通过 App Center 手动安装

  1. 从 Releases 页面 下载最新 .qpkg 文件
  2. 登录 QTS Web 管理界面，打开 App Center
  3. 右上角齿轮图标 → 手动安装 → 上传 .qpkg 文件
  4. 安装完成后点击打开，浏览器访问 http://NAS-IP:18800
  5. 完成初始配置：
    • 添加至少一个 LLM 模型并设为默认
    • 在 Launcher 中启动 Gateway

配置 LLM 模型

配置文件位于 ${QPKG_ROOT}/workspace/config.json，安装时由模板自动生成，填写 API Key 后即可使用。

推荐的 LLM 服务提供商：

提供商 推荐模型 api_base
火山引擎（豆包） doubao-seed-1.6、doubao-seed-1.6-flash https://ark.cn-beijing.volces.com/api/v3
通义千问（阿里） qwen3-max、qwen3-plus、qwen3-flash https://dashscope.aliyuncs.com/api/v1
DeepSeek（深度求索） deepseek-chat、deepseek-reasoner https://api.deepseek.com
月之暗面 Kimi kimi-k2.5、kimi-k2-thinking https://platform.moonshot.cn/api/v1
智谱 GLM glm-5、glm-4.6、glm-4-flash https://open.bigmodel.cn/api/paas/v4
文心一言（百度） ernie-4.5、ernie-3.5、ernie-speed https://qianfan.baidubce.com/v2
MiniMax MiniMax-M2.7、abab6.5s-chat https://api.minimaxi.com/v1
腾讯混元 hunyuan-large、hunyuan-turbo https://hunyuan.tencentcloudapi.com/v1
OpenAI gpt-4o、gpt-4o-mini https://api.openai.com/v1
Anthropic Claude（via OpenRouter） anthropic/claude-sonnet-4-5 https://openrouter.ai/api/v1

详细配置说明参考 PicoClaw 文档

权限模型

⚠️ 默认封闭原则：安装即锁，按需开锁

安装完成后，Agent 默认没有系统访问权限：

  • ✅ 能访问的：${QPKG_ROOT}/workspace/ 工作目录（沙箱内）
  • ❌ 不能访问的：/share/ 共享文件夹、/etc/config/ 系统配置（未授权前）
  • ❌ 不能执行的：系统包管理、防火墙修改、用户管理、磁盘格式化、固件升级

当你需要 Agent 管理共享文件夹时，需要在 config.json 的 custom_allow_patterns 中手动添加对应路径的授权。你也可以直接命令 Agent 开放对应文件夹权限，Agent 会告知你具体需要修改的配置。

这样设计的目的：NAS 上的数据往往不可替代，"默认开放"会让你在还没搞清楚 Agent 能做什么之前，就已经暴露了全部数据。

MCP Assistant 集成

QNAP 官方推出了 MCP Assistant QPKG，提供基于标准 MCP 协议的 NAS 管理接口。QNAP Agent 已完整集成对 MCP 工具的调用能力。

为什么推荐 MCP 方式

方式 权限要求 安全性 适用场景
MCP 工具调用 只需 Token，无需开放 Shell ✅ 高，细粒度权限 日常查询、文件管理、用户管理
直接 Shell 命令 需要开放沙箱路径 ⚠️ 取决于配置 Docker 管理、复杂脚本

通过 MCP，Agent 可以在不需要完整 Shell 权限的情况下完成绝大多数日常任务，包括：

  • 查询系统状态（CPU、内存、磁盘、温度、进程）
  • 浏览和搜索共享文件夹中的文件
  • 查看系统日志（支持按级别和关键词筛选）
  • 管理用户和用户组
  • 全文搜索文件内容（需安装 Qsirch）

安装与配置

  1. 在 NAS 的 App Center 中加入 Beta 测试计划，搜索并安装 MCP Assistant

    QTS 5.2.0 版本需从官网手动下载 .qpkg 后通过 App Center 手动安装。

  2. 打开 MCP Assistant → Credentials → Create 创建 Token

    • Name：填写便于辨识的名称，如 qnap-agent
    • Key Type：选择 Secret Key
    • Read-only Mode：
      • ☑ 勾选 → 只读权限（日常查询推荐，最安全）
      • ☐ 不勾选 → 完全权限（创建/删除操作时需要）
    • 点击 Create，记录生成的 Token 字符串

  3. 记录 Token 和 NAS 局域网 IP，直接在对话框中告诉 Agent：

    帮我配置 MCP Assistant 连接，NAS IP 是 192.168.x.x，Token 是 xxxx

    Agent 会读取内置的 QNAP MCP 技能文档，无需重启 Agent 即可使用。

安全提示： Token 代表完整用户权限，请勿将其写入代码仓库或公开场合。MCP 服务使用 HTTP 明文（8442 端口），建议仅在局域网内使用。

配置完成后，向 Agent 提问即可，指明以后调用QNAP MCP工具操作：

"帮我看看 NAS 目前磁盘用了多少？"
"在 Public 文件夹里有没有叫'发票'的文件？"
"最近有没有系统错误日志？"
"现在哪个进程 CPU 占用最高？"

详细的工具文档和调用规范见 skills/qnap-mcp/SKILL.md

OpenList 网盘管理集成

QNAP Agent 已完整集成对 OpenList（AList 社区分支）的 HTTP API 调用能力，通过内置的 qnap-openlist 技能包实现对远程网盘、云盘聚合站点的完整文件管理。

为什么集成 OpenList

方式 适用场景 优势
OpenList API 调用 管理网盘聚合站、远程云盘 ✅ 支持 40+ 存储源（阿里云盘、百度网盘、OneDrive、Google Drive、Quark 等）
MCP 工具调用 管理 QNAP 本地共享文件夹 ✅ 细粒度权限、无需开放 Shell
直接 Shell 命令 复杂脚本、Docker 管理 ⚠️ 取决于沙箱配置

通过 OpenList，Agent 可以跨多个云盘统一管理文件，包括：

  • 浏览和搜索所有已添加存储中的文件
  • 获取文件的下载直链（302 重定向或代理下载）
  • 上传、重命名、移动、复制、删除文件
  • 创建分享链接（支持密码和有效期设置）
  • 管理离线下载任务
  • 管理存储挂载点和驱动配置
  • 索引构建与搜索维护

配置与使用

首次使用时，直接告诉 Agent 你的 OpenList 实例信息：

帮我配置 OpenList 连接，地址是 http://192.168.x.x:5244，用户名 admin，密码 xxx

Agent 会执行 login 命令并将凭据保存至 skills/qnap-openlist/openlist-config.json。后续所有操作无需重复认证。

配置完成后，可以直接向 Agent 下达网盘管理指令：

"在阿里云盘里有没有'发票'相关的文件？"
"帮我把 /Quark/report。pdf 复制到 /Backup/ 目录"
"给 /Aliyundrive/photos 目录下的所有 .jpg 文件创建下载直链"
"搜索所有网盘中关键词为'合同'的文件"

详细的命令参考和最佳实践见 skills/qnap-openlist/SKILL.md

安全删除与回收站

执行删除操作时，Agent 优先使用 tools/safe-rm.sh 将文件移至共享文件夹的 @Recycle 回收站，而非永久删除。删除后可通过 File Station 界面恢复文件。

使用安全删除前，需要为共享文件夹开启回收站功能：

控制台 → 共享文件夹 → 编辑每个共享文件夹 → ☑️ 启用回收站

自升级机制

看门狗（watchdog.sh）每 5 分钟检查 update/ 目录：

  • 支持压缩包（.tar.gz、.zip）和直接二进制文件两种投放方式
  • 发现升级包 → 校验可执行性 → 停服务 → 备份旧版本 → 替换 → 重启
  • 升级失败自动回滚到备份版本
  • 重启不影响对话记忆（memory/ 目录完整保留）

默认不开启自动检查更新。 你可以直接让 Agent 检查更新：

"帮我检查一下 qnap-agent 有没有新版本"

Skills 技能库

Agent 在执行操作前会优先查阅技能库，确保在 QTS 非标准环境中使用正确的命令和安全的操作方式。

技能 覆盖内容
qnap-system QTS 与标准 Linux 差异、QNAP 专有命令、路径约定
qnap-storage 存储池、RAID、逻辑卷、磁盘空间分析
qnap-raid RAID 故障排查、降级恢复、磁盘更换流程
qnap-docker Container Station、容器管理、Compose 项目
qnap-media 媒体文件分析、Plex/Emby/Jellyfin、Arr 全家桶
qnap-network 网络诊断、端口查询、Windows 11 SMB 兼容性
qnap-security 安全加固、Deadbolt 勒索病毒应急处理
qnap-backup HBS3、快照策略、3-2-1 备份原则
qnap-ssl Let's Encrypt 证书申请、stunnel 部署
qnap-plugins ZeroTier、Tailscale、OpenList、NPS 等第三方插件
qnap-mcp MCP Assistant 安装配置、24 个工具完整文档
qnap-openlist OpenList 网盘 API 集成、文件管理、分享、离线下载、存储管理
qnap-forbidden 绝对禁止操作清单，防止误操作损坏系统
qnap-learned-* Agent 自动积累的使用经验（持续增长）

下载