Choruz定时任务教程:用Cron让AI Agent每天24小时自主工作

原创2026-10-15 16:29:371,932 阅读

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 端就是一个群聊界面,先熟悉一下主界面:

Choruz AI Agent 协作平台主界面,用于创建和管理定时任务

创建定时任务只需三步:

  1. 打开 Agent 会话:在左侧边栏点开你要安排工作的 AI Agent;
  2. 进入 Detail Panel 的 Schedule 标签页,点击 Add;
  3. 填写任务名、调度表达式、触发消息,保存即可。

界面整体长这样,左侧是会话列表,右上角 + 按钮可以新建 Agent、群组或公司:

Choruz 平台新建菜单,可创建 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),原理很简单但很可靠:

  1. 轮询:每 30 秒查询一次 agent_cron_job 表,找出「已启用且 next_run_at 已到期」的任务;
  2. 触发:为到期的任务以 choruz-cron 身份向会话插入一条消息,并写入待执行命令;
  3. 执行:消息走正常消息管道(路由 → 执行器),Agent 开始工作;
  4. 推进:算出下一次执行时间并更新记录。

可靠性方面做了不少功夫:

  • ⏰ 原子抢占 + 幂等键:即使跑多个调度器实例,同一次触发也只会被领取一次,不会重复执行;
  • 🔄 卡死恢复:任务卡在运行状态超过 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。

执行结果同样会在会话里看到:

Choruz 群组会话界面,AI Agent 定时任务执行后的消息与图片结果在此展示

若 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 自己排班;底层调度器用原子抢占、幂等键和过期恢复保证了每次触发不多跑、不漏跑。

上手建议:

  1. 先用 every + 1h 跑一个简单任务,确认结果出现在会话里;
  2. 再换成 cron 表达式固定每天的时间点,并设置时区;
  3. 用 PATCH 接口或界面随时调整文案与频率,观察 last_status 是否健康。

把重复劳动交给 Choruz 定时任务,你的 AI Agent 就能每天 24 小时自主工作,你只需要在群里看它交作业。🚀

登录后查看全文
Choruz