diff --git a/docs/cli/config.md b/docs/cli/config.md index 06f0023afd47..1ad471ae40e7 100644 --- a/docs/cli/config.md +++ b/docs/cli/config.md @@ -114,6 +114,13 @@ openclaw config validate --json If validation is already failing, start with `openclaw configure` or `openclaw doctor --fix`. `openclaw chat` does not bypass the invalid-config guard. +Provider and runtime `params` bags are intentionally typed as +`Record` because their owners define the supported keys and +values. `openclaw config validate` can validate the container and overall +config shape, but it cannot type-check provider-specific parameter names or +values. Passing validation does not prove that a param is supported; consult +the provider docs and verify behavior on the selected runtime and provider. + ## Values Values parse as JSON5 when possible; otherwise they are treated as raw strings. Use `--strict-json` to require standard JSON with no string fallback (JSON5-only syntax such as comments, trailing commas, or unquoted keys is then rejected). `--json` is a legacy alias for `--strict-json` on `config set`. @@ -301,13 +308,20 @@ Example patch: defaults: { model: { primary: "openai/gpt-5.6-sol" }, models: { - "openai/gpt-5.6-sol": { params: { fastMode: true } }, + "openai/gpt-5.6-sol": { + agentRuntime: { id: "openclaw" }, + params: { fastMode: true }, + }, }, }, }, } ``` +The runtime pin makes this an embedded OpenClaw recipe. A valid `fastMode` +value is a portable typed runtime control and does not choose OpenClaw by +itself. + Use `--replace-path ` when one object or array must become exactly the provided value instead of being recursively patched: ```bash diff --git a/docs/concepts/model-providers.md b/docs/concepts/model-providers.md index 5175a782b2bd..df8a4f8aff59 100644 --- a/docs/concepts/model-providers.md +++ b/docs/concepts/model-providers.md @@ -30,7 +30,7 @@ Reference for **LLM/model providers** (not chat channels like WhatsApp/Telegram) OpenAI model refs and agent runtimes are separate: - `openai/` selects the canonical OpenAI provider and model. The prefix alone never selects Codex. - - With provider/model runtime policy unset or `auto`, OpenAI may select Codex implicitly only for an exact official HTTPS Platform Responses or ChatGPT Responses route with no authored request override. + - With provider/model runtime policy unset or `auto`, OpenAI may select Codex implicitly only for an exact official HTTPS Platform Responses or ChatGPT Responses route with no authored provider request override. Valid model-scoped Fast-mode controls do not count as authored request params. - Authored Completions adapters, custom endpoints, and routes with authored request behavior stay on OpenClaw. Plaintext official HTTP endpoints are rejected. - legacy Codex model refs are legacy config that doctor rewrites to `openai/`. - Provider/model `agentRuntime.id: "openclaw"` explicitly keeps an otherwise eligible route on OpenClaw. `agentRuntime.id: "codex"` requires Codex and fails closed when the effective route is not Codex-compatible. @@ -111,9 +111,9 @@ Official provider plugins publish their own model catalog rows. These providers - CLI: `openclaw onboard --auth-choice openai-api-key` - Default transport is `auto`; OpenClaw passes the transport choice to the shared model runtime. - Override per model via `agents.defaults.models["openai/"].params.transport` (`"sse"`, `"websocket"`, or `"auto"`) -- OpenAI priority processing can be enabled via `agents.defaults.models["openai/"].params.serviceTier` -- `/fast` and `params.fastMode` map direct `openai/*` Responses requests to `service_tier=priority` on `api.openai.com` -- Use `params.serviceTier` when you want an explicit tier instead of the shared `/fast` toggle +- OpenAI API Fast mode (formerly Priority processing) can be requested on the embedded runtime via `agents.defaults.models["openai/"].params.serviceTier`; OpenClaw currently sends `service_tier=priority` +- `/fast` and valid `params.fastMode` / `params.fast_mode` values are shared agent-runtime controls; on direct embedded `openai/*` Responses requests they map to the same wire tier +- Use `params.serviceTier` when you want an authored embedded-provider tier instead of the shared `/fast` control - Hidden OpenClaw attribution headers (`originator`, `version`, `User-Agent`) apply only on native OpenAI traffic to `api.openai.com`, not generic OpenAI-compatible proxies - Native OpenAI routes also keep Responses `store`, prompt-cache hints, and OpenAI reasoning-compat payload shaping; proxy routes do not - `openai/gpt-5.3-codex-spark` is available only through ChatGPT/Codex OAuth; direct OpenAI API-key and Azure API-key routes reject it @@ -162,13 +162,15 @@ Claude CLI reuse (`claude -p`) is a sanctioned OpenClaw integration path. Anthro - Plugin boundary: `openai/*` loads the OpenAI plugin; explicit runtime policy or the provider-owned effective route decides whether the native Codex app-server plugin is selected. - CLI: `openclaw onboard --auth-choice openai` or `openclaw models auth login --provider openai` - OpenClaw's embedded ChatGPT Responses transport defaults to `auto` (WebSocket-first, SSE fallback). -- `agents.defaults.models["openai/"].params.transport`, `params.serviceTier`, and `params.fastMode` are authored embedded-request settings. They keep implicit runtime selection on OpenClaw; native Codex owns its app-server transport and service tier. +- `agents.defaults.models["openai/"].params.transport` and `params.serviceTier` are authored embedded-provider request settings. They keep implicit runtime selection on OpenClaw; native Codex owns its app-server transport and service tier. +- Valid model-scoped `params.fastMode` / `params.fast_mode` values and valid cutoff keys are portable typed agent-runtime controls. They do not count as authored provider request params and do not select a runtime. Pin `agentRuntime.id: "openclaw"` or `agentRuntime.id: "codex"` when a recipe depends on one runtime. - 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 -- The shared `/fast` toggle remains available as a runtime control; it is distinct from authored model params. +- The shared `/fast` toggle, configured defaults, and valid model-scoped Fast params resolve through one runtime-control policy. See [Thinking levels](/tools/thinking#fast-mode-fast) for precedence. +- OpenAI API Fast mode is premium-priced and model-specific. GPT-5.6 Sol currently costs 2× Standard token pricing, and long-context multipliers stack. ChatGPT/Codex-credit Fast mode is separate: 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). - The native Codex catalog can expose exact `openai/gpt-5.6-sol`, `openai/gpt-5.6-terra`, and `openai/gpt-5.6-luna` refs according to account access. It does not apply the direct API's bare `gpt-5.6` alias client-side. - `openai/gpt-5.5` uses the Codex catalog native `contextWindow = 400000` and default runtime `contextTokens = 272000`; override the runtime cap with `models.providers.openai.models[].contextTokens` - Sign in with `openai` auth and use `openai/gpt-5.6-sol` for a fresh subscription-backed setup. Select `openai/gpt-5.5` explicitly if that Codex workspace does not expose GPT-5.6. -- Use provider/model `agentRuntime.id: "openclaw"` to keep an otherwise eligible route on the built-in runtime. With runtime unset or `auto`, only an exact official HTTPS Responses/ChatGPT-compatible route with no authored request override may select Codex implicitly. +- Use provider/model `agentRuntime.id: "openclaw"` to keep an otherwise eligible route on the built-in runtime. With runtime unset or `auto`, only an exact official HTTPS Responses/ChatGPT-compatible route with no authored provider request override may select Codex implicitly. - Legacy Codex GPT refs are legacy state, not a live provider route. Use canonical `openai/*` refs for new agent config, and run `openclaw doctor --fix` to migrate `codex/*` and `openai-codex/*` refs while preserving their native Codex semantics with model-scoped `agentRuntime.id: "codex"`. Existing explicit canonical `openai/gpt-5.5` selections are not upgraded. ```json5 diff --git a/docs/plugins/codex-harness-reference.md b/docs/plugins/codex-harness-reference.md index f8b85f3f5b8e..2f3fb891e52d 100644 --- a/docs/plugins/codex-harness-reference.md +++ b/docs/plugins/codex-harness-reference.md @@ -190,30 +190,38 @@ managed stdio or the local Unix control socket for production workloads. `appServer` fields: -| Field | Default | Meaning | -| --------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `transport` | `"stdio"` | `"stdio"` spawns Codex; explicit `"unix"` connects to the local control socket; `"websocket"` connects to `url`. | -| `homeScope` | `"agent"` | `"agent"` isolates ordinary harness state per OpenClaw agent. `"user"` is an explicit opt-in that shares the native `$CODEX_HOME` or `~/.codex`, uses native auth, and enables owner-only thread management. User scope supports local stdio or Unix transport. For the separate supervision connection, an unset value resolves to `"user"` for stdio or Unix and `"agent"` for WebSocket. | -| `command` | managed Codex binary | Executable for stdio transport. Leave unset to use the managed binary. | -| `args` | `["app-server", "--listen", "stdio://"]` | Arguments for stdio transport. | -| `url` | unset | WebSocket App Server URL or `unix://` URL. An empty explicit Unix path selects the canonical user-home control socket. | -| `authToken` | unset | Bearer token for WebSocket transport. Accepts a literal string or SecretInput such as `${CODEX_APP_SERVER_TOKEN}`. | -| `headers` | `{}` | Extra WebSocket headers. Header values accept literal strings or SecretInput values, for example `x-codex-client-session-token: "${CODEX_CLIENT_SESSION_TOKEN}"`. | -| `clearEnv` | `[]` | Extra environment variable names removed from the spawned stdio app-server process after OpenClaw builds its inherited environment. | -| `remoteWorkspaceRoot` | unset | Remote Codex app-server workspace root. OpenClaw maps the local cwd into this root and transfers authoritative remote attachments over an output-capped, no-shell `command/exec` reader. Paths escaping either workspace, symbolic links, oversized files, and unbounded attachment batches fail closed; uploads retain the configured channel identity and app-server request timeout. | -| `loopDetectionPreToolUseRelay` | `true` | Install the Codex `PreToolUse` subprocess used only for OpenClaw loop detection and its explicit no-policy marker. Set `false` to reduce per-tool process fan-out. Before-tool plugin hooks and trusted-tool policy still install their required relay. | -| `requestTimeoutMs` | `60000` | Timeout for app-server control-plane calls. | -| `turnCompletionIdleTimeoutMs` | `60000` | Quiet window after Codex accepts a turn or after a turn-scoped app-server request while OpenClaw waits for `turn/completed`. | -| `turnAssistantCompletionIdleTimeoutMs` | `10000` | Quiet window after a final/non-commentary assistant item or pre-tool raw assistant completion arms the assistant-output release while OpenClaw still waits for `turn/completed`. Raising it gives Codex more time to emit `turn/completed` before OpenClaw interrupts and releases the session lane. | -| `postToolRawAssistantCompletionIdleTimeoutMs` | `300000` | Completion-idle and progress guard used after a tool handoff, native tool completion, post-tool raw assistant progress, raw reasoning completion, or reasoning progress while OpenClaw waits for `turn/completed`. Use this for trusted or heavy workloads where post-tool synthesis can legitimately stay quiet longer than the final assistant release budget. | -| `mode` | `"yolo"` unless local Codex requirements disallow YOLO | Preset for YOLO or guardian-reviewed execution. | -| `approvalPolicy` | `"never"` or an allowed guardian approval policy | Native Codex approval policy sent to thread start, resume, and turn. | -| `sandbox` | `"danger-full-access"` or an allowed guardian sandbox | Native Codex sandbox mode sent to thread start and resume. Active OpenClaw sandboxes narrow `danger-full-access` turns to Codex `workspace-write`; the turn network flag follows OpenClaw sandbox egress. | -| `approvalsReviewer` | `"user"` or an allowed guardian reviewer | Use `"auto_review"` to let Codex review native approval prompts when allowed. | -| `defaultWorkspaceDir` | current process directory | Workspace used by `/codex bind` when `--cwd` is omitted. | -| `serviceTier` | unset | Optional Codex app-server service tier. `"priority"` enables fast-mode routing, `"flex"` requests flex processing, and `null` clears the override. Legacy `"fast"` is accepted as `"priority"`. | -| `networkProxy` | disabled | Opt into Codex permissions-profile networking for app-server commands. OpenClaw defines the selected `permissions..network` config and selects it with `default_permissions` instead of sending `sandbox`. | -| `experimental.sandboxExecServer` | `false` | Preview opt-in that registers an OpenClaw sandbox-backed Codex environment with the supported Codex app-server so native Codex execution can run inside the active OpenClaw sandbox. | +| Field | Default | Meaning | +| --------------------------------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `transport` | `"stdio"` | `"stdio"` spawns Codex; explicit `"unix"` connects to the local control socket; `"websocket"` connects to `url`. | +| `homeScope` | `"agent"` | `"agent"` isolates ordinary harness state per OpenClaw agent. `"user"` is an explicit opt-in that shares the native `$CODEX_HOME` or `~/.codex`, uses native auth, and enables owner-only thread management. User scope supports local stdio or Unix transport. For the separate supervision connection, an unset value resolves to `"user"` for stdio or Unix and `"agent"` for WebSocket. | +| `command` | managed Codex binary | Executable for stdio transport. Leave unset to use the managed binary. | +| `args` | `["app-server", "--listen", "stdio://"]` | Arguments for stdio transport. | +| `url` | unset | WebSocket App Server URL or `unix://` URL. An empty explicit Unix path selects the canonical user-home control socket. | +| `authToken` | unset | Bearer token for WebSocket transport. Accepts a literal string or SecretInput such as `${CODEX_APP_SERVER_TOKEN}`. | +| `headers` | `{}` | Extra WebSocket headers. Header values accept literal strings or SecretInput values, for example `x-codex-client-session-token: "${CODEX_CLIENT_SESSION_TOKEN}"`. | +| `clearEnv` | `[]` | Extra environment variable names removed from the spawned stdio app-server process after OpenClaw builds its inherited environment. | +| `remoteWorkspaceRoot` | unset | Remote Codex app-server workspace root. OpenClaw maps the local cwd into this root and transfers authoritative remote attachments over an output-capped, no-shell `command/exec` reader. Paths escaping either workspace, symbolic links, oversized files, and unbounded attachment batches fail closed; uploads retain the configured channel identity and app-server request timeout. | +| `loopDetectionPreToolUseRelay` | `true` | Install the Codex `PreToolUse` subprocess used only for OpenClaw loop detection and its explicit no-policy marker. Set `false` to reduce per-tool process fan-out. Before-tool plugin hooks and trusted-tool policy still install their required relay. | +| `requestTimeoutMs` | `60000` | Timeout for app-server control-plane calls. | +| `turnCompletionIdleTimeoutMs` | `60000` | Quiet window after Codex accepts a turn or after a turn-scoped app-server request while OpenClaw waits for `turn/completed`. | +| `turnAssistantCompletionIdleTimeoutMs` | `10000` | Quiet window after a final/non-commentary assistant item or pre-tool raw assistant completion arms the assistant-output release while OpenClaw still waits for `turn/completed`. Raising it gives Codex more time to emit `turn/completed` before OpenClaw interrupts and releases the session lane. | +| `postToolRawAssistantCompletionIdleTimeoutMs` | `300000` | Completion-idle and progress guard used after a tool handoff, native tool completion, post-tool raw assistant progress, raw reasoning completion, or reasoning progress while OpenClaw waits for `turn/completed`. Use this for trusted or heavy workloads where post-tool synthesis can legitimately stay quiet longer than the final assistant release budget. | +| `mode` | `"yolo"` unless local Codex requirements disallow YOLO | Preset for YOLO or guardian-reviewed execution. | +| `approvalPolicy` | `"never"` or an allowed guardian approval policy | Native Codex approval policy sent to thread start, resume, and turn. | +| `sandbox` | `"danger-full-access"` or an allowed guardian sandbox | Native Codex sandbox mode sent to thread start and resume. Active OpenClaw sandboxes narrow `danger-full-access` turns to Codex `workspace-write`; the turn network flag follows OpenClaw sandbox egress. | +| `approvalsReviewer` | `"user"` or an allowed guardian reviewer | Use `"auto_review"` to let Codex review native approval prompts when allowed. | +| `defaultWorkspaceDir` | current process directory | Workspace used by `/codex bind` when `--cwd` is omitted. | +| `serviceTier` | unset | Native Codex app-server preference only. Any non-empty string passes through for forward compatibility; documented values are `"priority"` and `"flex"`. `null` clears the override, and legacy `"fast"` normalizes to `"priority"`. This is neither the shared Fast-mode setting nor a direct embedded OpenAI setting. A shared Fast run control supersedes it with `priority` or `null`, or decides per model call in auto mode. | +| `networkProxy` | disabled | Opt into Codex permissions-profile networking for app-server commands. OpenClaw defines the selected `permissions..network` config and selects it with `default_permissions` instead of sending `sandbox`. | +| `experimental.sandboxExecServer` | `false` | Preview opt-in that registers an OpenClaw sandbox-backed Codex environment with the supported Codex app-server so native Codex execution can run inside the active OpenClaw sandbox. | + +`appServer.serviceTier` is used only when no shared Fast-mode run control is +supplied. On Codex harness turns, shared Fast on sends `priority`, Fast off +sends `null` to clear the OpenClaw-owned tier, and auto decides for each model +call. `/codex fast off` is separate: it persists `flex` in the bound native +conversation preference for later conversation-bound turns and does not change +the shared OpenClaw session policy. These values describe native configuration +and preference state, not observed provider routing. `appServer.networkProxy` is explicit because it changes the Codex sandbox contract. When enabled, OpenClaw also sets `features.network_proxy.enabled` and diff --git a/docs/plugins/codex-harness.md b/docs/plugins/codex-harness.md index 54b5bc82e377..4c652903d390 100644 --- a/docs/plugins/codex-harness.md +++ b/docs/plugins/codex-harness.md @@ -32,7 +32,10 @@ repaired by `openclaw doctor --fix`. With provider/model runtime policy unset or `auto`, the `openai/*` prefix alone never selects this harness. OpenAI may select Codex implicitly only for an exact official HTTPS Platform Responses or ChatGPT Responses route with no -authored request override. See +authored provider request override. Valid model-scoped `params.fastMode` / +`params.fast_mode` values and valid cutoff keys are typed agent-runtime +controls, so they do not count as authored provider request params or select a +runtime by themselves. See [OpenAI implicit agent runtime](/providers/openai#implicit-agent-runtime). If Codex owns auth before Platform versus ChatGPT routing is known, OpenClaw still requires every candidate route to declare Codex compatibility. Native @@ -211,19 +214,19 @@ rules, paired-node limits, metadata exposure, and troubleshooting. ## Configuration -| Need | Set | Where | -| --------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ---------------------------------- | -| Enable the harness | `plugins.entries.codex.enabled: true` | OpenClaw config | -| Hide native Codex session discovery | `plugins.entries.codex.config.sessionCatalog.enabled: false` | Codex plugin config | -| Keep an allowlisted plugin install | Include `codex` in `plugins.allow` | OpenClaw config | -| Allow eligible OpenAI turns to use Codex implicitly | Exact official HTTPS Responses/ChatGPT route, no authored request override, runtime unset/`auto` | OpenAI provider/model config | -| Sign in with ChatGPT/Codex OAuth | `openclaw models auth login --provider openai` | CLI auth profile | -| Add API-key backup for Codex runs | `openai:*` API-key profile listed after subscription auth in `auth.order.openai` | CLI auth profile + OpenClaw config | -| Fail closed when Codex is unavailable | Provider or model `agentRuntime.id: "codex"` | OpenClaw model/provider config | -| Use direct OpenAI API traffic | Provider or model `agentRuntime.id: "openclaw"` with normal OpenAI auth | OpenClaw model/provider config | -| Tune app-server behavior | `plugins.entries.codex.config.appServer.*` | Codex plugin config | -| Enable native Codex plugin apps | `plugins.entries.codex.config.codexPlugins.*` | Codex plugin config | -| Enable Codex Computer Use | `plugins.entries.codex.config.computerUse.*` | Codex plugin config | +| Need | Set | Where | +| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------- | +| Enable the harness | `plugins.entries.codex.enabled: true` | OpenClaw config | +| Hide native Codex session discovery | `plugins.entries.codex.config.sessionCatalog.enabled: false` | Codex plugin config | +| Keep an allowlisted plugin install | Include `codex` in `plugins.allow` | OpenClaw config | +| Allow eligible OpenAI turns to use Codex implicitly | Exact official HTTPS Responses/ChatGPT route, no authored provider request override, runtime unset/`auto` | OpenAI provider/model config | +| Sign in with ChatGPT/Codex OAuth | `openclaw models auth login --provider openai` | CLI auth profile | +| Add API-key backup for Codex runs | `openai:*` API-key profile listed after subscription auth in `auth.order.openai` | CLI auth profile + OpenClaw config | +| Fail closed when Codex is unavailable | Provider or model `agentRuntime.id: "codex"` | OpenClaw model/provider config | +| Use direct OpenAI API traffic | Provider or model `agentRuntime.id: "openclaw"` with normal OpenAI auth | OpenClaw model/provider config | +| Tune app-server behavior | `plugins.entries.codex.config.appServer.*` | Codex plugin config | +| Enable native Codex plugin apps | `plugins.entries.codex.config.codexPlugins.*` | Codex plugin config | +| Enable Codex Computer Use | `plugins.entries.codex.config.computerUse.*` | Codex plugin config | Prefer `auth.order.openai` for subscription-first/API-key-backup ordering. Existing legacy Codex auth profile ids and legacy Codex auth order are @@ -242,7 +245,8 @@ doctor-only legacy state; do not write new legacy Codex GPT refs. For a Codex-compatible effective route, both profiles above remain candidates for the same Codex run. Profile order chooses credentials, not the runtime. Changing auth order does not make a custom, Completions, HTTP, or -request-overridden route Codex-compatible. +request-overridden route Codex-compatible. Valid model-scoped Fast-mode and +cutoff controls are runtime controls, not request overrides. ### Compaction @@ -413,19 +417,26 @@ of `875900`. Active context grew from `197032` to `377386`, `561957`, and automatic compaction to `75980` active tokens, with a minimum after-compaction snapshot of `68375`. Compaction took `2810` ms and persisted a count of one. A durable marker survived compaction and restart, a deterministic long response -produced `5442` output tokens, every call reported `serviceTier: priority`, and -the full suite took `401.37` seconds. These timings are observations, not -service-level guarantees. +produced `5442` output tokens, and OpenClaw sent the Codex app-server tier +`priority` on every call. That request evidence does not prove which upstream +tier processed each call. The full suite took `401.37` seconds. These timings +are observations, not service-level guarantees. Long context is deliberately opt-in. Once input exceeds `272000` tokens, OpenAI bills the entire request at 2× input and cache rates and 1.5× output -rates. Fast/Priority adds another 2× tier, so long-context Fast traffic is 4× -short-context Standard input-side pricing and 3× short-context Standard output -pricing. The API remains authoritative for access, actual limits, and billing. -See -[OpenAI model limits](https://developers.openai.com/api/docs/models/compare) and -[API pricing](https://developers.openai.com/api/docs/pricing). +rates. Fast-mode pricing is model-specific; GPT-5.6 Sol API Fast mode (formerly +Priority processing) is currently another 2× over Standard, so this recipe is +4× short-context Standard input-side pricing and 3× short-context Standard +output pricing. OpenClaw currently sends the wire value +`service_tier: "priority"`. ChatGPT/Codex-credit Fast mode is separate: GPT-5.6 +and GPT-5.5 currently consume 2.5× Standard credits, while this API-key Codex +route uses API token pricing. The API remains authoritative for access, actual +limits, and billing. See +[OpenAI model limits](https://developers.openai.com/api/docs/models/compare), +[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). The rest of this page covers deployment shape, fail-closed routing, guardian @@ -451,10 +462,14 @@ Then check Codex app-server state: /codex binding ``` -`/codex binding` reports the attached native thread and current model settings. -`/codex status` reports app-server connectivity, account, rate limits, MCP -servers, and skills. `/codex models` lists the live Codex app-server catalog -for the harness and account. If `/status` is surprising, see +`/status` reports the resolved OpenClaw Fast policy (`on`, `off`, or `auto`) +and the selected runtime. It does not report the upstream service tier actually +honored or returned for a completed request. `/codex binding` reports the +attached native thread and current model settings. `/codex status` reports +app-server connectivity, account, rate limits, MCP servers, and skills. +Neither Codex command is provider-response telemetry. `/codex models` lists +the live Codex app-server catalog for the harness and account. If `/status` is +surprising, see [Troubleshooting](#troubleshooting). ## Routing and model selection @@ -464,8 +479,9 @@ Keep provider refs and runtime policy separate: - Use `openai/gpt-*` for canonical OpenAI model selection. The prefix alone never selects Codex. - With runtime unset or `auto`, only an exact official HTTPS Platform Responses - or ChatGPT Responses route with no authored request override may select Codex - implicitly. + or ChatGPT Responses route with no authored provider request override may + select Codex implicitly. Valid model-scoped Fast-mode and cutoff controls do + not count as authored request params. - Do not use legacy Codex GPT refs in config; run `openclaw doctor --fix` to repair legacy refs and stale session route pins. - `agentRuntime.id: "codex"` makes Codex a fail-closed requirement for a @@ -492,13 +508,13 @@ Keep provider refs and runtime policy separate: | Send Codex feedback only | `/codex diagnostics [note]` | | Start an ACP/acpx task | ACP/acpx session commands, not `/codex` | -| Use case | Configure | Verify | Notes | -| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------------- | ------------------------------------------ | -| Eligible OpenAI route with native Codex runtime | Exact official HTTPS Responses/ChatGPT route with no authored request override, plus enabled `codex` plugin | `/status` shows `Runtime: OpenAI Codex` | Implicit path when runtime is unset/`auto` | -| Fail closed if Codex is unavailable | Provider or model `agentRuntime.id: "codex"` | Turn fails instead of embedded fallback | Use for Codex-only deployments | -| Direct OpenAI API-key traffic through OpenClaw | Provider or model `agentRuntime.id: "openclaw"` and normal OpenAI auth | `/status` shows OpenClaw runtime | Use only when OpenClaw is intentional | -| Legacy config | legacy Codex GPT refs | `openclaw doctor --fix` rewrites it | Do not write new config this way | -| ACP/acpx Codex adapter | ACP `sessions_spawn({ runtime: "acp" })` | ACP task/session status | Separate from native Codex harness | +| Use case | Configure | Verify | Notes | +| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | ------------------------------------------------------- | +| Eligible OpenAI route with native Codex runtime | Exact official HTTPS Responses/ChatGPT route with no authored provider request override, plus enabled `codex` plugin | `/status` shows `Runtime: OpenAI Codex` | Valid Fast runtime controls do not disqualify this path | +| Fail closed if Codex is unavailable | Provider or model `agentRuntime.id: "codex"` | Turn fails instead of embedded fallback | Use for Codex-only deployments | +| Direct OpenAI API-key traffic through OpenClaw | Provider or model `agentRuntime.id: "openclaw"` and normal OpenAI auth | `/status` shows OpenClaw runtime | Use only when OpenClaw is intentional | +| Legacy config | legacy Codex GPT refs | `openclaw doctor --fix` rewrites it | Do not write new config this way | +| ACP/acpx Codex adapter | ACP `sessions_spawn({ runtime: "acp" })` | ACP task/session status | Separate from native Codex harness | `agents.defaults.imageModel` follows the same prefix split. Use `openai/gpt-*` for the normal OpenAI route and `codex/gpt-*` only when image understanding @@ -727,6 +743,26 @@ Common forms: - `/codex computer-use [status|install]` manages Codex Computer Use. - `/codex help` lists the full command tree. +### Shared Fast mode and Codex fast mode + +`/fast` controls the shared OpenClaw policy. A directive-only `/fast off` +persists `off` in the OpenClaw session and sends `null` on affected Codex +harness turns to clear the OpenClaw-owned service-tier override. `/fast default` +clears only that session layer, so lower-precedence shared defaults may still +resolve to `on`, `off`, or `auto`. + +`/codex fast` instead changes the bound native Codex conversation preference. +`/codex fast off` stores `flex` for later conversation-bound native turns; it +is not a synonym for `/fast off`, and it does not change the shared OpenClaw +session policy. When a shared Fast-mode run control reaches a Codex harness +turn, it supersedes `plugins.entries.codex.config.appServer.serviceTier` and +any binding preference that applies to that turn: Fast on sends `priority`, +Fast off sends `null`, and auto decides for each model call. The configured or +bound native tier is used only when no shared run control is supplied. + +`/codex fast status` and `/codex binding` report native preference state, not +the upstream tier that processed a completed provider request. + For most support reports, start with `/diagnostics [note]` in the conversation where the bug happened. It creates one Gateway diagnostics report and, for Codex harness sessions, asks for approval to send the @@ -933,29 +969,29 @@ Supported top-level Codex plugin fields: Supported `appServer` fields: -| Field | Default | Meaning | -| --------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `transport` | `"stdio"` | `"stdio"` spawns Codex; explicit `"unix"` connects to the local control socket; `"websocket"` connects to `url`. | -| `homeScope` | `"agent"` | `"agent"` isolates ordinary harness state per OpenClaw agent. `"user"` is an explicit opt-in that shares the native `$CODEX_HOME` or `~/.codex`, uses native auth, and enables owner-only thread management. User scope supports local stdio or Unix transport. For the separate supervision connection, an unset value resolves to `"user"` for stdio or Unix and `"agent"` for WebSocket. | -| `command` | managed Codex binary | Executable for stdio transport. Leave unset to use the managed binary; set it only for an explicit override. | -| `args` | `["app-server", "--listen", "stdio://"]` | Arguments for stdio transport. | -| `url` | unset | WebSocket App Server URL or `unix://` URL. An empty explicit Unix path selects the canonical user-home control socket. | -| `authToken` | unset | Bearer token for WebSocket transport. Accepts a literal string or SecretInput such as `${CODEX_APP_SERVER_TOKEN}`. | -| `headers` | `{}` | Extra WebSocket headers. Header values accept literal strings or SecretInput values, for example `x-codex-client-session-token: "${CODEX_CLIENT_SESSION_TOKEN}"`. | -| `clearEnv` | `[]` | Extra environment variable names removed from the spawned stdio app-server process after OpenClaw builds its inherited environment. OpenClaw keeps the selected `CODEX_HOME` and inherited `HOME` for local launches. | -| `codeModeOnly` | `false` | Opt into Codex's code-mode-only tool surface. Ordinary OpenClaw dynamic tools remain available through nested `tools.*` calls; `openclaw_direct` tools stay directly model-visible. | -| `remoteWorkspaceRoot` | unset | Remote Codex app-server workspace root. OpenClaw maps the local cwd into this root and transfers authoritative remote attachments over an output-capped, no-shell `command/exec` reader. Paths escaping either workspace, symbolic links, oversized files, and unbounded attachment batches fail closed; uploads retain the configured channel identity and app-server request timeout. | -| `requestTimeoutMs` | `60000` | Timeout for app-server control-plane calls. | -| `turnCompletionIdleTimeoutMs` | `60000` | Quiet window after Codex accepts a turn or after a turn-scoped app-server request while OpenClaw waits for `turn/completed`. | -| `turnAssistantCompletionIdleTimeoutMs` | `10000` | Quiet window after a final/non-commentary assistant item or pre-tool raw assistant completion arms the assistant-output release while OpenClaw still waits for `turn/completed`. Raising it gives Codex more time to emit `turn/completed` before OpenClaw interrupts and releases the session lane. | -| `postToolRawAssistantCompletionIdleTimeoutMs` | `300000` | Completion-idle and progress guard used after a tool handoff, native tool completion, post-tool raw assistant progress, raw reasoning completion, or reasoning progress while OpenClaw waits for `turn/completed`. Use this for trusted or heavy workloads where post-tool synthesis can legitimately stay quiet longer than the final assistant release budget. | -| `mode` | `"yolo"` unless local Codex requirements disallow YOLO | Preset for YOLO or guardian-reviewed execution. Local stdio requirements that omit `danger-full-access`, `never` approval, or the `user` reviewer make the implicit default guardian. | -| `approvalPolicy` | `"never"` or an allowed guardian approval policy | Native Codex approval policy sent to thread start/resume/turn. Guardian defaults prefer `"on-request"` when allowed. | -| `sandbox` | `"danger-full-access"` or an allowed guardian sandbox | Native Codex sandbox mode sent to thread start/resume. Guardian defaults prefer `"workspace-write"` when allowed, otherwise `"read-only"`. When an OpenClaw sandbox is active, `danger-full-access` turns use Codex `workspace-write` with network access derived from the OpenClaw sandbox egress setting. | -| `approvalsReviewer` | `"user"` or an allowed guardian reviewer | Use `"auto_review"` to let Codex review native approval prompts when allowed, otherwise `guardian_subagent` or `user`. `guardian_subagent` remains a legacy alias. | -| `serviceTier` | unset | Optional Codex app-server service tier. `"priority"` enables fast-mode routing, `"flex"` requests flex processing, `null` clears the override, and legacy `"fast"` is accepted as `"priority"`. | -| `networkProxy` | disabled | Opt into Codex permissions-profile networking for app-server commands. OpenClaw defines the selected `permissions..network` config and selects it with `default_permissions` instead of sending `sandbox`. | -| `experimental.sandboxExecServer` | `false` | Preview opt-in that registers an OpenClaw sandbox-backed Codex environment with the supported Codex app-server so native Codex execution can run inside the active OpenClaw sandbox. | +| Field | Default | Meaning | +| --------------------------------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `transport` | `"stdio"` | `"stdio"` spawns Codex; explicit `"unix"` connects to the local control socket; `"websocket"` connects to `url`. | +| `homeScope` | `"agent"` | `"agent"` isolates ordinary harness state per OpenClaw agent. `"user"` is an explicit opt-in that shares the native `$CODEX_HOME` or `~/.codex`, uses native auth, and enables owner-only thread management. User scope supports local stdio or Unix transport. For the separate supervision connection, an unset value resolves to `"user"` for stdio or Unix and `"agent"` for WebSocket. | +| `command` | managed Codex binary | Executable for stdio transport. Leave unset to use the managed binary; set it only for an explicit override. | +| `args` | `["app-server", "--listen", "stdio://"]` | Arguments for stdio transport. | +| `url` | unset | WebSocket App Server URL or `unix://` URL. An empty explicit Unix path selects the canonical user-home control socket. | +| `authToken` | unset | Bearer token for WebSocket transport. Accepts a literal string or SecretInput such as `${CODEX_APP_SERVER_TOKEN}`. | +| `headers` | `{}` | Extra WebSocket headers. Header values accept literal strings or SecretInput values, for example `x-codex-client-session-token: "${CODEX_CLIENT_SESSION_TOKEN}"`. | +| `clearEnv` | `[]` | Extra environment variable names removed from the spawned stdio app-server process after OpenClaw builds its inherited environment. OpenClaw keeps the selected `CODEX_HOME` and inherited `HOME` for local launches. | +| `codeModeOnly` | `false` | Opt into Codex's code-mode-only tool surface. Ordinary OpenClaw dynamic tools remain available through nested `tools.*` calls; `openclaw_direct` tools stay directly model-visible. | +| `remoteWorkspaceRoot` | unset | Remote Codex app-server workspace root. OpenClaw maps the local cwd into this root and transfers authoritative remote attachments over an output-capped, no-shell `command/exec` reader. Paths escaping either workspace, symbolic links, oversized files, and unbounded attachment batches fail closed; uploads retain the configured channel identity and app-server request timeout. | +| `requestTimeoutMs` | `60000` | Timeout for app-server control-plane calls. | +| `turnCompletionIdleTimeoutMs` | `60000` | Quiet window after Codex accepts a turn or after a turn-scoped app-server request while OpenClaw waits for `turn/completed`. | +| `turnAssistantCompletionIdleTimeoutMs` | `10000` | Quiet window after a final/non-commentary assistant item or pre-tool raw assistant completion arms the assistant-output release while OpenClaw still waits for `turn/completed`. Raising it gives Codex more time to emit `turn/completed` before OpenClaw interrupts and releases the session lane. | +| `postToolRawAssistantCompletionIdleTimeoutMs` | `300000` | Completion-idle and progress guard used after a tool handoff, native tool completion, post-tool raw assistant progress, raw reasoning completion, or reasoning progress while OpenClaw waits for `turn/completed`. Use this for trusted or heavy workloads where post-tool synthesis can legitimately stay quiet longer than the final assistant release budget. | +| `mode` | `"yolo"` unless local Codex requirements disallow YOLO | Preset for YOLO or guardian-reviewed execution. Local stdio requirements that omit `danger-full-access`, `never` approval, or the `user` reviewer make the implicit default guardian. | +| `approvalPolicy` | `"never"` or an allowed guardian approval policy | Native Codex approval policy sent to thread start/resume/turn. Guardian defaults prefer `"on-request"` when allowed. | +| `sandbox` | `"danger-full-access"` or an allowed guardian sandbox | Native Codex sandbox mode sent to thread start/resume. Guardian defaults prefer `"workspace-write"` when allowed, otherwise `"read-only"`. When an OpenClaw sandbox is active, `danger-full-access` turns use Codex `workspace-write` with network access derived from the OpenClaw sandbox egress setting. | +| `approvalsReviewer` | `"user"` or an allowed guardian reviewer | Use `"auto_review"` to let Codex review native approval prompts when allowed, otherwise `guardian_subagent` or `user`. `guardian_subagent` remains a legacy alias. | +| `serviceTier` | unset | Native Codex app-server preference only. Any non-empty string passes through for forward compatibility; documented values are `"priority"` and `"flex"`. `null` clears the override, and legacy `"fast"` normalizes to `"priority"`. This is neither the shared Fast-mode setting nor a direct embedded OpenAI setting. A shared Fast run control supersedes it with `priority` or `null`, or decides per model call in auto mode. | +| `networkProxy` | disabled | Opt into Codex permissions-profile networking for app-server commands. OpenClaw defines the selected `permissions..network` config and selects it with `default_permissions` instead of sending `sandbox`. | +| `experimental.sandboxExecServer` | `false` | Preview opt-in that registers an OpenClaw sandbox-backed Codex environment with the supported Codex app-server so native Codex execution can run inside the active OpenClaw sandbox. | `appServer.networkProxy` is explicit because it changes the Codex sandbox contract. When enabled, OpenClaw also sets `features.network_proxy.enabled` @@ -1178,7 +1214,7 @@ configs. Select an `openai/gpt-*` model, enable **OpenClaw uses the built-in harness instead of Codex:** confirm the effective route is an exact official HTTPS Platform Responses or ChatGPT Responses route, -has no authored request override, and that the Codex plugin is installed and +has no authored provider request override, and that the Codex plugin is installed and enabled. The `openai/gpt-*` prefix alone is not enough. For strict proof while testing, set provider or model `agentRuntime.id: "codex"`; forced Codex fails instead of falling back when the route or harness is incompatible. diff --git a/docs/providers/openai.md b/docs/providers/openai.md index 4f6d71b077a0..9510f61eb2e1 100644 --- a/docs/providers/openai.md +++ b/docs/providers/openai.md @@ -72,13 +72,19 @@ 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 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 | +| 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` values and valid +cutoff keys are typed agent-runtime controls, not authored provider request +params. They do not disqualify implicit Codex selection or select a runtime by +themselves. Pin `agentRuntime.id: "openclaw"` or `agentRuntime.id: "codex"` +when a recipe depends on one runtime. An explicit non-default provider/model `agentRuntime.id` remains authoritative. For example, `agentRuntime.id: "openclaw"` keeps an otherwise Codex-eligible @@ -502,7 +508,7 @@ for the full example. #### Embedded OpenClaw translation This example pins the exact Sol model to the embedded OpenClaw runtime, - enables priority processing through fast mode, and asks OpenAI Responses + enables OpenAI API Fast mode through the shared runtime control, and asks OpenAI Responses to compact at `700000` active tokens: ```json5 @@ -600,14 +606,15 @@ for the full example. 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/Priority is - another 2× tier. Combined long-context Fast traffic is therefore 4× - short-context Standard input-side pricing and 3× short-context Standard + 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 - [OpenAI API pricing](https://developers.openai.com/api/docs/pricing). The API - remains authoritative for account access, actual limits, and billing. + 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. ### Catalog recovery @@ -1294,12 +1301,14 @@ accordion below. ## Advanced configuration -The per-model `params` examples below shape OpenClaw's embedded provider -request. Configuring them is authored request behavior, so an otherwise eligible -`auto` route stays on OpenClaw instead of selecting Codex implicitly. The native -Codex app-server harness owns its own transport and request settings; explicit -`agentRuntime.id: "codex"` fails closed when the effective route is not declared -Codex-compatible. +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 own transport and request settings; +explicit `agentRuntime.id: "codex"` fails closed when the effective route is +not declared Codex-compatible. @@ -1326,6 +1335,7 @@ Codex-compatible. defaults: { models: { "openai/gpt-5.5": { + agentRuntime: { id: "openclaw" }, params: { transport: "auto" }, }, }, @@ -1346,20 +1356,28 @@ Codex-compatible. - **Chat/UI:** `/fast status|auto|on|off` - **Config:** `agents.defaults.models["/"].params.fastMode` - When enabled, OpenClaw maps fast mode to OpenAI priority processing - (`service_tier = "priority"`). Existing `service_tier` values are - preserved, and fast mode does not rewrite `reasoning` or + 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. + 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": { params: { fastMode: "auto", fastAutoOnSeconds: 30 } }, + "openai/gpt-5.5": { + agentRuntime: { id: "openclaw" }, + params: { fastMode: "auto", fastAutoOnSeconds: 30 }, + }, }, }, }, @@ -1367,22 +1385,40 @@ Codex-compatible. ``` - Session overrides win over config. Clearing the session override in the - Sessions UI returns the session to the configured default. + 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-fast) and + [Codex harness](/plugins/codex-harness#shared-fast-mode-and-codex-fast-mode). + 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). + - - OpenAI's API exposes priority processing via `service_tier`. Set it per - model in OpenClaw: + + 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": { params: { serviceTier: "priority" } }, + "openai/gpt-5.5": { + agentRuntime: { id: "openclaw" }, + params: { serviceTier: "priority" }, + }, }, }, }, @@ -1392,10 +1428,13 @@ Codex-compatible. Supported values: `auto`, `default`, `flex`, `priority`. - `serviceTier` is forwarded only to native OpenAI endpoints - (`api.openai.com`) and native Codex endpoints (`chatgpt.com/backend-api`). - If you route either provider through a proxy, OpenClaw leaves - `service_tier` untouched. + `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. diff --git a/docs/tools/thinking.md b/docs/tools/thinking.md index 8da6fd3bea6f..379378c8bc6d 100644 --- a/docs/tools/thinking.md +++ b/docs/tools/thinking.md @@ -67,18 +67,20 @@ title: "Thinking levels" - Directive-only message toggles a session fast-mode override and replies `Fast mode set to auto.`, `Fast mode enabled.`, or `Fast mode disabled.`. Use `/fast default` to clear the session override and inherit the configured default; aliases include `inherit`, `clear`, `reset`, and `unpin`. - Send `/fast` (or `/fast status`) with no mode to see the current effective fast-mode state. - OpenClaw resolves fast mode in this order: - 1. Inline/directive-only `/fast auto|on|off` override (`/fast default` clears this layer) - 2. Session override + 1. Inline `/fast auto|on|off` override on the current message + 2. Stored session override from a directive-only message (`/fast default` clears this layer) 3. Per-agent default (`agents.entries.*.fastModeDefault`) - 4. Per-model config: `agents.defaults.models["/"].params.fastMode` - 5. Fallback: `off` + 4. Global default (`agents.defaults.fastModeDefault`) + 5. Per-model config (`agents.defaults.models["/"].params.fastMode`) + 6. Fallback: `off` +- Valid model-scoped `params.fastMode` / `params.fast_mode` values and valid cutoff keys are typed agent-runtime controls. They do not count as authored provider request params and do not select OpenClaw or Codex by themselves. Pin `agentRuntime.id: "openclaw"` or `agentRuntime.id: "codex"` when a recipe depends on one runtime. - `auto` keeps the session/config mode as auto but resolves each new model call independently. Calls that start before the auto cutoff have fast mode enabled; later retry, fallback, tool-result, or continuation calls start with fast mode disabled. The cutoff defaults to 60 seconds; set `agents.defaults.models["/"].params.fastAutoOnSeconds` on the active model to change it. -- For `openai/*`, fast mode maps to OpenAI priority processing by sending `service_tier=priority` on supported Responses requests. -- For Codex-backed `openai/*` / `openai-codex/*` models, fast mode sends the same `service_tier=priority` flag on Codex Responses. Native Codex app-server turns receive the tier only on `turn/start` or thread start/resume, so `auto` cannot retier one already-running app-server turn; it applies to the next model turn OpenClaw starts. +- For `openai/*`, fast mode maps to OpenAI API Fast mode (formerly Priority processing). OpenClaw currently sends `service_tier=priority` on supported Responses requests. +- On Codex harness turns, the shared runtime control supersedes a configured native app-server tier: Fast on sends `priority`, Fast off sends `null` to clear the OpenClaw-owned tier, and auto decides for each model call. A configured Codex tier is used only when no shared Fast-mode run control is supplied. See [Codex harness](/plugins/codex-harness#shared-fast-mode-and-codex-fast-mode). - For direct public `anthropic/*` requests, including OAuth-authenticated traffic sent to `api.anthropic.com`, fast mode maps to Anthropic service tiers: `/fast on` sets `service_tier=auto`, `/fast off` sets `service_tier=standard_only`. - For `minimax/*` on the Anthropic-compatible path, `/fast on` (or `params.fastMode: true`) rewrites `MiniMax-M2.7` to `MiniMax-M2.7-highspeed`. - Explicit Anthropic `serviceTier` / `service_tier` model params override the fast-mode default when both are set. OpenClaw still skips Anthropic service-tier injection for non-Anthropic proxy base URLs. -- `/status` shows `Fast` when fast mode is enabled and `Fast:auto` when the configured mode is auto. +- `/status` reports the resolved OpenClaw policy (`on`, `off`, or `auto`) and the selected runtime. It does not report the upstream service tier actually honored or returned for a completed request. See [OpenAI Fast mode](/providers/openai#advanced-configuration) for provider details. ## Verbose directives (/verbose or /v)