QQ Bot 智能提醒
让 AI 帮用户设置、管理定时提醒，支持私聊和群聊。
⛔ 最重要的一条规则（读三遍）
调用 cron 工具时，payload.kind 必须是 "agentTurn"。绝对不能用 "systemEvent"！
systemEvent 只会在 AI 会话里插入一条文本，用户根本收不到 QQ 消息。
只有 agentTurn + deliver: true + channel: "qqbot" + to 才能真正把消息发到 QQ。
🛠️ 两种调用方式
方式一：cron 工具调用（推荐）
如果你的环境中有 cron 工具，使用 JSON 参数直接调用：
cron({
"action": "add",
"job": {
"name": "喝水提醒",
"schedule": { "kind": "at", "atMs": 1770734300000 },
"sessionTarget": "isolated",
"wakeMode": "now",
"deleteAfterRun": true,
"payload": {
"kind": "agentTurn",
"message": "暖心提醒内容",
"deliver": true,
"channel": "qqbot",
"to": "qqbot:c2c:0DEBF031..."
}
}
})
方式二：exec 工具执行 CLI 命令（备用）
⚠️ 如果没有 cron 工具，使用 exec 工具调用 openclaw CLI 命令。
重要区别：CLI 参数名和 JSON API 不一样！
| JSON API 字段 |
CLI 参数 |
action: "add" |
openclaw cron add |
job.schedule.kind: "at" |
--at "30s" 或 --at "2026-03-14T10:00:00Z" |
job.schedule.kind: "cron" |
--cron "0 8 * * *" --tz "Asia/Shanghai" |
job.schedule.atMs |
--at "30s"（相对时间）或 ISO 时间字符串 |
job.sessionTarget: "isolated" |
--session isolated |
job.wakeMode: "now" |
--wake now |
job.deleteAfterRun: true |
--delete-after-run |
job.payload.kind: "agentTurn" |
--message "..." |
job.payload.message |
--message "..." |
job.payload.deliver: true |
--announce |
job.payload.channel: "qqbot" |
--channel qqbot |
job.payload.to |
--to "qqbot:c2c:..." |
CLI 命令示例（一次性提醒）：
exec({
command: 'openclaw cron add --name "喝水提醒" --at "30s" --session isolated --wake now --delete-after-run --announce --channel qqbot --to "qqbot:c2c:0DEBF031A9738F49D0194257976D7BAE" --message "你是一个暖心的提醒助手。请用温暖、有趣的方式提醒用户：该喝水了。要求：(1) 不要回复HEARTBEAT_OK (2) 不要解释你是谁 (3) 直接输出一条暖心的提醒消息 (4) 可以加一句简短的鸡汤或关怀的话 (5) 控制在2-3句话以内 (6) 用emoji点缀"'
})
CLI 命令示例（周期提醒）：
exec({
command: 'openclaw cron add --name "打卡提醒" --cron "0 8 * * *" --tz "Asia/Shanghai" --session isolated --wake now --announce --channel qqbot --to "qqbot:c2c:0DEBF031A9738F49D0194257976D7BAE" --message "你是一个暖心的提醒助手。请用温暖、有趣的方式提醒用户：该打卡了。要求：(1) 不要回复HEARTBEAT_OK (2) 不要解释你是谁 (3) 直接输出一条暖心的提醒消息 (4) 可以加一句简短的鸡汤或关怀的话 (5) 控制在2-3句话以内 (6) 用emoji点缀"'
})
查询提醒（CLI）：
exec({ command: 'openclaw cron list --json' })
删除提醒（CLI）：
exec({ command: 'openclaw cron rm <job-id>' })
⚠️ CLI 时间格式特殊说明：
如何选择？
- 优先使用
cron 工具（如果可用）
- 如果
cron 工具不可用，用 exec 执行 CLI 命令
- 可以通过
openclaw cron add --help 查看完整参数列表
🤖 AI 决策指南
时间确认规则
设置提醒前，先确认当前系统时间（查看上下文中的时间信息，或执行 date）。
纯相对时间（"5分钟后"、"1小时后"）可以跳过确认，直接算 Date.now() + 延迟毫秒。
用户意图识别
| 用户说法 |
意图 |
cron 工具 action |
| "5分钟后提醒我喝水" |
创建一次性提醒 |
add（schedule.kind=at） |
| "每天8点提醒我打卡" |
创建周期提醒 |
add（schedule.kind=cron） |
| "我有哪些提醒" |
查询 |
list |
| "取消喝水提醒" |
删除 |
remove |
| "修改提醒时间" |
删除+重建 |
remove → add |
| "提醒我" (无时间) |
需追问 |
询问具体时间 |
必须追问的情况
- 没有时间："提醒我喝水" → "请问什么时候提醒你？"
- 时间模糊："晚点提醒我" → "具体几点呢？"
- 周期不明："定期提醒我" → "多久一次？每天？每周？"
📋 创建提醒（最重要）
🚨🚨🚨 工具调用参数模板（AI 必须严格遵循）
AI 调用 cron 工具时，传的是 JSON 参数，不是 CLI 命令。以下是唯一正确的 JSON 格式：
一次性提醒（N 分钟后）：
{
"action": "add",
"job": {
"name": "{任务名}",
"schedule": {
"kind": "at",
"atMs": {当前时间戳毫秒 + N分钟*60000}
},
"sessionTarget": "isolated",
"wakeMode": "now",
"deleteAfterRun": true,
"payload": {
"kind": "agentTurn",
"message": "你是一个暖心的提醒助手。请用温暖、有趣的方式提醒用户：{提醒内容}。要求：(1) 不要回复HEARTBEAT_OK (2) 不要解释你是谁 (3) 直接输出一条暖心的提醒消息 (4) 可以加一句简短的鸡汤或关怀的话 (5) 控制在2-3句话以内 (6) 用emoji点缀",
"deliver": true,
"channel": "qqbot",
"to": "{openid}"
}
}
}
周期提醒（每天/每周）：
{
"action": "add",
"job": {
"name": "{任务名}",
"schedule": {
"kind": "cron",
"expr": "0 8 * * *",
"tz": "Asia/Shanghai"
},
"sessionTarget": "isolated",
"wakeMode": "now",
"payload": {
"kind": "agentTurn",
"message": "你是一个暖心的提醒助手。请用温暖、有趣的方式提醒用户：{提醒内容}。要求：(1) 不要回复HEARTBEAT_OK (2) 不要解释你是谁 (3) 直接输出一条暖心的提醒消息 (4) 可以加一句简短的鸡汤或关怀的话 (5) 控制在2-3句话以内 (6) 用emoji点缀",
"deliver": true,
"channel": "qqbot",
"to": "{openid}"
}
}
}
🚨 绝对不可更改的 5 个字段（改了提醒就废了）：
payload.kind 必须是 "agentTurn" — ❌ 绝对不能用 "systemEvent"payload.deliver 必须是 truepayload.channel 必须是 "qqbot"payload.to 必须是用户的 openidsessionTarget 必须是 "isolated"
🚫 payload.kind: "systemEvent" 只会在 AI 会话中注入文本，不会发送 QQ 消息给用户！
⚠️ schedule.atMs 必须是绝对毫秒时间戳（如 1770733800000），不支持相对时间字符串如 "5m"！
需要自行计算：当前时间戳 + 延迟毫秒数。例如 5 分钟后 = Date.now() + 5 * 60 * 1000。
查询提醒
使用 cron 工具 action: "list" 查询。
删除提醒
使用 cron 工具 action: "remove" + jobId。
💬 用户交互模板
创建提醒后的反馈要简洁友好，不要啰嗦
创建成功反馈（推荐简洁版）
一次性提醒：
⏰ 好的，{时间}后提醒你{提醒内容}~
周期提醒：
⏰ 收到，{周期描述}提醒你{提醒内容}~
查询提醒反馈
📋 你的提醒：
1. ⏰ {提醒名} - {时间}
2. 🔄 {提醒名} - {周期}
说"取消xx提醒"可删除~
无提醒时反馈
📋 目前没有提醒哦~
说"5分钟后提醒我xxx"试试？
删除成功反馈
✅ 已取消"{提醒名称}"
⏱️ 时间格式
一次性提醒（schedule.kind = "at"）
⚠️ schedule.atMs 只接受绝对毫秒时间戳，需要自己计算！
| 用户说法 |
计算方式 |
| 5分钟后 |
Date.now() + 5 * 60 * 1000 |
| 半小时后 |
Date.now() + 30 * 60 * 1000 |
| 1小时后 |
Date.now() + 60 * 60 * 1000 |
| 明天早上8点 |
先确认当前日期，计算目标时间的毫秒时间戳 |
周期提醒（schedule.kind = "cron"）
必须加 "tz": "Asia/Shanghai"
| 用户说法 |
schedule.expr |
| 每天早上8点 |
"0 8 * * *" |
| 每天晚上10点 |
"0 22 * * *" |
| 每个工作日早上9点 |
"0 9 * * 1-5" |
| 每周一早上9点 |
"0 9 * * 1" |
| 每周末上午10点 |
"0 10 * * 0,6" |
| 每小时整点 |
"0 * * * *" |
📌 参数说明
工具调用 job 对象必填字段
| 字段 |
说明 |
示例 |
job.name |
任务名 |
"喝水提醒" |
job.schedule.kind |
"at" 或 "cron" |
"at" |
job.schedule.atMs |
绝对毫秒时间戳（不支持 "5m"！） |
1770734100000 |
job.sessionTarget |
必须 "isolated" |
"isolated" |
job.wakeMode |
推荐 "now" |
"now" |
job.payload.kind |
必须 "agentTurn"（❌ 不能用 "systemEvent"） |
"agentTurn" |
job.payload.message |
以 [直接输出] 开头 |
"[直接输出] 💧 喝水时间到！" |
job.payload.deliver |
必须 true |
true |
job.payload.channel |
必须 "qqbot" |
"qqbot" |
job.payload.to |
用户 openid |
从系统消息获取 |
job.deleteAfterRun |
一次性任务必须 true |
true |
payload.message 暖心提醒模板
💡 payload.message 是一个 prompt，告诉 AI 以暖心方式生成提醒。每次触发时 AI 会自由发挥，生成不重复的、有温度的提醒消息。
统一模板（把 {提醒内容} 替换成具体事项）：
你是一个暖心的提醒助手。请用温暖、有趣的方式提醒用户：{提醒内容}。要求：(1) 不要回复HEARTBEAT_OK (2) 不要解释你是谁 (3) 直接输出一条暖心的提醒消息 (4) 可以加一句简短的鸡汤或关怀的话 (5) 控制在2-3句话以内 (6) 用emoji点缀
效果举例（每次触发内容都不同）：
- 喝水提醒 →
💧 嘿，该喝水啦～身体是革命的本钱，水是身体的燃料！
- 开会提醒 →
📅 会议时间到～带上你的好想法，闪亮登场吧！
- 吃饭提醒 →
🍜 干饭时间到！再忙也要好好吃饭，你值得被善待～
- 打卡提醒 →
🌅 新的一天，记得打卡哦～每一天都是新的开始！
为什么用 prompt 而不是固定文本？
- 固定文本太死板，每次都一样，像机器人
- 用 prompt 让 AI 自由发挥，每次提醒都暖心且不重复
🎯 使用场景示例
场景1：一次性提醒
用户: 5分钟后提醒我喝水
AI 调用 cron 工具（假设当前时间戳为 1770734000000）:
{
"action": "add",
"job": {
"name": "喝水提醒",
"schedule": { "kind": "at", "atMs": 1770734300000 },
"sessionTarget": "isolated",
"wakeMode": "now",
"deleteAfterRun"
