openclaw - 💡(How to fix) Fix 5.26 regression: "Native hook relay unavailable" after relay re-register due to generation UUID staleness

Summary

After upgrading to 2026.5.26, codex tool calls intermittently fail with Native hook relay unavailable. Gateway restart fixes briefly, error returns.

Environment

• macOS 25.5.0 (Darwin)
• openclaw 2026.5.26 (10ad3aa)
• node 26.0.0 (homebrew)
• bundled codex 0.134.0
• previous working version: 2026.5.22

Root cause (from source diff 5.22 → 5.26)

dist/native-hook-relay-AN6S_wz5.js:

5.26 added a generation: randomUUID() field to each relay registration, embedded --generation <uuid> into the tool command built by commandForEvent, and added validation:

if (params.requireGeneration) {
  if (readNonEmptyString(params.generation, "generation") !== registration.generation)
    throw new Error(NATIVE_HOOK_RELAY_BRIDGE_STALE_REGISTRATION_ERROR);
}

HTTP bridge also returns 410 with stale registration when auth doesn't match current bridge:

if (!isCurrentNativeHookRelayBridgeRequest(auth)) {
  writeNativeHookRelayBridgeJson(res, 410, {
    ok: false,
    error: NATIVE_HOOK_RELAY_BRIDGE_STALE_REGISTRATION_ERROR
  });
}

Wrapper in hooks-cli-Cy_Rqd6n.js maps the stale error to user-visible "Native hook relay unavailable".

Failure sequence

1. Gateway registers relay → generation UUID_A
2. Tool command built with --generation UUID_A, sent to codex
3. Codex caches the command in its session tool definitions
4. Relay re-registers (gateway restart, TTL expiry, session reinit) → generation rotates to UUID_B
5. Codex executes cached command with --generation UUID_A
6. Validation: UUID_A !== UUID_B → throws stale registration → user sees Native hook relay unavailable
7. Subsequent shell tool calls fail until codex re-loads tool definitions

Repro

1. Upgrade to 5.26
2. Open openclaw session, run a few shell commands (work)
3. Trigger a gateway restart (`SIGUSR1`) or wait for relay TTL expiry
4. Run another shell command → `Native hook relay unavailable`

Workaround

Downgrade: `npm i -g [email protected]`.

Suggested fix direction

Either:

• Broadcast new generation to active codex sessions on re-register so tool defs refresh, OR
• Allow relay invocations from any generation that shares `relayId` while the registration is alive (keep `requireGeneration` for explicit fencing only), OR
• Stable generation per relayId across re-registers (don't rotate UUID unless registration intentionally invalidated).

Side note

Same `2026.5.26` update doctor logs unrelated `PluginStateStoreError: Plugin state for telegram exceeds the 1000 live row limit` — `telegram.message-cache` namespace writes rows with `expires_at = NULL` which never get evicted. Probably worth a separate issue but flagging for context since both surfaced together on upgrade.