vultr/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-05-06 12:30:44 +00:00
Code Issues Packages Projects Releases Wiki Activity

Make harness failures fail honestly (#69981)

Browse Source 
* Agents: fail honestly on harness errors

* Docs: clarify Codex harness fallback
This commit is contained in:
pashpashpash
2026-04-21 22:33:21 -07:00
committed by GitHub
parent a0ccf69259
commit dc4e97472d
10 changed files with 55 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
docs/.generated/config-baseline.sha256
View File

@@ -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

2
docs/gateway/configuration-reference.md
View File

@@ -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=<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.

8
docs/plugins/codex-harness.md
View File

@@ -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.

24
docs/plugins/sdk-agent-harness.md
View File

@@ -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: