Skip to content

Commit ca20f88

Browse files
pashpashpashpashpashpash
committed
fix: remove agent runtime fallback config
1 parent 5c4b035 commit ca20f88

49 files changed

Lines changed: 190 additions & 555 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs/.generated/config-baseline.sha256‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
fe6f32e80de6cf5f9877e2944039a31dc677fee0c70f4e63bb252315d29e5eb4 config-baseline.json
2-
6d477ca3b60982b770e85929ab8393a7923a6b31ce99f3b7c7dba13cdd4f9180 config-baseline.core.json
1+
b9831b7dafd0a7d6d1256ee531b30c0b75c64bf0f494fcc9e68bf2255fdb560a config-baseline.json
2+
b6ebb672410bd1ff148ee6d25fba1a359032686959e28d7b8f0313323f94debf config-baseline.core.json
33
f2a1aad257c570b497865680c331568a6775369528749826dfa35c1f644483fc config-baseline.channel.json
44
fffe0e74eab92a88c3c57952a70bc932438ce3a7f5f9982688437f2cdaee0bcb config-baseline.plugin.json

‎docs/concepts/agent-runtimes.md‎

Lines changed: 7 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -140,15 +140,13 @@ OpenClaw chooses an embedded runtime after provider and model resolution:
140140
supported CLI backend alias such as `claude-cli`.
141141
4. In `auto` mode, registered plugin runtimes can claim supported provider/model
142142
pairs.
143-
5. If no runtime claims a turn in `auto` mode and `fallback: "pi"` is set
144-
(the default), OpenClaw uses PI as the compatibility fallback. Set
145-
`fallback: "none"` to make unmatched `auto`-mode selection fail instead.
146-
147-
Explicit plugin runtimes fail closed by default. For example,
148-
`agentRuntime.id: "codex"` means Codex or a clear selection error unless you set
149-
`fallback: "pi"` in the same override scope. A runtime override does not inherit
150-
a broader fallback setting, so an agent-level `agentRuntime.id: "codex"` is not
151-
silently routed back to PI just because defaults used `fallback: "pi"`.
143+
5. If no runtime claims a turn in `auto` mode, OpenClaw uses PI as the
144+
compatibility runtime. Use an explicit runtime id when the run must be
145+
strict.
146+
147+
Explicit plugin runtimes fail closed. For example, `agentRuntime.id: "codex"`
148+
means Codex or a clear selection/runtime error; it is never silently routed back
149+
to PI.
152150

153151
CLI backend aliases are different from embedded harness ids. The preferred
154152
Claude CLI form is:

‎docs/concepts/model-providers.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -157,7 +157,7 @@ Anthropic staff told us OpenClaw-style Claude CLI usage is allowed again, so Ope
157157
agents: {
158158
defaults: {
159159
model: { primary: "openai/gpt-5.5" },
160-
agentRuntime: { id: "codex", fallback: "none" },
160+
agentRuntime: { id: "codex" },
161161
},
162162
},
163163
}

‎docs/gateway/config-agents.md‎

Lines changed: 5 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -334,7 +334,6 @@ Time format in system prompt. Default: `auto` (OS preference).
334334
params: { cacheRetention: "long" }, // global default provider params
335335
agentRuntime: {
336336
id: "pi", // pi | auto | registered harness id, e.g. codex
337-
fallback: "pi", // pi | none
338337
},
339338
pdfMaxBytesMb: 10,
340339
pdfMaxPages: 20,
@@ -393,7 +392,7 @@ Time format in system prompt. Default: `auto` (OS preference).
393392
- `params.chat_template_kwargs`: vLLM/OpenAI-compatible chat-template arguments merged into top-level `api: "openai-completions"` request bodies. For `vllm/nemotron-3-*` with thinking off, the bundled vLLM plugin automatically sends `enable_thinking: false` and `force_nonempty_content: true`; explicit `chat_template_kwargs` override generated defaults, and `extra_body.chat_template_kwargs` still has final precedence. For vLLM Qwen thinking controls, set `params.qwenThinkingFormat` to `"chat-template"` or `"top-level"` on that model entry.
394393
- `compat.supportedReasoningEfforts`: per-model OpenAI-compatible reasoning effort list. Include `"xhigh"` for custom endpoints that truly accept it; OpenClaw then exposes `/think xhigh` in command menus, Gateway session rows, session patch validation, agent CLI validation, and `llm-task` validation for that configured provider/model. Use `compat.reasoningEffortMap` when the backend wants a provider-specific value for a canonical level.
395394
- `params.preserveThinking`: Z.AI-only opt-in for preserved thinking. When enabled and thinking is on, OpenClaw sends `thinking.clear_thinking: false` and replays prior `reasoning_content`; see [Z.AI thinking and preserved thinking](/providers/zai#thinking-and-preserved-thinking).
396-
- `agentRuntime`: default low-level agent runtime policy. Omitted id defaults to OpenClaw Pi. Use `id: "pi"` to force the built-in PI harness, `id: "auto"` to let registered plugin harnesses claim supported models, a registered harness id such as `id: "codex"`, or a supported CLI backend alias such as `id: "claude-cli"`. Set `fallback: "none"` to disable automatic PI fallback. Explicit plugin runtimes such as `codex` fail closed by default unless you set `fallback: "pi"` in the same override scope. Keep model refs canonical as `provider/model`; select Codex, Claude CLI, Gemini CLI, and other execution backends through runtime config instead of legacy runtime provider prefixes. See [Agent runtimes](/concepts/agent-runtimes) for how this differs from provider/model selection.
395+
- `agentRuntime`: default low-level agent runtime policy. Omitted id defaults to OpenClaw Pi. Use `id: "pi"` to force the built-in PI harness, `id: "auto"` to let registered plugin harnesses claim supported models and use PI when none match, a registered harness id such as `id: "codex"` to require that harness, or a supported CLI backend alias such as `id: "claude-cli"`. Explicit plugin runtimes fail closed when the harness is unavailable or fails. Keep model refs canonical as `provider/model`; select Codex, Claude CLI, Gemini CLI, and other execution backends through runtime config instead of legacy runtime provider prefixes. See [Agent runtimes](/concepts/agent-runtimes) for how this differs from provider/model selection.
397396
- 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.
398397
- `maxConcurrent`: max parallel agent runs across sessions (each session still serialized). Default: 4.
399398

@@ -412,17 +411,16 @@ model, see [Agent runtimes](/concepts/agent-runtimes).
412411
model: "openai/gpt-5.5",
413412
agentRuntime: {
414413
id: "codex",
415-
fallback: "none",
416414
},
417415
},
418416
},
419417
}
420418
```
421419

422420
- `id`: `"auto"`, `"pi"`, a registered plugin harness id, or a supported CLI backend alias. The bundled Codex plugin registers `codex`; the bundled Anthropic plugin provides the `claude-cli` CLI backend.
423-
- `fallback`: `"pi"` or `"none"`. In `id: "auto"`, omitted fallback defaults to `"pi"` so old configs can keep using PI when no plugin harness claims a run. In explicit plugin runtime mode, such as `id: "codex"`, omitted fallback defaults to `"none"` so a missing harness fails instead of silently using PI. Runtime overrides do not inherit fallback from a broader scope; set `fallback: "pi"` alongside the explicit runtime when you intentionally want that compatibility fallback. Selected plugin harness failures always surface directly.
424-
- Environment overrides: `OPENCLAW_AGENT_RUNTIME=<id|auto|pi>` overrides `id`; `OPENCLAW_AGENT_HARNESS_FALLBACK=pi|none` overrides fallback for that process.
425-
- For Codex-only deployments, set `model: "openai/gpt-5.5"` and `agentRuntime.id: "codex"`. You may also set `agentRuntime.fallback: "none"` explicitly for readability; it is the default for explicit plugin runtimes.
421+
- `id: "auto"` lets registered plugin harnesses claim supported turns and uses PI when no harness matches. An explicit plugin runtime such as `id: "codex"` requires that harness and fails closed if it is unavailable or fails.
422+
- Environment override: `OPENCLAW_AGENT_RUNTIME=<id|auto|pi>` overrides `id` for that process.
423+
- For Codex-only deployments, set `model: "openai/gpt-5.5"` and `agentRuntime.id: "codex"`.
426424
- For Claude CLI deployments, prefer `model: "anthropic/claude-opus-4-7"` plus `agentRuntime.id: "claude-cli"`. Legacy `claude-cli/claude-opus-4-7` model refs still work for compatibility, but new config should keep provider/model selection canonical and put the execution backend in `agentRuntime.id`.
427425
- Older runtime-policy keys are rewritten to `agentRuntime` by `openclaw doctor --fix`.
428426
- Harness choice is pinned per session id after the first embedded run. Config/env changes affect new or reset sessions, not an existing transcript. Legacy sessions with transcript history but no recorded pin are treated as PI-pinned. `/status` reports the effective runtime, for example `Runtime: OpenClaw Pi Default` or `Runtime: OpenAI Codex`.
@@ -955,7 +953,7 @@ for provider examples and precedence.
955953
thinkingDefault: "high", // per-agent thinking level override
956954
reasoningDefault: "on", // per-agent reasoning visibility override
957955
fastModeDefault: false, // per-agent fast mode override
958-
agentRuntime: { id: "auto", fallback: "pi" },
956+
agentRuntime: { id: "auto" },
959957
params: { cacheRetention: "none" }, // overrides matching defaults.models params by key
960958
tts: {
961959
providers: {

‎docs/help/testing-live.md‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -291,8 +291,8 @@ Docker notes:
291291
- Optional image probe: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1`
292292
- Optional MCP/tool probe: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1`
293293
- Optional Guardian probe: `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1`
294-
- The smoke sets `OPENCLAW_AGENT_HARNESS_FALLBACK=none` so a broken Codex
295-
harness cannot pass by silently falling back to PI.
294+
- The smoke uses `agentRuntime.id: "codex"` so a broken Codex harness cannot
295+
pass by silently falling back to PI.
296296
- Auth: Codex app-server auth from the local Codex subscription login. Docker
297297
smokes can also provide `OPENAI_API_KEY` for non-Codex probes when applicable,
298298
plus optional copied `~/.codex/auth.json` and `~/.codex/config.toml`.
@@ -327,9 +327,8 @@ Docker notes:
327327
`OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` or
328328
`OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0` when you need a narrower debug
329329
run.
330-
- Docker also exports `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, matching the live
331-
test config so legacy aliases or PI fallback cannot hide a Codex harness
332-
regression.
330+
- Docker uses the same explicit Codex runtime config, so legacy aliases or PI
331+
fallback cannot hide a Codex harness regression.
333332

334333
### Recommended live recipes
335334

‎docs/plan/codex-context-engine-harness.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -143,14 +143,14 @@ For engines like lossless-claw, the assembled context should be deterministic
143143
for unchanged inputs. Do not add timestamps, random ids, or nondeterministic
144144
ordering to generated context text.
145145

146-
### PI fallback semantics do not change
146+
### Runtime selection semantics do not change
147147

148148
Harness selection remains as-is:
149149

150150
- `runtime: "pi"` forces PI
151151
- `runtime: "codex"` selects the registered Codex harness
152152
- `runtime: "auto"` lets plugin harnesses claim supported providers
153-
- `fallback: "none"` disables PI fallback when no plugin harness matches
153+
- unmatched `auto` runs use PI
154154

155155
This work changes what happens after the Codex harness is selected.
156156

‎docs/plugins/codex-computer-use.md‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -98,7 +98,6 @@ Computer Use available before a thread starts:
9898
model: "openai/gpt-5.5",
9999
agentRuntime: {
100100
id: "codex",
101-
fallback: "none",
102101
},
103102
},
104103
},

‎docs/plugins/codex-harness.md‎

Lines changed: 5 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,6 @@ Then enable the bundled `codex` plugin and force the Codex runtime:
6161
model: "openai/gpt-5.5",
6262
agentRuntime: {
6363
id: "codex",
64-
fallback: "none",
6564
},
6665
},
6766
},
@@ -305,7 +304,6 @@ adds a separate Codex agent:
305304
defaults: {
306305
agentRuntime: {
307306
id: "auto",
308-
fallback: "pi",
309307
},
310308
},
311309
list: [
@@ -358,8 +356,8 @@ routing.
358356
## Codex-only deployments
359357

360358
Force the Codex harness when you need to prove that every embedded agent turn
361-
uses Codex. Explicit plugin runtimes default to no PI fallback, so
362-
`fallback: "none"` is optional but often useful as documentation:
359+
uses Codex. Explicit plugin runtimes fail closed and are never silently retried
360+
through PI:
363361

364362
```json5
365363
{
@@ -368,7 +366,6 @@ uses Codex. Explicit plugin runtimes default to no PI fallback, so
368366
model: "openai/gpt-5.5",
369367
agentRuntime: {
370368
id: "codex",
371-
fallback: "none",
372369
},
373370
},
374371
},
@@ -382,9 +379,7 @@ OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run
382379
```
383380

384381
With Codex forced, OpenClaw fails early if the Codex plugin is disabled, the
385-
app-server is too old, or the app-server cannot start. Set
386-
`OPENCLAW_AGENT_HARNESS_FALLBACK=pi` only if you intentionally want PI to handle
387-
missing harness selection.
382+
app-server is too old, or the app-server cannot start.
388383

389384
## Per-agent Codex
390385

@@ -397,7 +392,6 @@ auto-selection:
397392
defaults: {
398393
agentRuntime: {
399394
id: "auto",
400-
fallback: "pi",
401395
},
402396
},
403397
list: [
@@ -412,7 +406,6 @@ auto-selection:
412406
model: "openai/gpt-5.5",
413407
agentRuntime: {
414408
id: "codex",
415-
fallback: "none",
416409
},
417410
},
418411
],
@@ -711,7 +704,6 @@ Minimal config:
711704
model: "openai/gpt-5.5",
712705
agentRuntime: {
713706
id: "codex",
714-
fallback: "none",
715707
},
716708
},
717709
},
@@ -1059,9 +1051,8 @@ new configs. Select an `openai/gpt-*` model with
10591051
**OpenClaw uses PI instead of Codex:** `agentRuntime.id: "auto"` can still use PI as the
10601052
compatibility backend when no Codex harness claims the run. Set
10611053
`agentRuntime.id: "codex"` to force Codex selection while testing. A
1062-
forced Codex runtime now fails instead of falling back to PI unless you
1063-
explicitly set `agentRuntime.fallback: "pi"`. Once Codex app-server is
1064-
selected, its failures surface directly without extra fallback config.
1054+
forced Codex runtime fails instead of falling back to PI. Once Codex app-server
1055+
is selected, its failures surface directly.
10651056

10661057
**The app-server is rejected:** upgrade Codex so the app-server handshake
10671058
reports version `0.125.0` or newer. Same-version prereleases or build-suffixed

‎docs/plugins/sdk-agent-harness.md‎

Lines changed: 26 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -201,25 +201,20 @@ model refs remain compatibility aliases for the native harness.
201201
When this mode runs, Codex owns the native thread id, resume behavior,
202202
compaction, and app-server execution. OpenClaw still owns the chat channel,
203203
visible transcript mirror, tool policy, approvals, media delivery, and session
204-
selection. Use `agentRuntime.id: "codex"` without a `fallback` override
205-
when you need to prove that only the Codex app-server path can claim the run.
206-
Explicit plugin runtimes already fail closed by default. Set `fallback: "pi"`
207-
only when you intentionally want PI to handle missing harness selection. Codex
208-
app-server failures already fail directly instead of retrying through PI.
209-
210-
## Disable PI fallback
211-
212-
By default, OpenClaw runs embedded agents with `agents.defaults.agentRuntime`
213-
set to `{ id: "auto", fallback: "pi" }`. In `auto` mode, registered plugin
214-
harnesses can claim a provider/model pair. If none match, OpenClaw falls back
215-
to PI.
216-
217-
In `auto` mode, set `fallback: "none"` when you need missing plugin harness
218-
selection to fail instead of using PI. Explicit plugin runtimes such as
219-
`agentRuntime.id: "codex"` already fail closed by default, unless
220-
`fallback: "pi"` is set in the same config or environment override scope.
221-
Selected plugin harness failures always fail hard. This does not block an
222-
explicit `agentRuntime.id: "pi"` or `OPENCLAW_AGENT_RUNTIME=pi`.
204+
selection. Use `agentRuntime.id: "codex"` when you need to prove that only the
205+
Codex app-server path can claim the run. Explicit plugin runtimes fail closed;
206+
Codex app-server selection failures and runtime failures are not retried through
207+
PI.
208+
209+
## Runtime strictness
210+
211+
By default, OpenClaw runs embedded agents with OpenClaw Pi. In `auto` mode,
212+
registered plugin harnesses can claim a provider/model pair, and PI handles the
213+
turn when none match. Use an explicit plugin runtime such as
214+
`agentRuntime.id: "codex"` when missing harness selection should fail instead
215+
of routing through PI. Selected plugin harness failures always fail hard. This
216+
does not block an explicit `agentRuntime.id: "pi"` or
217+
`OPENCLAW_AGENT_RUNTIME=pi`.
223218

224219
For Codex-only embedded runs:
225220

@@ -236,17 +231,15 @@ For Codex-only embedded runs:
236231
}
237232
```
238233

239-
If you want any registered plugin harness to claim matching models but never
240-
want OpenClaw to silently fall back to PI, keep `runtime: "auto"` and disable
241-
the fallback:
234+
If you want any registered plugin harness to claim matching models and otherwise
235+
use PI, set `id: "auto"`:
242236

243237
```json
244238
{
245239
"agents": {
246240
"defaults": {
247241
"agentRuntime": {
248-
"id": "auto",
249-
"fallback": "none"
242+
"id": "auto"
250243
}
251244
}
252245
}
@@ -259,39 +252,30 @@ Per-agent overrides use the same shape:
259252
{
260253
"agents": {
261254
"defaults": {
262-
"agentRuntime": {
263-
"id": "auto",
264-
"fallback": "pi"
265-
}
255+
"agentRuntime": { "id": "auto" }
266256
},
267257
"list": [
268258
{
269259
"id": "codex-only",
270260
"model": "openai/gpt-5.5",
271-
"agentRuntime": {
272-
"id": "codex",
273-
"fallback": "none"
274-
}
261+
"agentRuntime": { "id": "codex" }
275262
}
276263
]
277264
}
278265
}
279266
```
280267

281-
`OPENCLAW_AGENT_RUNTIME` still overrides the configured runtime. Use
282-
`OPENCLAW_AGENT_HARNESS_FALLBACK=none` to disable PI fallback from the
283-
environment.
268+
`OPENCLAW_AGENT_RUNTIME` still overrides the configured runtime.
284269

285270
```bash
286-
OPENCLAW_AGENT_RUNTIME=codex \
287-
OPENCLAW_AGENT_HARNESS_FALLBACK=none \
288-
openclaw gateway run
271+
OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run
289272
```
290273

291-
With fallback disabled, a session fails early when the requested harness is not
292-
registered, does not support the resolved provider/model, or fails before
293-
producing turn side effects. That is intentional for Codex-only deployments and
294-
for live tests that must prove the Codex app-server path is actually in use.
274+
With an explicit plugin runtime, a session fails early when the requested
275+
harness is not registered, does not support the resolved provider/model, or
276+
fails before producing turn side effects. That is intentional for Codex-only
277+
deployments and for live tests that must prove the Codex app-server path is
278+
actually in use.
295279

296280
This setting only controls the embedded agent harness. It does not disable
297281
image, video, music, TTS, PDF, or other provider-specific model routing.

‎docs/providers/openai.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -196,7 +196,7 @@ Choose your preferred auth method and follow the setup steps.
196196
```bash
197197
openclaw config set plugins.entries.codex '{"enabled":true}' --strict-json --merge
198198
openclaw config set agents.defaults.model.primary openai/gpt-5.5
199-
openclaw config set agents.defaults.agentRuntime '{"id":"codex","fallback":"none"}' --strict-json
199+
openclaw config set agents.defaults.agentRuntime '{"id":"codex"}' --strict-json
200200
```
201201
</Step>
202202
<Step title="Verify Codex auth is available">
@@ -235,7 +235,7 @@ Choose your preferred auth method and follow the setup steps.
235235
agents: {
236236
defaults: {
237237
model: { primary: "openai/gpt-5.5" },
238-
agentRuntime: { id: "codex", fallback: "none" },
238+
agentRuntime: { id: "codex" },
239239
},
240240
},
241241
}

0 commit comments

Comments
 (0)