JavaClaw的Cron定时任务:3种配置让AI助手自动定时干活
JavaClaw的Cron定时任务:3种配置让AI助手自动定时干活
JavaClaw 是一款基于 Spring Boot、Spring AI 和 JobRunr 构建的 Java 版个人 AI 助手,支持用自然语言创建Cron 定时任务:一句"每天中午 12 点给我发日报",AI 就会自动排期、按时执行,并通过 Telegram、Discord、Web 聊天等渠道把结果推送给你。本文带你搞懂 JavaClaw 定时任务背后的 3 种配置方式,让你的 AI 助手真正"自动定时干活"。
一、定时任务是如何实现的?
JavaClaw 的定时任务由 JobRunr 后台任务框架驱动,核心设计很直观:
- 调度层:TaskManager.java 负责任务的创建、延时调度和 Cron 周期调度,底层通过
JobScheduler把作业提交给 JobRunr; - 持久化层:每个任务都会保存为人类可读的 Markdown 文件,存放在
workspace/tasks/目录(按日期分桶,文件名形如yyyy-MM-dd/HHmmss-<状态>-<名称>.md),周期任务模板则存放在workspace/tasks/recurring/; - 执行层:TaskHandler.java 在作业触发时调用 AI Agent 处理任务,失败自动重试 3 次。
任务状态机如下,每次执行都会写回任务文件,随时可以"打开文件看进度":
todo → in_progress → completed / awaiting_human_input
状态定义见 Task.java。
二、配置方式 1:即时任务——说完立刻干活
这是最简单的用法。当你给 AI 一个目标时,它会通过 createTask 工具把请求固化成一个可跟踪的任务,然后立即入队执行,无需任何时间参数:
🗣️ 你说:"帮我建个任务:把 workspace 里的旧文档归档整理一下"
🤖 JavaClaw:
Task 'archive-old-docs' has been created successfully.
工具实现位于 JavaClawTaskTool.java,它把任务管理包装成 AI 可自动调用的 5 个工具,用户全程只需要说人话。
三、配置方式 2:单次延时任务——到点才执行
如果用户提到了明确的时间点(例如"下周一早上 9 点提醒我同步进度"),AI 会调用 scheduleTask,指定执行时间(格式 YYYY-MM-ddTHH:mm:ss,如 2025-03-17T09:00:00)、任务名和描述:
- 任务到点之前保持
todo状态,安静等待; - 到点后由 JobRunr 准时唤醒 Agent 执行,执行完通过你最近的聊天渠道推送结果。
🗣️ 你说:"下周一早上 9 点提醒我检查部署"
🤖 JavaClaw:
Task 'monday-deploy-check' has been scheduled for 2025-10-27T09:00:00.
四、配置方式 3:Cron 周期任务——真正的"定时干活"
这是 JavaClaw 定时任务的杀手级能力。对于日报、周报、定期清理这类周期性工作,AI 会调用 scheduleRecurringTask,传入一个标准 quartz 风格的 cron 表达式:
🗣️ 你说:"每天中午 12 点生成一份服务器状态日报,发到 Telegram"
🤖 JavaClaw:
Task 'daily-status-report' has been scheduled recurrently with cron expression '0 12 * * *'.
注意:cron 表达式中不要使用 ? 字符。常用表达式速查表:
| 表达式 | 含义 | 适用场景 |
|---|---|---|
0 12 * * * |
每天中午 12 点 | 每日日报 |
0 9 * * MON |
每周一早上 9 点 | 周报、周会准备 |
0 0 1 * * |
每月 1 号 0 点 | 月度账单汇总 |
0 */6 * * * |
每 6 小时一次 | 定时巡检 |
* * * * * |
每分钟 | 调试测试(慎用) |
周期任务触发时,RecurringTaskHandler.java 会基于 workspace/tasks/recurring/ 下的任务模板派生一个真实的执行任务(定义见 RecurringTask.java),这样每次运行的结果、状态和 Agent 反馈都有独立文件可查,互不覆盖。
五、管理你的定时任务
周期任务创建后并非"只增不减",JavaClaw 提供了两个配套工具,同样用自然语言就能操作:
- 列出全部:
listRecurringTasks会返回所有周期任务的 id、名称和描述; - 删除停跑:
deleteRecurringTask按名称移除任务,并清理 JobRunr 中已排队的作业,之后不再触发。
🗣️ 你说:"现在都有哪些定时任务?" → AI 列出清单 🗣️ 你说:"把每周的日志清理任务删掉" → AI 回复
Recurring task 'weekly-log-cleanup' has been deleted successfully.
删除逻辑在 TaskManager.java 中实现,会同时移除调度记录和待执行作业,避免"删了还在跑"的尴尬。
六、如何查看任务执行情况?
JavaClaw 提供三个观察窗口,适合不同深度的用户:
- 任务文件:直接打开
workspace/tasks/下的 Markdown 文件,里面包含任务描述、执行状态和 Agent 的执行反馈(Agent feedback段落); - 聊天渠道推送:任务完成后,AI 会主动通过最近的渠道发送通知,例如
📋 Task 'daily-status-report' completed: ...;如果任务卡住需要人工决策,会发送awaiting_human_input提示; - JobRunr Dashboard:访问
http://localhost:8081可查看后台作业的队列、执行历史、重试记录和日志。
七、快速上手示例
以"每日日报"为例,完整的交互流程只有 3 步:
- 在 Web 聊天(
/chat)或 Telegram 中说:"每天中午 12 点生成日报并发给我"; - AI 自动创建周期任务
daily-report,cron 为0 12 * * *; - 每天 12 点,Agent 自动执行并推送结果——你什么都不用管。
想停掉它?一句"取消日报任务"即可。整个过程无需改配置、不用写代码,这正是 JavaClaw "对话即调度"的设计哲学。
八、总结
| 配置方式 | 工具 | 适用场景 | 关键参数 |
|---|---|---|---|
| 即时任务 | createTask |
说完马上干 | 名称 + 描述 |
| 单次延时 | scheduleTask |
指定时间点执行 | YYYY-MM-ddTHH:mm:ss |
| Cron 周期 | scheduleRecurringTask |
日报/周报/巡检 | quartz cron 表达式 |
JavaClaw 把"定时任务"这件传统上需要写 crontab、配调度器的事情,变成了和 AI 说一句话的事。任务以 Markdown 文件持久化、执行过程可追溯、失败自动重试、状态实时推送——这套机制的核心代码集中在 base/src/main/java/ai/javaclaw/tasks/ 模块,感兴趣的开发者可以顺着 README.md 中的项目结构说明继续深挖。
现在,试试对你的 JavaClaw 说:"每天早上 8 点给我一份新闻摘要"吧!