Scheduler Notification Runbook

---

name: scheduler-notification-runbook

description: Reliable runbook for scheduled reminders and notification workflows with OpenClaw cron. Use when creating or reviewing reminder skills, scheduling one-shot or recurring reminders, choosing between systemEvent and agentTurn payloads, selecting the correct sessionTarget, writing reminder text that will still read clearly when delivered later, validating whether a job actually fired, or troubleshooting why a scheduled notification did not deliver as expected. Especially useful for ClawHub-published skills that need production-safe reminder behavior instead of ad hoc cron setup.

---

# Scheduler Notification Runbook

Overview

Use this skill to create reliable reminder and scheduled notification workflows with OpenClaw cron.

Focus on production-safe decisions: choose the correct payload type, choose the correct session target, write reminder text that still makes sense when delivered later, and verify that the job actually fired and delivered.

Core workflow

1. Classify the scheduling need

Decide which of these cases applies before creating any job:

If the request is only a reminder and does not need reasoning at fire time, prefer a `systemEvent` reminder.

If the request needs the agent to think, check state, summarize, or perform a task when the time arrives, prefer an `agentTurn` job.

2. Choose the payload type

Use this decision rule:

#### Use `payload.kind = "systemEvent"` when:

This is the default reminder pattern for simple reminders.

#### Use `payload.kind = "agentTurn"` when:

Do not use `agentTurn` just to send a basic reminder that could be expressed in plain text.

3. Choose the session target

Match `sessionTarget` to the payload and the desired behavior.

#### Use `sessionTarget = "main"`

Only with `payload.kind = "systemEvent"`.

Use this for normal reminder injection into the main session.

Recommended when:

#### Use `sessionTarget = "isolated"`

Only with `payload.kind = "agentTurn"`.

Use this for scheduled work that should run independently and optionally announce a summary.

Recommended when:

#### Use `sessionTarget = "current"`

Only with `payload.kind = "agentTurn"`.

Use this when the future agent run must stay attached to the current session context.

Recommended when:

#### Use `sessionTarget = "session:<name>"`

Only with `payload.kind = "agentTurn"`.

Use this for durable named workflows that should accumulate their own thread history.

Recommended when:

Writing reminder text

Reminder text quality matters because the user will read it later, not now.

Write the text as if it has already arrived in the future.

Rules for good reminder text

Good patterns

#### Short-delay reminder

Use for reminders in minutes or within the same day:

#### Next-day or dated reminder

Use for tomorrow or specific dates/times:

#### Context-rich reminder

Use when the reminder could be ambiguous later:

Avoid

Schedule selection

Pick the simplest schedule that matches the request.

Use `schedule.kind = "at"` when:

Use `schedule.kind = "every"` when:

Use `schedule.kind = "cron"` when:

Prefer the least complex schedule that accurately matches the request.

Delivery decisions for agent jobs

Delivery matters only for `agentTurn` jobs.

Use `delivery.mode = "announce"` when:

Use `delivery.mode = "none"` when:

Use `delivery.mode = "webhook"` when:

Do not try to simulate webhook behavior through ad hoc messaging if webhook delivery is the correct abstraction.

Validation workflow

Always validate after creating or updating a scheduled reminder workflow.

Minimum validation checklist

1. Confirm the schedule shape matches the request

2. Confirm the payload type matches the real need

3. Confirm the session target is valid for that payload

4. Confirm the reminder text reads naturally in the future

5. Confirm the job is enabled

6. Capture the returned `jobId`

Recommended follow-up checks

Troubleshooting

Use this sequence when a scheduled reminder or notification did not behave as expected.

Problem: the job was created but nothing happened

Check:

Problem: the job fired but the message was confusing

Check:

Problem: an `agentTurn` job ran but did not deliver visibly

Check:

Problem: the wrong session received the follow-up

Check:

Problem: the reminder should have been simple but was over-engineered

Check:

Production guidance for ClawHub publication

When packaging this as a reusable public skill, keep the skill focused on durable decision-making rather than local environment specifics.

Include

Exclude

Reference material

Read `references/cron-patterns.md` when you need compact pattern guidance for one-shot reminders, recurring reminders, and agent-run notification workflows.

Read `references/examples.md` when you need ClawHub-friendly examples that show the difference between simple reminders, recurring reminders, isolated agent jobs, and same-thread follow-ups.