OpenClaw API: How to Build Integrations and Extend Your Agent

API Architecture

OpenClaw's API is served by the gateway — the core process that manages your agent, handles message routing, and exposes HTTP/WebSocket endpoints.

The gateway runs on port 18789 by default (configurable).

Your App → HTTP/WS → OpenClaw Gateway → Agent → AI Model
                                       ↓
                                    Tools, Skills, Memory

Starting the Gateway

Start the gateway process and verify it's running before making API calls.

# Start the gateway
openclaw gateway start

# Check status
openclaw gateway status

# The API is now available at http://localhost:18789

Authentication

The gateway uses token-based authentication.

**Security note:** Never expose port 18789 to the public internet without authentication. See our security hardening guide for best practices. Consider running behind Tailscale for zero-trust access.

# Set a gateway token
openclaw config set gateway.token your-secret-token

# All API requests must include the token
curl -H "Authorization: Bearer your-secret-token" http://localhost:18789/api/status

Core API Endpoints

**Status** — Check if the gateway is running and healthy with GET /api/status. The response includes version, uptime, active agent, and current model.

**Send a Message** — The most useful endpoint. Send a message to your agent and get a response via POST /api/sessions/main/messages. This is the foundation for building any custom integration — your app sends a message, gets a response.

**Session Management** — List active sessions with GET /api/sessions, get session history with GET /api/sessions/:sessionKey/history, or create a new isolated session with POST /api/sessions. Sessions let you separate conversations. Your main chat is one session; a webhook handler could be another; a background automation could be a third.

**Cron Jobs** — List cron jobs with GET /api/cron, create them with POST /api/cron, or delete with DELETE /api/cron/:id. For more on scheduling, see our cron jobs guide.

# Check if the gateway is running and healthy
GET /api/status

# Response:
{
  "ok": true,
  "version": "2026.2.23",
  "uptime": 86400,
  "agent": "main",
  "model": "anthropic/claude-sonnet-4"
}

# Send a message to the main agent session
POST /api/sessions/main/messages
Content-Type: application/json

{
  "message": "What's on my calendar today?"
}

# Response:
{
  "response": "You have 3 events today: Team standup at 9 AM, lunch with Sarah at noon, and dentist at 4 PM.",
  "sessionKey": "agent:main:main"
}

# List active sessions
GET /api/sessions

# Get session history
GET /api/sessions/:sessionKey/history

# Create a new isolated session
POST /api/sessions
{
  "label": "my-custom-session",
  "target": "isolated"
}

# List cron jobs
GET /api/cron

# Create a cron job
POST /api/cron
{
  "name": "Morning briefing",
  "cron": "0 8 * * *",
  "tz": "Asia/Hong_Kong",
  "message": "Check email, calendar, and weather. Send me a morning summary."
}

# Delete a cron job
DELETE /api/cron/:id

Practical Examples

**Webhook Integration** — Trigger your agent from any webhook — GitHub, Stripe, monitoring alerts. Now your agent gets notified about GitHub events and can summarize them in your Telegram/WhatsApp chat.

**Custom Dashboard** — Build a simple web dashboard that queries your agent for status, sessions, and recent message history.

**Automated Research Pipeline** — Chain API calls for automated workflows. Ask the agent to research a topic and save the output to a daily report file.

**IoT and Smart Home** — Trigger your agent from smart home events like motion detection on cameras.

// Express.js webhook handler
app.post('/webhook/github', (req, res) => {
  const event = req.body;

  fetch('http://localhost:18789/api/sessions/main/messages', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer your-token',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      message: `GitHub event: ${event.action} on ${event.repository.name}. ${event.pull_request?.title || ''}`
    })
  });

  res.sendStatus(200);
});

// Fetch agent status and recent messages
async function getDashboard() {
  const status = await fetch('/api/status', { headers: authHeaders });
  const sessions = await fetch('/api/sessions', { headers: authHeaders });
  const history = await fetch('/api/sessions/main/history?limit=10', { headers: authHeaders });

  return {
    status: await status.json(),
    sessions: await sessions.json(),
    recentMessages: await history.json()
  };
}

#!/bin/bash
# Daily research pipeline

# Ask the agent to research a topic
RESPONSE=$(curl -s -X POST http://localhost:18789/api/sessions/research/messages \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "Search for the latest AI agent news and write a summary"}')

# Extract the response and save it
echo "$RESPONSE" | jq -r '.response' > ~/reports/$(date +%Y-%m-%d).md

# Home Assistant automation
import requests

def on_motion_detected(camera_name):
    requests.post('http://openclaw:18789/api/sessions/main/messages',
        headers={'Authorization': 'Bearer token'},
        json={'message': f'Motion detected on {camera_name}. Check the camera and let me know if anything looks unusual.'}
    )

WebSocket API

For real-time communication, use the WebSocket endpoint. WebSockets are useful for real-time streaming responses, building custom chat interfaces, and monitoring agent activity live.

const ws = new WebSocket('ws://localhost:18789/ws?token=your-token');

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: 'message',
    session: 'main',
    content: 'Hello!'
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Agent response:', data.content);
};

CLI as an API

The openclaw CLI itself is a powerful interface. The CLI is often simpler than HTTP calls for scripting.

# Send a message from scripts
openclaw send "Check my email" --session main

# Run a one-off task
openclaw run "Summarize the top HackerNews stories today"

# List and manage cron jobs
openclaw cron list
openclaw cron add --name "task" --cron "0 9 * * *" --message "Do something"

Rate Limits and Best Practices

Follow these best practices when building on the OpenClaw API.

• **Don't spam the API.** Each message triggers an AI inference call (which costs money)
• **Use isolated sessions** for automated workflows to keep them separate from your personal chat
• **Set timeouts** on API calls — AI responses can take 5-30 seconds
• **Monitor usage** with openclaw status to track token consumption
• **Use cron jobs** instead of polling — let OpenClaw handle scheduling

Conclusion

The OpenClaw API opens up endless possibilities. Build custom skills that extend your agent, set up automation workflows, connect to email and calendar, or explore the growing ClawHub skill ecosystem. The API is the foundation for making OpenClaw truly yours. New to OpenClaw? Start with our beginner guide before diving into the API.

Frequently asked questions