Configuration Reference

Config file location, schema overview, and key sections

OpenClaw reads a single JSON config file. This page summarizes file location, main sections, and common keys. For setup guidance, see the Configuration Guide. For secrets and env vars, see Secrets and Environment Variables.

Config File Location

  • Default (newer): ~/.openclaw/openclaw.json
  • Workspace: ~/.openclaw/workspace (or agents.defaults.workspace)
  • Legacy: Older installs may use ~/.clawdbot/ or ~/clawd—migrate to ~/.openclaw/ per official migration

Override with OPENCLAW_CONFIG. Restart the Gateway after editing.

Main Sections

  • agent — Model (agent.model), provider, baseUrl, failover, thinking depth
  • agents.defaults — Workspace path, sandbox mode, session behaviour
  • channels — Discord, Slack, Telegram, WhatsApp, etc.; DM policy, allowFrom
  • gateway — Port, bind, auth (token/password), Tailscale
  • skills — enabled list, per-skill settings (API keys)
  • browser — Browser automation enable/disable, color

Example Structure

Config structure
{
  "agent": {
    "model": "anthropic/claude-opus-4-6",
    "fallback": ["anthropic/claude-sonnet"]
  },
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace",
      "sandbox": { "mode": "non-main" }
    }
  },
  "gateway": {
    "port": 18789,
    "bind": "127.0.0.1",
    "auth": { "mode": "token" }
  },
  "skills": {
    "enabled": ["caldav", "slack"],
    "caldav": { "calendarUrl": "..." }
  },
  "channels": {
    "discord": { "dm": { "allowFrom": [] } }
  }
}

Full Schema

The complete schema is maintained in the OpenClaw source and documented at docs.openclaw.ai. Use openclaw doctor to validate your config and surface issues.

See also