Gateway Security

Gateway Security

Security is paramount when running an AI gateway that handles messaging platforms and executes code. This guide covers all aspects of OpenClaw Gateway security.

Security Overview

OpenClaw Gateway includes multiple layers of security:

• Network Security: Secure communication channels
• Authentication: Token-based access control
• Authorization: Role-based permissions
• Sandboxing: Isolated execution environments
• Data Protection: Encrypted storage and transmission
• Audit Logging: Comprehensive activity tracking

Network Security

Secure Binding

By default, OpenClaw Gateway binds to localhost only:

{
  gateway: {
    bind: "127.0.0.1", // Loopback only (most secure)
    port: 18789
  }
}

Remote Access Security

If you need remote access, use secure methods:

{
  gateway: {
    bind: "0.0.0.0", // Allow remote connections
    port: 18789,
    token: "your-secure-token-here",

    // TLS/SSL configuration
    tls: {
      enabled: true,
      cert: "/path/to/cert.pem",
      key: "/path/to/key.pem",
      ca: "/path/to/ca.pem"
    }
  }
}

Firewall Configuration

Configure firewall rules to restrict access:

# Allow only specific IPs
sudo ufw allow from 192.168.1.0/24 to any port 18789

# Block all other access
sudo ufw deny 18789

# Allow loopback
sudo ufw allow from 127.0.0.1 to any port 18789

Authentication

Token-Based Authentication

Generate secure tokens for Gateway access:

# Generate a new token
openclaw gateway generate-token

# Set token in configuration
openclaw config set gateway.token "your-generated-token"

# Rotate tokens regularly
openclaw gateway rotate-token

Token Configuration

{
  gateway: {
    token: "your-secure-token-here",

    // Token settings
    tokenConfig: {
      expiration: "24h",
      refreshEnabled: true,
      maxTokens: 5,
      tokenLength: 32
    }
  }
}

API Key Management

Securely store API keys:

{
  security: {
    // Use environment variables for sensitive data
    apiKeys: {
      anthropic: "${ANTHROPIC_API_KEY}",
      openai: "${OPENAI_API_KEY}",
      google: "${GOOGLE_API_KEY}"
    },

    // Key rotation settings
    keyRotation: {
      enabled: true,
      interval: "30d",
      notifyBefore: "7d"
    }
  }
}

Authorization

Role-Based Access Control

Define roles and permissions:

{
  security: {
    authorization: {
      enabled: true,
      roles: {
        admin: {
          permissions: ["*"], // All permissions
          channels: ["*"],
          commands: ["*"]
        },
        user: {
          permissions: ["read", "write"],
          channels: ["whatsapp", "telegram"],
          commands: ["help", "status", "ask"]
        },
        readonly: {
          permissions: ["read"],
          channels: ["*"],
          commands: ["help", "status"]
        }
      },

      // User assignments
      users: {
        "user123": {
          role: "user",
          channels: ["whatsapp"],
          restrictions: {
            maxMessages: 100,
            timeWindow: "1h"
          }
        }
      }
    }
  }
}

Channel Permissions

Control access to specific channels:

{
  channels: {
    whatsapp: {
      permissions: {
        allowedUsers: ["user123", "user456"],
        allowedRoles: ["admin", "user"],
        blockedUsers: ["spam_user"],

        // Command permissions
        commands: {
          allowed: ["help", "status", "ask"],
          blocked: ["config", "admin"]
        }
      }
    }
  }
}

Sandboxing

Docker Sandboxing

Run agents in isolated Docker containers:

{
  security: {
    sandboxing: {
      enabled: true,
      type: "docker",

      // Docker configuration
      docker: {
        image: "openclaw/sandbox:latest",
        network: "none", // No network access
        readonly: false,

        // Resource limits
        limits: {
          memory: "512m",
          cpu: "0.5",
          disk: "1g",
          processes: 10
        },

        // Volume mounts
        volumes: {
          "/workspace": "/workspace:rw",
          "/tmp": "/tmp:rw"
        },

        // Security options
        securityOpt: [
          "no-new-privileges:true",
          "seccomp:default"
        ],

        // User isolation
        user: "nobody",
        group: "nogroup"
      }
    }
  }
}

File System Sandboxing

Restrict file system access:

{
  security: {
    fileSystem: {
      // Allowed paths
      allowedPaths: [
        "~/.openclaw",
        "/tmp",
        "./workspace"
      ],

      // Denied paths (high priority)
      deniedPaths: [
        "/etc",
        "/usr/bin",
        "/usr/sbin",
        "~/.ssh",
        "~/.aws"
      ],

      // Path restrictions
      restrictions: {
        maxFileSize: "10MB",
        maxPathLength: 255,
        allowedExtensions: [".txt", ".py", ".js", ".md"],
        deniedExtensions: [".exe", ".sh", ".bat"]
      },

      // Monitoring
      monitoring: {
        logFileAccess: true,
        alertOnSuspicious: true,
        quarantineSuspicious: true
      }
    }
  }
}

Data Protection

Encryption

Configure encryption for sensitive data:

{
  security: {
    encryption: {
      // Database encryption
      database: {
        enabled: true,
        algorithm: "AES-256-GCM",
        keyDerivation: "PBKDF2",
        iterations: 100000
      },

      // Configuration encryption
      config: {
        enabled: true,
        encryptApiKeys: true,
        encryptTokens: true
      },

      // Message encryption
      messages: {
        enabled: false, // Usually not needed for local storage
        algorithm: "AES-256-CBC"
      }
    }
  }
}

Secure Storage

Secure storage of sensitive data:

{
  security: {
    storage: {
      // Secure configuration storage
      configPath: "~/.openclaw/config",
      configPermissions: "600",

      // Secure log storage
      logPath: "~/.openclaw/logs",
      logPermissions: "640",
      logRetention: "30d",

      // Secure backup storage
      backupPath: "~/.openclaw/backups",
      backupEncryption: true,
      backupRetention: "90d"
    }
  }
}

Audit Logging

Comprehensive Logging

Configure detailed audit logging:

{
  logging: {
    level: "info",

    // Audit log configuration
    audit: {
      enabled: true,
      file: "~/.openclaw/logs/audit.log",
      format: "json",

      // Events to log
      events: [
        "authentication",
        "authorization",
        "config_changes",
        "message_send",
        "message_receive",
        "agent_execution",
        "file_access",
        "errors"
      ],

      // Log retention
      retention: "365d",
      compression: true,
      encryption: true
    },

    // Security-specific logging
    security: {
      level: "warn",
      includeStackTrace: true,
      alertOnFailures: true,

      // Security events
      events: [
        "authentication_failure",
        "authorization_denied",
        "sandbox_escape",
        "suspicious_activity",
        "rate_limit_exceeded"
      ]
    }
  }
}

Log Analysis

Analyze security logs:

# View authentication attempts
openclaw logs filter --event authentication --level warn

# View authorization failures
openclaw logs filter --event authorization_denied

# View suspicious activity
openclaw logs filter --event suspicious_activity

# Generate security report
openclaw security report --last 7d

Rate Limiting

Global Rate Limiting

Configure global rate limits:

{
  security: {
    rateLimit: {
      enabled: true,

      // Global limits
      global: {
        windowMs: 900000, // 15 minutes
        maxRequests: 1000,
        skipSuccessfulRequests: false,
        skipFailedRequests: false
      },

      // Per-user limits
      perUser: {
        windowMs: 900000,
        maxRequests: 100,
        skipSuccessfulRequests: true
      },

      // Per-channel limits
      perChannel: {
        windowMs: 900000,
        maxRequests: 500
      }
    }
  }
}

Advanced Rate Limiting

Configure sophisticated rate limiting:

{
  security: {
    rateLimit: {
      // Role-based limits
      roleLimits: {
        admin: {
          windowMs: 900000,
          maxRequests: 10000
        },
        user: {
          windowMs: 900000,
          maxRequests: 100
        },
        readonly: {
          windowMs: 900000,
          maxRequests: 50
        }
      },

      // Command-specific limits
      commandLimits: {
        "config": {
          windowMs: 3600000, // 1 hour
          maxRequests: 10
        },
        "ask": {
          windowMs: 900000,
          maxRequests: 20
        }
      }
    }
  }
}

Security Monitoring

Real-time Monitoring

Configure security monitoring:

{
  security: {
    monitoring: {
      enabled: true,

      // Anomaly detection
      anomalyDetection: {
        enabled: true,
        threshold: 0.8,
        windowSize: "1h",

        // Metrics to monitor
        metrics: [
          "authentication_failures",
          "authorization_denials",
          "message_volume",
          "file_access_patterns",
          "resource_usage"
        ]
      },

      // Alerting
      alerting: {
        enabled: true,
        channels: ["email", "webhook"],
        recipients: ["admin@example.com"],
        webhookUrl: "https://your-monitoring.com/webhook"
      }
    }
  }
}

Security Scans

Regular security scans:

# Run security scan
openclaw security scan

# Check for vulnerabilities
openclaw security check-vulnerabilities

# Validate configuration
openclaw security validate-config

# Check permissions
openclaw security check-permissions

Security Best Practices

1. Network Security

• Use loopback binding when possible
• Implement TLS for remote access
• Configure firewall rules
• Use VPN for remote access

2. Authentication

• Use strong, unique tokens
• Rotate tokens regularly
• Implement multi-factor authentication
• Use environment variables for secrets

3. Authorization

• Follow principle of least privilege
• Implement role-based access control
• Regular permission audits
• Document permission policies

4. Sandboxing

• Always sandbox agent execution
• Use Docker containers for isolation
• Restrict file system access
• Monitor resource usage

5. Data Protection

• Encrypt sensitive data at rest
• Use secure communication channels
• Implement proper backup procedures
• Regular security audits

Security Checklist

Initial Setup

• Change default tokens and passwords
• Configure secure network binding
• Set up proper authentication
• Implement role-based access control
• Enable sandboxing
• Configure audit logging

Ongoing Maintenance

• Regular security updates
• Token rotation
• Permission audits
• Log review
• Security scans
• Backup verification

Incident Response

• Security incident plan
• Emergency contact procedures
• Data recovery procedures
• Communication plan
• Post-incident analysis

Security Commands

# Security management
openclaw security status
openclaw security scan
openclaw security check-permissions
openclaw security validate-config

# Token management
openclaw gateway generate-token
openclaw gateway rotate-token
openclaw gateway list-tokens

# Audit and logging
openclaw logs audit --last 24h
openclaw security report --last 7d
openclaw security export-audit --format json

# Configuration security
openclaw config encrypt
openclaw config decrypt
openclaw security backup-config

---

By following these security guidelines, your OpenClaw Gateway will be secure, resilient, and ready for production use. 🔒