> 规范网页：https://docs.tensuu.com/功能模块详解/12_定时任务.html ｜ Markdown：/功能模块详解/12_定时任务.md ｜ 文档修订：2026.10.26

# 定时任务

这篇帮你做什么：让机器人在设定时间 **自动往群里发一条消息**，或 **定时开/关全群禁言**。任务按群独立配置。入口：**侧边栏 → 群设置 → 定时任务**。

## 适用与不适用

| 你想做的事 | 是否适合本页 | 原因 |
| --- | --- | --- |
| 每天固定时间发一条提醒或公告 | 适合 | 选“发消息 + 每天定时” |
| 每隔一段时间重复发消息 | 适合 | 选“循环执行”，注意按间隔触发，不按整点对齐 |
| 定时开启或关闭全群禁言 | 适合 | 选“全群禁言”，影响群内所有人 |
| 给某个人定时私聊 | 不适合 | 本页只向当前群发送或操作全群禁言 |
| 发送失败后自动补发 | 不适合 | 没有自动补发保证，失败或未知时按结果入口核对 |
| 按群成员昵称等变量生成个性化内容 | 不适合 | 定时任务只有有限的变量可用，详见下方 |

## 作用范围与工作方式

- 任务属于顶部所选的群；只对该群执行。换群后看到的是另一个群的独立任务列表。
- 增、改、删、启停都是**即时持久化**的；顶部群选择框旁的 **保存** 只用于刷新列表并确认已落库，不是提交开关。
- 调度由服务端按 cron 表达式执行，时间按**服务器本地时区**计算。任务保存成功不代表已经到点；到点触发也不代表消息已送达。
- “发消息”走群消息发送动作；“全群禁言”操作的是整个群的禁言状态，不是禁言某个人，且要求机器人在该群有相应管理权限。
- 同一时刻的多个任务会各自执行；本页不提供任务之间的互斥或依赖。

## 添加一个任务

1. 点右上角 **添加任务**。
2. 填写：
   - **任务内容**（必填，100 字以内）：给自己看的备注，不会发到群里。
   - **执行方式**：发消息 / 全群禁言。
     - 选 **发消息**：填写 **发送信息**（必填，500 字以内），到点发送到当前群。
     - 选 **全群禁言**：选择 **禁言动作**——“开启全群禁言”或“关闭全群禁言”。注意这是整个群的开/关，**不是**禁言某个人。
   - **是否启用**：默认开启；关闭的任务不会执行。
   - **调度方式**（四选一）：
     - **循环执行**：从任务注册或调度器启动起，每隔一段固定时间执行一次。默认间隔 60 分钟，可填 1–1440，单位支持分钟/小时/天。
     - **每天定时**：每天固定时刻（时：分）执行一次。
     - **一次性执行**：指定某天某时刻执行。
     - **Crontab 专业模式**：按 cron 表达式定时。界面示例使用“分 时 日 月 周”五段，系统会补上秒位；也接受六段“秒 分 时 日 月 周”表达式。
   - **开始时间 / 结束时间**：可选填。**这两项只作记录展示，到期后任务不会自动停用**，到期请手动禁用或删除任务。
3. 点 **确认** 保存，列表出现新任务。

**怎样确认成功**：列表里能看到任务，“执行时间”列显示了按调度方式算出的计划（如“每天08:00执行”“每60minutes（00:00-23:59）”），启用状态为开。这一列是计划，不是实际执行记录。

## 设置项参考

| 字段 | 含义与取值 | 单位/默认 | 作用与限制 |
| --- | --- | --- | --- |
| 任务内容 | 维护备注 | 最多 100 字 | 不会发送到群 |
| 执行方式 | 发消息 / 全群禁言 | 无持久默认 | 决定执行动作 |
| 发送信息 | 到点发送的正文 | 最多 500 字 | 仅发消息方式使用 |
| 禁言动作 | 开启 / 关闭全群禁言 | 无持久默认 | 只影响整个群，不是单人禁言 |
| 是否启用 | 开 / 关 | 新建默认开 | 关闭后不再调度 |
| 调度方式 | 循环 / 每天 / 一次性 / Crontab | 无持久默认 | 决定 cron 表达式 |
| 执行间隔 | 1–1440 | 默认 60 分钟 | 仅循环执行；分钟/小时/天 |
| 每天执行时间段 | 开始–结束时间 | 默认 00:00–23:59 | **当前只作展示，不限制实际执行时段** |
| 每天执行时间 | 时:分 | 无 | 仅每天定时 |
| 执行时间 | 指定日期与时刻 | 无 | 仅一次性 |
| Crontab 表达式 | 5 段或 6 段 cron | 无 | 按服务器时区解释 |
| 开始/结束时间 | 记录用有效期 | 可空 | **不会自动停用任务** |

## 发送信息里的变量

“发消息”正文按文本模板处理，可使用：

| 变量 | 定时任务中的实际值 |
| --- | --- |
| `{{.group_id}}` | 当前任务所属群的协议层群号 |
| `{{.user_id}}` | 空；定时任务没有发起成员 |
| `{{.trigger_keyword}}` | 空；不是关键词触发 |

写法错误（如括号未闭合）时，系统会回退为发送原文并记录日志，不会阻止发送；变量名不存在时通常渲染为空字符串。因此不要用 `{{.nickname}}` 一类成员变量期待个性化内容。完整语法边界见[变量使用指南](../高级功能/变量使用指南.md#定时任务)。

## 日常管理

- **启用/禁用**：行内开关，或 **操作 → 禁用/启用**。禁用后不再执行；重新启用恢复。
- **编辑**：修改任意字段后保存即按新计划执行。
- **删除**：确认后任务移除，不再执行。
- **上次执行时间** 列：只显示最近一次被调度器触发的时间，**不是历史执行账本**；它在真正发送前写入，表示“调度器发起了这次尝试”，**不代表路由选择成功，也不代表消息一定发送成功**。
- 服务重启后，只有处于启用状态的任务会继续按计划执行。

## 怎样查执行结果

本页不是完整的结果账本，按下面顺序分开核对：

| 要确认什么 | 去哪里看 | 能证明什么 |
| --- | --- | --- |
| 调度是否触发过 | 本页“上次执行时间” | 调度器发起过本次尝试；不证明发送成功 |
| 计划时间是否正确 | 本页“执行时间”列 | 按当前配置算出的计划；不是实际执行时间 |
| 出站走到哪一步 | 日志中心 → 调试 / 出站结果，按事件群号或关联信息查询 | 短期进程内 Trace，可看排队、派发等阶段；过期、容量淘汰或重启后可能消失 |
| 程序或连接错误 | 日志中心 → 应用日志 | 对应时间的错误与连接异常 |

**不要用群聊监控的“最近触发记录”核对定时任务**：那里记录的是关键词、刷屏、识别和群员事件等监控触发，不覆盖定时任务。空结果也不能单独证明任务没有执行。详见[结果判断与排障](../核心概念/结果判断与排障.md#结果入口)。

## 已知边界

- **循环执行的“每天执行时间段”不限制实际执行时段**：任务按固定间隔从注册/启动时刻起触发，不会只在时间段内执行，也不保证整点对齐。如需固定在某个时刻，请改用“每天定时”。
- **一次性任务**只按“日 + 月”生成 cron；如果指定日期已经过去，仍可能在以后的每年同一日期时间再次触发。执行过一次后建议立即禁用或删除。
- **开始/结束时间**不会自动停用任务。
- 任务发送失败或结果未知时没有自动重试保证；不要在结果不明时反复新增同一任务。

正例：每天 09:00 发一条固定提醒，开始/结束时间留空，保存后核对“执行时间”为每天 09:00；到点后先看“上次执行时间”，再看调试/出站结果，最后在测试群确认实际消息。反例：设置循环 60 分钟并填写 09:00–18:00，期待只在白天执行——当前时间段不参与调度。

## 停止定时任务，或改回设置 {#关闭或改回}

- 临时停止定时任务：关闭目标任务的行内开关，刷新列表确认仍为关闭；不需要另外点顶部“保存”来提交开关。
- 不再保留任务：删除目标任务，刷新确认它已移除。
- 停用或删除只阻止后续调度，不能保证已经触发或在途的那次尝试被取消。已经发出的消息或已经执行的全群禁言状态不会自动恢复；需解除全群禁言时，先核对平台当前状态和原尝试结果，再按需要另建“关闭全群禁言”任务或手动解除。

## 和其他页面的关系

- 定时任务与关键词监控、问答、转发不是同一条匹配链；不要把定时发送当成“到点触发某条监控规则”。
- 发送正文的模板边界见[变量使用指南](../高级功能/变量使用指南.md#定时任务)。
- 配置范围与生效方式见[群管家怎样工作](../核心概念/工作方式与作用范围.md#作用范围)。
- 任务涉及成员处罚或禁言时，先核对[权限管理](../高级功能/权限管理.md)和机器人平台权限。