# openclaw-qqbot-cron-guide

**Repository Path**: wiisco/openclaw-qqbot-cron-guide

## Basic Information

- **Project Name**: openclaw-qqbot-cron-guide
- **Description**: OpenClaw QQBot 推送类定时任务配置指南
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-11
- **Last Updated**: 2026-04-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OpenClaw 配置 QQBot 推送类定时任务指南

> 本指南基于 2026-04 实战的经验总结，涵盖 QQ 私聊/群聊推送定时任务的完整配置流程、常见问题及解决方案。

---

## 一、前言

在 OpenClaw 中配置向 QQ 用户推送消息的定时任务，涉及三个核心机制的配合：

1. **Cron 调度器**：负责定时触发任务
2. **Isolated Session**：任务执行时的隔离会话环境
3. **QQBot Channel**：实际的消息推送通道

这三个机制之间的配合存在若干坑点，本指南旨在帮助避免重复踩坑。

---

## 二、账号体系说明

OpenClaw QQBot 支持多账号配置，每个账号绑定不同的 agent：

```json
"channels": {
  "qqbot": {
    "appId": "1903726875",      // 小盐（default 账号）
    "clientSecret": "***",
    "accounts": {
      "ajun": {                  // 阿俊
        "appId": "1903780574",
        "clientSecret": "***"
      },
      "xiami": {                 // 虾妹
        "appId": "1903758530",
        "clientSecret": "***"
      }
    }
  }
}
```

| 账号ID | 对应Agent | 用途 |
|--------|----------|------|
| default（顶层 appId） | 小盐 | 默认发信账号 |
| ajun | 阿俊 | 阿俊的 QQ 提醒推送 |
| xiami | 虾妹 | 虾妹的 QQ 简报推送 |

---

## 三、基本配置步骤

### 3.1 创建定时任务（最小化模板）

```bash
openclaw cron add \
  --name "虾米-每日AI资讯简报" \
  --agent xiami \
  --message "调用 daily-ai-news skill 获取当日AI资讯并发送" \
  --cron "50 7 * * *" \
  --tz Asia/Shanghai \
  --session isolated \
  --light-context \
  --timeout-seconds 600 \
  --account xiami \
  --channel qqbot \
  --to qqbot:c2c:目标私聊的OpenID
```

### 3.2 关键参数说明

| 参数 | 说明 |
|------|------|
| `--session isolated` | 在隔离会话中执行，**必须**（见 3.2.1） |
| `--light-context` | 减少冷启动 bootstrap 开销，**必须** |
| `--timeout-seconds 600` | 防止 60 秒 stall 检测截断，**必须** |
| `--account xiami` | 指定投递用的 QQ 账号（对应 xiami 的 third 账号），**必须** |
| `--channel qqbot` | 投递通道，**必须** |
| `--to` | 目标地址，**必须**，格式见 3.2.1 |

### 3.2.1 私聊与群聊的 target 格式

```bash
# 私聊（c2c）
--to qqbot:c2c:目标私聊的OpenID

# 群聊（group）
--to qqbot:group:目标群聊的OpenID
```

**私聊**：`qqbot:c2c:<对方的OpenID>`
**群聊**：`qqbot:group:<群ID>`

**群ID获取方式：** 通过 QQ 开放平台 API 查询机器人所在的频道列表：

```bash
# 使用 qqbot_channel_api 工具获取频道列表
guild_id 即群 ID
GET /users/@me/guilds
```

也可直接在 OpenClaw 对话中让小盐帮忙查询："帮我查一下我的 QQ 机器人加入了哪些群"

### 3.2.2 isolated session 与 main session 的选择

| 场景 | 选择 |
|------|------|
| 定时任务自动执行 | `isolated`（**推荐**） |
| 需要继承当前对话上下文 | `main` |
| 任务可能干扰正常聊天 | `isolated`（**必须**） |

**isolated session 特点：**
- 每次触发创建全新的临时会话，与主会话完全隔离
- 不会干扰用户当前的聊天对话
- 配合 `--light-context` 和 `--timeout-seconds 600` 使用

**main session 特点：**
- 在一直存活的主会话中执行，继承完整对话上下文
- 如果用户正在聊天，任务内容可能混入对话
- 适用于需要引用对话历史的场景

**定时任务推荐用 isolated**，避免干扰正常聊天。

---

## 四、注意事项（重点！）

### 4.1 announce 冗余投递问题 ⚠️

**问题现象：**
定时任务执行后，收到两条消息——一条是简报内容，另一条是发送总结（如"已发送至李总QQ，包含4条资讯"）。

**原因：**
默认 `--announce` 模式下，任务完成后 runner（调度器）自动发一条总结。这与 agent 自己调 `message` 工具发送的内容重复。

**解决：**
用 `--no-deliver` 替代 `--announce`：
```bash
openclaw cron add \
  ... \
  --no-deliver \
  ...
```

或者创建后编辑：
```bash
openclaw cron edit <任务ID> --no-deliver
```

---

### 4.2 QQ 账号凭证隔离问题 ⚠️⚠️⚠️（最高频踩坑）

**问题现象：**
isolated session 执行时，`message` 工具调用失败，报错：`QQBot not configured (missing appId or clientSecret)`

**原因：**

isolated session 创建时，**默认使用 default 账号（小盐）的凭证**，而不是任务所属 agent 自己的账号凭证。

例如：虾妹的定时任务（`agentId: "xiami"`）创建的 isolated session，调用 `message` 工具发 QQ 消息时，用的是 default 账号，不是虾妹自己的账号（xiami），导致认证失败。

**解决：**
创建任务时通过 `--account` 参数指定正确的账号：
```bash
--account xiami   # 或 --account ajun
```

---

### 4.3 isolated session 超时问题 ⚠️

**问题现象：**
定时任务经常报 `Request timed out before a response was generated`，耗时恰好约 60 秒。

**原因：**
OpenClaw Gateway 有 60 秒的 stall 检测机制。isolated session 冷启动时需要加载大量内容（system prompt、tools schema、skills ≈ 110k 字符），导致首次 API 调用延迟，被 stall 检测误杀。

**解决（三管齐下）：**
1. cron 命令加 `--session isolated --light-context` 参数
2. payload 加 `"lightContext": true`
3. payload 加 `"timeoutSeconds": 600`

---

### 4.4 HEARTBEAT.md 误判问题 ⚠️

**问题现象：**
isolated session 执行时，agent 立即返回 `HEARTBEAT_OK`，任务实际未执行。

**原因：**
agent workspace 目录下有非空 `HEARTBEAT.md` 文件时，isolated session 加载后误判为心跳 poll，直接返回 `HEARTBEAT_OK` 不执行任何操作。

**解决：**
各 agent 的 workspace 目录下，**不能有非空的 HEARTBEAT.md 文件**：
```markdown
# 已清空 - 由 cron 直接触发内容，不走 heartbeat 逻辑
```

---

### 4.5 定时任务消息内容规范

**原则：消息内容越短小，调用越稳定。**

| 任务类型 | 建议字数 | 原因 |
|---------|---------|------|
| 简单提醒（吃饭/睡觉） | 20-50 字 | 稳定快速 |
| 简报类（待办/资讯） | 100-200 字 | 中等稳定 |
| 复杂生成类（教育安全简报） | 500-800 字 | 需要较长超时 |

**建议：** 先让 agent 调用 skill 获取数据，再由 agent 自己组织内容发送，不要在 cron 消息里写死长内容。

---

## 五、配置检查清单

新建或修改 QQ 推送类 cron 任务时，对照检查以下 6 项：

- [ ] `--session isolated` 已设置
- [ ] `lightContext: true` 已设置
- [ ] `timeoutSeconds: 600` 已设置
- [ ] `--account` 已指定为对应的 agent 账号（`xiami` 或 `ajun`）
- [ ] `--to` 目标地址格式正确（私聊 `qqbot:c2c:目标私聊的OpenID` / 群聊 `qqbot:group:目标群聊的OpenID`）
- [ ] agent workspace 目录下 HEARTBEAT.md 为空或不存在

---

## 六、实战配置示例

### 示例一：虾米-每日AI资讯简报（私聊推送）

```bash
openclaw cron add \
  --name "虾米-每日AI资讯简报" \
  --agent xiami \
  --message "调用 daily-ai-news skill 获取当日AI资讯并发送" \
  --cron "50 7 * * *" \
  --tz Asia/Shanghai \
  --session isolated \
  --light-context \
  --timeout-seconds 600 \
  --account xiami \
  --channel qqbot \
  --to qqbot:c2c:目标私聊的OpenID
```

### 示例二：睡觉提醒（私聊推送）

```bash
openclaw cron add \
  --name "睡觉提醒" \
  --agent ajun \
  --message "提醒该睡觉了" \
  --cron "30 22 * * *" \
  --tz Asia/Shanghai \
  --session isolated \
  --light-context \
  --timeout-seconds 600 \
  --account ajun \
  --channel qqbot \
  --to qqbot:c2c:目标私聊的OpenID
```

### 示例三：群聊推送

```bash
openclaw cron add \
  --name "虾米-群通知" \
  --agent xiami \
  --message "发送群通知内容" \
  --cron "0 9 * * *" \
  --tz Asia/Shanghai \
  --session isolated \
  --light-context \
  --timeout-seconds 600 \
  --account xiami \
  --channel qqbot \
  --to qqbot:group:目标群聊的OpenID
```

---

*最后更新：2026-04-11*