Poll Automation

+15 Mana ✨
OpenClaw Polling Guide(DOCUMENTATION)OpenClaw External Integrations(DOCUMENTATION)

Introduction

Polling in OpenClaw is a mechanism for periodically checking the state of external resources and triggering agent actions based on changes. Unlike webhooks which are push-based, polling is pull-based: your agent proactively queries external systems at configured intervals. This lesson covers how polls work, when to use them over webhooks, and how to configure poll automation.

Key Concepts

  • Poll: A periodic check that queries an external resource and compares the result against previous state
  • Poll Interval: The time between consecutive poll checks
  • State Comparison: Detecting changes by comparing the current poll result to the previous one
  • Poll Trigger: The action taken when a change is detected during a poll check
  • Pull-Based Monitoring: Actively querying external systems rather than waiting for them to push events

Real World Context

A development team uses a third-party issue tracker that does not support webhooks. They need their OpenClaw agent to monitor for new high-priority issues and notify the team in Slack. Since webhooks are not available, they configure a poll that checks the issue tracker API every 5 minutes, compares the results to the previous check, and triggers a notification when new high-priority issues appear.

Deep Dive

Configuring a Poll

Polls are defined in the agent's configuration:

json
{
  "polls": [
    {
      "id": "issue-tracker",
      "interval": 300,
      "endpoint": {
        "url": "https://tracker.example.com/api/issues?priority=high&status=open",
        "method": "GET",
        "headers": {
          "Authorization": "Bearer ${TRACKER_API_TOKEN}"
        }
      },
      "onChange": {
        "action": "notify",
        "channel": "slack",
        "message": "New high-priority issues detected"
      }
    }
  ]
}

This poll checks the issue tracker API every 300 seconds (5 minutes). When the response changes compared to the previous check, it sends a notification to Slack. The API token is stored securely as an environment variable.

State Comparison Strategies

Polls can detect changes in several ways:

json
{
  "polls": [
    {
      "id": "deploy-status",
      "interval": 60,
      "endpoint": {
        "url": "https://ci.example.com/api/deployments/latest"
      },
      "compareStrategy": "json-diff",
      "compareField": "status",
      "onChange": {
        "action": "system-event",
        "mode": "now",
        "text": "Deployment status changed: {{current.status}}"
      }
    }
  ]
}

The compareStrategy field controls how changes are detected. The json-diff strategy compares specific JSON fields. The compareField narrows the comparison to just the status field, ignoring other changes. When a change is detected, a system event is sent to the agent for immediate processing.

Poll Lifecycle

Polls follow a predictable lifecycle on each interval:

json
{
  "lifecycle": [
    "1. Fetch: Make HTTP request to configured endpoint",
    "2. Compare: Diff current response against stored previous response",
    "3. Store: Save current response as new baseline for next comparison",
    "4. Trigger: If changes detected, execute the configured onChange action",
    "5. Log: Record the poll execution, result, and any triggered actions"
  ]
}

Every poll execution follows these five steps. The stored response becomes the baseline for the next comparison, ensuring that only genuine changes trigger actions.

Common Pitfalls

  • Setting intervals too short for rate-limited APIs: A 10-second poll against an API with a 60-requests-per-minute limit will exhaust your quota quickly.
  • Not handling API errors in poll configuration: If the endpoint returns a 500 error, the poll should not treat it as a change. Configure error handling to skip comparisons on failed requests.
  • Using polls when webhooks are available: Polls are less efficient than webhooks. Always prefer webhooks when the external service supports them.

Best Practices

  • Use polls only when webhooks are unavailable or when you need to check state that does not emit events.
  • Set intervals based on the external API's rate limits to avoid exhausting quotas.
  • Use compareField to narrow change detection to only the fields you care about, reducing false positives.

Summary

  • Polls periodically check external resources and trigger actions on detected changes
  • Configure polls with an endpoint, interval, comparison strategy, and onChange action
  • State comparison strategies include full response diff and field-specific JSON diff
  • Each poll follows a fetch-compare-store-trigger-log lifecycle
  • Prefer webhooks when available; use polls as a fallback for services without webhook support
✓ Completed