OpenClaw Gateway Configuration: A Complete Guide

Understanding how to configure the OpenClaw Gateway is essential for customizing your setup, enhancing security, and automating tasks. While openclaw onboard provides an interactive wizard for initial setup, the underlying configuration file—~/.openclaw/openclaw.json—holds the full power to tailor your Gateway's behavior.

This guide will walk you through the configuration system, from basic edits to advanced patterns like multi-agent routing and programmatic updates.

The Configuration File

OpenClaw uses a JSON5 configuration file located at ~/.openclaw/openclaw.json. JSON5 is chosen because it supports comments and trailing commas, making manual editing safer and more readable. If this file does not exist, OpenClaw will use sensible defaults and operate securely.

The primary reasons to create or modify this file include:

• Restricting access to your agent (e.g., allowing messages only from specific numbers)
• Adding or changing AI models
• Setting up automation like cron jobs and webhooks
• Configuring multi-agent routing for home and work environments
• Enabling Docker-based sandboxing for security

Editing Your Configuration

You have several ways to edit your configuration:

1. Interactive Wizard: Run openclaw onboard or openclaw configure for a guided experience.
2. CLI Commands: Use one-liners like openclaw config set agents.defaults.model.primary anthropic/claude-sonnet-4-5.
3. Control UI: Access the dashboard at http://127.0.0.1:18789 and navigate to the Config tab.
4. Direct Edit: Manually edit ~/.openclaw/openclaw.json. The Gateway watches this file and applies changes automatically in most cases.

Regardless of your method, remember that OpenClaw enforces strict schema validation. Invalid JSON, unknown keys, or incorrect types will prevent the Gateway from starting. Use openclaw doctor to diagnose and fix issues.

Core Configuration Tasks

Securing Access

Control which users can interact with your agent via dmPolicy in your channel configuration:

• pairing (default): Users must be approved via a one-time code
• allowlist: Only users in the allowFrom array are permitted
• open: All users can message the bot
• disabled: No one can message the bot

For example, to allow only your number on WhatsApp:

{
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15555550123"]
    }
  }
}

Setting Your AI Model

Choose your primary and fallback models under agents.defaults.model:

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["openai/gpt-5.2"]
      }
    }
  }
}

You can also define model aliases and parameters. Built-in alias shorthands include opus, sonnet, gpt, and gpt-mini, which map to their respective models.

Enabling Automation

Turn on cron jobs and set their behavior:

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2
  }
}

Similarly, configure webhooks to listen for external events:

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks"
  }
}

Multi-Agent Routing

Run multiple isolated agents by defining a list and routing rules:

{
  agents: {
    list: [
      { id: "home", workspace: "~/.openclaw/workspace-home" },
      { id: "work", workspace: "~/.openclaw/workspace-work" }
    ]
  },
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } }
  ]
}

This setup allows different configurations and access policies for personal and professional use.

Hot Reload and Restart Behavior

Most configuration changes apply without restarting the Gateway. Settings like channel configuration, model selection, and session management hot-reload instantly.

However, changes to core server settings—such as gateway.port or gateway.auth.token—require a restart. In hybrid mode (the default), the Gateway handles this automatically.

Programmatic Updates

You can update the configuration programmatically using RPC calls:

• config.patch: Merges a partial update into the existing config
• config.apply: Replaces the entire config (requires the current config hash for safety)

For example, to patch a setting:

openclaw gateway call config.patch --params '{
  "raw": "{ channels: { telegram: { groups: { \"*\": { requireMention: false } } } } }",
  "baseHash": "$(openclaw gateway call config.get --params {} | jq -r .payload.hash)"
}'

This is useful for scripts and automation tools that manage OpenClaw instances.

Final Thoughts

The OpenClaw configuration system is designed to be both accessible for beginners and powerful enough for advanced users. Start with the interactive wizard, then dive into the JSON5 file as your needs grow. Always validate your changes with openclaw doctor, and use version control to track your configuration history.

With the right setup, your OpenClaw Gateway becomes a secure, automated, and personalized hub for your AI agents.