vilvona 1.0.0

package/docs/plugins/codex-harness.md

@@ -0,0 +1,800 @@
+---
+summary: "Run OpenClaw embedded agent turns through the bundled Codex app-server harness"
+title: "Codex harness"
+read_when:
+  - You want to use the bundled Codex app-server harness
+  - You need Codex harness config examples
+  - You want Codex-only deployments to fail instead of falling back to OpenClaw
+---
+
+The bundled `codex` plugin lets OpenClaw run embedded OpenAI agent turns
+through Codex app-server instead of the built-in OpenClaw harness.
+
+Use the Codex harness when you want Codex to own the low-level agent session:
+native thread resume, native tool continuation, native compaction, and
+app-server execution. OpenClaw still owns chat channels, session files, model
+selection, OpenClaw dynamic tools, approvals, media delivery, and the visible
+transcript mirror.
+
+The normal setup uses canonical OpenAI model refs such as `openai/gpt-5.5`.
+Do not configure legacy Codex GPT refs. Put OpenAI agent auth order
+under `auth.order.openai`; older legacy Codex auth profile ids and
+legacy Codex auth order entries are legacy state repaired by
+`openclaw doctor --fix`.
+
+When no OpenClaw sandbox is active, OpenClaw starts Codex app-server threads
+with Codex native code mode enabled while leaving code-mode-only off by default.
+That keeps Codex native workspace and code capabilities available while
+OpenClaw dynamic tools continue through the app-server `item/tool/call` bridge.
+Active OpenClaw sandboxing and restricted tool policies disable native code mode
+entirely unless you opt into the experimental sandbox exec-server path.
+
+This Codex-native feature is separate from
+[OpenClaw code mode](/reference/code-mode), which is an opt-in QuickJS-WASI
+runtime for generic OpenClaw runs with a different `exec` input shape.
+
+For the broader model/provider/runtime split, start with
+[Agent runtimes](/concepts/agent-runtimes). The short version is:
+`openai/gpt-5.5` is the model ref, `codex` is the runtime, and Telegram,
+Discord, Slack, or another channel remains the communication surface.
+
+## Requirements
+
+- OpenClaw with the bundled `codex` plugin available.
+- If your config uses `plugins.allow`, include `codex`.
+- Codex app-server `0.125.0` or newer. The bundled plugin manages a compatible
+  Codex app-server binary by default, so local `codex` commands on `PATH` do not
+  affect normal harness startup.
+- Codex auth available through `openclaw models auth login --provider openai`,
+  an app-server account in the agent's Codex home, or an explicit Codex API-key
+  auth profile.
+
+For auth precedence, environment isolation, custom app-server commands, model
+discovery, and all config fields, see
+[Codex harness reference](/plugins/codex-harness-reference).
+
+## Quickstart
+
+Most users who want Codex in OpenClaw want this path: sign in with a
+ChatGPT/Codex subscription, enable the bundled `codex` plugin, and use a
+canonical `openai/gpt-*` model ref.
+
+Sign in with Codex OAuth:
+
+```bash
+openclaw models auth login --provider openai
+```
+
+Enable the bundled `codex` plugin and select an OpenAI agent model:
+
+```json5
+{
+  plugins: {
+    entries: {
+      codex: {
+        enabled: true,
+      },
+    },
+  },
+  agents: {
+    defaults: {
+      model: "openai/gpt-5.5",
+    },
+  },
+}
+```
+
+If your config uses `plugins.allow`, add `codex` there too:
+
+```json5
+{
+  plugins: {
+    allow: ["codex"],
+    entries: {
+      codex: {
+        enabled: true,
+      },
+    },
+  },
+}
+```
+
+Restart the gateway after changing plugin config. If an existing chat already
+has a session, use `/new` or `/reset` before testing runtime changes so the next
+turn resolves the harness from current config.
+
+## Configuration
+
+The quickstart config is the minimum viable Codex harness config. Set Codex
+harness options in OpenClaw config, and use the CLI only for Codex auth:
+
+| Need                                   | Set                                                                              | Where                              |
+| -------------------------------------- | -------------------------------------------------------------------------------- | ---------------------------------- |
+| Enable the harness                     | `plugins.entries.codex.enabled: true`                                            | OpenClaw config                    |
+| Keep an allowlisted plugin install     | Include `codex` in `plugins.allow`                                               | OpenClaw config                    |
+| Route OpenAI agent turns through Codex | `agents.defaults.model` or `agents.list[].model` as `openai/gpt-*`               | OpenClaw agent config              |
+| Sign in with ChatGPT/Codex OAuth       | `openclaw models auth login --provider openai`                                   | CLI auth profile                   |
+| Add API-key backup for Codex runs      | `openai:*` API-key profile listed after subscription auth in `auth.order.openai` | CLI auth profile + OpenClaw config |
+| Fail closed when Codex is unavailable  | Provider or model `agentRuntime.id: "codex"`                                     | OpenClaw model/provider config     |
+| Use direct OpenAI API traffic          | Provider or model `agentRuntime.id: "openclaw"` with normal OpenAI auth          | OpenClaw model/provider config     |
+| Tune app-server behavior               | `plugins.entries.codex.config.appServer.*`                                       | Codex plugin config                |
+| Enable native Codex plugin apps        | `plugins.entries.codex.config.codexPlugins.*`                                    | Codex plugin config                |
+| Enable Codex Computer Use              | `plugins.entries.codex.config.computerUse.*`                                     | Codex plugin config                |
+
+Use `openai/gpt-*` model refs for Codex-backed OpenAI agent turns. Prefer
+`auth.order.openai` for subscription-first/API-key-backup ordering. Existing
+legacy Codex auth profile ids and legacy Codex auth order are doctor-only
+legacy state; do not write new legacy Codex GPT refs.
+
+Do not set `compaction.model` or `compaction.provider` on Codex-backed agents.
+Codex compacts through its native app-server thread state, so OpenClaw ignores
+those local summarizer overrides at runtime and `openclaw doctor --fix` removes
+them when the agent uses Codex.
+
+Lossless remains supported as a context engine for assembly, ingestion, and
+maintenance around Codex turns. Configure it through
+`plugins.slots.contextEngine: "lossless-claw"` and
+`plugins.entries.lossless-claw.config.summaryModel`, not through
+`agents.defaults.compaction.provider`. `openclaw doctor --fix` migrates the old
+`compaction.provider: "lossless-claw"` shape to the Lossless context-engine slot
+when Codex is the active runtime, but native Codex still owns compaction.
+
+The native Codex app-server harness supports context engines that require
+pre-prompt assembly. Generic CLI backends, including `codex-cli`, do not provide
+that host capability.
+
+For Codex-backed agents, `/compact` starts native Codex app-server compaction on
+the bound thread. OpenClaw does not wait for completion, impose an OpenClaw
+timeout, restart the shared app-server, or fall back to a context-engine or
+public OpenAI summarizer. If the native Codex thread binding is missing or
+stale, the command fails closed so the operator sees the real runtime boundary
+instead of silently switching compaction backends.
+
+```json5
+{
+  auth: {
+    order: {
+      openai: ["openai:user@example.com", "openai:api-key-backup"],
+    },
+  },
+}
+```
+
+In that shape, both profiles still run through Codex for `openai/gpt-*` agent
+turns. The API key is only an auth fallback, not a request to switch to OpenClaw or
+plain OpenAI Responses.
+
+The rest of this page covers common variants users must choose between:
+deployment shape, fail-closed routing, guardian approval policy, native Codex
+plugins, and Computer Use. For full option lists, defaults, enums, discovery,
+environment isolation, timeouts, and app-server transport fields, see
+[Codex harness reference](/plugins/codex-harness-reference).
+
+## Verify Codex runtime
+
+Use `/status` in the chat where you expect Codex. A Codex-backed OpenAI agent
+turn shows:
+
+```text
+Runtime: OpenAI Codex
+```
+
+Then check Codex app-server state:
+
+```text
+/codex status
+/codex models
+```
+
+`/codex status` reports app-server connectivity, account, rate limits, MCP
+servers, and skills. `/codex models` lists the live Codex app-server catalog for
+the harness and account. If `/status` is surprising, see
+[Troubleshooting](#troubleshooting).
+
+## Routing and model selection
+
+Keep provider refs and runtime policy separate:
+
+- Use `openai/gpt-*` for OpenAI agent turns through Codex.
+- Do not use legacy Codex GPT refs in config. Run `openclaw doctor --fix` to
+  repair legacy refs and stale session route pins.
+- `agentRuntime.id: "codex"` is optional for normal OpenAI auto mode, but useful
+  when a deployment should fail closed if Codex is unavailable.
+- `agentRuntime.id: "openclaw"` opts a provider or model into the OpenClaw
+  embedded runtime when that is intentional.
+- `/codex ...` controls native Codex app-server conversations from chat.
+- ACP/acpx is a separate external harness path. Use it only when the user asks
+  for ACP/acpx or an external harness adapter.
+
+Common command routing:
+
+| User intent                                           | Use                                                                                                   |
+| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| Attach the current chat                               | `/codex bind [--cwd <path>]`                                                                          |
+| Resume an existing Codex thread                       | `/codex resume <thread-id>`                                                                           |
+| List or filter Codex threads                          | `/codex threads [filter]`                                                                             |
+| List native Codex plugins                             | `/codex plugins list`                                                                                 |
+| Enable or disable a configured native Codex plugin    | `/codex plugins enable <name>`, `/codex plugins disable <name>`                                       |
+| Attach an existing Codex CLI session on a paired node | `/codex sessions --host <node> [filter]`, then `/codex resume <session-id> --host <node> --bind here` |
+| Send Codex feedback only                              | `/codex diagnostics [note]`                                                                           |
+| Start an ACP/acpx task                                | ACP/acpx session commands, not `/codex`                                                               |
+
+| Use case                                             | Configure                                                              | Verify                                  | Notes                                 |
+| ---------------------------------------------------- | ---------------------------------------------------------------------- | --------------------------------------- | ------------------------------------- |
+| ChatGPT/Codex subscription with native Codex runtime | `openai/gpt-*` plus enabled `codex` plugin                             | `/status` shows `Runtime: OpenAI Codex` | Recommended path                      |
+| Fail closed if Codex is unavailable                  | Provider or model `agentRuntime.id: "codex"`                           | Turn fails instead of embedded fallback | Use for Codex-only deployments        |
+| Direct OpenAI API-key traffic through OpenClaw       | Provider or model `agentRuntime.id: "openclaw"` and normal OpenAI auth | `/status` shows OpenClaw runtime        | Use only when OpenClaw is intentional |
+| Legacy config                                        | legacy Codex GPT refs                                                  | `openclaw doctor --fix` rewrites it     | Do not write new config this way      |
+| ACP/acpx Codex adapter                               | ACP `sessions_spawn({ runtime: "acp" })`                               | ACP task/session status                 | Separate from native Codex harness    |
+
+`agents.defaults.imageModel` follows the same prefix split. Use `openai/gpt-*`
+for the normal OpenAI route and `codex/gpt-*` only when image understanding
+should run through a bounded Codex app-server turn. Do not use
+legacy Codex GPT refs; doctor rewrites that legacy prefix to `openai/gpt-*`.
+
+## Deployment patterns
+
+### Basic Codex deployment
+
+Use the quickstart config when all OpenAI agent turns should use Codex by
+default.
+
+```json5
+{
+  plugins: {
+    entries: {
+      codex: {
+        enabled: true,
+      },
+    },
+  },
+  agents: {
+    defaults: {
+      model: "openai/gpt-5.5",
+    },
+  },
+}
+```
+
+### Mixed provider deployment
+
+This shape keeps Claude as the default agent and adds a named Codex agent:
+
+```json5
+{
+  plugins: {
+    entries: {
+      codex: {
+        enabled: true,
+      },
+    },
+  },
+  agents: {
+    defaults: {
+      model: "anthropic/claude-opus-4-6",
+    },
+    list: [
+      {
+        id: "main",
+        default: true,
+        model: "anthropic/claude-opus-4-6",
+      },
+      {
+        id: "codex",
+        name: "Codex",
+        model: "openai/gpt-5.5",
+      },
+    ],
+  },
+}
+```
+
+With this config, the `main` agent uses its normal provider path and the
+`codex` agent uses Codex app-server.
+
+### Fail-closed Codex deployment
+
+For OpenAI agent turns, `openai/gpt-*` already resolves to Codex when the
+bundled plugin is available. Add explicit runtime policy when you want a written
+fail-closed rule:
+
+```json5
+{
+  models: {
+    providers: {
+      openai: {
+        agentRuntime: {
+          id: "codex",
+        },
+      },
+    },
+  },
+  agents: {
+    defaults: {
+      model: "openai/gpt-5.5",
+    },
+  },
+  plugins: {
+    entries: {
+      codex: {
+        enabled: true,
+      },
+    },
+  },
+}
+```
+
+With Codex forced, OpenClaw fails early if the Codex plugin is disabled, the
+app-server is too old, or the app-server cannot start.
+
+## App-server policy
+
+By default, the plugin starts OpenClaw's managed Codex binary locally with stdio
+transport. Set `appServer.command` only when you intentionally want to run a
+different executable. Use WebSocket transport only when an app-server is already
+running elsewhere:
+
+```json5
+{
+  plugins: {
+    entries: {
+      codex: {
+        enabled: true,
+        config: {
+          appServer: {
+            transport: "websocket",
+            url: "ws://gateway-host:39175",
+            authToken: "${CODEX_APP_SERVER_TOKEN}",
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+Local stdio app-server sessions default to the trusted local operator posture:
+`approvalPolicy: "never"`, `approvalsReviewer: "user"`, and
+`sandbox: "danger-full-access"`. If local Codex requirements disallow that
+implicit YOLO posture, OpenClaw selects allowed guardian permissions instead.
+When an OpenClaw sandbox is active for the session, OpenClaw disables Codex
+native Code Mode, user MCP servers, and app-backed plugin execution for that
+turn instead of relying on Codex host-side sandboxing. Shell access is exposed
+through OpenClaw sandbox-backed dynamic tools such as `sandbox_exec` and
+`sandbox_process` when the normal exec/process tools are available.
+
+Use normalized OpenClaw exec mode when you want Codex native auto-review before
+sandbox escapes or extra permissions:
+
+```json5
+{
+  tools: {
+    exec: {
+      mode: "auto",
+    },
+  },
+  plugins: {
+    entries: {
+      codex: {
+        enabled: true,
+      },
+    },
+  },
+}
+```
+
+For Codex app-server sessions, OpenClaw maps `tools.exec.mode: "auto"` to Codex
+Guardian-reviewed approvals, usually
+`approvalPolicy: "on-request"`, `approvalsReviewer: "auto_review"`, and
+`sandbox: "workspace-write"` when the local requirements allow those values.
+In `tools.exec.mode: "auto"`, OpenClaw does not preserve legacy unsafe Codex
+`approvalPolicy: "never"` or `sandbox: "danger-full-access"` overrides; use
+`tools.exec.mode: "full"` for an intentional no-approval Codex posture. The
+legacy `plugins.entries.codex.config.appServer.mode: "guardian"` preset still
+works, but `tools.exec.mode: "auto"` is the normalized OpenClaw surface.
+
+For the mode-level comparison with host exec approvals and ACPX permissions,
+see [Permission modes](/tools/permission-modes).
+
+For every app-server field, auth order, environment isolation, discovery, and
+timeout behavior, see [Codex harness reference](/plugins/codex-harness-reference).
+
+## Commands and diagnostics
+
+The bundled plugin registers `/codex` as a slash command on any channel that
+supports OpenClaw text commands.
+
+Common forms:
+
+- `/codex status` checks app-server connectivity, models, account, rate limits,
+  MCP servers, and skills.
+- `/codex models` lists live Codex app-server models.
+- `/codex threads [filter]` lists recent Codex app-server threads.
+- `/codex resume <thread-id>` attaches the current OpenClaw session to an
+  existing Codex thread.
+- `/codex compact` asks Codex app-server to compact the attached thread.
+- `/codex review` starts Codex native review for the attached thread.
+- `/codex diagnostics [note]` asks before sending Codex feedback for the
+  attached thread.
+- `/codex account` shows account and rate-limit status.
+- `/codex mcp` lists Codex app-server MCP server status.
+- `/codex skills` lists Codex app-server skills.
+
+For most support reports, start with `/diagnostics [note]` in the conversation
+where the bug happened. It creates one Gateway diagnostics report and, for Codex
+harness sessions, asks for approval to send the relevant Codex feedback bundle.
+See [Diagnostics export](/gateway/diagnostics) for the privacy model and group
+chat behavior.
+
+Use `/codex diagnostics [note]` only when you specifically want the Codex
+feedback upload for the currently attached thread without the full Gateway
+diagnostics bundle.
+
+### Inspect Codex threads locally
+
+The fastest way to inspect a bad Codex run is often to open the native Codex
+thread directly:
+
+```bash
+codex resume <thread-id>
+```
+
+Get the thread id from the completed `/diagnostics` reply, `/codex binding`, or
+`/codex threads [filter]`.
+
+For upload mechanics and runtime-level diagnostics boundaries, see
+[Codex harness runtime](/plugins/codex-harness-runtime#codex-feedback-upload).
+
+Auth is selected in this order:
+
+1. Ordered OpenAI auth profiles for the agent, preferably under
+   `auth.order.openai`. Run `openclaw doctor --fix` to migrate older
+   legacy Codex auth profile ids and legacy Codex auth order.
+2. The app-server's existing account in that agent's Codex home.
+3. For local stdio app-server launches only, `CODEX_API_KEY`, then
+   `OPENAI_API_KEY`, when no app-server account is present and OpenAI auth is
+   still required.
+
+When OpenClaw sees a ChatGPT subscription-style Codex auth profile, it removes
+`CODEX_API_KEY` and `OPENAI_API_KEY` from the spawned Codex child process. That
+keeps Gateway-level API keys available for embeddings or direct OpenAI models
+without making native Codex app-server turns bill through the API by accident.
+Explicit Codex API-key profiles and local stdio env-key fallback use app-server
+login instead of inherited child-process env. WebSocket app-server connections
+do not receive Gateway env API-key fallback; use an explicit auth profile or the
+remote app-server's own account.
+
+If a subscription profile hits a Codex usage limit, OpenClaw records the reset
+time when Codex reports one and tries the next ordered auth profile for the same
+Codex run. When the reset time passes, the subscription profile becomes eligible
+again without changing the selected `openai/gpt-*` model or Codex runtime.
+
+For local stdio app-server launches, OpenClaw sets `CODEX_HOME` to a per-agent
+directory so Codex config, auth/account files, plugin cache/data, and native
+thread state do not read or write the operator's personal `~/.codex` by
+default. OpenClaw preserves the normal process `HOME`; Codex-run subprocesses
+can still find user-home config and tokens, and Codex may discover shared
+`$HOME/.agents/skills` and `$HOME/.agents/plugins/marketplace.json` entries.
+
+If a deployment needs additional environment isolation, add those variables to
+`appServer.clearEnv`:
+
+```json5
+{
+  plugins: {
+    entries: {
+      codex: {
+        enabled: true,
+        config: {
+          appServer: {
+            clearEnv: ["CODEX_API_KEY", "OPENAI_API_KEY"],
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+`appServer.clearEnv` only affects the spawned Codex app-server child process.
+OpenClaw removes `CODEX_HOME` and `HOME` from this list during local launch
+normalization: `CODEX_HOME` stays per-agent, and `HOME` stays inherited so
+subprocesses can use normal user-home state.
+
+Codex dynamic tools default to `searchable` loading. OpenClaw does not expose
+dynamic tools that duplicate Codex-native workspace operations: `read`, `write`,
+`edit`, `apply_patch`, `exec`, `process`, and `update_plan`. Most remaining
+OpenClaw integration tools such as messaging, media, cron, browser, nodes,
+gateway, `heartbeat_respond`, and `web_search` are available through Codex tool
+search under the `openclaw` namespace, keeping the initial model context
+smaller.
+`sessions_yield` and message-tool-only source replies stay direct because
+those are turn-control contracts. `sessions_spawn` stays searchable so Codex's
+native `spawn_agent` remains the primary Codex subagent surface, while explicit
+OpenClaw or ACP delegation is still available through the `openclaw` dynamic
+tool namespace. Heartbeat collaboration instructions tell Codex to search for
+`heartbeat_respond` before ending a heartbeat turn when the tool is not already
+loaded.
+
+Set `codexDynamicToolsLoading: "direct"` only when connecting to a custom Codex
+app-server that cannot search deferred dynamic tools or when debugging the full
+tool payload.
+
+Supported top-level Codex plugin fields:
+
+| Field                      | Default        | Meaning                                                                                  |
+| -------------------------- | -------------- | ---------------------------------------------------------------------------------------- |
+| `codexDynamicToolsLoading` | `"searchable"` | Use `"direct"` to put OpenClaw dynamic tools directly in the initial Codex tool context. |
+| `codexDynamicToolsExclude` | `[]`           | Additional OpenClaw dynamic tool names to omit from Codex app-server turns.              |
+| `codexPlugins`             | disabled       | Native Codex plugin/app support for migrated source-installed curated plugins.           |
+
+Supported `appServer` fields:
+
+| Field                                         | Default                                                | Meaning                                                                                                                                                                                                                                                                                                                                                          |
+| --------------------------------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `transport`                                   | `"stdio"`                                              | `"stdio"` spawns Codex; `"websocket"` connects to `url`.                                                                                                                                                                                                                                                                                                         |
+| `command`                                     | managed Codex binary                                   | Executable for stdio transport. Leave unset to use the managed binary; set it only for an explicit override.                                                                                                                                                                                                                                                     |
+| `args`                                        | `["app-server", "--listen", "stdio://"]`               | Arguments for stdio transport.                                                                                                                                                                                                                                                                                                                                   |
+| `url`                                         | unset                                                  | WebSocket app-server URL.                                                                                                                                                                                                                                                                                                                                        |
+| `authToken`                                   | unset                                                  | Bearer token for WebSocket transport.                                                                                                                                                                                                                                                                                                                            |
+| `headers`                                     | `{}`                                                   | Extra WebSocket headers.                                                                                                                                                                                                                                                                                                                                         |
+| `clearEnv`                                    | `[]`                                                   | Extra environment variable names removed from the spawned stdio app-server process after OpenClaw builds its inherited environment. OpenClaw keeps per-agent `CODEX_HOME` and inherited `HOME` for local launches.                                                                                                                                               |
+| `codeModeOnly`                                | `false`                                                | Opt into Codex's code-mode-only tool surface. OpenClaw dynamic tools remain registered with Codex so nested `tools.*` calls return through the app-server `item/tool/call` bridge.                                                                                                                                                                               |
+| `requestTimeoutMs`                            | `60000`                                                | Timeout for app-server control-plane calls.                                                                                                                                                                                                                                                                                                                      |
+| `turnCompletionIdleTimeoutMs`                 | `60000`                                                | Quiet window after Codex accepts a turn or after a turn-scoped app-server request while OpenClaw waits for `turn/completed`.                                                                                                                                                                                                                                     |
+| `postToolRawAssistantCompletionIdleTimeoutMs` | `300000`                                               | Completion-idle and progress guard used after a tool handoff, native tool completion, post-tool raw assistant progress, raw reasoning completion, or reasoning progress while OpenClaw waits for `turn/completed`. Use this for trusted or heavy workloads where post-tool synthesis can legitimately stay quiet longer than the final assistant release budget. |
+| `mode`                                        | `"yolo"` unless local Codex requirements disallow YOLO | Preset for YOLO or guardian-reviewed execution. Local stdio requirements that omit `danger-full-access`, `never` approval, or the `user` reviewer make the implicit default guardian.                                                                                                                                                                            |
+| `approvalPolicy`                              | `"never"` or an allowed guardian approval policy       | Native Codex approval policy sent to thread start/resume/turn. Guardian defaults prefer `"on-request"` when allowed.                                                                                                                                                                                                                                             |
+| `sandbox`                                     | `"danger-full-access"` or an allowed guardian sandbox  | Native Codex sandbox mode sent to thread start/resume. Guardian defaults prefer `"workspace-write"` when allowed, otherwise `"read-only"`. When an OpenClaw sandbox is active, `danger-full-access` turns use Codex `workspace-write` with network access derived from the OpenClaw sandbox egress setting.                                                      |
+| `approvalsReviewer`                           | `"user"` or an allowed guardian reviewer               | Use `"auto_review"` to let Codex review native approval prompts when allowed, otherwise `guardian_subagent` or `user`. `guardian_subagent` remains a legacy alias.                                                                                                                                                                                               |
+| `serviceTier`                                 | unset                                                  | Optional Codex app-server service tier. `"priority"` enables fast-mode routing, `"flex"` requests flex processing, `null` clears the override, and legacy `"fast"` is accepted as `"priority"`.                                                                                                                                                                  |
+| `experimental.sandboxExecServer`              | `false`                                                | Preview opt-in that registers an OpenClaw sandbox-backed Codex environment with Codex app-server 0.132.0 or newer so native Codex execution can run inside the active OpenClaw sandbox.                                                                                                                                                                          |
+
+OpenClaw-owned dynamic tool calls are bounded independently from
+`appServer.requestTimeoutMs`: Codex `item/tool/call` requests use a 90 second
+OpenClaw watchdog by default. A positive per-call `timeoutMs` argument extends
+or shortens that specific tool budget. The `image_generate` tool uses
+`agents.defaults.imageGenerationModel.timeoutMs` when the tool call does not
+provide its own timeout, or a 120 second image-generation default otherwise.
+The media-understanding `image` tool uses
+`tools.media.image.timeoutSeconds` or its 60 second media default. Dynamic tool
+budgets are capped at 600000 ms. On timeout, OpenClaw aborts the tool signal
+where supported and returns a failed dynamic-tool response to Codex so the turn
+can continue instead of leaving the session in `processing`.
+
+After Codex accepts a turn, and after OpenClaw responds to a turn-scoped
+app-server request, the harness expects Codex to make current-turn progress and
+eventually finish the native turn with `turn/completed`. If the app-server goes
+quiet for `appServer.turnCompletionIdleTimeoutMs`, OpenClaw best-effort
+interrupts the Codex turn, records a diagnostic timeout, and releases the
+OpenClaw session lane so follow-up chat messages are not queued behind a stale
+native turn. Most non-terminal notifications for the same turn disarm that short
+watchdog because Codex has proven the turn is still alive. Tool handoffs use a
+longer post-tool idle budget: after OpenClaw returns an `item/tool/call`
+response, after native tool items such as `commandExecution` complete, after raw
+`custom_tool_call_output` completions, and after post-tool raw assistant
+progress, raw reasoning completions, or reasoning progress. The guard uses
+`appServer.postToolRawAssistantCompletionIdleTimeoutMs` when configured and
+defaults to five minutes otherwise. That same post-tool budget also extends the
+progress watchdog for the silent synthesis window before Codex emits the next
+current-turn event. Global app-server notifications, such as rate-limit updates,
+do not reset turn-idle progress. Reasoning completions, commentary
+`agentMessage` completions, and pre-tool raw reasoning or assistant progress can
+be followed by an automatic final reply, so they use the post-progress reply
+guard instead of releasing the session lane immediately. Only
+final/non-commentary completed `agentMessage` items and pre-tool raw
+assistant completions arm the assistant-output release: if Codex then goes quiet
+without `turn/completed`, OpenClaw best-effort interrupts the native turn and
+releases the session lane. Replay-safe stdio app-server failures, including
+turn-completion idle timeouts without assistant, tool, active-item, or
+side-effect evidence, are retried once on a fresh app-server attempt. Unsafe
+timeouts still retire the stuck app-server client and release the OpenClaw
+session lane. They also clear the stale native thread binding instead of being
+replayed automatically. Completion-watch timeouts surface Codex-specific timeout
+text: replay-safe cases say the response may be incomplete, while unsafe cases
+tell the user to verify current state before retrying. Public timeout diagnostics
+include structural fields such as the last app-server notification method,
+raw assistant response item id/type/role, active request/item counts, and armed
+watch state. When the last notification is a raw assistant response item, they
+also include a bounded assistant text preview. They do not include raw prompt or
+tool content.
+
+Environment overrides remain available for local testing:
+
+- `OPENCLAW_CODEX_APP_SERVER_BIN`
+- `OPENCLAW_CODEX_APP_SERVER_ARGS`
+- `OPENCLAW_CODEX_APP_SERVER_MODE=yolo|guardian`
+- `OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY`
+- `OPENCLAW_CODEX_APP_SERVER_SANDBOX`
+
+`OPENCLAW_CODEX_APP_SERVER_BIN` bypasses the managed binary when
+`appServer.command` is unset.
+
+`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` was removed. Use
+`plugins.entries.codex.config.appServer.mode: "guardian"` instead, or
+`OPENCLAW_CODEX_APP_SERVER_MODE=guardian` for one-off local testing. Config is
+preferred for repeatable deployments because it keeps the plugin behavior in the
+same reviewed file as the rest of the Codex harness setup.
+
+## Native Codex plugins
+
+Native Codex plugin support uses Codex app-server's own app and plugin
+capabilities in the same Codex thread as the OpenClaw harness turn. OpenClaw
+does not translate Codex plugins into synthetic `codex_plugin_*` OpenClaw
+dynamic tools.
+
+`codexPlugins` affects only sessions that select the native Codex harness. It
+has no effect on built-in harness runs, normal OpenAI provider runs, ACP conversation
+bindings, or other harnesses.
+
+Minimal migrated config:
+
+```json5
+{
+  plugins: {
+    entries: {
+      codex: {
+        enabled: true,
+        config: {
+          codexPlugins: {
+            enabled: true,
+            allow_destructive_actions: true,
+            plugins: {
+              "google-calendar": {
+                enabled: true,
+                marketplaceName: "openai-curated",
+                pluginName: "google-calendar",
+              },
+            },
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+Thread app config is computed when OpenClaw establishes a Codex harness session
+or replaces a stale Codex thread binding. It is not recomputed on every turn.
+After changing `codexPlugins`, use `/new`, `/reset`, or restart the gateway so
+future Codex harness sessions start with the updated app set.
+
+For migration eligibility, app inventory, destructive action policy,
+elicitations, and native plugin diagnostics, see
+[Native Codex plugins](/plugins/codex-native-plugins).
+
+OpenAI-side app and plugin access is controlled by the signed-in Codex account
+and, for Business and Enterprise/Edu workspaces, workspace app controls. See
+[Using Codex with your ChatGPT plan](https://help.openai.com/en/articles/11369540-using-codex-with-your-chatgpt-plan)
+for OpenAI's account and workspace-control overview.
+
+## Computer Use
+
+Computer Use is covered in its own setup guide:
+[Codex Computer Use](/plugins/codex-computer-use).
+
+The short version: OpenClaw does not vendor the desktop-control app or execute
+desktop actions itself. It prepares Codex app-server, verifies that the
+`computer-use` MCP server is available, and then lets Codex own the native MCP
+tool calls during Codex-mode turns.
+
+## Runtime boundaries
+
+The Codex harness changes the low-level embedded agent executor only.
+
+- OpenClaw dynamic tools are supported. Codex asks OpenClaw to execute those
+  tools, so OpenClaw remains in the execution path.
+- Codex-native shell, patch, MCP, and native app tools are owned by Codex.
+  OpenClaw can observe or block selected native events through the supported
+  relay, but it does not rewrite native tool arguments.
+- Codex owns native compaction. OpenClaw keeps a transcript mirror for channel
+  history, search, `/new`, `/reset`, and future model or harness switching, but
+  it does not replace Codex compaction with an OpenClaw or context-engine
+  summarizer.
+- Media generation, media understanding, TTS, approvals, and messaging-tool
+  output continue through the matching OpenClaw provider/model settings.
+- `tool_result_persist` applies to OpenClaw-owned transcript tool results, not
+  Codex-native tool result records.
+
+For hook layers, supported V1 surfaces, native permission handling, queue
+steering, Codex feedback upload mechanics, and compaction details, see
+[Codex harness runtime](/plugins/codex-harness-runtime).
+
+## Troubleshooting
+
+**Codex does not appear as a normal `/model` provider:** that is expected for
+new configs. Select an `openai/gpt-*` model, enable
+`plugins.entries.codex.enabled`, and check whether `plugins.allow` excludes
+`codex`.
+
+**OpenClaw uses the built-in harness instead of Codex:** make sure the model ref is
+`openai/gpt-*` on the official OpenAI provider and that the Codex plugin is
+installed and enabled. If you need strict proof while testing, set provider or
+model `agentRuntime.id: "codex"`. A forced Codex runtime fails instead of
+falling back to OpenClaw.
+
+**OpenAI Codex runtime falls back to the API-key path:** collect a redacted
+gateway excerpt that shows the model, runtime, selected provider, and failure.
+Ask affected collaborators to run this read-only command on their OpenClaw host:
+
+```bash
+(
+  pattern='openai/gpt-5\.[45]|openai[-]codex|agentRuntime(\.id)?|harnessRuntime|Runtime: OpenAI Codex|legacy OpenAI Codex prefix|resolveSelectedOpenAIRuntimeProvider|candidateProvider[": ]+openai|status[": ]+401|Incorrect API key|No API key|api-key path|API-key path|OAuth'
+
+  if ls /tmp/openclaw/openclaw-*.log >/dev/null 2>&1; then
+    grep -E -i -n "$pattern" /tmp/openclaw/openclaw-*.log 2>/dev/null || true
+  else
+    journalctl --user -u openclaw-gateway --since today --no-pager 2>/dev/null \
+      | grep -E -i "$pattern" || true
+  fi
+) | sed -E \
+    -e 's/(Authorization: Bearer )[A-Za-z0-9._~+\/-]+/\1[REDACTED]/Ig' \
+    -e 's/(Bearer )[A-Za-z0-9._~+\/-]+/\1[REDACTED]/Ig' \
+    -e 's/(api[_ -]?key[=: ]+)[^ ,}"]+/\1[REDACTED]/Ig' \
+    -e 's/(OPENAI_API_KEY[=: ]+)[^ ,}"]+/\1[REDACTED]/Ig' \
+    -e 's/sk-[A-Za-z0-9_-]{12,}/sk-[REDACTED]/g' \
+    -e 's/[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/[EMAIL-REDACTED]/g' \
+  | tail -200
+```
+
+Useful excerpts usually include `openai/gpt-5.5` or `openai/gpt-5.4`,
+`Runtime: OpenAI Codex`, `agentRuntime.id` or `harnessRuntime`,
+`candidateProvider: "openai"`, and a `401`, `Incorrect API key`, or
+`No API key` result. A corrected run should show the OpenAI OAuth
+path instead of a plain OpenAI API-key failure.
+
+**Legacy Codex model refs config remains:** run `openclaw doctor --fix`.
+Doctor rewrites legacy model refs to `openai/*`, removes stale session and
+whole-agent runtime pins, and preserves existing auth-profile overrides.
+
+**The app-server is rejected:** use Codex app-server `0.125.0` or newer.
+Same-version prereleases or build-suffixed versions such as
+`0.125.0-alpha.2` or `0.125.0+custom` are rejected because OpenClaw tests the
+stable `0.125.0` protocol floor.
+
+**`/codex status` cannot connect:** check that the bundled `codex` plugin is
+enabled, that `plugins.allow` includes it when an allowlist is configured, and
+that any custom `appServer.command`, `url`, `authToken`, or headers are valid.
+
+**Model discovery is slow:** lower
+`plugins.entries.codex.config.discovery.timeoutMs` or disable discovery. See
+[Codex harness reference](/plugins/codex-harness-reference#model-discovery).
+
+**WebSocket transport fails immediately:** check `appServer.url`, `authToken`,
+headers, and that the remote app-server speaks the same Codex app-server
+protocol version.
+
+**Native shell or patch tools are blocked with `Native hook relay unavailable`:**
+the Codex thread is still trying to use a native hook relay id that OpenClaw no
+longer has registered. This is a native Codex hook transport problem, not an ACP
+backend, provider, GitHub, or shell-command failure. Start a fresh session in
+the affected chat with `/new` or `/reset`, then retry a harmless command. If that
+works once but the next native tool call fails again, treat `/new` as a temporary
+workaround only: copy the prompt into a fresh session after restarting the Codex
+app-server or OpenClaw Gateway so old threads are dropped and native hook
+registrations are recreated.
+
+**A non-Codex model uses the built-in harness:** that is expected unless
+provider or model runtime policy routes it to another harness. Plain non-OpenAI
+provider refs stay on their normal provider path in `auto` mode.
+
+**Computer Use is installed but tools do not run:** check
+`/codex computer-use status` from a fresh session. If a tool reports
+`Native hook relay unavailable`, use the native hook relay recovery above. See
+[Codex Computer Use](/plugins/codex-computer-use#troubleshooting).
+
+## Related
+
+- [Codex harness reference](/plugins/codex-harness-reference)
+- [Codex harness runtime](/plugins/codex-harness-runtime)
+- [Native Codex plugins](/plugins/codex-native-plugins)
+- [Codex Computer Use](/plugins/codex-computer-use)
+- [Agent runtimes](/concepts/agent-runtimes)
+- [Model providers](/concepts/model-providers)
+- [OpenAI provider](/providers/openai)
+- [OpenAI Codex help](https://help.openai.com/en/collections/14937394-codex)
+- [Agent harness plugins](/plugins/sdk-agent-harness)
+- [Plugin hooks](/plugins/hooks)
+- [Diagnostics export](/gateway/diagnostics)
+- [Status](/cli/status)
+- [Testing](/help/testing-live#live-codex-app-server-harness-smoke)