From fc40cdb786e8f8f7f28c9050ff0a708b212810ff Mon Sep 17 00:00:00 2001 From: "openclaw-docs-sync[bot]" Date: Wed, 22 Apr 2026 05:34:11 +0000 Subject: [PATCH] chore(sync): mirror docs from openclaw/openclaw@dc4e97472d4f3d1f8df00a17193952df6f9ade31 --- .openclaw-sync/source.json | 4 ++-- docs/.generated/config-baseline.sha256 | 6 +++--- docs/gateway/configuration-reference.md | 2 +- docs/plugins/codex-harness.md | 8 ++++++-- docs/plugins/sdk-agent-harness.md | 24 +++++++++++++----------- 5 files changed, 25 insertions(+), 19 deletions(-) diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json index f0e1f4563..97cd0860d 100644 --- a/.openclaw-sync/source.json +++ b/.openclaw-sync/source.json @@ -1,5 +1,5 @@ { "repository": "openclaw/openclaw", - "sha": "e39784decd40e87b75fcf685d536b391efe9f313", - "syncedAt": "2026-04-22T05:13:21.173Z" + "sha": "dc4e97472d4f3d1f8df00a17193952df6f9ade31", + "syncedAt": "2026-04-22T05:34:11.225Z" } diff --git a/docs/.generated/config-baseline.sha256 b/docs/.generated/config-baseline.sha256 index 77fb883cb..f774298b3 100644 --- a/docs/.generated/config-baseline.sha256 +++ b/docs/.generated/config-baseline.sha256 @@ -1,4 +1,4 @@ -1022a9497ff0481675c483742b8e92c6063e53c9bb3e5c5c3bd39300cf2e1f31 config-baseline.json -7956c319e82d288d496a51cb2ff4485ab72ef4900cb089f99e1df8b9ef3bfb73 config-baseline.core.json +7c1b8b34618f44d56817ff54b930701710087dc7e76beaf4a554b6a5a25ba87c config-baseline.json +ed0c093e8acab2364608be3e65b98836600aea07df73ebb51d11919969c6c8fe config-baseline.core.json 6c0069b971ae298ae68516ebcd3eae0e8c82820d2e8f42ecbd2f53a2f9077371 config-baseline.channel.json -a7f297a3461e807fd15f8a7c8c68e41071dfc09af2118c24a26d5f534301a654 config-baseline.plugin.json +e5b7756b5f45ba227aa1bfab990dcf8a2a8b409b9ca01ea8bb1d5cd7adc06c90 config-baseline.plugin.json diff --git a/docs/gateway/configuration-reference.md b/docs/gateway/configuration-reference.md index fc852eb20..2d0247748 100644 --- a/docs/gateway/configuration-reference.md +++ b/docs/gateway/configuration-reference.md @@ -1266,7 +1266,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. `"none"` makes missing or unsupported plugin harness selection fail instead of silently using PI. +- `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.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. diff --git a/docs/plugins/codex-harness.md b/docs/plugins/codex-harness.md index 4378e33d9..bcd750e53 100644 --- a/docs/plugins/codex-harness.md +++ b/docs/plugins/codex-harness.md @@ -469,8 +469,12 @@ understanding continue to use the matching provider/model settings such as **Codex does not appear in `/model`:** enable `plugins.entries.codex.enabled`, set a `codex/*` model ref, or check whether `plugins.allow` excludes `codex`. -**OpenClaw falls back to PI:** set `embeddedHarness.fallback: "none"` or -`OPENCLAW_AGENT_HARNESS_FALLBACK=none` while testing. +**OpenClaw uses PI instead of Codex:** if no Codex harness claims the run, +OpenClaw may use PI as the compatibility backend. Set +`embeddedHarness.runtime: "codex"` to force Codex selection while testing, or +`embeddedHarness.fallback: "none"` to fail when no plugin harness matches. Once +Codex app-server is selected, its failures surface directly without extra +fallback config. **The app-server is rejected:** upgrade Codex so the app-server handshake reports version `0.118.0` or newer. diff --git a/docs/plugins/sdk-agent-harness.md b/docs/plugins/sdk-agent-harness.md index c89ef4145..6979c4d5e 100644 --- a/docs/plugins/sdk-agent-harness.md +++ b/docs/plugins/sdk-agent-harness.md @@ -94,10 +94,11 @@ OpenClaw chooses a harness after provider/model resolution: 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. Set `OPENCLAW_AGENT_HARNESS_FALLBACK=none` or -`embeddedHarness.fallback: "none"` to make that fallback a hard failure instead. +Plugin harness failures surface as run failures. In `auto` mode, PI fallback is +only used when no registered plugin harness supports the resolved +provider/model. Once a plugin harness has claimed a run, OpenClaw does not +replay that same turn through PI because that can change auth/runtime semantics +or duplicate side effects. The bundled Codex plugin registers `codex` as its harness id. Core treats that as an ordinary plugin harness id; Codex-specific aliases belong in the plugin @@ -149,19 +150,20 @@ When this mode runs, Codex owns the native thread id, resume behavior, compaction, and app-server execution. OpenClaw still owns the chat channel, visible transcript mirror, tool policy, approvals, media delivery, and session selection. Use `embeddedHarness.runtime: "codex"` with -`embeddedHarness.fallback: "none"` when you need to prove that the Codex -app-server path is used and PI fallback is not hiding a broken native harness. +`embeddedHarness.fallback: "none"` when you need to prove that only the Codex +app-server path can claim the run. That config is only a selection guard: +Codex app-server failures already fail directly instead of retrying through PI. ## Disable PI fallback By default, OpenClaw runs embedded agents with `agents.defaults.embeddedHarness` set to `{ runtime: "auto", fallback: "pi" }`. In `auto` mode, registered plugin -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. +harnesses can claim a provider/model pair. If none match, OpenClaw falls back +to PI. -Set `fallback: "none"` when you need to prove that a plugin harness is the only -runtime being exercised. This disables automatic PI fallback; it does not block -an explicit `runtime: "pi"` or `OPENCLAW_AGENT_RUNTIME=pi`. +Set `fallback: "none"` when you need missing plugin harness selection to fail +instead of using PI. Selected plugin harness failures already fail hard. This +does not block an explicit `runtime: "pi"` or `OPENCLAW_AGENT_RUNTIME=pi`. For Codex-only embedded runs: