From 6d4f65c9d41b5ab39fa01b66e848ea9d0e6291d0 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sun, 26 Apr 2026 04:38:39 +0100 Subject: [PATCH] docs: clarify codex runtime routing --- docs/concepts/agent-runtimes.md | 43 ++++++++++++++++++ docs/gateway/doctor.md | 12 +++++ docs/plugins/codex-harness.md | 80 +++++++++++++++++++++++++++++++++ docs/providers/openai.md | 53 ++++++++++++++++++---- docs/tools/acp-agents-setup.md | 14 ++++++ docs/tools/acp-agents.md | 19 ++++++++ 6 files changed, 212 insertions(+), 9 deletions(-) diff --git a/docs/concepts/agent-runtimes.md b/docs/concepts/agent-runtimes.md index 2dd067f5b8e..c22d57a4de3 100644 --- a/docs/concepts/agent-runtimes.md +++ b/docs/concepts/agent-runtimes.md @@ -27,6 +27,24 @@ 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. +## Three things named Codex + +Most confusion comes from three different surfaces sharing the Codex name: + +| 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. | +| 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. | + +Those surfaces are intentionally independent. Enabling the `codex` plugin makes +the native app-server features available; it does not rewrite +`openai-codex/*` into `openai/*`, does not change existing sessions, and does +not make ACP the Codex default. Selecting `openai-codex/*` means "use the Codex +OAuth provider route" unless you separately force a runtime. + The common Codex setup uses the `openai` provider with the `codex` runtime: ```json5 @@ -53,6 +71,19 @@ 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**, use + `openai/` with `embeddedHarness.runtime: "codex"`. +3. If the user asks for **Codex OAuth/subscription auth on the normal OpenClaw + runner**, use `openai-codex/` and leave the runtime as PI. +4. If the user explicitly says **ACP**, **acpx**, or **Codex ACP adapter**, use + ACP with `runtime: "acp"` and `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. + | You mean... | Use... | | --------------------------------------- | -------------------------------------------- | | Codex app-server chat/thread control | `/codex ...` from the bundled `codex` plugin | @@ -106,6 +137,18 @@ Explicit plugin runtimes fail closed by default. For example, a broader fallback setting, so an agent-level `runtime: "codex"` is not silently routed back to PI just because defaults used `fallback: "pi"`. +`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 +`openai-codex/*` as the explicit PI Codex OAuth route and avoids silently +moving subscription-auth configs onto the native app-server harness. + +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/` plus `runtime: "codex"` 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. diff --git a/docs/gateway/doctor.md b/docs/gateway/doctor.md index 3dc59c5f380..057a4bf703a 100644 --- a/docs/gateway/doctor.md +++ b/docs/gateway/doctor.md @@ -269,6 +269,18 @@ warns and points to the explicit app-server shape: `openai/*` plus `embeddedHarness.runtime: "codex"` or `OPENCLAW_AGENT_RUNTIME=codex`. +Doctor does not repair this automatically because both routes are valid: + +- `openai-codex/*` + PI means "use Codex OAuth/subscription auth through the + normal OpenClaw runner." +- `openai/*` + `runtime: "codex"` means "run the embedded turn through native + Codex app-server." +- `/codex ...` means "control or bind a native Codex conversation from chat." +- `/acp ...` or `runtime: "acp"` means "use the external ACP/acpx adapter." + +If the warning appears, choose the route you intended and edit config manually. +Keep the warning as-is when PI Codex OAuth is intentional. + ### 3) Legacy state migrations (disk layout) Doctor can migrate older on-disk layouts into the current structure: diff --git a/docs/plugins/codex-harness.md b/docs/plugins/codex-harness.md index 1c94739209e..2dabb42b0bf 100644 --- a/docs/plugins/codex-harness.md +++ b/docs/plugins/codex-harness.md @@ -20,6 +20,27 @@ If you are trying to orient yourself, start with `openai/gpt-5.5` is the model ref, `codex` is the runtime, and Telegram, Discord, Slack, or another channel remains the communication surface. +## What this plugin changes + +The bundled `codex` plugin contributes several separate capabilities: + +| Capability | How you use it | What it does | +| --------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------- | +| Native embedded runtime | `embeddedHarness.runtime: "codex"` | Runs OpenClaw embedded agent turns through Codex app-server. | +| Native chat-control commands | `/codex bind`, `/codex resume`, `/codex steer`, ... | Binds and controls Codex app-server threads from a messaging conversation. | +| Codex app-server provider/catalog | `codex` internals, surfaced through the harness | Lets the runtime discover and validate app-server models. | +| Codex media-understanding path | `codex/*` image-model compatibility paths | Runs bounded Codex app-server turns for supported image understanding models. | +| Native hook relay | Plugin hooks around Codex-native events | Lets OpenClaw observe/block supported Codex-native tool/finalization events. | + +Enabling the plugin makes those capabilities available. It does **not**: + +- start using Codex for every OpenAI model +- convert `openai-codex/*` model refs into the native runtime +- make ACP/acpx the default Codex path +- hot-switch existing sessions that already recorded a PI runtime +- replace OpenClaw channel delivery, session files, auth-profile storage, or + message routing + The same plugin also owns the native `/codex` chat-control command surface. If the plugin is enabled and the user asks to bind, resume, steer, stop, or inspect Codex threads from chat, agents should prefer `/codex ...` over ACP. ACP remains @@ -58,6 +79,27 @@ If the `codex` plugin is enabled but the primary model is still intentional: `openai-codex/*` remains the PI Codex OAuth/subscription path, and native app-server execution stays an explicit runtime choice. +## Route map + +Use this table before changing config: + +| Desired behavior | Model ref | Runtime config | Plugin requirement | Expected status label | +| ------------------------------------------- | -------------------------- | -------------------------------------- | --------------------------- | ------------------------------ | +| OpenAI API through normal OpenClaw runner | `openai/gpt-*` | omitted or `runtime: "pi"` | OpenAI provider | `Runtime: OpenClaw Pi Default` | +| Codex OAuth/subscription through PI | `openai-codex/gpt-*` | omitted or `runtime: "pi"` | OpenAI Codex OAuth provider | `Runtime: OpenClaw Pi Default` | +| Native Codex app-server embedded turns | `openai/gpt-*` | `embeddedHarness.runtime: "codex"` | `codex` plugin | `Runtime: OpenAI Codex` | +| Mixed providers with conservative auto mode | provider-specific refs | `runtime: "auto", fallback: "pi"` | Optional plugin runtimes | Depends on selected runtime | +| Explicit Codex ACP adapter session | ACP prompt/model dependent | `sessions_spawn` with `runtime: "acp"` | healthy `acpx` backend | ACP task/session status | + +The important split is provider versus runtime: + +- `openai-codex/*` answers "which provider/auth route should PI use?" +- `embeddedHarness.runtime: "codex"` answers "which loop should execute this + embedded turn?" +- `/codex ...` answers "which native Codex conversation should this chat bind + or control?" +- ACP answers "which external harness process should acpx launch?" + ## Pick the right model prefix OpenAI-family routes are prefix-specific. Use `openai-codex/*` when you want @@ -96,6 +138,25 @@ and inspect the gateway's structured `agent harness selected` record. It includes the selected harness id, selection reason, runtime/fallback policy, and, in `auto` mode, each plugin candidate's support result. +### What doctor warnings mean + +`openclaw doctor` warns when all of these are true: + +- the bundled `codex` plugin is enabled or allowed +- an agent's primary model is `openai-codex/*` +- that agent's effective runtime is not `codex` + +That warning exists because users often expect "Codex plugin enabled" to imply +"native Codex app-server runtime." OpenClaw does not make that leap. The warning +means: + +- **No change is required** if you intended ChatGPT/Codex OAuth through PI. +- Change the model to `openai/` and set + `embeddedHarness.runtime: "codex"` if you intended native app-server + execution. +- Existing sessions still need `/new` or `/reset` after a runtime change, + because session runtime pins are sticky. + Harness selection is not a live session control. When an embedded turn runs, OpenClaw records the selected harness id on that session and keeps using it for later turns in the same session id. Change `embeddedHarness` config or @@ -232,6 +293,25 @@ With this shape: - If Codex is missing or unsupported for the `codex` agent, the turn fails instead of quietly using PI. +## Agent command routing + +Agents should route user requests by intent, not by the word "Codex" alone: + +| User asks for... | Agent should use... | +| -------------------------------------------------------- | ------------------------------------------------ | +| "Bind this chat to Codex" | `/codex bind` | +| "Resume Codex thread `` here" | `/codex resume ` | +| "Show Codex threads" | `/codex threads` | +| "Use Codex as the runtime for this agent" | config change to `embeddedHarness.runtime` | +| "Use my ChatGPT/Codex subscription with normal OpenClaw" | `openai-codex/*` model refs | +| "Run Codex through ACP/acpx" | ACP `sessions_spawn({ runtime: "acp", ... })` | +| "Start Claude Code/Gemini/OpenCode/Cursor in a thread" | ACP/acpx, not `/codex` and not native sub-agents | + +OpenClaw only advertises ACP spawn guidance to agents when ACP is enabled, +dispatchable, and backed by a loaded runtime backend. If ACP is not available, +the system prompt and plugin skills should not teach the agent about ACP +routing. + ## Codex-only deployments Force the Codex harness when you need to prove that every embedded agent turn diff --git a/docs/providers/openai.md b/docs/providers/openai.md index 2b49c3fb810..f53c068d87c 100644 --- a/docs/providers/openai.md +++ b/docs/providers/openai.md @@ -7,7 +7,13 @@ read_when: title: "OpenAI" --- -OpenAI provides developer APIs for GPT models. OpenClaw supports three OpenAI-family routes. The model prefix selects the route: +OpenAI provides developer APIs for GPT models, and Codex is also available as a +ChatGPT-plan coding agent through OpenAI's Codex clients. OpenClaw keeps those +surfaces separate so config stays predictable. + +OpenClaw supports three OpenAI-family routes. The model prefix selects the +provider/auth route; a separate runtime setting selects who executes the +embedded agent loop: - **API key** — direct OpenAI Platform access with usage-based billing (`openai/*` models) - **Codex subscription through PI** — ChatGPT/Codex sign-in with subscription access (`openai-codex/*` models) @@ -29,6 +35,24 @@ changing config. | Image generation or editing | `openai/gpt-image-2` | Works with either `OPENAI_API_KEY` or OpenAI Codex OAuth. | | Transparent-background images | `openai/gpt-image-1.5` | Use `outputFormat=png` or `webp` and `openai.background=transparent`. | +## Naming map + +The names are similar but not interchangeable: + +| Name you see | Layer | Meaning | +| ---------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------- | +| `openai` | Provider prefix | Direct OpenAI Platform API route. | +| `openai-codex` | Provider prefix | OpenAI Codex OAuth/subscription route through the normal OpenClaw PI runner. | +| `codex` plugin | Plugin | Bundled OpenClaw plugin that provides native Codex app-server runtime and `/codex` chat controls. | +| `embeddedHarness.runtime: codex` | Agent runtime | Force the native Codex app-server harness for embedded turns. | +| `/codex ...` | Chat command set | Bind/control Codex app-server threads from a conversation. | +| `runtime: "acp", agentId: "codex"` | ACP session route | Explicit fallback path that runs Codex through ACP/acpx. | + +This means a config can intentionally contain both `openai-codex/*` and the +`codex` plugin. That is valid when you want Codex OAuth through PI and also want +native `/codex` chat controls available. `openclaw doctor` warns about that +combination so you can confirm it is intentional; it does not rewrite it. + GPT-5.5 is available through both direct OpenAI Platform API-key access and subscription/OAuth routes. Use `openai/gpt-5.5` for direct `OPENAI_API_KEY` @@ -94,10 +118,11 @@ Choose your preferred auth method and follow the setup steps. ### Route summary - | Model ref | Route | Auth | - |-----------|-------|------| - | `openai/gpt-5.5` | Direct OpenAI Platform API | `OPENAI_API_KEY` | - | `openai/gpt-5.4-mini` | Direct OpenAI Platform API | `OPENAI_API_KEY` | + | Model ref | Runtime config | Route | Auth | + | ---------------------- | -------------------------- | --------------------------- | ---------------- | + | `openai/gpt-5.5` | omitted / `runtime: "pi"` | Direct OpenAI Platform API | `OPENAI_API_KEY` | + | `openai/gpt-5.4-mini` | omitted / `runtime: "pi"` | Direct OpenAI Platform API | `OPENAI_API_KEY` | + | `openai/gpt-5.5` | `runtime: "codex"` | Codex app-server harness | Codex app-server | `openai/*` is the direct OpenAI API-key route unless you explicitly force @@ -156,10 +181,11 @@ Choose your preferred auth method and follow the setup steps. ### Route summary - | Model ref | Route | Auth | - |-----------|-------|------| - | `openai-codex/gpt-5.5` | ChatGPT/Codex OAuth through PI | Codex sign-in | - | `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | Codex app-server harness | Codex app-server auth | + | Model ref | Runtime config | Route | Auth | + |-----------|----------------|-------|------| + | `openai-codex/gpt-5.5` | omitted / `runtime: "pi"` | ChatGPT/Codex OAuth through PI | Codex sign-in | + | `openai-codex/gpt-5.5` | `runtime: "auto"` | Still PI unless a plugin explicitly claims `openai-codex` | Codex sign-in | + | `openai/gpt-5.5` | `embeddedHarness.runtime: "codex"` | Codex app-server harness | Codex app-server auth | Keep using the `openai-codex` provider id for auth/profile commands. The @@ -188,6 +214,15 @@ Choose your preferred auth method and follow the setup steps. `/new` or `/reset` after changing `embeddedHarness` if you want `/status` to reflect a new PI/Codex choice. + ### Doctor warning + + If the bundled `codex` plugin is enabled while this tab's + `openai-codex/*` route is selected, `openclaw doctor` warns that the model + still resolves through PI. Keep the config unchanged when that is the + intended subscription-auth route. Switch to `openai/` plus + `embeddedHarness.runtime: "codex"` only when you want native Codex + app-server execution. + ### Context window cap OpenClaw treats model metadata and the runtime context cap as separate values. diff --git a/docs/tools/acp-agents-setup.md b/docs/tools/acp-agents-setup.md index ad71262477c..708801b140b 100644 --- a/docs/tools/acp-agents-setup.md +++ b/docs/tools/acp-agents-setup.md @@ -11,6 +11,20 @@ For the overview, operator runbook, and concepts, see [ACP agents](/tools/acp-ag The sections below cover acpx harness config, plugin setup for the MCP bridges, and permission configuration. +Use this page only when you are setting up the ACP/acpx route. For native Codex +app-server runtime config, use [Codex harness](/plugins/codex-harness). For +OpenAI API keys or Codex OAuth model-provider config, use +[OpenAI](/providers/openai). + +Codex has two OpenClaw routes: + +| Route | Config/command | Setup page | +| -------------------------- | ------------------------------------------------------ | --------------------------------------- | +| Native Codex app-server | `/codex ...`, `embeddedHarness.runtime: "codex"` | [Codex harness](/plugins/codex-harness) | +| Explicit Codex ACP adapter | `/acp spawn codex`, `runtime: "acp", agentId: "codex"` | This page | + +Prefer the native route unless you explicitly need ACP/acpx behavior. + ## acpx harness support (current) Current acpx built-in harness aliases: diff --git a/docs/tools/acp-agents.md b/docs/tools/acp-agents.md index e2a2d3e79cd..bea7cd7252e 100644 --- a/docs/tools/acp-agents.md +++ b/docs/tools/acp-agents.md @@ -20,6 +20,11 @@ If you want Codex or Claude Code to connect as an external MCP client directly to existing OpenClaw channel conversations, use [`openclaw mcp serve`](/cli/mcp) instead of ACP. +ACP is not the default Codex path. It is the external-harness path. The native +Codex app-server plugin owns `/codex ...` controls and the +`embeddedHarness.runtime: "codex"` embedded runtime; ACP owns +`/acp ...` controls and `sessions_spawn({ runtime: "acp" })` sessions. + ## Which page do I want? There are three nearby surfaces that are easy to confuse: @@ -35,6 +40,12 @@ There are three nearby surfaces that are easy to confuse: Usually, yes. Fresh installs ship the bundled `acpx` runtime plugin enabled by default, with a plugin-local pinned `acpx` binary that OpenClaw probes and self-repairs on startup. Run `/acp doctor` for a readiness check. +OpenClaw only teaches agents about ACP spawning when ACP is truly usable: ACP +must be enabled, dispatch must not be disabled, the current session must not be +sandbox-blocked, and a runtime backend must be loaded. If those conditions are +not met, ACP plugin skills and `sessions_spawn` ACP guidance stay hidden so the +agent does not suggest an unavailable backend. + First-run gotchas: - If `plugins.allow` is set, it is a restrictive plugin inventory and must include `acpx`; otherwise the bundled default is intentionally blocked and `/acp doctor` reports the missing allowlist entry. @@ -142,6 +153,14 @@ thread records. Use explicit ACP only when you want the ACP runtime/session model. The embedded Codex support boundary is documented in the [Codex harness v1 support contract](/plugins/codex-harness#v1-support-contract). +For model/provider/runtime selection, remember: + +- `openai-codex/*` is the PI Codex OAuth/subscription route. +- `openai/*` plus `embeddedHarness.runtime: "codex"` is the native Codex + app-server embedded runtime route. +- `/codex ...` is native Codex conversation control. +- `/acp ...` or `runtime: "acp"` is explicit ACP/acpx control. + Natural-language triggers that should route to the ACP runtime: - "Run this as a one-shot Claude Code ACP session and summarize the result."