From 5bb94caef814f6e83ffe9d7f7495bd105d5b56ef Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Fri, 22 May 2026 18:00:53 +0100 Subject: [PATCH] docs: clarify OpenAI HTTP client guidance MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Refs #52075. Refs #54275. Co-authored-by: Francisco Co-authored-by: 孔祥俊 --- docs/gateway/openai-http-api.md | 25 +++++++++++++++++++++++++ docs/install/bun.md | 2 +- 2 files changed, 26 insertions(+), 1 deletion(-) diff --git a/docs/gateway/openai-http-api.md b/docs/gateway/openai-http-api.md index 0896498434c..7a0a5794f8b 100644 --- a/docs/gateway/openai-http-api.md +++ b/docs/gateway/openai-http-api.md @@ -78,6 +78,14 @@ Auth matrix: 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. @@ -136,6 +144,8 @@ By default the endpoint is **stateless per request** (a new session key is gener 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: @@ -284,6 +294,21 @@ If that returns `openclaw/default`, most Open WebUI setups can connect with the ## 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 diff --git a/docs/install/bun.md b/docs/install/bun.md index 3221e8fc09a..12af9804046 100644 --- a/docs/install/bun.md +++ b/docs/install/bun.md @@ -50,7 +50,7 @@ bun pm trust baileys protobufjs ## Caveats -Some scripts still hardcode pnpm (for example `docs:build`, `ui:*`, `protocol:check`). Run those via pnpm for now. +Some scripts still hardcode pnpm (for example `check:docs`, `ui:*`, `protocol:check`). Run those via pnpm for now. ## Related