ChatOps 快速开始

pt-tools 内置了一套 ChatOps 层，让你可以通过 QQ 私聊 或 Telegram 私聊 随时查看下载状态、控制任务、接收事件通知，不需要打开浏览器。

---

简介

ChatOps 的核心思路和 Hermes / MoviePilot 类似：在你熟悉的 IM 里对 bot 发一条命令，bot 调用 pt-tools 内部服务并回复结果。整个交互都在私聊里发生，不需要暴露 Web UI 端口。

功能亮点：

• 内置命令覆盖状态查询、种子控制、任务管理和站点签到
• 绑定后才能使用，只有用绑定码完成绑定的账号才能执行命令；QQ 和 Telegram 通道还会先按通道里的名单过滤发送者
• 绑定码机制，8 字符一次性码，默认 5 分钟有效（可选 1 小时到永久），通过 Web UI 生成再发给需要绑定的用户
• 操作审计，每条命令的执行结果、延迟、触发用户全部记录到 action_audit 表
• AES-GCM 加密落库，Bot Token / Access Token 等凭证加密存储，截图不泄漏明文
• 出站推送，除命令回复外，还能把系统事件（种子推送成功、磁盘告警等）主动推送到 IM

---

支持的通道

通道	协议	入站命令	出站推送	推荐场景
QQ OneBot	OneBot v11 反向 WebSocket	✅	✅	国内用户、日常 QQ 就是主要 IM
Telegram	Bot API 长轮询	✅	✅	海外用户、需要对接外网通知
企业微信群机器人	企业微信 Webhook	❌	✅	出站推送（群内告警），见更多通知通道
钉钉 / 飞书群机器人	Webhook（可加签）	❌	✅	出站推送，见更多通知通道
Bark / Server 酱 / ntfy	各自的推送接口	❌	✅	推到手机，见更多通知通道
通用 Webhook ⚠️	HMAC-SHA256 HTTP	❌	🧪 实验性	自定义集成、接入 n8n / Zapier 等；代码已实现，尚未端到端验证

入站命令（IM→pt-tools）需要双向连接，Webhook 类通道只支持单向出站推送。

---

选择哪个通道？

需要在 IM 里发命令控制 pt-tools？
│
├── 是 → 国内用 QQ 作为主要 IM？
│        ├── 是 → QQ OneBot (NapCat)  →  docs/guide/chatops-qq-napcat.md
│        └── 否 → 能访问 Telegram？
│                  ├── 是 → Telegram Bot  →  docs/guide/chatops-telegram.md
│                  └── 否 → 挂代理后再用 Telegram
│
└── 只需要出站通知（事件推送到群）？
     ├── 企业微信、钉钉、飞书群 → 对应的群机器人（docs/guide/notify-channels.md）
     ├── 推到手机 → Bark、Server 酱或 ntfy（docs/guide/notify-channels.md）
     └── 自定义系统 → 配置 Generic Webhook

---

内置命令清单

所有命令均以 / 开头，在私聊窗口发送。命令不区分大小写。

命令	Command (EN)	说明	权限
/help	/help	列出所有可用命令及用法	普通
/status	/status	系统运行状态：速度、磁盘、活跃任务数	普通
/version	/version	当前版本及最新可用版本	普通
/tasks	/tasks	RSS 任务列表及运行状态	普通
/sites	/sites	已配置站点摘要（名称、类型）	普通
/torrents	/torrents	按下载器分页列出种子	普通
/pause <hash>	/pause <hash>	暂停指定种子（支持 hash 前缀）	管理员
/resume <hash>	/resume <hash>	恢复指定种子	管理员
/delete <hash>	/delete <hash>	删除种子（带二次确认）	管理员
/signin [站点]	/signin [site]	立即签到；不带站点时签到所有开启了自动签到、当天尚无结果的站点	管理员
/bind <code>	/bind <code>	凭 8 字符绑定码将当前账号绑定到 pt-tools	任何人
/unbind	/unbind	解除当前账号的绑定	管理员
/addrss	/addrss	互动添加 RSS 订阅（文本向导，或单行 /addrss 站点 | 名 | URL | 下载器）	管理员
/delrss	/delrss	互动删除 RSS 订阅（先列出，再按名称/ID/序号选择删除）	管理员
/sub <关键词>	/sub <title>	在 TMDB 上搜电影或剧集，回复编号订阅（剧集可加季号），见追剧与订阅	管理员
/follow <剧名>	/follow <show>	在 TMDB 上搜剧集，回复编号开始追（可加季号），按播出时间搜索、开着版本锁；也可以写 /追剧	管理员
/subs	/subs	列出订阅：编号、进度（缺几集、在等版本的）、下次搜索的时间	普通
/runs <编号>	/runs <id>	一个订阅最近 5 次运行：找到了什么、为什么没要、推送了哪个；编号见 /subs	普通
/today	/today	今天订阅里播出的集与上映的电影，各自入库了没有；也可以写 /今日，见订阅日历	普通
/unlock <编号> <集号>	/unlock <id> <episode>	追剧的这一集换版本（不受版本锁限制），马上搜一次	管理员
/newchat	/newchat	AI 助手开一个新对话，之后的消息不带以前的上下文，见 AI 助手	普通

速率限制：默认每用户每分钟最多 10 条命令，超出后静默丢弃（不回复错误，防止信息泄露）。

AI 助手：在「系统 → AI 助手设置」打开「通知渠道（ChatOps）」以后，不以 / 开头的消息交给 AI 助手回答，改动类操作回复「确认」才执行，见 AI 助手。没打开时这类消息只收到「只识别命令」的提示。

重要

目前每个完成绑定的账号都拥有管理员权限，表中标为「管理员」的命令对所有已绑定账号可用。请只把绑定码发给你信任的账号，不再需要时在 ChatOps → ChatOps 绑定 中撤销。

---

开始配置

根据你选择的通道，继续阅读对应的详细指南：

• QQ (NapCat) → chatops-qq-napcat.md
• Telegram → chatops-telegram.md

配置完成后，建议打开 Web UI 的操作审计页面（/chatops/audit），确认命令正常执行并被记录。

Web UI → ChatOps → 消息通知，可以看到已配置的 QQ 和 Telegram 通道

Web UI → ChatOps → 操作审计，展示今日命令数、成功率和最近记录

查看审计日志

操作审计除了命令、App 与 MCP 的写操作，还记下每一次后台通知的投递：每日战报、签到、追剧与订阅、保号提醒、失效种子、远程访问等通知发给哪个通道、成功还是失败、失败的原因（例如「QQ 通道无可用收件人」「Telegram 网络超时」）。通知失败会按退避重试，每一次尝试各记一条，最后一次标明不再重试；原因里的 bot token、Cookie 之类的凭据会被遮住。

• 工具栏的「类型」可以只看「消息通知」或只看「命令与接口」；通知的「命令」列写成「每日战报」「签到」「追剧」这样的来源名。
• 「消息通知」页的「最近的通知」也写着没发出去的那几条的原因。
• 接口：GET /api/chatops/audit?category=notify|action（notify 只要通知投递，action 是其余的记录）。

---

RSS 上新通知

通道配好后，你还可以让 pt-tools 在 RSS 拉到新种时主动推送给你：

• all 模式：任何上新都告诉你（仅用 feed 字段，无额外站点请求）
• filtered 模式：仅在过滤规则命中时通知（适合追剧 / 挑蓝光）
• both 模式：两路都开，filtered 命中时自动 supersede 同种子的 all 通知

支持静默时段（HH:MM 跨午夜）、30s digest 合并、指数退避重试、Telegram 内联按钮（立即下载 / 忽略）等。

详见 → RSS 上新通知