OpenClaw 定时任务配置

什么是 Cron 任务？

OpenClaw 的 cron 任务系统让你能够：

• ⏰ 定时执行自动化操作
• 📊 周期性数据同步
• 📝 自动内容发布
• 🔔 定时提醒和通知
• 🧹 定期清理和维护

调度类型

1. Cron 表达式

// 每天早上8点执行
{
  schedule: {
    kind: "cron",
    expr: "0 8 * * *",
    tz: "Asia/Shanghai"
  }
}

// 每周一上午9点
{
  schedule: {
    kind: "cron",
    expr: "0 9 * * 1"
  }
}

// 每月1号凌晨
{
  schedule: {
    kind: "cron",
    expr: "0 0 1 * *"
  }
}

2. 间隔执行

// 每30分钟执行一次
{
  schedule: {
    kind: "every",
    everyMs: 1800000  // 30分钟 = 1800000毫秒
  }
}

// 每2小时
{
  schedule: {
    kind: "every",
    everyMs: 7200000,
    anchorMs: Date.now()  // 从当前时间开始
  }
}

3. 一次性执行

// 指定时间执行一次
{
  schedule: {
    kind: "at",
    at: "2026-04-15T09:00:00Z"
  }
}

负载类型

System Event (主会话)

{
  payload: {
    kind: "systemEvent",
    text: "执行每日SEO巡检任务"
  }
}

Agent Turn (独立会话)

{
  payload: {
    kind: "agentTurn",
    message: "生成今天的AI新闻日报",
    model: "tencentcodingplan/tc-code-latest",
    thinking: "high",
    timeoutSeconds: 600
  }
}

通知配置

无通知

{
  delivery: { mode: "none" }
}

群聊通知

{
  delivery: {
    mode: "announce",
    channel: "feishu",
    to: "oc_c942dfd09730eb94bf838c6519c115e9"
  }
}

Webhook 回调

{
  delivery: {
    mode: "webhook",
    to: "https://your-server.com/webhook/openclaw",
    bestEffort: true
  }
}

实战示例

示例1: 每日SEO巡检

await cron({
  action: "add",
  job: {
    name: "daily-seo-audit",
    schedule: {
      kind: "cron",
      expr: "0 2 * * *",
      tz: "Asia/Shanghai"
    },
    payload: {
      kind: "agentTurn",
      message: "执行SEO巡检：检查死链、更新sitemap、优化meta",
      timeoutSeconds: 300
    },
    delivery: {
      mode: "announce",
      channel: "feishu"
    },
    sessionTarget: "isolated",
    enabled: true
  }
});

示例2: 每小时RSS聚合

await cron({
  action: "add",
  job: {
    name: "hourly-rss-feed",
    schedule: {
      kind: "every",
      everyMs: 3600000
    },
    payload: {
      kind: "agentTurn",
      message: "聚合最新AI资讯：\n1. 抓取OpenAI blog\n2. 抓取Anthropic blog\n3. 整理成摘要"
    },
    sessionTarget: "isolated"
  }
});

示例3: 定时内容发布

await cron({
  action: "add",
  job: {
    name: "weekly-community-update",
    schedule: {
      kind: "cron",
      expr: "0 10 * * 5",  // 每周五上午10点
      tz: "Asia/Shanghai"
    },
    payload: {
      kind: "agentTurn",
      message: "生成周报：\n1. 本周热门工具\n2. 社区动态\n3. 教程更新"
    },
    delivery: {
      mode: "announce",
      channel: "discord"
    }
  }
});

任务管理

查看任务列表

// 列出所有任务
const jobs = await cron({
  action: "list"
});

// 包含已禁用的任务
const allJobs = await cron({
  action: "list",
  includeDisabled: true
});

手动触发

// 立即执行指定任务
await cron({
  action: "run",
  jobId: "daily-seo-audit"
});

// 强制执行
await cron({
  action: "run",
  jobId: "daily-seo-audit",
  runMode: "force"
});

修改任务

// 更新cron表达式
await cron({
  action: "update",
  jobId: "hourly-rss-feed",
  patch: {
    schedule: {
      kind: "every",
      everyMs: 7200000  // 改为2小时
    }
  }
});

// 禁用任务
await cron({
  action: "update",
  jobId: "temp-task",
  patch: { enabled: false }
});

删除任务

await cron({
  action: "remove",
  jobId: "old-experiment-task"
});

运行记录

// 查看任务运行历史
const runs = await cron({
  action: "runs",
  jobId: "daily-seo-audit",
  limit: 20
});

// 检查调度器状态
const status = await cron({ action: "status" });

上下文消息

可以在触发时传递历史消息作为上下文：

await cron({
  action: "run",
  jobId: "weekly-report",
  contextMessages: 5  // 包含最近5条对话
});

最佳实践

• 使用有意义的任务名称，便于识别
• 设置合理的timeoutSeconds，避免任务卡死
• 重要任务配置delivery通知，及时了解执行结果
• 使用tz参数确保时区正确
• 测试时先使用"every"短间隔，确认无误后改为cron

相关资源

• Agent Skills 开发
• 子Agent编排
• 社区运营
• AI新闻日报