From da1a3434f48d87256ba70603d73131d493bf6680 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Wed, 27 May 2026 19:46:26 +0100 Subject: [PATCH] docs: document native Codex hook relay recovery --- docs/plugins/codex-harness.md | 11 +++++++++-- docs/tools/acp-agents.md | 7 +++++++ 2 files changed, 16 insertions(+), 2 deletions(-) diff --git a/docs/plugins/codex-harness.md b/docs/plugins/codex-harness.md index f46130e7e331..ccea4191a09d 100644 --- a/docs/plugins/codex-harness.md +++ b/docs/plugins/codex-harness.md @@ -734,14 +734,21 @@ that any custom `appServer.command`, `url`, `authToken`, or headers are valid. 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 the +same fresh session still fails, restart the Codex app-server or OpenClaw Gateway +so 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 `/new` or `/reset`; if it persists, restart -the gateway to clear stale native hook registrations. See +`Native hook relay unavailable`, use the native hook relay recovery above. See [Codex Computer Use](/plugins/codex-computer-use#troubleshooting). ## Related diff --git a/docs/tools/acp-agents.md b/docs/tools/acp-agents.md index bb046543d98d..1d9d1a7876f7 100644 --- a/docs/tools/acp-agents.md +++ b/docs/tools/acp-agents.md @@ -834,6 +834,13 @@ permission modes, see | ACP session stalls indefinitely after completing work | Harness process finished but ACP session did not report completion. | Update OpenClaw; current acpx cleanup reaps OpenClaw-owned stale wrapper and adapter processes on close and Gateway startup. | | Harness sees `<<>>` | Internal event envelope leaked across the ACP boundary. | Update OpenClaw and rerun the completion flow; external harnesses should receive plain completion prompts only. | + +`Command blocked by PreToolUse hook: Native hook relay unavailable` belongs to +the native Codex hook relay, not ACP/acpx. In a bound Codex chat, start a fresh +session with `/new` or `/reset`; if it persists, restart the Codex app-server or +OpenClaw Gateway. See [Codex harness troubleshooting](/plugins/codex-harness#troubleshooting). + + ## Related - [ACP agents - setup](/tools/acp-agents-setup)