---
name: qqbot-cron
description: QQ Bot 智能提醒技能。支持一次性提醒、周期性任务、自动降级确保送达。可设置、查询、取消提醒。
metadata: {"clawdbot":{"emoji":"⏰"}}
---

# QQ Bot 智能提醒

让 AI 帮用户设置、管理定时提醒，支持私聊和群聊。

---

## 🤖 AI 决策指南

> **本节专为 AI 理解设计，帮助快速决策**

### 用户意图识别

| 用户说法 | 意图 | 执行动作 |
|----------|------|----------|
| "5分钟后提醒我喝水" | 创建提醒 | `openclaw cron add` |
| "每天8点提醒我打卡" | 创建周期提醒 | `openclaw cron add --cron` |
| "我有哪些提醒" | 查询提醒 | `openclaw cron list` |
| "取消喝水提醒" | 删除提醒 | `openclaw cron remove` |
| "修改提醒时间" | 删除+重建 | 先 remove 再 add |
| "提醒我" (无时间) | **需追问** | 询问具体时间 |

### 必须追问的情况

当用户说法**缺少以下信息**时，**必须追问**：

1. **没有时间**："提醒我喝水" → 询问"请问什么时候提醒你？"
2. **时间模糊**："晚点提醒我" → 询问"具体几点呢？"
3. **周期不明**："定期提醒我" → 询问"多久一次？每天？每周？"

### 无需追问可直接执行

| 用户说法 | 理解为 |
|----------|--------|
| "5分钟后" | `--at 5m` |
| "半小时后" | `--at 30m` |
| "1小时后" | `--at 1h` |
| "明天早上8点" | `--at 2026-02-02T08:00:00+08:00` |
| "每天早上8点" | `--cron "0 8 * * *"` |
| "工作日9点" | `--cron "0 9 * * 1-5"` |

---

## 📋 命令速查

### 创建提醒（完整模板）

```bash
openclaw cron add \
  --name "{任务名}" \
  --at "{时间}" \
  --message "🔔 {提醒内容}时间到！" \
  --deliver \
  --channel qqbot \
  --to "{openid}" \
  --delete-after-run
```

> ⚠️ **极其重要**：
> - `--message` 参数直接写最终要发送的提醒内容
> - 提醒内容格式：`🔔 {内容}时间到！`
> - **不要**使用 `--system-prompt` 或 `--system-event`（cron 不支持这些参数）
> - 保持消息简洁，如：`🔔 喝水时间到！`、`📅 开会时间到！`

> ⚠️ **注意**：`cron add` 命令不支持 `--reply-to` 参数。提醒消息将作为主动消息直接发送给用户。

### 查询提醒列表

```bash
openclaw cron list
```

### 删除提醒

```bash
openclaw cron remove {jobId}
```

### 立即发送消息（主动消息）

```bash
openclaw message send \
  --channel qqbot \
  --target "{openid}" \
  --message "{消息内容}"
```

### 立即发送消息（被动回复）

```bash
openclaw message send \
  --channel qqbot \
  --target "{openid}" \
  --reply-to "{message_id}" \
  --message "{消息内容}"
```

> ⚠️ **注意**：`--reply-to` 仅在 `message send` 命令中支持，且 message_id 必须在 1 小时内有效。定时提醒不支持被动回复。

---

## 💬 用户交互模板

> **创建提醒后的反馈要简洁友好，不要啰嗦**

### 创建成功反馈（推荐简洁版）

**一次性提醒**：
```
⏰ 好的，{时间}后提醒你{提醒内容}~
```

**周期提醒**：
```
⏰ 收到，{周期描述}提醒你{提醒内容}~
```

### 查询提醒反馈

```
📋 你的提醒：

1. ⏰ {提醒名} - {时间}
2. 🔄 {提醒名} - {周期}

说"取消xx提醒"可删除~
```

### 无提醒时反馈

```
📋 目前没有提醒哦~

说"5分钟后提醒我xxx"试试？
```

### 删除成功反馈

```
✅ 已取消"{提醒名称}"
```

---

## ⏱️ 时间格式

### 相对时间（--at）

> ⚠️ **不要加 + 号！** 用 `5m` 而不是 `+5m`

| 用户说法 | 参数值 |
|----------|--------|
| 5分钟后 | `5m` |
| 半小时后 | `30m` |
| 1小时后 | `1h` |
| 2小时后 | `2h` |
| 明天这时候 | `24h` |

### 绝对时间（--at）

| 用户说法 | 参数值 |
|----------|--------|
| 今天下午3点 | `2026-02-01T15:00:00+08:00` |
| 明天早上8点 | `2026-02-02T08:00:00+08:00` |
| 2月14日中午 | `2026-02-14T12:00:00+08:00` |

### Cron 表达式（--cron）

| 用户说法 | Cron 表达式 | 必须加 `--tz "Asia/Shanghai"` |
|----------|-------------|------------------------------|
| 每天早上8点 | `0 8 * * *` | ✅ |
| 每天晚上10点 | `0 22 * * *` | ✅ |
| 每个工作日早上9点 | `0 9 * * 1-5` | ✅ |
| 每周一早上9点 | `0 9 * * 1` | ✅ |
| 每周末上午10点 | `0 10 * * 0,6` | ✅ |
| 每小时整点 | `0 * * * *` | ✅ |

---

## 📌 参数说明

### 必填参数

| 参数 | 说明 | 示例 |
|------|------|------|
| `--name` | 任务名，含用户标识 | `"喝水提醒"` |
| `--at` / `--cron` | 触发时间（二选一） | `5m` / `0 8 * * *` |
| `--message` | **提醒内容**（见下方模板） | `"🔔 喝水时间到！"` |
| `--deliver` | 启用投递 | 固定值 |
| `--channel qqbot` | QQ 渠道 | 固定值 |
| `--to` | 接收者 openid | 从系统消息获取 |

### 推荐参数

| 参数 | 说明 | 何时使用 |
|------|------|----------|
| `--delete-after-run` | 执行后删除 | **一次性任务必须** |
| `--tz "Asia/Shanghai"` | 时区 | **周期任务必须** |

### --message 提醒内容模板（最关键）

> ⚠️ **`--message` 的内容会直接发送给用户**，所以要写清楚提醒内容！

**模板格式**：
```
--message "🔔 {提醒内容}时间到！"
```

**示例**：
- 喝水：`--message "💧 喝水时间到！"`
- 开会：`--message "📅 开会时间到！"`
- 打卡：`--message "🌅 打卡时间到！"`
- 日报：`--message "📝 写日报时间到！"`

**为什么这样写？**
- 消息内容会直接发送，不经过 AI 处理
- 保持简洁，一目了然

---

## 🎯 使用场景示例

### 场景1：一次性提醒

**用户**: 5分钟后提醒我喝水

**AI 执行**:
```bash
openclaw cron add \
  --name "喝水提醒" \
  --at "5m" \
  --message "💧 喝水时间到！" \
  --deliver \
  --channel qqbot \
  --to "{openid}" \
  --delete-after-run
```

**AI 回复**:
```
⏰ 好的，5分钟后提醒你喝水~
```

**5分钟后用户收到**:
```
💧 喝水时间到！
```

---

### 场景2：每日周期提醒

**用户**: 每天早上8点提醒我打卡

**AI 执行**:
```bash
openclaw cron add \
  --name "打卡提醒" \
  --cron "0 8 * * *" \
  --tz "Asia/Shanghai" \
  --message "🌅 打卡时间到！" \
  --deliver \
  --channel qqbot \
  --to "{openid}"
```

**AI 回复**:
```
⏰ 收到，每天早上8点提醒你打卡~
```

> 💡 周期任务**不加** `--delete-after-run`

---

### 场景3：工作日提醒

**用户**: 工作日下午6点提醒我写日报

**AI 执行**:
```bash
openclaw cron add \
  --name "日报提醒" \
  --cron "0 18 * * 1-5" \
  --tz "Asia/Shanghai" \
  --message "📝 写日报时间到！" \
  --deliver \
  --channel qqbot \
  --to "{openid}"
```

**AI 回复**:
```
⏰ 收到，工作日下午6点提醒你写日报~
```

---

### 场景4：会议提醒

**用户**: 3分钟后提醒我开会

**AI 执行**:
```bash
openclaw cron add \
  --name "开会提醒" \
  --at "3m" \
  --message "📅 开会时间到！" \
  --deliver \
  --channel qqbot \
  --to "{openid}" \
  --delete-after-run
```

**AI 回复**:
```
⏰ 好的，3分钟后提醒你开会~
```

**3分钟后用户收到**:
```
📅 开会时间到！
```

---

### 场景5：群组提醒

**用户**（群聊）: 每天早上9点提醒大家站会

**AI 执行**:
```bash
openclaw cron add \
  --name "站会提醒" \
  --cron "0 9 * * 1-5" \
  --tz "Asia/Shanghai" \
  --message "📢 站会时间到！" \
  --deliver \
  --channel qqbot \
  --to "group:{group_openid}"
```

> 💡 群组使用 `group:{group_openid}` 格式

---

### 场景6：查询提醒

**用户**: 我有哪些提醒？

**AI 执行**:
```bash
openclaw cron list
```

**AI 回复**（根据返回结果）:
```
📋 你的提醒：

1. ⏰ 喝水提醒 - 3分钟后
2. 🔄 打卡提醒 - 每天08:00

说"取消xx提醒"可删除~
```

---

### 场景7：取消提醒

**用户**: 取消打卡提醒

**AI 执行**:
1. 先执行 `openclaw cron list` 找到对应任务 ID
2. 执行 `openclaw cron remove {jobId}`

**AI 回复**:
```
✅ 已取消"打卡提醒"
```

---

## ⚙️ 消息发送说明

### 定时提醒（cron add）

定时提醒**只能发送主动消息**，因为：
- 提醒执行时，原始 message_id 通常已超过 1 小时有效期
- `openclaw cron add` 命令不支持 `--reply-to` 参数

```
┌─────────────────────┐
│ 定时任务触发         │
└──────────┬──────────┘
           ↓
┌─────────────────────┐
│ AI 通过 system-event │
│ 获取用户上下文信息   │
└──────────┬──────────┘
           ↓
┌─────────────────────┐
│ 发送主动消息到用户   │
│ --channel qqbot     │
│ --to {openid}       │
└──────────┬──────────┘
           ↓
    ✅ 用户收到提醒
```

### 即时回复（message send）

即时消息发送支持被动回复（如果 message_id 有效）：

```
                ┌─────────────────────┐
                │ 发送即时消息         │
                └──────────┬──────────┘
                           ↓
         ┌──────────────────────────────┐
         │ 有 --reply-to 且 message_id  │
         │ 在 1 小时内有效？             │
         └──────────────────────────────┘
               ↓                ↓
              是               否
               ↓                ↓
    ┌───────────────┐  ┌─────────────────┐
    │ 被动消息回复   │  │ 发送主动消息     │
    │ (引用原消息)   │  │ (直接发送)      │
    └───────────────┘  └─────────────────┘
```

---

## ⚠️ 重要限制

| 限制 | 说明 |
|------|------|
| **message_id 有效期** | 1 小时内有效，超时自动降级 |
| **回复次数限制** | 同一 message_id 最多回复 4 次 |
| **主动消息权限** | ⚠️ **QQ 机器人需要申请主动消息权限**，否则定时提醒会发送失败 |
| **主动消息限制** | 只能发给与机器人交互过的用户（24小时内） |
| **消息内容** | `--message` 不能为空 |

### ⚠️ 主动消息权限说明

定时提醒功能依赖**主动消息能力**，但 QQ 官方默认**不授予**此权限。

**常见错误**：
- 错误码 `40034102`："主动消息失败, 无权限"
- 这表示机器人没有主动消息权限

**解决方案**：
1. 登录 [QQ 开放平台](https://q.qq.com/)
2. 进入机器人开发-沙箱管理，消息列表配置中添加自己。

> 💡 **临时替代方案**：在没有主动消息权限前，可以让用户使用"回复"方式获得即时提醒，而非定时提醒。

---

## 📝 消息模板

| 场景 | 触发时输出 | Emoji |
|------|------------|-------|
| 喝水 | 喝水时间到啦！ | 💧 🚰 |
| 打卡 | 早上好，打卡时间到！ | 🌅 ✅ |
| 会议 | 开会时间到！ | 📅 👥 |
| 休息 | 该休息一下了~ | 😴 💤 |
| 日报 | 下班前别忘了写日报哦~ | 📝 ✍️ |
| 运动 | 运动时间到！ | 🏃 💪 |
| 吃药 | 该吃药了~ | 💊 🏥 |
| 生日 | 今天是xx的生日！ | 🎂 🎉 |

---

## 🔧 用户标识

| 类型 | 格式 | 来源 |
|------|------|------|
| 用户 openid | `B3EA9A1d-2D3c-5CBD-...` | 系统消息自动提供 |
| 群组 openid | `group:FeC1ADaf-...` | 系统消息自动提供 |
| message_id | `ROBOT1.0_xxx` | 系统消息自动提供 |

> 💡 这些信息在系统消息中格式如：
> - `当前用户 openid: B3EA9A1d-...`
> - `当前消息 message_id: ROBOT1.0_...`