diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json
index 8fb5318da..513c5ff09 100644
--- a/.openclaw-sync/source.json
+++ b/.openclaw-sync/source.json
@@ -1,5 +1,5 @@
 {
   "repository": "openclaw/openclaw",
-  "sha": "b58223510c8134f4a91f6c289a4e8fe715dcb925",
-  "syncedAt": "2026-04-26T03:36:59.099Z"
+  "sha": "6336ed4166c5fe35d3e8e49e70320f66ba92575d",
+  "syncedAt": "2026-04-26T03:37:23.735Z"
 }
diff --git a/docs/gateway/doctor.md b/docs/gateway/doctor.md
index a120c319f..3dc59c5f3 100644
--- a/docs/gateway/doctor.md
+++ b/docs/gateway/doctor.md
@@ -249,7 +249,7 @@ doctor prints platform-specific fix guidance. On macOS with a Homebrew Node, the
 fix is usually `brew postinstall ca-certificates`. With `--deep`, the probe runs
 even if the gateway is healthy.
 
-### 2c) Codex OAuth provider overrides
+### 2e) Codex OAuth provider overrides
 
 If you previously added legacy OpenAI transport settings under
 `models.providers.openai-codex`, they can shadow the built-in Codex OAuth
@@ -259,6 +259,16 @@ the stale transport override and get the built-in routing/fallback behavior
 back. Custom proxies and header-only overrides are still supported and do not
 trigger this warning.
 
+### 2f) Codex plugin route warnings
+
+When the bundled Codex plugin is enabled, doctor also checks whether
+`openai-codex/*` primary model refs still resolve through the default PI runner.
+That combination is valid when you want Codex OAuth/subscription auth through
+PI, but it is easy to confuse with the native Codex app-server harness. Doctor
+warns and points to the explicit app-server shape:
+`openai/*` plus `embeddedHarness.runtime: "codex"` or
+`OPENCLAW_AGENT_RUNTIME=codex`.
+
 ### 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 998efdd5c..1c9473920 100644
--- a/docs/plugins/codex-harness.md
+++ b/docs/plugins/codex-harness.md
@@ -53,6 +53,11 @@ want native app-server execution. Legacy `codex/*` model refs still auto-select
 the harness for compatibility, but runtime-backed legacy provider prefixes are
 not shown as normal model/provider choices.
 
+If the `codex` plugin is enabled but the primary model is still
+`openai-codex/*`, `openclaw doctor` warns instead of changing the route. That is
+intentional: `openai-codex/*` remains the PI Codex OAuth/subscription path, and
+native app-server execution stays an explicit runtime choice.
+
 ## Pick the right model prefix
 
 OpenAI-family routes are prefix-specific. Use `openai-codex/*` when you want
diff --git a/docs/providers/openai.md b/docs/providers/openai.md
index 95036c1ad..2b49c3fb8 100644
--- a/docs/providers/openai.md
+++ b/docs/providers/openai.md
@@ -42,6 +42,8 @@ Enabling the OpenAI plugin, or selecting an `openai-codex/*` model, does not
 enable the bundled Codex app-server plugin. OpenClaw enables that plugin only
 when you explicitly select the native Codex harness with
 `embeddedHarness.runtime: "codex"` or use a legacy `codex/*` model ref.
+If the bundled `codex` plugin is enabled but `openai-codex/*` still resolves
+through PI, `openclaw doctor` warns and leaves the route unchanged.
 </Note>
 
 ## OpenClaw feature coverage