- Keep `hooks.allowRequestSessionKey=false` unless you require caller-selected sessions.

- If you enable `hooks.allowRequestSessionKey`, also set `hooks.allowedSessionKeyPrefixes` to constrain allowed session key shapes.

- Hook payloads are wrapped with safety boundaries by default.

</Warning>

</Warning>

## Gmail PubSub integration

- Configured fallback chains still apply because cron `--model` is a job primary, not a session `/model` override.

- Payload `fallbacks` replaces configured fallbacks for that job; `fallbacks: []` disables fallback and makes the run strict.

- A plain `--model` with no explicit or configured fallback list does not fall through to the agent primary as a silent extra retry target.

</Note>

</Note>

## Configuration

- Always set a webhook password.

- Webhook authentication is always required. OpenClaw rejects BlueBubbles webhook requests unless they include a password/guid that matches `channels.bluebubbles.password` (for example `?password=<password>` or `x-password`), regardless of loopback/proxy topology.

- Password authentication is checked before reading/parsing full webhook bodies.

</Warning>

</Warning>

## Keeping Messages.app alive (VM / headless setups)

- **DM access** is controlled by `*.allowFrom`.

- **Group access** is controlled by `*.groupPolicy` + allowlists (`*.groups`, `*.groupAllowFrom`).

- **Reply triggering** is controlled by mention gating (`requireMention`, `/activation`).

</Note>

</Note>

Quick flow (what happens to a group message):

4. Action `id` must be **alphanumeric only** (`[a-zA-Z0-9]`). Hyphens and underscores break Mattermost's server-side action routing (returns 404). Strip them before use.

5. `context.action_id` must match the button's `id` so the confirmation message shows the button name (e.g., "Approve") instead of a raw ID.

6. `context.action_id` is required — the interaction handler returns 400 without it.

</Warning>

</Warning>

**HMAC token generation**

- Add the model to `agents.defaults.models`, or

- Clear the allowlist (remove `agents.defaults.models`), or

- Pick a model from `/model list`.

</Warning>

</Warning>

Example allowlist config:

- `main` (default): agent main session.

- Explicit session key (copy from `openclaw sessions --json` or the [sessions CLI](/cli/sessions)).

- Session key formats: see [Sessions](/concepts/session) and [Groups](/channels/groups).

</ParamField>

</ParamField>

<ParamField path="target" type="string">

- `last`: deliver to the last used external channel.

- explicit channel: any configured channel or plugin id, for example `discord`, `matrix`, `telegram`, or `whatsapp`.

- Live node commands come from what the node declares on connect after the gateway's global node command policy (`gateway.nodes.allowCommands` and `denyCommands`) is applied.

- Per-node `system.run` allow and ask policy lives on the node in `exec.approvals.node.*`, not in the pairing record.

</Warning>

</Warning>

## Node command gating (2026.3.31+)

- Sensitive mounts (secrets, SSH keys, service credentials) should be `:ro` unless absolutely required.

- Combine with `workspaceAccess: "ro"` if you only need read access to the workspace; bind modes stay independent.

- See [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated) for how binds interact with tool policy and elevated exec.

</Warning>

</Warning>

## Images and setup

- Internal Gateway clients that do not travel through the reverse proxy should use `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD`, not trusted-proxy identity headers.

- Non-loopback Control UI deployments still need explicit `gateway.controlUi.allowedOrigins`.

- **Forwarded-header evidence overrides loopback locality for local direct fallback.** If a request arrives on loopback but carries `X-Forwarded-For` / `X-Forwarded-Host` / `X-Forwarded-Proto` headers pointing at a non-local origin, that evidence disqualifies local-direct password fallback and device-identity gating. With `allowLoopback: true`, trusted-proxy auth can still accept the request as a same-host proxy request, while `requiredHeaders` and `allowUsers` continue to apply.

</Warning>

</Warning>

### Configuration reference

- `minimax` and `minimax-portal` image understanding comes from the plugin-owned `MiniMax-VL-01` media provider.

- The bundled MiniMax text catalog still starts text-only; explicit `models.providers.minimax` entries materialize image-capable M2.7 chat refs.

</Note>

</Note>

## Model selection guidance