How to Use the OpenClaw OpenAI-Compatible API

The OpenAI-compatible API is useful when you want OpenClaw to appear inside existing chat clients, RAG tools, or internal software that already speaks OpenAI Chat Completions. The important mental model is that you are not exposing a dumb model proxy. You are exposing an agent gateway. That means the same routing, permissions, tools, memory, and safety choices that apply to your OpenClaw agent can apply to API calls too.

30-second answer

Enable gateway.http.endpoints.chatCompletions.enabled, keep the endpoint on loopback or a private network, authenticate with your Gateway token or password, and point clients at the Gateway /v1 surface. The documented endpoints include POST /v1/chat/completions plus GET /v1/models, GET /v1/models/{id}, POST /v1/embeddings, and POST /v1/responses. Use openclaw/default as the model unless you intentionally target a specific configured agent.

When this pays off

This pays off for teams that already have Open WebUI, LibreChat, LobeChat, custom dashboards, or internal scripts, but want those surfaces to use a real OpenClaw operator instead of a plain provider API key. It is also a cleaner revenue-support pattern: one trusted agent can answer support, run approved tools, and keep continuity while customer-facing tooling still uses a familiar OpenAI client contract.

Operator runbook

1. Start with the Gateway auth decision, not the client UI. The official docs are clear that this surface is trusted operator access when protected by a shared Gateway bearer secret. Put it behind loopback, a tailnet, or trusted private ingress. Do not publish it directly to the internet just because a chat client accepts a base URL and API key.
2. Enable the endpoint in config with gateway.http.endpoints.chatCompletions.enabled set to true. This is intentionally opt-in. If the Gateway rejects the config, run openclaw doctor and fix schema issues before you debug client behavior. OpenClaw uses strict configuration validation, so typos are safer than silent partial configuration.
3. Use the agent-target model contract. Set the client model to openclaw/default for the default agent, or openclaw/ when you have a specific configured agent. If you need a different backend model for a request, use x-openclaw-model instead of pretending that the OpenAI model field is a raw provider selector.
4. Test the model list first. The docs show a simple smoke test against /v1/models with Authorization: Bearer YOUR_TOKEN. If openclaw/default appears, the client has the right base URL and auth path. If it does not, fix Gateway auth or endpoint enablement before changing agent prompts.
5. Only then test chat. A failed chat call can be an agent issue, model auth issue, or tool-policy issue, while a failed /v1/models call is usually base URL, endpoint, or bearer-token wiring. Separating those checks keeps you out of vague debugging loops.
6. Document the surface as operator-grade. Anyone with the bearer token can drive the selected agent through the Gateway. For a real trust boundary between products, customers, or departments, run separate Gateways rather than relying on model names as authorization.

Verification

A clean verification path is: openclaw gateway status, then curl /v1/models through the same URL the client will use, then one non-streaming chat request, then one streaming request if your client needs SSE. For production, also check logs and usage-cost summaries after real traffic so you can see provider, model, token, and cost behavior instead of discovering a runaway integration from the bill.

Common mistakes

The classic mistake is exposing this endpoint like a harmless model proxy. It is not. The docs explicitly call it a full operator-access surface. Another mistake is passing --url to CLI probes and expecting config credentials to be reused; Gateway query commands require explicit --token or --password with URL overrides. Treat every auth failure as a signal to simplify the path and prove one layer at a time.

Turn it into a repeatable operating system

The OpenClaw Playbook turns this from a one-off integration into an operating pattern: which agents deserve API exposure, how to split customer-facing and internal gateways, what to log, and how to keep tool access narrow enough that API compatibility does not become an expensive security accident.