Gateway Protocol Explained

Protocol Overview

OpenClaw Gateway uses multiple communication protocols to interact with different clients and services:

HTTP REST API: For management operations and synchronous requests
WebSocket: For real-time bidirectional communication
Server-Sent Events (SSE): For streaming responses
Webhook HTTP POST: For receiving messages from channel platforms

HTTP REST API

Base Endpoints

GET    /health              Health check
GET    /api/status           Service status
POST   /api/chat             Send message
GET    /api/models           Get model list
GET    /api/channels         Get channel list
GET    /api/sessions         Get session list
POST   /api/sessions/:id     Operate on a session

Request Format

All API requests use JSON:

curl -X POST https://gateway.example.com/api/chat \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "api",
    "message": "Hello",
    "sessionId": "session-123",
    "stream": false
  }'

Response Format

{
  "success": true,
  "data": {
    "message": "Hello! How can I help you?",
    "sessionId": "session-123",
    "model": "gpt-4o",
    "usage": { "promptTokens": 15, "completionTokens": 12, "totalTokens": 27 }
  },
  "timestamp": "2026-03-10T08:30:00Z"
}

Streaming Responses (SSE)

When stream: true, the Gateway uses Server-Sent Events:

curl -X POST https://gateway.example.com/api/chat \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"channel": "api", "message": "Write a poem", "stream": true}'

SSE event stream format:

event: message
data: {"type": "chunk", "content": "Roses"}

event: message
data: {"type": "chunk", "content": " are"}

event: message
data: {"type": "chunk", "content": " red"}

event: message
data: {"type": "done", "usage": {"totalTokens": 50}}

WebSocket Protocol

WebSocket connections for real-time bidirectional communication:

const ws = new WebSocket('wss://gateway.example.com/ws');

ws.onopen = () => {
  ws.send(JSON.stringify({ type: 'auth', token: 'your-api-key' }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log(data);
};

WebSocket Message Types

Client to Server:

{"type": "auth", "token": "api-key"}
{"type": "message", "channel": "api", "content": "Hello", "sessionId": "s1"}
{"type": "ping"}
{"type": "subscribe", "events": ["message", "status"]}

Server to Client:

{"type": "auth_ok", "user": "admin"}
{"type": "message", "content": "Hello!", "sessionId": "s1"}
{"type": "chunk", "content": "partial", "sessionId": "s1"}
{"type": "done", "sessionId": "s1", "usage": {}}
{"type": "pong"}
{"type": "error", "code": "INVALID_SESSION", "message": "..."}

Health Check Protocol

GET /health           # Returns: {"status": "ok"}
GET /health/detailed  # Returns detailed status with providers, channels, memory

API Versioning

/api/v1/chat    ← Current stable version
/api/v2/chat    ← New version (if available)

Rate Limit Headers

Gateway includes rate limit info in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1709020800

Summary

Understanding Gateway communication protocols is essential for developing custom integrations and troubleshooting. HTTP REST API works for simple integration, WebSocket for real-time interaction, and SSE for streaming output. All protocols support authentication and rate limiting.