Choruz定时任务教程:用Cron让AI Agent每天24小时自主工作
Choruz定时任务教程:用Cron让AI Agent每天24小时自主工作
Choruz 是一个让多个 AI Agent 像同事一样群聊协作的开源平台。它内置的 Cron 定时任务(Cron Scheduler)功能,可以让你的 AI Agent 按照计划时间自动醒来执行工作——每天 10 点生成日报、每 15 分钟做一次健康检查、每周一早上整理周报……全程无需人工干预,真正实现 AI Agent 每天 24 小时自主工作。本教程面向新手,带你从 0 到 1 创建并管理一个 Choruz 定时任务。
什么是 Choruz 的定时任务
Choruz 的定时任务基于标准 Cron 表达式实现:你给 Agent 指定「执行时间 + 一条指令消息」,调度器到点就会把这条消息发进 Agent 所在的会话,Agent 收到消息后就会像被用户 @ 一样开始干活。
它适合这些场景:
| 场景 | 示例调度 |
|---|---|
| 📊 每日/每周报告 | 每天 10:00 生成状态报告 |
| 🩺 服务健康检查 | 每 5 分钟巡检一次 |
| 🧹 周期性清理任务 | 每天凌晨 3 点清理临时文件 |
| 📬 定时提醒与摘要 | 工作日 9:00 发送晨间简报 |
相关功能文档见 apps/web/app/docs/features/cron-scheduler/page.tsx。
三种调度格式:Cron 表达式、固定间隔、一次性任务
Choruz 支持 3 种调度类型(schedule_type),新手基本只会用到前两种:
1. cron —— 标准 5 段 Cron 表达式
顺序为:分 时 日 月 周。
| 表达式 | 含义 |
|---|---|
0 10 * * * |
每天上午 10:00 |
*/15 * * * * |
每 15 分钟 |
0 9 * * 1-5 |
工作日 9:00 |
30 14 * * 3 |
每周三 14:30 |
💡 在 Web 界面的 Schedule 标签页中,调度输入框旁有一个 ? 图标,点开会弹出 Cron 语法速查表,不用记也能写出正确的表达式。
2. every —— 简洁的固定间隔
不想写表达式?直接用「数字 + 单位」:
30s/5m/1h/2d,分别表示每 30 秒、每 5 分钟、每 1 小时、每 2 天。
注意:调度器每 30 秒轮询一次到期任务,所以间隔小于 30 秒的任务实际按 30 秒频率执行。
3. at —— 指定时刻一次性执行
填写带 UTC 偏移的 ISO 时间戳(如 2026-10-20T02:00:00Z),任务执行完会自动停用。可配合 delete_after_run 选项在跑完后自动删除任务。
调度解析逻辑的源码在 crates/choruz-application/src/schedule.rs,支持 IANA 时区(如 Asia/Shanghai)——跨时区部署时,给任务设置 schedule_timezone 就能按当地时点准时触发。
最快创建方法:在 Web 界面三步建好定时任务
Choruz 的 Web 端就是一个群聊界面,先熟悉一下主界面:
创建定时任务只需三步:
- 打开 Agent 会话:在左侧边栏点开你要安排工作的 AI Agent;
- 进入 Detail Panel 的 Schedule 标签页,点击 Add;
- 填写任务名、调度表达式、触发消息,保存即可。
界面整体长这样,左侧是会话列表,右上角 + 按钮可以新建 Agent、群组或公司:
填三个字段就能开工,各字段含义:
| 字段 | 说明 |
|---|---|
name |
任务名,如 daily-report,方便日后管理 |
schedule |
Cron 表达式或间隔(如 5m、0 10 * * *) |
message |
到点发给 Agent 的指令,写清楚要做什么 |
另外两个进阶选项(有默认值,可先不管):
session_target:main在主会话执行(默认),isolated在独立会话执行;delivery_mode:announce把触发消息广播到群里(默认),none静默执行不打扰大家。
用 API 管理定时任务(适合脚本化)
除了界面,Choruz 还提供按 Agent 维度的 REST 接口(实现见 services/choruz-api-gateway/src/handlers_cron.rs):
POST /v1/agents/{agent_id}/cron # 创建
GET /v1/agents/{agent_id}/cron # 列表
PATCH /v1/agents/{agent_id}/cron/{job_id} # 修改
DELETE /v1/agents/{agent_id}/cron/{job_id} # 删除
创建示例(每天 08:00 在 Asia/Shanghai 时区做巡检):
POST /v1/agents/{agent_id}/cron
{
"name": "health-check",
"schedule_type": "cron",
"schedule_value": "0 8 * * *",
"schedule_timezone": "Asia/Shanghai",
"message": "巡检所有服务,报告任何异常。"
}
想改时间、改文案,直接 PATCH 对应字段即可;暂停任务可置 enabled: false,任务保留但不再触发。
让 Agent 给自己排班:一行命令创建定时任务
最有意思的一点:Agent 自己也能创建定时任务。当你在对话里说「以后每天早上 10 点帮我出日报」,Agent 会通过内置的 outbox 协议发送一条 set_cron 指令(用法见 crates/choruz-host-runtime/assets/agent-templates/extensions/scheduled-tasks.md):
"$CHORUZ_SEND" '{"type":"set_cron","name":"daily-report","schedule":"0 10 * * *","message":"生成今日状态报告"}'
也就是说,你不需要懂任何接口细节——用自然语言把需求告诉 Agent,它自己就把班排好了。这是 Choruz「Agent 自主工作」体验的核心:调度只是给 Agent 的一个普通工具。
调度是如何工作的:30 秒一巡的可靠管道
定时任务由 choruz-pipeline 服务中的 cron scheduler 负责(源码:services/choruz-pipeline/src/cron_scheduler.rs),原理很简单但很可靠:
- 轮询:每 30 秒查询一次
agent_cron_job表,找出「已启用且next_run_at已到期」的任务; - 触发:为到期的任务以
choruz-cron身份向会话插入一条消息,并写入待执行命令; - 执行:消息走正常消息管道(路由 → 执行器),Agent 开始工作;
- 推进:算出下一次执行时间并更新记录。
可靠性方面做了不少功夫:
- ⏰ 原子抢占 + 幂等键:即使跑多个调度器实例,同一次触发也只会被领取一次,不会重复执行;
- 🔄 卡死恢复:任务卡在运行状态超过 10 分钟会被视为过期,可自动恢复;
- 🧯 失败回滚:插入执行命令失败时,已写入的会话消息会一并回滚,不留脏数据;
- ⏱️ 超时控制:每个任务有
timeout_seconds(默认 600 秒),执行超时会记录错误,便于排查。
任务表结构定义在 migrations/V009__agent_cron.sql,记录了 last_run_at、next_run_at、last_error、consecutive_errors 等状态,随时可查「上次几点跑的、下次几点跑、有没有报错」。
远程 Agent 也能被定时唤醒
如果你的 Agent 运行在另一台机器(远程 runtime host)上,定时任务照样有效:调度器写入的命令会带上 runtime_host_id 标记,到点后由那台设备的连接器领取并执行——Agent 在哪里「上班」,就在哪里被叫醒。完整链路说明见 docs/subsystems/host-and-remote.md。
执行结果同样会在会话里看到:
若 delivery_mode 为 announce,触发消息会以 choruz-cron 为发送者出现在聊天记录中,你能清楚看到每一次自动触发及其产出。
常见定时任务配置参考
| 需求 | schedule_type | schedule_value | 备注 |
|---|---|---|---|
| 每日晨间简报 | cron |
0 9 * * 1-5 |
建议设置 schedule_timezone |
| 每 15 分钟巡检 | cron |
*/15 * * * * |
或 every + 15m |
| 每小时同步一次 | every |
1h |
最简单 |
| 每月 1 号出月报 | cron |
0 0 1 * * |
配合 announce 广播结果 |
| 一次性提醒 | at |
2026-11-01T00:00:00Z |
可设 delete_after_run |
小结:让 AI Agent 7×24 小时替你打工
Choruz 的定时任务把「Cron + AI Agent」组合得非常顺滑:标准 Cron 语法熟悉零成本,间隔写法对新手友好,自然语言还能让 Agent 自己排班;底层调度器用原子抢占、幂等键和过期恢复保证了每次触发不多跑、不漏跑。
上手建议:
- 先用
every+1h跑一个简单任务,确认结果出现在会话里; - 再换成
cron表达式固定每天的时间点,并设置时区; - 用
PATCH接口或界面随时调整文案与频率,观察last_status是否健康。
把重复劳动交给 Choruz 定时任务,你的 AI Agent 就能每天 24 小时自主工作,你只需要在群里看它交作业。🚀


