See [Security](/gateway/security) and [Remote access](/gateway/remote).

## When to use this endpoint

Use `/v1/chat/completions` when you are integrating tooling or a trusted app-side backend with an existing gateway and can safely hold gateway operator credentials.

- Prefer this over adding a new built-in channel when your integration is just another operator/client surface for the same gateway.

- For native mobile clients that connect directly to a remote gateway, prefer [WebChat](/web/webchat) or the [Gateway Protocol](/gateway/protocol) and implement the paired-device bootstrap/device-token flow so the device does not need a shared HTTP token/password.

- Build a channel plugin instead when you are integrating an external messaging network with its own users, rooms, webhook delivery, or outbound transport. See [Building plugins](/plugins/building-plugins).

## Agent-first model contract

OpenClaw treats the OpenAI `model` field as an **agent target**, not a raw provider model id.

If the request includes an OpenAI `user` string, the Gateway derives a stable session key from it, so repeated calls can share an agent session.

For custom apps, the safest default is to reuse the same `user` value per conversation thread. Avoid account-level identifiers unless you explicitly want multiple conversations or devices to share one OpenClaw session. Use `x-openclaw-session-key` when you need explicit routing control across multiple clients or threads.

## Why this surface matters

This is the highest-leverage compatibility set for self-hosted frontends and tooling:

## Examples

Stable session for one app conversation:

```bash

curl -sS http://127.0.0.1:18789/v1/chat/completions \

-H 'Authorization: Bearer YOUR_TOKEN' \

-H 'Content-Type: application/json' \

-d '{

"model": "openclaw/default",

"user": "conv:YOUR_CONVERSATION_ID",

"messages": [{"role":"user","content":"Summarize my tasks for today"}]

}'

```

Reuse the same `user` value on later calls for that conversation to continue the same agent session.

Non-streaming:

```bash