HTTP API Endpoints

+15 Mana ✨
OpenClaw HTTP API(DOCUMENTATION)

Introduction

OpenClaw exposes an OpenAI-compatible HTTP API, allowing any tool or application that speaks the OpenAI protocol to use your OpenClaw gateway as a model backend. This means IDEs, CLI tools, and custom applications can connect to your agents without any OpenClaw-specific integration.

Key Concepts

  • OpenAI-Compatible API: An HTTP endpoint that follows the OpenAI /v1/chat/completions contract, making OpenClaw a drop-in replacement for OpenAI in any compatible tool.
  • Model Routing: Requests specify a model name, and OpenClaw routes them to the appropriate agent and underlying model provider.
  • Streaming Support: The API supports Server-Sent Events (SSE) streaming for real-time response delivery.
  • Tool Use: The API supports OpenAI-format tool definitions, which map to OpenClaw agent tools.

Real World Context

A development team uses Cursor IDE, which supports OpenAI-compatible backends. By pointing Cursor to the OpenClaw API, developers get AI assistance powered by their custom agents with company-specific knowledge, memory, and tool access — all through the IDE they already use.

Deep Dive

The API is available at http://<gateway-host>:<port>/v1/chat/completions:

bash
curl http://localhost:18789/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${OPENCLAW_API_KEY}" \
  -d '{
    "model": "default",
    "messages": [
      {"role": "user", "content": "Explain the builder pattern in TypeScript"}
    ],
    "stream": true
  }'

This curl command sends a chat completion request to the local OpenClaw gateway. The model field specifies which agent to route to ("default" uses the default agent). The stream: true flag enables SSE streaming. The response format is identical to OpenAI's API.

The /v1/models endpoint lists available agents:

bash
curl http://localhost:18789/v1/models \
  -H "Authorization: Bearer ${OPENCLAW_API_KEY}"

# Response:
# {
#   "data": [
#     {"id": "default", "object": "model"},
#     {"id": "code-reviewer", "object": "model"},
#     {"id": "deployer", "object": "model"}
#   ]
# }

Each agent appears as a "model" in the OpenAI API format. Third-party tools that list available models will show your OpenClaw agents.

Common Pitfalls

  1. Forgetting to enable the API — The HTTP API may not be enabled by default. Check your gateway configuration for api.enabled: true.
  2. Not setting an API key — Without authentication, anyone on the network can send requests to your gateway. Always configure an API key.

Best Practices

  1. Use the API behind a reverse proxy — Put Nginx or Caddy in front for TLS, rate limiting, and access logging.
  2. Map agent names to meaningful model IDs — When third-party tools list your "models," descriptive names like "code-reviewer" are clearer than "agent-1".

Summary

  • OpenClaw exposes an OpenAI-compatible API at /v1/chat/completions
  • Any tool that supports OpenAI's API format can connect to OpenClaw agents
  • The /v1/models endpoint lists available agents as "models"
  • Streaming via SSE is supported for real-time response delivery
  • Always enable authentication and use a reverse proxy in production
✓ Completed