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.

Validate before restart

Run openclaw doctor before gateway restart. Keep dated backups—tokens and model IDs break easily. Official fields: docs.openclaw.ai.

Diff before deploy

Keep config in git (private repo) and diff before restart. Breaking changes often hit channels.* or agent.model—roll back one field at a time if doctor output is unclear.

See also