OpenClaw API Guide: Gateway Endpoints, Auth, and Integration

The OpenClaw Gateway is a long-running daemon that serves both HTTP and WebSocket traffic on a single configurable port. The HTTP layer provides an OpenResponses-compatible REST interface for sending prompts, listing models, generating embeddings, and running chat completions. The WebSocket layer adds a protocol for session control, scheduled automation, event hooks, and skill management.

Five HTTP endpoints form the core REST surface:

The chat completions endpoint follows the widely adopted OpenAI-compatible format, so existing tooling can connect without major changes. The responses endpoint uses the OpenResponses format, which adds support for structured inputs beyond plain text.

Some endpoints require explicit activation in the Gateway configuration before they accept traffic. Once enabled, all endpoints share the same port, so there is no additional service to deploy. Check the official Gateway documentation for endpoint-specific setup steps.

The WebSocket protocol covers everything the REST endpoints do not. Clients connect and exchange JSON frames: requests use {type: "req", id, method, params}, responses return as {type: "res", id, ok, payload}, and server-push events arrive as {type: "event", event, payload}. The first frame on any connection must be a connect message carrying device identity.

Through this protocol you can list and manage sessions (sessions.list, sessions.create, sessions.send), schedule recurring agent runs (cron.add, cron.list, cron.run), manage skills (skills.status, skills.install), query tool catalogs (tools.catalog, tools.invoke), and inspect diagnostics and usage. The full method catalog spans dozens of operations across status, sessions, messages, cron, hooks, and skills categories. Most HTTP-only integrations need just the five REST endpoints.

Agent selection works through the model field in your request body. Set it to "openclaw" or "openclaw/default" for the default agent, or "openclaw/<agentId>" to route to a specific one. The x-openclaw-agent-id header provides an alternative routing path.

POST /v1/responses is the primary HTTP endpoint for running OpenClaw agents. A minimal request needs two fields: model for agent routing and input for the prompt.

curl -sS http://127.0.0.1:18789/v1/responses \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"model": "openclaw", "input": "Summarize the last three log entries"}'

The input field accepts a plain string or an array of structured items. When you pass an array, each item carries a type field that tells the Gateway how to process it.

Message items use roles to shape the conversation. system and developer roles append text to the system prompt. user and assistant roles build conversation history, with the most recent user message becoming the current turn.

Image items (input_image) accept base64-encoded data or a URL. Supported formats include JPEG, PNG, GIF, WebP, HEIC, and HEIF, with a 10MB size limit. HEIC and HEIF images are converted to JPEG before reaching the model provider.

File items (input_file) handle text, markdown, HTML, CSV, JSON, and PDF content up to 5MB. The Gateway decodes file content and adds it to the system prompt as untrusted external content wrapped in boundary markers. For PDFs, text extraction runs first. If the extracted text is under 200 characters, the Gateway rasterizes the first pages to images instead.

Function call output items (function_call_output) let you implement client-side tool loops. When the agent calls a function you defined, the response includes a function_call output item with a call_id. Send a follow-up request with the matching call_id and the tool's result to continue the conversation.

Beyond model and input, several optional fields shape request behavior:

• instructions adds text to the system prompt alongside any system-role messages
• tools defines client-side function tools with name, description, and JSON Schema parameters
• tool_choice filters which tools the agent can call
• stream enables SSE output (covered in the streaming section below)
• temperature and top_p adjust sampling parameters
• max_output_tokens sets a best-effort length cap on the response
• user enables session persistence across requests
• previous_response_id continues from a specific earlier response in the same session

The Gateway also supports custom headers for fine-grained control. x-openclaw-model overrides which backend model the agent uses for a single request. x-openclaw-session-key sets the session key explicitly. x-openclaw-message-channel provides a synthetic ingress context for requests that do not originate from a standard messaging surface.

The Gateway supports three authentication strategies. Your choice depends on the deployment model and how much you trust the network path between client and Gateway.

Shared-Secret Auth Configure the Gateway for token or password authentication and pass the secret in the Authorization: Bearer header:

curl http://127.0.0.1:18789/v1/models \
  -H 'Authorization: Bearer my-gateway-token'

This grants full operator access with six default scopes: operator.admin, operator.approvals, operator.pairing, operator.read, operator.talk.secrets, and operator.write. The Gateway ignores the x-openclaw-scopes header in this mode, so every request gets identical permissions. This is the simplest option for single-user setups and local development.

Trusted Identity-Bearing HTTP

This mode works behind reverse proxies like Tailscale Serve that inject verified identity headers into requests. The Gateway reads caller identity from those proxy headers and applies permissions accordingly. When the caller includes an x-openclaw-scopes header, the Gateway honors it to narrow permissions below the default set.

One detail to watch: loopback connections (127.0.0.1) need explicit opt-in in the Gateway configuration. Without enabling loopback trust, local clients behind a trusted proxy will be rejected even though they are on the same machine.

Private-Ingress Open Auth

When open authentication is enabled, no header is required, and any client that can reach the Gateway gets access. The Gateway still honors x-openclaw-scopes if provided, but there is no identity verification. Only use this where network-level controls already restrict who can connect.

### SSH tunnel for remote access without exposing the port publicly
ssh -N -L 18789:127.0.0.1:18789 your-server

Narrowing Permissions per Request In the trusted proxy and open auth modes, the x-openclaw-scopes header lets callers restrict permissions for individual requests. A frontend application could send x-openclaw-scopes: operator.read to limit a request to read-only operations, even when the caller would normally have broader access. In shared-secret mode this header has no effect.

Persist OpenClaw agent output across sessions and restarts

Free 50GB workspace with Intelligence Mode auto-indexing for semantic search. No credit card needed. Connect through the Fastio MCP server for agent reads, writes, and team handoff.

Start 14-Day Trial

Set stream: true in your request body to receive server-sent events instead of a single JSON response. The Gateway sets the Content-Type to text/event-stream and emits structured events as the agent works.

curl -N http://127.0.0.1:18789/v1/responses \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"model": "openclaw", "stream": true, "input": "Explain cron job syntax"}'

Each SSE message follows the format event: <type> plus data: <json>. The stream terminates with data: [DONE]. Events arrive in a predictable lifecycle order:

1. response.created confirms the response object exists
2. response.in_progress signals the agent is running
3. response.output_item.added fires when a new output item starts
4. response.content_part.added marks the start of a content chunk
5. response.output_text.delta delivers incremental text tokens (this is the event to parse for real-time display)
6. response.output_text.done signals a text segment is complete
7. response.content_part.done and response.output_item.done close their respective containers
8. response.completed ends a successful run

If the agent hits an error mid-stream, you receive response.failed instead of response.completed. Your client should handle both terminal events and clean up accordingly.

Non-Streaming Error Responses

When streaming is off, errors return standard HTTP status codes with a JSON body:

{
  "error": {
    "message": "Missing or invalid authentication",
    "type": "invalid_request_error"
  }
}

Status 400 means a malformed request body. Status 401 means missing or invalid credentials. Status 405 means you sent the wrong HTTP method. Use the error.type field for programmatic handling rather than parsing the message string, which may change between Gateway versions.

URL Fetching Security

When you include URL-based images or files in your input, the Gateway fetches them server-side. DNS resolution validation and private IP blocking prevent SSRF attacks by default. Redirects are capped at 3 hops with a 10-second timeout per fetch. The Gateway configuration supports URL allowlists and the option to disable URL fetching entirely for tighter control.

Session Routing

By default, each POST /v1/responses call is stateless. The Gateway generates a fresh session key, runs the agent, and discards context after responding. To maintain conversation state across requests, include a user field with a stable identifier string. The Gateway derives a deterministic session key from this value, so all requests sharing the same user string route to one conversation thread.

For explicit control, the x-openclaw-session-key header sets the session key directly. And previous_response_id continues from a specific earlier response, which is useful when you need to branch or replay conversations.

Scheduling Tasks with Cron The Gateway includes a built-in cron system for recurring agent tasks. Job definitions persist across Gateway restarts. Through the WebSocket protocol, cron.add creates a new scheduled job, cron.update modifies its schedule or parameters, cron.remove deletes it, and cron.run triggers an immediate execution outside the normal schedule.

Each cron job runs in its own isolated session, keeping scheduled work separate from interactive conversations. Inspect run history through cron.runs to confirm your automation is executing on time and producing the expected output.

Event Hooks

Hooks fire when specific events happen inside the Gateway: a message arrives, a session compacts, the Gateway restarts, or a command executes. Each hook lives in its own directory with a HOOK.md metadata file and a handler.ts implementation. Five hooks ship pre-installed, including session-memory (saves the last 15 messages to workspace memory) and boot-md (runs startup instructions on launch).

The Gateway loads hooks from four locations in precedence order: bundled, plugin, managed, and workspace-local. Check the official Gateway documentation for hook directory paths and management commands.

Where to Put Agent Output

The Gateway handles conversation state and task execution, but it does not provide long-term file storage or team-level access controls for sharing output. If your agents produce reports, extracted data, or processed files, that output needs somewhere durable to land.

For single-machine setups, writing to the local filesystem works fine. S3 or GCS handles bulk storage if you already run cloud infrastructure. For workflows where agents build something that a human needs to review or download, Fastio provides shared workspaces with a free tier: 50GB of storage, included credits per month, and no credit card required. Agents connect through the Fastio MCP server or REST API. Intelligence Mode auto-indexes uploaded files for semantic search, so other agents or team members can query stored documents without managing a separate vector database.

For OpenClaw deployments running cron-scheduled tasks, persistent storage outside the Gateway means output survives restarts and session cleanup. Setup details for connecting OpenClaw workspaces to Fastio are at /storage-for-openclaw/.