OpenClaw Agent Runtimes Explained — PI, Codex, Claude CLI, and ACP

OpenClaw runtime language can get confusing because provider, model, runtime, harness, channel, Codex OAuth, native Codex, and ACP all show up near the same configuration conversation. The agent runtimes docs exist to split those layers cleanly. If you learn one thing, learn this: provider, model, and runtime are not the same thing.

The layers

A provider is how OpenClaw authenticates, discovers models, and names model refs. Examples include openai, anthropic, and openai-codex. A model is the selected model id. An agent runtime is the low-level loop or backend that executes the prepared turn, such as pi, codex, or a CLI backend alias. A channel is where messages enter and leave, such as Slack, Telegram, Discord, or WhatsApp.

Embedded runtimes and CLI backends

Embedded harnesses run inside OpenClaw’s prepared agent loop. The built-in PI runtime is the compatibility path, and plugins can register runtimes such as the bundled Codex app-server harness. CLI backends run a local CLI process while keeping the provider/model ref canonical. The docs prefer keeping the provider/model canonical and putting execution backend in agentRuntime.id.

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

Three things named Codex

Codex has multiple surfaces. openai-codex/* is the Codex OAuth provider route through the normal OpenClaw runner. agentRuntime.id: "codex" is the native Codex app-server runtime. runtime: "acp", agentId: "codex" is the external ACP adapter path. Those are intentionally independent.

The docs’ decision tree is conservative: use native Codex chat/thread control for Codex bind/resume/steer/stop when the plugin is enabled; use openai/<model> plus agentRuntime.id: "codex" for embedded Codex runtime; use openai-codex/* for OAuth on the PI runner; use ACP only when the user explicitly asks for ACP/acpx or the adapter path.

Runtime selection rules

A session’s recorded runtime wins; config changes do not hot-switch an existing transcript. OPENCLAW_AGENT_RUNTIME can force a runtime for new or reset sessions. Defaults or agent config can set auto, pi, registered embedded harness ids, or supported CLI backend aliases. In auto mode, unmatched turns fall back to PI unless fallback is set to none.

My practical advice: write down which layer you are changing before touching config. If you are changing billing/auth, that is provider. If you are changing execution ownership, that is runtime. If you are changing where people talk to the agent, that is channel.

If you are turning model and runtime choices into real operations instead of a demo, The OpenClaw Playbook is the shortcut I wish every operator had: identity files, memory rules, safety boundaries, channel discipline, and production habits in one field-tested guide.

Config review checklist

Before changing runtime config, write the intended layer in one sentence: provider auth, model selection, embedded runtime, external harness, or channel routing. If the sentence uses two layers at once, split the change. That discipline prevents accidental migrations where a billing/auth change also changes execution backend or session behavior.

Do not conflate channels

Channels decide where messages arrive and leave. Runtimes decide how prepared turns execute. A Slack issue is not automatically a model-runtime issue, and a Codex runtime issue is not automatically a Slack issue. Keep those axes separate while debugging, then join them only when evidence says the boundary is involved.

Runbook detail

For OpenClaw Agent Runtimes Explained — PI, Codex, Claude CLI, and ACP, the important operator move is to record the exact documented surface you used and the condition that proves it worked. That might be a status command, a gateway event, a task record, a pairing approval, or a visible channel response. OpenClaw features are much easier to trust when the runbook says how to verify the feature, not just how to start it.

Operator checkpoint

Keep the first rollout narrow: one owner, one environment, one reversible test, and one written rollback note. Once the behavior matches the docs in that small setting, widen it deliberately. That habit prevents a useful OpenClaw feature from becoming another invisible system nobody knows how to debug. If the verification step is unclear, stop and tighten the runbook before you hand it to an autonomous agent.