OpenClaw · inbound email

An email arrives. Your OpenClaw agent wakes up.

Install one skill, give the agent a free inbox, and route inbound mail into a dedicated Gateway hook with header-only authentication.

Prerequisite: a working OpenClaw agent with a model provider configured · no polling · custom domain later

OpenClaw · current install

$openclaw skills install @gwendall/domani

Installed · @gwendall/domani

$openclaw skills verify @gwendall/domani

Verified · latest release

$npx domani-cli login --surface skill

Approved · credential stored in OS keychain

The event path

Webhook triggering replaces an inbox polling loop.

Email arrives

A message lands in agent@domani.run.

Domani authenticates

Authorization plus X-Domani-Signature accompany the event.

Gateway maps

/hooks/domani-email turns the payload into an isolated agent task.

Agent acts

OpenClaw can deliver the final response to the configured channel.

Polling

Repeated reads, idle requests, and delay set by the polling interval.

Webhook

One push when mail is processed; reconcile the stored inbox only after receiver downtime.

1 · Gateway ingress

Map Domani's payload into an isolated agent run.

Merge this into `~/.openclaw/openclaw.json`; preserve stricter existing settings. Put two different long random values in the Gateway environment or `~/.openclaw/.env`: `OPENCLAW_GATEWAY_TOKEN` for control-plane auth and `OPENCLAW_HOOK_TOKEN` for this ingress. Agent hook runs are isolated by default. Restart after validating.

openclaw.json · merge, do not replace

${ gateway: { mode: "local", bind: "loopback", auth: { mode: "token", token: "${OPENCLAW_GATEWAY_TOKEN}" } }, hooks: { enabled: true, token: "${OPENCLAW_HOOK_TOKEN}", path: "/hooks", allowRequestSessionKey: false, allowedAgentIds: ["main"], mappings: [{ match: { path: "domani-email" }, action: "agent", agentId: "main", wakeMode: "now", name: "Domani email", messageTemplate: "New email for {{email}}\nFrom: {{message.from}}\nSubject: {{message.subject}}\n\n{{message.text}}", deliver: true, channel: "last" }] } }

Dedicated token

Use a long random value and do not reuse OPENCLAW_GATEWAY_TOKEN. OpenClaw flags reuse as a critical security finding.

Trusted exposure

Keep the Gateway loopback-only and expose the hook through HTTPS via a tailnet or trusted reverse proxy. Configure trustedProxies to the exact proxy IPs when applicable.

Restricted agent

Treat email as untrusted input. Use a restricted tool policy and keep unsafe-content bypasses disabled.

Official OpenClaw webhook reference Official security configuration

2 · Domani mailbox

Pass the token by environment variable, then prove delivery.

Use the externally reachable HTTPS form of your mapped hook. The hidden prompt keeps the bearer value out of shell history and the CLI reads it without printing it.

Domani CLI · secret-safe

$read -rsp 'OpenClaw hook token: ' OPENCLAW_HOOK_TOKEN; echo

$export OPENCLAW_HOOK_AUTH="Bearer $OPENCLAW_HOOK_TOKEN"

$domani email webhook agent@domani.run --url 'https://YOUR_GATEWAY/hooks/domani-email' --authorization-env OPENCLAW_HOOK_AUTH

Webhook configured · Authorization

$domani email webhook-test agent@domani.run

Test delivered · HTTP 200

$unset OPENCLAW_HOOK_TOKEN OPENCLAW_HOOK_AUTH

Test first

Require a 2xx result before sending live mail.

Live second

Send one real email and confirm exactly one isolated task starts.

Reconcile after downtime

Live mailbox callbacks are attempted up to three times. Still read the stored inbox after longer Gateway downtime because webhook delivery is at-least-once and retry windows are bounded.

Troubleshooting

Four boundaries to check.

401 / 429Check the dedicated hook token. OpenClaw rate-limits repeated auth failures; wait for Retry-After instead of retrying harder.

404Confirm hooks.enabled, hooks.path and the mapping path. The Domani URL must end in /hooks/domani-email for this example.

TimeoutReturn acceptance before long agent work. Domani's test has a 10-second receiver timeout.

Agent does not runValidate config, restart the Gateway, verify allowedAgentIds, then inspect Gateway logs for mapping or model-policy rejection.

The Domani test proves that the Gateway accepted the HTTP event. It does not measure the downstream model's completion time.

First result

Create the inbox. Test the hook. Send the email.

Keep the custom-domain decision for after the event loop works.

Community integration using documented OpenClaw and Domani interfaces.

Domani webhook API ClawHub listing