diff --git a/docs/providers/openai.md b/docs/providers/openai.md
index 74b14c1ab28..a1bd2950dbf 100644
--- a/docs/providers/openai.md
+++ b/docs/providers/openai.md
@@ -9,577 +9,465 @@ title: "OpenAI"
# OpenAI
-OpenAI provides developer APIs for GPT models. Codex supports **ChatGPT sign-in** for subscription
-access or **API key** sign-in for usage-based access. Codex cloud requires ChatGPT sign-in.
-OpenAI explicitly supports subscription OAuth usage in external tools/workflows like OpenClaw.
+OpenAI provides developer APIs for GPT models. OpenClaw supports two auth routes:
-## Default interaction style
+- **API key** — direct OpenAI Platform access with usage-based billing (`openai/*` models)
+- **Codex subscription** — ChatGPT/Codex sign-in with subscription access (`openai-codex/*` models)
-OpenClaw can add a small OpenAI-specific prompt overlay for both `openai/*` and
-`openai-codex/*` runs. By default, the overlay keeps the assistant warm,
-collaborative, concise, direct, and a little more emotionally expressive
-without replacing the base OpenClaw system prompt. The friendly overlay also
-permits the occasional emoji when it fits naturally, while keeping overall
-output concise.
+OpenAI explicitly supports subscription OAuth usage in external tools and workflows like OpenClaw.
-Config key:
+## Getting started
-`plugins.entries.openai.config.personality`
+Choose your preferred auth method and follow the setup steps.
-Allowed values:
+
+
+ **Best for:** direct API access and usage-based billing.
-- `"friendly"`: default; enable the OpenAI-specific overlay.
-- `"on"`: alias for `"friendly"`.
-- `"off"`: disable the overlay and use the base OpenClaw prompt only.
+
+
+ Create or copy an API key from the [OpenAI Platform dashboard](https://platform.openai.com/api-keys).
+
+
+ ```bash
+ openclaw onboard --auth-choice openai-api-key
+ ```
-Scope:
+ Or pass the key directly:
-- Applies to `openai/*` models.
-- Applies to `openai-codex/*` models.
-- Does not affect other providers.
+ ```bash
+ openclaw onboard --openai-api-key "$OPENAI_API_KEY"
+ ```
+
+
+ ```bash
+ openclaw models list --provider openai
+ ```
+
+
-This behavior is on by default. Keep `"friendly"` explicitly if you want that
-to survive future local config churn:
+ ### Route summary
-```json5
-{
- plugins: {
- entries: {
- openai: {
- config: {
- personality: "friendly",
+ | Model ref | Route | Auth |
+ |-----------|-------|------|
+ | `openai/gpt-5.4` | Direct OpenAI Platform API | `OPENAI_API_KEY` |
+ | `openai/gpt-5.4-pro` | Direct OpenAI Platform API | `OPENAI_API_KEY` |
+
+
+ ChatGPT/Codex sign-in is routed through `openai-codex/*`, not `openai/*`.
+
+
+ ### Config example
+
+ ```json5
+ {
+ env: { OPENAI_API_KEY: "sk-..." },
+ agents: { defaults: { model: { primary: "openai/gpt-5.4" } } },
+ }
+ ```
+
+
+ OpenClaw does **not** expose `openai/gpt-5.3-codex-spark` on the direct API path. Live OpenAI API requests reject that model. Spark is Codex-only.
+
+
+
+
+
+ **Best for:** using your ChatGPT/Codex subscription instead of a separate API key. Codex cloud requires ChatGPT sign-in.
+
+
+
+ ```bash
+ openclaw onboard --auth-choice openai-codex
+ ```
+
+ Or run OAuth directly:
+
+ ```bash
+ openclaw models auth login --provider openai-codex
+ ```
+
+
+ ```bash
+ openclaw config set agents.defaults.model.primary openai-codex/gpt-5.4
+ ```
+
+
+ ```bash
+ openclaw models list --provider openai-codex
+ ```
+
+
+
+ ### Route summary
+
+ | Model ref | Route | Auth |
+ |-----------|-------|------|
+ | `openai-codex/gpt-5.4` | ChatGPT/Codex OAuth | Codex sign-in |
+ | `openai-codex/gpt-5.3-codex-spark` | ChatGPT/Codex OAuth | Codex sign-in (entitlement-dependent) |
+
+
+ This route is intentionally separate from `openai/gpt-5.4`. Use `openai/*` with an API key for direct Platform access, and `openai-codex/*` for Codex subscription access.
+
+
+ ### Config example
+
+ ```json5
+ {
+ agents: { defaults: { model: { primary: "openai-codex/gpt-5.4" } } },
+ }
+ ```
+
+
+ If onboarding reuses an existing Codex CLI login, those credentials stay managed by Codex CLI. On expiry, OpenClaw re-reads the external Codex source first and writes the refreshed credential back to Codex storage.
+
+
+ ### Context window cap
+
+ OpenClaw treats model metadata and the runtime context cap as separate values.
+
+ For `openai-codex/gpt-5.4`:
+
+ - Native `contextWindow`: `1050000`
+ - Default runtime `contextTokens` cap: `272000`
+
+ The smaller default cap has better latency and quality characteristics in practice. Override it with `contextTokens`:
+
+ ```json5
+ {
+ models: {
+ providers: {
+ "openai-codex": {
+ models: [{ id: "gpt-5.4", contextTokens: 160000 }],
+ },
},
},
- },
- },
-}
-```
+ }
+ ```
-### Disable the OpenAI prompt overlay
+
+ Use `contextWindow` to declare native model metadata. Use `contextTokens` to limit the runtime context budget.
+
-If you want the unmodified base OpenClaw prompt, set the overlay to `"off"`:
-
-```json5
-{
- plugins: {
- entries: {
- openai: {
- config: {
- personality: "off",
- },
- },
- },
- },
-}
-```
-
-You can also set it directly with the config CLI:
-
-```bash
-openclaw config set plugins.entries.openai.config.personality off
-```
-
-OpenClaw normalizes this setting case-insensitively at runtime, so values like
-`"Off"` still disable the friendly overlay.
-
-## Option A: OpenAI API key (OpenAI Platform)
-
-**Best for:** direct API access and usage-based billing.
-Get your API key from the OpenAI dashboard.
-
-Route summary:
-
-- `openai/gpt-5.4` = direct OpenAI Platform API route
-- Requires `OPENAI_API_KEY` (or equivalent OpenAI provider config)
-- In OpenClaw, ChatGPT/Codex sign-in is routed through `openai-codex/*`, not `openai/*`
-
-### CLI setup
-
-```bash
-openclaw onboard --auth-choice openai-api-key
-# or non-interactive
-openclaw onboard --openai-api-key "$OPENAI_API_KEY"
-```
-
-### Config snippet
-
-```json5
-{
- env: { OPENAI_API_KEY: "sk-..." },
- agents: { defaults: { model: { primary: "openai/gpt-5.4" } } },
-}
-```
-
-OpenAI's current API model docs list `gpt-5.4` and `gpt-5.4-pro` for direct
-OpenAI API usage. OpenClaw forwards both through the `openai/*` Responses path.
-OpenClaw intentionally suppresses the stale `openai/gpt-5.3-codex-spark` row,
-because direct OpenAI API calls reject it in live traffic.
-
-OpenClaw does **not** expose `openai/gpt-5.3-codex-spark` on the direct OpenAI
-API path. `pi-ai` still ships a built-in row for that model, but live OpenAI API
-requests currently reject it. Spark is treated as Codex-only in OpenClaw.
+
+
## Image generation
-The bundled `openai` plugin also registers image generation through the shared
-`image_generate` tool.
+The bundled `openai` plugin registers image generation through the `image_generate` tool.
-- Default image model: `openai/gpt-image-1`
-- Generate: up to 4 images per request
-- Edit mode: enabled, up to 5 reference images
-- Supports `size`
-- Current OpenAI-specific caveat: OpenClaw does not forward `aspectRatio` or
- `resolution` overrides to the OpenAI Images API today
-
-To use OpenAI as the default image provider:
+| Capability | Value |
+| ------------------------- | ---------------------------------- |
+| Default model | `openai/gpt-image-1` |
+| Max images per request | 4 |
+| Edit mode | Enabled (up to 5 reference images) |
+| Size overrides | Supported |
+| Aspect ratio / resolution | Not forwarded to OpenAI Images API |
```json5
{
agents: {
defaults: {
- imageGenerationModel: {
- primary: "openai/gpt-image-1",
- },
+ imageGenerationModel: { primary: "openai/gpt-image-1" },
},
},
}
```
-See [Image Generation](/tools/image-generation) for the shared tool
-parameters, provider selection, and failover behavior.
+
+See [Image Generation](/tools/image-generation) for shared tool parameters, provider selection, and failover behavior.
+
## Video generation
-The bundled `openai` plugin also registers video generation through the shared
-`video_generate` tool.
+The bundled `openai` plugin registers video generation through the `video_generate` tool.
-- Default video model: `openai/sora-2`
-- Modes: text-to-video, image-to-video, and single-video reference/edit flows
-- Current limits: 1 image or 1 video reference input
-- Current OpenAI-specific caveat: OpenClaw currently only forwards `size`
- overrides for native OpenAI video generation. Unsupported optional overrides
- such as `aspectRatio`, `resolution`, `audio`, and `watermark` are ignored
- and reported back as a tool warning.
-
-To use OpenAI as the default video provider:
+| Capability | Value |
+| ---------------- | --------------------------------------------------------------------------------- |
+| Default model | `openai/sora-2` |
+| Modes | Text-to-video, image-to-video, single-video edit |
+| Reference inputs | 1 image or 1 video |
+| Size overrides | Supported |
+| Other overrides | `aspectRatio`, `resolution`, `audio`, `watermark` are ignored with a tool warning |
```json5
{
agents: {
defaults: {
- videoGenerationModel: {
- primary: "openai/sora-2",
- },
+ videoGenerationModel: { primary: "openai/sora-2" },
},
},
}
```
-See [Video Generation](/tools/video-generation) for the shared tool
-parameters, provider selection, and failover behavior.
+
+See [Video Generation](/tools/video-generation) for shared tool parameters, provider selection, and failover behavior.
+
-## Option B: OpenAI Code (Codex) subscription
+## Personality overlay
-**Best for:** using ChatGPT/Codex subscription access instead of an API key.
-Codex cloud requires ChatGPT sign-in, while the Codex CLI supports ChatGPT or API key sign-in.
+OpenClaw adds a small OpenAI-specific prompt overlay for `openai/*` and `openai-codex/*` runs. The overlay keeps the assistant warm, collaborative, concise, and a little more emotionally expressive without replacing the base system prompt.
-Route summary:
+| Value | Effect |
+| ---------------------- | ---------------------------------- |
+| `"friendly"` (default) | Enable the OpenAI-specific overlay |
+| `"on"` | Alias for `"friendly"` |
+| `"off"` | Use base OpenClaw prompt only |
-- `openai-codex/gpt-5.4` = ChatGPT/Codex OAuth route
-- Uses ChatGPT/Codex sign-in, not a direct OpenAI Platform API key
-- Provider-side limits for `openai-codex/*` can differ from the ChatGPT web/app experience
-
-### CLI setup (Codex OAuth)
-
-```bash
-# Run Codex OAuth in the wizard
-openclaw onboard --auth-choice openai-codex
-
-# Or run OAuth directly
-openclaw models auth login --provider openai-codex
-```
-
-### Config snippet (Codex subscription)
-
-```json5
-{
- agents: { defaults: { model: { primary: "openai-codex/gpt-5.4" } } },
-}
-```
-
-OpenAI's current Codex docs list `gpt-5.4` as the current Codex model. OpenClaw
-maps that to `openai-codex/gpt-5.4` for ChatGPT/Codex OAuth usage.
-
-This route is intentionally separate from `openai/gpt-5.4`. If you want the
-direct OpenAI Platform API path, use `openai/*` with an API key. If you want
-ChatGPT/Codex sign-in, use `openai-codex/*`.
-
-If onboarding reuses an existing Codex CLI login, those credentials stay
-managed by Codex CLI. On expiry, OpenClaw re-reads the external Codex source
-first and, when the provider can refresh it, writes the refreshed credential
-back to Codex storage instead of taking ownership in a separate OpenClaw-only
-copy.
-
-If your Codex account is entitled to Codex Spark, OpenClaw also supports:
-
-- `openai-codex/gpt-5.3-codex-spark`
-
-OpenClaw treats Codex Spark as Codex-only. It does not expose a direct
-`openai/gpt-5.3-codex-spark` API-key path.
-
-OpenClaw also preserves `openai-codex/gpt-5.3-codex-spark` when `pi-ai`
-discovers it. Treat it as entitlement-dependent and experimental: Codex Spark is
-separate from GPT-5.4 `/fast`, and availability depends on the signed-in Codex /
-ChatGPT account.
-
-### Codex context window cap
-
-OpenClaw treats the Codex model metadata and the runtime context cap as separate
-values.
-
-For `openai-codex/gpt-5.4`:
-
-- native `contextWindow`: `1050000`
-- default runtime `contextTokens` cap: `272000`
-
-That keeps model metadata truthful while preserving the smaller default runtime
-window that has better latency and quality characteristics in practice.
-
-If you want a different effective cap, set `models.providers..models[].contextTokens`:
-
-```json5
-{
- models: {
- providers: {
- "openai-codex": {
- models: [
- {
- id: "gpt-5.4",
- contextTokens: 160000,
- },
- ],
+
+
+ ```json5
+ {
+ plugins: {
+ entries: {
+ openai: { config: { personality: "friendly" } },
+ },
},
- },
- },
-}
-```
+ }
+ ```
+
+
+ ```bash
+ openclaw config set plugins.entries.openai.config.personality off
+ ```
+
+
-Use `contextWindow` only when you are declaring or overriding native model
-metadata. Use `contextTokens` when you want to limit the runtime context budget.
+
+Values are case-insensitive at runtime, so `"Off"` and `"off"` both disable the overlay.
+
-### Transport default
+## Advanced configuration
-OpenClaw uses `pi-ai` for model streaming. For both `openai/*` and
-`openai-codex/*`, default transport is `"auto"` (WebSocket-first, then SSE
-fallback).
+
+
+ OpenClaw uses WebSocket-first with SSE fallback (`"auto"`) for both `openai/*` and `openai-codex/*`.
-In `"auto"` mode, OpenClaw also retries one early, retryable WebSocket failure
-before it falls back to SSE. Forced `"websocket"` mode still surfaces transport
-errors directly instead of hiding them behind fallback.
+ In `"auto"` mode, OpenClaw:
+ - Retries one early WebSocket failure before falling back to SSE
+ - After a failure, marks WebSocket as degraded for ~60 seconds and uses SSE during cool-down
+ - Attaches stable session and turn identity headers for retries and reconnects
+ - Normalizes usage counters (`input_tokens` / `prompt_tokens`) across transport variants
-After a connect or early-turn WebSocket failure in `"auto"` mode, OpenClaw marks
-that session's WebSocket path as degraded for about 60 seconds and sends
-subsequent turns over SSE during the cool-down instead of thrashing between
-transports.
+ | Value | Behavior |
+ |-------|----------|
+ | `"auto"` (default) | WebSocket first, SSE fallback |
+ | `"sse"` | Force SSE only |
+ | `"websocket"` | Force WebSocket only |
-For native OpenAI-family endpoints (`openai/*`, `openai-codex/*`, and Azure
-OpenAI Responses), OpenClaw also attaches stable session and turn identity state
-to requests so retries, reconnects, and SSE fallback stay aligned to the same
-conversation identity. On native OpenAI-family routes this includes stable
-session/turn request identity headers plus matching transport metadata.
-
-OpenClaw also normalizes OpenAI usage counters across transport variants before
-they reach session/status surfaces. Native OpenAI/Codex Responses traffic may
-report usage as either `input_tokens` / `output_tokens` or
-`prompt_tokens` / `completion_tokens`; OpenClaw treats those as the same input
-and output counters for `/status`, `/usage`, and session logs. When native
-WebSocket traffic omits `total_tokens` (or reports `0`), OpenClaw falls back to
-the normalized input + output total so session/status displays stay populated.
-
-You can set `agents.defaults.models..params.transport`:
-
-- `"sse"`: force SSE
-- `"websocket"`: force WebSocket
-- `"auto"`: try WebSocket, then fall back to SSE
-
-For `openai/*` (Responses API), OpenClaw also enables WebSocket warm-up by
-default (`openaiWsWarmup: true`) when WebSocket transport is used.
-
-Related OpenAI docs:
-
-- [Realtime API with WebSocket](https://platform.openai.com/docs/guides/realtime-websocket)
-- [Streaming API responses (SSE)](https://platform.openai.com/docs/guides/streaming-responses)
-
-```json5
-{
- agents: {
- defaults: {
- model: { primary: "openai-codex/gpt-5.4" },
- models: {
- "openai-codex/gpt-5.4": {
- params: {
- transport: "auto",
+ ```json5
+ {
+ agents: {
+ defaults: {
+ models: {
+ "openai-codex/gpt-5.4": {
+ params: { transport: "auto" },
+ },
},
},
},
- },
- },
-}
-```
+ }
+ ```
-### OpenAI WebSocket warm-up
+ Related OpenAI docs:
+ - [Realtime API with WebSocket](https://platform.openai.com/docs/guides/realtime-websocket)
+ - [Streaming API responses (SSE)](https://platform.openai.com/docs/guides/streaming-responses)
-OpenAI docs describe warm-up as optional. OpenClaw enables it by default for
-`openai/*` to reduce first-turn latency when using WebSocket transport.
+
-### Disable warm-up
+
+ OpenClaw enables WebSocket warm-up by default for `openai/*` to reduce first-turn latency.
-```json5
-{
- agents: {
- defaults: {
- models: {
- "openai/gpt-5.4": {
- params: {
- openaiWsWarmup: false,
+ ```json5
+ // Disable warm-up
+ {
+ agents: {
+ defaults: {
+ models: {
+ "openai/gpt-5.4": {
+ params: { openaiWsWarmup: false },
+ },
},
},
},
- },
- },
-}
-```
+ }
+ ```
-### Enable warm-up explicitly
+
-```json5
-{
- agents: {
- defaults: {
- models: {
- "openai/gpt-5.4": {
- params: {
- openaiWsWarmup: true,
+
+ OpenClaw exposes a shared fast-mode toggle for both `openai/*` and `openai-codex/*`:
+
+ - **Chat/UI:** `/fast status|on|off`
+ - **Config:** `agents.defaults.models["/"].params.fastMode`
+
+ When enabled, OpenClaw maps fast mode to OpenAI priority processing (`service_tier = "priority"`). Existing `service_tier` values are preserved, and fast mode does not rewrite `reasoning` or `text.verbosity`.
+
+ ```json5
+ {
+ agents: {
+ defaults: {
+ models: {
+ "openai/gpt-5.4": { params: { fastMode: true } },
+ "openai-codex/gpt-5.4": { params: { fastMode: true } },
},
},
},
- },
- },
-}
-```
+ }
+ ```
-### OpenAI and Codex priority processing
+
+ Session overrides win over config. Clearing the session override in the Sessions UI returns the session to the configured default.
+
-OpenAI's API exposes priority processing via `service_tier=priority`. In
-OpenClaw, set `agents.defaults.models["/"].params.serviceTier`
-to pass that field through on native OpenAI/Codex Responses endpoints.
+
-```json5
-{
- agents: {
- defaults: {
- models: {
- "openai/gpt-5.4": {
- params: {
- serviceTier: "priority",
- },
- },
- "openai-codex/gpt-5.4": {
- params: {
- serviceTier: "priority",
+
+ OpenAI's API exposes priority processing via `service_tier`. Set it per model in OpenClaw:
+
+ ```json5
+ {
+ agents: {
+ defaults: {
+ models: {
+ "openai/gpt-5.4": { params: { serviceTier: "priority" } },
+ "openai-codex/gpt-5.4": { params: { serviceTier: "priority" } },
},
},
},
- },
- },
-}
-```
+ }
+ ```
-Supported values are `auto`, `default`, `flex`, and `priority`.
+ Supported values: `auto`, `default`, `flex`, `priority`.
-OpenClaw forwards `params.serviceTier` to both direct `openai/*` Responses
-requests and `openai-codex/*` Codex Responses requests when those models point
-at the native OpenAI/Codex endpoints.
+
+ `serviceTier` is only forwarded to native OpenAI endpoints (`api.openai.com`) and native Codex endpoints (`chatgpt.com/backend-api`). If you route either provider through a proxy, OpenClaw leaves `service_tier` untouched.
+
-Important behavior:
+
-- direct `openai/*` must target `api.openai.com`
-- `openai-codex/*` must target `chatgpt.com/backend-api`
-- if you route either provider through another base URL or proxy, OpenClaw leaves `service_tier` untouched
+
+ For direct OpenAI Responses models (`openai/*` on `api.openai.com`), OpenClaw auto-enables server-side compaction:
-### OpenAI fast mode
+ - Forces `store: true` (unless model compat sets `supportsStore: false`)
+ - Injects `context_management: [{ type: "compaction", compact_threshold: ... }]`
+ - Default `compact_threshold`: 70% of `contextWindow` (or `80000` when unavailable)
-OpenClaw exposes a shared fast-mode toggle for both `openai/*` and
-`openai-codex/*` sessions:
+
+
+ Useful for compatible endpoints like Azure OpenAI Responses:
-- Chat/UI: `/fast status|on|off`
-- Config: `agents.defaults.models["/"].params.fastMode`
-
-When fast mode is enabled, OpenClaw maps it to OpenAI priority processing:
-
-- direct `openai/*` Responses calls to `api.openai.com` send `service_tier = "priority"`
-- `openai-codex/*` Responses calls to `chatgpt.com/backend-api` also send `service_tier = "priority"`
-- existing payload `service_tier` values are preserved
-- fast mode does not rewrite `reasoning` or `text.verbosity`
-
-For GPT 5.4 specifically, the most common setup is:
-
-- send `/fast on` in a session using `openai/gpt-5.4` or `openai-codex/gpt-5.4`
-- or set `agents.defaults.models["openai/gpt-5.4"].params.fastMode = true`
-- if you also use Codex OAuth, set `agents.defaults.models["openai-codex/gpt-5.4"].params.fastMode = true` too
-
-Example:
-
-```json5
-{
- agents: {
- defaults: {
- models: {
- "openai/gpt-5.4": {
- params: {
- fastMode: true,
+ ```json5
+ {
+ agents: {
+ defaults: {
+ models: {
+ "azure-openai-responses/gpt-5.4": {
+ params: { responsesServerCompaction: true },
+ },
+ },
+ },
},
- },
- "openai-codex/gpt-5.4": {
- params: {
- fastMode: true,
+ }
+ ```
+
+
+ ```json5
+ {
+ agents: {
+ defaults: {
+ models: {
+ "openai/gpt-5.4": {
+ params: {
+ responsesServerCompaction: true,
+ responsesCompactThreshold: 120000,
+ },
+ },
+ },
+ },
},
+ }
+ ```
+
+
+ ```json5
+ {
+ agents: {
+ defaults: {
+ models: {
+ "openai/gpt-5.4": {
+ params: { responsesServerCompaction: false },
+ },
+ },
+ },
+ },
+ }
+ ```
+
+
+
+
+ `responsesServerCompaction` only controls `context_management` injection. Direct OpenAI Responses models still force `store: true` unless compat sets `supportsStore: false`.
+
+
+
+
+
+ For GPT-5-family runs on `openai/*` and `openai-codex/*`, OpenClaw can use a stricter embedded execution contract:
+
+ ```json5
+ {
+ agents: {
+ defaults: {
+ embeddedPi: { executionContract: "strict-agentic" },
},
},
- },
- },
-}
-```
+ }
+ ```
-Session overrides win over config. Clearing the session override in the Sessions UI
-returns the session to the configured default.
+ With `strict-agentic`, OpenClaw:
+ - No longer treats a plan-only turn as successful progress when a tool action is available
+ - Retries the turn with an act-now steer
+ - Auto-enables `update_plan` for substantial work
+ - Surfaces an explicit blocked state if the model keeps planning without acting
-### Native OpenAI versus OpenAI-compatible routes
+
+ Scoped to OpenAI and Codex GPT-5-family runs only. Other providers and older model families keep default behavior.
+
-OpenClaw treats direct OpenAI, Codex, and Azure OpenAI endpoints differently
-from generic OpenAI-compatible `/v1` proxies:
+
-- native `openai/*`, `openai-codex/*`, and Azure OpenAI routes keep
- `reasoning: { effort: "none" }` intact when you explicitly disable reasoning
-- native OpenAI-family routes default tool schemas to strict mode
-- hidden OpenClaw attribution headers (`originator`, `version`, and
- `User-Agent`) are only attached on verified native OpenAI hosts
- (`api.openai.com`) and native Codex hosts (`chatgpt.com/backend-api`)
-- native OpenAI/Codex routes keep OpenAI-only request shaping such as
- `service_tier`, Responses `store`, OpenAI reasoning-compat payloads, and
- prompt-cache hints
-- proxy-style OpenAI-compatible routes keep the looser compat behavior and do
- not force strict tool schemas, native-only request shaping, or hidden
- OpenAI/Codex attribution headers
+
+ OpenClaw treats direct OpenAI, Codex, and Azure OpenAI endpoints differently from generic OpenAI-compatible `/v1` proxies:
-Azure OpenAI stays in the native-routing bucket for transport and compat
-behavior, but it does not receive the hidden OpenAI/Codex attribution headers.
+ **Native routes** (`openai/*`, `openai-codex/*`, Azure OpenAI):
+ - Keep `reasoning: { effort: "none" }` intact when reasoning is explicitly disabled
+ - Default tool schemas to strict mode
+ - Attach hidden attribution headers on verified native hosts only
+ - Keep OpenAI-only request shaping (`service_tier`, `store`, reasoning-compat, prompt-cache hints)
-This preserves current native OpenAI Responses behavior without forcing older
-OpenAI-compatible shims onto third-party `/v1` backends.
+ **Proxy/compatible routes:**
+ - Use looser compat behavior
+ - Do not force strict tool schemas or native-only headers
-### Strict-agentic GPT mode
+ Azure OpenAI uses native transport and compat behavior but does not receive the hidden attribution headers.
-For `openai/*` and `openai-codex/*` GPT-5-family runs, OpenClaw can use a
-stricter embedded Pi execution contract:
+
+
-```json5
-{
- agents: {
- defaults: {
- embeddedPi: {
- executionContract: "strict-agentic",
- },
- },
- },
-}
-```
+## Related
-With `strict-agentic`, OpenClaw no longer treats a plan-only assistant turn as
-successful progress when a concrete tool action is available. It retries the
-turn with an act-now steer, auto-enables the structured `update_plan` tool for
-substantial work, and surfaces an explicit blocked state if the model keeps
-planning without acting.
-
-The mode is scoped to OpenAI and OpenAI Codex GPT-5-family runs. Other providers
-and older model families keep the default embedded Pi behavior unless you opt
-them into other runtime settings.
-
-### OpenAI Responses server-side compaction
-
-For direct OpenAI Responses models (`openai/*` using `api: "openai-responses"` with
-`baseUrl` on `api.openai.com`), OpenClaw now auto-enables OpenAI server-side
-compaction payload hints:
-
-- Forces `store: true` (unless model compat sets `supportsStore: false`)
-- Injects `context_management: [{ type: "compaction", compact_threshold: ... }]`
-
-By default, `compact_threshold` is `70%` of model `contextWindow` (or `80000`
-when unavailable).
-
-### Enable server-side compaction explicitly
-
-Use this when you want to force `context_management` injection on compatible
-Responses models (for example Azure OpenAI Responses):
-
-```json5
-{
- agents: {
- defaults: {
- models: {
- "azure-openai-responses/gpt-5.4": {
- params: {
- responsesServerCompaction: true,
- },
- },
- },
- },
- },
-}
-```
-
-### Enable with a custom threshold
-
-```json5
-{
- agents: {
- defaults: {
- models: {
- "openai/gpt-5.4": {
- params: {
- responsesServerCompaction: true,
- responsesCompactThreshold: 120000,
- },
- },
- },
- },
- },
-}
-```
-
-### Disable server-side compaction
-
-```json5
-{
- agents: {
- defaults: {
- models: {
- "openai/gpt-5.4": {
- params: {
- responsesServerCompaction: false,
- },
- },
- },
- },
- },
-}
-```
-
-`responsesServerCompaction` only controls `context_management` injection.
-Direct OpenAI Responses models still force `store: true` unless compat sets
-`supportsStore: false`.
-
-## Notes
-
-- Model refs always use `provider/model` (see [/concepts/models](/concepts/models)).
-- Auth details + reuse rules are in [/concepts/oauth](/concepts/oauth).
+
+
+ Choosing providers, model refs, and failover behavior.
+
+
+ Shared image tool parameters and provider selection.
+
+
+ Shared video tool parameters and provider selection.
+
+
+ Auth details and credential reuse rules.
+
+