OpenClaw config hooks

Most assistants become useful the moment something outside them can start the conversation. OpenClaw covers that with inbound hooks: a small HTTP surface on the Gateway that accepts a JSON body and turns it into a wake or an agent run. The surface is deliberately narrow, and almost every interesting decision is a configuration decision rather than a code one. Getting those decisions wrong does not usually produce an error; it produces a path where the payload is untrusted and nothing about the sender is proven.

What the endpoint promises

• The endpoints stay closed until the hooks block is enabled and given a nonempty shared token, which authenticates ingress and nothing else, so payload content stays untrusted and the target agent still needs its own tool and workspace limits.
• Authentication is accepted as a bearer header or a dedicated OpenClaw token header, a token passed as a query parameter is rejected with 400 even when a valid header is also present, and after twenty failed attempts in a sixty second window further invalid attempts from that client are throttled with 429 and a retry delay, with no exemption for loopback.
• The ordinary request body limit is 256 KiB with a thirty second body read timeout, the Gmail path derives a larger allowance from its per message byte limit, and fan out still processes only the first two hundred items of an array, dropping the excess with a warning rather than an HTTP failure.
• A direct agent call returns a run identifier once the run is admitted, admission that does not happen within fifteen seconds returns 503 and cancels that queued work, and an HTTP 200 proves admission rather than a model result or a delivered message.

Persistence controls conversation reuse, not tool permissions or sandboxing.

Sessions, mappings and transforms

Session policy is where most of the configuration weight sits. A logical key resolves from the request or the matching mapping, then from a configured default, and finally from a generated hook key carrying a uuid, and a configured default must itself match the prefix allowlist. Persistent mode on the direct agent endpoint requires an explicit request key, the caller key opt in and a nonempty prefix allowlist, while a persistent mapping needs a stable mapping key or a default one. Templated mapping keys need the prefix allowlist at configuration time and the caller key opt in at dispatch, and that includes the built in Gmail preset unless an earlier mapping overrides it. Requests sharing a canonical logical key are serialised through completion even in isolated mode, so a fixed default orders them and can also push a later request into the admission timeout while an earlier run is still active. Mappings are evaluated in array order before presets, the first match owns the request including a transform that returns nothing, and later mappings are not tried. Templates can read payload fields, array positions, headers, query values, the path and an ISO timestamp, with missing values becoming empty strings and objects serialised as JSON. Transforms are trusted Gateway code rather than agent sandbox code, they live under a constrained transforms directory that rejects traversal and symlink escapes, and they stay cached until the hook configuration reloads. A transform that returns nothing ends the request with 204 before any run, task, execution identity or audit receipt exists.

Retries and fan out

• Replay keys are read from an idempotency header, then an OpenClaw specific header, then the payload field, and only trimmed nonempty strings of at most 256 characters are used, with the same key replaying only for the same token, path and resolved dispatch fields.
• A terminal replay entry expires five minutes after completion settles and counts against a bound of one thousand terminal entries, pending admissions are retained without expiry, and a restart clears replay state entirely while failed admissions stay retryable.
• Fan out waits up to eight seconds after mapping and transform work, returns the admitted run identifiers with a dispatched count, and can report an error alongside work that is still pending, which is why the reference describes it as something short of durable exactly once processing.

If you are wiring this for the first time, read the hooks reference next to the Gateway configuration reference, because the endpoint contract and the session policy are written as one story and the defaults only make sense together.

Why the contract is narrow

Read the field tables and a pattern appears: nearly every guarantee is stated together with what it is not. A token grants ingress, not identity. A queued wake asks for a heartbeat without proving one ran. A completion status reports that a reply existed without exposing a single character of it, and a delivery error collapses to one categorical value. That restraint is what lets the OpenClaw Gateway accept calls from systems it cannot vouch for, and the same instinct shows up in the advice about prompt injection. The cost is that operators have to read carefully, because the happy path and the proven path are not the same path.

On Diali

On Diali each customer runs their own assistant, channels are connected from the dashboard, and the runtime configuration is generated from it and replaced at each release. State lives on a persistent volume, with daily snapshots and one-click restore available through the Backups add-on (included on Max). If you want to see how the hosted shape differs from a self managed one, Hosted OpenClaw on Diali and Diali pricing are the places to start.

• Hooks stay closed until a token is set.
• HTTP 200 proves admission, not a delivered answer.
• Fan out stops at two hundred items per request.