Gateway Configuration

Gateway Configuration

The OpenClaw Gateway is the central component that manages all messaging platform connections and AI agent communications. This guide covers comprehensive Gateway configuration.

Configuration File Location

OpenClaw stores configuration in:

• Primary: ~/.openclaw/openclaw.json
• Environment: OPENCLAW_CONFIG_PATH (custom location)
• State: ~/.openclaw/state/ (runtime data)

Basic Configuration Structure

{
  // Core Gateway settings
  gateway: {
    port: 18789,
    bind: "127.0.0.1",
    token: "your-security-token",
    canvasHost: {
      port: 18793
    }
  },

  // Messaging channels
  channels: {
    whatsapp: { /* WhatsApp settings */ },
    telegram: { /* Telegram settings */ },
    discord: { /* Discord settings */ },
    imessage: { /* iMessage settings */ }
  },

  // AI agents
  agents: {
    default: { /* Default agent config */ }
  },

  // Security and permissions
  security: {
    authentication: true,
    sandboxing: true
  },

  // Logging and monitoring
  logging: {
    level: "info",
    file: true
  }
}

Gateway Core Settings

Network Configuration

{
  gateway: {
    // WebSocket server port for node connections
    port: 18789,

    // Bind address (security: use 127.0.0.1 for local only)
    bind: "127.0.0.1",

    // Security token for non-loopback connections
    token: "generated-secure-token",

    // Canvas host for web views (iOS/Android nodes)
    canvasHost: {
      port: 18793,
      host: "127.0.0.1"
    },

    // Connection limits
    maxConnections: 100,
    connectionTimeout: 30000,

    // Heartbeat settings
    heartbeat: {
      interval: 30000,
      timeout: 90000
    }
  }
}

Service Configuration

{
  gateway: {
    // Service mode settings
    service: {
      enabled: true,
      user: "openclaw",
      group: "openclaw",
      workingDirectory: "~/.openclaw"
    },

    // Process management
    process: {
      maxMemory: "1GB",
      maxCpu: 50,
      restartDelay: 5000,
      maxRestarts: 10
    }
  }
}

Channel Configuration

WhatsApp

{
  channels: {
    whatsapp: {
      // Enable/disable WhatsApp
      enabled: true,

      // Connection settings
      connection: {
        timeout: 60000,
        reconnectInterval: 5000,
        maxReconnectAttempts: 10
      },

      // Security and access control
      allowFrom: [
        "+15555550123",
        "+15555550456"
      ],
      blockFrom: [
        "+15555550000" // Spam numbers
      ],

      // Group chat settings
      groups: {
        "*": { // All groups
          requireMention: true,
          mentionPatterns: ["@openclaw", "@ai"],
          allowedCommands: ["help", "status", "code"]
        },
        "family-group@g.us": {
          requireMention: false,
          autoRespond: true
        }
      },

      // Message handling
      messages: {
        maxMessageLength: 4096,
        mediaEnabled: true,
        voiceTranscription: true,
        typingIndicator: true
      },

      // Session management
      session: {
        savePath: "~/.openclaw/sessions/whatsapp",
        autoSave: true,
        encryption: true
      }
    }
  }
}

Telegram

{
  channels: {
    telegram: {
      enabled: true,

      // Bot configuration
      botToken: "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",

      // Webhook configuration
      webhook: {
        enabled: true,
        url: "https://your-domain.com/webhook/telegram",
        port: 8443,
        secret: "webhook-secret"
      },

      // Polling configuration (alternative to webhook)
      polling: {
        enabled: false,
        interval: 1000,
        timeout: 30000
      },

      // Allowed users and groups
      allowFrom: [
        123456789, // User IDs
        -1001234567890 // Group chat IDs (negative)
      ],

      // Group settings
      groups: {
        "*": {
          requireMention: true,
          mentionPatterns: ["/openclaw", "@openclaw"]
        }
      },

      // Command handling
      commands: {
        enabled: true,
        prefix: "/",
        commands: {
          "start": "Welcome message",
          "help": "Show available commands",
          "status": "Show gateway status"
        }
      }
    }
  }
}

Discord

{
  channels: {
    discord: {
      enabled: true,

      // Bot configuration
      botToken: "MTIzNDU2Nzg5OABCdefGHIjklMNOpqrsTUVwxyz",

      // Gateway intents
      intents: [
        "GUILDS",
        "GUILD_MESSAGES",
        "DIRECT_MESSAGES",
        "MESSAGE_CONTENT"
      ],

      // Server and channel permissions
      allowedServers: [
        "123456789012345678" // Server IDs
      ],
      allowedChannels: [
        "123456789012345678" // Channel IDs
      ],

      // Message settings
      messages: {
        maxMessageLength: 2000,
        embeds: true,
        reactions: true,
        typingIndicator: true
      },

      // Voice support (optional)
      voice: {
        enabled: false,
        joinChannels: [],
        autoDisconnect: true
      }
    }
  }
}

iMessage (macOS)

{
  channels: {
    imessage: {
      enabled: true,

      // imsg CLI configuration
      imsgPath: "/usr/local/bin/imsg",

      // Contact filtering
      allowFrom: [
        "contact@example.com",
        "+15555550123"
      ],

      // Message handling
      messages: {
        maxMessageLength: 1000,
        mediaEnabled: true,
        readReceipts: true
      },

      // Group chat support
      groups: {
        enabled: true,
        requireMention: true
      }
    }
  }
}

Agent Configuration

Pi Agent (Default)

{
  agents: {
    default: {
      type: "pi",

      // RPC connection
      rpc: {
        host: "127.0.0.1",
        port: 8080,
        timeout: 30000,
        retries: 3
      },

      // Model configuration
      model: "claude-3.5-sonnet",
      maxTokens: 4096,
      temperature: 0.7,

      // System prompt
      systemPrompt: "You are a helpful AI assistant. Be concise and accurate.",

      // Tool permissions
      tools: {
        fileSystem: {
          enabled: true,
          allowedPaths: ["/workspace", "/tmp"],
          deniedPaths: ["/etc", "/usr/bin"]
        },
        webBrowser: {
          enabled: true,
          allowedDomains: ["*"],
          timeout: 30000
        },
        terminal: {
          enabled: true,
          allowedCommands: ["python", "node", "git", "npm"],
          deniedCommands: ["rm", "sudo", "chmod 777"]
        },
        api: {
          enabled: true,
          timeout: 10000,
          allowedDomains: ["api.github.com", "api.openai.com"]
        }
      },

      // Memory and context
      memory: {
        maxContextLength: 10000,
        retainHistory: true,
        summaryThreshold: 8000
      }
    }
  }
}

Multi-Agent Setup

{
  agents: {
    // Coding specialist
    coding: {
      type: "pi",
      model: "claude-3.5-sonnet",
      systemPrompt: "You are a coding expert. Always provide working code.",
      tools: {
        fileSystem: { enabled: true },
        terminal: { enabled: true }
      }
    },

    // Research specialist
    research: {
      type: "pi",
      model: "gpt-4",
      systemPrompt: "You are a research assistant. Find and summarize information.",
      tools: {
        webBrowser: { enabled: true },
        api: { enabled: true }
      }
    },

    // Chat assistant
    chat: {
      type: "pi",
      model: "claude-3-haiku",
      systemPrompt: "You are a friendly chat assistant.",
      maxTokens: 1000
    }
  },

  // Routing rules
  routing: {
    default: "chat",
    code: "coding",
    research: "research",
    patterns: {
      "\\b(code|program|debug|fix)\\b": "coding",
      "\\b(search|find|research|lookup)\\b": "research"
    }
  }
}

Security Configuration

Authentication

{
  security: {
    // Enable authentication
    authentication: true,

    // Token settings
    tokens: {
      gateway: "gateway-token-here",
      nodes: "node-token-here",
      expiration: "24h"
    },

    // API keys
    apiKeys: {
      anthropic: "your-anthropic-api-key",
      openai: "your-openai-api-key",
      google: "your-google-api-key"
    },

    // Rate limiting
    rateLimit: {
      enabled: true,
      windowMs: 900000, // 15 minutes
      maxRequests: 100,
      skipSuccessfulRequests: false
    }
  }
}

Sandboxing

{
  security: {
    // Agent sandboxing
    sandboxing: {
      enabled: true,
      type: "docker", // or "chroot", "none"

      // Docker sandbox settings
      docker: {
        image: "openclaw/sandbox:latest",
        network: "none",
        readonly: false,
        tmpfs: ["/tmp"],
        volumes: {
          "/workspace": "/workspace"
        },
        limits: {
          memory: "512m",
          cpu: "0.5",
          disk: "1g"
        }
      }
    },

    // File system permissions
    fileSystem: {
      allowedPaths: [
        "~/.openclaw",
        "/tmp",
        "./workspace"
      ],
      deniedPaths: [
        "/etc",
        "/usr/bin",
        "~/.ssh"
      ],
      maxFileSize: "10MB"
    }
  }
}

Logging and Monitoring

Logging Configuration

{
  logging: {
    // Log level
    level: "info", // debug, info, warn, error

    // Log outputs
    outputs: {
      console: {
        enabled: true,
        colorize: true
      },
      file: {
        enabled: true,
        path: "~/.openclaw/logs/gateway.log",
        maxSize: "10MB",
        maxFiles: 5,
        rotation: "daily"
      },
      syslog: {
        enabled: false,
        host: "localhost",
        port: 514
      }
    },

    // Log formatting
    format: {
      timestamp: true,
      level: true,
      component: true,
      requestId: true
    },

    // Component-specific logging
    components: {
      gateway: "info",
      channels: "info",
      agents: "debug",
      security: "warn"
    }
  }
}

Monitoring and Metrics

{
  monitoring: {
    // Metrics collection
    metrics: {
      enabled: true,
      interval: 60000,
      retention: "7d"
    },

    // Health checks
    health: {
      enabled: true,
      endpoint: "/health",
      checks: [
        "database",
        "channels",
        "agents",
        "disk_space",
        "memory"
      ]
    },

    // Performance monitoring
    performance: {
      enabled: true,
      slowQueryThreshold: 1000,
      memoryThreshold: 0.8,
      cpuThreshold: 0.9
    }
  }
}

Advanced Configuration

Multiple Gateways

{
  // Multiple gateway instances
  gateways: {
    primary: {
      port: 18789,
      bind: "127.0.0.1",
      channels: ["whatsapp", "telegram"]
    },
    secondary: {
      port: 19000,
      bind: "127.0.0.1",
      channels: ["discord", "imessage"]
    }
  }
}

Cluster Configuration

{
  cluster: {
    enabled: true,
    mode: "swarm", // or "kubernetes"

    nodes: [
      {
        id: "node-1",
        host: "192.168.1.10",
        port: 18789,
        role: "primary"
      },
      {
        id: "node-2",
        host: "192.168.1.11",
        port: 18789,
        role: "worker"
      }
    ],

    discovery: {
      type: "static", // or "dns", "consul"
      interval: 30000
    }
  }
}

Environment Variables

OpenClaw supports environment variable overrides:

# Gateway settings
export OPENCLAW_PORT=18789
export OPENCLAW_BIND=127.0.0.1
export OPENCLAW_TOKEN=your-token

# Configuration path
export OPENCLAW_CONFIG_PATH=/custom/path/config.json
export OPENCLAW_STATE_DIR=/custom/path/state

# API keys (recommended for security)
export OPENCLAW_ANTHROPIC_API_KEY=your-key
export OPENCLAW_OPENAI_API_KEY=your-key

# Logging
export OPENCLAW_LOG_LEVEL=debug
export OPENCLAW_LOG_FILE=/var/log/openclaw.log

Configuration Validation

Validate Configuration

# Check configuration syntax
openclaw config validate

# Test specific sections
openclaw config validate --section gateway
openclaw config validate --section channels

# Show configuration
openclaw config show
openclaw config show --section agents

Configuration Templates

# Generate template configuration
openclaw config template --output template.json

# Generate for specific use case
openclaw config template --profile production
openclaw config template --profile development

Best Practices

1. Security First

   • Use loopback binding (127.0.0.1)
   • Enable authentication tokens
   • Restrict file system access
   • Use environment variables for API keys

2. Performance

   • Set appropriate connection limits
   • Enable message batching
   • Configure proper timeouts
   • Monitor resource usage

3. Reliability

   • Enable automatic reconnection
   • Configure health checks
   • Set up log rotation
   • Backup configuration regularly

4. Scalability

   • Use multiple gateways for high load
   • Configure clustering for HA
   • Implement proper load balancing
   • Monitor metrics and alerts

Troubleshooting

Common Configuration Issues

Gateway won’t start

# Check configuration syntax
openclaw config validate

# Check port availability
netstat -an | grep 18789

# View startup logs
openclaw gateway logs

Channel connection failures

# Test channel configuration
openclaw channels test whatsapp

# Check credentials
openclaw config show channels.whatsapp.botToken

# Verify network connectivity
ping api.telegram.org

Agent communication errors

# Test agent connection
openclaw agent test

# Check RPC settings
openclaw config show agents.default.rpc

# Verify agent is running
ps aux | grep pi

---

With proper Gateway configuration, your OpenClaw installation will be secure, performant, and reliable! 🚀