jason.woltje
193479b52d
Mosaic concepts pages now own the adapted content; source/license metadata under docs/reference/concepts. Adds ACT-1 agent-context planning capture, pinned concept test package + preparation utility, foundation observation notes (durability, evidence, federation, onboarding, workflow), and the #1495 consolidation assessment. TOOLS.md updated for the host-dev launcher.
1758 lines
83 KiB
Markdown
1758 lines
83 KiB
Markdown
---
|
||
summary: "Use OpenAI via API keys or Codex subscription in OpenClaw"
|
||
read_when:
|
||
- You want to use OpenAI models in OpenClaw
|
||
- You want Codex subscription auth instead of API keys
|
||
- You want Astra async tools, mid-turn steering, or cached reasoning changes
|
||
- You need stricter GPT-5 agent execution behavior
|
||
title: "OpenAI"
|
||
---
|
||
|
||
OpenClaw uses one provider id, `openai`, for both direct API-key auth and
|
||
ChatGPT/Codex subscription auth. `openai/*` is the canonical model route.
|
||
For embedded agent turns with runtime policy unset or `auto`, OpenAI's route
|
||
facts decide whether OpenClaw may select the bundled Codex app-server runtime
|
||
implicitly. The `openai/*` prefix alone does not select a runtime.
|
||
|
||
- **Agent models** - `openai/*` through the runtime selected by explicit
|
||
`agentRuntime` config or OpenAI's implicit route policy. Sign in with Codex
|
||
auth for ChatGPT/Codex subscription use, or configure an API-key auth
|
||
profile when you want key-based billing.
|
||
- **Non-agent OpenAI APIs** - direct OpenAI Platform access, billed per use,
|
||
through `OPENAI_API_KEY` or an `openai` API-key auth profile.
|
||
- **Legacy config** - `codex/*` and `openai-codex/*` refs are repaired to
|
||
`openai/*` plus model-scoped `agentRuntime.id: "codex"` by
|
||
`openclaw doctor --fix`.
|
||
|
||
OpenAI explicitly supports subscription OAuth usage in external tools and
|
||
workflows like OpenClaw.
|
||
|
||
## Usage and cost tracking
|
||
|
||
OpenClaw keeps subscription quota and Platform API billing distinct:
|
||
|
||
- ChatGPT/Codex OAuth shows the subscription plan, quota windows, and credit balance.
|
||
- `OPENAI_ADMIN_KEY` shows 30 days of provider-reported organization cost and completions usage in Control UI **Usage**, including daily spend, request/token totals, top models, and cost categories.
|
||
- `OPENAI_PROJECT_ID` optionally scopes Admin API history to one project.
|
||
- OpenClaw never sends `OPENAI_API_KEY` or an `openai` inference profile to organization APIs; those credentials may belong to custom, Azure, or agent-local endpoints.
|
||
|
||
An explicit Admin key takes precedence over OAuth. Provider-reported history is not merged with OpenClaw's session-derived estimated cost; it can include API activity from other clients and provider-side billing adjustments.
|
||
|
||
OpenAI's [API Usage Dashboard](https://help.openai.com/en/articles/10478918) documentation describes the organization-owner and explicit Usage Dashboard permission requirements for usage data.
|
||
|
||
Provider, model, runtime, and channel are separate layers. If those labels are
|
||
getting mixed together, read [Agent runtimes](/concepts/agent-runtimes) before
|
||
changing config.
|
||
|
||
## Quick choice
|
||
|
||
| Goal | Use | Notes |
|
||
| ------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------- |
|
||
| ChatGPT/Codex subscription, native Codex runtime | `openai/gpt-5.6-sol` | Fresh subscription setup; sign in with Codex auth. |
|
||
| Direct API-key billing for agent turns | `openai/gpt-5.6-sol` plus an ordered API-key auth profile | Fresh API-key setup uses the explicit Sol id. |
|
||
| Choose an exact GPT-5.6 tier | `openai/gpt-5.6-sol`, `-terra`, or `-luna` | Check `models list` for the tiers available to this account. |
|
||
| Account without GPT-5.6 access | `openai/gpt-5.5` | Explicit recovery choice; OpenClaw does not silently downgrade. |
|
||
| Direct API-key billing, explicit OpenClaw runtime | `openai/gpt-5.6` plus provider/model `agentRuntime.id: "openclaw"` | Select a normal `openai` API-key profile. |
|
||
| Latest ChatGPT Instant model alias | `openai/chat-latest` | Direct API-key only; moving alias, not the stable default. |
|
||
| Image generation or editing | `openai/gpt-image-2` | Works with `OPENAI_API_KEY` or Codex OAuth. |
|
||
| Transparent-background images | `openai/gpt-image-1.5` | Set `outputFormat` to `png` or `webp` and `background=transparent`. |
|
||
|
||
### Retired subscription model references
|
||
|
||
GPT-5.4 and GPT-5.4 Mini are retired from the ChatGPT-account Codex route. Run `openclaw doctor --fix` to replace persisted subscription references with their documented successors: `openai/gpt-5.6-terra` and `openai/gpt-5.6-luna`, respectively. This includes defaults, per-agent model selections, automation overrides, and unlocked session overrides whose selected route is known. The Platform API-key route is unaffected. Doctor retains pinned overrides when their successor is outside the agent's model policy, or when clearing an override would keep the same retired model and account. It reports the model or policy change needed, along with unresolved or conflicting account routes. Review the repair output, restart the Gateway, and re-enable any automation that was disabled after repeated failures.
|
||
|
||
## GPT-6 Astra
|
||
|
||
Select `openai/gpt-6-astra` with an OpenAI API-key profile or a ChatGPT/Codex
|
||
subscription that has access to Astra. Access is rolling out; a successful
|
||
account catalog remains authoritative, so adding model support does not grant
|
||
access to an account that has not received it.
|
||
If ChatGPT/Codex catalog discovery is unavailable, the offline fallback list
|
||
omits Astra until account discovery succeeds.
|
||
|
||
```bash
|
||
openclaw models set openai/gpt-6-astra
|
||
```
|
||
|
||
Astra uses the Responses API for agent tool calls. It supports text and image
|
||
input, a 1,050,000-token context window, and up to 128,000 output tokens.
|
||
OpenClaw retains its ordinary 272,000-token active input budget by default.
|
||
The supported reasoning efforts are `low`, `medium`, `high`, `xhigh`, and `max`.
|
||
OpenClaw defaults Astra to `low` on both the OpenClaw and Codex runtimes to
|
||
limit reasoning cost and subscription-budget consumption on ordinary prompts.
|
||
The OpenAI provider owns this default, so model selection, Control UI, and
|
||
Codex turn requests share it. Explicit agent, model, global, and session
|
||
thinking settings still take precedence; switching models does not clear an
|
||
existing `high` override. Use `/think default` to clear a session override.
|
||
An existing `minimal` setting maps to `low`. Astra cannot disable reasoning;
|
||
`off` never sends the unsupported `none` effort.
|
||
Temperature and `top_p` are not sent.
|
||
These defaults also apply to configured Astra model entries without explicit
|
||
reasoning or temperature compatibility metadata.
|
||
Azure Responses deployments continue to use their configured capabilities.
|
||
|
||
`/think ultra` is also available on the OpenClaw and Codex runtimes. Ultra enables
|
||
proactive sub-agent orchestration; it is not a raw Responses API effort. OpenClaw
|
||
uses `max`, while native Codex selects Astra's model-defined effort (`xhigh`).
|
||
|
||
Standard pricing per million tokens is $10 input, $1 cache reads, $12.50 cache
|
||
writes, and $50 output. Requests above 272K input tokens have higher rates.
|
||
See the [Astra model reference](https://developers.openai.com/api/docs/models/gpt-6-astra)
|
||
and [migration guide](https://developers.openai.com/api/docs/guides/latest-model?model=gpt-6-astra).
|
||
|
||
### Async tools, steering, and reasoning changes
|
||
|
||
Use an OpenAI Platform API-key profile and the built-in OpenClaw runtime for
|
||
these Astra capabilities. They require the official `https://api.openai.com/v1`
|
||
Responses endpoint. Configure the existing model settings:
|
||
|
||
```json5
|
||
{
|
||
agents: {
|
||
defaults: {
|
||
models: {
|
||
"openai/gpt-6-astra": {
|
||
agentRuntime: { id: "openclaw" },
|
||
params: {
|
||
transport: "auto",
|
||
responsesServerCompaction: false,
|
||
},
|
||
},
|
||
},
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
- **Async function calls:** Astra can continue reasoning while OpenClaw runs a
|
||
direct function tool. OpenClaw sends the completed result in the next model
|
||
request after the active response finishes. This
|
||
applies to direct tools; code-mode tools retain their existing execution flow.
|
||
- **Mid-turn steering:** [Steering messages](/concepts/queue#queue-modes) can
|
||
reach Astra while it is reasoning, using the active session's cached
|
||
WebSocket. Use `auto` or `websocket-cached`; SSE keeps ordinary queued
|
||
steering at the next available runtime boundary. Each live batch owns one
|
||
response; later messages can steer its successor. Context or payload hooks
|
||
that rewrite the active request's prefix keep ordinary queued delivery.
|
||
- **Reasoning changes without rebuilding the cached prefix:** Change the
|
||
[thinking level](/tools/thinking), for example with `/think high`, before
|
||
the next user turn. OpenClaw preserves the original request-level effort
|
||
and places a `configuration_update` at the new turn. This optimization
|
||
works across matching session history over SSE or cached WebSockets.
|
||
Automatic steering continuations keep their inherited settings. If steering
|
||
waits for a tool result or approval, the explicit continuation uses current
|
||
request settings, including output limits and reasoning settings, without
|
||
repeating accepted steering. Earlier `configuration_update` items retain
|
||
their effect; a changed request-level effort does not replace those controls.
|
||
When accepted steering waits for a tool result or approval and its history
|
||
contains effort controls, finish that input with a compatible Astra model
|
||
and mode before switching.
|
||
|
||
The example disables automatic server compaction because OpenAI cannot combine
|
||
it with configuration updates. Cache-preserving effort changes also exclude
|
||
automatic truncation, pro mode, and API multi-agent mode. The cache state is
|
||
local to the running process or connection; expiry, restart, or rewritten
|
||
history starts a fresh request using the selected effort.
|
||
|
||
The native [Codex harness](/plugins/codex-harness) owns its own Responses loop;
|
||
these built-in-runtime capabilities do not imply native Codex support.
|
||
|
||
## Naming map
|
||
|
||
| Name you see | Layer | Meaning |
|
||
| --------------------------------------- | ----------------- | ---------------------------------------------------------------------------------------- |
|
||
| `openai` | Provider prefix | Canonical OpenAI model route; route facts determine the implicit runtime. |
|
||
| `codex` plugin | Plugin | Bundled plugin providing the native Codex app-server runtime and `/codex` chat controls. |
|
||
| provider/model `agentRuntime.id: codex` | Agent runtime | Force the native Codex app-server harness for matching embedded turns. |
|
||
| `/codex ...` | Chat command set | Bind/control Codex app-server threads from a conversation. |
|
||
| `runtime: "acp", agentId: "codex"` | ACP session route | Explicit fallback path that runs Codex through ACP/acpx. |
|
||
|
||
## Implicit agent runtime
|
||
|
||
When provider/model `agentRuntime` policy is unset or `auto`, OpenAI's
|
||
provider-owned route policy chooses the implicit runtime from the effective
|
||
endpoint and adapter:
|
||
|
||
| Effective route facts | Implicit runtime |
|
||
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
|
||
| Exact official Platform HTTPS endpoint with `openai-responses`, or exact official ChatGPT HTTPS endpoint with `openai-chatgpt-responses`; no authored provider request override | Codex may be selected |
|
||
| Authored `openai-completions` adapter | OpenClaw |
|
||
| Custom endpoint | OpenClaw |
|
||
| Explicit exact official endpoint using HTTP | Rejected |
|
||
| Route with an authored provider/model request override | OpenClaw |
|
||
|
||
Valid model-scoped `params.fastMode` / `params.fast_mode`, cutoff, and `thinking`
|
||
values are typed agent-runtime controls, not authored provider request params.
|
||
Affirmative reasoning support and native reasoning-effort metadata also preserve
|
||
Codex selection. See [Runtime selection](/concepts/agent-runtimes#runtime-selection)
|
||
for the supported capability values and the request overrides that remain protected.
|
||
|
||
An explicit `agentRuntime.id: "openclaw"` keeps a Codex-eligible route on
|
||
OpenClaw. Explicit `agentRuntime.id: "codex"` requires a registered Codex harness;
|
||
unsupported routes/auth fail closed, except that authored request overrides may
|
||
use Codex's declared exact-request OpenClaw fallback before execution. Inspect
|
||
the completed result's actual harness when a recipe depends on native execution.
|
||
Runtime selection does not change credential type or billing: Platform API-key
|
||
auth and ChatGPT/Codex subscription auth remain distinct.
|
||
|
||
`openclaw doctor --fix` migrates legacy `codex/*` and `openai-codex/*` model
|
||
refs, legacy Codex auth profile ids, and legacy Codex auth-order entries to the
|
||
canonical `openai` route. Migrated model refs receive model-scoped
|
||
`agentRuntime.id: "codex"`; use `auth.order.openai` for new auth-order config.
|
||
|
||
<Note>
|
||
Fresh OpenAI setup applies a GPT-5.6 primary only when no primary model is
|
||
configured. Adding or refreshing OpenAI auth preserves an existing explicit
|
||
selection, including `openai/gpt-5.5`, unless you explicitly use
|
||
`models auth login --set-default` or `models set`. Use an API-key auth profile
|
||
only when you want API-key auth for an agent model.
|
||
</Note>
|
||
|
||
## GPT-5.6 limited preview
|
||
|
||
OpenClaw recognizes the exact `openai/gpt-5.6-sol`,
|
||
`openai/gpt-5.6-terra`, and `openai/gpt-5.6-luna` model ids. All three expose
|
||
`xhigh` and `max` reasoning in the current catalog. OpenAI describes Sol as
|
||
the flagship tier, Terra as the balanced tier, and Luna as the fast,
|
||
lower-cost tier. See the
|
||
[GPT-5.6 launch announcement](https://openai.com/index/previewing-gpt-5-6-sol/)
|
||
and [access guide](https://help.openai.com/en/articles/20001325-a-preview-of-gpt-5-6-sol-terra-and-luna).
|
||
|
||
OpenAI's [GPT-5.6 Sol model page](https://developers.openai.com/api/docs/models/gpt-5.6-sol)
|
||
documents the bare `openai/gpt-5.6` id as a supported alias for Sol. Fresh
|
||
API-key and ChatGPT/Codex OAuth setup use the canonical `openai/gpt-5.6-sol`
|
||
ref so model pickers do not show both names for the same tier. Run
|
||
`openclaw doctor --fix` to rewrite persisted bare OpenAI refs to that canonical
|
||
identity. The native Codex catalog can show the exact Sol, Terra, and Luna ids depending on
|
||
workspace access. Check the current account with:
|
||
|
||
```bash
|
||
openclaw models list --provider openai
|
||
```
|
||
|
||
API organization and Codex workspace access can differ. If GPT-5.6 is not
|
||
available, select GPT-5.5 explicitly:
|
||
|
||
```bash
|
||
openclaw models set openai/gpt-5.5
|
||
```
|
||
|
||
OpenClaw surfaces the upstream access error and does not silently replace a
|
||
GPT-5.6 selection with GPT-5.5.
|
||
|
||
<Note>
|
||
Eligible exact official HTTPS routes may select the bundled Codex app-server
|
||
plugin when runtime policy is unset or `auto`; authored Completions routes,
|
||
custom endpoints, and request-transport overrides remain on OpenClaw. Plaintext
|
||
official HTTP endpoints are rejected. Explicit provider/model runtime config remains
|
||
authoritative. Run `openclaw doctor --fix` to repair stale legacy Codex model
|
||
refs, `codex-cli/*` refs, or old runtime session pins that were not set by
|
||
explicit runtime config.
|
||
</Note>
|
||
|
||
## OpenClaw feature coverage
|
||
|
||
| OpenAI capability | OpenClaw surface | Status |
|
||
| ------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
|
||
| Chat / Responses | `openai/<model>` model provider | Yes |
|
||
| Codex subscription models | `openai/<model>` with OpenAI OAuth | Yes |
|
||
| Legacy Codex model refs | old Codex model refs, `codex-cli/<model>` | Repaired by doctor to `openai/<model>` |
|
||
| Codex app-server harness | Codex-compatible HTTPS route with runtime unset/`auto`, or explicit `agentRuntime.id: codex` | Yes |
|
||
| Server-side web search | Native OpenAI Responses tool | Yes, when web search is enabled and no other provider is pinned |
|
||
| Images | `image_generate` | Yes |
|
||
| Videos | `video_generate` | Yes |
|
||
| Text-to-speech | `tts.provider: "openai"` / `tts` | Yes |
|
||
| Batch speech-to-text | `tools.media.audio` / media understanding | Yes |
|
||
| Streaming speech-to-text | Voice Call `streaming.provider: "openai"` | Yes |
|
||
| Realtime voice | Voice Call `realtime.provider: "openai"` / Control UI Talk `talk.realtime.provider: "openai"` | Yes (auth order depends on the selected Realtime route; see below) |
|
||
| Embeddings | memory embedding provider | Yes |
|
||
|
||
<Note>
|
||
Released GPT-Live browser and Gateway-relay WebRTC try an OpenClaw ChatGPT OAuth
|
||
profile first and fall back to Platform API-key auth. Ordinary GA browser
|
||
Realtime tries Platform auth first and falls back to OAuth only when no Platform
|
||
credential source is configured. Direct backend sockets and unlisted or private
|
||
realtime routes require Platform API-key auth.
|
||
|
||
Platform auth is resolved in this order: configured realtime API key, `openai`
|
||
API-key profile, then `OPENAI_API_KEY`. Voice Call, Discord realtime voice,
|
||
direct backend sockets, unlisted or private realtime routes, and realtime
|
||
transcription still require Platform auth.
|
||
|
||
If API-key auth reports missing billing, top up Platform credits at
|
||
[platform.openai.com/account/billing](https://platform.openai.com/account/billing)
|
||
for the organization backing your realtime credentials when using API-key
|
||
auth. Realtime voice accepts the `openai` API-key auth profile created by
|
||
`openclaw onboard --auth-choice openai-api-key`, a Platform API key set via
|
||
`talk.realtime.providers.openai.apiKey` for Control UI Talk, or
|
||
`plugins.entries.voice-call.config.realtime.providers.openai.apiKey` for Voice
|
||
Call, or the `OPENAI_API_KEY` environment variable.
|
||
|
||
In Control UI Video Talk with Platform auth, OpenAI WebRTC receives camera context on demand:
|
||
when the model calls `describe_view`, the browser sends one bounded JPEG over
|
||
the realtime data channel. OpenClaw does not attach a continuous camera track
|
||
to the OpenAI session.
|
||
</Note>
|
||
|
||
## Memory embeddings
|
||
|
||
OpenClaw can use OpenAI, or an OpenAI-compatible embedding endpoint, for
|
||
`memory_search` indexing and query embeddings:
|
||
|
||
```json5
|
||
{
|
||
memory: {
|
||
search: {
|
||
provider: "openai",
|
||
model: "text-embedding-3-small",
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
For OpenAI-compatible endpoints that require asymmetric embedding labels, set
|
||
`queryInputType` and `documentInputType` under `memory.search`. OpenClaw
|
||
forwards these as provider-specific `input_type` request fields: query
|
||
embeddings use `queryInputType`; indexed memory chunks and batch indexing use
|
||
`documentInputType`. See the
|
||
[Memory configuration reference](/reference/memory-config#provider-specific-config)
|
||
for the full example.
|
||
|
||
## Getting started
|
||
|
||
<Tabs>
|
||
<Tab title="API key (OpenAI Platform)">
|
||
**Best for:** direct API access and usage-based billing.
|
||
|
||
<Steps>
|
||
<Step title="Get your API key">
|
||
Create or copy an API key from the [OpenAI Platform dashboard](https://platform.openai.com/api-keys).
|
||
</Step>
|
||
<Step title="Run onboarding">
|
||
```bash
|
||
openclaw onboard --auth-choice openai-api-key
|
||
```
|
||
|
||
Or pass the key directly:
|
||
|
||
```bash
|
||
openclaw onboard --openai-api-key "$OPENAI_API_KEY"
|
||
```
|
||
</Step>
|
||
<Step title="Verify the model is available">
|
||
```bash
|
||
openclaw models list --provider openai
|
||
```
|
||
</Step>
|
||
</Steps>
|
||
|
||
### Route summary
|
||
|
||
| Model ref | Runtime policy or route facts | Route | Auth |
|
||
| ---------------- | ------------------------------------------------------------- | ------------------------- | --------------------------------- |
|
||
| `openai/gpt-5.6` | unset/`auto`, exact official HTTPS native route, no request override | Codex may be selected | Ordered API-key auth profile |
|
||
| `openai/gpt-5.6` | provider/model `agentRuntime.id: "openclaw"` | OpenClaw embedded runtime | Selected `openai` API-key profile |
|
||
| `openai/gpt-5.5` | explicit provider/model `agentRuntime.id` | Selected agent runtime | Selected OpenAI API-key profile |
|
||
| `openai/*` | authored Completions, custom, or request override | OpenClaw embedded runtime | Credential type remains unchanged |
|
||
| `openai/*` | plaintext official HTTP endpoint | Rejected | Credential is not sent |
|
||
|
||
<Note>
|
||
With runtime unset or `auto`, only an eligible exact official HTTPS native
|
||
route may select the Codex app-server harness implicitly. For API-key auth
|
||
on an agent model, create an `openai` API-key auth profile and order it with
|
||
`auth.order.openai`; `OPENAI_API_KEY` remains the direct fallback for
|
||
non-agent OpenAI API surfaces. Run `openclaw doctor --fix` to migrate older
|
||
legacy Codex auth-order entries.
|
||
</Note>
|
||
|
||
### Config example
|
||
|
||
```json5
|
||
{
|
||
env: { vars: { OPENAI_API_KEY: "example-openai-key-not-real" } },
|
||
agents: { defaults: { model: { primary: "openai/gpt-5.6-sol" } } },
|
||
}
|
||
```
|
||
|
||
The bare direct-API `gpt-5.6` alias is also accepted and resolves to the
|
||
Sol tier. If this API organization does not expose GPT-5.6, set the primary
|
||
to `openai/gpt-5.5` explicitly.
|
||
|
||
To try ChatGPT's current Instant model from the OpenAI API, set the model
|
||
to `openai/chat-latest`:
|
||
|
||
```json5
|
||
{
|
||
env: { vars: { OPENAI_API_KEY: "example-openai-key-not-real" } },
|
||
agents: { defaults: { model: { primary: "openai/chat-latest" } } },
|
||
}
|
||
```
|
||
|
||
`chat-latest` is a moving alias. Fresh OpenAI API-key setup instead uses
|
||
`openai/gpt-5.6-sol`. The bare direct-API `openai/gpt-5.6` alias remains
|
||
supported and resolves to Sol. Existing
|
||
explicit primaries, including `openai/gpt-5.5`, remain unchanged. The
|
||
`chat-latest` alias only accepts `medium` text verbosity; OpenClaw forces
|
||
any other requested verbosity to `medium` for this model.
|
||
|
||
<Warning>
|
||
OpenClaw does **not** expose `gpt-5.3-codex-spark` on the direct OpenAI
|
||
API-key route. It is available only through Codex subscription catalog
|
||
entries when your signed-in account exposes it.
|
||
</Warning>
|
||
|
||
</Tab>
|
||
|
||
<Tab title="Codex subscription">
|
||
**Best for:** using your ChatGPT/Codex subscription with native Codex
|
||
app-server execution instead of a separate API key. Codex cloud requires
|
||
ChatGPT sign-in.
|
||
|
||
<Steps>
|
||
<Step title="Run Codex OAuth">
|
||
```bash
|
||
openclaw onboard --auth-choice openai
|
||
```
|
||
|
||
Or run OAuth directly:
|
||
|
||
```bash
|
||
openclaw models auth login --provider openai
|
||
```
|
||
|
||
For headless or callback-hostile setups, add `--device-code` to sign
|
||
in with a ChatGPT device-code flow instead of the localhost browser
|
||
callback:
|
||
|
||
```bash
|
||
openclaw models auth login --provider openai --device-code
|
||
```
|
||
</Step>
|
||
<Step title="Use the canonical OpenAI model route">
|
||
```bash
|
||
openclaw config set agents.defaults.model.primary openai/gpt-5.6-sol
|
||
```
|
||
|
||
No runtime config is required for this exact official HTTPS native
|
||
route. It may select the Codex app-server runtime automatically, and
|
||
OpenClaw installs or repairs the bundled Codex plugin when that runtime
|
||
is chosen.
|
||
</Step>
|
||
<Step title="Verify Codex auth is available">
|
||
```bash
|
||
openclaw models list --provider openai
|
||
```
|
||
|
||
After the gateway is running, send `/codex status` or `/codex models`
|
||
in chat to verify the native app-server runtime.
|
||
</Step>
|
||
</Steps>
|
||
|
||
### Route summary
|
||
|
||
| Model ref | Runtime policy or route facts | Route | Auth |
|
||
| ------------------------ | ------------------------------------------------------------- | -------------------------------------------------------- | -------------------------------------------------- |
|
||
| `openai/gpt-5.6-sol` | unset/`auto`, exact official HTTPS native route, no request override | Codex may be selected | Codex sign-in, or an ordered `openai` auth profile |
|
||
| `openai/gpt-5.6-terra` | unset/`auto`, exact official HTTPS native route, no request override | Codex may be selected | Codex sign-in when the catalog exposes Terra |
|
||
| `openai/gpt-5.6-luna` | unset/`auto`, exact official HTTPS native route, no request override | Codex may be selected | Codex sign-in when the catalog exposes Luna |
|
||
| `openai/gpt-5.6-sol` | provider/model `agentRuntime.id: "openclaw"` | OpenClaw embedded runtime, internal Codex-auth transport | Selected `openai` OAuth profile |
|
||
| `openai/gpt-5.5` | explicit provider/model `agentRuntime.id` | Selected agent runtime | Selected OpenAI auth profile |
|
||
| `openai/*` | authored Completions, custom, or request override | OpenClaw embedded runtime | Credential requirement remains route-specific |
|
||
| `openai/*` | plaintext official HTTP endpoint | Rejected | Credential is not sent |
|
||
| Legacy Codex GPT-5.5 ref | repaired by doctor | Rewritten to `openai/gpt-5.5` | Migrated OpenAI OAuth profile |
|
||
| `codex-cli/gpt-5.5` | repaired by doctor | Rewritten to `openai/gpt-5.5` | Codex app-server auth |
|
||
|
||
<Warning>
|
||
Fresh subscription-backed setup uses exact `openai/gpt-5.6-sol`; the
|
||
native Codex catalog may also expose exact Terra or Luna refs. If the
|
||
account does not expose GPT-5.6, select `openai/gpt-5.5` explicitly. Older
|
||
Codex GPT refs are legacy OpenClaw routes, not the native Codex runtime
|
||
path; run `openclaw doctor --fix` to migrate them without upgrading an
|
||
existing explicit GPT-5.5 selection. `gpt-5.3-codex-spark` stays limited
|
||
to accounts whose Codex subscription catalog advertises it; direct OpenAI
|
||
API-key and Azure refs for it stay suppressed.
|
||
</Warning>
|
||
|
||
<Note>
|
||
New config should put OpenAI agent auth order under `auth.order.openai`;
|
||
doctor migrates older legacy Codex auth-order entries.
|
||
</Note>
|
||
|
||
### Config example
|
||
|
||
```json5
|
||
{
|
||
plugins: { entries: { codex: { enabled: true } } },
|
||
agents: {
|
||
defaults: {
|
||
model: { primary: "openai/gpt-5.6-sol" },
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
With an API-key backup, keep the selected model under `openai/*` and put
|
||
the auth order under `openai`. OpenClaw tries the subscription first, then
|
||
the API key, while staying on the Codex harness:
|
||
|
||
```json5
|
||
{
|
||
plugins: { entries: { codex: { enabled: true } } },
|
||
agents: {
|
||
defaults: {
|
||
model: { primary: "openai/gpt-5.6-sol" },
|
||
},
|
||
},
|
||
auth: {
|
||
order: {
|
||
openai: [
|
||
"openai:[email protected]",
|
||
"openai:api-key-backup",
|
||
],
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
<Note>
|
||
Onboarding no longer imports OAuth material from `~/.codex`. Sign in with
|
||
browser OAuth (default) or the device-code flow above; OpenClaw manages the
|
||
resulting credentials in its own agent auth store.
|
||
</Note>
|
||
|
||
### Check and recover Codex OAuth routing
|
||
|
||
```bash
|
||
openclaw models status
|
||
openclaw models auth list --provider openai
|
||
openclaw config get agents.defaults.model --json
|
||
openclaw config get models.providers.openai.agentRuntime --json
|
||
```
|
||
|
||
For a specific agent, add `--agent <id>`:
|
||
|
||
```bash
|
||
openclaw models status --agent <id>
|
||
openclaw models auth list --agent <id> --provider openai
|
||
```
|
||
|
||
If an older config still has legacy Codex GPT refs, or a stale OpenAI
|
||
runtime session pin without explicit runtime config, repair it:
|
||
|
||
```bash
|
||
openclaw doctor --fix
|
||
openclaw config validate
|
||
```
|
||
|
||
If `models auth list --provider openai` shows no usable profile, sign in
|
||
again:
|
||
|
||
```bash
|
||
openclaw models auth login --provider openai
|
||
openclaw models status --probe --probe-provider openai
|
||
```
|
||
|
||
Use `--profile-id` for multiple Codex OAuth logins in the same agent, then
|
||
control them via auth ordering or `/model ...@<profileId> -s`:
|
||
|
||
```bash
|
||
openclaw models auth login --provider openai --profile-id openai:ritsuko
|
||
openclaw models auth login --provider openai --profile-id openai:lain
|
||
```
|
||
|
||
Run `openclaw doctor --fix` to migrate older legacy OpenAI Codex prefix
|
||
profile ids and order entries before relying on profile ordering.
|
||
|
||
### Status indicator
|
||
|
||
Chat `/status` shows which model runtime is active for the current
|
||
session. The bundled Codex app-server harness appears as
|
||
`Runtime: OpenAI Codex` when an eligible implicit route or explicit
|
||
provider/model runtime policy selects it.
|
||
|
||
### Doctor warning
|
||
|
||
If legacy Codex model refs or stale OpenAI runtime pins remain in config
|
||
or session state, `openclaw doctor --fix` rewrites them to `openai/*` with
|
||
the Codex runtime unless OpenClaw is explicitly configured.
|
||
|
||
### Context window defaults and long-context opt-in
|
||
|
||
OpenClaw treats native model capacity and the active runtime budget as
|
||
separate values:
|
||
|
||
- `contextWindow` declares the model's native window.
|
||
- `contextTokens` caps how much of that window OpenClaw uses for active input.
|
||
|
||
ChatGPT/Codex OAuth follows the live Codex account catalog. The current
|
||
catalog commonly advertises a `272000` token active window for GPT-5.6.
|
||
Direct API-key GPT-5.5 and GPT-5.6 models also default to `272000`
|
||
`contextTokens`, even though the Platform API exposes a larger native
|
||
window. This keeps the normal latency, quality, and cost profile consistent
|
||
across auth modes. Override a direct model's active-input budget with
|
||
`models.providers.openai.models[].contextTokens` on that exact model entry.
|
||
|
||
For direct API-key GPT-5.5 and GPT-5.6, OpenAI documents a `1050000`
|
||
token provider window and `128000` maximum output tokens. Reserving the
|
||
full output allowance gives the shared safe input budget used by both
|
||
runtime recipes below:
|
||
|
||
```text
|
||
1050000 total - 128000 maximum output = 922000 safe active input
|
||
automatic compaction threshold = 700000 active tokens
|
||
```
|
||
|
||
`922000` is a derived operating budget, not a separate provider-published
|
||
input limit. The two runtimes translate that budget differently: embedded
|
||
OpenClaw sends Responses compaction controls, while native Codex owns its
|
||
catalog window and automatic compaction. See the official
|
||
[model comparison](https://developers.openai.com/api/docs/models/compare)
|
||
and [GPT-5.5 model page](https://developers.openai.com/api/docs/models/gpt-5.5).
|
||
|
||
#### Embedded OpenClaw translation
|
||
|
||
This example pins the exact Sol model to the embedded OpenClaw runtime,
|
||
enables OpenAI API Fast mode through the shared runtime control, and asks OpenAI Responses
|
||
to compact at `700000` active tokens:
|
||
|
||
```json5
|
||
{
|
||
models: {
|
||
providers: {
|
||
openai: {
|
||
models: [
|
||
{
|
||
id: "gpt-5.6-sol",
|
||
name: "GPT-5.6 Sol",
|
||
contextWindow: 1050000,
|
||
contextTokens: 922000,
|
||
maxTokens: 128000,
|
||
},
|
||
],
|
||
},
|
||
},
|
||
},
|
||
agents: {
|
||
defaults: {
|
||
model: { primary: "openai/gpt-5.6-sol" },
|
||
models: {
|
||
"openai/gpt-5.6-sol": {
|
||
agentRuntime: { id: "openclaw" },
|
||
params: {
|
||
fastMode: true,
|
||
responsesServerCompaction: true,
|
||
responsesCompactThreshold: 700000,
|
||
},
|
||
},
|
||
},
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
OpenAI Responses automatic compaction emits an encrypted `compaction`
|
||
output item. A stateless client carries the newest item into the next
|
||
request and may drop every earlier input item. OpenClaw persists that item
|
||
opaquely, fences reuse by route, session, and auth, replays it, prunes the
|
||
replaced prefix, carries it through worker transcript commits, and removes
|
||
it from display and diagnostics. Never print, log, or expose the encrypted
|
||
content.
|
||
|
||
A process-owned isolated-Gateway run verified this exact
|
||
`openai/gpt-5.6-sol` configuration. Dense turns reached `295098`, `586562`,
|
||
and `863664` prompt tokens. Turn three emitted and persisted a first-class
|
||
server compaction item; the next request replayed that exact opaque item,
|
||
pruned its prefix, and used `9602` prompt tokens. A deterministic long
|
||
response produced `5480` output tokens, durable markers survived compaction
|
||
and Gateway restart, restart latency was `12081` ms, every call reported
|
||
`serviceTier: priority`, and the full suite took `220.03` seconds. These
|
||
timings are observations, not service-level guarantees.
|
||
|
||
#### Native Codex translation
|
||
|
||
Keep the same OpenClaw model selection, but make Codex the explicit runtime
|
||
and do not add Responses compaction params to this model entry:
|
||
|
||
```json5
|
||
{
|
||
agents: {
|
||
defaults: {
|
||
model: { primary: "openai/gpt-5.6-sol" },
|
||
models: {
|
||
"openai/gpt-5.6-sol": {
|
||
agentRuntime: { id: "codex" },
|
||
params: { fastMode: true },
|
||
},
|
||
},
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
Codex must receive `922000` for both `context_window` and
|
||
`max_context_window`, `700000` for `auto_compact_token_limit`, and matching
|
||
app-server overrides with `model_auto_compact_token_limit_scope=total`.
|
||
Codex then applies its 95% effective-window reserve, yielding `875900`
|
||
active tokens. Configure an ordered OpenAI API-key profile and keep the
|
||
default isolated agent-scoped Codex home. The complete catalog, app-server,
|
||
auth, and restart recipe is in
|
||
[Codex harness long context](/plugins/codex-harness/configuration#direct-api-long-context).
|
||
|
||
These examples are two explicit runtime choices, not one auto-selecting
|
||
configuration. The model-scoped `agentRuntime` and runtime-owned compaction
|
||
settings must change together. OpenClaw can retain both choices only when
|
||
their model refs or agent configurations are distinguishable; otherwise,
|
||
switch the model runtime and its matching config as one atomic change. Then
|
||
restart the Gateway and native Codex app-server, run `/model default -s`,
|
||
and start a fresh chat. Existing native Codex threads retain the provider
|
||
and model recorded when they were created.
|
||
|
||
<Warning>
|
||
OpenAI applies higher long-context pricing once a GPT-5.5 or GPT-5.6
|
||
request exceeds `272000` input tokens: the whole qualifying request is
|
||
billed at 2× input and cache rates and 1.5× output rates. Fast-mode pricing
|
||
is model-specific; GPT-5.6 Sol API Fast mode is currently another 2× over
|
||
Standard. For that model, combined long-context Fast traffic is therefore
|
||
4× short-context Standard input-side pricing and 3× short-context Standard
|
||
output pricing. Large prompts are resent or compacted across turns, so an
|
||
opt-in session can cost substantially more than the default even when the
|
||
visible reply is short. See [Fast mode](https://openai.com/api-priority-processing/)
|
||
and [OpenAI API pricing](https://developers.openai.com/api/docs/pricing).
|
||
The API remains authoritative for account access, actual limits, and billing.
|
||
</Warning>
|
||
|
||
### Catalog recovery
|
||
|
||
OpenClaw uses upstream Codex catalog metadata for `gpt-5.5` when it is
|
||
present. If live Codex discovery omits the `gpt-5.5` row while the account
|
||
is authenticated, OpenClaw synthesizes that OAuth model row so cron,
|
||
sub-agent, and configured default-model runs do not fail with
|
||
`Unknown model`.
|
||
|
||
</Tab>
|
||
</Tabs>
|
||
|
||
## Native Codex app-server auth
|
||
|
||
The native Codex app-server harness uses `openai/*` model refs when an eligible
|
||
exact official HTTPS route selects it implicitly, or when provider/model
|
||
`agentRuntime.id: "codex"` selects it explicitly. Its auth is still
|
||
account-based. OpenClaw selects auth in this order:
|
||
|
||
1. Ordered OpenAI auth profiles for the agent, preferably under
|
||
`auth.order.openai`. Run `openclaw doctor --fix` to migrate older legacy
|
||
Codex auth profile ids and auth order.
|
||
2. The app-server's existing account, such as a local Codex CLI ChatGPT
|
||
sign-in. For the default isolated agent home, OpenClaw bridges that native
|
||
CLI account into the app-server through its login RPC; it does not share the
|
||
CLI's config, plugins, or thread store.
|
||
3. For local stdio app-server launches only, and only when the app-server
|
||
reports no account: `CODEX_API_KEY`, then `OPENAI_API_KEY`.
|
||
|
||
The default per-agent `codex-home/auth.json` is not a runtime auth store. If
|
||
you copied or mounted Codex CLI credentials there, import them into the agent's
|
||
OpenClaw auth store before starting a native Codex turn. Replace `<agent-id>`
|
||
with the configured agent that owns this Codex home:
|
||
|
||
```bash
|
||
openclaw migrate plan codex --from <codex-home> --agent <agent-id> --include-secrets --item auth:openai
|
||
openclaw migrate apply codex --from <codex-home> --agent <agent-id> --include-secrets --item auth:openai --yes
|
||
```
|
||
|
||
A local ChatGPT/Codex subscription sign-in is not replaced just because the
|
||
gateway process also has `OPENAI_API_KEY` for direct OpenAI models or
|
||
embeddings. The env API-key fallback applies only to the local stdio no-account
|
||
path; it is never sent over WebSocket app-server connections. When a
|
||
subscription-style Codex profile is selected, OpenClaw also keeps
|
||
`CODEX_API_KEY` and `OPENAI_API_KEY` out of the spawned stdio app-server child
|
||
and sends the selected credentials through the app-server login RPC instead.
|
||
|
||
When that subscription profile is blocked by a Codex usage limit, OpenClaw
|
||
marks the profile blocked until Codex's advertised reset time and lets auth
|
||
ordering rotate to the next `openai:*` profile, without changing the selected
|
||
model or dropping out of the Codex harness. Once the reset time passes, the
|
||
subscription profile is eligible again.
|
||
|
||
## Image generation
|
||
|
||
The bundled `openai` plugin registers image generation through the
|
||
`image_generate` tool. It supports both OpenAI API-key and Codex OAuth image
|
||
generation through the same `openai/gpt-image-2` model ref.
|
||
|
||
| Capability | OpenAI API key | Codex OAuth |
|
||
| ------------------------- | ---------------------------------- | ------------------------------------ |
|
||
| Model ref | `openai/gpt-image-2` | `openai/gpt-image-2` |
|
||
| Auth | `OPENAI_API_KEY` | OpenAI Codex OAuth sign-in |
|
||
| Transport | OpenAI Images API | Codex Responses backend |
|
||
| Max images per request | 4 | 4 |
|
||
| Edit mode | Enabled (up to 5 reference images) | Enabled (up to 5 reference images) |
|
||
| Moderation | `low` or `auto`; generate and edit | `low` or `auto`; generate and edit |
|
||
| Size overrides | Supported, including 2K/4K sizes | Supported, including 2K/4K sizes |
|
||
| Aspect ratio / resolution | Not forwarded to OpenAI Images API | Mapped to a supported size when safe |
|
||
|
||
```json5
|
||
{
|
||
agents: {
|
||
defaults: {
|
||
mediaModels: { image: { primary: "openai/gpt-image-2" } },
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
<Note>
|
||
See [Image Generation](/tools/image-generation) for shared tool parameters,
|
||
provider selection, and failover behavior.
|
||
</Note>
|
||
|
||
`gpt-image-2` is the default for OpenAI text-to-image generation and image
|
||
editing. `gpt-image-1.5`, `gpt-image-1`, and `gpt-image-1-mini` remain usable
|
||
as explicit model overrides. Use `openai/gpt-image-1.5` for
|
||
transparent-background PNG/WebP output; the current `gpt-image-2` API rejects
|
||
`background: "transparent"`.
|
||
|
||
For a transparent-background request, call `image_generate` with
|
||
`model: "openai/gpt-image-1.5"`, `outputFormat: "png"` or `"webp"`, and
|
||
`background: "transparent"`; the older `openai.background` provider option is
|
||
still accepted. OpenClaw also protects the public OpenAI and OpenAI Codex OAuth
|
||
routes by rewriting default `openai/gpt-image-2` transparent requests to
|
||
`gpt-image-1.5`; Azure and custom OpenAI-compatible endpoints keep their
|
||
configured deployment/model names.
|
||
|
||
The same setting is exposed for headless CLI runs:
|
||
|
||
```bash
|
||
openclaw infer image generate \
|
||
--model openai/gpt-image-1.5 \
|
||
--output-format png \
|
||
--background transparent \
|
||
--prompt "A simple red circle sticker on a transparent background" \
|
||
--json
|
||
```
|
||
|
||
Use the same `--output-format` and `--background` flags with
|
||
`openclaw infer image edit` when starting from an input file.
|
||
`--openai-background` remains available as an OpenAI-specific alias. Use
|
||
`--quality low|medium|high|auto` to control OpenAI Images quality and cost.
|
||
Use `--openai-moderation low|auto` with both `image generate` and `image edit`
|
||
to pass OpenAI's moderation hint. The direct OpenAI Images API and the
|
||
ChatGPT/Codex OAuth Responses backend both support moderation for text-to-image
|
||
generation and reference-image edits.
|
||
|
||
For ChatGPT/Codex OAuth installs, keep the same `openai/gpt-image-2` ref. When
|
||
an `openai` OAuth profile is configured, OpenClaw resolves that stored OAuth
|
||
access token and sends image requests through the Codex Responses backend; it
|
||
does not first try `OPENAI_API_KEY` or silently fall back to an API key.
|
||
Configure `models.providers.openai` explicitly with an API key, custom base
|
||
URL, or Azure endpoint when you want the direct OpenAI Images API route
|
||
instead. If that custom image endpoint is on a trusted LAN/private address,
|
||
also set `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`; OpenClaw
|
||
keeps private/internal OpenAI-compatible image endpoints blocked unless this
|
||
opt-in is present.
|
||
|
||
Generate:
|
||
|
||
```
|
||
/tool image_generate model=openai/gpt-image-2 prompt="A polished launch poster for OpenClaw on macOS" size=3840x2160 count=1
|
||
```
|
||
|
||
Generate a transparent PNG:
|
||
|
||
```
|
||
/tool image_generate model=openai/gpt-image-1.5 prompt="A simple red circle sticker on a transparent background" outputFormat=png background=transparent
|
||
```
|
||
|
||
Edit:
|
||
|
||
```
|
||
/tool image_generate model=openai/gpt-image-2 prompt="Preserve the object shape, change the material to translucent glass" image=/path/to/reference.png size=1024x1536
|
||
```
|
||
|
||
## Video generation
|
||
|
||
The bundled `openai` plugin registers video generation through the
|
||
`video_generate` tool.
|
||
|
||
| 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 for text-to-video and image-to-video |
|
||
| Aspect ratio | Converted to the closest supported size, not forwarded raw |
|
||
| Other overrides | `resolution`, `audio`, `watermark` are unsupported and dropped with a tool warning |
|
||
|
||
OpenAI image-to-video requests use `POST /v1/videos` with an image
|
||
`input_reference`. Single-video edits use `POST /v1/videos/edits` with the
|
||
uploaded video in the `video` field.
|
||
|
||
```json5
|
||
{
|
||
agents: {
|
||
defaults: {
|
||
mediaModels: { video: { primary: "openai/sora-2" } },
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
<Note>
|
||
See [Video Generation](/tools/video-generation) for shared tool parameters,
|
||
provider selection, and failover behavior.
|
||
|
||
The OpenAI provider declares `supportsSize` but not `supportsAspectRatio` or
|
||
`supportsResolution`. OpenClaw's shared normalization layer converts a
|
||
requested `aspectRatio` into the closest matching OpenAI `size` before the
|
||
request reaches the provider, so aspect-ratio requests generally still work.
|
||
`resolution` has no size fallback and is dropped, surfaced to the caller as
|
||
`Ignored unsupported overrides for openai/<model>: resolution=<value>`.
|
||
</Note>
|
||
|
||
## GPT-5 prompt contribution
|
||
|
||
OpenClaw adds a shared GPT-5 prompt contribution to matching GPT-5-family
|
||
OpenClaw-assembled prompts. The OpenAI plugin setting below controls the
|
||
friendly style on OpenAI-family routes. Older GPT-4.x model ids do not match.
|
||
|
||
The native Codex app-server harness does not receive the persona/tool-
|
||
discipline behavior contract or the friendly interaction-style overlay through
|
||
developer instructions; native Codex keeps Codex-owned base, model, and
|
||
project-doc behavior, and OpenClaw disables Codex's built-in personality for
|
||
native threads so agent workspace personality files stay authoritative.
|
||
OpenClaw contributes only runtime context to native Codex threads: channel
|
||
delivery, OpenClaw dynamic tools, ACP delegation, workspace context, and
|
||
OpenClaw skills. The heartbeat-guidance text from this same contribution is the
|
||
one exception: native Codex heartbeat turns do get it, injected as dedicated
|
||
collaboration instructions rather than through the shared prompt-contribution
|
||
hook.
|
||
|
||
The GPT-5 contribution adds a tagged behavior contract for persona
|
||
persistence, execution safety, tool discipline, output shape, completion
|
||
checks, and verification on matching OpenClaw-assembled prompts. Channel-
|
||
specific reply and silent-message behavior stays in the shared OpenClaw system
|
||
prompt and outbound delivery policy. The friendly interaction-style layer is
|
||
separate and configurable.
|
||
|
||
| Value | Effect |
|
||
| ---------------------- | ------------------------------------------- |
|
||
| `"friendly"` (default) | Enable the friendly interaction-style layer |
|
||
| `"on"` | Alias for `"friendly"` |
|
||
| `"off"` | Disable only the friendly style layer |
|
||
|
||
<Tabs>
|
||
<Tab title="Config">
|
||
```json5
|
||
{
|
||
plugins: {
|
||
entries: {
|
||
openai: {
|
||
config: { personality: "friendly" },
|
||
},
|
||
},
|
||
},
|
||
}
|
||
```
|
||
</Tab>
|
||
<Tab title="CLI">
|
||
```bash
|
||
openclaw config set plugins.entries.openai.config.personality off
|
||
```
|
||
</Tab>
|
||
</Tabs>
|
||
|
||
<Tip>
|
||
Values are case-insensitive at runtime, so `"Off"` and `"off"` both disable the
|
||
friendly style layer.
|
||
</Tip>
|
||
|
||
<Note>
|
||
The retired `agents.defaults.promptOverlays` key is no longer read; config
|
||
validation rejects it, and `openclaw doctor --fix` migrates its personality
|
||
value into `plugins.entries.openai.config.personality` when that key is unset.
|
||
</Note>
|
||
|
||
## Voice and speech
|
||
|
||
<AccordionGroup>
|
||
<Accordion title="Speech synthesis (TTS)">
|
||
The bundled `openai` plugin registers speech synthesis for the
|
||
`tts` surface.
|
||
|
||
| Setting | Config path | Default |
|
||
| ------------- | --------------------------------------------------------- | ----------------------------------- |
|
||
| Model | `tts.providers.openai.model` | `gpt-4o-mini-tts` |
|
||
| Voice | `tts.providers.openai.speakerVoice` | `coral` |
|
||
| Speed | `tts.providers.openai.speed` | (unset) |
|
||
| Instructions | `tts.providers.openai.instructions` | (unset, `gpt-4o-mini-tts` family only) |
|
||
| Format | `tts.providers.openai.responseFormat` | `opus` for voice notes, `mp3` for files |
|
||
| API key | `tts.providers.openai.apiKey` | Falls back to `OPENAI_API_KEY` |
|
||
| Base URL | `tts.providers.openai.baseUrl` | `https://api.openai.com/v1` |
|
||
| Extra body | `tts.providers.openai.extraBody` / `extra_body` | (unset) |
|
||
|
||
Available models: `gpt-4o-mini-tts`, `gpt-4o-mini-tts-2025-12-15`, `tts-1`,
|
||
`tts-1-hd`. Available voices: `alloy`, `ash`, `ballad`, `cedar`, `coral`,
|
||
`echo`, `fable`, `juniper`, `marin`, `onyx`, `nova`, `sage`, `shimmer`,
|
||
`verse`.
|
||
|
||
`extraBody` is merged into `/audio/speech` request JSON after OpenClaw's
|
||
generated fields, so use it for OpenAI-compatible endpoints that require
|
||
additional keys such as `lang`. Prototype keys are ignored.
|
||
|
||
```json5
|
||
{
|
||
tts: {
|
||
providers: {
|
||
openai: { model: "gpt-4o-mini-tts", speakerVoice: "coral" },
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
<Note>
|
||
Set `OPENAI_TTS_BASE_URL` to override the TTS base URL without affecting
|
||
the chat API endpoint. OpenAI TTS requires an OpenAI Platform API key.
|
||
OAuth-only installs can use Codex-backed chat models and GA Realtime browser
|
||
Talk over a ChatGPT subscription when the account has access (see the
|
||
Realtime accordion).
|
||
OpenAI TTS, Voice Call, GA Gateway relay, and Discord realtime voice still
|
||
require a Platform API key.
|
||
</Note>
|
||
|
||
</Accordion>
|
||
|
||
<Accordion title="Speech-to-text">
|
||
The bundled `openai` plugin registers batch speech-to-text through
|
||
OpenClaw's media-understanding transcription surface.
|
||
|
||
Batch transcription can use the selected OpenAI API-key or ChatGPT OAuth
|
||
profile on the standard transcription endpoint when the account permits it.
|
||
Configured models, prompts, and language hints work through the same request
|
||
path. Access and quota errors are reported without switching credential
|
||
classes; OAuth support does not imply included or unlimited transcription.
|
||
Custom endpoints and request overrides require an API-key profile.
|
||
See [Audio and voice notes](/nodes/audio#openai-transcription-alongside-chatgpt%2Fcodex-oauth)
|
||
for selecting a separate audio API-key profile when desired.
|
||
|
||
- Default model: `gpt-4o-transcribe`
|
||
- Endpoint: OpenAI REST `/v1/audio/transcriptions`
|
||
- Input path: multipart audio file upload
|
||
- Used wherever inbound audio transcription reads `tools.media.audio`,
|
||
including Discord voice-channel segments and channel audio attachments
|
||
|
||
To force OpenAI for inbound audio transcription:
|
||
|
||
```json5
|
||
{
|
||
tools: {
|
||
media: {
|
||
models: [
|
||
{
|
||
type: "provider",
|
||
provider: "openai",
|
||
model: "gpt-4o-transcribe",
|
||
capabilities: ["audio"],
|
||
},
|
||
],
|
||
audio: {
|
||
enabled: true,
|
||
},
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
Language and prompt hints are forwarded to OpenAI when supplied by the
|
||
shared audio media config or per-call transcription request.
|
||
|
||
</Accordion>
|
||
|
||
<Accordion title="Realtime transcription">
|
||
The bundled `openai` plugin registers realtime transcription for the
|
||
Voice Call plugin.
|
||
|
||
| Setting | Config path | Default |
|
||
| ----------------- | ----------------------------------------------------------------------- | --------- |
|
||
| Model | `plugins.entries.voice-call.config.streaming.providers.openai.model` | `gpt-4o-transcribe` |
|
||
| Language | `...openai.language` | (unset) |
|
||
| Prompt | `...openai.prompt` | (unset) |
|
||
| Silence duration | `...openai.silenceDurationMs` | `800` |
|
||
| VAD threshold | `...openai.vadThreshold` | `0.5` |
|
||
| Auth | `...openai.apiKey`, `OPENAI_API_KEY`, or `openai` API-key profile | Platform API key required |
|
||
|
||
<Note>
|
||
Uses a WebSocket connection to `wss://api.openai.com/v1/realtime` with
|
||
G.711 u-law (`g711_ulaw` / `audio/pcmu`) audio. For an `openai` API-key
|
||
profile, the Gateway mints an ephemeral Realtime transcription client
|
||
secret before opening the WebSocket. This streaming provider is for Voice
|
||
Call's realtime transcription path; Discord voice currently records short
|
||
segments and uses the batch `tools.media.audio` transcription path
|
||
instead.
|
||
</Note>
|
||
|
||
</Accordion>
|
||
|
||
<Accordion title="Realtime voice">
|
||
The bundled `openai` plugin registers realtime voice for the Voice Call
|
||
plugin.
|
||
|
||
| Setting | Config path | Default |
|
||
| --------------------------------------- | ---------------------------------------------------------------------------- | ---------------------- |
|
||
| Model | `plugins.entries.voice-call.config.realtime.providers.openai.model` | `gpt-realtime-2.1` |
|
||
| Voice | `...openai.voice` | `alloy` |
|
||
| Temperature (Azure deployment bridge) | `...openai.temperature` | `0.8` |
|
||
| VAD threshold | `...openai.vadThreshold` | `0.5` |
|
||
| Silence duration | `...openai.silenceDurationMs` | `500` |
|
||
| Prefix padding | `...openai.prefixPaddingMs` | `300` |
|
||
| Reasoning effort | `...openai.reasoningEffort` | (unset) |
|
||
| Auth | `openai` auth profile, `...openai.apiKey`, or `OPENAI_API_KEY` | Released GPT-Live: OAuth first; ordinary GA browser: Platform first; Platform required for other routes |
|
||
|
||
Available built-in Realtime voices for `gpt-realtime-2.1`: `alloy`, `ash`,
|
||
`ballad`, `coral`, `echo`, `sage`, `shimmer`, `verse`, `marin`, `cedar`.
|
||
OpenAI recommends `marin` and `cedar` for the best Realtime quality. This
|
||
is a separate set from the Text-to-speech voices above; a TTS-only voice
|
||
such as `fable`, `nova`, or `onyx` is not valid for Realtime sessions.
|
||
Set the model explicitly to `gpt-realtime-2.1-mini` when you prefer the
|
||
smaller, lower-cost Realtime 2.1 variant.
|
||
|
||
#### Gateway-controlled Realtime call cleanup
|
||
|
||
Closing a Gateway-controlled GA Realtime WebRTC session retires its Gateway
|
||
authority and closes the local sideband before asking OpenAI to hang up the
|
||
provider call. These are separate events; control closure does not establish
|
||
provider acknowledgment or recall already queued media.
|
||
|
||
If hangup fails, explicit cancellation or cleanup reports the failure. The
|
||
broker retries automatically after 1 second, then 5 seconds, with the existing
|
||
30-second timeout for each attempt. After all three attempts fail, the log
|
||
reports `cleanup INCOMPLETE`. The exact cleanup obligation and its capacity
|
||
remain reserved, including across plugin replacement: eight sessions globally
|
||
and two per Gateway client. Restore provider connectivity; a later OpenAI
|
||
broker/plugin runtime cleanup can retry these retained calls. Repeating End
|
||
or `talk.client.close` is not that retry boundary because the Gateway session
|
||
may already be retired.
|
||
|
||
Cleanup obligations are in memory only. Gateway exit, crash, or restart can
|
||
lose them; restarting is not proof that the provider call ended. The
|
||
adapter's 30-minute active-session lease is not a remote-lifetime guarantee
|
||
or a fallback after failed hangup.
|
||
|
||
#### GA Realtime browser authentication
|
||
|
||
Ordinary GA browser Talk tries Platform auth first in this order: the
|
||
configured realtime key, an `openai` API-key profile, then `OPENAI_API_KEY`.
|
||
When a Platform credential is available, the Gateway mints an ephemeral
|
||
client secret and the browser performs the SDP exchange directly.
|
||
|
||
When no Platform credential source is configured, ordinary GA browser Talk
|
||
falls back to the OpenClaw ChatGPT OAuth subscription profile. The
|
||
single-use Gateway offer broker keeps OAuth server-side, exchanges the
|
||
browser's SDP, and returns only the answer SDP. An explicitly configured but
|
||
unavailable Platform credential fails instead of falling back to OAuth.
|
||
|
||
Gateway-controlled GA relay, iOS client-owned WebRTC, Voice Call, direct
|
||
backend sockets, and Discord realtime voice require Platform auth.
|
||
|
||
#### Released GPT-Live browser and Gateway relay authentication
|
||
|
||
Released GPT-Live browser and Gateway-relay WebRTC try the OpenClaw ChatGPT
|
||
OAuth subscription profile first. When OAuth is unavailable, the Gateway
|
||
falls back to Platform auth in this order: the configured realtime key, an
|
||
`openai` API-key profile, then `OPENAI_API_KEY`. Create the OAuth profile
|
||
with `openclaw models auth login --provider openai`.
|
||
|
||
Both credential types stay in the Gateway. The single-use offer broker
|
||
exchanges the browser's SDP and returns only the answer SDP; it does not
|
||
send an OAuth token, Platform key, or ephemeral client secret to the browser.
|
||
|
||
The enabled OpenAI plugin starts the broker automatically, including when
|
||
you sign in after the Gateway has started. The broker opens a provider
|
||
session only when you start Talk; signing in does not open the microphone or
|
||
start a voice session. Returning to the browser after sign-in refreshes the
|
||
chat microphone's readiness.
|
||
|
||
#### Unlisted and private realtime transport paths
|
||
|
||
Unlisted or private browser Talk uses Platform-key client WebRTC with
|
||
Gateway-owned control. Gateway relay and other direct backend consumers use
|
||
the Platform-key bidirectional transport. Credentials and provider control
|
||
remain on the Gateway.
|
||
|
||
Use the account-issued realtime model value. Unlisted model values are
|
||
accepted as free-form Talk config but are not published through catalogs
|
||
or diagnostics. Opt in explicitly with `talk.realtime.model`; the released
|
||
model remains the default.
|
||
|
||
Current Platform-key sessions accept `marin` and `cedar`. OpenClaw defaults
|
||
to `marin` and maps unsupported configured voices back to it.
|
||
|
||
Unlisted or private browser WebRTC prerequisites, in order:
|
||
|
||
1. A Platform API key configured through `talk.realtime.providers.openai.apiKey`,
|
||
an `openai` API-key profile, or `OPENAI_API_KEY`.
|
||
2. `talk.realtime.model` set to the account-issued value — via **Settings →
|
||
Talk** in the Control UI or the config below.
|
||
3. The bundled `openai` plugin registered in full mode. A restrictive
|
||
`plugins.allow` list fails with "OpenAI realtime browser session broker
|
||
is unavailable".
|
||
|
||
```json5
|
||
{
|
||
talk: {
|
||
realtime: {
|
||
provider: "openai",
|
||
model: "<account-issued-realtime-model>",
|
||
transport: "webrtc",
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
Gateway relay uses the direct bidirectional transport:
|
||
|
||
```json5
|
||
{
|
||
talk: {
|
||
realtime: {
|
||
provider: "openai",
|
||
model: "<account-issued-realtime-model>",
|
||
transport: "gateway-relay",
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
Browser Talk uses `transport: "webrtc"`.
|
||
|
||
| Consumer | Unlisted/private route status |
|
||
| --- | --- |
|
||
| Browser Talk | Supported with Platform-key client WebRTC and Gateway-owned sideband |
|
||
| Gateway-relay Talk | Supported with direct Platform-key transport |
|
||
| Discord bidirectional voice | Supported with the Platform-key backend WebSocket |
|
||
| Voice Call and telephony | Supported with the Platform-key backend WebSocket |
|
||
| iOS client-owned Talk | Implemented; device live verification pending |
|
||
| Android realtime Talk | Pending an Android device live-proof flip; Android stays on native Talk |
|
||
|
||
These rows describe implemented transports, not account entitlement or
|
||
complete model capability parity. See the [Discord voice policy limits](/channels/discord#voice-channels)
|
||
and [Voice Call tool limits](/plugins/voice-call#realtime-voice-conversations) before
|
||
selecting an unlisted or private route for those consumers.
|
||
|
||
<Warning>
|
||
Unlisted or private routes require a Platform API key with access to the
|
||
configured account-issued model. OAuth is not a fallback for them. If
|
||
session creation is rejected, verify that the key and configured model
|
||
belong to the same Platform project.
|
||
</Warning>
|
||
|
||
A `403 Voice session access denied` response is overloaded and does not by
|
||
itself prove an account entitlement problem: an invalid voice produces the
|
||
same response. First verify the model and voice against the accepted lists
|
||
above, then verify the Platform key and configured model against the same
|
||
project.
|
||
|
||
The released Gateway-owned WebRTC route uses OAuth first with Platform
|
||
fallback, routes sideband delegations through the configured OpenClaw
|
||
agent, and keeps credentials away from relay clients. Unlisted or private
|
||
browser WebRTC and the direct backend socket remain Platform-only. The
|
||
direct socket enables Discord voice and Voice Call/telephony; OpenClaw
|
||
converts G.711 u-law telephony audio to and from the provider's 24 kHz PCM
|
||
stream. Android's client-side gate stays closed until the Gateway relay
|
||
path has live proof from an Android device.
|
||
|
||
The WebRTC path creates a provider call and joins its sideband. The direct
|
||
backend path opens one bidirectional session, sends a Frameless
|
||
`session.update`, then carries PCM audio, transcripts, delegations, and
|
||
delegation results over that socket.
|
||
|
||
Maintainers can exercise the Platform direct path and the separate GA
|
||
browser OAuth path with the opt-in live tests. The account-issued realtime
|
||
model is read from `talk.realtime.model`; missing credentials or model config
|
||
produce sanitized skips, and the tests never print either value:
|
||
|
||
```bash
|
||
OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_GPT_LIVE=1 node --import tsx scripts/test-live.mts -- extensions/openai/realtime-quicksilver.live.test.ts
|
||
OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_GPT_LIVE=1 node --import tsx scripts/test-live.mts -- extensions/openai/realtime-quicksilver-gateway-bridge.live.test.ts
|
||
```
|
||
|
||
<Note>
|
||
GA backend OpenAI realtime bridges use the Realtime WebSocket session
|
||
shape, which does not accept `session.temperature`; GPT-Live uses the
|
||
separate Frameless Bidi shape. Azure OpenAI
|
||
deployments remain available via `azureEndpoint` and `azureDeployment` and
|
||
keep the deployment-compatible session shape (including `temperature`).
|
||
Supports bidirectional tool calling and G.711 u-law audio.
|
||
</Note>
|
||
|
||
<Note>
|
||
Realtime voice is selected when the session is created. OpenAI allows most
|
||
session fields to change later, but the voice cannot be changed after the
|
||
model has emitted audio in that session. OpenClaw currently exposes the
|
||
built-in Realtime voice ids as strings.
|
||
</Note>
|
||
|
||
<Note>
|
||
Control UI Talk uses browser WebRTC sessions. The released
|
||
browser/Gateway-owned route tries ChatGPT OAuth first through the Gateway
|
||
offer broker, keeping OAuth server-side. When OAuth is unavailable, it
|
||
falls back to Platform credentials in this order: configured realtime key,
|
||
API-key profile, then `OPENAI_API_KEY`. Direct backend sockets and unlisted
|
||
or private realtime routes require Platform credentials.
|
||
Maintainer live verification is available with
|
||
`OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts`;
|
||
the OpenAI legs verify the backend WebSocket bridge, a synthesized PCM24
|
||
speech-to-response audio roundtrip, and the browser WebRTC SDP exchange
|
||
without logging secrets. Pass `--openai-only` to run those legs without
|
||
Google credentials. Use `--openai-audio-cycles 3` for a short repeated
|
||
connect, talkback, and close soak.
|
||
</Note>
|
||
|
||
</Accordion>
|
||
</AccordionGroup>
|
||
|
||
## Azure OpenAI endpoints
|
||
|
||
The bundled `openai` provider can target an Azure OpenAI resource for image
|
||
generation by overriding the base URL. On the image-generation path, OpenClaw
|
||
detects Azure hostnames on `models.providers.openai.baseUrl` and switches to
|
||
Azure's request shape automatically.
|
||
|
||
<Note>
|
||
Realtime voice uses a separate configuration path
|
||
(`plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint`)
|
||
and is not affected by `models.providers.openai.baseUrl`. See the **Realtime
|
||
voice** accordion under [Voice and speech](#voice-and-speech) for its Azure
|
||
settings.
|
||
</Note>
|
||
|
||
Use Azure OpenAI when:
|
||
|
||
- You already have an Azure OpenAI subscription, quota, or enterprise
|
||
agreement
|
||
- You need regional data residency or compliance controls Azure provides
|
||
- You want to keep traffic inside an existing Azure tenancy
|
||
|
||
### Configuration
|
||
|
||
For Azure image generation through the bundled `openai` provider, point
|
||
`models.providers.openai.baseUrl` at your Azure resource and set `apiKey` to
|
||
the Azure OpenAI key (not an OpenAI Platform key):
|
||
|
||
```json5
|
||
{
|
||
models: {
|
||
providers: {
|
||
openai: {
|
||
baseUrl: "https://<your-resource>.openai.azure.com",
|
||
apiKey: "<azure-openai-api-key>",
|
||
},
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
OpenClaw recognizes these Azure host suffixes for the Azure image-generation
|
||
route:
|
||
|
||
- `*.openai.azure.com`
|
||
- `*.services.ai.azure.com`
|
||
- `*.cognitiveservices.azure.com`
|
||
|
||
For image-generation requests on a recognized Azure host, OpenClaw:
|
||
|
||
- Sends the `api-key` header instead of `Authorization: Bearer`
|
||
- Uses deployment-scoped paths (`/openai/deployments/{deployment}/...`)
|
||
- Appends `?api-version=...` to each request
|
||
- Uses a 600s default request timeout for Azure image-generation calls.
|
||
Per-call `timeoutMs` values still override this default.
|
||
|
||
Other base URLs (public OpenAI, OpenAI-compatible proxies) keep the standard
|
||
OpenAI image request shape.
|
||
|
||
<Note>
|
||
Azure routing for the `openai` provider's image-generation path requires
|
||
OpenClaw 2026.4.22 or later. Earlier versions treat any custom
|
||
`openai.baseUrl` like the public OpenAI endpoint and fail against Azure image
|
||
deployments.
|
||
</Note>
|
||
|
||
### API version
|
||
|
||
Set `AZURE_OPENAI_API_VERSION` to pin a specific Azure preview or GA version
|
||
for the Azure image-generation path:
|
||
|
||
```bash
|
||
export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
|
||
```
|
||
|
||
The default is `2024-12-01-preview` when the variable is unset.
|
||
|
||
### Model names are deployment names
|
||
|
||
Azure OpenAI binds models to deployments. For Azure image-generation requests
|
||
routed through the bundled `openai` provider, the `model` field in OpenClaw
|
||
must be the **Azure deployment name** you configured in the Azure portal, not
|
||
the public OpenAI model id.
|
||
|
||
If you create a deployment called `gpt-image-2-prod` that serves `gpt-image-2`:
|
||
|
||
```
|
||
/tool image_generate model=openai/gpt-image-2-prod prompt="A clean poster" size=1024x1024 count=1
|
||
```
|
||
|
||
The same deployment-name rule applies to any image-generation call routed
|
||
through the bundled `openai` provider.
|
||
|
||
### Regional availability
|
||
|
||
Azure image generation is currently available only in a subset of regions
|
||
(for example `eastus2`, `swedencentral`, `polandcentral`, `westus3`,
|
||
`uaenorth`). Check Microsoft's current region list before creating a
|
||
deployment, and confirm the specific model is offered in your region.
|
||
|
||
### Parameter differences
|
||
|
||
Azure OpenAI and public OpenAI do not always accept the same image parameters.
|
||
Azure may reject options public OpenAI allows (for example certain
|
||
`background` values on `gpt-image-2`) or expose them only on specific model
|
||
versions. These differences come from Azure and the underlying model, not
|
||
OpenClaw. If an Azure request fails with a validation error, check the
|
||
parameter set supported by your specific deployment and API version in the
|
||
Azure portal.
|
||
|
||
<Note>
|
||
Azure OpenAI uses native transport and compat behavior but does not receive
|
||
OpenClaw's hidden attribution headers - see the **Native vs OpenAI-compatible
|
||
routes** accordion under [Advanced configuration](#advanced-configuration).
|
||
|
||
For chat or Responses traffic on Azure (beyond image generation), use the
|
||
onboarding flow or a dedicated Azure provider config; `openai.baseUrl` alone
|
||
does not pick up the Azure API/auth shape. A separate
|
||
`azure-openai-responses/*` provider exists; see the Server-side compaction
|
||
accordion below.
|
||
</Note>
|
||
|
||
## Advanced configuration
|
||
|
||
The `transport` and `serviceTier` examples below are authored embedded-provider
|
||
request settings, so an otherwise eligible `auto` route stays on OpenClaw
|
||
instead of selecting Codex implicitly. Valid `fastMode` / `fast_mode` values
|
||
and valid cutoff keys are typed agent-runtime controls and do not select a
|
||
runtime. Runtime-specific examples therefore pin `agentRuntime.id` explicitly.
|
||
The native Codex app-server harness owns its transport and request settings.
|
||
Authored embedded-provider settings can therefore select the declared OpenClaw
|
||
fallback even with explicit `agentRuntime.id: "codex"`; see
|
||
[Runtime selection](/concepts/agent-runtimes#runtime-selection).
|
||
|
||
<AccordionGroup>
|
||
<Accordion title="Transport (WebSocket vs SSE)">
|
||
Direct API-key requests use SSE by default. Set `params.transport` when you
|
||
want Responses WebSocket mode on an eligible official OpenAI endpoint.
|
||
|
||
| Value | Behavior |
|
||
| --------------------- | -------- |
|
||
| `"sse"` (default) | Stream each request over SSE |
|
||
| `"auto"` | Prefer a session-cached WebSocket, with pre-dispatch SSE fallback |
|
||
| `"websocket-cached"` | Explicitly use the session-cached WebSocket path, with the same pre-dispatch SSE fallback |
|
||
| `"websocket"` | Use a transient WebSocket for the request, with pre-dispatch SSE fallback |
|
||
|
||
Cached modes keep one eligible connection per session. When the prior
|
||
request and response still match the current history, OpenClaw sends only
|
||
the new input and references the prior response with
|
||
`previous_response_id`. Otherwise it sends full history without that
|
||
reference.
|
||
|
||
A setup or handshake failure before request dispatch falls back to SSE; it
|
||
is not retried or reconnected first. After dispatch, failures with an
|
||
unknown outcome remain replay-unsafe and fail closed. The explicit server
|
||
rejections `previous_response_not_found` and
|
||
`websocket_connection_limit_reached` are safe exceptions: OpenClaw closes
|
||
the failed socket and retries that turn once over SSE with full history and
|
||
no rejected `previous_response_id`.
|
||
|
||
```json5
|
||
{
|
||
agents: {
|
||
defaults: {
|
||
models: {
|
||
"openai/gpt-5.5": {
|
||
agentRuntime: { id: "openclaw" },
|
||
params: { transport: "auto" },
|
||
},
|
||
},
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
Related OpenAI docs:
|
||
- [Responses API WebSocket mode](https://developers.openai.com/api/docs/guides/websocket-mode)
|
||
- [Streaming API responses (SSE)](https://platform.openai.com/docs/guides/streaming-responses)
|
||
|
||
</Accordion>
|
||
|
||
<Accordion title="Fast mode">
|
||
OpenClaw exposes a shared fast-mode toggle for `openai/*`:
|
||
|
||
- **Chat/UI:** `/fast status|auto|on|off`
|
||
- **Config:** `agents.defaults.models["<provider>/<model>"].params.fastMode`
|
||
|
||
Valid `params.fastMode` / `params.fast_mode` values and valid cutoff keys
|
||
are typed runtime controls. They do not count as authored provider request
|
||
params and do not select OpenClaw or Codex. The example below pins embedded
|
||
OpenClaw because it describes a direct provider request.
|
||
|
||
When enabled on the embedded runtime, OpenClaw maps fast mode to OpenAI API
|
||
Fast mode (formerly Priority processing) and currently sends
|
||
`service_tier = "priority"`. Fast mode does not rewrite `reasoning` or
|
||
`text.verbosity`. `fastMode: "auto"` starts new model calls fast until the
|
||
auto cutoff, then starts later retry, fallback, tool-result, or continuation
|
||
calls without fast mode. The cutoff defaults to 60 seconds; set
|
||
`params.fastAutoOnSeconds` on the active model to change it.
|
||
|
||
```json5
|
||
{
|
||
agents: {
|
||
defaults: {
|
||
models: {
|
||
"openai/gpt-5.5": {
|
||
agentRuntime: { id: "openclaw" },
|
||
params: { fastMode: "auto", fastAutoOnSeconds: 30 },
|
||
},
|
||
},
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
<Note>
|
||
The full precedence is inline message, stored session, per-agent default,
|
||
global default, per-model `params.fastMode`, then off. `/fast default`
|
||
clears only the session layer. `/status` reports the resolved OpenClaw
|
||
policy and runtime, not the upstream service tier actually honored or
|
||
returned. See [Thinking levels](/tools/thinking#fast-mode-%2Ffast) and
|
||
[Codex harness](/plugins/codex-harness/commands#shared-fast-mode-and-codex-fast-mode).
|
||
</Note>
|
||
|
||
Fast mode is premium-priced and model-specific. GPT-5.6 Sol API Fast mode
|
||
currently costs 2× Standard token pricing, with long-context multipliers
|
||
stacking as described above. ChatGPT/Codex-credit Fast mode is a separate
|
||
billing system: GPT-5.6 and GPT-5.5 currently consume 2.5× Standard credits,
|
||
while API-key Codex runs use API token pricing. See
|
||
[Fast mode](https://openai.com/api-priority-processing/),
|
||
[API pricing](https://developers.openai.com/api/docs/pricing), and
|
||
[Codex speed](https://learn.chatgpt.com/docs/agent-configuration/speed).
|
||
|
||
</Accordion>
|
||
|
||
<Accordion title="OpenAI API Fast mode with service_tier">
|
||
OpenAI now calls this API product Fast mode; it was formerly Priority
|
||
processing. OpenClaw currently sends the wire value
|
||
`service_tier = "priority"`. Set an explicit tier per
|
||
model on the embedded OpenClaw runtime:
|
||
|
||
```json5
|
||
{
|
||
agents: {
|
||
defaults: {
|
||
models: {
|
||
"openai/gpt-5.5": {
|
||
agentRuntime: { id: "openclaw" },
|
||
params: { serviceTier: "priority" },
|
||
},
|
||
},
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
Supported values: `auto`, `default`, `flex`, `priority`.
|
||
|
||
<Warning>
|
||
`params.serviceTier` is an authored embedded-provider setting, not native
|
||
Codex app-server configuration. It is forwarded only by the embedded
|
||
runtime to native OpenAI endpoints (`api.openai.com`) and native ChatGPT
|
||
endpoints (`chatgpt.com/backend-api`). If you route either provider through
|
||
a proxy, OpenClaw leaves `service_tier` untouched. Configure the native
|
||
harness separately with `plugins.entries.codex.config.appServer.serviceTier`;
|
||
the shared Fast-mode run control can supersede that value.
|
||
</Warning>
|
||
|
||
</Accordion>
|
||
|
||
<Accordion title="Server-side compaction (Responses API)">
|
||
For store-capable direct OpenAI Responses models (`openai/*` resolved to
|
||
`api.openai.com`), the OpenAI plugin's OpenClaw stream wrapper auto-enables
|
||
server-side compaction:
|
||
|
||
- 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)
|
||
|
||
The same resolved route and effective threshold gate the client preflight,
|
||
so OpenClaw does not delay local compaction unless the transport will inject
|
||
`context_management`. ChatGPT OAuth, custom proxies, and routes with
|
||
`compat.supportsStore: false` are not store-capable and therefore ignore
|
||
these server-compaction controls. This applies to the built-in OpenClaw
|
||
runtime path and to OpenAI provider hooks used by embedded runs. The native
|
||
Codex app-server harness manages its own context through Codex and is not
|
||
affected by this setting.
|
||
|
||
OpenAI emits the compacted state as an encrypted `compaction` output item.
|
||
Keep that item opaque. For stateless continuation, carry the newest item
|
||
forward and drop the earlier input prefix it replaces. OpenClaw does this
|
||
automatically: it persists and replays the item only for the matching
|
||
route, session, and auth identity, preserves it across worker transcript
|
||
commits, and filters it from user-visible history and diagnostics. Never
|
||
display or log the encrypted content.
|
||
|
||
<Tabs>
|
||
<Tab title="Enable explicitly">
|
||
Useful for store-capable endpoints like Azure OpenAI Responses. Setting
|
||
this to `true` does not override endpoint or `supportsStore` capability:
|
||
|
||
```json5
|
||
{
|
||
agents: {
|
||
defaults: {
|
||
models: {
|
||
"azure-openai-responses/gpt-5.5": {
|
||
params: { responsesServerCompaction: true },
|
||
},
|
||
},
|
||
},
|
||
},
|
||
}
|
||
```
|
||
</Tab>
|
||
<Tab title="Custom threshold">
|
||
```json5
|
||
{
|
||
agents: {
|
||
defaults: {
|
||
models: {
|
||
"openai/gpt-5.5": {
|
||
params: {
|
||
responsesServerCompaction: true,
|
||
responsesCompactThreshold: 120000,
|
||
},
|
||
},
|
||
},
|
||
},
|
||
},
|
||
}
|
||
```
|
||
</Tab>
|
||
<Tab title="Disable">
|
||
```json5
|
||
{
|
||
agents: {
|
||
defaults: {
|
||
models: {
|
||
"openai/gpt-5.5": {
|
||
params: { responsesServerCompaction: false },
|
||
},
|
||
},
|
||
},
|
||
},
|
||
}
|
||
```
|
||
</Tab>
|
||
</Tabs>
|
||
|
||
<Note>
|
||
`responsesServerCompaction` only controls `context_management` injection.
|
||
Direct OpenAI Responses models still force `store: true` unless compat
|
||
sets `supportsStore: false`.
|
||
</Note>
|
||
|
||
</Accordion>
|
||
|
||
<Accordion title="Strict-agentic GPT mode">
|
||
For `openai` provider GPT-5-family models run through OpenClaw's embedded
|
||
runtime, OpenClaw already defaults to a stricter execution contract called
|
||
`strict-agentic`. It auto-activates whenever the resolved provider is
|
||
`openai` and the model id matches the GPT-5 family, unless config
|
||
explicitly opts back out:
|
||
|
||
```json5
|
||
{
|
||
agents: {
|
||
defaults: {
|
||
embeddedAgent: { executionContract: "default" },
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
Setting `"strict-agentic"` explicitly is a no-op on a supported lane (it
|
||
is already the default) and inert on unsupported provider/model pairs.
|
||
|
||
With `strict-agentic` active, OpenClaw:
|
||
- Makes `progress_card` available for substantial work unless `tools.updatePlan` disables it
|
||
- Retries structurally empty or reasoning-only turns with a visible-answer
|
||
continuation
|
||
- Uses explicit harness plan events when the selected harness provides
|
||
them
|
||
|
||
OpenClaw does not classify assistant prose to decide whether a turn is a
|
||
plan, progress update, or final answer.
|
||
|
||
<Note>
|
||
This contract lives entirely in OpenClaw's embedded agent runner. It does
|
||
not apply to the native Codex app-server harness, which manages its own
|
||
turn and plan behavior; the harness selection matters more than the
|
||
execution-contract setting for native Codex runs.
|
||
</Note>
|
||
|
||
</Accordion>
|
||
|
||
<Accordion title="Native vs OpenAI-compatible routes">
|
||
OpenClaw treats direct OpenAI, Codex, and Azure OpenAI endpoints
|
||
differently from generic OpenAI-compatible `/v1` proxies:
|
||
|
||
**Native routes** (`openai/*`, Azure OpenAI):
|
||
- Keep `reasoning: { effort: "none" }` only for models that support the
|
||
OpenAI `none` effort
|
||
- Omit disabled reasoning for models or proxies that reject
|
||
`reasoning.effort: "none"`
|
||
- Default tool schemas to strict mode
|
||
- Attach hidden attribution headers on verified native hosts only (Azure
|
||
OpenAI does not get these headers, even though it is a native route)
|
||
- Keep OpenAI-only request shaping (`service_tier`, `store`,
|
||
reasoning-compat, prompt-cache hints)
|
||
|
||
**Proxy/compatible routes:**
|
||
- Use looser compat behavior
|
||
- Strip Completions `store` from non-native `openai-completions` payloads
|
||
- Accept advanced `params.extra_body`/`params.extraBody` pass-through JSON
|
||
for OpenAI-compatible Completions proxies
|
||
- Accept `params.chat_template_kwargs` for OpenAI-compatible Completions
|
||
proxies such as vLLM
|
||
- Do not force strict tool schemas or native-only headers
|
||
|
||
If a usable tool schema is incompatible with requested strict mode, the request uses
|
||
`strict: false`. Debug logs report the downgrade under `openai-transport`,
|
||
with a bounded sample of incompatible tools. Built-in and managed Responses
|
||
requests share duplicate suppression for the same model and schemas.
|
||
|
||
</Accordion>
|
||
</AccordionGroup>
|
||
|
||
## Related
|
||
|
||
<CardGroup cols={2}>
|
||
<Card title="Model selection" href="/concepts/model-providers" icon="layers">
|
||
Choosing providers, model refs, and failover behavior.
|
||
</Card>
|
||
<Card title="Image generation" href="/tools/image-generation" icon="image">
|
||
Shared image tool parameters and provider selection.
|
||
</Card>
|
||
<Card title="Video generation" href="/tools/video-generation" icon="video">
|
||
Shared video tool parameters and provider selection.
|
||
</Card>
|
||
<Card title="OAuth and auth" href="/gateway/authentication" icon="key">
|
||
Auth details and credential reuse rules.
|
||
</Card>
|
||
</CardGroup>
|