docs: clarify OpenAI HTTP client guidance

Refs #52075.
Refs #54275.

Co-authored-by: Francisco <franciscopino1997@gmail.com>
Co-authored-by: 孔祥俊 <xiangjunkong90@gmail.com>

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

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