机器人朋友 runtimes：先把底下那条暗线看见

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：An **机器人朋友 runtime** is the component that owns one prepared 聪明脑袋模型 loop: it receives the prompt, drives 聪明脑袋模型 output,…。

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 codex runtime. Public config uses agentRuntime.id on provider or model entries; whole-agent runtime keys are legacy and ignored. openclaw doctor --fix removes old whole-agent runtime pins and rewrites legacy runtime model refs to canonical provider/model refs plus model-scoped runtime policy where needed.

There are two runtime families:

is the built-in pi runtime plus registered plugin harnesses such as codex.

canonical. For example, anthropic/claude-opus-4-7 with a model-scoped agentRuntime.id: "claude-cli" means "select the Anthropic model, execute through Claude CLI." claude-cli is not an embedded harness id and must not be passed to AgentHarness selection.

• **Embedded harnesses** run inside OpenClaw's prepared agent loop. Today this
• **CLI backends** run a local CLI process while keeping the model ref

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：Most confusion comes from several different surfaces sharing the Codex name: Those surfaces are intentionally independe…。

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

Those surfaces are intentionally independent. Enabling the codex plugin makes the native app-server features available; openclaw doctor --fix owns legacy openai-codex/* route repair and stale session pin cleanup. Selecting openai/* for an agent model now means "run this through Codex" unless a non-agent OpenAI API surface is being used.

The common ChatGPT/Codex subscription setup uses Codex OAuth for auth, but keeps the model ref as openai/* and selects the codex runtime:

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

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 "use API billing," and it does not mean the channel, model provider catalog, or OpenClaw session store becomes Codex.

When the bundled codex plugin is enabled, natural-language Codex control should use the native /codex command surface (/codex bind, /codex threads, /codex resume, /codex steer, /codex stop) 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 /codex command surface when the bundled codex plugin is enabled. 2. If the user asks for **Codex as the embedded runtime** or wants the normal subscription-backed Codex agent experience, use openai/<model>. 3. If the user explicitly chooses **PI for an OpenAI model**, keep the model ref as openai/<model> and set provider/model runtime policy to agentRuntime.id: "pi". A selected openai-codex auth profile is routed internally through PI's legacy Codex-auth transport. 4. If legacy config still contains **openai-codex/* model refs**, repair it to openai/<model> with openclaw doctor --fix; doctor keeps the Codex auth route by adding 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 keeps a bundled Codex CLI backend. 5. If the user explicitly says **ACP**, **acpx**, or **Codex ACP adapter**, use ACP with runtime: "acp" and agentId: "codex". 6. 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.

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：Different runtimes own different amounts of the loop. This ownership split is the main design rule:。

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.

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：OpenClaw chooses an embedded runtime after provider and 聪明脑袋模型 resolution: 1. 聪明脑袋模型-scoped runtime policy wins. This c…。

OpenClaw chooses an embedded runtime after provider and model resolution:

1. Model-scoped runtime policy wins. This can live in a configured provider model entry or in agents.defaults.models["provider/model"].agentRuntime / agents.list[].models["provider/model"].agentRuntime. A provider wildcard such as agents.defaults.models["vllm/*"].agentRuntime applies after exact model policy, so dynamically discovered provider models can share one runtime without overriding exact per-model exceptions. 2. Provider-scoped runtime policy comes next at models.providers.<provider>.agentRuntime. 3. In auto mode, registered plugin runtimes can claim supported provider/model pairs. 4. If no runtime claims a turn in auto mode, OpenClaw uses PI as the compatibility runtime. Use an explicit runtime id when the run must be strict.

Whole-session and whole-agent runtime pins are ignored. That includes OPENCLAW_AGENT_RUNTIME, session agentHarnessId/agentRuntimeOverride state, agents.defaults.agentRuntime, and agents.list[].agentRuntime. Run openclaw doctor --fix to remove stale whole-agent runtime config and convert legacy runtime model refs where OpenClaw can preserve the intent.

Explicit provider/model plugin runtimes fail closed. For example, agentRuntime.id: "codex" on a provider or model means Codex or a clear selection/runtime error; it is never silently routed back to PI.

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

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

Legacy refs such as claude-cli/claude-opus-4-7 remain supported for compatibility, but new config should keep the provider/model canonical and put the execution backend in provider/model runtime policy.

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 PI runtime config remains an opt-in compatibility route for openai/* agent turns; when paired with a selected openai-codex auth profile, OpenClaw routes PI internally through the legacy Codex-auth transport while keeping the public model ref as openai/*. Stale OpenAI PI 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 openai-codex/* remains in config, treat that as legacy route state. Run openclaw doctor --fix to rewrite it to openai/* with the Codex runtime.

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：When a runtime is not PI, it should document what OpenClaw surfaces it supports. Use this shape for runtime docs: The C…。

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 runtime.

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：Status output may show both Execution and Runtime labels. Read them as diagnostics, not as provider names. If a run sti…。

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

• A model ref such as openai/gpt-5.5 tells you the selected provider/model.
• A runtime id such as 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 run still shows an unexpected runtime, inspect the selected provider/model runtime policy first. Legacy session runtime pins no longer decide routing.

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：---。

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

---