Before You Expose an OpenClaw Gateway, Write Down the Trust Boundary

Published June 5, 2026 · OpenClawBlog Team. Sources rechecked September 13, 2026.

A Gateway that answers only on loopback has a simple first boundary: a remote machine cannot open its socket. Move it to a LAN address, a tailnet, a reverse proxy, or a public route and that assumption disappears. The change is easy to describe as remote access. It is better understood as a change to who can reach OpenClaw's control plane.

The control plane is not a single chat box. OpenClaw's current documentation describes one Gateway owning sessions, authentication profiles, channels, and state. Its network surface multiplexes WebSocket and HTTP on one port, including the Control UI and agent-authored canvas and A2UI content. A mistake at the edge can therefore expose more than the page you intended to share. See the network exposure guidance for the documented surface.

This is the threat model I would write before opening access: who may connect, what counts as proof of identity, which agent receives the request, what that agent can call, which data it can read, and how the route will be closed if the answer changes. The checks below are proposed operator checks, not a local OpenClaw test. The documentation and advisory pages were opened on September 13, 2026; the installed version and deployment still need their own verification.

Start with a one-sentence trust statement

OpenClaw's security model assumes one trusted boundary per Gateway: a single operator or a team whose members trust one another. The repository's security policy says authenticated Gateway callers are treated as trusted operators, and that one Gateway is not a hostile multi-tenant boundary. This is the sentence that changes the rest of the design.

Write a statement such as:

The Gateway is for these people and devices. They may use this agent for this job. They may not use it to reach personal accounts, unrelated workspaces, or another trust group.

Then name the exception. If the route is public, the untrusted party is not only the person who opens a connection. It also includes messages, documents, web pages, attachments, and logs that the agent may be asked to read.

Before touching gateway.bind, record the Gateway host and OS user, the state directory, the URL and port, the authentication mode and secret source, enabled channels, reachable agents, tool profiles, sandbox and elevated policies, external credentials, and the backup location. That list comes directly from the Gateway exposure runbook. If you cannot fill it in, the deployment is not ready for a wider network.

Use a separate Gateway, OS user, or host when operators are mutually untrusted. Separate agent names or session labels can make a shared installation easier to navigate, but they do not change the trust cell.

Map every boundary between sender and side effect

The useful diagram is a path, not a list of features:

sender or device → network or proxy → Gateway authentication → channel, UI, or API route → session and agent → tools, nodes, plugins, files, and outgoing services

The OpenClaw threat model uses a similar flow from channels to the Gateway, then to agents, tools, and external services. Turn each arrow into a question.

Two details are easy to miss. First, sessionKey is a routing control, not a per-user authorization boundary. Second, pairing approves a sender or device to trigger the bot; it does not create a separate host security boundary. If you need those stronger boundaries, move the workload to a separate deployment.

Choose an exposure pattern, not just a bind value

The exposure runbook recommends the narrowest pattern that satisfies the workflow:

OpenClaw's network guidance says loopback is the default, while lan, tailnet, and custom expand the attack surface. The same page says the Gateway should never be exposed unauthenticated on 0.0.0.0. Saying it is behind my router is not a threat model; it leaves the reachable source set and the authentication boundary unclear.

A reverse proxy is not automatically a security layer. The trusted proxy documentation requires the proxy to authenticate the user, the Gateway to trust only the proxy's source addresses, and the proxy to add identity headers that it controls. Firewall direct access to the Gateway port. Strip or overwrite client-supplied forwarding and identity headers. Set an explicit allowUsers list when the proxy serves more than one audience. A TLS terminator that does none of this is not an identity-aware proxy.

Define the assets and the actors

List the assets before listing mitigations. OpenClaw's storage guidance says the state directory may contain Gateway and remote credentials, channel credentials, pairing allowlists, model authentication, MCP OAuth sessions, transcripts, tool output, and installed plugins. The browser profile and paired nodes add another class of asset: a person who can drive them may be able to act as the logged-in user or run commands on the paired device.

For a first draft, consider these actors:

• An internet scanner or LAN user who can find the port and guess, replay, or steal a credential.
• A caller with a valid Gateway secret or a compromised proxy identity. OpenClaw treats that caller as an operator for the Gateway, not as a narrowly scoped chat sender.
• A trusted person who forwards a poisoned page, email, document, attachment, log, or code sample to the agent.
• A public or semi-public group participant who can influence a shared agent through a channel policy.
• A local process or OS user that can read the Gateway state, environment, browser profile, or socket.

The model is not a trusted principal. The prompt-injection guidance treats content itself as hostile, even when only one operator can message the bot. A strong model may reduce the chance of following a malicious instruction, but it does not replace tool policy, approvals, sandboxing, or sender controls.

Put the controls in writing

Authentication and edge controls

Use an explicit token or password mode for any non-loopback deployment, keep the secret out of chat and source control, and give remote clients only the credential path they need. There is an important limitation here: current OpenClaw guidance treats shared-secret bearer access to /v1/*, /tools/invoke, and other Gateway-protected HTTP routes as full operator access. A token is therefore not a read-only API key just because the client only intends to read.

Rate limiting helps with guessing but does not make a public endpoint safe. The documented default for failed token, password, or device authentication is ten failures per 60 seconds followed by a five-minute lockout per client IP and credential scope. Loopback is exempt by default, and other IPs are unaffected by one client's lockout. Put the limit behind a firewall and an identity-aware edge when the endpoint is reachable beyond a trusted private network.

Channels and content

For DMs, start with pairing or a strict allowlist. The access-control documentation says open DM access requires an explicit wildcard allow entry. For groups, decide whether membership is trusted, require mentions where ambient messages are not trusted, and do not combine a wildcard allowlist with broad tools. If several people can DM the bot, use a channel-and-peer session scope so a fresh sender does not inherit a shared conversation.

These controls reduce who can start a turn. They do not sanitize a document or prevent an approved operator from asking the agent to follow hostile instructions. Keep web, browser, fetch, and other high-risk inputs out of a lower-trust agent unless the task actually needs them.

Tools, nodes, and plugins

Start an exposed agent with a narrow tool profile. The official tool-permissions guidance identifies gateway and cron as control-plane-sensitive, and recommends denying them, along with session-spawn and session-send tools, for agents that handle untrusted content unless the workflow requires them. A paired macOS node can expose system.run, which the documentation describes as remote code execution on that Mac. Native plugins run in the Gateway process and should be treated as host-trusted code.

A conservative starting point is non-main sandboxing, host exec denied or approval-gated, elevated mode disabled, narrow bind mounts, and no personal browser profile or credentials. The runbook's example uses a messaging profile with exec.security set to deny and elevated tools disabled. That setting also blocks benign diagnostics. Record the tradeoff rather than quietly weakening it when a health check fails.

Host and stored data

Use a dedicated OS user or host for a materially different trust group. Lock down the state directory and configuration; OpenClaw recommends user-only directory and file permissions, commonly 700 for directories and 600 for files, plus full-disk encryption. Use a dedicated browser profile and dedicated service accounts for a shared business agent. Do not put a personal password manager or personal Apple or Google account on the same runtime you expose to other people.

Version and feature gates

Include the exact OpenClaw package version, enabled plugins, paired clients, and enabled HTTP or channel features in the threat model. Historical advisories show why having a Gateway token is not enough. GHSA-943q-mwmv-hhvh affected OpenClaw versions before 2026.2.14: a caller with a valid Gateway token could reach higher-risk session tools through /tools/invoke depending on policy. The advisory says it was not a drive-by unauthenticated issue and records the fix in 2026.2.14.

GHSA-cwj3-vqpp-pmxr affected versions before 2026.4.23. A prompt-injected model with access to the owner-only Gateway tool could persist unsafe changes to settings such as network, proxy, TLS, credentials, and tool policy. The advisory explicitly describes this as a model-to-operator guard bypass, not a remote unauthenticated Gateway compromise. Those are historical, version-scoped records; check the installed package and the features you have enabled instead of borrowing their ranges as a universal safe floor.

Test the denial paths before calling it safe

Proposed checks, not a hands-on test for this article. Run the documented preflight on a controlled machine:

openclaw doctor
openclaw security audit
openclaw security audit --deep
openclaw health

Resolve critical findings. Then test the path as an operator would experience it:

• An authorized client succeeds, while a wrong token, an unapproved device, and an unapproved sender are denied.
• A direct connection to the Gateway port fails when the reverse proxy is the intended only path.
• A request with forged X-Forwarded-For or identity headers does not become a trusted proxy request.
• A non-loopback Control UI accepts only the intended origins; avoid allowedOrigins set to * outside controlled testing.
• A Tailscale Serve connection does not accidentally imply access to HTTP APIs that use ordinary Gateway authentication.
• An unknown DM receives the expected pairing or blocking behavior, and a group needs the intended mention or allowlist condition.
• A content-injection test using dummy files cannot call denied tools, read a production path, send a message, or reach a personal browser.
• Logs and transcripts redact secrets, and the route still behaves correctly after a Gateway restart.

After each exposure change, the runbook asks for an authorized success, an unauthorized denial, correct routing, secret-redacted logs, and approval or denial for high-impact tools. Keep the result with the configuration revision. A green audit is evidence of checks passing; it is not proof that every proxy, plugin, model, or channel behaves safely.

Plan the failures and the rollback

Some failures are useful signals. A trusted-proxy request from an unconfigured source can be rejected with proxy_attribution_required instead of being treated as a local request. Fix the proxy source list and header handling; do not solve that error by allowing every source. If a same-host proxy is used, enabling allowLoopback explicitly trusts local processes to the same degree as the proxy, so keep the Gateway firewalled from direct remote access.

If the Control UI works through Tailscale but an HTTP API call fails, check which authentication path the endpoint uses. If a diagnostics command fails after applying a deny-all exec policy, that is expected behavior, not evidence that the policy is broken. If a shared Gateway exposes another operator's sessions, the current trust model treats that as a boundary choice; use separate Gateways when it is unacceptable.

If the Gateway may be overexposed, close the route first: stop the process or supervisor, set gateway.bind back to loopback, and stop direct forwarding, Tailscale Funnel, or proxy routes. Freeze risky DMs and remove wildcard entries. Then rotate Gateway, remote-client, provider, and channel credentials, review logs, transcripts, tool calls, and configuration changes, and rerun the deep audit. The incident-response guidance gives this order because a secret rotation is less useful while the attacker can still reach the service.

Record what remains true after hardening

A threat model is honest when it preserves residual risk:

• A valid shared Gateway credential may mean operator-level authority. Do not hand it to a service or person that should only submit messages.
• Prompt injection remains possible through content. Model choice is a mitigation, not a boundary.
• Session scope, pairing, and agent labels improve routing and admission, but they do not create hostile multi-tenant isolation.
• Browser profiles, paired nodes, native plugins, and external credentials enlarge the trust cell. Sandbox settings for agent tools do not turn an in-process plugin into an untrusted extension.
• Audit output finds configuration and runtime conditions covered by its checks. It does not certify the business logic of a proxy, the behavior of a model, or the intent of a third-party plugin.

The official ATLAS page labels itself a living version 1.0 draft. That is a reason to review it alongside the installed release and your own data flows, not to treat the page as a complete security certificate.

The decision rule

Expose an OpenClaw Gateway beyond loopback only when you can answer six questions without hand-waving: who can reach it, how identity is proved, which agent receives the request, which tools and nodes are available, what data and credentials are in scope, and how you will close and rotate the deployment. For personal remote administration, loopback plus SSH or Tailscale Serve is usually the cleanest answer. For a trusted team, a narrowly configured private route or identity-aware proxy can be reasonable. For mutually untrusted users, separate Gateways are the answer.

If one of those answers is still uncertain, keep the listener on loopback and write the missing decision before widening the surface.

Sources

All sources were accessed on 2026-09-13. Official documentation pages do not expose a publication date, so their source records use an empty publication date. Advisory publication dates are recorded below.

1. Gateway exposure runbook
2. Network exposure
3. Trusted proxy auth
4. Security trust model and repository security policy
5. Threat model (MITRE ATLAS)
6. Access control and allowlists, prompt injection, and tool and agent permissions
7. Secrets, storage, and logs and rate limiting
8. GHSA-943q-mwmv-hhvh and GHSA-cwj3-vqpp-pmxr
9. Operator incident response