技术分享►OpenClaw使用指南

OpenClaw定时提醒任务模式详解与问题解决

引言

在使用OpenClaw进行自动化任务管理时，定时提醒功能是一个非常实用的特性。然而，很多用户在设置定时提醒后发现飞书收不到消息，这通常是因为对OpenClaw的两种定时任务模式理解不够深入。本文将详细解析这个问题的根本原因，并提供完整的解决方案。

问题现象

用户在OpenClaw中设置了定时提醒任务，但在指定时间没有收到任何飞书消息通知。任务看似已经创建成功，但实际的消息推送功能并未生效。

根本原因分析

OpenClaw定时任务的两种模式

OpenClaw提供了两种不同的定时任务执行模式，每种模式有其特定的用途和限制：

1. systemEvent模式（默认模式）

特点：

  • 会话类型: 主会话（main session）
  • 执行方式: 将提醒文本作为系统事件注入到当前主会话中
  • 消息路由: 仅在主会话内部处理，不会自动发送到外部消息渠道
  • 适用场景: 内部状态更新、日志记录、会话内通知

限制：

  • ❌ 无法直接发送飞书消息
  • ❌ 无法跨会话通信
  • ❌ 依赖主会话处于活跃状态

2. agentPrompt模式（推荐模式）

特点：

  • 会话类型: 隔离会话（isolated session）
  • 执行方式: 在独立的隔离会话中运行完整的Agent回合
  • 消息路由: 支持完整的消息发送功能，包括飞书、Telegram等外部渠道
  • 适用场景: 外部通知、跨平台消息推送、独立任务执行

优势：

  • ✅ 支持所有消息渠道
  • ✅ 独立于主会话运行
  • ✅ 完整的工具调用能力

问题根源

当用户使用默认的systemEvent模式设置定时提醒时，OpenClaw只是将提醒内容注入到主会话中，而不会触发外部消息发送机制。这就是为什么飞书收不到消息的根本原因。

解决方案

正确的定时任务配置方法

要确保定时提醒能够成功发送到飞书，必须使用agentPrompt模式。以下是正确的配置方式：

1. 使用Cron API设置agentPrompt模式

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// 正确的配置示例
{
  "name": "电话值班提醒",
  "schedule": {
    "kind": "at",
    "at": "2026-02-20T01:00:00.000Z"
  },
  "payload": {
    "kind": "agentTurn",           // 关键：使用agentTurn
    "message": "⏰ 重要提醒：今天需要电话值班！"
  },
  "sessionTarget": "isolated",    // 关键：使用isolated会话
  "delivery": {
    "mode": "announce"           // 确保启用消息公告
  }
}

2. 关键配置参数说明

参数 正确值 说明
payload.kind "agentTurn" 启用Agent回合执行
sessionTarget "isolated" 使用隔离会话
delivery.mode "announce" 启用消息公告

3. 错误配置示例（避免使用）

1
2
3
4
5
6
7
8
// ❌ 错误的配置（默认systemEvent模式）
{
  "payload": {
    "kind": "systemEvent",       // 问题所在：systemEvent模式
    "text": "提醒内容"
  },
  "sessionTarget": "main"        // 问题所在：主会话
}

实际应用案例

案例1：电话值班提醒

需求：在2月20日和2月22日早上9点提醒电话值班

正确实现：

  • 使用agentPrompt模式
  • 设置sessionTarget: "isolated"
  • 包含完整的提醒内容和操作指引

案例2：商品价格监控

需求：定时检查京东商品价格并推送通知

正确实现：

  • 在隔离会话中执行网页抓取
  • 使用完整的消息发送功能
  • 支持条件判断和智能提醒

最佳实践建议

1. 何时使用哪种模式

场景 推荐模式 理由
外部消息推送 agentPrompt 需要完整的消息发送能力
内部状态更新 systemEvent 轻量级，不影响主会话
复杂任务执行 agentPrompt 需要完整的工具调用
简单日志记录 systemEvent 性能开销小

2. 配置检查清单

在设置定时任务前，请确认：

  • ✅ 是否需要发送外部消息？
  • ✅ 是否需要调用外部工具？
  • ✅ 是否需要独立于主会话运行？
  • ✅ 是否已正确设置sessionTarget为"isolated"？

3. 调试技巧

如果定时任务没有按预期工作：

  1. 检查任务配置：确认sessionTarget和payload.kind
  2. 查看任务日志：检查隔离会话的执行日志
  3. 测试消息发送：在隔离会话中手动测试消息功能
  4. 验证权限设置：确保飞书消息权限已正确配置

总结

OpenClaw的定时提醒功能非常强大，但要确保消息能够成功发送到飞书等外部渠道，必须使用agentPrompt模式而非默认的systemEvent模式。关键在于：

  • sessionTarget: "isolated" - 使用隔离会话
  • payload.kind: "agentTurn" - 启用完整的Agent回合
  • delivery.mode: "announce" - 启用消息公告

通过正确配置这些参数，您就可以充分利用OpenClaw的定时任务功能，实现可靠的自动化消息推送。

相关标签：#OpenClaw #定时任务 #飞书集成 #技术分享 #自动化