The OpenClaw API

The OpenClaw API most people mean is the Gateway’s OpenAI-compatible chat completions surface: disabled by default, served on the same port as the Gateway once enabled, and run through the same agent path as a chat message, so routing, permissions and config are the Gateway’s own. Here is what it serves, the trick in the model field, the security boundary the docs put in bold, how sessions are derived, and the cases where the docs point you elsewhere.

Enabling it and what it serves

• One flag under the Gateway’s HTTP endpoints turns it on; the responses endpoint is enabled separately.
• Four paths: chat completions, the models list, one model by id, and embeddings, multiplexed with the WebSocket on the Gateway port.
• The model field is an agent target, not a provider model: openclaw for the default agent, openclaw slash default as a stable alias, openclaw slash an agent id for a specific one. Headers can override the backend model, the agent, the session key and the ingress channel; the models list returns agent targets, never provider models or sub-agents.

Treat this endpoint as full operator access to the gateway instance

The security boundary

A valid Gateway token or password on this endpoint is equivalent to an owner credential, not a narrow per-user scope, and requests go through the same control-plane path as trusted operator actions, so an agent whose policy allows sensitive tools can use them from here. The docs’ instruction is to keep it on loopback, a tailnet or private ingress and never on the public internet. Auth follows the Gateway: a bearer token or password, a trusted identity-aware proxy that injects identity headers, or no header at all on private ingress; with a rate limit configured, too many failed attempts return a 429 with a retry-after header.

Sessions

• By default the endpoint is stateless per request: a new session key is generated on every call.
• An OpenAI user string derives a stable session key, so repeated calls with the same value share an agent session; reuse it per conversation thread and avoid account-level identifiers unless several devices should share one session.
• The explicit session-key header is for routing control across clients, with reserved internal namespaces rejected, and continuing an incognito conversation through it requires operator admin authority.

OpenClaw Gateway security controls places the endpoint among the other Gateway controls, and OpenClaw and Tailscale is the private ingress the docs have in mind.

When to use it

The docs prefer it over a new built-in channel when the integration is just another operator or client surface for the same Gateway. For native mobile clients they prefer WebChat or the Gateway protocol with the paired-device token flow, so the device never holds a shared secret, and for an external messaging network with its own users and rooms they say to build a channel plugin. OpenClaw plugins is where that path starts.

On Diali

On Diali the boundary the docs describe is enforced for you: the Gateway is not on the public internet, and what reaches it does so through the dashboard’s authenticated session. Hosted OpenClaw on Diali is the assistant and Security on Diali describes the boundary.

• Off by default; four paths on the Gateway port.
• The model field picks an agent; a bearer token is owner access.
• Stateless unless you send a user string.