Skip to main content

API Reference

The OpenClaw Gateway provides a REST API that allows external programs to interact with the Agent. The API listens on http://127.0.0.1:18789 by default.

Security Warning

The Gateway API should only be used locally. Never expose port 18789 to the public internet. For remote access, use an SSH tunnel or VPN. See Security Best Practices.

Authentication​

All API requests require an authentication token in the Header:

curl -H "Authorization: Bearer YOUR_GATEWAY_TOKEN" \
  http://127.0.0.1:18789/api/v1/health

Token is configured in ~/.openclaw/gateway.yaml:

gateway:
  auth:
    enabled: true
    token: "${GATEWAY_AUTH_TOKEN}"

Base URL​

http://127.0.0.1:18789/api/v1

All endpoints are prefixed with /api/v1.

Endpoint Overview​

MethodEndpointDescription
GET/healthHealth check
GET/statusSystem status
POST/messageSend a message to the Agent
GET/conversationsList conversations
GET/conversations/:idGet a specific conversation
DELETE/conversations/:idDelete a conversation
GET/memory/statsMemory system statistics
POST/memory/searchSearch memory
DELETE/memory/prunePrune memory
GET/skillsList installed skills
POST/skills/installInstall a skill
DELETE/skills/:nameRemove a skill
GET/channelsList connected messaging platforms
GET/configGet configuration (redacted)
PUT/configUpdate configuration
GET/logsGet logs

Messages​

POST /message​

Send a message to the Agent and get a response. This is the most commonly used endpoint.

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"channel": "api", "message": "What is the weather like tomorrow?"}' \
  http://127.0.0.1:18789/api/v1/message

Parameters:

ParameterTypeRequiredDescription
channelstringYesSource channel (api, telegram, internal, etc.)
messagestringYesMessage content
conversation_idstringNoConversation ID (omit to create new)
wait_for_responsebooleanNoWait for response (default true)
timeout_msintegerNoTimeout in ms (default 30000)

Streaming Response​

Supports Server-Sent Events (SSE) for streaming responses:

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"channel": "api", "message": "Write a poem"}' \
  http://127.0.0.1:18789/api/v1/message

Error Handling​

All error responses follow a unified format:

{
  "error": "error_code",
  "message": "Human-readable error description",
  "status": 400,
  "details": {}
}

Common Error Codes​

HTTP StatusError CodeDescription
400bad_requestMalformed request
401unauthorizedAuthentication failed
403forbiddenInsufficient permissions
404not_foundResource not found
408timeoutRequest timed out
429rate_limitedRate limit exceeded
500internal_errorInternal error
503service_unavailableService unavailable

SDKs & Client Libraries​

Node.js​

import { OpenClawClient } from '@openclaw/sdk';

const client = new OpenClawClient({
  baseUrl: 'http://127.0.0.1:18789',
  token: process.env.GATEWAY_AUTH_TOKEN,
});

const response = await client.message('What is the weather tomorrow?');
console.log(response.content);

Python​

from openclaw import OpenClawClient

client = OpenClawClient(
    base_url="http://127.0.0.1:18789",
    token=os.environ["GATEWAY_AUTH_TOKEN"],
)

response = client.message("What is the weather tomorrow?")
print(response.content)

WebSocket API​

The Gateway also provides WebSocket connections for real-time communication:

const ws = new WebSocket('ws://127.0.0.1:18789/ws');

ws.onopen = () => {
  ws.send(JSON.stringify({ type: 'auth', token: 'YOUR_TOKEN' }));
};

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

Further Reading​