Agent runtimes

An agent runtime is the component that owns one prepared model loop: it receives the prompt, drives model output, handles native tool calls, and returns the finished turn to OpenClaw.

Runtimes are easy to confuse with providers because both show up near model configuration. They are different layers:

You will also see the word harness in code. A harness is the implementation that provides an agent runtime. For example, the bundled Codex harness implements the

runtime. Public config uses ; rewrites older runtime-policy keys to that shape.

There are two runtime families:

• Embedded harnesses run inside OpenClaw's prepared agent loop. Today this is the built-in
  text

  Copy

  pi
  runtime plus registered plugin harnesses such as
  text

  Copy

  codex
  .
• CLI backends run a local CLI process while keeping the model ref canonical. For example,
  text

  Copy

  anthropic/claude-opus-4-7
  with
  text

  Copy

  agentRuntime.id: "claude-cli"
  means "select the Anthropic model, execute through Claude CLI."
  text

  Copy

  claude-cli
  is not an embedded harness id and must not be passed to AgentHarness selection.

Three things named Codex

Most confusion comes from three different surfaces sharing the Codex name:

Those surfaces are intentionally independent. Enabling the

plugin makes the native app-server features available; it does not rewrite into , does not change existing sessions, and does not make ACP the Codex default. Selecting means "use the Codex OAuth provider route" unless you separately force a runtime.

The common Codex setup uses the

provider with the runtime:

json5
Copy
{
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
      agentRuntime: {
        id: "codex",
      },
    },
  },
}

That means OpenClaw selects an OpenAI model ref, then asks the Codex app-server runtime to run the embedded agent turn. It does not mean the channel, model provider catalog, or OpenClaw session store becomes Codex.

When the bundled

plugin is enabled, natural-language Codex control should use the native command surface (, , , , ) instead of ACP. Use ACP for Codex only when the user explicitly asks for ACP/acpx or is testing the ACP adapter path. Claude Code, Gemini CLI, OpenCode, Cursor, and similar external harnesses still use ACP.

This is the agent-facing decision tree:

1. If the user asks for Codex bind/control/thread/resume/steer/stop, use the native
   text

   Copy

   /codex
   command surface when the bundled
   text

   Copy

   codex
   plugin is enabled.
2. If the user asks for Codex as the embedded runtime, use
   text

   Copy

   openai/<model>
   with
   text

   Copy

   agentRuntime.id: "codex"
   .
3. If the user asks for Codex OAuth/subscription auth on the normal OpenClaw runner, use
   text

   Copy

   openai-codex/<model>
   and leave the runtime as PI.
4. If the user explicitly says ACP, acpx, or Codex ACP adapter, use ACP with
   text

   Copy

   runtime: "acp"
   and
   text

   Copy

   agentId: "codex"
   .
5. If the request is for Claude Code, Gemini CLI, OpenCode, Cursor, Droid, or another external harness, use ACP/acpx, not the native sub-agent runtime.

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

Runtime ownership

Different runtimes own different amounts of the loop.

This ownership split is the main design rule:

• If OpenClaw owns the surface, OpenClaw can provide normal plugin hook behavior.
• If the native runtime owns the surface, OpenClaw needs runtime events or native hooks.
• If the native runtime owns canonical thread state, OpenClaw should mirror and project context, not rewrite unsupported internals.

Runtime selection

OpenClaw chooses an embedded runtime after provider and model resolution:

1. A session's recorded runtime wins. Config changes do not hot-switch an existing transcript to a different native thread system.
2. text

   Copy

   OPENCLAW_AGENT_RUNTIME=<id>
   forces that runtime for new or reset sessions.
3. text

   Copy

   agents.defaults.agentRuntime.id
   or
   text

   Copy

   agents.list[].agentRuntime.id
   can set
   text

   Copy

   auto
   ,
   text

   Copy

   pi
   , a registered embedded harness id such as
   text

   Copy

   codex
   , or a supported CLI backend alias such as
   text

   Copy

   claude-cli
   .
4. In
   text

   Copy

   auto
   mode, registered plugin runtimes can claim supported provider/model pairs.
5. If no runtime claims a turn in
   text

   Copy

   auto
   mode and
   text

   Copy

   fallback: "pi"
   is set (the default), OpenClaw uses PI as the compatibility fallback. Set
   text

   Copy

   fallback: "none"
   to make unmatched
   text

   Copy

   auto
   -mode selection fail instead.

Explicit plugin runtimes fail closed by default. For example,

means Codex or a clear selection error unless you set in the same override scope. A runtime override does not inherit a broader fallback setting, so an agent-level is not silently routed back to PI just because defaults used .

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

json5
Copy
{
  agents: {
    defaults: {
      model: "anthropic/claude-opus-4-7",
      agentRuntime: { id: "claude-cli" },
    },
  },
}

Legacy refs such as

remain supported for compatibility, but new config should keep the provider/model canonical and put the execution backend in .

mode is intentionally conservative. Plugin runtimes can claim provider/model pairs they understand, but the Codex plugin does not claim the provider in mode. That keeps as the explicit PI Codex OAuth route and avoids silently moving subscription-auth configs onto the native app-server harness.

If

warns that the plugin is enabled while still routes through PI, treat that as a diagnosis, not a migration. Keep the config unchanged when PI Codex OAuth is what you want. Switch to plus only when you want native Codex app-server execution.

Compatibility contract

When a runtime is not PI, it should document what OpenClaw surfaces it supports. Use this shape for runtime docs:

The Codex runtime support contract is documented in Codex harness.

Status labels

Status output may show both

and labels. Read them as diagnostics, not as provider names.

• A model ref such as
  text

  Copy

  openai/gpt-5.5
  tells you the selected provider/model.
• A runtime id such as
  text

  Copy

  codex
  tells you which loop is executing the turn.
• A channel label such as Telegram or Discord tells you where the conversation is happening.

If a session still shows PI after changing runtime config, start a new session with

or clear the current one with . Existing sessions keep their recorded runtime so a transcript is not replayed through two incompatible native session systems.

Related

• Codex harness
• OpenAI
• Agent harness plugins
• Agent loop
• Models
• Status