Cloudroom 自动化任务完整指南:cron 定时 + Webhook 触发,Mac 睡了 AI 也按时开工
Cloudroom 自动化任务完整指南:cron 定时 + Webhook 触发,Mac 睡了 AI 也按时开工
Cloudroom 核心(cloudroom-core)是一款开源、可自托管的 Rust 运行时,它让 Claude Code、Codex、Pi 等编码智能体在云端沙箱里运行,并为每个 agent 提供独立的"房间"。它的自动化任务能力(room-cli automation)支持 cron 周期定时、一次性延迟 与 Webhook 触发三种玩法,由云端调度驱动——Mac 合盖睡觉、甚至关机,AI 任务依然按时开工。
📌 本指南面向新手:不写代码,只讲清楚"何时用哪种触发、命令怎么敲、结果去哪看"。
为什么需要"云端自动化"?
用本地 CLI 跑 AI 编码任务有个经典痛点:人不在电脑前,任务就停。
- 下班回家,想定时批量重构代码——没人盯着;
- 睡前想让 AI 跑一轮回归并汇总报告——Mac 不能不合盖;
- 等外部服务发 Webhook 才该干活——本地电脑总不能 7×24 开着。
Cloudroom 的思路是把"运行环境"搬进云端:每个 agent 都有独立沙箱,定时与调度发生在云端,而不是你的 Mac 上。这就是"Mac 睡了,AI 也按时开工"的秘密所在。
图源:项目架构图(docs/architecture.png)。可以看到 Mac 与云端沙箱是解耦的——沙箱由云端唤醒与调度。
自动化任务的四种触发方式
创建自动化任务用 room-cli automation create(应用里叫 loop,room-cli loop 是同一命令)。一条命令只能选 一种 触发方式:
| 触发方式 | 命令片段 | 适用场景 |
|---|---|---|
| cron 周期定时 | --cron '分 时 日 月 周' [--timezone 时区] |
每天凌晨跑、每周一汇总等周期任务 |
| 指定时刻 | --at ISO时间 |
在某个精确时间点运行一次 |
| 延迟运行 | --in 30m |
"半小时后提醒我"这类一次性延迟任务 |
| Webhook 触发 | --webhook |
由外部事件(CI、监控、表单)推送才开工 |
一个典型的每日晨报循环:
room-cli automation create --name 每日晨报 --prompt '汇总今天的提交与改动' --cron '0 9 * * *' --timezone Asia/Shanghai --new-thread
几点新手须知:
- ✅ cron 表达式必须是 5 字段(分 时 日 月 周),写错会被拒绝;
- ✅ 时区用
--timezone显式指定,避免按沙箱默认时区跑偏; - ⚠️ Webhook 与脚本脚本(script)暂时不能同时使用。
两种执行模式:新线程还是原线程?
定时循环默认行为有两种,按需选择:
--new-thread(每次开新线程):每个 cron 周期都启动一个全新的云端线程,跑在独立沙箱里,自动继承当前线程的项目与 agent 设置。适合"每次都要干净环境"的批处理。--same-thread(沿用当前线程):不另开线程,直接在当前线程上重发 prompt,保留上下文。适合需要"接着上次聊"的任务。
一次性任务(--at / --in)默认沿用当前线程,加上 --new-thread 才会开新线程。
Webhook 触发:让外部事件唤醒 AI
--webhook 模式不靠时钟,而靠"被推送":
- 创建时打印一个唯一的秘密 URL(注意:只打印一次);
- 任何服务向这个 URL 发
POST,就会触发该循环; - 收到的请求体会作为 data 注入本次运行的 prompt,AI 可以直接读到事件内容;
- 想换 URL?用
room-cli automation hook <ID>重新生成。
典型用法:CI 构建完成、监控告警、表单提交……只要能发 HTTP 请求,就能"按一下 AI 就开工",完全不必等定时到点。
可选:运行前先跑一段脚本
创建时可加 --script / --script-file,让脚本先于 prompt 执行(限 60 秒):
- 脚本在自动化专属沙箱中运行,拿到全新线程;
- 脚本无输出则跳过本次运行;
- 脚本有输出则拼接进 prompt,相当于给 AI 动态喂数据。
这就把"先取数据、再让 AI 处理"两步合一了。
管理自动化任务:暂停、手动跑、查看
创建只是开始,日常离不开这几个命令(list 会显示每个循环的下次运行时间或错误原因):
room-cli automation list
pause/resume:暂停 / 恢复调度;run:不等定时,立即手动触发一次——调 prompt 时特别好用;update:修改名称、prompt、定时、脚本、模型等;delete:删除循环;hook:重新生成 Webhook URL。
💡 新手建议:先用 --in 1m 试跑一次确认 prompt 没问题,再切成 --cron 长期跑。
Mac 睡着了,为什么 AI 还按时开工?
这是 Cloudroom 自动化的核心卖点,机制很简单:
- 调度与执行都在云端。Cloudroom 由云端侧的 cron 调度器每分钟检查到期的任务,唤醒对应沙箱并发送 prompt——不依赖你的 Mac 是否在线。
- Mac 离线不影响定时循环。即便你合盖、关机,
--new-thread的定时循环依然会在云端开新线程执行;从云端线程里执行room-cli automation命令也照常工作。 - 会话休眠只是释放进程,不是删除。Cloudroom 对空闲 30 分钟的会话会释放 harness 进程(见会话生命周期文档),历史保留在盘上;下一条 prompt 会自动唤醒并恢复原生会话。
一句话:睡前把定时或 Webhook 自动化建好,合上 Mac,醒来就能看到新线程里跑完的结果。
常见问题排查
- 报错
Use a 5-field cron:cron 不是 5 字段,检查是否多写/漏写字段。 - 想按本地时间定时:务必加
--timezone Asia/Shanghai。 - Webhook URL 忘了?:
hook命令会重新生成,旧 URL 作废。 - 定时"没到点":先
room-cli automation list看下次运行时间或错误信息。 - 新线程循环跑的不是预期模型:用
--provider/--model指定,或在list里查看每个循环当前用的 agent。
相关文档与源码
想深入细节,可参考这些相对路径的资料:
- 📖 room-cli 自动化技能说明(
src/mac/room-cli/SKILL.md) - 📖 云端会话生命周期与休眠机制(
docs/session-lifecycle.md) - 📖 自动化核心实现(
src/session/automation.rs) - 📖 会话休眠模块(
src/session/sleep.rs) - 🖼️ 项目架构图(
docs/architecture.png)
小结:
room-cli automation把"定时、事件驱动"搬进云端。cron 周期、一次性延迟、Webhook 推送三选一,配合--new-thread/--same-thread与list/pause/run管理命令,就能让 AI 在你离线时依旧准时开工。
