🔐 Security & DM Policies

1 The threat model

OpenClaw has access to things a regular chatbot doesn't:

• Your filesystem — it can read, write, and delete files
• Shell commands — it can execute arbitrary terminal commands
• Messaging channels — it can send messages to real people on your behalf
• API keys & credentials — stored in ~/.openclaw/
• Browser control — if enabled, it can navigate, click, and fill forms

The security framework follows three priorities, in this exact order:

1. Identity first — decide who can talk to the agent (DM policies, allowlists, pairing)
2. Scope next — decide what the agent can do (tools, sandboxing, permissions)
3. Model last — assume the model can be manipulated; design so manipulation has limited blast radius

2 DM policies

The DM policy is your first line of defense. It controls who can send direct messages to your agent on each channel.

Configure per channel

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "...",
      "dmPolicy": "pairing",
      "allowFrom": ["your_telegram_id"]
    },
    "discord": {
      "enabled": true,
      "token": "...",
      "dmPolicy": "allowlist",
      "allowFrom": ["123456789012345678"]
    }
  }
}

3 Pairing flow

Pairing is like Bluetooth pairing — both sides must agree before communication starts. Here's how it works:

1. Someone sends your agent a DM
2. The agent responds with a 6-digit pairing code (expires in 1 hour)
3. The sender tells you the code (or you see it in logs)
4. You approve it from your terminal

Approve a pairing request

# Approve a specific code
openclaw pairing approve telegram 482910

# List pending pairing requests
openclaw pairing list

# Revoke a previously approved user
openclaw pairing revoke telegram <user_id>

Once approved, that user is added to a local pairing store and can message freely in future sessions.

Where are approved IDs stored?

Pairing approvals are stored locally in the OpenClaw state directory. They persist across restarts. You can audit and revoke them at any time with the pairing CLI commands.

4 Group chat security

Groups introduce a unique risk: multiple people can send messages, and any message can contain a prompt injection attempt. The agent processes everything it sees in the group.

Group policies

{
  "groupPolicy": "allowlist",
  "groups": {
    "allowFrom": ["group_id_1", "group_id_2"]
  }
}

Mention gating

In groups, require the bot to be explicitly @mentioned before it responds:

{
  "channels": {
    "discord": {
      "requireMention": true
    }
  }
}

Without mention gating, your bot is "always-on" in the group — reading and potentially acting on every message. With mention gating, it only activates when directly addressed.

Session isolation

By default, OpenClaw uses dmScope to isolate sessions per user. Each person gets their own conversation context — they can't see each other's messages, memories, or tool outputs. This applies to both DMs and group interactions.

5 Sandboxing

Sandboxing is your safety net — if the agent goes off the rails (tricked by a prompt injection, buggy skill, or hallucinated command), the damage is contained to a disposable environment.

Option A: Tool sandboxing (recommended)

Gateway runs on your host, but tools execute inside Docker containers:

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",
        "scope": "session",
        "workspaceAccess": "none"
      }
    }
  }
}

• "non-main" — sandboxes all sessions except your main DM (where you're the trusted operator)
• "session" — each session gets its own isolated sandbox
• "workspaceAccess": "none" — sandboxed sessions can't read your workspace files

Option B: Full gateway in Docker

Run the entire gateway inside a container for maximum isolation:

docker run -d --name openclaw \
  -v ~/.openclaw:/root/.openclaw \
  -p 18789:18789 \
  ghcr.io/openclaw/openclaw:latest

What sandboxing protects against

6 Exec & tool policies

Control what your agent can execute and whether it needs your approval first.

Consent mode (ask before executing)

{
  "exec": {
    "ask": "on"
  }
}

With ask: "on", the agent sends you a confirmation prompt before running any shell command or writing any file. You approve or reject. This is the safest mode for getting started.

Tool profiles

Control which categories of tools are available:

{
  "tools": {
    "profile": "minimal"
  }
}

Per-agent overrides

Different agents can have different tool access levels. Your personal assistant might get full access while a group-facing bot gets minimal:

{
  "agents": {
    "personal": { "tools": { "profile": "standard" } },
    "group-bot": { "tools": { "profile": "minimal" } }
  }
}

7 File permissions & credential hygiene

Lock down the OpenClaw directory

# Restrict the entire OpenClaw directory
chmod 700 ~/.openclaw

# Lock the config file (contains API keys)
chmod 600 ~/.openclaw/openclaw.json

# Lock credentials directory
chmod 700 ~/.openclaw/credentials

Where your secrets live

Rules

• Never commit ~/.openclaw/ to version control. Add it to your global .gitignore.
• Never put API keys in workspace files. SOUL.md, AGENTS.md, etc. are loaded into AI context — keys there could be leaked through prompt injection.
• Use environment variables when possible instead of hardcoding keys in config.
• Rotate keys periodically — especially if you suspect exposure.

8 Network exposure & Control UI

The Control UI (WebChat at :18789) is an admin interface with full access to your agent and configuration. It is not designed for public exposure.

Keep it local

{
  "gateway": {
    "bind": "loopback",
    "controlUi": {
      "allowInsecureAuth": false
    }
  }
}

• "bind": "loopback" — only accessible from localhost (127.0.0.1)
• "allowInsecureAuth": false — never disable auth on the Control UI

Remote access (if you need it)

If you run OpenClaw on a VPS and need remote access:

• SSH tunnel (simplest): ssh -L 18789:localhost:18789 user@your-vps — then open localhost:18789 in your browser
• Tailscale (recommended for persistent access): bind to your Tailscale IP (100.x.x.x) instead of 0.0.0.0
• Never use Cloudflare Tunnel, ngrok, or port forwarding to expose :18789 to the public internet

9 Skill vetting

Skills are code that your agent can execute. A malicious skill has the same access as your agent — filesystem, shell, network. Always vet before installing.

Red flags in SKILL.md files

• curl | bash or wget | sh — remote code execution
• Base64-encoded strings — obfuscated payloads
• Zero-width Unicode characters — hidden instructions invisible to the eye
• References to ~/.ssh, ~/.openclaw/credentials, or ~/.aws
• Auto-update mechanisms that pull code from external URLs
• Requests for permissions beyond what the skill description claims to need

Safe practices

• Read the SKILL.md source before installing — always
• Prefer bundled skills (maintained by @steipete) — they ship with OpenClaw and are vetted
• Check our Skill Explorer for Pixeyo-curated skills that have been manually reviewed
• Run community skills in sandboxed sessions
• Use openclaw security audit which checks for known risky skill patterns

10 Security audit & doctor

OpenClaw has built-in tools to check your security posture.

Quick check

# Basic health and security check
openclaw doctor

# Deep audit with auto-fix
openclaw doctor --deep --yes

# Dedicated security scan
openclaw security audit --deep

What the audit checks

• DM policies — flags open policies or missing allowlists
• Network exposure — warns if gateway is bound to 0.0.0.0
• File permissions — checks ~/.openclaw/ directory permissions
• Sandbox configuration — flags sandbox settings that are configured but not active
• Plugin/skill allowlists — checks for extensions running without explicit approval
• Credential exposure — warns about tokens in workspace files
• Gateway auth — checks for weak or missing authentication; v2026.3.7+: when both gateway.auth.token and gateway.auth.password are set, you must set gateway.auth.mode to token or password

Third-party auditing

# ClawShield (independent security scanner)
clawshield audit
clawshield apply safe --write  # Auto-fix common issues

11 Incident response

If you suspect your agent has been compromised, a skill acted unexpectedly, or a token was exposed:

Immediate steps (in this order)

1. Stop the blast radius — disable elevated tools or stop the gateway entirely:

openclaw gateway stop

2. Rotate all secrets — change your gateway.auth token, hooks.token, and all AI provider API keys

3. Review logs — check for unexpected tool calls, file access, or outbound requests:

openclaw logs --json --limit 500 | grep -E "exec|write|fetch"

4. Audit the environment:

openclaw security audit --deep

5. Restart with tighter config — reduce tool profile, enable consent mode, re-evaluate allowlists

12 The hardening checklist

Print this. Run through it after installation and after every major config change.

Identity (who can talk)

• dmPolicy is "pairing" or "allowlist" on every channel
• No channel has dmPolicy: "open" with tool access enabled
• groupPolicy is "allowlist" — not open
• requireMention: true on group channels
• Pairing store reviewed — no unknown/stale approved users

Scope (what it can do)

• exec.ask is "on" (consent mode) — at least during setup
• Sandbox mode is "non-main" at minimum
• Group-facing agents use tools.profile: "minimal"
• /reasoning and /verbose disabled in public rooms
• Only necessary skills installed — no "install everything" approach

Network (what's exposed)

• gateway.bind is "loopback" — not 0.0.0.0
• controlUi.allowInsecureAuth is false
• Port 18789 is NOT exposed to the public internet
• Remote access via SSH tunnel or Tailscale only

Credentials (what's protected)

• chmod 700 ~/.openclaw and chmod 600 openclaw.json
• No API keys in workspace files (SOUL.md, AGENTS.md, etc.)
• ~/.openclaw/ excluded from git repos and public backups
• Gateway auth token is strong (not default or short)
• logging.redactSensitive is "tools" — keep it on

Ongoing

• openclaw doctor --deep --yes run weekly
• Skills reviewed before installation (check source code)
• OpenClaw updated to latest version regularly
• Node.js is 22.12.0+ (includes critical security CVE fixes)