Back
Openclaw-Series

11. OpenClaw Security Configuration Best Practices

Security is a critical consideration for OpenClaw deployment. This article covers DM pairing, sandbox mode, permission control, sensitive data handling, network security, and other security configurations to help you build a secure and reliable AI assistant system.

  • “sandbox mode”
  • “permission control”
  • “sensitive data protection”
  • “AI agent security best practices”

Applies to OpenClaw v2026.2 | This article is suitable for all OpenClaw users, especially those preparing for production deployment or team use.

TL;DR: DM pairing prevents unauthorized access: "dmPolicy": "pairing". Sandbox isolates risky operations: "sandbox": {"mode": "non-main"}. Sensitive data filtering: "security": {"sensitiveData": {"patterns": ["sk-*"]}}. Use Tailscale for remote access instead of exposing to the public internet. Run openclaw doctor --security to check security status.

Security Risk Overview

Main Risk Types

Risk Type Description Potential Consequences
Unauthorized Access Strangers can use your Agent Resource abuse, privacy leakage
Permission Abuse Agent performs operations beyond expectations Data corruption, system damage
Data Leakage Sensitive information improperly handled Privacy breach, compliance issues
Network Attacks External attackers exploit vulnerabilities System intrusion, data theft
Prompt Injection Malicious instructions bypass security limits Unauthorized operations

Security Model

flowchart TB
    subgraph outer["Network Layer"]
        FW[Firewall]
        TLS[HTTPS/TLS]
    end
    
    subgraph middle["Access Control"]
        DM[DM Pairing]
        WL[Whitelist]
        AUTH[Authentication]
    end
    
    subgraph inner["Execution Control"]
        SBX[Sandbox]
        PERM[Permissions]
        AUDIT[Audit]
    end
    
    subgraph core["Agent"]
        AG[Agent Core]
    end
    
    outer --> middle --> inner --> core

DM Pairing Mechanism

What is DM Pairing?

DM (Direct Message) pairing is a protection mechanism that requires new users to complete pairing before they can converse with the Agent.

Pairing Flow

sequenceDiagram
    participant S as Stranger
    participant B as Bot
    participant G as Gateway
    participant O as Owner
    
    S->>B: Send message "Hello"
    B->>G: Message arrives
    G->>G: Check pairing status
    G-->>B: Not paired, generate pairing code
    B-->>S: "Please pair: Code ABC123"
    S->>O: Tell owner the pairing code
    O->>G: openclaw pairing approve telegram ABC123
    G->>G: Add to whitelist
    G-->>S: Pairing successful
    S->>B: Send message "Hello"
    B-->>S: Normal response

Configuring DM Pairing

{
  "channels": {
    "telegram": {
      "botToken": "your_token",
      "dmPolicy": "pairing"
    },
    "whatsapp": {
      "dmPolicy": "pairing"
    },
    "discord": {
      "dmPolicy": "pairing"
    }
  }
}

Pairing Modes

Mode Description Security Level Use Case
pairing Requires pairing code ⭐⭐⭐⭐ Personal use (default)
open Anyone can use ⭐ Public service
whitelist Whitelisted users only ⭐⭐⭐⭐⭐ High security requirements

Pairing Management

# View pending pairing requests
openclaw pairing list

# Output example:
# Channel    Code     User        Created
# telegram   ABC123   @stranger   2026-02-26 10:30:00
# discord    XYZ789   user#1234   2026-02-26 10:35:00

# Approve pairing
openclaw pairing approve telegram ABC123

# Reject pairing
openclaw pairing reject telegram ABC123

# View paired users
openclaw pairing show telegram

Whitelist Configuration

{
  "channels": {
    "telegram": {
      "dmPolicy": "open",
      "allowFrom": [
        123456789,
        987654321
      ]
    },
    "whatsapp": {
      "dmPolicy": "open",
      "allowFrom": [
        "+8613800138000",
        "+8613800138001"
      ]
    }
  }
}

Getting User IDs

# Telegram: Send a message to @userinfobot
# Discord: Use /id command in channel or view user profile
# WhatsApp: Get from contact info

Sandbox Mode

What is Sandbox?

Sandbox is an isolation mechanism that limits the Agent’s scope of operations to prevent accidental or malicious system modifications.

Sandbox Modes

Mode Description Use Case
off No sandbox, full trust Main session, trusted environment
non-main Sandbox enabled for non-main sessions Multi-user, team sharing
always Sandbox always enabled Untrusted environment, public service

Configuring Sandbox

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",
        "allowlist": ["read", "write", "edit", "bash"],
        "denylist": ["browser", "canvas", "nodes"],
        "container": {
          "image": "openclaw/sandbox:latest",
          "timeout": 30000,
          "memory": "512m",
          "cpu": "0.5"
        }
      }
    }
  }
}

Tool Permission Control

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",
        "allowlist": [
          "read",
          "write",
          "edit",
          "bash",
          "web_search",
          "sessions_list",
          "sessions_history",
          "sessions_send"
        ],
        "denylist": [
          "browser",
          "canvas",
          "nodes",
          "cron",
          "discord",
          "gateway"
        ]
      }
    }
  }
}

File System Permissions

{
  "agents": {
    "defaults": {
      "permissions": {
        "filesystem": {
          "read": ["~/workspace", "~/documents"],
          "write": ["~/workspace/output"],
          "deny": ["~/.ssh", "~/.gnupg", "~/.openclaw/credentials"]
        }
      }
    }
  }
}

Network Permissions

{
  "agents": {
    "defaults": {
      "permissions": {
        "network": {
          "outbound": {
            "allow": [
              "api.anthropic.com",
              "api.openai.com",
              "github.com"
            ],
            "deny": ["*"]
          }
        }
      }
    }
  }
}

Elevated Permissions

What are Elevated Permissions?

Elevated permissions are a mechanism for temporarily raising permissions for operations that require higher privileges.

Configuring Elevated Permissions

{
  "agents": {
    "defaults": {
      "elevatedAccess": {
        "enabled": true,
        "allowlist": [123456789, 987654321],
        "requireConfirmation": true,
        "timeout": 300000
      }
    }
  }
}

Using Elevated Permissions

# Request elevated permissions in chat
/elevated on

# Perform operations requiring elevated permissions
# ...

# Disable elevated permissions
/elevated off

Sensitive Data Handling

Types of Sensitive Information

Type Examples Handling
API Keys sk-ant-xxx, sk-xxx Do not log, do not output
Passwords Login passwords, database passwords Do not store, do not transmit
Tokens OAuth token, Session token Encrypted storage
Personal Information ID card, bank card Do not log, anonymize

Configuring Sensitive Information Filtering

{
  "security": {
    "sensitiveData": {
      "patterns": [
        "sk-[a-zA-Z0-9]{20,}",
        "xox[baprs]-[a-zA-Z0-9-]+",
        "[0-9]{15,19}",
        "[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}"
      ],
      "redact": true,
      "log": false
    }
  }
}

Credential Storage

# Credential storage location
~/.openclaw/credentials/

# Encrypted storage
# OpenClaw uses system keychain for encrypted storage of sensitive credentials

Credential Management

# View stored credentials
openclaw credentials list

# Output example:
# Name           Type        Created
# telegram-bot   api_key     2026-02-20
# gmail-oauth    oauth       2026-02-21

# Delete credential
openclaw credentials delete telegram-bot

# Export credentials (encrypted)
openclaw credentials export --output credentials.enc

# Import credentials
openclaw credentials import --input credentials.enc

Network Security

Bind Configuration

{
  "gateway": {
    "bind": "loopback",  // Local access only
    "port": 18789,
    "tls": {
      "enabled": false
    }
  }
}
Bind Option Description Security Level
loopback Local access only ⭐⭐⭐⭐⭐
private Private network access ⭐⭐⭐⭐
all All interfaces access ⭐

Tailscale Configuration

{
  "gateway": {
    "tailscale": {
      "mode": "serve",  // serve or funnel
      "resetOnExit": true
    },
    "auth": {
      "mode": "password",
      "allowTailscale": true
    }
  }
}

Authentication Configuration

{
  "gateway": {
    "auth": {
      "mode": "password",
      "password": "your-secure-password",
      "sessionTimeout": 3600000
    }
  }
}

Audit and Logging

Operation Logging

{
  "logging": {
    "level": "info",
    "audit": {
      "enabled": true,
      "events": [
        "tool.invoke",
        "session.create",
        "session.reset",
        "pairing.approve",
        "pairing.reject",
        "elevated.enable",
        "elevated.disable"
      ],
      "retention": 30
    }
  }
}

Viewing Audit Logs

# View audit logs
openclaw logs --type audit

# Output example:
# [2026-02-26 10:30:00] INFO  tool.invoke session=main tool=bash command="ls -la"
# [2026-02-26 10:30:05] INFO  pairing.approve channel=telegram code=ABC123 user=123456789
# [2026-02-26 10:31:00] INFO  elevated.enable session=telegram:user:123456789

# Filter specific events
openclaw logs --type audit --filter "tool.invoke"

# By time range
openclaw logs --type audit --from 2026-02-01 --to 2026-02-28

Usage Monitoring

# View usage
openclaw usage --today

# Output example:
# Date: 2026-02-26
# Requests: 128
# Tokens In: 125,000
# Tokens Out: 45,000
# Cost: $2.10
# Top Tools: bash(45), read(32), write(18)

# Anomaly detection
openclaw usage --alerts

# Output example:
# ⚠️  High usage detected: 1000+ requests in 1 hour
# ⚠️  Unusual tool pattern: bash commands to sensitive directories

Security Checklist

Basic Security

  • Enable DM pairing or whitelist
  • Configure sandbox mode
  • Set reasonable tool permissions
  • Enable operation audit logging
  • Rotate API keys regularly

Advanced Security

  • Configure filesystem permission restrictions
  • Set network outbound whitelist
  • Enable sensitive information filtering
  • Configure Elevated permission confirmation
  • Regularly review paired users

Enterprise Security

  • Use Docker sandbox isolation
  • Configure Tailscale private network
  • Enable HTTPS/TLS
  • Set usage alerts
  • Regular security audits

Security Diagnostics

# Run security diagnostics
openclaw doctor --security

# Output example:
# ✅ DM Pairing: Enabled
# ✅ Sandbox Mode: non-main
# ⚠️  File Permissions: Some directories not restricted
# ✅ Network Outbound: Restricted to allowlist
# ⚠️  Elevated Access: No confirmation required
# ✅ Audit Logging: Enabled
# ✅ Credentials: Encrypted

# Recommendations:
# - Restrict file access to ~/workspace only
# - Enable elevated access confirmation

Summary

Security configuration is an important part of OpenClaw deployment:

  • DM Pairing: Prevents unauthorized access
  • Sandbox Mode: Limits scope of operations
  • Permission Control: Fine-grained tool and file permissions
  • Sensitive Data: Filter and protect sensitive information
  • Network Security: Bind and authentication configuration
  • Audit Logging: Track and monitor operations

This Chapter Summary:

  • Understood main security risks and protection mechanisms
  • Mastered DM pairing and whitelist configuration
  • Learned sandbox mode and permission control
  • Understood sensitive data handling and network configuration
  • Mastered audit logging and security checklist

Update Log:

  • 2026-02-26: Initial release, based on OpenClaw v2026.2

Series Navigation: