vultr/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-05-06 09:20:43 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: clarify codex runtime routing

Browse Source
This commit is contained in:
Peter Steinberger
2026-04-26 04:38:39 +01:00
parent 6336ed4166
commit 6d4f65c9d4
6 changed files with 212 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

43
docs/concepts/agent-runtimes.md
View File

@@ -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/<model>` with `embeddedHarness.runtime: "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
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/<model>` 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.

12
docs/gateway/doctor.md
View File

@@ -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:

80
docs/plugins/codex-harness.md
View File

@@ -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/<model>` 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 `<id>` here" | `/codex resume <id>` |
| "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

53
docs/providers/openai.md
View File

@@ -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.
<Note>
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 |
<Note>
`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 |
<Note>
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/<model>` 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.

14
docs/tools/acp-agents-setup.md
View File

@@ -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:

19
docs/tools/acp-agents.md
View File

@@ -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."