Access Control and Security Hardening Guide for OpenClaw

Introduction

As an AI gateway connecting multiple chat platforms, security is critical for OpenClaw. If unauthorized users gain access, you could face steep API charges and potential data leaks. This tutorial covers multiple layers of security hardening, including Dashboard authentication, user access control, rate limiting, and audit logging.

Security Threat Overview

Threat Type	Risk Level	Description
Unauthorized Dashboard access	High	Attackers can modify configuration and view conversations
API Key leakage	High	Others can consume your API quota
User abuse	Medium	Authorized users overusing the service, driving up costs
Conversation data exposure	Medium	Chat logs accessed without authorization
DDoS attacks	Medium	Service overwhelmed by malicious requests
Injection attacks	Low	Malicious prompts manipulating AI behavior

Step 1: Dashboard Authentication

1.1 Enable Password Authentication

By default, the Dashboard may lack password protection. Configure it immediately:

{
  dashboard: {
    enabled: true,
    port: 18789,
    auth: {
      enabled: true,
      username: "admin",
      password: "${OPENCLAW_DASHBOARD_PASSWORD}",  // Use an environment variable
    }
  }
}

Set the environment variable:

# Generate a strong password
openssl rand -base64 32
# Output example: K7x9mP2vQ4wR1tY6uI3oA8sD5fG0hJ=

# Add to environment variables
echo 'export OPENCLAW_DASHBOARD_PASSWORD="K7x9mP2vQ4wR1tY6uI3oA8sD5fG0hJ="' >> ~/.bashrc
source ~/.bashrc

1.2 Configure Session Management

{
  dashboard: {
    auth: {
      enabled: true,
      username: "admin",
      password: "${OPENCLAW_DASHBOARD_PASSWORD}",
      session: {
        timeout: 3600,           // Session expiration (seconds), 1 hour
        maxSessions: 3,          // Maximum concurrent sessions
        secureCookie: true,      // Send cookies over HTTPS only
      }
    }
  }
}

1.3 Multi-User Management

If a team needs to manage OpenClaw:

{
  dashboard: {
    auth: {
      enabled: true,
      users: [
        {
          username: "admin",
          password: "${ADMIN_PASSWORD}",
          role: "admin",          // Full control
        },
        {
          username: "operator",
          password: "${OPERATOR_PASSWORD}",
          role: "operator",       // Can view logs and status, cannot modify configuration
        },
        {
          username: "viewer",
          password: "${VIEWER_PASSWORD}",
          role: "viewer",         // Read-only access
        }
      ]
    }
  }
}

Role permissions comparison:

Permission	admin	operator	viewer
View Dashboard	✓	✓	✓
View logs	✓	✓	✓
View conversation history	✓	✓	✗
Modify configuration	✓	✗	✗
Manage users	✓	✗	✗
Restart service	✓	✓	✗

Step 2: API Key Protection

2.1 Environment Variable Storage (Required)

Never store API Keys in plain text in your configuration file:

// Wrong approach ✗
{
  models: {
    openai: {
      apiKey: "sk-proj-abc123..."   // Do not do this!
    }
  }
}

// Correct approach ✓
{
  models: {
    openai: {
      apiKey: "${OPENAI_API_KEY}"   // Reference via environment variable
    }
  }
}

2.2 File Permission Control

# Restrict configuration file permissions
chmod 600 ~/.config/openclaw/openclaw.json5

# Confirm file ownership
chown $(whoami) ~/.config/openclaw/openclaw.json5

# Verify permissions
ls -la ~/.config/openclaw/openclaw.json5
# Should show -rw------- (owner read/write only)

2.3 Git Exclusion

If you use Git to manage your configuration, ensure sensitive files are excluded:

# Add to .gitignore
echo "openclaw.json5" >> ~/.config/openclaw/.gitignore
echo ".env" >> ~/.config/openclaw/.gitignore
echo "*.key" >> ~/.config/openclaw/.gitignore
echo "*.pem" >> ~/.config/openclaw/.gitignore

Step 3: User Whitelist / Blacklist

3.1 User Whitelist (Recommended)

Only allow specified users to use the AI assistant:

{
  accessControl: {
    mode: "whitelist",            // whitelist or blacklist
    whitelist: {
      telegram: [
        "123456789",              // Telegram user ID
        "987654321",
      ],
      whatsapp: [
        "+8613800138000",         // WhatsApp phone number
        "+8613900139000",
      ],
      discord: [
        "112233445566778899",     // Discord user ID
      ]
    },
    denyMessage: "Sorry, you do not have permission to use this assistant. Please contact the administrator.",
  }
}

3.2 User Blacklist

If most users should have access and you only need to block specific individuals:

{
  accessControl: {
    mode: "blacklist",
    blacklist: {
      telegram: [
        "111111111",              // Banned user
      ],
      global: [
        "[email protected]",   // Blocked across all channels
      ]
    },
    blockMessage: "Your access has been suspended.",
  }
}

3.3 Group Access Control

For bots deployed in group chats, you can restrict which groups are allowed:

{
  accessControl: {
    groups: {
      telegram: {
        allowedGroups: [
          "-1001234567890",       // Allowed group ID
          "-1009876543210",
        ],
        allowPrivate: true,       // Allow private messages
      },
      discord: {
        allowedServers: [
          "1234567890123456",     // Allowed server ID
        ],
        allowedChannels: [
          "9876543210987654",     // Allowed channel ID (more granular)
        ]
      }
    }
  }
}

Step 4: Rate Limiting

4.1 Global Rate Limits

Prevent any single user from overusing the service:

{
  rateLimit: {
    global: {
      maxRequestsPerMinute: 30,     // Maximum 30 requests per minute globally
      maxRequestsPerHour: 500,      // Maximum 500 per hour globally
      maxRequestsPerDay: 5000,      // Maximum 5000 per day globally
    }
  }
}

4.2 Per-User Rate Limits

{
  rateLimit: {
    perUser: {
      maxRequestsPerMinute: 5,      // 5 per minute per user
      maxRequestsPerHour: 60,       // 60 per hour per user
      maxRequestsPerDay: 500,       // 500 per day per user
      cooldownMessage: "You're sending messages too frequently. Please try again shortly.",
    }
  }
}

4.3 Tiered Rate Limits

Set different limits for different user groups:

{
  rateLimit: {
    tiers: {
      vip: {
        users: ["123456789", "+8613800138000"],
        maxRequestsPerMinute: 20,
        maxRequestsPerDay: 2000,
      },
      standard: {
        default: true,               // Default tier for unspecified users
        maxRequestsPerMinute: 5,
        maxRequestsPerDay: 200,
      },
      restricted: {
        users: ["987654321"],
        maxRequestsPerMinute: 1,
        maxRequestsPerDay: 20,
      }
    }
  }
}

Step 5: IP Restrictions

5.1 Dashboard IP Whitelist

Only allow specific IPs to access the Dashboard:

{
  dashboard: {
    auth: {
      enabled: true,
      username: "admin",
      password: "${OPENCLAW_DASHBOARD_PASSWORD}",
    },
    ipWhitelist: [
      "203.0.113.0/24",            // Your office IP range
      "198.51.100.1",              // Your home IP
      "127.0.0.1",                 // Local access
    ]
  }
}

5.2 Firewall Restrictions

System-level IP restrictions are more robust:

# Using ufw (Ubuntu)
sudo ufw allow from 203.0.113.0/24 to any port 18789
sudo ufw deny 18789

# Using iptables
sudo iptables -A INPUT -p tcp --dport 18789 -s 203.0.113.0/24 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 18789 -j DROP

5.3 Fail2ban for Brute-Force Protection

Configure Fail2ban to automatically ban IPs with multiple failed login attempts:

sudo apt install fail2ban

Create a Fail2ban rule for OpenClaw:

sudo nano /etc/fail2ban/jail.d/openclaw.conf

[openclaw]
enabled = true
port = 18789
filter = openclaw
logpath = /var/log/openclaw/access.log
maxretry = 5
findtime = 600
bantime = 3600

Create the filter:

sudo nano /etc/fail2ban/filter.d/openclaw.conf

[Definition]
failregex = ^.*authentication failed.*from <HOST>.*$
ignoreregex =

sudo systemctl restart fail2ban

Step 6: Audit Logging

6.1 Enable Detailed Logging

{
  logging: {
    level: "info",                   // debug, info, warn, error
    file: "/var/log/openclaw/openclaw.log",
    audit: {
      enabled: true,
      file: "/var/log/openclaw/audit.log",
      events: [
        "auth.login",                // Login events
        "auth.failed",               // Failed logins
        "config.change",             // Configuration changes
        "user.blocked",              // User blocked
        "rateLimit.exceeded",        // Rate limit triggered
        "message.received",          // Messages received (optional, high volume)
      ]
    }
  }
}

6.2 Log Rotation

Prevent log files from growing indefinitely:

sudo nano /etc/logrotate.d/openclaw

/var/log/openclaw/*.log {
    daily
    missingok
    rotate 30
    compress
    delaycompress
    notifempty
    create 640 openclaw openclaw
    postrotate
        openclaw restart > /dev/null 2>&1 || true
    endscript
}

6.3 Reviewing Audit Logs

# View recent audit events
openclaw logs --audit --since 24h

# Filter for failed login events
openclaw logs --audit --filter "auth.failed"

# View activity for a specific user
openclaw logs --audit --user "123456789"

Step 7: Security Best Practices Checklist

Pre-Deployment Check

# Run a security check
openclaw doctor --security

Security Checklist

Item	Status	Notes
Dashboard password set	□	Use a strong password, at least 16 characters
API Keys use environment variables	□	Never store in plain text in config files
Config file permissions set to 600	□	Owner read/write only
HTTPS enabled	□	Required for production
User whitelist configured	□	Restrict who can use the service
Rate limiting enabled	□	Prevent abuse
Audit logging enabled	□	Record critical operations
Firewall configured	□	Only open necessary ports
Auto-updates enabled	□	Patch security vulnerabilities promptly
Regular backups	□	Prevent data loss

Regular Security Maintenance

# Weekly: Check audit logs for anomalies
openclaw logs --audit --since 7d --filter "auth.failed"

# Monthly: Update OpenClaw to the latest version
npm update -g openclaw@latest

# Monthly: Rotate Dashboard password
# Update the environment variable password and restart

# Quarterly: Review the whitelist and remove inactive users

Troubleshooting

Forgot the Dashboard Password

# Simply update the environment variable with a new password
export OPENCLAW_DASHBOARD_PASSWORD="new-password"
openclaw restart

Accidentally Blocked Your Own IP

# Log in via SSH first
# If blocked by Fail2ban
sudo fail2ban-client set openclaw unbanip your-ip

# If blocked by the config file IP whitelist
# Edit the config file to add your IP, then restart
openclaw restart

Rate Limits Too Strict

Monitor the frequency of rateLimit.exceeded events in the logs and adjust accordingly:

openclaw logs --audit --filter "rateLimit.exceeded" --since 24h

Adjust limit values based on actual usage patterns.

Summary

Security hardening is an essential step for running a production-grade OpenClaw instance. The core measures include: enabling Dashboard authentication, protecting API Keys with environment variables, configuring user whitelists, setting up rate limiting, and enabling audit logging. These measures are not complicated but significantly improve security. We recommend following the security checklist in this article to verify and configure each item, ensuring your AI assistant runs in a secure and controlled environment.