From a8173276bf1b48d97f0c08508bdf0002e0065d2b Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Thu, 23 Apr 2026 20:38:45 +0100 Subject: [PATCH] docs(openai): canonicalize GPT model refs --- docs/cli/config.md | 4 +- docs/concepts/model-providers.md | 15 ++-- docs/concepts/models.md | 2 +- docs/gateway/configuration-reference.md | 4 +- docs/help/faq.md | 38 +++++----- docs/help/testing.md | 12 ++-- docs/plugins/codex-harness.md | 69 +++++++++---------- docs/plugins/sdk-agent-harness.md | 28 ++++---- docs/providers/openai.md | 34 +++++---- docs/reference/wizard.md | 4 +- docs/start/wizard-cli-reference.md | 4 +- docs/tools/llm-task.md | 2 +- .../models/codex-harness-no-meta-leak.md | 2 +- .../medium-game-plan-codex-harness.md | 4 +- 14 files changed, 104 insertions(+), 118 deletions(-) diff --git a/docs/cli/config.md b/docs/cli/config.md index 47ff5f4ecf3..6ac53055a3d 100644 --- a/docs/cli/config.md +++ b/docs/cli/config.md @@ -38,7 +38,7 @@ openclaw config get browser.executablePath openclaw config set browser.executablePath "/usr/bin/google-chrome" openclaw config set agents.defaults.heartbeat.every "2h" openclaw config set agents.list[0].tools.exec.node "node-id-or-name" -openclaw config set agents.defaults.models '{"openai-codex/gpt-5.5":{}}' --strict-json --merge +openclaw config set agents.defaults.models '{"openai/gpt-5.5":{}}' --strict-json --merge openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN openclaw config set secrets.providers.vaultfile --provider-source file --provider-path /etc/openclaw/secrets.json --provider-mode json openclaw config unset plugins.entries.brave.config.webSearch.apiKey @@ -115,7 +115,7 @@ you pass `--replace`. Use `--merge` when adding entries to those maps: ```bash -openclaw config set agents.defaults.models '{"openai-codex/gpt-5.5":{}}' --strict-json --merge +openclaw config set agents.defaults.models '{"openai/gpt-5.5":{}}' --strict-json --merge openclaw config set models.providers.ollama.models '[{"id":"llama3.2","name":"Llama 3.2"}]' --strict-json --merge ``` diff --git a/docs/concepts/model-providers.md b/docs/concepts/model-providers.md index d6eaeea957d..9fc9025d25c 100644 --- a/docs/concepts/model-providers.md +++ b/docs/concepts/model-providers.md @@ -18,7 +18,7 @@ For model selection rules, see [/concepts/models](/concepts/models). - CLI helpers: `openclaw onboard`, `openclaw models list`, `openclaw models set `. - `models.providers.*.models[].contextWindow` is native model metadata; `contextTokens` is the effective runtime cap. - Fallback rules, cooldown probes, and session-override persistence: [Model failover](/concepts/model-failover). -- Bundled `codex` is paired with the Codex agent harness — use `codex/gpt-*` for Codex-owned login, discovery, native thread resume, and app-server execution. Plain `openai/gpt-*` uses the OpenAI provider and normal transport. Disable automatic PI fallback for Codex-only deployments via `agents.defaults.embeddedHarness.fallback: "none"` — see [Codex harness](/plugins/codex-harness). +- OpenAI GPT model refs are canonical as `openai/`. Legacy `openai-codex/` and `codex/` refs remain compatibility aliases for older configs and tests. For native Codex app-server execution, keep the model ref as `openai/gpt-*` and force `agents.defaults.embeddedHarness.runtime: "codex"` — see [Codex harness](/plugins/codex-harness). ## Plugin-owned provider behavior @@ -95,26 +95,27 @@ OpenClaw ships with the pi‑ai catalog. These providers require **no** } ``` -### OpenAI Code (Codex) +### OpenAI Codex OAuth - Provider: `openai-codex` - Auth: OAuth (ChatGPT) -- Example model: `openai-codex/gpt-5.5` +- Canonical model ref: `openai/gpt-5.5` +- Legacy model refs: `openai-codex/gpt-*`, `codex/gpt-*` - CLI: `openclaw onboard --auth-choice openai-codex` or `openclaw models auth login --provider openai-codex` - Default transport is `auto` (WebSocket-first, SSE fallback) -- Override per model via `agents.defaults.models["openai-codex/"].params.transport` (`"sse"`, `"websocket"`, or `"auto"`) +- Override per model via `agents.defaults.models["openai/"].params.transport` (`"sse"`, `"websocket"`, or `"auto"`) - `params.serviceTier` is also forwarded on native Codex Responses requests (`chatgpt.com/backend-api`) - Hidden OpenClaw attribution headers (`originator`, `version`, `User-Agent`) are only attached on native Codex traffic to `chatgpt.com/backend-api`, not generic OpenAI-compatible proxies - Shares the same `/fast` toggle and `params.fastMode` config as direct `openai/*`; OpenClaw maps that to `service_tier=priority` -- `openai-codex/gpt-5.3-codex-spark` remains available when the Codex OAuth catalog exposes it; entitlement-dependent -- `openai-codex/gpt-5.5` keeps native `contextWindow = 1000000` and a default runtime `contextTokens = 272000`; override the runtime cap with `models.providers.openai-codex.models[].contextTokens` +- `openai/gpt-5.3-codex-spark` remains available through Codex OAuth when the catalog exposes it; entitlement-dependent +- `openai/gpt-5.5` keeps native `contextWindow = 1000000` and a default runtime `contextTokens = 272000`; override the runtime cap with `models.providers.openai-codex.models[].contextTokens` - Policy note: OpenAI Codex OAuth is explicitly supported for external tools/workflows like OpenClaw. ```json5 { - agents: { defaults: { model: { primary: "openai-codex/gpt-5.5" } } }, + agents: { defaults: { model: { primary: "openai/gpt-5.5" } } }, } ``` diff --git a/docs/concepts/models.md b/docs/concepts/models.md index 424a4179144..5aef6f3b3e1 100644 --- a/docs/concepts/models.md +++ b/docs/concepts/models.md @@ -72,7 +72,7 @@ Provider configuration examples (including OpenCode) live in Use additive writes when updating `agents.defaults.models` by hand: ```bash -openclaw config set agents.defaults.models '{"openai-codex/gpt-5.5":{}}' --strict-json --merge +openclaw config set agents.defaults.models '{"openai/gpt-5.5":{}}' --strict-json --merge ``` `openclaw config set` protects model/provider maps from accidental clobbers. A diff --git a/docs/gateway/configuration-reference.md b/docs/gateway/configuration-reference.md index 4204e90aad0..a89cc00010c 100644 --- a/docs/gateway/configuration-reference.md +++ b/docs/gateway/configuration-reference.md @@ -1257,7 +1257,7 @@ Codex app-server harness. { agents: { defaults: { - model: "codex/gpt-5.5", + model: "openai/gpt-5.5", embeddedHarness: { runtime: "codex", fallback: "none", @@ -1270,7 +1270,7 @@ Codex app-server harness. - `runtime`: `"auto"`, `"pi"`, or a registered plugin harness id. The bundled Codex plugin registers `codex`. - `fallback`: `"pi"` or `"none"`. `"pi"` keeps the built-in PI harness as the compatibility fallback when no plugin harness is selected. `"none"` makes missing or unsupported plugin harness selection fail instead of silently using PI. Selected plugin harness failures always surface directly. - Environment overrides: `OPENCLAW_AGENT_RUNTIME=` overrides `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=none` disables PI fallback for that process. -- For Codex-only deployments, set `model: "codex/gpt-5.5"`, `embeddedHarness.runtime: "codex"`, and `embeddedHarness.fallback: "none"`. +- For Codex-only deployments, set `model: "openai/gpt-5.5"`, `embeddedHarness.runtime: "codex"`, and `embeddedHarness.fallback: "none"`. - Harness choice is pinned per session id after the first embedded run. Config/env changes affect new or reset sessions, not an existing transcript. Legacy sessions with transcript history but no recorded pin are treated as PI-pinned. `/status` shows non-PI harness ids such as `codex` next to `Fast`. - This only controls the embedded chat harness. Media generation, vision, PDF, music, video, and TTS still use their provider/model settings. diff --git a/docs/help/faq.md b/docs/help/faq.md index 41c33db234a..c11388d7afc 100644 --- a/docs/help/faq.md +++ b/docs/help/faq.md @@ -658,26 +658,27 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, - OpenClaw supports **OpenAI Code (Codex)** via OAuth (ChatGPT sign-in). Onboarding can run the OAuth flow and will set the default model to `openai-codex/gpt-5.5` when appropriate. See [Model providers](/concepts/model-providers) and [Onboarding (CLI)](/start/wizard). + OpenClaw supports **OpenAI Code (Codex)** via OAuth (ChatGPT sign-in). New model refs should use the canonical `openai/gpt-5.5` path; `openai-codex/gpt-*` remains a legacy compatibility alias. See [Model providers](/concepts/model-providers) and [Onboarding (CLI)](/start/wizard). - - OpenClaw treats the two routes separately: + + `openai-codex` is still the internal auth/profile provider id for ChatGPT/Codex OAuth. The model ref should be canonical OpenAI: - - `openai-codex/gpt-5.5` = ChatGPT/Codex OAuth - - `openai/gpt-5.5` = direct OpenAI Platform API + - `openai/gpt-5.5` = canonical GPT-5.5 model ref + - `openai-codex/gpt-5.5` = legacy compatibility alias + - `openai-codex:...` = auth profile id, not a model ref - In OpenClaw, ChatGPT/Codex sign-in is wired to the `openai-codex/*` route, - not the direct `openai/*` route. If you want the direct API path in - OpenClaw, set `OPENAI_API_KEY` (or the equivalent OpenAI provider config). - If you want ChatGPT/Codex sign-in in OpenClaw, use `openai-codex/*`. + If you want the direct OpenAI Platform billing/limit path, set + `OPENAI_API_KEY`. If you want ChatGPT/Codex subscription auth, sign in with + `openclaw models auth login --provider openai-codex` and keep model refs on + `openai/*` in new configs. - `openai-codex/*` uses the Codex OAuth route, and its usable quota windows are - OpenAI-managed and plan-dependent. In practice, those limits can differ from - the ChatGPT website/app experience, even when both are tied to the same account. + Codex OAuth uses OpenAI-managed, plan-dependent quota windows. In practice, + those limits can differ from the ChatGPT website/app experience, even when + both are tied to the same account. OpenClaw can show the currently visible provider usage/quota windows in `openclaw models status`, but it does not invent or normalize ChatGPT-web @@ -2344,8 +2345,8 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, Yes. Set one as default and switch as needed: - - **Quick switch (per session):** `/model gpt-5.5` for daily tasks, `/model openai-codex/gpt-5.5` for coding with Codex OAuth. - - **Default + switch:** set `agents.defaults.model.primary` to `openai/gpt-5.5`, then switch to `openai-codex/gpt-5.5` when coding (or the other way around). + - **Quick switch (per session):** `/model gpt-5.5` for daily tasks, or keep the same model and switch auth/profile as needed. + - **Default:** set `agents.defaults.model.primary` to `openai/gpt-5.5`. - **Sub-agents:** route coding tasks to sub-agents with a different default model. See [Models](/concepts/models) and [Slash commands](/tools/slash-commands). @@ -2355,9 +2356,9 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, Use either a session toggle or a config default: - - **Per session:** send `/fast on` while the session is using `openai/gpt-5.5` or `openai-codex/gpt-5.5`. + - **Per session:** send `/fast on` while the session is using `openai/gpt-5.5`. - **Per model default:** set `agents.defaults.models["openai/gpt-5.5"].params.fastMode` to `true`. - - **Codex OAuth too:** if you also use `openai-codex/gpt-5.5`, set the same flag there. + - **Legacy aliases:** older `openai-codex/gpt-*` entries can keep their own params, but new configs should put params on `openai/gpt-*`. Example: @@ -2371,11 +2372,6 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, fastMode: true, }, }, - "openai-codex/gpt-5.5": { - params: { - fastMode: true, - }, - }, }, }, }, diff --git a/docs/help/testing.md b/docs/help/testing.md index 0a0171eda92..32818e20239 100644 --- a/docs/help/testing.md +++ b/docs/help/testing.md @@ -681,7 +681,7 @@ Docker notes: `agent` method: - load the bundled `codex` plugin - select `OPENCLAW_AGENT_RUNTIME=codex` - - send a first gateway agent turn to `codex/gpt-5.5` + - send a first gateway agent turn to `openai/gpt-5.5` with the Codex harness forced - send a second turn to the same OpenClaw session and verify the app-server thread can resume - run `/codex status` and `/codex models` through the same gateway command @@ -691,7 +691,7 @@ Docker notes: denied so the agent asks back - Test: `src/gateway/gateway-codex-harness.live.test.ts` - Enable: `OPENCLAW_LIVE_CODEX_HARNESS=1` -- Default model: `codex/gpt-5.5` +- Default model: `openai/gpt-5.5` - Optional image probe: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` - Optional MCP/tool probe: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` - Optional Guardian probe: `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1` @@ -708,7 +708,7 @@ OPENCLAW_LIVE_CODEX_HARNESS=1 \ OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1 \ OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1 \ OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1 \ - OPENCLAW_LIVE_CODEX_HARNESS_MODEL=codex/gpt-5.5 \ + OPENCLAW_LIVE_CODEX_HARNESS_MODEL=openai/gpt-5.5 \ pnpm test:live -- src/gateway/gateway-codex-harness.live.test.ts ``` @@ -731,7 +731,7 @@ Docker notes: `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0` when you need a narrower debug run. - Docker also exports `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, matching the live - test config so `openai-codex/*` or PI fallback cannot hide a Codex harness + test config so legacy aliases or PI fallback cannot hide a Codex harness regression. ### Recommended live recipes @@ -769,7 +769,7 @@ There is no fixed “CI model list” (live is opt-in), but these are the **reco This is the “common models” run we expect to keep working: - OpenAI (non-Codex): `openai/gpt-5.5` (optional: `openai/gpt-5.4-mini`) -- OpenAI Codex: `openai-codex/gpt-5.5` +- OpenAI Codex OAuth: `openai/gpt-5.5` (`openai-codex/gpt-*` remains a legacy alias) - Anthropic: `anthropic/claude-opus-4-6` (or `anthropic/claude-sonnet-4-6`) - Google (Gemini API): `google/gemini-3.1-pro-preview` and `google/gemini-3-flash-preview` (avoid older Gemini 2.x models) - Google (Antigravity): `google-antigravity/claude-opus-4-6-thinking` and `google-antigravity/gemini-3-flash` @@ -777,7 +777,7 @@ This is the “common models” run we expect to keep working: - MiniMax: `minimax/MiniMax-M2.7` Run gateway smoke with tools + image: -`OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.5,openai-codex/gpt-5.5,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` +`OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.5,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` ### Baseline: tool calling (Read + optional Exec) diff --git a/docs/plugins/codex-harness.md b/docs/plugins/codex-harness.md index d59dfeb3092..ed5c1bb37aa 100644 --- a/docs/plugins/codex-harness.md +++ b/docs/plugins/codex-harness.md @@ -31,25 +31,23 @@ aligned with the PI harness: Bundled plugins can also register a Codex app-server extension factory to add async `tool_result` middleware. -The harness is off by default. It is selected only when the `codex` plugin is -enabled and the resolved model is a `codex/*` model, or when you explicitly -force `embeddedHarness.runtime: "codex"` or `OPENCLAW_AGENT_RUNTIME=codex`. -If you never configure `codex/*`, existing PI, OpenAI, Anthropic, Gemini, local, -and custom-provider runs keep their current behavior. +The harness is off by default. New configs should keep OpenAI model refs +canonical as `openai/gpt-*` and explicitly force +`embeddedHarness.runtime: "codex"` or `OPENCLAW_AGENT_RUNTIME=codex` when they +want native app-server execution. Legacy `codex/*` model refs still auto-select +the harness for compatibility. ## Pick the right model prefix -OpenClaw has separate routes for OpenAI and Codex-shaped access: +OpenClaw now keeps OpenAI GPT model refs canonical as `openai/*`: -| Model ref | Runtime path | Use when | -| ---------------------- | -------------------------------------------- | ----------------------------------------------------------------------- | -| `openai/gpt-5.5` | OpenAI provider through OpenClaw/PI plumbing | You want direct OpenAI Platform API access with `OPENAI_API_KEY`. | -| `openai-codex/gpt-5.5` | OpenAI Codex OAuth provider through PI | You want ChatGPT/Codex OAuth without the Codex app-server harness. | -| `codex/gpt-5.5` | Bundled Codex provider plus Codex harness | You want native Codex app-server execution for the embedded agent turn. | +| Model ref | Runtime path | Use when | +| ----------------------------------------------------- | -------------------------------------------- | ----------------------------------------------------------------------- | +| `openai/gpt-5.5` | OpenAI provider through OpenClaw/PI plumbing | You want direct OpenAI Platform API access with `OPENAI_API_KEY`. | +| `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | Codex app-server harness | You want native Codex app-server execution for the embedded agent turn. | -The Codex harness only claims `codex/*` model refs. Existing `openai/*`, -`openai-codex/*`, Anthropic, Gemini, xAI, local, and custom provider refs keep -their normal paths. +Legacy `openai-codex/gpt-*` and `codex/gpt-*` refs remain accepted as +compatibility aliases, but new docs/config examples should use `openai/gpt-*`. Harness selection is not a live session control. When an embedded turn runs, OpenClaw records the selected harness id on that session and keeps using it for @@ -82,7 +80,7 @@ uses. ## Minimal config -Use `codex/gpt-5.5`, enable the bundled plugin, and force the `codex` harness: +Use `openai/gpt-5.5`, enable the bundled plugin, and force the `codex` harness: ```json5 { @@ -95,7 +93,7 @@ Use `codex/gpt-5.5`, enable the bundled plugin, and force the `codex` harness: }, agents: { defaults: { - model: "codex/gpt-5.5", + model: "openai/gpt-5.5", embeddedHarness: { runtime: "codex", fallback: "none", @@ -120,14 +118,15 @@ If your config uses `plugins.allow`, include `codex` there too: } ``` -Setting `agents.defaults.model` or an agent model to `codex/` also -auto-enables the bundled `codex` plugin. The explicit plugin entry is still -useful in shared configs because it makes the deployment intent obvious. +Legacy configs that set `agents.defaults.model` or an agent model to +`codex/` still auto-enable the bundled `codex` plugin. New configs should +prefer `openai/` plus the explicit `embeddedHarness` entry above. ## Add Codex without replacing other models -Keep `runtime: "auto"` when you want Codex for `codex/*` models and PI for -everything else: +Keep `runtime: "auto"` when you want legacy `codex/*` refs to select Codex and +PI for everything else. For new configs, prefer explicit `runtime: "codex"` on +the agents that should use the harness. ```json5 { @@ -141,17 +140,15 @@ everything else: agents: { defaults: { model: { - primary: "codex/gpt-5.5", + primary: "openai/gpt-5.5", fallbacks: ["openai/gpt-5.5", "anthropic/claude-opus-4-6"], }, models: { - "codex/gpt-5.5": { alias: "codex" }, - "codex/gpt-5.4-mini": { alias: "codex-mini" }, "openai/gpt-5.5": { alias: "gpt" }, "anthropic/claude-opus-4-6": { alias: "opus" }, }, embeddedHarness: { - runtime: "auto", + runtime: "codex", fallback: "pi", }, }, @@ -161,8 +158,7 @@ everything else: With this shape: -- `/model codex` or `/model codex/gpt-5.5` uses the Codex app-server harness. -- `/model gpt` or `/model openai/gpt-5.5` uses the OpenAI provider path. +- `/model gpt` or `/model openai/gpt-5.5` uses the Codex app-server harness for this config. - `/model opus` uses the Anthropic provider path. - If a non-Codex model is selected, PI remains the compatibility harness. @@ -175,7 +171,7 @@ the Codex harness: { agents: { defaults: { - model: "codex/gpt-5.5", + model: "openai/gpt-5.5", embeddedHarness: { runtime: "codex", fallback: "none", @@ -194,8 +190,7 @@ openclaw gateway run ``` With fallback disabled, OpenClaw fails early if the Codex plugin is disabled, -the requested model is not a `codex/*` ref, the app-server is too old, or the -app-server cannot start. +the app-server is too old, or the app-server cannot start. ## Per-agent Codex @@ -220,7 +215,7 @@ auto-selection: { id: "codex", name: "Codex", - model: "codex/gpt-5.5", + model: "openai/gpt-5.5", embeddedHarness: { runtime: "codex", fallback: "none", @@ -239,11 +234,11 @@ and lets the next turn resolve the harness from current config again. ## Model discovery By default, the Codex plugin asks the app-server for available models. If -discovery fails or times out, it uses the bundled fallback catalog: +discovery fails or times out, it uses a bundled fallback catalog for: -- `codex/gpt-5.5` -- `codex/gpt-5.4-mini` -- `codex/gpt-5.2` +- GPT-5.5 +- GPT-5.4 mini +- GPT-5.2 You can tune discovery under `plugins.entries.codex.config.discovery`: @@ -458,8 +453,8 @@ Remote app-server with explicit headers: Model switching stays OpenClaw-controlled. When an OpenClaw session is attached to an existing Codex thread, the next turn sends the currently selected -`codex/*` model, provider, approval policy, sandbox, and service tier to -app-server again. Switching from `codex/gpt-5.5` to `codex/gpt-5.2` keeps the +OpenAI model, provider, approval policy, sandbox, and service tier to +app-server again. Switching from `openai/gpt-5.5` to `openai/gpt-5.2` keeps the thread binding but asks Codex to continue with the newly selected model. ## Codex command diff --git a/docs/plugins/sdk-agent-harness.md b/docs/plugins/sdk-agent-harness.md index 176eeaf0ea3..bf772d551f2 100644 --- a/docs/plugins/sdk-agent-harness.md +++ b/docs/plugins/sdk-agent-harness.md @@ -122,19 +122,19 @@ OpenClaw. The harness then claims that provider in `supports(...)`. The bundled Codex plugin follows this pattern: - provider id: `codex` -- user model refs: `codex/gpt-5.5`, `codex/gpt-5.2`, or another model returned - by the Codex app server +- user model refs: canonical `openai/gpt-5.5` plus + `embeddedHarness.runtime: "codex"`; legacy `codex/gpt-*` refs remain accepted + for compatibility - harness id: `codex` - auth: synthetic provider availability, because the Codex harness owns the native Codex login/session - app-server request: OpenClaw sends the bare model id to Codex and lets the harness talk to the native app-server protocol -The Codex plugin is additive. Plain `openai/gpt-*` refs remain OpenAI provider -refs and continue to use the normal OpenClaw provider path. Select `codex/gpt-*` -when you want Codex-managed auth, Codex model discovery, native threads, and -Codex app-server execution. `/model` can switch among the Codex models returned -by the Codex app server without requiring OpenAI provider credentials. +The Codex plugin is additive. Plain `openai/gpt-*` refs continue to use the +normal OpenClaw provider path unless you force the Codex harness with +`embeddedHarness.runtime: "codex"`. Older `codex/gpt-*` refs still select the +Codex provider and harness for compatibility. For operator setup, model prefix examples, and Codex-only configs, see [Codex Harness](/plugins/codex-harness). @@ -156,13 +156,9 @@ into the OpenClaw transcript. The bundled `codex` harness is the native Codex mode for embedded OpenClaw agent turns. Enable the bundled `codex` plugin first, and include `codex` in -`plugins.allow` if your config uses a restrictive allowlist. It is different -from `openai-codex/*`: - -- `openai-codex/*` uses ChatGPT/Codex OAuth through the normal OpenClaw provider - path. -- `codex/*` uses the bundled Codex provider and routes the turn through Codex - app-server. +`plugins.allow` if your config uses a restrictive allowlist. New configs should +use `openai/gpt-*` with `embeddedHarness.runtime: "codex"`. Legacy +`openai-codex/*` and `codex/*` model refs remain compatibility aliases. When this mode runs, Codex owns the native thread id, resume behavior, compaction, and app-server execution. OpenClaw still owns the chat channel, @@ -189,7 +185,7 @@ For Codex-only embedded runs: { "agents": { "defaults": { - "model": "codex/gpt-5.5", + "model": "openai/gpt-5.5", "embeddedHarness": { "runtime": "codex", "fallback": "none" @@ -230,7 +226,7 @@ Per-agent overrides use the same shape: "list": [ { "id": "codex-only", - "model": "codex/gpt-5.5", + "model": "openai/gpt-5.5", "embeddedHarness": { "runtime": "codex", "fallback": "none" diff --git a/docs/providers/openai.md b/docs/providers/openai.md index 8d73087d156..aab7b462292 100644 --- a/docs/providers/openai.md +++ b/docs/providers/openai.md @@ -9,10 +9,10 @@ title: "OpenAI" # OpenAI -OpenAI provides developer APIs for GPT models. OpenClaw supports two auth routes: +OpenAI provides developer APIs for GPT models. OpenClaw supports two auth routes behind the same canonical OpenAI model refs: - **API key** — direct OpenAI Platform access with usage-based billing (`openai/*` models) -- **Codex subscription** — ChatGPT/Codex sign-in with subscription access (`openai-codex/*` models) +- **Codex subscription** — ChatGPT/Codex sign-in with subscription access. The internal auth/provider id is `openai-codex`, but new model refs should still use `openai/*`. OpenAI explicitly supports subscription OAuth usage in external tools and workflows like OpenClaw. @@ -21,7 +21,7 @@ OpenAI explicitly supports subscription OAuth usage in external tools and workfl | OpenAI capability | OpenClaw surface | Status | | ------------------------- | ----------------------------------------- | ------------------------------------------------------ | | Chat / Responses | `openai/` model provider | Yes | -| Codex subscription models | `openai-codex/` model provider | Yes | +| Codex subscription models | `openai/` with `openai-codex` auth | Yes | | Server-side web search | Native OpenAI Responses tool | Yes, when web search is enabled and no provider pinned | | Images | `image_generate` | Yes | | Videos | `video_generate` | Yes | @@ -69,7 +69,7 @@ Choose your preferred auth method and follow the setup steps. | `openai/gpt-5.5-pro` | Direct OpenAI Platform API | `OPENAI_API_KEY` | - ChatGPT/Codex sign-in is routed through `openai-codex/*`, not `openai/*`. + `openai-codex/*` remains accepted as a legacy compatibility alias, but new configs should use `openai/*`. ### Config example @@ -110,7 +110,7 @@ Choose your preferred auth method and follow the setup steps. ```bash - openclaw config set agents.defaults.model.primary openai-codex/gpt-5.5 + openclaw config set agents.defaults.model.primary openai/gpt-5.5 ``` @@ -124,18 +124,18 @@ Choose your preferred auth method and follow the setup steps. | Model ref | Route | Auth | |-----------|-------|------| - | `openai-codex/gpt-5.5` | ChatGPT/Codex OAuth | Codex sign-in | - | `openai-codex/gpt-5.3-codex-spark` | ChatGPT/Codex OAuth | Codex sign-in (entitlement-dependent) | + | `openai/gpt-5.5` | ChatGPT/Codex OAuth | Codex sign-in | + | `openai/gpt-5.3-codex-spark` | ChatGPT/Codex OAuth | Codex sign-in (entitlement-dependent) | - This route is intentionally separate from `openai/gpt-5.5`. Use `openai/*` with an API key for direct Platform access, and `openai-codex/*` for Codex subscription access. + `openai-codex/*` and `codex/*` model refs are legacy compatibility aliases. Keep using the `openai-codex` provider id for auth/profile commands. ### Config example ```json5 { - agents: { defaults: { model: { primary: "openai-codex/gpt-5.5" } } }, + agents: { defaults: { model: { primary: "openai/gpt-5.5" } } }, } ``` @@ -147,7 +147,7 @@ Choose your preferred auth method and follow the setup steps. OpenClaw treats model metadata and the runtime context cap as separate values. - For `openai-codex/gpt-5.5`: + For `openai/gpt-5.5` through Codex OAuth: - Native `contextWindow`: `1000000` - Default runtime `contextTokens` cap: `272000` @@ -243,9 +243,9 @@ See [Video Generation](/tools/video-generation) for shared tool parameters, prov ## GPT-5 prompt contribution -OpenClaw adds a shared GPT-5 prompt contribution for GPT-5-family runs across providers. It applies by model id, so `openai/gpt-5.5`, `openai-codex/gpt-5.5`, `openrouter/openai/gpt-5.5`, `opencode/gpt-5.5`, and other compatible GPT-5 refs receive the same overlay. Older GPT-4.x models do not. +OpenClaw adds a shared GPT-5 prompt contribution for GPT-5-family runs across providers. It applies by model id, so `openai/gpt-5.5`, `openrouter/openai/gpt-5.5`, `opencode/gpt-5.5`, and other compatible GPT-5 refs receive the same overlay. Older GPT-4.x models do not. -The bundled native Codex harness provider (`codex/*`) uses the same GPT-5 behavior and heartbeat overlay through Codex app-server developer instructions, so `codex/gpt-5.x` sessions keep the same follow-through and proactive heartbeat guidance even though Codex owns the rest of the harness prompt. +The bundled native Codex harness uses the same GPT-5 behavior and heartbeat overlay through Codex app-server developer instructions, so `openai/gpt-5.x` sessions forced through `embeddedHarness.runtime: "codex"` keep the same follow-through and proactive heartbeat guidance even though Codex owns the rest of the harness prompt. The GPT-5 contribution adds a tagged behavior contract for persona persistence, execution safety, tool discipline, output shape, completion checks, and verification. Channel-specific reply and silent-message behavior stays in the shared OpenClaw system prompt and outbound delivery policy. The GPT-5 guidance is always enabled for matching models. The friendly interaction-style layer is separate and configurable. @@ -535,7 +535,7 @@ the Server-side compaction accordion below. agents: { defaults: { models: { - "openai-codex/gpt-5.5": { + "openai/gpt-5.5": { params: { transport: "auto" }, }, }, @@ -571,7 +571,7 @@ the Server-side compaction accordion below. - OpenClaw exposes a shared fast-mode toggle for both `openai/*` and `openai-codex/*`: + OpenClaw exposes a shared fast-mode toggle for `openai/*`: - **Chat/UI:** `/fast status|on|off` - **Config:** `agents.defaults.models["/"].params.fastMode` @@ -584,7 +584,6 @@ the Server-side compaction accordion below. defaults: { models: { "openai/gpt-5.5": { params: { fastMode: true } }, - "openai-codex/gpt-5.5": { params: { fastMode: true } }, }, }, }, @@ -606,7 +605,6 @@ the Server-side compaction accordion below. defaults: { models: { "openai/gpt-5.5": { params: { serviceTier: "priority" } }, - "openai-codex/gpt-5.5": { params: { serviceTier: "priority" } }, }, }, }, @@ -688,7 +686,7 @@ the Server-side compaction accordion below. - For GPT-5-family runs on `openai/*` and `openai-codex/*`, OpenClaw can use a stricter embedded execution contract: + For GPT-5-family runs on `openai/*`, OpenClaw can use a stricter embedded execution contract: ```json5 { @@ -715,7 +713,7 @@ the Server-side compaction accordion below. OpenClaw treats direct OpenAI, Codex, and Azure OpenAI endpoints differently from generic OpenAI-compatible `/v1` proxies: - **Native routes** (`openai/*`, `openai-codex/*`, Azure OpenAI): + **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 diff --git a/docs/reference/wizard.md b/docs/reference/wizard.md index 99390e50bf8..df04485b4a4 100644 --- a/docs/reference/wizard.md +++ b/docs/reference/wizard.md @@ -34,9 +34,9 @@ For a high-level overview, see [Onboarding (CLI)](/start/wizard). - **Anthropic API key**: preferred Anthropic assistant choice in onboarding/configure. - **Anthropic setup-token**: still available in onboarding/configure, though OpenClaw now prefers Claude CLI reuse when available. - **OpenAI Code (Codex) subscription (OAuth)**: browser flow; paste the `code#state`. - - Sets `agents.defaults.model` to `openai-codex/gpt-5.5` when model is unset or `openai/*`. + - Sets `agents.defaults.model` to `openai/gpt-5.5` when model is unset or already OpenAI-family. - **OpenAI Code (Codex) subscription (device pairing)**: browser pairing flow with a short-lived device code. - - Sets `agents.defaults.model` to `openai-codex/gpt-5.5` when model is unset or `openai/*`. + - Sets `agents.defaults.model` to `openai/gpt-5.5` when model is unset or already OpenAI-family. - **OpenAI API key**: uses `OPENAI_API_KEY` if present or prompts for a key, then stores it in auth profiles. - Sets `agents.defaults.model` to `openai/gpt-5.5` when model is unset, `openai/*`, or `openai-codex/*`. - **xAI (Grok) API key**: prompts for `XAI_API_KEY` and configures xAI as a model provider. diff --git a/docs/start/wizard-cli-reference.md b/docs/start/wizard-cli-reference.md index ad2e4a8ecb9..953bf8b8734 100644 --- a/docs/start/wizard-cli-reference.md +++ b/docs/start/wizard-cli-reference.md @@ -132,13 +132,13 @@ What you set: Browser flow; paste `code#state`. - Sets `agents.defaults.model` to `openai-codex/gpt-5.5` when model is unset or `openai/*`. + Sets `agents.defaults.model` to `openai/gpt-5.5` when model is unset or already OpenAI-family. Browser pairing flow with a short-lived device code. - Sets `agents.defaults.model` to `openai-codex/gpt-5.5` when model is unset or `openai/*`. + Sets `agents.defaults.model` to `openai/gpt-5.5` when model is unset or already OpenAI-family. diff --git a/docs/tools/llm-task.md b/docs/tools/llm-task.md index c5a2ee6796c..5a7185aeba3 100644 --- a/docs/tools/llm-task.md +++ b/docs/tools/llm-task.md @@ -55,7 +55,7 @@ without writing custom OpenClaw code for each workflow. "defaultProvider": "openai-codex", "defaultModel": "gpt-5.5", "defaultAuthProfileId": "main", - "allowedModels": ["openai-codex/gpt-5.5"], + "allowedModels": ["openai/gpt-5.5"], "maxTokens": 800, "timeoutMs": 30000 } diff --git a/qa/scenarios/models/codex-harness-no-meta-leak.md b/qa/scenarios/models/codex-harness-no-meta-leak.md index 54c262ffef3..90b21508fbc 100644 --- a/qa/scenarios/models/codex-harness-no-meta-leak.md +++ b/qa/scenarios/models/codex-harness-no-meta-leak.md @@ -24,7 +24,7 @@ codeRefs: - extensions/qa-lab/src/suite.ts execution: kind: flow - summary: Run with `pnpm openclaw qa suite --provider-mode live-frontier --model codex/gpt-5.5 --alt-model codex/gpt-5.5 --scenario codex-harness-no-meta-leak`. + summary: Run with `pnpm openclaw qa suite --provider-mode live-frontier --model openai/gpt-5.5 --alt-model openai/gpt-5.5 --scenario codex-harness-no-meta-leak`. config: requiredProvider: codex requiredModel: gpt-5.5 diff --git a/qa/scenarios/workspace/medium-game-plan-codex-harness.md b/qa/scenarios/workspace/medium-game-plan-codex-harness.md index 956a9f78899..f3c0dac48e2 100644 --- a/qa/scenarios/workspace/medium-game-plan-codex-harness.md +++ b/qa/scenarios/workspace/medium-game-plan-codex-harness.md @@ -11,7 +11,7 @@ coverage: - models.codex-cli objective: Verify the Codex app-server harness can plan and build a medium-complex self-contained browser game. successCriteria: - - A live-frontier run fails fast unless the selected primary model is codex/gpt-5.5. + - A live-frontier run fails fast unless the selected primary model is openai/gpt-5.5 with the Codex harness forced. - The scenario forces the Codex embedded harness and disables PI fallback. - The prompt explicitly asks the agent to enter plan mode before editing. - The agent writes a self-contained HTML game with a canvas loop, controls, scoring, waves, pause, and restart. @@ -25,7 +25,7 @@ codeRefs: - extensions/qa-lab/src/suite.ts execution: kind: flow - summary: Run with `pnpm openclaw qa suite --provider-mode live-frontier --model codex/gpt-5.5 --alt-model codex/gpt-5.5 --scenario medium-game-plan-codex-harness`. + summary: Run with `pnpm openclaw qa suite --provider-mode live-frontier --model openai/gpt-5.5 --alt-model openai/gpt-5.5 --scenario medium-game-plan-codex-harness`. config: requiredProvider: codex requiredModel: gpt-5.5