Security Hardening (Part 1): Access Control and Identity
One-sentence goal: This lesson is the first lesson in OpenClaw security hardening, helping you tighten your access surface — recognize the Gateway trust boundary, control who can connect, and bind every approval to a specific person.
Security advisory GHSA-pw3x-g8v8-fvj2: the baseline version 2026.10.9 of this lesson is affected, please upgrade first
2026-11-19, OpenClaw published a high-severity advisory (CVSS 8.8): "delegation could skip approval for restricted agents". Even when the tool policy already forbids executing commands and writing files, the openclaw tool could still write persistent configuration without approval, allowing a restricted agent to open up host command execution.
- Affected versions: ≥ 2026.9.2 and < 2026.10.33, as well as 2026.11.1 ~ 2026.11.3. This lesson is written against 2026.10.9, which is within the affected range.
- Fixed versions: upgrade the stable channel to 2026.11.4 or newer; upgrade the extended-stable channel to 2026.10.33.
- Temporary mitigation before upgrading: set
tools.exec.modetoask, and reject untrusted delegation changes.
First use openclaw --version to check your version. For how to choose a channel and how to upgrade or roll back, see Upgrading and Version Channels. Original advisory: https://github.com/openclaw/openclaw/security/advisories/GHSA-pw3x-g8v8-fvj2
Preparation
- Have OpenClaw installed (v2026.8.1 and above, i.e. OpenClaw 2.0; the repository version at the time of writing is 2026.10.9), Node 24.16.0+ or 26.1.0+.
- The Gateway is already running on your own machine, with at least one channel connected (one of the 20+ channels such as Telegram, Slack, Discord, etc.).
- It is recommended to first go through Advanced Handbook: Skills and Security Hardening.
First, establish an understanding: OpenClaw is a self-hosted gateway with no hosted service; state, memory, and credentials all stay on your own hardware; one Gateway process is the entire trust boundary, and models and agent harnesses (Claude, Codex, local models) are all just replaceable plugins. Security hardening means shrinking this boundary's external exposure surface.
Follow Along
Step 1: Recognize the trust boundary, and use dmPolicy and an allowlist to control channel entry points
First, on the machine running the Gateway, map out the chain: "user → channel → Gateway → model". Every channel you connect (Telegram, Slack, Discord...) adds another entry point that can reach the trust boundary. The first gate for controlling the DM entry point is dmPolicy, which every channel that supports DMs has:
dmPolicy Value | Behavior |
|---|---|
pairing (default) | Unknown senders receive a pairing code, and messages are ignored until approval; pairing codes expire after 1 hour, and each channel holds at most 3 pending pairing requests |
allowlist | Unknown senders are rejected outright, with no pairing handshake |
open | Anyone can DM; requires the channel allowlist to include "*" to take effect (explicitly enabled) |
disabled | Ignore all inbound DMs |
The default pairing is already solid: strangers cannot get a word in before you approve. When someone DMs your assistant, use these two commands to manage pairing:
openclaw pairing list <channel> # <channel> 换成渠道名,如 telegram
openclaw pairing approve <channel> <code> # 批准后,对方才能与助手对话The second gate is the allowlist, which has two layers:
- DM layer:
allowFrom(e.g.channels.discord.allowFrom,channels.slack.allowFrom) determines who can DM the assistant; people approved through pairing are stored in the shared database (by default~/.openclaw/state/openclaw.sqlite) and take effect merged with the configured allowlist. - Group layer:
channels.whatsapp.groups,channels.telegram.groups, etc. determine which groups the assistant accepts, andrequireMentioncan be set per group (it must be @-mentioned to respond); settinggroupsalso makes it act as a group allowlist — write"*"to keep all groups.groupPolicy: "allowlist"plusgroupAllowFromcan further restrict who in a group can trigger it (for channels such as WhatsApp/Telegram/Signal/iMessage/Teams).
💡 Multiple people sharing the assistant? Isolate DM sessions
By default all DMs converge into the same main session. If multiple people can DM the assistant (multi-person allowlist or open), set session.dmScope: "per-channel-peer" in ~/.openclaw/openclaw.json so that each "channel + sender" gets an isolated session; openclaw security audit will give the same recommendation when it detects multi-user DMs.
Expected result: You get an inventory of entry points and can clearly answer "who can talk to my assistant today, and through which channels"; unknown senders are by default stuck at the pairing step and ignored until approved.
Step 2: Tighten the network exposure surface of OpenClaw security
With the channel entry points under control, look next at where the Gateway itself listens: it runs WebSocket and HTTP on a single port, default port 18789 (change the port with gateway.port, --port, or the environment variable OPENCLAW_GATEWAY_PORT). The listen address is determined by gateway.bind:
"loopback": Default for regular hosts; only local clients can connect."auto": Default when this setting is omitted in a container; resolves to0.0.0.0, making port forwarding and container network access convenient."lan"/"tailnet"/"custom": Makes the Gateway reachable by more clients; you must also configure authentication and a real firewall.
The rule is strict: starting on a non-loopback address requires authentication to be configured, otherwise the Gateway refuses to start. For remote access, prefer Tailscale Serve (the Gateway stays on loopback, with Tailscale controlling access) over binding to the LAN; never expose an unauthenticated Gateway on 0.0.0.0.
Authentication is mandatory by default: without a valid authentication path, the Gateway rejects WebSocket connections; onboarding generates a token by default, and local clients must also authenticate. There are three authentication modes, configured in gateway.auth:
token: Shared bearer token, the recommended choice for most deployments.password: Recommended to be set via the environment variableOPENCLAW_GATEWAY_PASSWORD.trusted-proxy: Trusts a reverse proxy with identity authentication.
// ~/.openclaw/openclaw.json
{
gateway: {
bind: "loopback",
auth: { mode: "token", token: "replace-with-long-random-token" },
},
}This gateway token is generated with openclaw doctor --generate-gateway-token, or you can make one yourself with openssl rand -hex 32. Note: startup rejects empty tokens, the literals undefined/null, and example placeholder strings; openclaw security audit warns about tokens shorter than 24 characters.
Expected result: The Gateway only listens on the network locations you allow, and connections require authentication; scanning your machine from the public internet finds no Gateway on port 18789.
Step 3: Bind approvals to exact identities
Have the assistant execute a sensitive command that requires approval, and observe the information bound in the approval prompt. The security model of OpenClaw 2.0 binds approvals to the exact request, command, session, and person: manually confirm sensitive commands from unknown sessions one by one, and do not approve them wholesale.
Expected result: For every approval you can see which session, which person, and which command it corresponds to; there is no "one person approves, everyone gets through".
Verification
- Send a DM to the assistant from an unknown account: under the default
dmPolicy: "pairing", the other party should receive a pairing code and be ignored until you approve; if the stranger gets full capabilities directly, go back to steps 1 and 2 to tighten things up. - Run
openclaw pairing list <channel>; you should see the pending pairing request. Approve it withopenclaw pairing approve <channel> <code>, after which the other party can talk to the assistant. - Scan your public IP from an external network (e.g.
nmap -sT -p 1-65535 <公网IP> --open); the open ports should only be services you intentionally exposed, with no Gateway visible on port 18789. - Trigger a command that requires approval, and verify that the approval info shows the exact request, command, session, and person.
- Verify the default outbound behavior: OpenClaw only performs a daily version check by default, and anonymous statistics require you to opt in; to disable the version check, set
update.checkOnStart: false.
Common Pitfalls
- Treating the Gateway as an ordinary chatbot and exposing it to the public internet. The Gateway is a trust boundary; exposing its port means exposing your credentials and memories along with it.
- Setting
dmPolicytoopenfor convenience.openlets anyone DM the assistant, and it only takes effect after you explicitly set the channel allowlist to"*"— the official docs position it as a deliberate, considered choice, not the default posture. - Assuming your data lives in the cloud. State, memories, and credentials all live on your own hardware; if the machine isn't secure, the assistant isn't either.
- Connecting more and more channels without updating the entry inventory. Every time you connect a new channel, you should go back to step 1 and update the inventory.
- Still running a version earlier than 2.0. The security model where "approval is bound to the exact request/command/session/person" was introduced in v2026.8.1; upgrade older versions first before talking about hardening.
Next Lesson
Access control and identity are the first gate of OpenClaw security: strangers can't get past pairing, the Gateway isn't left naked on the public internet, and every approval corresponds to a specific person. The next lesson Security Hardening (Part 2): Tool Permissions and Sandboxing addresses "what you can do once inside": restricting tool permissions and isolating execution environments with a sandbox.
Related reading: Security Hardening (Part 3): Prompt Injection Defense and Security Auditing, WeCom Integration: Adding an AI Assistant to Work Group Chats.