Create Cron Job
Set up a scheduled task per conventions/cron.md. Read the convention first.
Need a periodic check instead? Consider HEARTBEAT.md — see "Cron vs Heartbeat" in conventions/cron.md.
Before You Start
Determine:
- - Which agent handles the job
- Main session (needs conversation context) or isolated (standalone)
- Delivery mode (announce, webhook, none)
Steps
1. Choose the execution mode
| Question | If yes | If no |
|---|
| Does the task need recent conversation context? | Main session | Isolated |
| Does the agent need its AGENTS.md/SOUL.md? |
Isolated (normal) | Isolated +
lightContext |
| Is this a one-shot reminder? |
--at with
--delete-after-run | Recurring schedule |
2. Choose a job name
Format: <agent-id>-<purpose> in kebab-case.
Examples: auditor-daily-report, archivist-daily-backup, INLINECODE9
3. Choose a schedule
| Pattern | CLI flag | Example |
|---|
| Cron expression | INLINECODE10 | INLINECODE11 (7 AM daily) |
| Fixed interval |
--every |
--every "4h" |
| One-shot (relative) |
--at |
--at "20m" |
| One-shot (absolute) |
--at |
--at "2026-03-15T09:00:00Z" |
Always set timezone for cron expressions: INLINECODE18
4. Create the job
Main session (task needs conversational context):
CODEBLOCK0
Isolated (standalone task):
CODEBLOCK1
Isolated + lightweight context (simple, self-contained chore):
CODEBLOCK2
One-shot reminder:
CODEBLOCK3
5. Bind to an agent
Always use --agent <agent-id> for agent-specific jobs.
6. Set delivery mode
- - Announce (most jobs): INLINECODE20
- Webhook: INLINECODE21
- None: omit delivery flags
7. Document in the agent's AGENTS.md
CODEBLOCK4
8. Create a skill if the job uses scripts
If the cron job executes scripts (not just a self-contained message), create a skill using the create-skill skill:
- - Scripts live in
workspace/skills/<skill-name>/scripts/, not in ad-hoc workspace directories - The skill makes the capability discoverable for on-demand use, not just cron
- Description should cover both automated (cron) and on-demand (user request) triggers
- See "Workspace File Placement" in
conventions/skills.md for where files belong
Skip if the cron job's message is fully self-contained (no external scripts or supporting files).
9. Test the job
CODEBLOCK5
Post-Creation Checklist
- - [ ] Job name follows
<agent-id>-<purpose> kebab-case convention - [ ] Timezone set for cron expressions (
--tz) - [ ] Explicit
--agent binding for agent-specific jobs - [ ] Delivery mode set (announce/webhook/none)
- [ ] Channel and target specified for announce delivery
- [ ] Agent's AGENTS.md updated with Scheduled Tasks entry
- [ ] Job tested with INLINECODE28
- [ ] No duplicate: checked that no system crontab or existing job covers the same task
- [ ] One-shot reminders use INLINECODE29
- [ ] If job uses scripts: skill created in
workspace/skills/<name>/ with scripts in its scripts/ subdir - [ ] No ad-hoc files or directories created at workspace root (see
conventions/skills.md)
创建定时任务
根据 conventions/cron.md 设置定时任务。请先阅读该规范。
需要周期性检查？ 请考虑 HEARTBEAT.md — 参见 conventions/cron.md 中的定时任务 vs 心跳检测。
开始之前
确定：
- - 哪个智能体处理该任务
- 主会话（需要对话上下文）还是隔离会话（独立运行）
- 交付模式（公告、Webhook、无）
步骤
1. 选择执行模式
| 问题 | 是 | 否 |
|---|
| 任务是否需要最近的对话上下文？ | 主会话 | 隔离会话 |
| 智能体是否需要其 AGENTS.md/SOUL.md？ |
隔离会话（常规） | 隔离会话 + lightContext |
| 是一次性提醒？ | --at 配合 --delete-after-run | 周期性调度 |
2. 选择任务名称
格式：<智能体ID>-<用途>，采用短横线命名法。
示例：auditor-daily-report、archivist-daily-backup、reminder-standup-meeting
3. 选择调度方式
| 模式 | CLI 标志 | 示例 |
|---|
| Cron 表达式 | --cron | --cron 0 7 *（每天上午7点） |
| 固定间隔 |
--every | --every 4h |
| 一次性（相对时间） | --at | --at 20m |
| 一次性（绝对时间） | --at | --at 2026-03-15T09:00:00Z |
始终为 cron 表达式设置时区：--tz America/Los_Angeles
4. 创建任务
主会话（任务需要对话上下文）：
bash
openclaw cron add \
--name <智能体ID>-<用途> \
--every <间隔> \
--session main \
--system-event <指令文本> \
--wake now
隔离会话（独立任务）：
bash
openclaw cron add \
--name <智能体ID>-<用途> \
--cron <表达式> \
--tz <时区> \
--session isolated \
--message <指令文本> \
--agent <智能体ID> \
--announce \
--channel <频道> \
--to <目标>
隔离会话 + 轻量上下文（简单、自包含的例行任务）：
bash
openclaw cron add \
--name <智能体ID>-<用途> \
--every <间隔> \
--session isolated \
--message <自包含指令> \
--light-context \
--announce
一次性提醒：
bash
openclaw cron add \
--name reminder-<用途> \
--at <时间> \
--session isolated \
--message <提醒文本> \
--announce \
--delete-after-run
5. 绑定到智能体
对于特定智能体的任务，始终使用 --agent <智能体ID>。
6. 设置交付模式
- - 公告（大多数任务）：--announce --channel <频道> --to <目标>
- Webhook：--webhook
- 无：省略交付标志
7. 在智能体的 AGENTS.md 中记录
markdown
定时任务
| 任务 | 调度 | 消息 | 操作 |
|---|
| <任务名称> | <调度> | <消息> | <智能体执行的操作> |
8. 如果任务使用脚本，则创建技能
如果定时任务执行脚本（不仅仅是自包含消息），使用 create-skill 技能创建技能：
- - 脚本存放在 workspace/skills/<技能名称>/scripts/ 中，而非临时工作区目录
- 技能使能力可被发现，不仅限于定时任务，还可按需使用
- 描述应涵盖自动化（定时任务）和按需（用户请求）两种触发方式
- 文件存放位置请参见 conventions/skills.md 中的工作区文件放置
如果定时任务的消息完全自包含（无外部脚本或支持文件），则跳过此步骤。
9. 测试任务
bash
openclaw cron run <任务ID> # 强制立即执行
openclaw cron list # 验证任务是否存在
openclaw cron runs --id <任务ID> # 检查运行历史
创建后检查清单
- - [ ] 任务名称遵循 <智能体ID>-<用途> 短横线命名法规范
- [ ] 为 cron 表达式设置时区（--tz）
- [ ] 为特定智能体的任务显式绑定 --agent
- [ ] 设置交付模式（公告/Webhook/无）
- [ ] 为公告交付指定频道和目标
- [ ] 在智能体的 AGENTS.md 中更新定时任务条目
- [ ] 使用 openclaw cron run <任务ID> 测试任务
- [ ] 无重复：检查系统 crontab 或现有任务未覆盖相同功能
- [ ] 一次性提醒使用 --delete-after-run
- [ ] 如果任务使用脚本：在 workspace/skills/<名称>/ 中创建技能，脚本放在其 scripts/ 子目录中
- [ ] 未在工作区根目录创建临时文件或目录（参见 conventions/skills.md）
