Initial commit with translated description
This commit is contained in:
114
SKILL.md
Normal file
114
SKILL.md
Normal file
@@ -0,0 +1,114 @@
|
|||||||
|
---
|
||||||
|
name: cron-mastery
|
||||||
|
description: "掌握OpenClaw的定时系统。用于安排可靠的提醒、设置定期维护和理解何时使用Cron与Heartbeat。"
|
||||||
|
---
|
||||||
|
|
||||||
|
# Cron Mastery
|
||||||
|
|
||||||
|
**Rule #1: Heartbeats drift. Cron is precise.**
|
||||||
|
|
||||||
|
This skill provides the definitive guide for managing time in OpenClaw 2026.2.15+. It solves the "I missed my reminder" problem by enforcing a strict separation between casual checks (heartbeat) and hard schedules (cron).
|
||||||
|
|
||||||
|
## The Core Principle
|
||||||
|
|
||||||
|
| System | Behavior | Best For | Risk |
|
||||||
|
| :--- | :--- | :--- | :--- |
|
||||||
|
| **Heartbeat** | "I'll check in when I can" (e.g., every 30-60m) | Email checks, casual news summaries, low-priority polling. | **Drift:** A "remind me in 10m" task will fail if the heartbeat is 30m. |
|
||||||
|
| **Cron** | "I will run at exactly X time" | Reminders ("in 5 mins"), daily reports, system maintenance. | **Clutter:** Creates one-off jobs that need cleanup. |
|
||||||
|
|
||||||
|
## 1. Setting Reliable Reminders (2026.2.15+ Standard)
|
||||||
|
|
||||||
|
**Rule:** Never use `act:wait` or internal loops for long delays (>1 min). Use `cron:add` with a one-shot `at` schedule.
|
||||||
|
|
||||||
|
### Precision & The "Scheduler Tick"
|
||||||
|
While Cron is precise, execution depends on the **Gateway Heartbeat** (typically every 10-60s). A job set for `:00` seconds will fire on the first "tick" after that time. Expect up to ~30s of variance depending on your gateway config.
|
||||||
|
|
||||||
|
### Modern One-Shot Reminder Pattern
|
||||||
|
Use this payload structure for "remind me in X minutes" tasks.
|
||||||
|
|
||||||
|
**Key Features (v2026.2.15+):**
|
||||||
|
- **Payload Choice:** Use **AgentTurn** with **Strict Instructions** for push notifications (reminders that ping your phone). Use **systemEvent** only for silent logs or background state updates.
|
||||||
|
- **Reliability:** `nextRunAtMs` corruption and "Add-then-Update" deadlocks are resolved.
|
||||||
|
- **Auto-Cleanup:** One-shot jobs auto-delete after success (`deleteAfterRun: true`).
|
||||||
|
|
||||||
|
**CRITICAL: Push Notifications vs. Silent Logs**
|
||||||
|
|
||||||
|
- **systemEvent (Silent):** Injects text into the chat history. Great for background logs, but **WILL NOT** ping the user's phone on Telegram/WhatsApp.
|
||||||
|
- **AgentTurn (Proactive):** Wakes an agent to deliver the message. **REQUIRED** for push notifications. Use the "Strict" prompt to avoid AI chatter.
|
||||||
|
|
||||||
|
**For push-notification reminders (Reliable):**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"name": "Remind: Water",
|
||||||
|
"schedule": { "kind": "at", "at": "2026-02-06T01:30:00Z" },
|
||||||
|
"payload": {
|
||||||
|
"kind": "agentTurn",
|
||||||
|
"message": "DELIVER THIS EXACT MESSAGE TO THE USER WITHOUT MODIFICATION OR COMMENTARY:\n\n💧 Drink water, Momo!"
|
||||||
|
},
|
||||||
|
"sessionTarget": "isolated",
|
||||||
|
"delivery": { "mode": "announce", "channel": "telegram", "to": "1027899060" }
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**For background logs (Silent):**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"name": "Log: System Pulse",
|
||||||
|
"schedule": { "kind": "every", "everyMs": 3600000 },
|
||||||
|
"payload": {
|
||||||
|
"kind": "systemEvent",
|
||||||
|
"text": "[PULSE] System healthy."
|
||||||
|
},
|
||||||
|
"sessionTarget": "main"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Cron Concurrency Rule (Stabilized)
|
||||||
|
Pre-2026.2.15, the "Add-then-Update" pattern caused deadlocks. While this is now stabilized, it is still **best practice** to pass all parameters (including `wakeMode: "now"`) directly in the initial `cron.add` call for maximum efficiency.
|
||||||
|
|
||||||
|
## 2. The Janitor (Auto-Cleanup) - LEGACY
|
||||||
|
|
||||||
|
**Note:** As of v2026.2.14, OpenClaw includes **maintenance recompute semantics**. The gateway now automatically cleans up stuck jobs and repairs corrupted schedules.
|
||||||
|
|
||||||
|
**Manual cleanup is only needed for:**
|
||||||
|
- One-shot jobs created with `deleteAfterRun: false`.
|
||||||
|
- Stale recurring jobs you no longer want.
|
||||||
|
|
||||||
|
### Why use `sessionTarget: "main"`? (CRITICAL)
|
||||||
|
Sub-agents (`isolated`) often have restricted tool policies and cannot call `gateway` or delete other `cron` jobs. For system maintenance like the Janitor, **always** target the `main` session via `systemEvent` so the primary agent (with full tool access) performs the cleanup.
|
||||||
|
|
||||||
|
## 3. Reference: Timezone Lock
|
||||||
|
|
||||||
|
For cron to work, the agent **must** know its time.
|
||||||
|
* **Action:** Add the user's timezone to `MEMORY.md`.
|
||||||
|
* **Example:** `Timezone: Cairo (GMT+2)`
|
||||||
|
* **Validation:** If a user says "remind me at 9 PM," confirm: "9 PM Cairo time?" before scheduling.
|
||||||
|
|
||||||
|
## 4. The Self-Wake Rule (Behavioral)
|
||||||
|
|
||||||
|
**Problem:** If you say "I'll wait 30 seconds" and end your turn, you go to sleep. You cannot wake up without an event.
|
||||||
|
**Solution:** If you need to "wait" across turns, you **MUST** schedule a Cron job.
|
||||||
|
|
||||||
|
* **Wait < 1 minute (interactive):** Only allowed if you keep the tool loop open (using `act:wait`).
|
||||||
|
* **Wait > 1 minute (async):** Use Cron with `wakeMode: "now"`.
|
||||||
|
|
||||||
|
## 5. Legacy Migration Guide
|
||||||
|
|
||||||
|
If you have old cron jobs using these patterns, update them:
|
||||||
|
|
||||||
|
| Legacy (Pre-2026.2.3) | Modern (2026.2.15+) |
|
||||||
|
| :--- | :--- |
|
||||||
|
| `"schedule": {"kind": "at", "atMs": 1234567890}` | `"schedule": {"kind": "at", "at": "2026-02-06T01:30:00Z"}` |
|
||||||
|
| `"deliver": true` in payload | Not needed - `announce` mode handles delivery |
|
||||||
|
| `"sessionTarget": "main"` | `"sessionTarget": "isolated"` (default behavior) |
|
||||||
|
| Manual ghost cleanup required | One-shots auto-delete (`deleteAfterRun: true`) |
|
||||||
|
| `cron.update` after `cron.add` | Single-step `cron.add` with all properties |
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
* **"My reminder didn't fire":** Check `cron:list`. Verify the `at` timestamp is in the future (ISO 8601 format). Ensure `wakeMode: "now"` is set.
|
||||||
|
* **"Gateway Timeout (10000ms)":** This happens if the `cron` tool takes too long (huge job list or file lock).
|
||||||
|
- **Fix 1:** Manually delete `~/.openclaw/state/cron/jobs.json` and restart the gateway if it's corrupted.
|
||||||
|
- **Fix 2:** Run a manual sweep to reduce the job count.
|
||||||
|
* **"Job ran but I didn't get the message":** Ensure you are using the **Strict Instruction Pattern** with `agentTurn` + `announce` mode for proactive pings.
|
||||||
|
* **"The reminder message has extra commentary":** The subagent is being conversational. Use the strict prompt pattern: `"DELIVER THIS EXACT MESSAGE TO THE USER WITHOUT MODIFICATION OR COMMENTARY:\n\n💧 Your message here"`
|
||||||
6
_meta.json
Normal file
6
_meta.json
Normal file
@@ -0,0 +1,6 @@
|
|||||||
|
{
|
||||||
|
"ownerId": "kn77tqkcm269sx2m1yqg1ja83n8090mv",
|
||||||
|
"slug": "cron-mastery",
|
||||||
|
"version": "1.0.3",
|
||||||
|
"publishedAt": 1771282970279
|
||||||
|
}
|
||||||
83
references/templates.md
Normal file
83
references/templates.md
Normal file
@@ -0,0 +1,83 @@
|
|||||||
|
# Cron Examples & Templates
|
||||||
|
|
||||||
|
## One-Shot Reminder (Push Notification / Reliable)
|
||||||
|
|
||||||
|
**Context:** User says "Remind me to check the oven in 15 mins."
|
||||||
|
**Best for:** Timers that MUST ping the user's phone.
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"action": "add",
|
||||||
|
"job": {
|
||||||
|
"name": "Oven Timer",
|
||||||
|
"schedule": {
|
||||||
|
"kind": "at",
|
||||||
|
"at": "2026-02-16T21:15:00+02:00"
|
||||||
|
},
|
||||||
|
"payload": {
|
||||||
|
"kind": "agentTurn",
|
||||||
|
"message": "DELIVER THIS EXACT MESSAGE TO THE USER WITHOUT MODIFICATION OR COMMENTARY:\n\n🔥 OVEN CHECK! It's been 15 minutes."
|
||||||
|
},
|
||||||
|
"sessionTarget": "isolated",
|
||||||
|
"delivery": {
|
||||||
|
"mode": "announce",
|
||||||
|
"channel": "telegram",
|
||||||
|
"to": "1027899060"
|
||||||
|
},
|
||||||
|
"wakeMode": "now"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## The Janitor (System Maintenance)
|
||||||
|
|
||||||
|
**Context:** Cleaning up finished one-shot jobs daily.
|
||||||
|
**Best for:** Running with full tool access in the main session.
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"action": "add",
|
||||||
|
"job": {
|
||||||
|
"name": "Daily Cron Sweep",
|
||||||
|
"schedule": {
|
||||||
|
"kind": "every",
|
||||||
|
"everyMs": 86400000
|
||||||
|
},
|
||||||
|
"payload": {
|
||||||
|
"kind": "systemEvent",
|
||||||
|
"text": "Time for the 24-hour cron sweep. List all cron jobs (includeDisabled: true). Delete any disabled jobs with lastStatus: ok. Report results."
|
||||||
|
},
|
||||||
|
"sessionTarget": "main",
|
||||||
|
"wakeMode": "now"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Complex Task (Recurring/Async)
|
||||||
|
|
||||||
|
**Context:** User says "Summarize my emails every morning at 8 AM."
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"action": "add",
|
||||||
|
"job": {
|
||||||
|
"name": "Morning Briefing",
|
||||||
|
"schedule": {
|
||||||
|
"kind": "cron",
|
||||||
|
"expr": "0 8 * * *",
|
||||||
|
"tz": "Africa/Cairo"
|
||||||
|
},
|
||||||
|
"payload": {
|
||||||
|
"kind": "agentTurn",
|
||||||
|
"message": "Good morning! Search for unread emails and top tech news, then summarize them."
|
||||||
|
},
|
||||||
|
"sessionTarget": "isolated",
|
||||||
|
"wakeMode": "now",
|
||||||
|
"delivery": {
|
||||||
|
"mode": "announce",
|
||||||
|
"channel": "telegram",
|
||||||
|
"to": "1027899060"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
Reference in New Issue
Block a user