OpenClaw security: who can talk to it and what it can do

01What you'll learn

• How OpenClaw thinks about security: who → how far → the model last.
• How to run the built-in audit and what it does not do for you.
• How to decide who may write to the assistant: pairing, ID allowlists, mentions.
• What prompt injection means for an assistant with tools and how to limit it with hard rules, not clever prompts.
• Where secrets live on disk, how to protect them and how to rotate them.
• How to keep the Gateway on loopback, with authentication, and reach it remotely and safely.
• What to do if you suspect a breach.

02Before you start

• You have done Lesson 3 (the Gateway runs, Discord is connected, there is a sandbox) or at least have a working OpenClaw with one chat channel 🔒 local.
• You can open a terminal and edit a small text file.
• For remote access: a Tailscale account 🌐 global or SSH access to the machine running the Gateway.
• You make a copy of your settings before changing anything (the OpenClaw settings folder) — every change below is easy to undo only if you have something to go back to.

03Steps

1. The threat model: three questions in order

   The assistant can run commands, read and write files, reach network services and send messages. Most trouble is not a clever hack but "someone wrote to it and it did it". So OpenClaw orders the decisions like this, and this is also the order of the lesson:

   Order	The question	The hard boundary
   1 · Identity	Who can write to it?	Pairing, ID allowlists, "open" only explicitly
   2 · Scope	Where and what can it do?	Server allowlist, mentions, tool policy, sandbox
   3 · The model	What if it is tricked?	You assume it can be manipulated and shrink the damage

   Why is the model last? Because you cannot trust it as a gate. The documentation says it plainly: prompts in the system message are "soft" guidance; hard enforcement comes from tool policy, approvals, the sandbox and channel allowlists.

2. Run the audit — first

   OpenClaw has a built-in check that compares your settings with the safe defaults. Run it after every change and before you open anything to the network:

   bashcopy

   openclaw security audit
   openclaw security audit --deep
   openclaw security audit --json

   The plain audit looks at settings and file permissions. --deep adds an attempt to reach the running Gateway. It looks for: can a stranger trigger the bot, what is the "blast radius" of the tools, how the Gateway is exposed to the network, folder permissions, plugins and drift from policy. Each finding has an identifier and a severity.

   There is also openclaw security audit --fix, but do not treat it as "fix everything". It only turns open group policies into allowlists and tightens file permissions. It does not rotate tokens, disable tools or change where the Gateway listens.

   🧭

   In what order to fix findings

   (1) Anything "open" together with tools enabled — limit who can write first. (2) Public exposure to the network or missing authentication — immediately. (3) Remote browser control — treat it as operator access. (4) Permissions on the state folders. (5) Plugins — only explicitly allowed ones. (6) Model — for an assistant with tools, choose a serious, modern model.

3. Who can write: pairing and allowlists

   Every chat channel that accepts direct messages has a dmPolicy:

   Policy	What happens
   pairing (default)	A stranger gets a code and is ignored until you approve it. The code is valid for 1 hour; pending requests are at most 3 per channel.
   allowlist	Strangers are blocked, with no handshake.
   open	Anyone can write. Requires an explicit "*" in the list. A last resort.
   disabled	Direct messages are ignored.

   You approve a pairing from the terminal (replace CODE with the one you received):

   bashcopy

   openclaw pairing list discord
   openclaw pairing approve discord CODE

   For servers (groups) there is a second layer: which servers the bot accepts at all, and who in them can trigger it. Start closed, with IDs, not names. Names and labels can change or be forged; OpenClaw has a separate "dangerous" setting for name matching and the audit flags it. Put the settings in a file and apply them through a dry run (replace the placeholders with your own IDs):

   bash · access.patch.json5copy

   cat > access.patch.json5 <<'JSON5'
   {
     channels: {
       discord: {
         dmPolicy: "pairing",
         allowFrom: ["YOUR_USER_ID"],   // who may DM the bot, by ID
         groupPolicy: "allowlist",
         guilds: {
           YOUR_SERVER_ID: {
             requireMention: true,
             users: ["YOUR_USER_ID"],
           },
         },
       },
     },
     // if more than one person can write to the bot:
     session: { dmScope: "per-channel-peer" },
   }
   JSON5
   openclaw config patch --file ./access.patch.json5 --dry-run
   openclaw config patch --file ./access.patch.json5
   openclaw gateway restart

   • allowFrom — the list of IDs of people who may send the bot direct messages. Pairing approvals are added to it automatically.
   • requireMention: true — the bot is triggered only when you mention it; it does not sit "listening" in every channel.
   • session.dmScope: "per-channel-peer" — each sender has a separate context. Otherwise all direct messages flow into one session and one person can influence another's conversation.
   • Replying to a bot message does not bypass the group allowlist.
   ⚠️

   Pairing does not make a person a "separate boundary"

   Approving someone lets them trigger the bot. It does not isolate them from your machine. If you do not trust them fully, do not give them an assistant with dangerous tools.

4. Prompt injection: content is a threat too

   Prompt injection is when someone writes text that makes the model do something dangerous: "forget the rules", "print the files", "open this link and run the commands". The important part is that no public bot is needed: even if only you write to the assistant, everything it reads — a web page, an email, a document, an attachment, a pasted log — can carry hostile instructions. The content is an attack surface, not just the sender.

   In OWASP's classification for large-language-model applications (2026 edition) these are LLM01 Prompt Injection and LLM03 Excessive Agency (giving the agent too many rights) — see "Sources". Practical measures:

   • Treat links, attachments and pasted "instructions" as hostile by default.
   • Limit the blast radius: tools are the most dangerous part (exec, browser, web fetch, files). Give them only to trusted assistants.
   • Deny the tools that control the Gateway itself on every surface that reads other people's content.
   • Use a "reader": an assistant that is read-only or has no tools, which summarises foreign content, and you pass the summary to the main one.
   • Do not put secrets in prompts; keep them on the Gateway, not in a folder the assistant can reach.
   • Model: smaller and older models are easier to manipulate. For an assistant with tools pick a strong modern model; if you still use a small one, take away its browser and web fetch and keep it in a sandbox.

   Here is a "narrow" profile that follows the recommended baseline (apply it with a dry run, as above):

   bash · tools.patch.json5copy

   cat > tools.patch.json5 <<'JSON5'
   {
     tools: {
       profile: "messaging",
       deny: ["gateway", "cron", "sessions_spawn", "sessions_send"],
       exec: { security: "deny", ask: "always" },
       elevated: { enabled: false },
     },
   }
   JSON5
   openclaw config patch --file ./tools.patch.json5 --dry-run
   openclaw config patch --file ./tools.patch.json5
   openclaw gateway restart

   • profile: "messaging" — messages only, no files and no shell, until you open something explicitly.
   • deny — the tools for controlling the Gateway, scheduled jobs and starting new sessions are closed. The documentation recommends this for any surface that handles untrusted content.
   • exec.security: "deny" — no commands at all. If you need harmless diagnostics, relax it only after you choose who, which command and with what approval.
   • elevated.enabled: false — "elevated" mode is the door out of the sandbox; keep it off.
   ⚠️

   This is stricter than the file-access lesson

   The "messaging" profile closes the file tools too. If you want the assistant to use the folders from Lesson 3, open one tool at a time, inside the sandbox, and run the audit again. For extra strictness you can add the groups group:automation, group:runtime and group:fs to deny (from the recommended baseline).
   ✅

   Plugins and skills are trusted code

   Plugins run inside the Gateway process itself. Install only from sources you trust, pin an exact version and review the code before enabling it; prefer an explicit plugins.allow list. That also closes the "supply chain" risk (OWASP LLM04 in the 2026 edition).

5. Secrets: where they are, how you protect them

   Assume that everything in the OpenClaw state folder (by default ~/.openclaw) may hold secrets or private data:

   What	What it may contain
   The main settings file	Tokens (Gateway, remote Gateway), provider settings, allowlists
   The credentials folder	Channel credentials, pairing lists
   The runtime state databases	Model access profiles; sessions and transcripts that hold private messages and tool output
   The sandboxes	Copies of files read or written inside

   The measures, in order of importance:

   • Permissions: the folder for you only (700), files 600. openclaw doctor can warn and offer to tighten them. On Windows the audit uses ACLs instead of chmod.
   • An encrypted disk on the machine; on a shared machine, a separate user for the Gateway.
   • Secret references (SecretRef) instead of plain text: plain text stays readable to the assistant if it sits in a file it can open. When everything has been moved, openclaw secrets audit --check shows whether any plain text is left.
   • Logs and transcripts: secret redaction in them is always on and cannot be turned off; for your own patterns use logging.redactPatterns. When you share diagnostics, give openclaw status --all (secrets hidden), not raw logs.
   • Backups: do not hand them to others or put them in version control — the tokens are in there.
   • Never write a secret in the chat with the bot, in a prompt or in a shared file.
   🔁

   Rotating a secret

   Make a new secret (openclaw doctor --generate-gateway-token for the Gateway token) → restart the Gateway → update the clients that call it → check that the old one no longer works. For a Discord bot token: "Reset Token" in the developer portal and update the secret reference.

6. The Gateway: where it listens and how it authenticates

   The Gateway has one network entrance (a port) for the dashboard and for WebSocket. Where it listens decides how many people can even try:

   • gateway.bind: "loopback" (default) — local clients only. Keep it that way.
   • "lan", "tailnet", "custom" — widen the surface; only with authentication and a real firewall.
   • Never expose the Gateway without authentication on all network interfaces.

   Authentication is required by default: without a valid method the Gateway refuses WebSocket connections. The modes are token (default, recommended), password and trusted-proxy (for a proxy that knows the users). Supply the secret through an environment variable (OPENCLAW_GATEWAY_TOKEN or OPENCLAW_GATEWAY_PASSWORD) or a secret reference, not as plain text in the file:

   bashcopy

   openclaw doctor --generate-gateway-token
   openclaw security audit --deep

   bash · gateway.patch.json5copy

   cat > gateway.patch.json5 <<'JSON5'
   {
     gateway: {
       mode: "local",
       bind: "loopback",
       auth: { mode: "token" },
     },
   }
   JSON5
   openclaw config patch --file ./gateway.patch.json5 --dry-run
   openclaw config patch --file ./gateway.patch.json5
   openclaw gateway restart

   • A dashboard over plain HTTP from another machine is a weakened setup: the token does not replace the browser's identity. Use HTTPS (Tailscale Serve) or open the dashboard on the machine itself.
   • Settings whose name starts with dangerous or dangerously are "break glass" exceptions. Keep them off; the audit lists them one by one.
   • Keep discovery on the local network (mDNS/Bonjour) off or in "minimal" mode; the full mode reveals paths and machine names.

7. Remote access — narrowest way first

   You want to write to the assistant or open the dashboard while away. The documentation ranks the ways from the safest:

   Way	When	Required
   1 · Loopback + SSH tunnel	Personal use, administration	The Gateway stays on loopback; you tunnel its local port
   2 · Loopback + Tailscale Serve	Access only from your own devices	The Gateway stays on loopback; Tailscale guards access
   3 · Network bind	A private network with known devices	Authentication, firewall, no public port
   4 · Trusted reverse proxy	An organisation's single sign-on	Authentication through the proxy, strict addresses, header cleaning
   5 · Public internet	Rare, high risk	Identity-aware proxy, TLS, rate limits — not for this lesson

   Option 1 — SSH tunnel. Nothing is opened to the internet; access is as strong as your SSH key (replace the placeholders; the default port is described in the OpenClaw documentation):

   bash · on your computercopy

   ssh -N -L 18789:127.0.0.1:18789 <USER>@<GATEWAY_MACHINE>

   Then, on your own computer, open the dashboard at the local address the tunnel gives you.

   Option 2 — Tailscale Serve. OpenClaw can set up Serve itself; the Gateway stays on loopback while Tailscale provides HTTPS and access control only inside your private network:

   bash · remote.patch.json5copy

   cat > remote.patch.json5 <<'JSON5'
   {
     gateway: {
       bind: "loopback",
       tailscale: { mode: "serve" },
     },
   }
   JSON5
   openclaw config patch --file ./remote.patch.json5 --dry-run
   openclaw config patch --file ./remote.patch.json5
   openclaw gateway restart

   • You need Tailscale installed and signed in, and HTTPS enabled for your network. Do not leave "unknown" devices in it. On Windows and your phone use the app from tailscale.com/download; on Linux/WSL2 use the official script: curl -fsSL https://tailscale.com/install.sh | sh, then sudo tailscale up.
   • The identity headers from Serve authenticate only the dashboard and WebSocket — not the other HTTP entry points. If foreign code might run on the same machine, turn off gateway.auth.allowTailscale and require a token or password.
   • Do not forward these headers through your own reverse proxy.
   • Funnel makes the service public and requires a shared password. For an assistant with tools — avoid it.
   ⛔

   Do not open a router port and do not forward the Gateway to the internet

   An assistant reachable from outside is a remote control of your machine. Every time you change outside access, first go through the official "before opening to the network" checklist (see "Sources") and then run a full audit.

8. Test the refusal and have an incident plan

   After every change to access: (1) run openclaw security audit --deep; (2) check that allowed access works; (3) check that an unknown sender or browser is refused; (4) check that the logs hide secrets; (5) check that dangerous tools ask for approval or are denied. Write down which warnings you accept on purpose.

   If you suspect the Gateway was exposed or a secret leaked, act in this order:

   • Stop and close: stop the Gateway; set gateway.bind back to "loopback" and turn off Serve/Funnel.
   • Freeze access: risky direct messages and groups → dmPolicy: "disabled" or required mentions; remove every "*".
   • Rotate the secrets: the Gateway's, its clients', the channels' (for example a Discord bot token) and the model providers'.
   • Review: the logs (openclaw logs), the session transcripts and recent changes to gateway.bind, gateway.auth, the DM and group policies, tools.elevated and plugins.
   • Run again openclaw security audit --deep and re-open with the narrowest way.
   bashcopy

   openclaw logs --follow
   openclaw security audit --deep

04Check

Checklist

• openclaw security audit was run after the last change; no unresolved serious findings.
• Direct messages use pairing or a strict list; no "*"; groups use an allowlist and mentions; lists contain IDs, not names.
• If more than one person writes to the bot — session.dmScope is per-channel-peer.
• The tools that control the Gateway are denied where foreign content is read; exec is denied or asks for approval; elevated is off.
• Plugins come from an explicit list and have an exact version.
• The state folder is 700, settings and credentials 600; secrets go through a reference or variable, not into a chat or prompt.
• The Gateway listens on loopback only; authentication is on with a long random secret; there is no public port.
• Remote access is through an SSH tunnel or Tailscale Serve, and a stranger's attempt is refused.
• You have the steps for rotating secrets and for rolling back written down.

Quiz

05What's next

06Sources

1. OpenClaw: security — trust model, DM access, prompt injection, network exposure, secrets on disk, incident response.
2. CLI: security — what security audit checks and how far --fix goes.
3. Hardened baselines · tool permissions · checklist before opening to the network.
4. OpenClaw: Tailscale 🌐 global — Serve, Funnel, authentication.
5. OpenClaw: secrets management — secret references (SecretRef).
6. OWASP Top 10 for LLM Applications, 2026 edition (published 03.08.2026; source text on GitHub) — LLM01 Prompt Injection, LLM03 Excessive Agency, LLM04 Supply Chain. In the 2025 edition the same risks were LLM01, LLM06 and LLM03.