System Events

+15 Mana ✨
OpenClaw System Events(DOCUMENTATION)OpenClaw Automation Patterns(DOCUMENTATION)

Introduction

System events are a way to inject instructions into your OpenClaw agent programmatically, either for immediate processing or queued for the next heartbeat turn. Unlike webhooks which are triggered by external services, system events are sent by you or your scripts to control agent behavior on demand. This lesson covers the system event command, its delivery modes, and practical use cases.

Key Concepts

  • System Event: A programmatic instruction sent to an agent via the CLI or API
  • --mode now: Delivers the event immediately, creating a new agent turn right away
  • --mode next-heartbeat: Queues the event to be processed during the next heartbeat cycle
  • Event Text: The instruction text that the agent receives and processes
  • Event Queueing: The mechanism that stores events until the next heartbeat turn

Real World Context

A CI/CD pipeline finishes a deployment and needs to notify the OpenClaw agent to run post-deployment validation. The pipeline script sends a system event with mode "now" so the agent starts validation immediately, without waiting for the next heartbeat cycle. Later, a monitoring script detects a minor warning and sends an event with mode "next-heartbeat" to include it in the regular check cycle rather than interrupting the agent's current work.

Deep Dive

Sending System Events

The basic command to send a system event:

bash
openclaw system event \
  --text "Run post-deployment smoke tests on staging" \
  --mode now

This sends an event to the agent with immediate delivery. The agent creates a new turn, processes the instruction, and responds. The --mode now flag means the event is handled right away, regardless of the heartbeat schedule.

Deferred Events with next-heartbeat

For non-urgent events, queue them for the next heartbeat:

bash
openclaw system event \
  --text "Minor: Disk usage on node-3 reached 75%" \
  --mode next-heartbeat

This event is stored in a queue and delivered to the agent during the next heartbeat turn. The agent processes it alongside its regular heartbeat checklist items. This is efficient because it batches the event with other scheduled work rather than creating a separate turn.

Using System Events in Scripts

System events integrate naturally into automation scripts:

bash
#!/bin/bash
# post-deploy.sh - runs after successful deployment

DEPLOY_ENV=$1
DEPLOY_SHA=$2

openclaw system event \
  --text "Deployment completed: env=$DEPLOY_ENV sha=$DEPLOY_SHA. Run smoke tests and verify all endpoints return 200." \
  --mode now

echo "Agent notified of deployment"

This script sends a system event after a deployment, passing the environment and commit SHA to the agent. The agent then runs the requested smoke tests using this context.

Comparing Delivery Modes

The two modes serve different purposes:

bash
# Immediate: agent drops everything and handles this now
openclaw system event --text "CRITICAL: Database is down" --mode now

# Deferred: handled in next regular cycle
openclaw system event --text "FYI: New team member joined" --mode next-heartbeat

Use now for critical events that require immediate attention. Use next-heartbeat for informational events that can wait for the regular heartbeat cycle. The deferred mode is more cost-efficient because it batches processing with other heartbeat items.

Common Pitfalls

  • Using --mode now for every event: This creates a new agent turn for each event, which is expensive. Reserve immediate mode for genuinely urgent situations.
  • Forgetting that next-heartbeat events depend on heartbeat being enabled: If the agent's heartbeat is disabled, queued events will never be delivered until heartbeat is re-enabled.
  • Sending events with insufficient context: The agent receives only the text you provide. Include enough details for the agent to act without needing to ask follow-up questions.

Best Practices

  • Default to next-heartbeat mode for non-critical events to batch processing and reduce costs.
  • Include actionable context in event text so the agent can process the event without additional tool calls.
  • Use system events in CI/CD pipelines as the bridge between your automation infrastructure and your OpenClaw agent.

Summary

  • System events let you send programmatic instructions to your agent via CLI or API
  • The --mode now flag delivers events immediately, creating a new agent turn
  • The --mode next-heartbeat flag queues events for the next heartbeat cycle
  • Immediate mode is for critical events; deferred mode is for informational updates
  • Include sufficient context in event text for the agent to act autonomously
✓ Completed