When one OpenClaw Gateway serves a small team, which remote-access and auth pattern do you standardise on, and what would make you split it?
answer
- one trust boundary per Gateway
- narrowest pattern that works
- a shared token is everyone's admin key
- identity from a trusted proxy
- split Gateways, not sessions
basics
~20 sStart with the narrowest pattern: the Gateway on loopback behind Tailscale Serve or SSH, with one token held by people who trust each other. Move to trusted-proxy auth when you need per-person identity, and split Gateways when users stop trusting each other.
solid answer
~40 sOpenClaw supports one trust boundary per Gateway, so the first question is whether the team is one. If it is, loopback plus Tailscale Serve gives HTTPS and tailnet identity for the Control UI, with the shared token for HTTP APIs and CLIs, but everyone holding that token is a full operator. When you need per-person identity, allowlists or scopes, use an identity-aware proxy with `gateway.auth.mode: "trusted-proxy"`: `gateway.trustedProxies` lists only the proxy's IPs, the proxy overwrites forwarded headers, `allowUsers` names who gets in, and a firewall leaves the proxy as the only path. The audit flags that mode critical on purpose, since the proxy becomes the auth boundary. When users or data stop sharing trust, split: separate Gateways and credentials, ideally separate OS users or hosts.
code
json · 14 lines{
"gateway": {
"bind": "lan",
"trustedProxies": ["10.0.0.5"],
"auth": {
"mode": "trusted-proxy",
"trustedProxy": {
"userHeader": "x-forwarded-user",
"allowUsers": ["[email protected]", "[email protected]"],
"allowLoopback": false
}
}
}
}go deeper
Know that one OpenClaw Gateway is meant for one person or a team that trusts each other, and that the shared token makes its holder an operator.
Explain the exposure patterns from SSH tunnel to trusted proxy and what each one requires before it is safe.
Configure trusted-proxy auth correctly: narrow trustedProxies, header overwrite, allowUsers, a firewall on the direct port, and loopback only by explicit consent.
Weigh a shared secret's simplicity against identity-bound access, and decide where to split Gateways by trust and data, not by convenience.
## The constraint that frames the decision OpenClaw's security model supports **one trust boundary per Gateway**: a single operator, or a team whose members trust each other. Inside one Gateway, an authenticated connection is an operator in a trusted control-plane role; named operator roles can bound what each teammate's connection does, but the docs call them collaboration guardrails, not tenant isolation. Anyone who can edit `~/.openclaw` is an operator too. So the decision is not only "how do people reach it" but "are these people one boundary at all". ## The menu OpenClaw's exposure runbook ranks the patterns from narrowest to widest: | Pattern | Fits | Required controls | |---|---|---| | Loopback + SSH tunnel | Personal use, admin access | `gateway.bind: "loopback"`, tunnel `127.0.0.1:18789` | | Loopback + Tailscale Serve | Tailnet access to Control UI and WebSocket | Gateway stays on loopback; identity headers cover only the Control UI WebSocket | | Tailnet or LAN bind | Private network of known devices | Gateway auth, firewall allowlist, no public port-forward | | Trusted reverse proxy | Team SSO or OIDC in front | `trusted-proxy` auth, strict `trustedProxies`, header overwrite, explicit allowed users | | Public internet | Rare, high-risk | Identity-aware proxy, TLS, rate limits, strict allowlists, sandboxed non-main sessions | The runbook's rule is to **prefer the narrowest pattern that satisfies the workflow** and widen one control at a time. ## A defensible default for a small trusted team - **Loopback plus Tailscale Serve.** HTTPS and MagicDNS without a public port; tailnet identity can authenticate the Control UI WebSocket. - **One generated token for CLIs and HTTP callers**, held only by the team. Shared-secret auth over HTTP is full operator access and `x-openclaw-scopes` does not narrow it, so the token is effectively everyone's admin key. - **`openclaw security audit --deep` on every change**, with accepted findings recorded as suppressions with reasons. Its weakness is attribution: with one shared secret you cannot tell teammates apart or remove one person without rotating for everyone. ## When identity matters: trusted-proxy auth An identity-aware reverse proxy authenticates each person and passes identity in a header. The Gateway side: 1. `gateway.auth.mode: "trusted-proxy"` with `gateway.auth.trustedProxy.userHeader` naming the identity header; startup refuses this mode with an empty `gateway.trustedProxies`. 2. `gateway.trustedProxies` lists **only the proxy's source IPs**. The proxy must overwrite `X-Forwarded-For` rather than append, and `gateway.allowRealIpFallback` stays false unless the proxy cannot send `X-Forwarded-For`. 3. `gateway.auth.trustedProxy.allowUsers` restricts which authenticated users get in; without it any user the proxy authenticates is accepted. 4. A firewall blocks direct access to the Gateway port, so the proxy is the only path. 5. A same-host proxy on loopback is refused unless `gateway.auth.trustedProxy.allowLoopback` is set, because local processes could forge the headers. The audit reports `gateway.trusted_proxy_auth` as critical by design: **the proxy is now the authentication boundary**, and the Gateway is only as safe as its configuration. The payoff is per-request scopes and identity-bound access, which shared secrets cannot give. ## When to split instead Split into separate Gateways with separate credentials, ideally separate OS users or hosts, when: - people sharing the assistant do not fully trust each other; - a team agent would sit on the same runtime as someone's personal accounts or credentials; - one audience needs public or semi-public ingress and another holds sensitive data. DM session scoping and per-agent sandboxes reduce leakage inside one boundary; they do not create a second one. The tradeoff is cost and operations, more hosts and tokens, against a blast radius that stops at the boundary you drew. ## A decision checklist Before widening access, the exposure runbook asks you to be able to explain four things: who can reach the Gateway, how they authenticate, which agents they can trigger, and which tools those agents can use. In practice: 1. **List the people** and decide whether they are one trust boundary. If not, plan separate Gateways now; it is far cheaper than separating later. 2. **Pick the narrowest pattern** from the table that covers the real workflow, not the hypothetical one. 3. **Decide shared secret or identity.** A shared token is fine while everyone is equally trusted and nobody needs to be removed alone; once per-person removal, audit trails or scopes matter, budget for trusted-proxy auth. 4. **Write down the evidence** each change must ship with: a clean `openclaw security audit --deep`, an external port scan, and a tested rollback to loopback with rotated tokens.
- Why does putting `127.0.0.1` in OpenClaw's `gateway.trustedProxies` weaken security?It tells the Gateway to accept forwarded client-attribution headers from any same-host process, and every local process can forge them. The docs say adding 127.0.0.1 explicitly trusts same-host processes to supply proxy attribution, so keep token or password auth unless everything on the host belongs to one trust boundary.
- With token auth behind an unconfigured same-host reverse proxy, what does an OpenClaw Gateway do?It rejects proxied requests on Gateway-authenticated routes because it cannot attribute the forwarded client: HTTP gets `403` with `proxy_attribution_required` and WebSocket auth fails with guidance to set `gateway.trustedProxies`. That stops proxied traffic from passing as a local, trusted connection.
- One Gateway can safely host users who do not trust each other.
- Per-person x-openclaw-scopes headers give each teammate least privilege.
- List every teammate's laptop IP in gateway.trustedProxies.
- trusted-proxy mode is safe once the proxy terminates TLS.
- Separate DM sessions are as good as separate Gateways.