From 1c550add65fa1b9432976d1c62e925bf9b360d07 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-sync[bot]" Date: Thu, 23 Apr 2026 15:57:39 +0000 Subject: [PATCH] chore(sync): mirror docs from openclaw/openclaw@17138392885935a0fbf01dd1ed95462db6292e37 --- .openclaw-sync/source.json | 4 ++-- docs/gateway/configuration-reference.md | 1 + docs/plugins/codex-harness.md | 18 +++++++++++++++++- docs/plugins/sdk-agent-harness.md | 17 +++++++++++++---- 4 files changed, 33 insertions(+), 7 deletions(-) diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json index be7054f28..e7f7e45b7 100644 --- a/.openclaw-sync/source.json +++ b/.openclaw-sync/source.json @@ -1,5 +1,5 @@ { "repository": "openclaw/openclaw", - "sha": "f58e0176ca2eed34ffab5a162d25e473cbac509a", - "syncedAt": "2026-04-23T15:45:00.261Z" + "sha": "17138392885935a0fbf01dd1ed95462db6292e37", + "syncedAt": "2026-04-23T15:55:53.190Z" } diff --git a/docs/gateway/configuration-reference.md b/docs/gateway/configuration-reference.md index a05e38713..0890d6e50 100644 --- a/docs/gateway/configuration-reference.md +++ b/docs/gateway/configuration-reference.md @@ -1271,6 +1271,7 @@ Codex app-server harness. - `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"`. +- 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` shows non-PI harness ids such as `codex` next to `Fast`. - 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`): diff --git a/docs/plugins/codex-harness.md b/docs/plugins/codex-harness.md index bcf000a89..678109fa4 100644 --- a/docs/plugins/codex-harness.md +++ b/docs/plugins/codex-harness.md @@ -51,6 +51,21 @@ The Codex harness only claims `codex/*` model refs. Existing `openai/*`, `openai-codex/*`, Anthropic, Gemini, xAI, local, and custom provider refs keep their normal paths. +Harness selection is not a live session control. When an embedded turn runs, +OpenClaw records the selected harness id on that session and keeps using it for +later turns in the same session id. Change `embeddedHarness` config or +`OPENCLAW_AGENT_RUNTIME` when you want future sessions to use another harness; +use `/new` or `/reset` to start a fresh session before switching an existing +conversation between PI and Codex. This avoids replaying one transcript through +two incompatible native session systems. + +Legacy sessions created before harness pins are treated as PI-pinned once they +have transcript history. Use `/new` or `/reset` to opt that conversation into +Codex after changing config. + +`/status` shows the effective non-PI harness next to `Fast`, for example +`Fast ยท codex`. The default PI harness is omitted. + ## Requirements - OpenClaw with the bundled `codex` plugin available. @@ -218,7 +233,8 @@ auto-selection: Use normal session commands to switch agents and models. `/new` creates a fresh OpenClaw session and the Codex harness creates or resumes its sidecar app-server -thread as needed. `/reset` clears the OpenClaw session binding for that thread. +thread as needed. `/reset` clears the OpenClaw session binding for that thread +and lets the next turn resolve the harness from current config again. ## Model discovery diff --git a/docs/plugins/sdk-agent-harness.md b/docs/plugins/sdk-agent-harness.md index 455d50ed5..e654ca1d6 100644 --- a/docs/plugins/sdk-agent-harness.md +++ b/docs/plugins/sdk-agent-harness.md @@ -87,11 +87,14 @@ export default definePluginEntry({ OpenClaw chooses a harness after provider/model resolution: -1. `OPENCLAW_AGENT_RUNTIME=` forces a registered harness with that id. -2. `OPENCLAW_AGENT_RUNTIME=pi` forces the built-in PI harness. -3. `OPENCLAW_AGENT_RUNTIME=auto` asks registered harnesses if they support the +1. An existing session's recorded harness id wins, so config/env changes do not + hot-switch that transcript to another runtime. +2. `OPENCLAW_AGENT_RUNTIME=` forces a registered harness with that id for + sessions that are not already pinned. +3. `OPENCLAW_AGENT_RUNTIME=pi` forces the built-in PI harness. +4. `OPENCLAW_AGENT_RUNTIME=auto` asks registered harnesses if they support the resolved provider/model. -4. If no registered harness matches, OpenClaw uses PI unless PI fallback is +5. If no registered harness matches, OpenClaw uses PI unless PI fallback is disabled. Plugin harness failures surface as run failures. In `auto` mode, PI fallback is @@ -100,6 +103,12 @@ 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 selected harness id is persisted with the session id after an embedded run. +Legacy sessions created before harness pins are treated as PI-pinned once they +have transcript history. Use a new/reset session when changing between PI and a +native plugin harness. `/status` shows non-default harness ids such as `codex` +next to `Fast`; PI stays hidden because it is the default compatibility path. + 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 or operator config, not in the shared runtime selector.