OpenClaw Configuration Reference

What openclaw.json Does

The openclaw.json file is the main configuration file for your OpenClaw instance. It controls how the gateway authenticates users, which LLM provider to use, and which messenger channels are active.

ClawHosters generates this file automatically based on your dashboard settings. When you change your LLM provider, add a Telegram bot, or update any other setting, ClawHosters regenerates the config and deploys it to your instance.

You do not need to edit this file manually unless you SSH into your instance for advanced configuration.

File Location

On your instance, the config file is stored at:

/root/.openclaw/openclaw.json

This is a bind-mount from /opt/openclaw/dotopenclaw/openclaw.json on the host system. Changes to either path affect the same file.

Config Structure

The file is a JSON object with up to five top-level sections. Not all sections are present on every instance. Sections are included only when relevant.

{
  "gateway": { ... },
  "commands": { ... },
  "models": { ... },
  "agents": { ... },
  "channels": { ... }
}

Note: API keys are NOT stored in openclaw.json. They are passed as Docker environment variables via the .env file. See Environment Variables for details.

gateway (Always Present)

Controls how the OpenClaw gateway runs and authenticates requests.

{
  "gateway": {
    "mode": "local",
    "auth": {
      "mode": "token",
      "token": "sha256-hashed-token"
    },
    "controlUi": {
      "allowInsecureAuth": true
    }
  }
}

The gateway section is always generated, even on instances without any LLM or messenger configured.

commands (Conditional)

Enables built-in commands for the OpenClaw instance. Currently supports the restart command.

{
  "commands": {
    "restart": true
  }
}

agents (Conditional)

Specifies the default LLM model for the instance. Only present when an LLM is configured.

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-3-haiku"
      }
    }
  }
}

All models use the provider/model-name format:

channels (Conditional)

Configures messenger integrations. Each channel is only included if it has been set up in your dashboard.

Telegram

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
      "dmPolicy": "owner_only",
      "allowFrom": ["*"]
    }
  }
}

Discord

{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "bot-token-here",
      "dm": {
        "enabled": true,
        "policy": "pairing",
        "allowFrom": ["*"]
      }
    }
  }
}

Slack

{
  "channels": {
    "slack": {
      "enabled": true,
      "botToken": "xoxb-...",
      "appToken": "xapp-..."
    }
  }
}

WhatsApp

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "dmPolicy": "owner_only"
    }
  }
}

Minimal vs Full Example

A freshly created instance with no LLM or messengers configured has only the gateway section:

{
  "gateway": {
    "mode": "local",
    "auth": {
      "mode": "token",
      "token": "a1b2c3d4..."
    },
    "controlUi": {
      "allowInsecureAuth": true
    }
  }
}

A fully configured instance with Anthropic LLM and Telegram:

{
  "gateway": {
    "mode": "local",
    "auth": {
      "mode": "token",
      "token": "a1b2c3d4..."
    },
    "controlUi": {
      "allowInsecureAuth": true
    }
  },
  "commands": {
    "restart": true
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-3-haiku"
      }
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "123456789:ABCdef...",
      "dmPolicy": "owner_only",
      "allowFrom": ["*"]
    }
  }
}

Note: The Anthropic API key is passed as the ANTHROPIC_API_KEY Docker environment variable, not in this file.

How Config Changes Are Applied

When you update settings in your dashboard:

1. ClawHosters regenerates openclaw.json with your new settings
2. The file is uploaded to your instance via SCP
3. The doctor --fix command runs to apply plugin changes
4. Your instance picks up the new configuration

This process takes a few seconds. During the update, your instance stays running. There is no downtime for config changes.

Manual Editing via SSH

If you SSH into your instance, you can view the config at /root/.openclaw/openclaw.json. You can edit it manually, but be aware:

• Dashboard setting changes will overwrite your manual edits
• Invalid JSON will prevent the gateway from starting
• Missing the gateway section will break authentication

If you break the config, use the "Redeploy" button in your dashboard to regenerate it from your saved settings.

Related Documentation

• SSH Access: How to connect to your instance
• Connecting Telegram: Setting up Telegram
• LLM Add-on: Configuring LLM providers
• Rebuilding an Instance: Factory reset if config is broken