| ------------- | ------------------------------------- | ------------------------------------------------------------------- |

| Provider | `openai`, `anthropic`, `openai-codex` | How OpenClaw authenticates, discovers models, and names model refs. |

| Model | `gpt-5.5`, `claude-opus-4-6` | The model selected for the agent turn. |

| Agent runtime | `pi`, `codex`, ACP-backed runtimes | The low level loop that executes the prepared turn. |

| Agent runtime | `pi`, `codex`, `claude-cli` | The low level loop or backend that executes the prepared turn. |

| Channel | Telegram, Discord, Slack, WhatsApp | Where messages enter and leave OpenClaw. |

You will also see the word **harness** in code and config. A harness is the

implementation that provides an agent runtime. For example, the bundled Codex

harness implements the `codex` runtime. The config key is still named

`embeddedHarness` for compatibility, but user-facing docs and status output

should generally say runtime.

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`; `openclaw

doctor --fix` 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 `pi` runtime plus registered plugin harnesses such as

`codex`.

- **CLI backends** run a local CLI process while keeping the model ref

canonical. For example, `anthropic/claude-opus-4-7` with

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

## Three things named Codex

| Surface | OpenClaw name/config | What it does |

| ---------------------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------- |

| Codex OAuth provider route | `openai-codex/*` model refs | Uses ChatGPT/Codex subscription OAuth through the normal OpenClaw PI runner. |

| Native Codex app-server runtime | `embeddedHarness.runtime: "codex"` | Runs the embedded agent turn through the bundled Codex app-server harness. |

| Native Codex app-server runtime | `agentRuntime.id: "codex"` | Runs the embedded agent turn through the bundled Codex app-server harness. |

| Codex ACP adapter | `runtime: "acp"`, `agentId: "codex"` | Runs Codex through the external ACP/acpx control plane. Use only when ACP/acpx is explicitly asked. |

| Native Codex chat-control command set | `/codex ...` | Binds, resumes, steers, stops, and inspects Codex app-server threads from chat. |

| OpenAI Platform API route for GPT/Codex-style models | `openai/*` model refs | Uses OpenAI API-key auth unless a runtime override, such as `runtime: "codex"`, runs the turn. |

agents: {

defaults: {

model: "openai/gpt-5.5",

embeddedHarness: {

runtime: "codex",

agentRuntime: {

id: "codex",

},

},

},

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**, use

`openai/<model>` with `embeddedHarness.runtime: "codex"`.

`openai/<model>` with `agentRuntime.id: "codex"`.

3. If the user asks for **Codex OAuth/subscription auth on the normal OpenClaw

runner**, use `openai-codex/<model>` and leave the runtime as PI.

4. If the user explicitly says **ACP**, **acpx**, or **Codex ACP adapter**, use

| You mean... | Use... |

| --------------------------------------- | -------------------------------------------- |

| Codex app-server chat/thread control | `/codex ...` from the bundled `codex` plugin |

| Codex app-server embedded agent runtime | `embeddedHarness.runtime: "codex"` |

| Codex app-server embedded agent runtime | `agentRuntime.id: "codex"` |

| OpenAI Codex OAuth on the PI runner | `openai-codex/*` model refs |

| Claude Code or other external harness | ACP/acpx |

1. A session's recorded runtime wins. Config changes do not hot-switch an

existing transcript to a different native thread system.

2. `OPENCLAW_AGENT_RUNTIME=<id>` forces that runtime for new or reset sessions.

3. `agents.defaults.embeddedHarness.runtime` or

`agents.list[].embeddedHarness.runtime` can set `auto`, `pi`, or a registered

runtime id such as `codex`.

3. `agents.defaults.agentRuntime.id` or `agents.list[].agentRuntime.id` can set

`auto`, `pi`, a registered embedded harness id such as `codex`, or a

supported CLI backend alias such as `claude-cli`.

4. In `auto` mode, registered plugin runtimes can claim supported provider/model

pairs.

5. If no runtime claims a turn in `auto` mode and `fallback: "pi"` is set

a broader fallback setting, so an agent-level `runtime: "codex"` is not silently

routed back to PI just because defaults used `fallback: "pi"`.

CLI backend aliases are different from embedded harness ids. The preferred

Claude CLI form is:

```json5

{

agents: {

defaults: {

model: "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 `agentRuntime.id`.

`auto` mode is intentionally conservative. Plugin runtimes can claim

provider/model pairs they understand, but the Codex plugin does not claim the

`openai-codex` provider in `auto` mode. That keeps

If `openclaw doctor` warns that the `codex` plugin is enabled while

`openai-codex/*` 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 `openai/<model>` plus `runtime: "codex"` only when you want native

Switch to `openai/<model>` plus `agentRuntime.id: "codex"` only when you want native

Codex app-server execution.

## Compatibility contract