OpenClaw Gateway Configuration Complete Guide

Introduction

If you are new to OpenClaw, you might wonder how it connects various chat applications with AI models. The answer lies in the Gateway — the core component. The official documentation positions OpenClaw as a "Gateway network connecting chat applications with programming agents," and the Gateway is the hub of this network.

This article starts with the Gateway's core concepts and provides a detailed guide to configuration methods, startup parameters, and key settings for practical use.

What Is the Gateway?

The Gateway is OpenClaw's core architectural layer. All message sending, receiving, routing, and forwarding goes through it. Think of it as a "message relay station":

Chat Applications (WhatsApp / Telegram / Discord / ...)
        ↕
   OpenClaw Gateway (single process, multi-channel)
        ↕
   AI Models (Claude / GPT / Ollama / ...)

The Gateway's design philosophy is single process, multi-channel — you only need to start one Gateway process to manage all chat channel connections simultaneously. This means simple deployment, low resource usage, and flexible scalability.

Configuration File Location

The Gateway configuration is written in OpenClaw's main configuration file. Default paths are as follows:

Platform	Path
Linux / macOS	`~/.config/openclaw/openclaw.json5`
Windows	`%USERPROFILE%\.config\openclaw\openclaw.json5`
Docker	`/app/config/openclaw.json5`

You can also customize the path via an environment variable:

export OPENCLAW_CONFIG=/path/to/your/openclaw.json5

Gateway Core Configuration

Edit the gateway section in the configuration file. Here is a complete configuration example:

{
  gateway: {
    // Listening port, default 18789
    port: 18789,

    // Listening address
    // "127.0.0.1" — localhost only (recommended for development)
    // "0.0.0.0" — allow all network access (use with firewall in production)
    host: "0.0.0.0",

    // Dashboard access password
    dashboardPassword: "your-strong-password",

    // API key (for external systems calling OpenClaw API)
    apiKey: "your-api-key",

    // Request timeout (milliseconds), default 120 seconds
    timeout: 120000,

    // Maximum request body size, controls media file upload limit
    maxBodySize: "10mb",

    // CORS cross-origin settings
    cors: {
      enabled: true,
      origins: ["*"],
    },
  },
}

Parameter Quick Reference

Parameter	Type	Default	Description
`port`	number	18789	Gateway listening port
`host`	string	"127.0.0.1"	Listening address
`dashboardPassword`	string	none	Dashboard login password
`apiKey`	string	none	API authentication key
`timeout`	number	120000	Request timeout (ms)
`maxBodySize`	string	"10mb"	Maximum request body size

Starting the Gateway

After configuration, start the Gateway with:

openclaw gateway --port 18789

If the port is already set in the configuration file, you can also use the shorthand:

openclaw up

To run in the background:

openclaw up -d

Once started, the Gateway will begin listening on the specified port and automatically connect to all enabled channels.

Access Control

In production environments, access control is essential. OpenClaw provides multiple layers of security mechanisms.

IP Whitelist and Blacklist

Restrict accessible IP addresses through the security configuration section:

{
  security: {
    // Only allow the following IPs (leave empty for no restriction)
    ipWhitelist: [
      "192.168.1.0/24",
      "10.0.0.5",
    ],

    // Block specific IPs
    ipBlacklist: [
      "203.0.113.50",
    ],

    // Request rate limiting
    rateLimit: {
      enabled: true,
      maxRequests: 60,
      windowMs: 60000,
    },
  },
}

Channel-Level User Restrictions

Each channel can also have its own allowed users or groups. Using Telegram as an example:

{
  channels: {
    telegram: {
      enabled: true,
      token: "your-bot-token",
      // Only allow these user IDs
      allowedUsers: [12345678, 87654321],
      // Only allow these groups
      allowedGroups: [-100123456789],
    },
  },
}

This dual control (Gateway-level + channel-level) gives you fine-grained management over who can access the AI service.

Multi-Channel Routing

A key feature of the Gateway is its plugin-based channel extensions. Each chat platform integration is an independent channel plugin, and the Gateway handles unified management and message routing.

{
  channels: {
    whatsapp: {
      enabled: true,
      phoneNumber: "+86138xxxx",
      responseMode: "all",
    },

    telegram: {
      enabled: true,
      token: "your-bot-token",
      responseMode: "mention",
    },

    discord: {
      enabled: true,
      token: "your-discord-token",
      responseMode: "mention",
      allowedChannels: ["general", "ai-chat"],
    },
  },
}

Each channel can have a different response mode:

"all": Reply to all messages
"mention": Reply only when @mentioned

Multi-Agent Routing and Session Isolation

When you have multiple AI models configured, the Gateway supports rule-based multi-agent routing. Different channels can route to different models, and each channel's conversation context is isolated by default.

{
  context: {
    // Isolation strategy
    // "channel" — isolate by channel (default, recommended)
    // "user" — isolate by user (same user shares context across channels)
    // "global" — global sharing
    isolation: "channel",

    // Context window size
    maxMessages: 50,

    // Context expiration time (seconds)
    ttl: 3600,
  },
}

The session isolation mechanism ensures that conversations across different channels do not interfere with each other. For example, conversations on Telegram will not leak into Discord, and vice versa.

Media Support

The Gateway has built-in support for multiple media types, including images, audio, and documents. When a user sends an image in a chat, the Gateway passes it to a model with vision capabilities for processing.

You can control the maximum upload file size by adjusting the maxBodySize parameter:

{
  gateway: {
    // Increase if you need to handle large files
    maxBodySize: "25mb",
  },
}

Web Dashboard

The Gateway includes a built-in Web Dashboard for monitoring and managing the service from your browser:

openclaw dashboard

The Dashboard provides the following features:

View real-time connection status of each channel
Monitor message sending/receiving statistics
View model call counts and token consumption
Real-time log stream viewing

Accessing the Dashboard requires the password set in dashboardPassword. If no password is set, it is strongly recommended to add one in production environments.

Configuration Validation and Troubleshooting

After modifying the Gateway configuration, it is recommended to validate the configuration file first:

# Run diagnostics to check configuration and component status
openclaw doctor

# Validate configuration file syntax only
openclaw doctor --config-only

If the Gateway has issues after startup, check the logs for troubleshooting:

# View real-time logs
openclaw logs

# View logs for a specific channel
openclaw logs --channel telegram

Conclusion

The Gateway is the central hub of OpenClaw. Understanding how it works will help you better deploy and manage your AI chat services. Key takeaways:

Single Process, Multi-Channel: One Gateway process manages all chat platform connections
Centralized Configuration: All settings are managed in a single openclaw.json5 file
Layered Security: Dual access control at both the Gateway and channel levels
Session Isolation: Conversation contexts across channels are independent by default
Plugin Extensions: Flexibly connect new chat platforms through the plugin mechanism

It is recommended to start with a minimal configuration, get one channel working first, and then gradually add more channels and advanced settings.