From c67629fe0c8dc79ebfc646132768d4714e4fd666 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 1 May 2026 00:05:20 +0100
Subject: [PATCH] docs: surface Codex harness quick config

---
 docs/plugins/codex-harness.md | 89 ++++++++++++++++++-----------------
 1 file changed, 46 insertions(+), 43 deletions(-)

diff --git a/docs/plugins/codex-harness.md b/docs/plugins/codex-harness.md
index 1db06c52794..42a33ec5ab2 100644
--- a/docs/plugins/codex-harness.md
+++ b/docs/plugins/codex-harness.md
@@ -20,6 +20,52 @@ 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.
 
+## Quick config
+
+To use the Codex harness for GPT agent turns, keep the model ref canonical as
+`openai/gpt-*`, enable the bundled `codex` plugin, and set
+`agentRuntime.id: "codex"`:
+
+```json5
+{
+  plugins: {
+    entries: {
+      codex: {
+        enabled: true,
+      },
+    },
+  },
+  agents: {
+    defaults: {
+      model: "openai/gpt-5.5",
+      agentRuntime: {
+        id: "codex",
+        fallback: "none",
+      },
+    },
+  },
+}
+```
+
+If your config uses `plugins.allow`, include `codex` there too:
+
+```json5
+{
+  plugins: {
+    allow: ["codex"],
+    entries: {
+      codex: {
+        enabled: true,
+      },
+    },
+  },
+}
+```
+
+Do not use `openai-codex/gpt-*` for this path. That selects Codex OAuth through
+the normal PI runner unless you separately force a runtime. Config changes apply
+to new or reset sessions; existing sessions keep their recorded runtime.
+
 ## What this plugin changes
 
 The bundled `codex` plugin contributes several separate capabilities:
@@ -192,49 +238,6 @@ For live and Docker smoke tests, auth usually comes from the Codex CLI account
 or an OpenClaw `openai-codex` auth profile. Local stdio app-server launches can
 also fall back to `CODEX_API_KEY` / `OPENAI_API_KEY` when no account is present.
 
-## Minimal config
-
-Use `openai/gpt-5.5`, enable the bundled plugin, and force the `codex` harness:
-
-```json5
-{
-  plugins: {
-    entries: {
-      codex: {
-        enabled: true,
-      },
-    },
-  },
-  agents: {
-    defaults: {
-      model: "openai/gpt-5.5",
-      agentRuntime: {
-        id: "codex",
-      },
-    },
-  },
-}
-```
-
-If your config uses `plugins.allow`, include `codex` there too:
-
-```json5
-{
-  plugins: {
-    allow: ["codex"],
-    entries: {
-      codex: {
-        enabled: true,
-      },
-    },
-  },
-}
-```
-
-Legacy configs that set `agents.defaults.model` or an agent model to
-`codex/<model>` still auto-enable the bundled `codex` plugin. New configs should
-prefer `openai/<model>` plus the explicit `agentRuntime` entry above.
-
 ## Add Codex alongside other models
 
 Do not set `agentRuntime.id: "codex"` globally if the same agent should freely switch