Async Queue

A lightweight, file-backed task queue that fires delayed tasks to any OpenClaw agent at a scheduled time. Consists of four components:

Installation (first time, macOS)

bash "$(openclaw skill path async-queue)/scripts/install.sh"

This will:

1. Copy daemon.js + push.js to ~/.openclaw/queue/
2. Copy the queue-wake plugin to ~/.openclaw/extensions/queue-wake/
3. Register the daemon under launchd (auto-starts on login, auto-restarts on crash)

Then restart the OpenClaw gateway to activate the plugin:

openclaw gateway restart

Push a task

node ~/.openclaw/queue/push.js --task "description" --delay \x3C10s|5m|2h|HH:MM|H:MMam/pm> [--to \x3CagentId>] [--then "next task text"]

Arguments:

• --to — agent name (e.g. main). Can also be a full session key like agent:main:main. Optional; defaults to queue/config.json.defaultTo if set, else marcus.
• --task — what the agent should do when this fires
• --delay — how long from now: 10s, 5m, 2h, or absolute time: HH:MM (24h) / H:MMam (12h)
• --then — optional chained task text to enqueue immediately after this task fires
• --ttl — (optional) seconds before item expires if undelivered (default: 300)

Examples:

# Remind in 30 minutes
node ~/.openclaw/queue/push.js --to main --task "Follow up: did the user save that document?" --delay 30m

# Check deploy health in 5 minutes
node ~/.openclaw/queue/push.js --to main --task "Verify deploy is healthy — check HTTP status" --delay 5m

# Fire today at 6:30 PM (or tomorrow if already past)
node ~/.openclaw/queue/push.js --task "Ping me before dinner" --delay 6:30pm

# Tonight reminder
node ~/.openclaw/queue/push.js --to main --task "Ask user about the pending decision" --delay 2h

# Chain a follow-up immediately after the first task fires
node ~/.openclaw/queue/push.js --task "Run deploy checks" --delay 10m --then "Verify logs are clean"

When to use this skill

Use async-queue when:

• User asks to be reminded about something in X minutes/hours
• You spawn a sub-agent or background job and need to check back on it
• A follow-up needs to happen after a delay (e.g. verify a deploy, nudge a pending action)
• Any work that can't be completed this turn and needs to continue later

Don't use async-queue for:

• Immediate actions → just do them
• Recurring schedules → use openclaw cron
• Tasks waiting on user input → message the user directly

Schema

{
  "id": "uuid",
  "to": "agentId",
  "task": "string — what to execute when this fires",
  "then": "string — optional chained task to enqueue after successful fire",
  "runAt": "ISO 8601 timestamp",
  "createdAt": "ISO 8601 timestamp",
  "ttl": 300
}

ttl: seconds the item may remain undelivered before being dropped (default: 300s). Increase for tasks scheduled many hours out if the daemon might miss a window.

Delivery flow

push.js → queue.json → daemon.js (polls 30s)
   → POST /api/queue-wake (queue-wake plugin)
      → enqueueSystemEvent([QUEUE:agentId] task)
      → requestHeartbeatNow(agentId)
         → agent wakes, sees task in context

Check queue state

cat ~/.openclaw/queue/queue.json         # pending items
node ~/.openclaw/queue/queue-cli.js list # pretty list
node ~/.openclaw/queue/queue-cli.js history # last 20 deliveries
node ~/.openclaw/queue/queue-cli.js cancel \x3CidPrefix>
tail -20 ~/.openclaw/queue/daemon.log    # delivery history

Daemon status (macOS)

launchctl list | grep queue-daemon       # running?

# Restart if needed:
launchctl unload  ~/Library/LaunchAgents/ai.openclaw.queue-daemon.plist
launchctl load    ~/Library/LaunchAgents/ai.openclaw.queue-daemon.plist

Files installed

Protocol

See references/PROTOCOL.md for the full protocol: when to queue, rules, TTL guidance, and common task patterns.