OpenClaw API: The Complete Automation Power Guide

Teams that connect OpenClaw to their existing toolchain — Zapier, n8n, custom backends, cron schedulers — get three times the utility from their agent setup. The REST API is the bridge. Eleven core endpoints cover everything from triggering agent tasks to reading pipeline state. Here's the complete picture in one guide.

API Overview and Base URL

The OpenClaw REST API is served by the gateway. It's available at /api/v1/ relative to your gateway's domain. For a local development setup, that's http://localhost:8080/api/v1/. For a production setup behind your reverse proxy, it's https://your-domain.com/api/v1/.

All responses are JSON. All request bodies that include data must be JSON with Content-Type: application/json. The API follows standard HTTP conventions — GET for reads, POST for creates, DELETE for removals. Response codes follow the usual semantics: 200 for success, 400 for bad requests, 401 for auth failures, 404 for missing resources, 500 for server errors.

As of early 2025, the OpenClaw API is at version v1. The version is included in the path so you can pin integrations to a specific version and update on your own schedule when breaking changes arrive.

Authentication

Every API request must include an Authorization header with your gateway token as a Bearer token.

curl -H "Authorization: Bearer your-gateway-token" \
     https://your-domain.com/api/v1/channels

The gateway token is the same secret you configure in gateway.yaml. All agents use it to register with the gateway, and all API clients use it to call the API. This simplifies credential management — one secret controls both agent connections and API access.

Core Endpoints Reference

Here are the endpoints you'll use in most integrations.

Sending Messages to Agents via API

This is the most commonly used endpoint. Send a POST request to /api/v1/messages with the target channel ID and message body. The agent processes it identically to a message arriving from Telegram, WhatsApp, or any other channel.

curl -X POST https://your-domain.com/api/v1/messages \
  -H "Authorization: Bearer your-gateway-token" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "researcher-001",
    "message": "Research the latest developments in quantum error correction published in January 2025",
    "metadata": {
      "task_id": "task-99",
      "source": "cron-scheduler"
    }
  }'

The response includes a message ID you can use to track the task. The agent's response appears in the message history endpoint and, if configured, via webhook to your registered URL.

Use the metadata field to pass context that helps you correlate API responses to the triggering request in your external system. Task IDs, source labels, and priority flags all belong here — they're logged but not passed to the agent's context.

Webhooks: Receive Agent Responses Without Polling

Register a webhook to get notified when an agent sends a response. OpenClaw will POST the response payload to your URL immediately when the agent finishes — no polling required.

curl -X POST https://your-domain.com/api/v1/webhooks \
  -H "Authorization: Bearer your-gateway-token" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/hooks/openclaw",
    "events": ["message.sent", "task.completed", "agent.error"],
    "channel_id": "researcher-001",
    "secret": "your-webhook-signing-secret"
  }'

Set a secret in your webhook registration. OpenClaw signs every outgoing webhook payload with this secret using HMAC-SHA256. Verify the signature on your endpoint to confirm the payload is genuine and hasn't been tampered with. This is the same pattern used by Stripe, GitHub, and Twilio.

Common API Integration Mistakes

• Polling message history in a tight loop — polling every second generates unnecessary load. Use webhooks for near-realtime notifications, or poll at a reasonable interval (10–30 seconds) for batch workloads.
• Ignoring response codes — a 503 from the API means the gateway is overloaded, not that your request was processed. Always handle non-200 responses with retry logic and exponential backoff.
• Not verifying webhook signatures — anyone can POST to your webhook URL. Always verify the HMAC-SHA256 signature before acting on a webhook payload.
• Storing the gateway token in source code — use environment variables or a secret manager. Token rotation is easier when the token isn't embedded in twelve files.
• Not setting a message TTL on API-triggered tasks — if your external system sends a task but the target agent is temporarily offline, the message queues. Without a TTL, outdated tasks may be processed hours later. Set an appropriate expiry in the message metadata.

Frequently Asked Questions

What can I do with the OpenClaw REST API?

The REST API lets you send messages to any agent channel, query agent status, read and write shared memory, manage channel registrations, trigger tasks from external systems, and retrieve conversation history. It's the integration layer connecting OpenClaw to your existing tools.

How do I authenticate with the API?

Include your gateway token in the Authorization header as a Bearer token: Authorization: Bearer your-gateway-token. The same token configured in gateway.yaml authenticates API calls. Keep it secret — anyone with it can control your entire agent system.

What is the base URL for the API?

The API base URL is your gateway URL followed by /api/v1/. For production: https://your-domain.com/api/v1/. For local development: http://localhost:8080/api/v1/. All endpoints are relative to this base.

Can I send messages to an agent without a user interface?

Yes. POST to /api/v1/messages with a channel ID and message body. The agent processes it identically to a user message from any other channel. This is how you integrate OpenClaw into automation pipelines — cron jobs, webhook handlers, and external systems can trigger agent tasks directly.

Does the API support webhooks for receiving responses?

Yes. Register a webhook URL via /api/v1/webhooks and specify which events to listen for. When the agent responds or triggers an event, OpenClaw POSTs the payload to your URL. This enables push-based integrations without polling.

Is there a rate limit on the API?

Rate limits are configurable in gateway.yaml — none are enforced by default. For production, set per-client limits to prevent runaway scripts from overwhelming your agents or LLM API quotas. A typical starting point is 30 requests per minute per API key.