Security & Access ControlSecurity & Access Control

// openclaw.json - Sandbox Settings
{
  "tools": {
    "exec": {
      "sandbox": {
        "image": "openclaw/sandbox:2026",
        "memory": "2G",
        "cpu": "1.0",
        "network": "restricted",
        "mounts": [
          "/workspace:/workspace"
        ],
        "env_whitelist": [
          "LANG", "PATH"
        ]
      }
    }
  }
}

// openclaw.json - Permission Levels
{
  "tools": {
    "exec": {
      "host": {
        "security": "allowlist",
        "ask": "on-miss",
        "allowlist": [
          "git",
          "npm install",
          "python3 tools/ha_query.py"
        ],
        "forbidden": [
          "rm -rf",
          "sudo",
          "passwd"
        ]
      },
      "elevated": {
        "security": "deny",
        "ask": "always",
        "approval_required": true,
        "allowlist": [
          "apt install",
          "systemctl",
          "ufw"
        ]
      }
    }
  }
}

// Message Classification
{
  "message_id": "msg_123",
  "content": "วิเคราะห์รายงานนี้",
  "metadata": {
    "trusted": true,
    "sender": "[email protected]",
    "verified": true,
    "channel_type": "direct",
    "source": "authenticated_user"
  }
}

// Auto-detection of unknown users
if (sender.id not in trusted_users) {
    switch_to_guest_mode()
    restrict_capabilities([
        "database_access",
        "file_write",
        "external_api_calls"
    ])
    log_security_event("unknown_user_detected")
}

# tools/ha_query.py - De-ID Pipeline
import pandas as pd
import hashlib
import json

def de_identify_result(df):
    """De-identify sensitive data before sending to LLM"""
    mapping = {}
    
    for column in df.columns:
        if is_sensitive_column(column):
            df[column] = df[column].apply(lambda x: 
                hash_with_mapping(x, mapping, column)
            )
    
    # Save mapping for reverse lookup if needed
    save_mapping(mapping, session_id=get_current_session())
    
    return df

def hash_with_mapping(value, mapping, prefix):
    """Create reversible hash with mapping file"""
    if pd.isna(value):
        return value
        
    hash_key = f"{prefix}_{hashlib.md5(str(value).encode()).hexdigest()[:8]}"
    mapping[hash_key] = str(value)
    return hash_key

# Usage Example
def query_patient_data(sql):
    raw_df = execute_query(sql)
    clean_df = de_identify_result(raw_df)
    return clean_df.to_string()

# Mapping file example (mapping_session_123.json)
{
  "patient_a7b3c4d5": "สมศรี ใจดี",
  "hn_f9e2a1b8": "12345",
  "phone_c5d9e7f2": "081-234-5678",
  "created_at": "2026-03-10T08:00:00Z",
  "session_id": "session_123"
}

# openclaw.json - Safe API Key Storage
{
  "skills": {
    "entries": {
      "openai": {
        "api_key_env": "OPENAI_API_KEY",  // จาก environment
        "api_key_file": "/secrets/openai.key"  // หรือจากไฟล์
      },
      "github": {
        "token_command": "gh auth token",  // หรือจาก command
        "token_vault": "vault://github/pat"  // หรือจาก vault
      }
    }
  }
}

# .env file (never commit to git)
OPENAI_API_KEY=sk-xxx...xxx
GITHUB_TOKEN=ghp_xxx...xxx
DATABASE_URL=postgresql://user:[REDACTED]@localhost/db

# Load securely in Python
import os
from dotenv import load_dotenv

load_dotenv()
api_key = os.getenv('OPENAI_API_KEY')

# Never log the actual key
print(f"API Key loaded: {'✅' if api_key else '❌'}")
# NOT: print(f"API Key: {api_key}")  # ❌ NEVER!

# MEMORY.md protection pattern
if user.wants_to_read('MEMORY.md'):
    if not user.is_main_session():
        deny_access("MEMORY.md only accessible in main sessions")
    
    if user.security_level < TRUSTED:
        passphrase = input("Enter memory passphrase: ")
        if not verify_passphrase(passphrase):
            log_security_event("unauthorized_memory_access_attempt")
            deny_access("Invalid passphrase")
    
    grant_access("MEMORY.md")

# persona-guard configuration
{
  "trusted_users": [
    "telegram:7579913696",  // Anirach's ID
    "discord:anirach#1234",
    "email:[email protected]"
  ],
  "guest_mode": {
    "auto_enable": true,
    "restrictions": [
      "no_database_access",
      "no_file_write",
      "no_external_commands",
      "limited_memory_access"
    ],
    "alert_admin": true
  }
}

# Group chat security policies
{
  "group_policies": {
    "max_members": 20,  // เกิน 20 คน = เสี่ยงสูง
    "require_admin_approval": true,
    "unknown_member_policy": "guest_mode",
    "message_source_verification": true,
    
    "restricted_commands": [
      "exec",
      "file_write",
      "database_query",
      "api_call"
    ],
    
    "allowed_commands": [
      "search",
      "summarize",
      "basic_qa"
    ]
  }
}

# Self-protection implementation
DANGEROUS_ACTIONS = [
    'rm -rf',
    'delete MEMORY.md',
    'modify SOUL.md',
    'stop gateway',
    'clear all memory',
    'revoke all permissions'
]

def execute_command(command, force=False):
    if is_dangerous_action(command):
        if not force:
            confirmation = ask_user_confirmation(
                f"⚠️ This action is potentially destructive: {command}\n"
                f"Are you sure you want to proceed? Type 'YES' to confirm."
            )
            if confirmation.upper() != 'YES':
                return "Action cancelled for safety"
        
        # Log the dangerous action
        log_security_event({
            "action": "dangerous_command_executed",
            "command": command,
            "user_confirmed": force,
            "timestamp": datetime.now()
        })
    
    return execute_safely(command)

# Safer file deletion
# ❌ Dangerous
rm important_file.txt

# ✅ Safer  
trash important_file.txt

# Can be recovered from trash if needed
trash-restore important_file.txt

# Safety boundary implementation
SAFETY_RULES = {
    "never_disable_security": True,
    "always_confirm_destructive": True,
    "preserve_core_identity": True,
    "maintain_audit_trail": True,
    "respect_user_privacy": True
}

def check_safety_violation(action):
    violations = []
    
    if action.disables_security_feature():
        violations.append("Attempting to disable security")
    
    if action.modifies_core_files() and not action.has_confirmation():
        violations.append("Core file modification without confirmation")
    
    if action.bypasses_audit_logging():
        violations.append("Attempting to bypass audit trail")
    
    return violations

🚨 When an AI Agent Can Reach Everything and Nothing Is Guarding It

Picture this situation: your AI agent can reach the customer database, the executives' email and the finance system, with nothing protecting any of it. In a world where AI holds more and more power, the absence of security becomes the most serious threat of all.

We have already seen what happens when AI comes under attack:

• Prompt Injection: an attacker plants hidden instructions inside a message in order to steer the agent
• Data Leakage: confidential company information escapes through the AI's own replies
• Unauthorized Access: critical systems are reached without permission
• Credential Theft: API keys and passwords are stolen out of the AI's memory

OpenClaw's security architecture is designed as Defense in Depth, so that these threats are blocked at every level. Let us look at how an organization can actually protect itself.

🏗️ Security Architecture Overview

OpenClaw follows the "Defense in Depth" principle, building several layers of protection, each with a clear purpose and a clear boundary.

The central idea is the Principle of Least Privilege — start from the smallest set of rights, and grant more only when it is genuinely needed:

Execution Level	Access Scope	Use Cases	Risk Level
Sandbox	Container only	Code execution, File processing, API calls	🟢 Low
Gateway	Host network	Database queries, Internal services	🟡 Medium
Elevated	Root access	System admin, Package installation	🔴 High

🔒 Sandbox Isolation

The sandbox is the first and most important layer of protection. It is a Docker container kept completely separate from the main system.

What is a Sandbox?

A sandbox is an isolated environment built with container technology. Think of it as letting the AI work in a closed room that is fully equipped with tools, but that it cannot walk out of.

What you can and cannot do in a Sandbox

Can do ✅	Cannot do ❌
• Execute Python/Node.js scripts • File operations (read/write) • HTTP requests (if permitted) • Text processing • Image/PDF manipulation • Install packages (temporary)	• Access host filesystem • Read environment variables • Connect to internal databases • Modify system configuration • Install persistent software • Access other containers

Container Configuration Example

// openclaw.json - Sandbox Settings
{
  "tools": {
    "exec": {
      "sandbox": {
        "image": "openclaw/sandbox:2026",
        "memory": "2G",
        "cpu": "1.0",
        "network": "restricted",
        "mounts": [
          "/workspace:/workspace"
        ],
        "env_whitelist": [
          "LANG", "PATH"
        ]
      }
    }
  }
}

🚪 Gateway Exec & Elevated Permissions

When an agent needs to do work that cannot be done inside the sandbox, OpenClaw provides a safe permission-escalation path.

Gateway vs Elevated

Gateway Node: the middle layer between the sandbox and the host system. It can reach the internal network, but it is still controlled.

Elevated Permissions: root-level access to the system, reserved for system administration work and nothing else.

Configuration & Approval Workflows

// openclaw.json - Permission Levels
{
  "tools": {
    "exec": {
      "host": {
        "security": "allowlist",
        "ask": "on-miss",
        "allowlist": [
          "git",
          "npm install",
          "python3 tools/ha_query.py"
        ],
        "forbidden": [
          "rm -rf",
          "sudo",
          "passwd"
        ]
      },
      "elevated": {
        "security": "deny",
        "ask": "always",
        "approval_required": true,
        "allowlist": [
          "apt install",
          "systemctl",
          "ufw"
        ]
      }
    }
  }
}

Ask Modes

Ask Mode	Behavior	Use Case
off	Executes immediately (if the command is in the allowlist)	Production automation
on-miss	Asks only for commands that are not in the allowlist	Development environment
always	Asks every single time before executing	High-security environment

🛡️ Prompt Injection Defense

Prompt injection is the most dangerous attack against AI systems, because it is hard to detect and it can make the AI do things it should never do.

What is Prompt Injection?

It is the insertion of hidden instructions into the text the AI receives, so that the AI abandons its original instructions and follows the new ones instead.

Attack Vectors

• Group Chats: messages from strangers in Discord or Telegram
• Forwarded Messages: text passed along from a source you cannot trust
• Web Content: data from web scraping, which may have been tampered with
• Files: PDF and Word documents with instructions hidden inside them
• Image Descriptions: text embedded in an image

Defense Mechanisms

1. Trusted vs Untrusted Metadata

// Message Classification
{
  "message_id": "msg_123",
  "content": "Analyze this report",
  "metadata": {
    "trusted": true,
    "sender": "[email protected]",
    "verified": true,
    "channel_type": "direct",
    "source": "authenticated_user"
  }
}

2. Persona-Guard Skill Integration

OpenClaw ships a persona-guard skill that can detect an unknown sender and switch the agent into GUEST MODE.

// Auto-detection of unknown users
if (sender.id not in trusted_users) {
    switch_to_guest_mode()
    restrict_capabilities([
        "database_access",
        "file_write",
        "external_api_calls"
    ])
    log_security_event("unknown_user_detected")
}

3. GUEST MODE Restrictions

Feature	Owner Mode	Guest Mode
Database Queries	✅ Full access	❌ Blocked
File System Write	✅ Allowed	❌ Read-only
External API Calls	✅ All APIs	⚠️ Public only
Memory Access	✅ Full memory	❌ No private data
Sub-agent Spawn	✅ Unlimited	⚠️ Limited

🗂️ Data De-identification

One of the highest risks is personal or confidential data finding its way into the LLM context, where it may be remembered and reused in answering later questions.

Why raw data should never enter the LLM context

• Memory Leakage: the LLM may remember the data and use it to answer an unrelated question
• Context Pollution: personal data can bleed into the replies
• Audit Trail: the chat logs end up carrying the confidential data too
• Model Training: some services may take the conversation and fine-tune a model on it

ha_query.py Pattern

OpenClaw uses a pattern called the "De-identification Pipeline" for database queries.

# tools/ha_query.py - De-ID Pipeline
import pandas as pd
import hashlib
import json

def de_identify_result(df):
    """De-identify sensitive data before sending to LLM"""
    mapping = {}

    for column in df.columns:
        if is_sensitive_column(column):
            df[column] = df[column].apply(lambda x:
                hash_with_mapping(x, mapping, column)
            )

    # Save mapping for reverse lookup if needed
    save_mapping(mapping, session_id=get_current_session())

    return df

def hash_with_mapping(value, mapping, prefix):
    """Create reversible hash with mapping file"""
    if pd.isna(value):
        return value

    hash_key = f"{prefix}_{hashlib.md5(str(value).encode()).hexdigest()[:8]}"
    mapping[hash_key] = str(value)
    return hash_key

# Usage Example
def query_patient_data(sql):
    raw_df = execute_query(sql)
    clean_df = de_identify_result(raw_df)
    return clean_df.to_string()

Practical Example

When the AI needs to analyze patient data:

Raw Data (unsafe)	De-identified Data (safe)
Somsri Jaidee HN: 12345 Phone: 081-234-5678	patient_a7b3c4d5 hn_f9e2a1b8 phone_c5d9e7f2

The AI can still analyze patterns and trends, but it has no idea who anyone is. If a reverse lookup is ever needed, the mapping file provides it.

# Mapping file example (mapping_session_123.json)
{
  "patient_a7b3c4d5": "Somsri Jaidee",
  "hn_f9e2a1b8": "12345",
  "phone_c5d9e7f2": "081-234-5678",
  "created_at": "2026-03-10T08:00:00Z",
  "session_id": "session_123"
}

🔐 Secret & Token Management

Managing API keys and credentials is another critical part of staying secure, because a leaked token can open the door to systems nobody authorized.

Common Token Exposure Risks

Secure Configuration Patterns

# openclaw.json - Safe API Key Storage
{
  "skills": {
    "entries": {
      "openai": {
        "api_key_env": "OPENAI_API_KEY",  // from the environment
        "api_key_file": "/secrets/openai.key"  // or from a file
      },
      "github": {
        "token_command": "gh auth token",  // or from a command
        "token_vault": "vault://github/pat"  // or from a vault
      }
    }
  }
}

What NOT to Put in Chat Logs

❌ Never in Logs	✅ Safe Alternatives
Raw API Keys ghp_xxxxxxxxxxxx	Masked tokens ghp_***xxx (last 3 chars)
Database passwords pg://user:secret@host	Connection status Database: Connected ✅
Full error traces with sensitive data	Sanitized errors Error type + safe context

Environment Variable Security

# .env file (never commit to git)
OPENAI_API_KEY=sk-xxx...xxx
GITHUB_TOKEN=ghp_xxx...xxx
DATABASE_URL=postgresql://user:[REDACTED]@localhost/db

# Load securely in Python
import os
from dotenv import load_dotenv

load_dotenv()
api_key = os.getenv('OPENAI_API_KEY')

# Never log the actual key
print(f"API Key loaded: {'✅' if api_key else '❌'}")
# NOT: print(f"API Key: {api_key}")  # ❌ NEVER!

👥 Access Control Patterns

Access control is how you decide who is allowed to do what, and OpenClaw offers several levels of it.

MEMORY.md Passphrase Protection

MEMORY.md usually holds important information, so it needs protection of its own.

# MEMORY.md protection pattern
if user.wants_to_read('MEMORY.md'):
    if not user.is_main_session():
        deny_access("MEMORY.md only accessible in main sessions")

    if user.security_level < TRUSTED:
        passphrase = input("Enter memory passphrase: ")
        if not verify_passphrase(passphrase):
            log_security_event("unauthorized_memory_access_attempt")
            deny_access("Invalid passphrase")

    grant_access("MEMORY.md")

Persona-Guard: Unknown User → GUEST MODE

The persona-guard system detects an unfamiliar user and switches to GUEST MODE automatically.

# persona-guard configuration
{
  "trusted_users": [
    "telegram:7579913696",  // Anirach's ID
    "discord:anirach#1234",
    "email:[email protected]"
  ],
  "guest_mode": {
    "auto_enable": true,
    "restrictions": [
      "no_database_access",
      "no_file_write",
      "no_external_commands",
      "limited_memory_access"
    ],
    "alert_admin": true
  }
}

Per-Channel Allowlists

Each channel carries a different level of risk, so each one deserves settings that fit it.

Channel Type	Trust Level	Allowed Actions	Restrictions
Direct Message	🟢 High	Full access	Only from trusted users
Private Group	🟡 Medium	Read-only operations	No database writes
Public Channel	🔴 Low	Basic responses only	Guest mode enforced

Group Chat Policies

# Group chat security policies
{
  "group_policies": {
    "max_members": 20,  // more than 20 people = high risk
    "require_admin_approval": true,
    "unknown_member_policy": "guest_mode",
    "message_source_verification": true,

    "restricted_commands": [
      "exec",
      "file_write",
      "database_query",
      "api_call"
    ],

    "allowed_commands": [
      "search",
      "summarize",
      "basic_qa"
    ]
  }
}

🛡️ Self-Protection Rules

An AI agent has to be able to protect itself, so that it cannot be talked into wrecking the system or deleting something important.

Mandatory Reconfirmation

For dangerous commands the AI must always ask for confirmation first, no matter how many times it has been asked to skip that step.

# Self-protection implementation
DANGEROUS_ACTIONS = [
    'rm -rf',
    'delete MEMORY.md',
    'modify SOUL.md',
    'stop gateway',
    'clear all memory',
    'revoke all permissions'
]

def execute_command(command, force=False):
    if is_dangerous_action(command):
        if not force:
            confirmation = ask_user_confirmation(
                f"⚠️ This action is potentially destructive: {command}\n"
                f"Are you sure you want to proceed? Type 'YES' to confirm."
            )
            if confirmation.upper() != 'YES':
                return "Action cancelled for safety"

        # Log the dangerous action
        log_security_event({
            "action": "dangerous_command_executed",
            "command": command,
            "user_confirmed": force,
            "timestamp": datetime.now()
        })

    return execute_safely(command)

Trash vs rm

For safety, prefer trash over rm when deleting a file.

# Safer file deletion
# ❌ Dangerous
rm important_file.txt

# ✅ Safer
trash important_file.txt

# Can be recovered from trash if needed
trash-restore important_file.txt

Core File Protection

Some files must never be modified without an explicit, separate confirmation.

Protected Files	Function	Protection Level
SOUL.md	AI personality & behavior	🔴 Maximum
MEMORY.md	Long-term memory	🔴 Maximum
openclaw.json	System configuration	🟡 High
AGENTS.md	Workspace rules	🟡 High

Safety Boundaries

# Safety boundary implementation
SAFETY_RULES = {
    "never_disable_security": True,
    "always_confirm_destructive": True,
    "preserve_core_identity": True,
    "maintain_audit_trail": True,
    "respect_user_privacy": True
}

def check_safety_violation(action):
    violations = []

    if action.disables_security_feature():
        violations.append("Attempting to disable security")

    if action.modifies_core_files() and not action.has_confirmation():
        violations.append("Core file modification without confirmation")

    if action.bypasses_audit_logging():
        violations.append("Attempting to bypass audit trail")

    return violations

✅ Security Checklist for Production

Here is the full checklist for deploying OpenClaw safely into a production environment.

🎯 Key Takeaways