cron-setup

# OpenClaw Cron Jobs 配置指南 Cron 是 Gateway 内置的调度器，持久化存储任务，在指定时间唤醒 agent 执行，并可选择将结果投递到聊天频道。 ## 核心概念 ### 两种执行模式 | 模式 | 用途 | payload 类型 | |------|------|--------------| | **main** (主会话) | 系统事件，融入正常心跳流程 | `systemEvent` | | **isolated** (独立会话) | 后台任务，不污染主会话历史 | `agentTurn` | ### 三种调度类型 | 类型 | 字段 | 示例 | |------|------|------| | **一次性** | `schedule.kind: "at"` | `2026-03-04T10:00:00Z` 或 `20m` (相对时间) | | **固定间隔** | `schedule.kind: "every"` | `everyMs: 3600000` (1 小时) | | **Cron 表达式** | `schedule.kind: "cron"` | `expr: "0 7 * * *"` (每天 7 点) | ## 快速开始 ### 1. 创建一次性提醒（主会话） ```bash openclaw cron add \ --name "提醒事项" \ --at "20m" \ --session main \ --system-event "20 分钟后检查日历" \ --wake now \ --delete-after-run ``` ### 2. 创建周期性任务（独立会话） ```bash openclaw cron add \ --name "晨间简报" \ --cron "0 7 * * *" \ --tz "Asia/Shanghai" \ --session isolated \ --message "总结昨晚的邮件和日历事件" \ --announce \ --channel telegram \ --to "+8613800138000" ``` ### 3. 创建带模型覆盖的深度任务 ```bash openclaw cron add \ --name "周报分析" \ --cron "0 9 * * 1" \ --tz "Asia/Shanghai" \ --session isolated \ --message "分析本周项目进展" \ --model "opus" \ --thinking high \ --announce \ --channel whatsapp \ --to "+8613800138000" ``` ## 常用命令 ```bash # 查看任务列表 openclaw cron list # 手动运行任务 openclaw cron run <job-id> # 查看运行历史 openclaw cron runs --id <job-id> --limit 10 # 编辑任务 openclaw cron edit <job-id> --message "新提示词" # 删除任务 openclaw cron remove <job-id> ``` ## JSON Schema（工具调用） ### 一次性主会话任务 ```json { "name": "提醒", "schedule": { "kind": "at", "at": "2026-03-04T10:00:00Z" }, "sessionTarget": "main", "wakeMode": "now", "payload": { "kind": "systemEvent", "text": "提醒内容" }, "deleteAfterRun": true } ``` ### 周期性独立会话任务 ```json { "name": "晨间简报", "schedule": { "kind": "cron", "expr": "0 7 * * *", "tz": "Asia/Shanghai" }, "sessionTarget": "isolated", "wakeMode": "next-heartbeat", "payload": { "kind": "agentTurn", "message": "总结隔夜更新" }, "delivery": { "mode": "announce", "channel": "telegram", "to": "+8613800138000", "bestEffort": true } } ``` ## 投递模式（Delivery） 仅适用于 `isolated` 任务： | 模式 | 说明 | |------|------| | `announce` | 投递到指定频道，并在主会话发送简短摘要 | | `webhook` | POST 到 HTTP 端点 | | `none` | 仅内部执行，无投递 | **省略 `delivery` 时默认行为：** `announce` 模式 ## Telegram 话题投递 支持论坛话题（topic）： ```bash --to "-1001234567890:topic:123" # 推荐：显式话题标记 --to "-1001234567890:123" # 简写：数字后缀 ``` ## 配置示例（参考） 当前工作配置示例（`~/.openclaw/cron/jobs.json`）： ```json { "name": "daily-health-summary", "schedule": { "kind": "cron", "expr": "0 10 * * *", "tz": "Asia/Shanghai" }, "sessionTarget": "isolated", "payload": { "kind": "agentTurn", "message": "从 Bitable 查询健康数据并生成总结" }, "delivery": { "mode": "none", "channel": "last" } } ``` ## 故障排查 ### 任务不执行 1. 检查 cron 是否启用：`cron.enabled: true`（配置中） 2. 检查 Gateway 是否持续运行（cron 在 Gateway 进程内执行） 3. 确认时区设置正确（`--tz` 参数） ### 任务反复延迟 - 连续失败会触发指数退避：30s → 1m → 5m → 15m → 60m - 成功执行后退避重置 ### 查看存储位置 - 任务存储：`~/.openclaw/cron/jobs.json` - 运行历史：`~/.openclaw/cron/runs/<jobId>.jsonl` ## 高级配置 在 `~/.openclaw/config.json` 中： ```json5 { cron: { enabled: true, sessionRetention: "24h", // 独立会话保留时长 runLog: { maxBytes: "2mb", // 运行日志最大大小 keepLines: 2000, // 保留行数 }, } } ``` ## Cron vs Heartbeat | 场景 | 推荐 | |------|------| | 精确时间（如"每周一 9 点"） | **cron** | | 批量检查（邮箱 + 日历 + 天气） | **heartbeat** | | 一次性提醒 | **cron** | | 后台自动化（频繁/嘈杂） | **cron (isolated)** | | 主会话上下文相关任务 | **heartbeat** | --- **文档来源：** https://docs.openclaw.ai/automation/cron-jobs