HTTP API

The OpenClaw Gateway (default port 18789) serves a small set of HTTP surfaces on the same port as the WebSocket server. These surfaces cover health checks, OpenAI-compatible inference, direct tool calls, webhook ingress, plugin-registered routes, the Control UI, and WebChat.

Bind address, TLS, and authentication for all HTTP surfaces are controlled by the gateway.* configuration keys. See Configuration for the full set of options.

Health and Readiness Probes

The Gateway provides built-in probe endpoints for container health checks, load balancers, and orchestration platforms:

  • GET /healthz — liveness
  • GET /readyz — readiness

Aliases are also supported:

  • GET /health
  • GET /ready

These endpoints return simple JSON ({"ok":true,"status":"..."} or readiness details). They are used by:

  • Dockerfile HEALTHCHECK
  • docker-compose.yml healthcheck
  • render.yaml healthCheckPath: /health
  • Fly.io and other managed-service probes

Probes do not require authentication under the default loopback bind. When the Gateway is exposed beyond loopback, protect the probes with gateway.auth or a reverse proxy.

OpenAI-Compatible Endpoints

When enabled, the Gateway serves a subset of the OpenAI API:

  • POST /v1/chat/completions
  • POST /v1/responses (OpenResponses)
  • GET /v1/models
  • POST /v1/embeddings

These endpoints accept standard OpenAI request bodies and return compatible streaming and non-streaming responses. Authentication uses the same Gateway auth configuration (token, password, or trusted-proxy).

Enablement is controlled by:

{
  "gateway": {
    "http": {
      "endpoints": {
        "chatCompletions": { "enabled": true },
        "responses": { "enabled": true }
      }
    }
  }
}

Tool Invocation

POST /tools/invoke

This endpoint allows direct invocation of registered tools over HTTP. It requires appropriate scopes from the active Gateway auth configuration.

Webhook Ingress

When hooks.enabled is true, the Gateway hosts webhook endpoints under the configured base path (default /hooks).

Example path:

POST /hooks/gmail

Authentication is header-based only (Authorization: Bearer ... or x-openclaw-token). Query-string tokens are rejected. All hook payloads are treated as untrusted input.

Configuration lives under the top-level hooks key and includes mappings, token, default session key, allowed prefixes, and Gmail Pub/Sub support. See Configuration for the schema.

Plugin HTTP Routes

Plugins can register arbitrary HTTP and WebSocket routes via the plugin system. These routes are served under the Gateway HTTP server and are discovered from the active plugin registry.

Routes are pinned at Gateway startup and re-pinned on config or plugin reload without a full restart.

Some bundled channel plugins expose gateway-auth bypass paths for callbacks. Canvas and A2UI plugin surfaces are served under:

  • /__openclaw__/canvas/
  • /__openclaw__/a2ui/

Control UI and WebChat

The Control UI is served at the Gateway root (for example http://127.0.0.1:18789). It provides a browser interface for config editing, logs, sessions, tools, and plugin surfaces. Behavior is controlled by gateway.controlUi.enabled and gateway.controlUi.basePath.

WebChat is a static chat UI served alongside the Control UI. It uses the Gateway WebSocket API for history and message sending.

Both surfaces are disabled or protected when the Gateway is bound to a non-loopback address unless explicit allowedOrigins or auth is configured.

Additional Notes

  • Default listen address is loopback (127.0.0.1:18789). Change exposure with gateway.bind, gateway.customBindHost, or Tailscale modes. See Configuration.
  • All HTTP surfaces respect the active gateway.auth mode (token/password/trusted-proxy/none) and rate limiting.
  • The primary control plane for CLI, nodes, and operator clients is the WebSocket RPC protocol. See Gateway protocol.
Updated June 17, 2026