docs: document harness fallback policy

2026-04-12 01:31:08 +00:00 · 2026-04-10 21:26:54 +01:00
parent d236cb4680
commit c16b1b7433
6 changed files with 93 additions and 6 deletions
--- 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
--- 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

--- 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=<id|auto|pi>` 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`.
--- 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`

--- 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.
--- a/src/config/schema.help.ts
+++ b/src/config/schema.help.ts
@@ -1088,6 +1088,18 @@ export const FIELD_HELP: Record<string, string> = {
  "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).",