diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json
index ccb2ab0f6..c2528867f 100644
--- a/.openclaw-sync/source.json
+++ b/.openclaw-sync/source.json
@@ -1,5 +1,5 @@
 {
   "repository": "openclaw/openclaw",
-  "sha": "3bd2ee78b6acf105c23656bb2d61416d6ccb2fa7",
-  "syncedAt": "2026-04-24T18:38:29.642Z"
+  "sha": "bc0f54bd04469d79095283c3b7ab55a3118fc3ae",
+  "syncedAt": "2026-04-24T18:41:15.250Z"
 }
diff --git a/docs/gateway/config-agents.md b/docs/gateway/config-agents.md
index 6204bb383..cd1d73393 100644
--- a/docs/gateway/config-agents.md
+++ b/docs/gateway/config-agents.md
@@ -369,7 +369,7 @@ Time format in system prompt. Default: `auto` (OS preference).
   - For direct OpenAI Responses models, server-side compaction is enabled automatically. Use `params.responsesServerCompaction: false` to stop injecting `context_management`, or `params.responsesCompactThreshold` to override the threshold. See [OpenAI server-side compaction](/providers/openai#server-side-compaction-responses-api).
 - `params`: global default provider parameters applied to all models. Set at `agents.defaults.params` (e.g. `{ cacheRetention: "long" }`).
 - `params` merge precedence (config): `agents.defaults.params` (global base) is overridden by `agents.defaults.models["provider/model"].params` (per-model), then `agents.list[].params` (matching agent id) overrides by key. See [Prompt Caching](/reference/prompt-caching) for details.
-- `embeddedHarness`: default low-level embedded agent runtime policy. Use `runtime: "auto"` to let registered plugin harnesses claim supported models, `runtime: "pi"` to force the built-in PI harness, or a registered harness id such as `runtime: "codex"`. Set `fallback: "none"` to disable automatic PI fallback.
+- `embeddedHarness`: default low-level embedded agent runtime policy. Use `runtime: "auto"` to let registered plugin harnesses claim supported models, `runtime: "pi"` to force the built-in PI harness, or a registered harness id such as `runtime: "codex"`. Set `fallback: "none"` to disable automatic PI fallback. New Codex harness configs should keep model refs canonical as `openai/*` and select the harness here rather than using legacy `codex/*` model refs.
 - Config writers that mutate these fields (for example `/models set`, `/models set-image`, and fallback add/remove commands) save canonical object form and preserve existing fallback lists when possible.
 - `maxConcurrent`: max parallel agent runs across sessions (each session still serialized). Default: 4.
 
diff --git a/docs/plugins/codex-harness.md b/docs/plugins/codex-harness.md
index e520b3f8e..b76128654 100644
--- a/docs/plugins/codex-harness.md
+++ b/docs/plugins/codex-harness.md
@@ -3,7 +3,7 @@ summary: "Run OpenClaw embedded agent turns through the bundled Codex app-server
 title: "Codex harness"
 read_when:
   - You want to use the bundled Codex app-server harness
-  - You need Codex model refs and config examples
+  - You need Codex harness config examples
   - You want to disable PI fallback for Codex-only deployments
 ---
 
@@ -35,7 +35,8 @@ The harness is off by default. New configs should keep OpenAI model refs
 canonical as `openai/gpt-*` and explicitly force
 `embeddedHarness.runtime: "codex"` or `OPENCLAW_AGENT_RUNTIME=codex` when they
 want native app-server execution. Legacy `codex/*` model refs still auto-select
-the harness for compatibility.
+the harness for compatibility, but they are not shown as normal model/provider
+choices.
 
 ## Pick the right model prefix
 
@@ -54,10 +55,11 @@ GPT-5.5 is currently subscription/OAuth-only in OpenClaw. Use
 app-server harness. Direct API-key access for `openai/gpt-5.5` is supported
 once OpenAI enables GPT-5.5 on the public API.
 
-Legacy `codex/gpt-*` refs remain accepted as compatibility aliases. New PI
-Codex OAuth configs should use `openai-codex/gpt-*`; new native app-server
-harness configs should use `openai/gpt-*` plus `embeddedHarness.runtime:
-"codex"`.
+Legacy `codex/gpt-*` refs remain accepted as compatibility aliases. Doctor
+compatibility migration rewrites legacy primary `codex/*` refs to `openai/*`
+and records the Codex harness policy separately. New PI Codex OAuth configs
+should use `openai-codex/gpt-*`; new native app-server harness configs should
+use `openai/gpt-*` plus `embeddedHarness.runtime: "codex"`.
 
 `agents.defaults.imageModel` follows the same prefix split. Use
 `openai-codex/gpt-*` when image understanding should run through the OpenAI