OpenClaw agent runtimes

Four labels sit close together in OpenClaw status output and configuration, and they mean four different things. A provider describes how OpenClaw authenticates, discovers models and names model refs. A model is the one selected for the agent turn. An agent runtime is the low-level loop or backend that executes the prepared turn, and a channel is simply where messages enter and leave OpenClaw. Runtimes are the layer people misread most often, because they appear near model configuration and carry names that overlap with provider names.

Two runtime families

• Embedded harnesses run inside the prepared agent loop and include the built-in OpenClaw runtime plus registered plugin harnesses such as the Codex and Copilot runtimes.
• CLI backends run a local CLI process while keeping the model ref canonical, so an Anthropic model carrying a model-scoped Claude CLI runtime means select the Anthropic model and execute through Claude CLI.
• A harness is the implementation that provides an agent runtime, which is why the bundled Codex harness implements the Codex runtime, and why the Claude CLI id is not an embedded harness id and must not be passed to harness selection.
• Public configuration puts the runtime id on provider or model entries, whole-agent runtime keys are legacy and ignored, and the doctor repair command removes old whole-agent runtime pins and rewrites legacy runtime model refs to canonical provider and model refs plus model-scoped runtime policy where needed.

Runtimes are easy to confuse with providers because both show up near model configuration.

How a runtime is selected

OpenClaw resolves an embedded runtime only after provider and model resolution, and the order is fixed. Model-scoped runtime policy wins first, whether it lives in a configured provider model entry or in the per model runtime setting on agent defaults or on one specific agent. A provider wildcard applies after exact model policy, so dynamically discovered provider models can share one runtime without overriding exact per model exceptions. Provider-scoped runtime policy comes next. In automatic mode, registered plugin runtimes can claim supported provider and model pairs, and if nothing claims the turn OpenClaw falls back to its own runtime as the compatibility runtime, which is why an explicit runtime id is the right move when a run must be strict. Explicit provider and model plugin runtimes fail closed when the harness is missing or cannot support the route or the authentication, with one selection-time exception: a harness may declare that OpenClaw can reproduce the exact request, and Codex uses that fallback for authored request overrides such as headers, request parameters, timeouts or payload compatibility switches, preserving them instead of dropping them silently. Once a harness starts executing, its failures are not replayed through another runtime. Historical harness records tell you which runtime produced a transcript but do not pin the next turn, and the opt-in Copilot runtime is never selected automatically at all.

Who owns what

• With the embedded OpenClaw runtime, OpenClaw owns the model loop, the canonical transcript, the native tool loop, context assembly and channel delivery.
• With the Codex app-server runtime, Codex owns the model loop and the canonical thread while OpenClaw keeps a transcript mirror, bridges its dynamic tools through the Codex adapter and projects assembled context into the Codex turn.
• Compaction follows the same split, since OpenClaw or the selected context engine handles it in the embedded case while Codex-native compaction runs in the other, with OpenClaw notifications and mirror maintenance around it.

The design rule behind that table is short. If OpenClaw owns the surface it can provide normal plugin hook behaviour, if the native runtime owns the surface OpenClaw needs runtime events or native hooks, and if the native runtime owns canonical thread state OpenClaw mirrors and projects context rather than rewriting internals it does not control. See model providers and model refs for how model refs are named, and the agent loop and turn execution for how a prepared turn is driven.

Why the labels stay separate

Keeping the layers apart is not pedantry, it is what makes a support conversation possible. A model ref points at the selected provider and model, a runtime id names the loop executing the turn, and a channel label says where the conversation is happening, so when a run shows an unexpected runtime the first thing to inspect is the selected provider and model runtime policy. The page is careful about what a locked concrete model chat means as well: the lock prevents model changes, it does not hand model or authentication ownership to a native runtime, and authored request settings remain part of the concrete request. A bound native session is the other case, keeping its native model and, separately, its native connection authentication, verified against the exact pinned harness and its private binding rather than a previous usage report. Next-turn runtime metadata can include a declared fallback when the registered harness can determine it from the configured route, but it does not probe credentials or start a runtime, and the completed result records the runtime that actually ran. When a runtime is not OpenClaw, its own documentation is expected to state which surfaces it supports, including what compaction data is exposed and whether the context engine lifecycle runs, and the guides on context compaction and the context engine lifecycle fill in the rest so nobody assumes equivalence that was never claimed.

On Diali

On Diali the runtime configuration is generated from the dashboard and replaced at each release, so the provider, model and runtime choices behind an assistant stay in one place. Each customer runs their own assistant, with state on a persistent volume; daily snapshots and one-click restore are available through the Backups add-on (included on Max). See Hosted OpenClaw on Diali for what we host, and Diali security for how we treat that state.

• Provider, model, agent runtime and channel are four separate layers.
• Model-scoped policy wins, then provider policy, then automatic claiming.
• A locked model chat prevents model changes, not authentication ownership.