diff --git a/docs/.generated/config-baseline.sha256 b/docs/.generated/config-baseline.sha256 index 9324a7056db..56238367798 100644 --- a/docs/.generated/config-baseline.sha256 +++ b/docs/.generated/config-baseline.sha256 @@ -1,4 +1,4 @@ -c2705b6fbb297a6f06aefa6036db71aa5dbfea5a21ec3dafd53ed631cdc558f9 config-baseline.json -b8e245d02a00b696af2b4f0447553dd3b5bb98ca805aca650fb2ce5c0487eacb config-baseline.core.json +0d39440fe9e6ace28f407bc6412aaab0c9ceb31a1d496c079f8ddd258ae23ed1 config-baseline.json +0270f541792d9372503b15251dc24e276abd6c43cfc74768a590f01d55b0bf67 config-baseline.core.json e1f94346a8507ce3dec763b598e79f3bb89ff2e33189ce977cc87d3b05e71c1d config-baseline.channel.json 9153501720ea74f9356432a011fa9b41c9b700084bfe0d156feb5647624b35ad config-baseline.plugin.json diff --git a/docs/concepts/model-providers.md b/docs/concepts/model-providers.md index d6425205a67..f4bee523f22 100644 --- a/docs/concepts/model-providers.md +++ b/docs/concepts/model-providers.md @@ -54,6 +54,9 @@ For model selection rules, see [/concepts/models](/concepts/models). Use `codex/gpt-*` when you want Codex-owned login, model discovery, native thread resume, and app-server execution. Plain `openai/gpt-*` refs continue to use the OpenAI provider and the normal OpenClaw provider transport. + Codex-only deployments can disable automatic PI fallback with + `agents.defaults.embeddedHarness.fallback: "none"`; see + [Agent Harness Plugins](/plugins/sdk-agent-harness#disable-pi-fallback). ## Plugin-owned provider behavior diff --git a/docs/gateway/configuration-reference.md b/docs/gateway/configuration-reference.md index 9c53e81983a..03484f554fa 100644 --- a/docs/gateway/configuration-reference.md +++ b/docs/gateway/configuration-reference.md @@ -1053,6 +1053,10 @@ Time format in system prompt. Default: `auto` (OS preference). fallbacks: ["openai/gpt-5.4-mini"], }, params: { cacheRetention: "long" }, // global default provider params + embeddedHarness: { + runtime: "auto", // auto | pi | registered harness id, e.g. codex + fallback: "pi", // pi | none + }, pdfMaxBytesMb: 10, pdfMaxPages: 20, thinkingDefault: "low", @@ -1100,9 +1104,37 @@ Time format in system prompt. Default: `auto` (OS preference). - `models`: the configured model catalog and allowlist for `/model`. Each entry can include `alias` (shortcut) and `params` (provider-specific, for example `temperature`, `maxTokens`, `cacheRetention`, `context1m`). - `params`: global default provider parameters applied to all models. Set at `agents.defaults.params` (e.g. `{ cacheRetention: "long" }`). - `params` merge precedence (config): `agents.defaults.params` (global base) is overridden by `agents.defaults.models["provider/model"].params` (per-model), then `agents.list[].params` (matching agent id) overrides by key. See [Prompt Caching](/reference/prompt-caching) for details. +- `embeddedHarness`: default low-level embedded agent runtime policy. Use `runtime: "auto"` to let registered plugin harnesses claim supported models, `runtime: "pi"` to force the built-in PI harness, or a registered harness id such as `runtime: "codex"`. Set `fallback: "none"` to disable automatic PI fallback. - Config writers that mutate these fields (for example `/models set`, `/models set-image`, and fallback add/remove commands) save canonical object form and preserve existing fallback lists when possible. - `maxConcurrent`: max parallel agent runs across sessions (each session still serialized). Default: 4. +### `agents.defaults.embeddedHarness` + +`embeddedHarness` controls which low-level executor runs embedded agent turns. +Most deployments should keep the default `{ runtime: "auto", fallback: "pi" }`. +Use it when a trusted plugin provides a native harness, such as the bundled +Codex app-server harness. + +```json5 +{ + agents: { + defaults: { + model: "codex/gpt-5.4", + embeddedHarness: { + runtime: "codex", + fallback: "none", + }, + }, + }, +} +``` + +- `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. `"none"` makes missing or unsupported plugin harness selection fail instead of silently using PI. +- 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.4"`, `embeddedHarness.runtime: "codex"`, and `embeddedHarness.fallback: "none"`. +- This only controls the embedded chat harness. Media generation, vision, PDF, music, video, and TTS still use their provider/model settings. + **Built-in alias shorthands** (only apply when the model is in `agents.defaults.models`): | Alias | Model | @@ -1583,6 +1615,7 @@ scripts/sandbox-browser-setup.sh # optional browser image thinkingDefault: "high", // per-agent thinking level override reasoningDefault: "on", // per-agent reasoning visibility override fastModeDefault: false, // per-agent fast mode override + embeddedHarness: { runtime: "auto", fallback: "pi" }, params: { cacheRetention: "none" }, // overrides matching defaults.models params by key skills: ["docs-search"], // replaces agents.defaults.skills when set identity: { @@ -1623,6 +1656,7 @@ scripts/sandbox-browser-setup.sh # optional browser image - `thinkingDefault`: optional per-agent default thinking level (`off | minimal | low | medium | high | xhigh | adaptive`). Overrides `agents.defaults.thinkingDefault` for this agent when no per-message or session override is set. - `reasoningDefault`: optional per-agent default reasoning visibility (`on | off | stream`). Applies when no per-message or session reasoning override is set. - `fastModeDefault`: optional per-agent default for fast mode (`true | false`). Applies when no per-message or session fast-mode override is set. +- `embeddedHarness`: optional per-agent low-level harness policy override. Use `{ runtime: "codex", fallback: "none" }` to make one agent Codex-only while other agents keep the default PI fallback. - `runtime`: optional per-agent runtime descriptor. Use `type: "acp"` with `runtime.acp` defaults (`agent`, `backend`, `mode`, `cwd`) when the agent should default to ACP harness sessions. - `identity.avatar`: workspace-relative path, `http(s)` URL, or `data:` URI. - `identity` derives defaults: `ackReaction` from `emoji`, `mentionPatterns` from `name`/`emoji`. diff --git a/docs/help/testing.md b/docs/help/testing.md index 4caaa478e00..4d13ef8fa3c 100644 --- a/docs/help/testing.md +++ b/docs/help/testing.md @@ -404,6 +404,8 @@ Docker notes: - Default model: `codex/gpt-5.4` - Optional image probe: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` - Optional MCP/tool probe: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` +- The smoke sets `OPENCLAW_AGENT_HARNESS_FALLBACK=none` so a broken Codex + harness cannot pass by silently falling back to PI. - Auth: `OPENAI_API_KEY` from the shell/profile, plus optional copied `~/.codex/auth.json` and `~/.codex/config.toml` diff --git a/docs/plugins/sdk-agent-harness.md b/docs/plugins/sdk-agent-harness.md index 721587f7160..4691455778f 100644 --- a/docs/plugins/sdk-agent-harness.md +++ b/docs/plugins/sdk-agent-harness.md @@ -91,11 +91,13 @@ OpenClaw chooses a harness after provider/model resolution: 2. `OPENCLAW_AGENT_RUNTIME=pi` forces the built-in PI harness. 3. `OPENCLAW_AGENT_RUNTIME=auto` asks registered harnesses if they support the resolved provider/model. -4. If no registered harness matches, OpenClaw uses PI. +4. If no registered harness matches, OpenClaw uses PI unless PI fallback is + disabled. Forced plugin harness failures surface as run failures. In `auto` mode, OpenClaw may fall back to PI when the selected plugin harness fails before a -turn has produced side effects. +turn has produced side effects. Set `OPENCLAW_AGENT_HARNESS_FALLBACK=none` or +`embeddedHarness.fallback: "none"` to make that fallback a hard failure instead. The bundled Codex plugin registers `codex` as its harness id. For compatibility, `codex-app-server` and `app-server` also resolve to that same harness when you @@ -128,7 +130,7 @@ OpenClaw requires Codex app-server `0.118.0` or newer. The Codex plugin checks the app-server initialize handshake and blocks older or unversioned servers so OpenClaw only runs against the protocol surface it has been tested with. -## Harness selection policy +## Disable PI fallback By default, OpenClaw runs embedded agents with `agents.defaults.embeddedHarness` set to `{ runtime: "auto", fallback: "pi" }`. In `auto` mode, registered plugin @@ -136,7 +138,10 @@ harnesses can claim a provider/model pair. If none match, or if an auto-selected plugin harness fails before producing output, OpenClaw falls back to PI. Set `fallback: "none"` when you need to prove that a plugin harness is the only -runtime being exercised: +runtime being exercised. This disables automatic PI fallback; it does not block +an explicit `runtime: "pi"` or `OPENCLAW_AGENT_RUNTIME=pi`. + +For Codex-only embedded runs: ```json { @@ -152,6 +157,23 @@ runtime being exercised: } ``` +If you want any registered plugin harness to claim matching models but never +want OpenClaw to silently fall back to PI, keep `runtime: "auto"` and disable +the fallback: + +```json +{ + "agents": { + "defaults": { + "embeddedHarness": { + "runtime": "auto", + "fallback": "none" + } + } + } +} +``` + Per-agent overrides use the same shape: ```json @@ -181,6 +203,20 @@ Per-agent overrides use the same shape: `OPENCLAW_AGENT_HARNESS_FALLBACK=none` to disable PI fallback from the environment. +```bash +OPENCLAW_AGENT_RUNTIME=codex \ +OPENCLAW_AGENT_HARNESS_FALLBACK=none \ +openclaw gateway run +``` + +With fallback disabled, a session fails early when the requested harness is not +registered, does not support the resolved provider/model, or fails before +producing turn side effects. That is intentional for Codex-only deployments and +for live tests that must prove the Codex app-server path is actually in use. + +This setting only controls the embedded agent harness. It does not disable +image, video, music, TTS, PDF, or other provider-specific model routing. + ## Native sessions and transcript mirror A harness may keep a native session id, thread id, or daemon-side resume token. diff --git a/src/config/schema.help.ts b/src/config/schema.help.ts index ba40c1c39dc..a6d040792fe 100644 --- a/src/config/schema.help.ts +++ b/src/config/schema.help.ts @@ -1088,6 +1088,18 @@ export const FIELD_HELP: Record = { "agents.defaults.model.primary": "Primary model (provider/model).", "agents.defaults.model.fallbacks": "Ordered fallback models (provider/model). Used when the primary model fails.", + "agents.defaults.embeddedHarness": + "Default embedded agent harness policy. Use runtime=auto for plugin harness selection, runtime=pi for built-in PI, or a registered harness id such as codex.", + "agents.defaults.embeddedHarness.runtime": + "Embedded harness runtime: auto, pi, or a registered plugin harness id such as codex.", + "agents.defaults.embeddedHarness.fallback": + "Embedded harness fallback when no plugin harness matches or an auto-selected plugin harness fails before side effects. Set none to disable automatic PI fallback.", + "agents.list.*.embeddedHarness": + "Per-agent embedded harness policy override. Use fallback=none to make this agent fail instead of falling back to PI.", + "agents.list.*.embeddedHarness.runtime": + "Per-agent embedded harness runtime: auto, pi, or a registered plugin harness id such as codex.", + "agents.list.*.embeddedHarness.fallback": + "Per-agent embedded harness fallback. Set none to disable automatic PI fallback for this agent.", "agents.defaults.imageModel.primary": "Optional image model (provider/model) used when the primary model lacks image input.", "agents.defaults.imageModel.fallbacks": "Ordered fallback image models (provider/model).",