openclaw/docs/gateway/security/exposure-runbook.md

---
summary: "Pre-flight and rollback checklist before exposing an OpenClaw Gateway beyond loopback"
title: "Gateway exposure runbook"
sidebarTitle: "Exposure runbook"
read_when:
  - Exposing the Gateway over LAN, tailnet, Tailscale Serve, Funnel, or a reverse proxy
  - Reviewing a deployment before allowing real messaging users
  - Rolling back a risky remote access or DM configuration
---

<Warning>
Expose the Gateway only after you can explain who can reach it, how they are
authenticated, which agents they can trigger, and which tools those agents can
use. When in doubt, return to loopback-only access and re-run the audit.
</Warning>

This runbook turns the broader [Security](/gateway/security) guidance into an
operator checklist for remote access and messaging exposure.

## Choose the exposure pattern

Prefer the narrowest pattern that satisfies the workflow.

| Pattern                    | Recommended when                                | Required controls                                                                                   |
| -------------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| Loopback + SSH tunnel      | Personal use, admin access, debugging           | Keep `gateway.bind: "loopback"` and tunnel `127.0.0.1:18789`                                        |
| Loopback + Tailscale Serve | Personal tailnet access to Control UI/WebSocket | Keep Gateway loopback-only; rely on Tailscale identity headers only for supported surfaces          |
| Tailnet/LAN bind           | Dedicated private network with known devices    | Gateway auth, firewall allowlist, no public port-forward                                            |
| Trusted reverse proxy      | Organization SSO/OIDC in front of Gateway       | `trusted-proxy` auth, strict `trustedProxies`, header overwrite/strip rules, explicit allowed users |
| Public internet            | Rare, high-risk deployments                     | Identity-aware proxy, TLS, rate limits, strict allowlists, sandboxed non-main sessions              |

Avoid direct public port-forwarding to the Gateway. If you need public access,
put an identity-aware proxy in front of it and make the proxy the only network
path to the Gateway.

## Pre-flight inventory

Record these before changing bind, proxy, Tailscale, or channel policy:

- Gateway host, OS user, and state directory.
- Gateway URL and bind mode.
- Auth mode, token/password source, or trusted proxy identity source.
- All enabled channels and whether they accept DMs, groups, or webhooks.
- Agents reachable from non-local senders.
- Tool profile, sandbox mode, and elevated tool policy for each reachable agent.
- External credentials available to those agents.
- Backup location for `~/.openclaw/openclaw.json` and credentials.

If more than one person can message the bot, treat this as shared delegated tool
authority, not as per-user host isolation.

## Baseline checks

Run these before opening access:

```bash
openclaw doctor
openclaw security audit
openclaw security audit --deep
openclaw health
```

Resolve critical findings first. Warnings may be acceptable only when they are
intentional and documented for the deployment.

For remote CLI validation, pass credentials explicitly:

```bash
openclaw gateway probe --url ws://127.0.0.1:18789 --token "$OPENCLAW_GATEWAY_TOKEN"
```

Do not assume local config credentials apply to an explicit remote URL.

## Minimum safe baseline

Use this shape as the starting point for exposed deployments:

```json5
{
  gateway: {
    bind: "loopback",
    auth: {
      mode: "token",
      token: "replace-with-a-long-random-token",
    },
  },
  session: {
    dmScope: "per-channel-peer",
  },
  agents: {
    defaults: {
      sandbox: { mode: "non-main" },
    },
  },
  tools: {
    profile: "messaging",
    exec: { security: "deny", ask: "always" },
    elevated: { enabled: false },
  },
}
```

Then widen one control at a time. For example, add a specific channel allowlist
before enabling write-capable tools, or enable a reverse proxy before accepting
remote Control UI traffic.

The strict `exec.security: "deny"` baseline blocks all exec calls, including
benign diagnostics. If diagnostics or low-risk commands are required, relax this
only after choosing the specific senders, agents, commands, and approval mode
that match your threat model.

## DM and group exposure

Messaging channels are untrusted input surfaces. Before allowing DMs or groups:

- Prefer `dmPolicy: "pairing"` or strict `allowFrom` lists.
- Avoid `dmPolicy: "open"` unless every sender is trusted.
- Do not combine `"*"` allowlists with broad tool access.
- Require mentions in groups unless the room is tightly controlled.
- Use `session.dmScope: "per-channel-peer"` when multiple people can DM the bot.
- Route shared channels to agents with minimal tools and no personal credentials.

Pairing approves the sender to trigger the bot. It does not make that sender a
separate host security boundary.

## Reverse proxy checks

For identity-aware proxies:

- The proxy must authenticate users before forwarding to the Gateway.
- Direct access to the Gateway port must be blocked by firewall or network policy.
- `gateway.trustedProxies` must contain only the proxy source IPs.
- The proxy must strip or overwrite client-supplied identity and forwarding headers.
- `gateway.auth.trustedProxy.allowUsers` should list expected users when the proxy serves more than one audience.
- Same-host loopback proxy mode should use `allowLoopback` only when local processes are trusted and the proxy owns the identity headers.

Run `openclaw security audit --deep` after proxy changes. Trusted-proxy findings
are intentionally high-signal because the proxy becomes the authentication
boundary.

## Tool and sandbox review

Before exposing an agent to remote senders:

- Confirm which sessions run on host versus sandbox.
- Deny or require approval for host exec.
- Keep elevated tools disabled unless a specific, trusted sender needs them.
- Avoid browser, canvas, node, cron, gateway, and session-spawn tools for open or semi-open messaging surfaces.
- Keep bind mounts narrow and avoid credential, home, Docker socket, and system paths.
- Use separate gateways, OS users, or hosts for materially different trust boundaries.

If remote users are not fully trusted, isolation must come from separate
deployments, not only from prompts or session labels.

## Post-change validation

After each exposure change:

1. Re-run `openclaw security audit --deep`.
2. Test a successful authorized connection.
3. Test that an unauthorized sender or browser session is denied.
4. Confirm logs redact secrets.
5. Confirm DM/group routing reaches only the intended agent.
6. Confirm high-impact tools ask for approval or are denied.
7. Document the accepted residual warnings.

Do not proceed to the next exposure change until the current one is understood.

## Rollback plan

If the Gateway may be overexposed:

```json5
{
  gateway: {
    bind: "loopback",
  },
  channels: {
    whatsapp: { dmPolicy: "disabled" },
    telegram: { dmPolicy: "disabled" },
    discord: { dmPolicy: "disabled" },
    slack: { dmPolicy: "disabled" },
  },
  tools: {
    exec: { security: "deny", ask: "always" },
    elevated: { enabled: false },
  },
}
```

Then:

1. Stop public forwarding, Tailscale Funnel, or reverse proxy routes.
2. Rotate Gateway tokens/passwords and affected integration credentials.
3. Remove `"*"` and unexpected senders from allowlists.
4. Review recent audit logs, run history, tool calls, and config changes.
5. Re-run `openclaw security audit --deep`.
6. Re-enable access with the narrowest pattern that satisfies the workflow.

## Review checklist

- Gateway remains loopback-only unless there is a documented reason.
- Non-loopback access has auth, firewalling, and no public direct route.
- Trusted-proxy deployments have strict proxy IPs and header controls.
- DMs use pairing or allowlists, not open access by default.
- Groups require mentions or explicit allowlists.
- Shared channels do not reach personal credentials.
- Non-main sessions run in sandbox mode.
- Host exec and elevated tools are denied or approval-gated.
- Logs redact secrets.
- Critical audit findings are resolved.
- Rollback steps are tested and documented.