diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json index 5924a1868..26f7a4eb7 100644 --- a/.openclaw-sync/source.json +++ b/.openclaw-sync/source.json @@ -1,5 +1,5 @@ { "repository": "openclaw/openclaw", - "sha": "e2fd3dcee9cdd37f89d1037b29ec70f9d59eec46", - "syncedAt": "2026-04-25T20:34:31.784Z" + "sha": "34fb96622eb69d11d95fb0ea90f755a73939842a", + "syncedAt": "2026-04-25T20:36:40.174Z" } diff --git a/docs/plugins/codex-harness.md b/docs/plugins/codex-harness.md index 37dd240ae..8798d91f7 100644 --- a/docs/plugins/codex-harness.md +++ b/docs/plugins/codex-harness.md @@ -103,7 +103,8 @@ Codex after changing config. ## 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 @@ -551,7 +552,7 @@ normal turns. On the next message, OpenClaw resumes that Codex thread, passes th 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. @@ -597,31 +598,30 @@ around that boundary. 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 @@ -632,9 +632,15 @@ harness. Text, images, video, music, TTS, approvals, and messaging-tool output 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 @@ -677,7 +683,9 @@ explicitly set `embeddedHarness.fallback: "pi"`. Once Codex app-server is 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. diff --git a/docs/plugins/sdk-agent-harness.md b/docs/plugins/sdk-agent-harness.md index a488c411e..c19f90271 100644 --- a/docs/plugins/sdk-agent-harness.md +++ b/docs/plugins/sdk-agent-harness.md @@ -142,9 +142,11 @@ Codex provider and harness for compatibility. For operator setup, model prefix examples, and Codex-only configs, see [Codex Harness](/plugins/codex-harness). -OpenClaw requires Codex app-server `0.118.0` or newer. The Codex plugin checks +OpenClaw requires Codex app-server `0.125.0` or newer. The Codex plugin checks the app-server initialize handshake and blocks older or unversioned servers so -OpenClaw only runs against the protocol surface it has been tested with. +OpenClaw only runs against the protocol surface it has been tested with. The +`0.125.0` floor includes the native MCP hook payload support that landed in +Codex `0.124.0`, while pinning OpenClaw to the newer tested stable line. ### Tool-result middleware