docs: clarify Codex subscription runtime (#75910)

pashpashpash · web-flow · commit 9fb90f3d2921 · 2026-05-02T11:33:20.000+09:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,7 @@ Docs: https://docs.openclaw.ai
 
 ### Changes
 
+- Docs/Codex: clarify that ChatGPT/Codex subscription setups should use `openai/gpt-*` with `agentRuntime.id: "codex"` for native Codex runtime, while `openai-codex/*` remains the PI OAuth route. Thanks @pashpashpash.
 - Plugins/source checkout: load bundled plugins from the `extensions/*` pnpm workspace tree in source checkouts, so plugin-local dependencies and edits are used directly while packaged installs keep using the built runtime tree. Thanks @vincentkoc.
 - Plugins/beta: prepare Brave, Codex, Feishu, Synology Chat, Tlon, and Twitch for `2026.5.1-beta.1` npm and ClawHub publishing. Thanks @vincentkoc.
 - Providers/xAI: add Grok 4.3 to the bundled catalog and make it the default xAI chat model.
diff --git a/docs/concepts/agent-runtimes.md b/docs/concepts/agent-runtimes.md
@@ -37,25 +37,26 @@ There are two runtime families:
   through Claude CLI." `claude-cli` is not an embedded harness id and must not
   be passed to AgentHarness selection.
 
-## Three things named Codex
+## Codex surfaces
 
-Most confusion comes from three different surfaces sharing the Codex name:
+Most confusion comes from several 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                      | `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.      |
+| Surface                                              | OpenClaw name/config                       | What it does                                                                                               |
+| ---------------------------------------------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
+| Native Codex app-server runtime                      | `openai/*` plus `agentRuntime.id: "codex"` | Runs the embedded agent turn through Codex app-server. This is the usual ChatGPT/Codex subscription setup. |
+| Codex OAuth provider route                           | `openai-codex/*` model refs                | Uses ChatGPT/Codex subscription OAuth through the normal OpenClaw PI runner.                               |
+| 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 `agentRuntime.id: "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:
+The common ChatGPT/Codex subscription setup uses Codex OAuth for auth, but keeps
+the model ref as `openai/*` and selects the `codex` runtime:
 
 ```json5
 {
@@ -71,8 +72,9 @@ The common Codex setup uses the `openai` provider with the `codex` runtime:
 ```
 
 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 the channel, model
-provider catalog, or OpenClaw session store becomes Codex.
+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`,
@@ -85,7 +87,8 @@ 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
+2. If the user asks for **Codex as the embedded runtime** or wants the normal
+   subscription-backed Codex agent experience, use
    `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.
@@ -142,10 +145,10 @@ OpenClaw chooses an embedded runtime after provider and model resolution:
    `fallback: "none"` to make unmatched `auto`-mode selection fail instead.
 
 Explicit plugin runtimes fail closed by default. For example,
-`runtime: "codex"` means Codex or a clear selection error unless you set
+`agentRuntime.id: "codex"` means Codex or a clear selection error unless you set
 `fallback: "pi"` in the same override scope. A runtime override does not inherit
-a broader fallback setting, so an agent-level `runtime: "codex"` is not silently
-routed back to PI just because defaults used `fallback: "pi"`.
+a broader fallback setting, so an agent-level `agentRuntime.id: "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:
diff --git a/docs/concepts/model-providers.md b/docs/concepts/model-providers.md
@@ -29,15 +29,15 @@ Reference for **LLM/model providers** (not chat channels like WhatsApp/Telegram)
   <Accordion title="OpenAI provider/runtime split">
     OpenAI-family routes are prefix-specific:
 
-    - `openai/<model>` uses the direct OpenAI API-key provider in PI.
+    - `openai/<model>` plus `agents.defaults.agentRuntime.id: "codex"` uses the native Codex app-server harness. This is the usual ChatGPT/Codex subscription setup.
     - `openai-codex/<model>` uses Codex OAuth in PI.
-    - `openai/<model>` plus `agents.defaults.agentRuntime.id: "codex"` uses the native Codex app-server harness.
+    - `openai/<model>` without a Codex runtime override uses the direct OpenAI API-key provider in PI.
 
     See [OpenAI](/providers/openai) and [Codex harness](/plugins/codex-harness). If the provider/runtime split is confusing, read [Agent runtimes](/concepts/agent-runtimes) first.
 
     Plugin auto-enable follows the same boundary: `openai-codex/<model>` belongs to the OpenAI plugin, while the Codex plugin is enabled by `agentRuntime.id: "codex"` or legacy `codex/<model>` refs.
 
-    GPT-5.5 is available through `openai/gpt-5.5` for direct API-key traffic, `openai-codex/gpt-5.5` in PI for Codex OAuth, and the native Codex app-server harness when `agentRuntime.id: "codex"` is set.
+    GPT-5.5 is available through the native Codex app-server harness when `agentRuntime.id: "codex"` is set, through `openai-codex/gpt-5.5` in PI for Codex OAuth, and through `openai/gpt-5.5` in PI for direct API-key traffic when your account exposes it.
 
   </Accordion>
   <Accordion title="CLI runtimes">
@@ -148,11 +148,18 @@ Anthropic staff told us OpenClaw-style Claude CLI usage is allowed again, so Ope
 - Shares the same `/fast` toggle and `params.fastMode` config as direct `openai/*`; OpenClaw maps that to `service_tier=priority`
 - `openai-codex/gpt-5.5` uses the Codex catalog native `contextWindow = 400000` and default runtime `contextTokens = 272000`; override the runtime cap with `models.providers.openai-codex.models[].contextTokens`
 - Policy note: OpenAI Codex OAuth is explicitly supported for external tools/workflows like OpenClaw.
-- Use `openai-codex/gpt-5.5` when you want the Codex OAuth/subscription route; use `openai/gpt-5.5` when your API-key setup and local catalog expose the public API route.
+- For the common subscription plus native Codex runtime route, sign in with `openai-codex` auth but configure `openai/gpt-5.5` plus `agents.defaults.agentRuntime.id: "codex"`.
+- Use `openai-codex/gpt-5.5` only when you want the Codex OAuth/subscription route through PI; use `openai/gpt-5.5` without the Codex runtime override when your API-key setup and local catalog expose the public API route.
 
 ```json5
 {
-  agents: { defaults: { model: { primary: "openai-codex/gpt-5.5" } } },
+  plugins: { entries: { codex: { enabled: true } } },
+  agents: {
+    defaults: {
+      model: { primary: "openai/gpt-5.5" },
+      agentRuntime: { id: "codex", fallback: "none" },
+    },
+  },
 }
 ```
 
diff --git a/docs/concepts/models.md b/docs/concepts/models.md
@@ -23,7 +23,7 @@ sidebarTitle: "Models CLI"
   </Card>
 </CardGroup>
 
-Model refs choose a provider and model. They do not usually choose the low-level agent runtime. For example, `openai/gpt-5.5` can run through the normal OpenAI provider path or through the Codex app-server runtime, depending on `agents.defaults.agentRuntime.id`. See [Agent runtimes](/concepts/agent-runtimes).
+Model refs choose a provider and model. They do not usually choose the low-level agent runtime. For example, `openai/gpt-5.5` can run through the normal OpenAI provider path or through the Codex app-server runtime, depending on `agents.defaults.agentRuntime.id`. In Codex runtime mode, the `openai/gpt-*` ref does not imply API-key billing; auth can come from a Codex account or `openai-codex` auth profile. See [Agent runtimes](/concepts/agent-runtimes).
 
 ## How model selection works
 
diff --git a/docs/gateway/doctor.md b/docs/gateway/doctor.md
@@ -260,7 +260,7 @@ That stages grounded durable candidates into the short-term dreaming store while
     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."
+    - `openai/*` + `agentRuntime.id: "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."
 
diff --git a/docs/help/faq-first-run.md b/docs/help/faq-first-run.md
@@ -594,26 +594,29 @@ and troubleshooting see the main [FAQ](/help/faq).
 
   <Accordion title="How does Codex auth work?">
     OpenClaw supports **OpenAI Code (Codex)** via OAuth (ChatGPT sign-in). Use
-    `openai-codex/gpt-5.5` for Codex OAuth through the default PI runner. Use
-    `openai/gpt-5.5` for direct OpenAI API-key access. GPT-5.5 can also use
-    subscription/OAuth via `openai-codex/gpt-5.5` or native Codex app-server
-    runs with `openai/gpt-5.5` and `agentRuntime.id: "codex"`.
+    `openai/gpt-5.5` with `agentRuntime.id: "codex"` for the common setup:
+    ChatGPT/Codex subscription auth plus native Codex app-server execution. Use
+    `openai-codex/gpt-5.5` only when you want Codex OAuth through the default
+    PI runner. Use `openai/gpt-5.5` without the Codex runtime override for
+    direct OpenAI API-key access.
     See [Model providers](/concepts/model-providers) and [Onboarding (CLI)](/start/wizard).
   </Accordion>
 
   <Accordion title="Why does OpenClaw still mention openai-codex?">
     `openai-codex` is the provider and auth-profile id for ChatGPT/Codex OAuth.
     It is also the explicit PI model prefix for Codex OAuth:
 
-    - `openai/gpt-5.5` = current direct OpenAI API-key route in PI
+    - `openai/gpt-5.5` + `agentRuntime.id: "codex"` = ChatGPT/Codex subscription auth with native Codex runtime
     - `openai-codex/gpt-5.5` = Codex OAuth route in PI
-    - `openai/gpt-5.5` + `agentRuntime.id: "codex"` = native Codex app-server route
+    - `openai/gpt-5.5` without a Codex runtime override = direct OpenAI API-key route in PI
     - `openai-codex:...` = auth profile id, not a model ref
 
     If you want the direct OpenAI Platform billing/limit path, set
     `OPENAI_API_KEY`. If you want ChatGPT/Codex subscription auth, sign in with
-    `openclaw models auth login --provider openai-codex` and use
-    `openai-codex/*` model refs for PI runs.
+    `openclaw models auth login --provider openai-codex`. For native Codex
+    runtime, keep the model ref as `openai/gpt-5.5` and set
+    `agentRuntime.id: "codex"`. Use `openai-codex/*` model refs only for PI
+    runs.
 
   </Accordion>
 
diff --git a/docs/help/faq-models.md b/docs/help/faq-models.md
@@ -145,11 +145,12 @@ troubleshooting, see the main [FAQ](/help/faq).
   </Accordion>
 
   <Accordion title="Can I use GPT 5.5 for daily tasks and Codex 5.5 for coding?">
-    Yes. Set one as default and switch as needed:
+    Yes. Treat model choice and runtime choice separately:
 
-    - **Quick switch (per session):** `/model openai/gpt-5.5` for current direct OpenAI API-key tasks or `/model openai-codex/gpt-5.5` for GPT-5.5 Codex OAuth tasks.
-    - **Default:** set `agents.defaults.model.primary` to `openai/gpt-5.5` for API-key usage or `openai-codex/gpt-5.5` for GPT-5.5 Codex OAuth usage.
-    - **Sub-agents:** route coding tasks to sub-agents with a different default model.
+    - **Native Codex coding agent:** set `agents.defaults.model.primary` to `openai/gpt-5.5` and `agents.defaults.agentRuntime.id` to `"codex"`. Sign in with `openclaw models auth login --provider openai-codex` when you want ChatGPT/Codex subscription auth.
+    - **Direct OpenAI API tasks through PI:** use `/model openai/gpt-5.5` without a Codex runtime override and configure `OPENAI_API_KEY`.
+    - **Codex OAuth through PI:** use `/model openai-codex/gpt-5.5` only when you intentionally want the normal PI runner with Codex OAuth.
+    - **Sub-agents:** route coding tasks to a Codex-only agent with its own model and `agentRuntime` default.
 
     See [Models](/concepts/models) and [Slash commands](/tools/slash-commands).
 
diff --git a/docs/plugins/codex-harness.md b/docs/plugins/codex-harness.md
diff --git a/docs/plugins/sdk-agent-harness.md b/docs/plugins/sdk-agent-harness.md
diff --git a/docs/providers/openai.md b/docs/providers/openai.md
