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 four top-level sections. Not all sections are present on every instance — sections are included only when relevant.

{
  "gateway": { ... },
  "env": { ... },
  "agents": { ... },
  "channels": { ... }
}

gateway (Always Present)

Controls how the OpenClaw gateway runs and authenticates requests.

{
  "gateway": {
    "mode": "local",
    "trustedProxies": [
      "172.16.0.0/12",
      "10.0.0.0/8",
      "127.0.0.1"
    ],
    "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.

env (Conditional)

Contains API keys for the selected LLM provider. This section is only present if you have configured an LLM.

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-..."
  }
}

Only the relevant key for your provider is included:

If no LLM is configured (instance in "no LLM" mode), this section is omitted entirely.

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"
      }
    }
  }
}

Model string format varies by provider:

Anthropic models are a special case — they do not include the provider prefix in the model string.

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",
    "trustedProxies": ["172.16.0.0/12", "10.0.0.0/8", "127.0.0.1"],
    "auth": {
      "mode": "token",
      "token": "a1b2c3d4..."
    },
    "controlUi": {
      "allowInsecureAuth": true
    }
  }
}

A fully configured instance with Anthropic LLM and Telegram:

{
  "gateway": {
    "mode": "local",
    "trustedProxies": ["172.16.0.0/12", "10.0.0.0/8", "127.0.0.1"],
    "auth": {
      "mode": "token",
      "token": "a1b2c3d4..."
    },
    "controlUi": {
      "allowInsecureAuth": true
    }
  },
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-api03-..."
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "claude-3-haiku"
      }
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "123456789:ABCdef...",
      "dmPolicy": "owner_only",
      "allowFrom": ["*"]
    }
  }
}

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