如何配置 Cron 任务来定期运行代理？

在 OpenClaw 系统中，你可以使用网关内置的 Cron 调度器来配置定期运行的代理任务。Cron 任务直接在网关内部运行，允许你设置精确的执行时间，并能自动唤醒代理执行特定操作。

以下是配置 Cron 任务的关键步骤和方法：

1. 核心概念与选择

在配置之前，你需要确定两个核心要素：

执行位置 (Session Target)

• main (主会话)：将事件加入主会话队列，在下一次心跳（Heartbeat）时运行。适合需要共享主会话上下文的任务。
• isolated (独立会话)：运行一个专用的代理轮次（会话 ID 为 cron:<jobId>）。适合不想干扰主聊天记录的后台"家务"任务。

调度类型 (Schedule Kind)

• at：一次性任务（ISO 8601 时间戳）。
• every：固定间隔（毫秒）。
• cron：标准 Cron 表达式（5 位或包含秒的 6 位字段），支持时区设置。

2. 使用 CLI 添加任务 (推荐)

你可以通过 openclaw cron add 命令快速创建定期任务。以下是几个典型场景：

配置每日早报 (独立会话)

在每天早上 7 点运行，使用独立会话并通过 WhatsApp 发送摘要。

openclaw cron add \
--name "每日简报" \
--cron "0 7 * * *" \
--tz "Asia/Shanghai" \
--session isolated \
--message "总结昨晚的更新和今天的日程。" \
--announce \
--channel whatsapp \
--to "+861234567890"

配置每 4 小时一次的检查 (主会话)

openclaw cron add \
--name "项目检查" \
--every "4h" \
--session main \
--system-event "现在是进行项目健康检查的时间" \
--wake now

3. 系统配置与存储

启用 Cron

确保你的 ~/.openclaw/openclaw.json 配置文件中 cron.enabled 为 true（默认即为启用）。

任务存储

所有任务持久化存储在 ~/.openclaw/cron/jobs.json 中。手动编辑此文件仅在网关停止时是安全的，建议优先使用 CLI 命令进行修改。

重试机制

如果任务执行失败，系统会自动应用指数退避策略（30秒、1分钟、5分钟等）进行重试。

4. 管理与维护命令

• 查看任务列表：openclaw cron list。
• 手动触发任务：openclaw cron run <job-id>。
• 查看运行记录：openclaw cron runs --id <job-id>。
• 编辑现有任务：使用 openclaw cron edit <job-id> 并加上需要修改的参数。

5. Cron vs 心跳 (Heartbeat)

使用 Cron 的场景

需要精确时间执行的任务（如"每周一早上 9 点"）或需要独立会话/不同模型配置的任务。

使用心跳的场景

适合批量处理常规监控（如每 30 分钟检查一次收件箱），它可以利用主会话的上下文做出更智能的判断。

如果你需要更复杂的、包含多步工具调用且需要人工审批的工作流，可以考虑结合使用 Lobster 插件。