skip to content

Securing the Agent

Keeping an agent with shell access and your accounts safe: who can reach the Gateway, what the security audit checks, and how sandboxes and tool policy limit damage. Asked in every serious interview.

part ofAI coding toolsread it →
on this pageshow

explore

questions

12

Why does an OpenClaw Gateway bind to loopback by default, and what changes when you widen `gateway.bind`?

level: juniorimportance: must knowfreq 20%

answer

  1. who can open the socket
  2. 127.0.0.1 and port 18789
  3. lan, tailnet, custom, auto
  4. startup refuses a wide bind without a secret
  5. containers flip the default

basics

~20 s

OpenClaw's gateway.bind defaults to loopback (127.0.0.1, port 18789), so only same-host processes can reach the Gateway's WebSocket and Control UI. Wider modes such as lan or tailnet admit other machines and require token or password auth.

solid answer

~40 s

The Gateway is the one process that holds your channels, sessions and credentials, so `gateway.bind` decides who can even try to talk to it. The default `"loopback"` listens on `127.0.0.1:18789`, which only same-host clients can reach. `"lan"` listens on all interfaces, `"tailnet"` on the Tailnet IPv4 plus `127.0.0.1`, `"custom"` on an address in `customBindHost`, and `"auto"` prefers loopback but uses `0.0.0.0` in a detected container. Widening the bind is guarded: the Gateway refuses to start on a non-loopback address without a token or password (or trusted-proxy auth). Loopback is not a substitute for auth either; onboarding still generates a token, because any local process or a same-host reverse proxy can reach a loopback port.

code

json · 7 lines
json
{
  "gateway": {
    "bind": "loopback",
    "port": 18789,
    "auth": { "mode": "token", "token": "replace-with-a-long-random-token" }
  }
}

go deeper

for a junior

Recall the default: gateway.bind is loopback on 127.0.0.1 port 18789, so only same-host clients connect, and remote use goes through an SSH tunnel or Tailscale.

for a middle

Explain each bind mode and the startup guard that refuses a non-loopback bind without a token or password, and why loopback still carries a token.

for a senior

Show you know where exposure really comes from: container images that default to lan, a same-host reverse proxy, and the audit findings that catch each.

for a principal

Argue for loopback plus a tunnel or Serve as the team standard, and say what evidence a wider bind must come with: auth, origin allowlist, firewall rule, audit run.

## What the bind decides The **Gateway** is the single long-running process at the centre of an OpenClaw install. It keeps the chat-channel connections, the sessions, the model credentials and the tool runtime, and every client (the CLI, the browser Control UI, the phone apps) talks to it over one port that carries both WebSocket and HTTP. That port is `18789` by default (`gateway.port`, `--port` or `OPENCLAW_GATEWAY_PORT`). `gateway.bind` controls **which network interface that port listens on**, and therefore which machines can even attempt a connection. It is the outermost layer of the security model: before tokens, pairing, DM policies or sandboxes matter, someone has to reach the socket. ## The modes | `gateway.bind` | Listens on | Who can connect | |---|---|---| | `"loopback"` (default) | `127.0.0.1` | Processes on the same host | | `"lan"` | `0.0.0.0` (all IPv4 interfaces) | Anything that can route to the host | | `"tailnet"` | The Tailnet IPv4, plus `127.0.0.1` | Tailnet devices and same-host clients; falls back to loopback if no Tailnet address exists at startup | | `"custom"` | The IPv4 in `gateway.customBindHost` | Whatever can reach that address | | `"auto"` | Loopback if available, `0.0.0.0` in a detected container | Depends on where it runs | The bind takes these mode names, not raw host strings: you write `"lan"`, not `"0.0.0.0"`. ## Why loopback is the default OpenClaw's trust model is **one trust boundary per Gateway**: a single operator or a team whose members trust each other. A connection authenticated to the Gateway is treated as an operator, and shared-secret operator access over HTTP is effectively full access. Listening only on `127.0.0.1` means the attack surface on a fresh install is the local machine, and anything remote has to arrive through a path you chose deliberately: - an **SSH tunnel** that forwards `127.0.0.1:18789` from your laptop to the host; - **Tailscale Serve**, which keeps the Gateway on loopback and proxies tailnet traffic to it over HTTPS; - a reverse proxy you configure, with `gateway.trustedProxies` set. ## What happens when you widen it OpenClaw guards the wider modes at startup rather than leaving them to the audit: 1. If the resolved bind address is not loopback and there is no token or password (and the auth mode is not `"trusted-proxy"`), the Gateway **refuses to bind** and exits with an error naming `gateway.auth.token`/`password` and the matching environment variables. 2. A non-loopback Control UI also needs a browser-origin allowlist (`gateway.controlUi.allowedOrigins`, or `gateway.publicOrigin` when the list is omitted), or startup fails. 3. `openclaw security audit` reports `gateway.bind_no_auth` as **critical** for a wide bind without a shared secret, which matters for configs that have not been restarted yet. So a wide bind is never unauthenticated by accident, but it does make the token or password the main barrier between the internet and an operator session, plus a firewall if you add one. ## Loopback still needs auth A common misreading is that loopback means auth can be skipped. It cannot, for two reasons: - **Every local process can reach a loopback port**, including other users' processes and anything a compromised tool started. - **A same-host reverse proxy turns loopback into remote access.** The audit's `gateway.loopback_no_auth` finding (critical) exists for exactly this: loopback bind, Control UI enabled, no auth secret. That is why onboarding generates a Gateway token even for a loopback install, and why, in token mode with no credential at all, a loopback Gateway mints a runtime-only token instead of running open. ## Containers are the deliberate exception Inside a container, `127.0.0.1` is the container's own network namespace, so a loopback-bound Gateway would be unreachable from the host. The Docker setup therefore defaults `OPENCLAW_GATEWAY_BIND=lan`, and the security overview says plainly that container images default to an exposed bind that must be paired with auth and a firewall. On a server, that is where most accidental exposure comes from. ## Exposure the bind does not cover The bind decides who can reach the port; a few neighbouring settings decide what the Gateway tells the network about itself: - **mDNS discovery.** When the bundled Bonjour plugin is enabled, the Gateway advertises itself on the local network. The default `discovery.mdns.mode` is `"minimal"`; `"full"` adds the CLI path (which reveals the username) and the SSH port, and the audit flags it as `discovery.mdns_full_mode`. `"off"` or `OPENCLAW_DISABLE_BONJOUR=1` stops advertising. - **Browser origins.** A non-loopback Control UI needs an explicit origin allowlist; `allowedOrigins: ["*"]` disables origin checks and is flagged too. ## Checking what you actually bound Do not trust memory or a config diff alone: 1. Run `openclaw security audit` and read every `gateway.*` finding. 2. From another machine, scan the host's public address for open ports; the only ones expected are those you meant to expose, usually SSH. 3. After changing the bind, restart the Gateway and repeat both steps.

  • Why is a loopback-bound OpenClaw Gateway still given a token?
    Any process on the host can open a loopback port, and a same-host reverse proxy can forward outside traffic to it. The audit flags a loopback Control UI with no auth secret as `gateway.loopback_no_auth`, critical. Onboarding generates a token by default, and in token mode with no credential a loopback Gateway creates a runtime-only token rather than running open.
  • What does `gateway.bind: "tailnet"` listen on, and what if Tailscale is not up yet?
    It listens on the host's Tailnet IPv4 and also on `127.0.0.1` for same-host clients, with plain `ws://` and no HTTPS. If no Tailnet address exists when the Gateway starts, it falls back to loopback only; you restart after Tailscale comes up to add the Tailnet listener. It still needs token or password auth like any non-loopback bind.

Binding to loopback is like a house phone with no outside line: anyone in the house can pick it up, nobody outside can dial in, and you still lock the doors because people inside can use it too.

  • The Gateway listens on all interfaces until you lock it down.
  • Loopback-only means you can safely turn Gateway auth off.
  • Setting bind to lan without a token just triggers an audit warning.
  • You set gateway.bind to a raw address like 0.0.0.0.
  • The Docker image keeps the Gateway on loopback like a host install.
open as a page

Does OpenClaw run an agent's tools in a sandbox by default, and what moves into the sandbox once you turn it on?

level: juniorimportance: must knowfreq 14%

basics

~20 s

No. OpenClaw sandboxing is off by default, so tools run on the Gateway host. When you enable it, only tool execution (shell, file tools, the optional browser) moves into a container; the Gateway process itself always stays on the host.

open as a page

How do you reach an OpenClaw Gateway on a remote server from your laptop without opening its port to the internet?

level: middleimportance: must knowfreq 16%

basics

~20 s

Keep the Gateway on loopback and bring the port to you: an SSH tunnel forwarding 127.0.0.1:18789, or OpenClaw-managed Tailscale Serve, which proxies tailnet-only HTTPS to the loopback Gateway. Funnel and wide binds widen exposure and lean harder on auth.

open as a page

In OpenClaw, how do tools.allow and tools.deny decide which tools an agent can call, and what do they not control?

level: middleimportance: must knowfreq 10%

basics

~20 s

OpenClaw tool policy filters tools by name: deny always wins, and a non-empty allow blocks everything not listed. It applies with or without the sandbox and is the hard stop, but it does not inspect what an allowed exec command does.

open as a page

In OpenClaw, how do the `gateway.auth` token and password modes work, and how do you set and rotate the secret safely?

level: middleimportance: should knowfreq 9%

basics

~20 s

OpenClaw's Gateway requires auth by default: token mode, the default, or password mode holds one shared secret every client presents. Generate a long random value, update each client's gateway.remote copy when rotating, and verify the old one fails.

open as a page

On an OpenClaw Gateway host, how do exec approvals decide whether a shell command runs, and what does a fresh install do?

level: middleimportance: should knowfreq 8%

basics

~20 s

As of OpenClaw 2026.9.9, host exec defaults to security full and ask off, so commands run without a prompt. With an allowlist and ask on-miss, unmatched commands wait for approval, and if no approver is reachable, askFallback (default deny) blocks them.

open as a page

Your OpenClaw Gateway on a VPS, set up with the Docker flow, turns up in an internet scan on port 18789; why did that happen, and what do you change?

level: seniorimportance: should knowfreq 6%

basics

~20 s

OpenClaw's Docker setup binds the Gateway to lan and publishes 18789 on the host, where Docker forwarding can bypass UFW, leaving the token as the main barrier. Close 18789 at the provider firewall, tunnel in over SSH or Tailscale, and rotate the token.

open as a page

A group-chat message tells an OpenClaw agent to run a shell command and print the owner's SSH keys; how do tool policy, the sandbox and elevated mode each stop it?

level: seniorimportance: should knowfreq 7%

basics

~20 s

Tool policy decides first: if exec is denied, nothing runs. If exec is allowed, the sandbox decides where it runs; a sandboxed group session sees no host home directory. Elevated could send exec to the host, but only for senders in tools.elevated.allowFrom.

open as a page

With OpenClaw's agents.defaults.sandbox.mode set to non-main, which sessions still run tools on the host, and why can that surprise an operator?

level: seniorimportance: should knowfreq 6%

basics

~20 s

Only the agent's main session (agent:<agentId>:main) stays on the host; group and channel sessions have their own keys and are sandboxed. Under the default session.dmScope of main, direct messages share that main session, so they run on the host too.

open as a page

What does `openclaw security audit` check in plain mode versus `--deep`, and what does `--fix` change or deliberately leave alone?

level: seniorimportance: nice to knowfreq 5%

basics

~20 s

Plain openclaw security audit reads config and files without loading plugin runtimes; --deep adds a live Gateway probe, plugin collectors and code scans. --fix applies a narrow set, open group policies to allowlists and tighter file permissions, never bind, auth or tokens.

open as a page

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?

level: principalimportance: nice to knowfreq 4%

basics

~20 s

Start 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.

open as a page

What sandbox and tool-policy baseline would you set for an OpenClaw agent that answers strangers in public groups, and what risk does it still leave?

level: principalimportance: nice to knowfreq 5%

basics

~20 s

Give public traffic its own agent: sandbox mode all, workspaceAccess none, no network, a deny list covering shell, file, automation and delegation tools, and elevated off. One Gateway is still one trust boundary, so messaging and session reach remain the residual risk.

open as a page