Agent Runtimes vs Providers: Core Concepts

An agent runtime is responsible for a single prepared model loop. It takes in the prompt, manages model output, executes native tool calls, and hands the completed turn back to OpenClaw.

Runtimes and providers are often mistaken for one another, since both appear around model configuration. In reality, they occupy separate layers:

A harness is the implementation that supplies an agent runtime, in code terms. As an example, the bundled Codex harness provides the codex runtime. Public configuration relies on agentRuntime.id attached to provider or model entries; runtime keys scoped to the whole agent are deprecated and disregarded. openclaw doctor --fix clears out those old whole-agent runtime pins and converts legacy runtime model refs into canonical provider/model refs, adding model-scoped runtime policy where applicable.

Two runtime categories exist:

• Embedded harnesses operate within OpenClaw's prepared agent loop. This includes the built-in openclaw runtime and registered plugin harnesses like codex and copilot.
• CLI backends spin up a local CLI process while preserving the canonical model ref. For instance, anthropic/claude-opus-5 paired with a model-scoped agentRuntime.id: "claude-cli" means "pick the Anthropic model, run it via Claude CLI." claude-cli is not an embedded harness id and should never be handed to AgentHarness selection.

The copilot harness is a separate, opt-in external plugin harness built for the GitHub Copilot CLI. See GitHub Copilot agent runtime for the user-facing comparison between PI, Codex, and GitHub Copilot agent runtime.

Codex surfaces

The Codex name appears across several distinct surfaces:

These surfaces are deliberately kept separate. Turning on the codex plugin exposes the native app-server capabilities; openclaw doctor --fix handles legacy Codex route repair and cleanup of stale session pins. Choosing openai/* for an agent model now translates to "run this through Codex," unless a non-agent OpenAI API surface is in play.

The typical ChatGPT/Codex subscription arrangement relies on Codex OAuth for authentication, while keeping the model ref as openai/* and picking the codex runtime:

{
  agents: {
    defaults: {
      model: "openai/gpt-5.6-sol",
    },
  },
}

In this flow, OpenClaw picks an OpenAI model ref and then asks the Codex app-server runtime to handle the embedded agent turn. This does not imply "use API billing," nor does it turn the channel, model provider catalog, or OpenClaw session store into Codex.

With the bundled codex plugin active, prefer the native /codex command surface (/codex bind, /codex threads, /codex resume, /codex steer, /codex stop) for natural-language Codex control rather than ACP. ACP should be used for Codex only when the user explicitly requests ACP/acpx or is evaluating the ACP adapter path. External harnesses like Claude Code, Gemini CLI, OpenCode, and Cursor continue to rely on ACP.

Decision tree:

1. Codex bind/control/thread/resume/steer/stop -> native /codex command surface when the bundled codex plugin is enabled.
2. Codex as the embedded runtime or the standard subscription-backed Codex agent experience -> openai/<model>.
3. OpenClaw explicitly chosen for an OpenAI model -> retain the model ref as openai/<model> and set provider/model runtime policy to agentRuntime.id: "openclaw". A selected openai OAuth profile is routed internally through OpenClaw's Codex-auth transport.
4. Legacy Codex model refs in config -> fix with openclaw doctor --fix to openai/<model>; doctor preserves the Codex auth route by inserting provider/model-scoped agentRuntime.id: "codex" where the old model ref implied it. Legacy codex-cli/* model refs repair to the same openai/<model> Codex app-server route; OpenClaw no longer ships a bundled Codex CLI backend.
5. ACP, acpx, or Codex ACP adapter explicitly requested -> runtime: "acp" and agentId: "codex".
6. Claude Code, Gemini CLI, OpenCode, Cursor, Droid, or another external harness -> ACP/acpx, not the native sub-agent runtime.

For the OpenAI-family prefix split, refer to OpenAI and Model providers. For the Codex runtime support contract, see Codex harness runtime.

Runtime ownership

How much of the loop each runtime takes on varies:

A design guideline applies: when OpenClaw controls a surface, standard plugin hook behavior is available. When the native runtime controls it, OpenClaw must rely on runtime events or native hooks. If canonical thread state sits with the native runtime, OpenClaw mirrors and projects context instead of rewriting internals it cannot support.

Runtime selection

Runtime resolution for an embedded setup happens after provider and model resolution, following this sequence:

1. Model-scoped runtime policy takes precedence. It is defined in a configured provider model entry, or in agents.defaults.models["provider/model"].agentRuntime / agents.entries.*.models["provider/model"].agentRuntime. A provider wildcard such as agents.defaults.models["vllm/*"].agentRuntime is applied after exact model policy, so dynamically discovered provider models can share one runtime without overriding exact per-model exceptions.
2. Provider-scoped runtime policy: models.providers.<provider>.agentRuntime.
3. auto mode: registered plugin runtimes can claim supported provider/model pairs.
4. If nothing claims the turn in auto mode, OpenClaw falls back to openclaw as the compatibility runtime. Use an explicit runtime id when the run must be strict.

Whole-session and whole-agent runtime pins are ignored: OPENCLAW_AGENT_RUNTIME, session agentHarnessId/agentRuntimeOverride state, agents.defaults.agentRuntime, and agents.entries.*.agentRuntime. Run openclaw doctor --fix to remove stale whole-agent runtime config and convert legacy runtime model refs where intent can be preserved.

Explicit provider/model plugin runtimes fail closed: agentRuntime.id: "codex" on a provider or model means Codex, or a clear selection/runtime error, it is never silently routed back to OpenClaw. Only auto may route an unmatched turn to OpenClaw.

CLI backend aliases differ from embedded harness ids. Preferred Claude CLI form:

{
  agents: {
    defaults: {
      model: "anthropic/claude-opus-5",
      models: {
        "anthropic/claude-opus-5": {
          agentRuntime: { id: "claude-cli" },
        },
      },
    },
  },
}

Legacy refs such as claude-cli/claude-opus-4-7 are accepted as compatibility input, but new config should keep the provider/model canonical and put the execution backend in provider/model runtime policy. Run openclaw doctor --fix to rewrite persisted legacy model selections, model-map keys, and explicit modelPolicy.allow entries to that canonical shape.

Legacy codex-cli/* refs are different: doctor migrates them to openai/* so they run through the Codex app-server harness instead of preserving a Codex CLI backend.

auto mode is intentionally conservative for most providers. OpenAI agent models are the exception: unset runtime and auto both resolve to the Codex harness. Explicit OpenClaw runtime config remains an opt-in compatibility route for openai/* agent turns; when paired with a selected openai OAuth profile, OpenClaw routes that path internally through the Codex-auth transport while keeping the public model ref as openai/*. Stale OpenAI runtime session pins are ignored by runtime selection and can be cleaned with openclaw doctor --fix.

If openclaw doctor warns that the codex plugin is enabled while legacy Codex model refs remain in config, treat that as legacy route state and run openclaw doctor --fix to rewrite it to openai/* with the Codex runtime.

GitHub Copilot agent runtime

The external @openclaw/copilot plugin registers an opt-in copilot runtime backed by the GitHub Copilot CLI (@github/copilot-sdk). It claims the canonical subscription github-copilot provider and is never selected by auto. Opt in per-model or per-provider via agentRuntime.id:

{
  agents: {
    defaults: {
      model: "github-copilot/gpt-5.5",
      models: {
        "github-copilot/gpt-5.5": {
          agentRuntime: { id: "copilot" },
        },
      },
    },
  },
}

The plugin manifest declares the harness provider, runtime, CLI session key, and auth profile prefix without requiring openclaw doctor to load plugin code. For configuration, auth, transcript mirroring, compaction, the declarative doctor contract, and the broader PI vs Codex vs Copilot SDK decision, see GitHub Copilot agent runtime.

Compatibility contract

When a runtime is not OpenClaw, its docs should state which OpenClaw surfaces it supports:

The Codex runtime support contract is documented in Codex harness runtime.

Status labels

Status output can show both Execution and Runtime labels. Read them as diagnostics, not provider names:

• A model ref such as openai/gpt-5.6-sol is the selected provider/model.
• A runtime id such as codex is the loop executing the turn.
• A channel label such as Telegram or Discord is where the conversation is happening.

If a run shows an unexpected runtime, inspect the selected provider/model runtime policy first. Legacy session runtime pins no longer decide routing.

Related

• Codex harness
• Codex harness runtime
• GitHub Copilot agent runtime
• OpenAI
• Agent harness plugins
• Agent loop
• Models
• Status