API Overview

Gateway API overview, endpoints, and authentication

Gateway API Overview

The OpenClaw Gateway API provides programmatic access to agent interactions, session management, and real-time communication via WebSocket and REST endpoints.

Base URL

The Gateway API runs on your local or remote OpenClaw instance:

http://localhost:18789

The default port is 18789. You can configure this in your OpenClaw config:

gateway:
  port: 18789
  bind: loopback  # or "all" for remote access

API Transport

OpenClaw Gateway supports two transport mechanisms:

• WebSocket - Primary protocol for real-time bidirectional communication
• HTTP/REST - Alternative endpoints for specific use cases (OpenAI compatibility, hooks, tools)

Authentication

All API requests require authentication. See Authentication for details.

Quick example:

curl -X POST http://localhost:18789/api/endpoint \
  -H "Authorization: Bearer your-token-here" \
  -H "Content-Type: application/json" \
  -d '{"method": "example"}'

Rate Limits

The Gateway implements rate limiting for authentication attempts to prevent brute-force attacks:

• Limit: 20 failed authentication attempts per client
• Window: 60 seconds
• Response: 429 Too Many Requests with Retry-After header

Available Endpoints

WebSocket Protocol

• Gateway WebSocket: ws://localhost:18789/ - Primary RPC protocol
• Canvas WebSocket: ws://localhost:18789/canvas/ws - Canvas host communication

See WebSocket Protocol for details.

REST Endpoints

• OpenAI Compatibility: /v1/chat/completions - OpenAI-compatible chat endpoint
• Hooks: /hooks/* - Webhook endpoints for external integrations
• Tools Invoke: /api/tools/invoke - HTTP-based tool invocation
• Slack Events: /api/slack/events - Slack app event receiver
• Channels: /api/channels/* - Channel-specific HTTP endpoints

See REST Endpoints for details.

Response Format

WebSocket Responses

WebSocket responses follow the RPC frame format:

{
  "id": "request-id",
  "ok": true,
  "payload": { ... },
  "error": null
}

HTTP Responses

HTTP endpoints return standard JSON:

{
  "ok": true,
  "data": { ... }
}

Error responses:

{
  "error": {
    "message": "Error description",
    "type": "error_type",
    "code": "ERROR_CODE"
  }
}

Error Codes

Common error codes:

Code	Description
INVALID_REQUEST	Request validation failed
UNAUTHORIZED	Authentication failed
METHOD_NOT_FOUND	Unknown RPC method
INTERNAL_ERROR	Server error
RATE_LIMITED	Rate limit exceeded

WebSocket vs REST

Use WebSocket when:

• You need real-time bidirectional communication
• Subscribing to events (agent responses, presence, health)
• Invoking multiple RPC methods
• Building interactive clients (CLI, mobile apps, web UI)

Use REST when:

• Integrating with external systems via webhooks
• OpenAI-compatible API access
• Simple one-off requests
• Tool invocation from HTTP-based systems

Next Steps

Authentication

Learn about authentication methods

WebSocket Protocol

Connect via WebSocket

REST Endpoints

Use HTTP endpoints

Agent Protocol

Invoke agents via API