openclaw - 💡(How to fix) Fix Gateway fails to start when allowedSessionKeyPrefixes contains only sub-prefixes (e.g. hook:ao:) [1 participants]

Summary

When hooks.allowedSessionKeyPrefixes is set to a sub-prefix like ["hook:ao:"] without a defaultSessionKey, the gateway refuses to start with:

Gateway failed to start: Error: hooks.allowedSessionKeyPrefixes must include 'hook:' when hooks.defaultSessionKey is unset

This is a usability issue because "hook:ao:" is a strict subset of "hook:" — it logically satisfies the requirement — but the validator rejects it. More importantly, the ao setup openclaw wizard writes exactly ["hook:ao:"] as the recommended prefix, meaning the wizard's own output produces a broken config.

Environment

• OpenClaw version: 2026.4.2
• OS: Ubuntu Linux 6.17.0 (x64)
• Node: 24.13.1
• Integration: Agent Orchestrator (AO) notifier plugin

Steps to Reproduce

1. Run ao setup openclaw (or manually set config below)
2. Set openclaw.json hooks config to:

{
  "hooks": {
    "enabled": true,
    "token": "<your-token>",
    "allowRequestSessionKey": true,
    "allowedSessionKeyPrefixes": ["hook:ao:"]
  }
}

1. Start the gateway: openclaw gateway start or via systemd
2. Gateway exits immediately with:

Gateway failed to start: Error: hooks.allowedSessionKeyPrefixes must include 'hook:' when hooks.defaultSessionKey is unset

Expected Behavior

One of:

Option A: The validator should accept sub-prefixes of "hook:" (e.g. "hook:ao:", "hook:myapp:") as satisfying the "hook:" requirement, since any session key matching "hook:ao:..." also starts with "hook:".

Option B: The ao setup openclaw wizard should automatically add defaultSessionKey (e.g. "hook:ao:default") when writing sub-prefixes, so the output config is always valid.

Option C: The error message should clearly say both options: "add 'hook:' to allowedSessionKeyPrefixes OR set defaultSessionKey" — right now it only implies the first option.

Actual Behavior

Gateway crashes on startup. The only fix is to manually add "hook:" to allowedSessionKeyPrefixes AND/OR set defaultSessionKey, which is not obvious from the error message.

Workaround

Add both "hook:" and "hook:ao:" to the prefix list, and set a defaultSessionKey:

{
  "hooks": {
    "enabled": true,
    "token": "<your-token>",
    "allowRequestSessionKey": true,
    "defaultSessionKey": "hook:ao:default",
    "allowedSessionKeyPrefixes": ["hook:", "hook:ao:"]
  }
}

Why This Matters

The ao setup openclaw wizard is the recommended setup path. It writes ["hook:ao:"] as the prefix. A user who follows the wizard exactly ends up with a gateway that won't start, with an error message that doesn't mention ao setup openclaw or the wizard as the source of the problem. This makes it very hard to debug without prior knowledge of the validation rules.