From 46a6746bcaa1d22e2594f7647365076be6a48e8b Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Sat, 11 Apr 2026 00:11:39 +0100
Subject: [PATCH] docs: clarify codex harness validation

---
 docs/help/testing.md                           | 3 +++
 docs/plugins/codex-harness.md                  | 4 +++-
 scripts/test-live-codex-harness-docker.sh      | 2 ++
 src/gateway/gateway-codex-harness.live.test.ts | 2 ++
 4 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/docs/help/testing.md b/docs/help/testing.md
index f8c5d8f76de..bfb784a360f 100644
--- a/docs/help/testing.md
+++ b/docs/help/testing.md
@@ -438,6 +438,9 @@ Docker notes:
 - Docker enables the image and MCP/tool probes by default. Set
   `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` or
   `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` when you need a narrower debug run.
+- Docker also exports `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, matching the live
+  test config so `openai-codex/*` or PI fallback cannot hide a Codex harness
+  regression.
 
 ### Recommended live recipes
 
diff --git a/docs/plugins/codex-harness.md b/docs/plugins/codex-harness.md
index 1b849008b8a..583d69c47eb 100644
--- a/docs/plugins/codex-harness.md
+++ b/docs/plugins/codex-harness.md
@@ -452,7 +452,9 @@ continue through the normal OpenClaw delivery path.
 
 When the selected model uses the Codex harness, native thread compaction is
 delegated to Codex app-server. OpenClaw keeps a transcript mirror for channel
-history, search, `/new`, `/reset`, and future model or harness switching.
+history, search, `/new`, `/reset`, and future model or harness switching. The
+mirror includes the user prompt, final assistant text, and lightweight Codex
+reasoning or plan records when the app-server emits them.
 
 Media generation does not require PI. Image, video, music, PDF, TTS, and media
 understanding continue to use the matching provider/model settings such as
diff --git a/scripts/test-live-codex-harness-docker.sh b/scripts/test-live-codex-harness-docker.sh
index e951c958149..fae82880025 100644
--- a/scripts/test-live-codex-harness-docker.sh
+++ b/scripts/test-live-codex-harness-docker.sh
@@ -80,6 +80,7 @@ echo "==> Run Codex harness live test in Docker"
 echo "==> Model: ${OPENCLAW_LIVE_CODEX_HARNESS_MODEL:-codex/gpt-5.4}"
 echo "==> Image probe: ${OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE:-1}"
 echo "==> MCP probe: ${OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE:-1}"
+echo "==> Harness fallback: none"
 echo "==> Auth files: ${AUTH_FILES_CSV:-none}"
 docker run --rm -t \
   -u node \
@@ -88,6 +89,7 @@ docker run --rm -t \
   -e HOME=/home/node \
   -e NODE_OPTIONS=--disable-warning=ExperimentalWarning \
   -e OPENAI_API_KEY \
+  -e OPENCLAW_AGENT_HARNESS_FALLBACK=none \
   -e OPENCLAW_CODEX_APP_SERVER_BIN="${OPENCLAW_CODEX_APP_SERVER_BIN:-codex}" \
   -e OPENCLAW_DOCKER_AUTH_FILES_RESOLVED="$AUTH_FILES_CSV" \
   -e OPENCLAW_LIVE_CODEX_HARNESS=1 \
diff --git a/src/gateway/gateway-codex-harness.live.test.ts b/src/gateway/gateway-codex-harness.live.test.ts
index db5f046418e..cf9407be3d0 100644
--- a/src/gateway/gateway-codex-harness.live.test.ts
+++ b/src/gateway/gateway-codex-harness.live.test.ts
@@ -232,6 +232,7 @@ async function writeLiveGatewayConfig(params: {
     agents: {
       defaults: {
         workspace: params.workspace,
+        embeddedHarness: { runtime: "codex", fallback: "none" },
         skipBootstrap: true,
         model: { primary: params.modelKey },
         models: { [params.modelKey]: {} },
@@ -421,6 +422,7 @@ describeLive("gateway live (Codex harness)", () => {
 
       clearRuntimeConfigSnapshot();
       process.env.OPENCLAW_AGENT_RUNTIME = "codex";
+      process.env.OPENCLAW_AGENT_HARNESS_FALLBACK = "none";
       process.env.OPENCLAW_CONFIG_PATH = configPath;
       process.env.OPENCLAW_GATEWAY_TOKEN = token;
       process.env.OPENCLAW_SKIP_BROWSER_CONTROL_SERVER = "1";