From 67f1a20136613e9f4320cda5e3a2587d81d33802 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 10 Apr 2026 22:43:33 +0100
Subject: [PATCH] docs: add Codex harness recipes

---
 docs/plugins/codex-harness.md | 83 +++++++++++++++++++++++++++++++++++
 1 file changed, 83 insertions(+)

diff --git a/docs/plugins/codex-harness.md b/docs/plugins/codex-harness.md
index 30feae1ebc0..4431f5357e7 100644
--- a/docs/plugins/codex-harness.md
+++ b/docs/plugins/codex-harness.md
@@ -333,6 +333,89 @@ the matching config field is unset:
 
 Config is preferred for repeatable deployments.
 
+## Common recipes
+
+Local Codex with default stdio transport:
+
+```json5
+{
+  plugins: {
+    entries: {
+      codex: {
+        enabled: true,
+      },
+    },
+  },
+}
+```
+
+Codex-only harness validation, with PI fallback disabled:
+
+```json5
+{
+  embeddedHarness: {
+    fallback: "none",
+  },
+  plugins: {
+    entries: {
+      codex: {
+        enabled: true,
+      },
+    },
+  },
+}
+```
+
+Guardian-reviewed Codex approvals:
+
+```json5
+{
+  plugins: {
+    entries: {
+      codex: {
+        enabled: true,
+        config: {
+          appServer: {
+            approvalPolicy: "on-request",
+            approvalsReviewer: "guardian_subagent",
+            sandbox: "workspace-write",
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+Remote app-server with explicit headers:
+
+```json5
+{
+  plugins: {
+    entries: {
+      codex: {
+        enabled: true,
+        config: {
+          appServer: {
+            transport: "websocket",
+            url: "ws://gateway-host:39175",
+            headers: {
+              "X-OpenClaw-Agent": "main",
+            },
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+Model switching stays OpenClaw-controlled. When an OpenClaw session is attached
+to an existing Codex thread, the next turn sends the currently selected
+`codex/*` model, provider, approval policy, sandbox, and service tier to
+app-server again. Switching from `codex/gpt-5.4` to `codex/gpt-5.2` keeps the
+thread binding but asks Codex to continue with the newly selected model.
+
 ## Codex command
 
 The bundled plugin registers `/codex` as an authorized slash command. It is