## Requirements

- OpenClaw with the bundled `codex` plugin available.

- Codex app-server `0.118.0` or newer.

- Codex app-server `0.125.0` or newer. Native MCP hook payloads landed in Codex

`0.124.0`; OpenClaw uses `0.125.0` as the tested support floor.

- Codex auth available to the app-server process.

The plugin blocks older or unversioned app-server handshakes. That keeps

currently selected OpenClaw model into app-server, and keeps extended history

enabled.

The command surface requires Codex app-server `0.118.0` or newer. Individual

The command surface requires Codex app-server `0.125.0` or newer. Individual

control methods are reported as `unsupported by this Codex app-server` if a

future or custom app-server does not expose that JSON-RPC method.

Supported in Codex runtime v1:

| Surface | Support | Why |

| --------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |

| OpenAI model loop through Codex | Supported | Codex app-server owns the OpenAI turn, native thread resume, and native tool continuation. |

| OpenClaw channel routing and delivery | Supported | Telegram, Discord, Slack, WhatsApp, iMessage, and other channels stay outside the model runtime. |

| OpenClaw dynamic tools | Supported | Codex asks OpenClaw to execute these tools, so OpenClaw stays in the execution path. |

| Prompt and context plugins | Supported | OpenClaw builds prompt overlays and projects context into the Codex turn before starting or resuming the thread. |

| Context engine lifecycle | Supported | Assemble, ingest or after-turn maintenance, and context-engine compaction coordination run for Codex turns. |

| Dynamic tool hooks | Supported | `before_tool_call`, `after_tool_call`, and tool-result middleware run around OpenClaw-owned dynamic tools. |

| Lifecycle hooks | Supported as adapter observations | `llm_input`, `llm_output`, `agent_end`, `before_compaction`, and `after_compaction` fire with honest Codex-mode payloads. |

| Native shell and patch block or observe | Supported through the native hook relay | Codex `PreToolUse` and `PostToolUse` are relayed for the committed native tool surfaces. Blocking is supported; argument rewriting is not. |

| Native permission policy | Supported through the native hook relay | Codex `PermissionRequest` can be routed through OpenClaw policy where the runtime exposes it. |

| App-server trajectory capture | Supported | OpenClaw records the request it sent to app-server and the app-server notifications it receives. |

| Surface | Support | Why |

| --------------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

| OpenAI model loop through Codex | Supported | Codex app-server owns the OpenAI turn, native thread resume, and native tool continuation. |

| OpenClaw channel routing and delivery | Supported | Telegram, Discord, Slack, WhatsApp, iMessage, and other channels stay outside the model runtime. |

| OpenClaw dynamic tools | Supported | Codex asks OpenClaw to execute these tools, so OpenClaw stays in the execution path. |

| Prompt and context plugins | Supported | OpenClaw builds prompt overlays and projects context into the Codex turn before starting or resuming the thread. |

| Context engine lifecycle | Supported | Assemble, ingest or after-turn maintenance, and context-engine compaction coordination run for Codex turns. |

| Dynamic tool hooks | Supported | `before_tool_call`, `after_tool_call`, and tool-result middleware run around OpenClaw-owned dynamic tools. |

| Lifecycle hooks | Supported as adapter observations | `llm_input`, `llm_output`, `agent_end`, `before_compaction`, and `after_compaction` fire with honest Codex-mode payloads. |

| Native shell, patch, and MCP block or observe | Supported through the native hook relay | Codex `PreToolUse` and `PostToolUse` are relayed for committed native tool surfaces, including MCP payloads on Codex app-server `0.125.0` or newer. Blocking is supported; argument rewriting is not. |

| Native permission policy | Supported through the native hook relay | Codex `PermissionRequest` can be routed through OpenClaw policy where the runtime exposes it. If OpenClaw returns no decision, Codex continues through its normal guardian or user approval path. |

| App-server trajectory capture | Supported | OpenClaw records the request it sent to app-server and the app-server notifications it receives. |

Not supported in Codex runtime v1:

| Surface | V1 boundary | Future path |

| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |

| Native tool argument mutation | Codex native pre-tool hooks can block, but OpenClaw does not rewrite Codex-native tool arguments. | Requires Codex hook/schema support for replacement tool input. |

| Editable Codex-native transcript history | Codex owns canonical native thread history. OpenClaw owns a mirror and can project future context, but should not mutate unsupported internals. | Add explicit Codex app-server APIs if native thread surgery is needed. |

| `tool_result_persist` for Codex-native tool records | That hook transforms OpenClaw-owned transcript writes, not Codex-native tool records. | Could mirror transformed records, but canonical rewrite needs Codex support. |

| Rich native compaction metadata | OpenClaw observes compaction start and completion, but does not receive a stable kept/dropped list, token delta, or summary payload. | Needs richer Codex compaction events. |

| Compaction intervention | Current OpenClaw compaction hooks are notification-level in Codex mode. | Add Codex pre/post compaction hooks if plugins need to veto or rewrite native compaction. |

| Stop or final-answer gating | Codex has native stop hooks, but OpenClaw does not expose final-answer gating as a v1 plugin contract. | Future opt-in primitive with loop and timeout safeguards. |

| Native MCP hook parity as a committed v1 surface | The relay is generic, but OpenClaw has not version-gated and tested native MCP pre/post hook behavior end to end. | Add OpenClaw MCP relay tests and docs once the supported app-server protocol floor covers those payloads. |

| Byte-for-byte model API request capture | OpenClaw can capture app-server requests and notifications, but Codex core builds the final OpenAI API request internally. | Needs a Codex model-request tracing event or debug API. |

| Surface | V1 boundary | Future path |

| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |

| Native tool argument mutation | Codex native pre-tool hooks can block, but OpenClaw does not rewrite Codex-native tool arguments. | Requires Codex hook/schema support for replacement tool input. |

| Editable Codex-native transcript history | Codex owns canonical native thread history. OpenClaw owns a mirror and can project future context, but should not mutate unsupported internals. | Add explicit Codex app-server APIs if native thread surgery is needed. |

| `tool_result_persist` for Codex-native tool records | That hook transforms OpenClaw-owned transcript writes, not Codex-native tool records. | Could mirror transformed records, but canonical rewrite needs Codex support. |

| Rich native compaction metadata | OpenClaw observes compaction start and completion, but does not receive a stable kept/dropped list, token delta, or summary payload. | Needs richer Codex compaction events. |

| Compaction intervention | Current OpenClaw compaction hooks are notification-level in Codex mode. | Add Codex pre/post compaction hooks if plugins need to veto or rewrite native compaction. |

| Stop or final-answer gating | Codex has native stop hooks, but OpenClaw does not expose final-answer gating as a v1 plugin contract. | Future opt-in primitive with loop and timeout safeguards. |

| Byte-for-byte model API request capture | OpenClaw can capture app-server requests and notifications, but Codex core builds the final OpenAI API request internally. | Needs a Codex model-request tracing event or debug API. |

## Tools, media, and compaction

continue through the normal OpenClaw delivery path.

The native hook relay is intentionally generic, but the v1 support contract is

limited to the Codex-native tool and permission paths that OpenClaw tests. Do not

assume every future Codex hook event is an OpenClaw plugin surface until the

runtime contract names it.

limited to the Codex-native tool and permission paths that OpenClaw tests. In

the Codex runtime, that includes shell, patch, and MCP `PreToolUse`,

`PostToolUse`, and `PermissionRequest` payloads. Do not assume every future

Codex hook event is an OpenClaw plugin surface until the runtime contract names

it.

For `PermissionRequest`, OpenClaw only returns explicit allow or deny decisions

when policy decides. A no-decision result is not an allow. Codex treats it as no

hook decision and falls through to its own guardian or user approval path.

Codex MCP tool approval elicitations are routed through OpenClaw's plugin

approval flow when Codex marks `_meta.codex_approval_kind` as

selected, its failures surface directly without extra fallback config.

**The app-server is rejected:** upgrade Codex so the app-server handshake

reports version `0.118.0` or newer.

reports version `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 the

stable `0.125.0` protocol floor is what OpenClaw tests.

**Model discovery is slow:** lower `plugins.entries.codex.config.discovery.timeoutMs`

or disable discovery.