Skip to content

Commit aa27e27

Browse files
vincentkocvincentkoc
authored
fix(models): normalize provider runtime selection (#71259)
* fix(models): normalize provider runtime selection * fix(models): reverse codex-only runtime migration * fix(models): default runtime selection to pi * fix(status): label model runtime clearly * fix(status): align pi runtime label * fix(plugins): align tool result middleware runtime naming * fix(models): validate runtime overrides
1 parent 60e7b69 commit aa27e27

75 files changed

Lines changed: 1398 additions & 390 deletions

File tree

Some content is hidden

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

‎CHANGELOG.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -98,7 +98,7 @@ Docs: https://docs.openclaw.ai
9898
- Plugins/Google Chat: log webhook auth rejection reasons only after all candidates fail, and warn when add-on `appPrincipal` values do not match configuration. Fixes #71078. (#71145) Thanks @luyao618.
9999
- Models/configure: preserve the existing default model when provider auth is re-run from configure while keeping explicit default-setting commands authoritative. Fixes #70696. (#70793) Thanks @Sathvik-1007.
100100
- Config/plugins: accept `plugins.entries.*.hooks.allowConversationAccess` in validation, generated schema metadata, and plugin policy inspection so trusted external plugins can enable conversation-access hooks such as `agent_end` without local schema patches. Fixes #71215. (#71221) Thanks @BillChirico.
101-
- Codex harness/models: keep legacy `codex/*` harness shorthand out of model picker and `/models` choice surfaces while migrating primary legacy refs to canonical `openai/*` plus explicit Codex harness config. (#71193) Thanks @vincentkoc.
101+
- Models/runtime: show one model provider choice per provider and move Codex, Claude CLI, and Gemini CLI execution into explicit runtime selection while keeping fallback-only legacy runtime refs unchanged. Thanks @vincentkoc.
102102
- Plugins/runtime deps: respect explicit plugin and channel disablement when repairing bundled runtime dependencies, so doctor and health checks no longer install deps for disabled configured channels. Thanks @vincentkoc.
103103
- Diagnostics/OTEL: export logs through bounded diagnostic log events instead of a direct logger transport hook. Thanks @vincentkoc.
104104
- WhatsApp/plugins: support an explicit opt-in for inbound `message_received` hooks with canonical channel, conversation, session, and sender fields. Thanks @vincentkoc.

‎docs/.generated/plugin-sdk-api-baseline.sha256‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,2 @@
1-
eb5c790aaa54be7b1380eb5a162db50dd314e052aedb5e608290092c33d999f2 plugin-sdk-api-baseline.json
2-
0d2fd80f69e0c3488b6bdbbbb035b08ab108637790d1f30b8e4f84c71c5bc8e2 plugin-sdk-api-baseline.jsonl
1+
f74435d49aa0af2509264d8581e12ffc624b1d6542d250d608ee5c3b41a234f3 plugin-sdk-api-baseline.json
2+
df33bbe47bb092ed11814576b5386253140f7aa6f8479a5334aff9b988125afc plugin-sdk-api-baseline.jsonl

‎docs/channels/discord.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -305,7 +305,7 @@ By default, components are single use. Set `components.reusable=true` to allow b
305305

306306
To restrict who can click a button, set `allowedUsers` on that button (Discord user IDs, tags, or `*`). When configured, unmatched users receive an ephemeral denial.
307307

308-
The `/model` and `/models` slash commands open an interactive model picker with provider and model dropdowns plus a Submit step. `/models add` is deprecated and now returns a deprecation message instead of registering models from chat. The picker reply is ephemeral and only the invoking user can use it.
308+
The `/model` and `/models` slash commands open an interactive model picker with provider, model, and compatible runtime dropdowns plus a Submit step. `/models add` is deprecated and now returns a deprecation message instead of registering models from chat. The picker reply is ephemeral and only the invoking user can use it.
309309

310310
File attachments:
311311

‎docs/cli/status.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ Notes:
2121

2222
- `--deep` runs live probes (WhatsApp Web + Telegram + Discord + Slack + Signal).
2323
- `--usage` prints normalized provider usage windows as `X% left`.
24-
- Session status output now separates `Runtime:` from `Runner:`. `Runtime` is the execution path and sandbox state (`direct`, `docker/*`), while `Runner` tells you whether the session is using embedded Pi, a CLI-backed provider, or an ACP harness backend such as `codex (acp/acpx)`.
24+
- Session status output separates `Execution:` from `Runtime:`. `Execution` is the sandbox path (`direct`, `docker/*`), while `Runtime` tells you whether the session is using `OpenClaw Pi Default`, `OpenAI Codex`, a CLI backend, or an ACP backend such as `codex (acp/acpx)`.
2525
- MiniMax's raw `usage_percent` / `usagePercent` fields are remaining quota, so OpenClaw inverts them before display; count-based fields win when present. `model_remains` responses prefer the chat-model entry, derive the window label from timestamps when needed, and include the model name in the plan label.
2626
- When the current session snapshot is sparse, `/status` can backfill token and cache counters from the most recent transcript usage log. Existing nonzero live values still win over transcript fallback values.
2727
- Transcript fallback can also recover the active runtime model label when the live session entry is missing it. If that transcript model differs from the selected model, status resolves the context window against the recovered runtime model instead of the selected one.

‎docs/concepts/model-providers.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,12 @@ For model selection rules, see [/concepts/models](/concepts/models).
2424
- Plugin auto-enable follows that same boundary: `openai-codex/<model>` belongs
2525
to the OpenAI plugin, while the Codex plugin is enabled by
2626
`embeddedHarness.runtime: "codex"` or legacy `codex/<model>` refs.
27+
- CLI runtimes use the same split: choose canonical model refs such as
28+
`anthropic/claude-*`, `google/gemini-*`, or `openai/gpt-*`, then set
29+
`agents.defaults.embeddedHarness.runtime` to `claude-cli`,
30+
`google-gemini-cli`, or `codex-cli` when you want a local CLI backend.
31+
Legacy `claude-cli/*`, `google-gemini-cli/*`, and `codex-cli/*` refs migrate
32+
back to canonical provider refs with the runtime recorded separately.
2733
- GPT-5.5 is currently available through subscription/OAuth routes:
2834
`openai-codex/gpt-5.5` in PI or `openai/gpt-5.5` with the Codex app-server
2935
harness. The direct API-key route for `openai/gpt-5.5` is supported once

‎docs/gateway/config-agents.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -316,7 +316,7 @@ Time format in system prompt. Default: `auto` (OS preference).
316316
},
317317
params: { cacheRetention: "long" }, // global default provider params
318318
embeddedHarness: {
319-
runtime: "auto", // auto | pi | registered harness id, e.g. codex
319+
runtime: "pi", // pi | auto | registered harness id, e.g. codex
320320
fallback: "pi", // pi | none
321321
},
322322
pdfMaxBytesMb: 10,
@@ -369,14 +369,14 @@ Time format in system prompt. Default: `auto` (OS preference).
369369
- For direct OpenAI Responses models, server-side compaction is enabled automatically. Use `params.responsesServerCompaction: false` to stop injecting `context_management`, or `params.responsesCompactThreshold` to override the threshold. See [OpenAI server-side compaction](/providers/openai#server-side-compaction-responses-api).
370370
- `params`: global default provider parameters applied to all models. Set at `agents.defaults.params` (e.g. `{ cacheRetention: "long" }`).
371371
- `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.
372-
- `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"`. Automatic PI fallback defaults to `"pi"` only in `auto` mode. Explicit plugin runtimes such as `codex` default to `"none"` unless you set `fallback: "pi"`. New Codex harness configs should keep model refs canonical as `openai/*` and select the harness here rather than using legacy `codex/*` model refs.
372+
- `embeddedHarness`: default low-level embedded agent runtime policy. Omitted runtime defaults to OpenClaw Pi. Use `runtime: "pi"` to force the built-in PI harness, `runtime: "auto"` to let registered plugin harnesses claim supported models, or a registered harness id such as `runtime: "codex"`. Set `fallback: "none"` to disable automatic PI fallback. 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.
373373
- 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.
374374
- `maxConcurrent`: max parallel agent runs across sessions (each session still serialized). Default: 4.
375375

376376
### `agents.defaults.embeddedHarness`
377377

378378
`embeddedHarness` controls which low-level executor runs embedded agent turns.
379-
Most deployments should keep the default `{ runtime: "auto", fallback: "pi" }`.
379+
Most deployments should keep the default OpenClaw Pi runtime.
380380
Use it when a trusted plugin provides a native harness, such as the bundled
381381
Codex app-server harness.
382382

‎docs/plugins/building-plugins.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -172,8 +172,8 @@ For the full registration API, see [SDK Overview](/plugins/sdk-overview#registra
172172

173173
Bundled plugins can use `api.registerAgentToolResultMiddleware(...)` when they
174174
need async tool-result rewriting before the model sees the output. Declare the
175-
targeted harnesses in `contracts.agentToolResultMiddleware`, for example
176-
`["pi", "codex-app-server"]`. This is a trusted bundled-plugin seam; external
175+
targeted runtimes in `contracts.agentToolResultMiddleware`, for example
176+
`["pi", "codex"]`. This is a trusted bundled-plugin seam; external
177177
plugins should prefer regular OpenClaw plugin hooks unless OpenClaw grows an
178178
explicit trust policy for this capability.
179179

‎docs/plugins/codex-harness.md‎

Lines changed: 12 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ These are in-process OpenClaw hooks, not Codex `hooks.json` command hooks:
2525
- `before_message_write` for mirrored transcript records
2626
- `agent_end`
2727

28-
Plugins can also register harness-neutral tool-result middleware to rewrite
28+
Plugins can also register runtime-neutral tool-result middleware to rewrite
2929
OpenClaw dynamic tool results after OpenClaw executes the tool and before the
3030
result is returned to Codex. This is separate from the public
3131
`tool_result_persist` plugin hook, which transforms OpenClaw-owned transcript
@@ -35,8 +35,8 @@ The harness is off by default. New configs should keep OpenAI model refs
3535
canonical as `openai/gpt-*` and explicitly force
3636
`embeddedHarness.runtime: "codex"` or `OPENCLAW_AGENT_RUNTIME=codex` when they
3737
want native app-server execution. Legacy `codex/*` model refs still auto-select
38-
the harness for compatibility, but they are not shown as normal model/provider
39-
choices.
38+
the harness for compatibility, but runtime-backed legacy provider prefixes are
39+
not shown as normal model/provider choices.
4040

4141
## Pick the right model prefix
4242

@@ -56,10 +56,12 @@ app-server harness. Direct API-key access for `openai/gpt-5.5` is supported
5656
once OpenAI enables GPT-5.5 on the public API.
5757

5858
Legacy `codex/gpt-*` refs remain accepted as compatibility aliases. Doctor
59-
compatibility migration rewrites legacy primary `codex/*` refs to `openai/*`
60-
and records the Codex harness policy separately. New PI Codex OAuth configs
61-
should use `openai-codex/gpt-*`; new native app-server harness configs should
62-
use `openai/gpt-*` plus `embeddedHarness.runtime: "codex"`.
59+
compatibility migration rewrites legacy primary runtime refs to canonical model
60+
refs and records the runtime policy separately, while fallback-only legacy refs
61+
are left unchanged because runtime is configured for the whole agent container.
62+
New PI Codex OAuth configs should use `openai-codex/gpt-*`; new native
63+
app-server harness configs should use `openai/gpt-*` plus
64+
`embeddedHarness.runtime: "codex"`.
6365

6466
`agents.defaults.imageModel` follows the same prefix split. Use
6567
`openai-codex/gpt-*` when image understanding should run through the OpenAI
@@ -86,9 +88,9 @@ Legacy sessions created before harness pins are treated as PI-pinned once they
8688
have transcript history. Use `/new` or `/reset` to opt that conversation into
8789
Codex after changing config.
8890

89-
`/status` shows the effective non-PI harness next to `Fast`, for example
90-
`Fast · codex`. The default PI harness remains `Runner: pi (embedded)` and does
91-
not add a separate harness badge.
91+
`/status` shows the effective model runtime. The default PI harness appears as
92+
`Runtime: OpenClaw Pi Default`, and the Codex app-server harness appears as
93+
`Runtime: OpenAI Codex`.
9294

9395
## Requirements
9496

‎docs/plugins/manifest.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -406,7 +406,7 @@ read without importing the plugin runtime.
406406
```json
407407
{
408408
"contracts": {
409-
"agentToolResultMiddleware": ["pi", "codex-app-server"],
409+
"agentToolResultMiddleware": ["pi", "codex"],
410410
"externalAuthProviders": ["acme-ai"],
411411
"speechProviders": ["openai"],
412412
"realtimeTranscriptionProviders": ["openai"],
@@ -427,7 +427,7 @@ Each list is optional:
427427
| Field | Type | What it means |
428428
| -------------------------------- | ---------- | --------------------------------------------------------------------- |
429429
| `embeddedExtensionFactories` | `string[]` | Deprecated embedded extension factory ids. |
430-
| `agentToolResultMiddleware` | `string[]` | Harness ids a bundled plugin may register tool-result middleware for. |
430+
| `agentToolResultMiddleware` | `string[]` | Runtime ids a bundled plugin may register tool-result middleware for. |
431431
| `externalAuthProviders` | `string[]` | Provider ids whose external auth profile hook this plugin owns. |
432432
| `speechProviders` | `string[]` | Speech provider ids this plugin owns. |
433433
| `realtimeTranscriptionProviders` | `string[]` | Realtime-transcription provider ids this plugin owns. |

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -146,15 +146,15 @@ OpenClaw only runs against the protocol surface it has been tested with.
146146

147147
### Tool-result middleware
148148

149-
Bundled plugins can attach harness-neutral tool-result middleware through
149+
Bundled plugins can attach runtime-neutral tool-result middleware through
150150
`api.registerAgentToolResultMiddleware(...)` when their manifest declares the
151-
targeted harness ids in `contracts.agentToolResultMiddleware`. This trusted
151+
targeted runtime ids in `contracts.agentToolResultMiddleware`. This trusted
152152
seam is for async tool-result transforms that must run before PI or Codex feeds
153153
tool output back into the model.
154154

155155
Legacy bundled plugins can still use
156156
`api.registerCodexAppServerExtensionFactory(...)` for Codex app-server-only
157-
middleware, but new result transforms should use the harness-neutral API.
157+
middleware, but new result transforms should use the runtime-neutral API.
158158
The Pi-only `api.registerEmbeddedExtensionFactory(...)` hook is deprecated for
159159
tool-result transforms; keep it only for bundled compatibility code that still
160160
needs direct Pi embedded-runner events.

0 commit comments

Comments
 (0)