Layered Security Model - Introduction to OpenClaw

Introduction

OpenClaw secures every interaction through three distinct security layers: who is acting, where they can act, and what they can do. This defense-in-depth approach ensures that a failure in one layer does not grant unrestricted access. Understanding these layers is essential before configuring any production deployment.

Key Concepts

Defense in depth -- multiple independent security layers so that breaching one does not compromise the system
Identity layer (who) -- authentication and pairing rules that establish which users and agents can communicate
Scope layer (where) -- allowlists and channel restrictions that limit where interactions can occur
Policy layer (what) -- tool profiles and sandboxing that control what actions agents may perform
Fail-closed -- the design principle where missing or invalid configuration denies access by default
Gateway authentication -- the mechanism that verifies every inbound connection before it reaches an agent

Real World Context

Consider a corporate office building. The front door has a badge reader (identity), each floor requires a separate keycard (scope), and inside each office certain filing cabinets are locked (policy). If someone steals a badge, they still cannot reach every floor or open every cabinet. OpenClaw applies the same philosophy: authentication alone is not enough; you also restrict where messages can go and what tools an agent can invoke.

Deep Dive

OpenClaw's security model is organized into three concentric layers. Each layer answers a different question and is configured independently.

Layer 1 -- Who (Identity & Pairing)

The identity layer determines which entities can connect at all. Gateway authentication is the outermost gate. Three modes are available:

yaml
# openclaw.yaml
gateway:
  auth:
    mode: token          # recommended for production
    # mode: password      # simpler but less secure
    # mode: trusted-proxy # only behind a verified reverse proxy

The token mode is recommended because tokens can be rotated without changing shared secrets. Authentication is mandatory by default -- there is no way to disable it without explicitly setting an override, which enforces the fail-closed principle.

Once authenticated, the pairing system controls which users can reach which agents through direct messages:

yaml
dm:
  pairing: default       # only pre-configured pairs may DM
  # pairing: allowlist   # explicit user-agent pairs
  # pairing: open        # any authenticated user can DM any agent
  # pairing: disabled    # DMs are completely off

The default pairing mode requires explicit pair definitions, preventing unauthorized users from engaging agents they should not access.

Layer 2 -- Where (Scope & Allowlists)

Even after authentication and pairing, the scope layer restricts which channels, groups, and contexts an agent can operate in.

For group conversations, you can set per-group defaults and use groupAllowFrom to restrict which users may invoke the agent in a given group:

yaml
groups:
  dev-team:
    allowFrom:
      - alice
      - bob
    mentionGating: true   # agent only responds when @mentioned

Mention-gating is a critical scope control. When enabled, the agent ignores all messages in a group unless explicitly mentioned, which dramatically reduces the attack surface for prompt injection in noisy channels.

Session isolation through dmScope prevents cross-user data leakage:

yaml
dm:
  dmScope: per-channel-peer  # each user gets an isolated session

With per-channel-peer, user A's conversation history and context are completely invisible to user B, even if both are talking to the same agent.

Layer 3 -- What (Tool Policies & Sandboxing)

The innermost layer controls what an agent can actually do once it receives a valid, scoped message. Tool profiles and sandboxing are configured here, but we cover them in detail in the next lesson.

The key idea is that even a fully authenticated user in an allowed channel is still restricted to a predefined set of actions. This means a compromised message cannot escalate to arbitrary code execution if the tool policy forbids it.

How the Layers Compose

Consider this request flow:

Incoming message
  → Gateway auth (token valid?)          [WHO]   → reject if no
  → Pairing check (user paired?)         [WHO]   → reject if no
  → Scope check (channel allowed?)       [WHERE] → reject if no
  → Mention gate (was agent @mentioned?) [WHERE] → ignore if no
  → Tool policy (action permitted?)      [WHAT]  → deny if no
  → Execute

Every step is an independent gate. A request must pass all of them.

Common Pitfalls

Relying on a single layer -- using only gateway auth without pairing or tool restrictions leaves agents wide open to any authenticated user running any tool
Setting pairing to open in production -- this bypasses the identity layer's granularity and allows any authenticated user to DM any agent, which is rarely appropriate outside development
Forgetting mention-gating in shared groups -- without it, every message in a busy channel is processed by the agent, increasing both cost and injection risk

Best Practices

Start with the strictest settings and relax only as needed -- begin with token auth, default pairing, and per-channel-peer scope, then open specific paths
Treat each layer as independently auditable -- review who can connect, where they can act, and what they can do as three separate checklists
Use openclaw security audit regularly -- this built-in tool checks all three layers for misconfigurations

Summary

OpenClaw enforces three security layers: who (identity/pairing), where (scope/allowlists), and what (tool policies/sandboxing)
Gateway authentication is mandatory and fail-closed; token mode is recommended for production
DM pairing modes range from disabled to open, with default (explicit pairs) being the safest starting point
Session isolation via dmScope: per-channel-peer prevents cross-user data leakage
Every inbound message must pass all three layers independently before any action is taken