OpenClaw Configuration Reference

Top-Level Structure

The config file is a single JSON5 object. All top-level keys are optional — OpenClaw applies defaults for anything missing. OpenClaw follows a two-bucket rule: root-level keys hold infrastructure and cross-agent defaults, agents.defaults holds agent-loop behaviour, and agents.entries.<id> overrides either for one agent. The table lists the keys this page covers; OpenClaw's configuration reference has the rest (plugins, tools, browser, TTS and more), and openclaw config schema prints every field.

agents — Model, Skills & Sandbox

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",

      // Primary model + fallbacks ("provider/model" ids — use your provider's current ones)
      model: {
        primary: "anthropic/claude-sonnet-5-5",
        fallbacks: ["openai/gpt-6-sol"]
      },

      // Model allowlist — defines which models users can switch to
      models: {
        "anthropic/claude-sonnet-5-5": { alias: "Sonnet" },
        "anthropic/claude-haiku-4-5": { alias: "Haiku"  },
        "openai/gpt-6-sol":           { alias: "Sol"    }
      },

      // Skills enabled by default for all agents
      skills: ["github", "weather"],   // omit for unrestricted skills

      // Sandbox controls which tools run in isolation
      sandbox: {
        mode: "non-main",  // off (default) | non-main | all
        scope: "agent"     // session | agent (default) | shared
      },

      // Heartbeat: proactive check-ins on a schedule
      heartbeat: {
        every: "30m",      // duration string; "0m" disables the recurring cadence
        target: "owner"    // owner (default) | last | none | a channel id
      }
    },

    // Named agents: an object keyed by agent id (was a "list" array before 2026.9)
    entries: {
      main: {
        workspace: "~/.openclaw/workspace",
        skills: ["github", "docs-search"],   // replaces defaults.skills for this agent
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"]
        }
      },
      work: {
        workspace: "~/.openclaw/workspace-work",
        skills: ["github", "jira"]
      }
    }
  }
}

A per-agent skills list replaces the defaults rather than adding to them, and [] means no skills. A string model on an agent is a strict primary with no fallback; use { primary, fallbacks: [...] } to opt that agent into fallback. The heartbeat object is strict — only its documented fields are accepted.

Sandbox Modes

channels — All Integrations

Every channel uses the same DM access pattern. The key config fields are consistent across all providers:

{
  channels: {
    <provider>: {
      enabled: true,
      dmPolicy:    "pairing",    // pairing | allowlist | open | disabled
      allowFrom:   ["+15555550123"],  // phone numbers, user IDs, or "*"
      groupPolicy: "allowlist",  // open | allowlist (default) | disabled
      groups: {
        "*": { requireMention: true }
      }
    }
  }
}

dmPolicy Values

Telegram

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "${TELEGRAM_BOT_TOKEN}",
      dmPolicy: "pairing",
      allowFrom: ["8734062810"],   // your numeric Telegram user ID
      groupPolicy: "allowlist",
      groups: {
        "-1001234567890": {        // group chat ID (negative number)
          requireMention: true,
          allowFrom: ["8734062810", "745123456"]
        }
      }
    }
  }
}

WhatsApp

{
  channels: {
    whatsapp: {
      enabled: true,
      dmPolicy: "allowlist",
      allowFrom: ["+15555550123"],   // E.164 format
      groupPolicy: "allowlist"
    }
  }
}

Discord

{
  channels: {
    discord: {
      enabled: true,
      botToken: "${DISCORD_BOT_TOKEN}",
      applicationId: "123456789012345678",
      dmPolicy: "allowlist",
      allowFrom: ["your-discord-user-id"]
    }
  }
}

session — Scope & Reset

{
  session: {
    // How conversation history is scoped
    dmScope: "per-channel-peer",
    // Options:
    //   main                — one global session for all DMs
    //   per-peer            — one session per sender (across channels)
    //   per-channel-peer    — one session per sender per channel (recommended)
    //   per-account-channel-peer — adds account-level isolation

    threadBindings: {
      enabled:    true,
      idleHours:  24,   // thread expires after 24h of inactivity
      maxAgeHours: 0    // 0 = no hard limit
    },

    reset: {
      mode:        "daily",  // daily | idle (omit, or "none", for no automatic reset)
      atHour:      4,        // 4 AM local time
      idleMinutes: 120       // reset after 2h of no messages
    }
  }
}

gateway — Server Settings

{
  gateway: {
    port: 18789,
    bind: "loopback",   // default; non-loopback binds need gateway auth — keep it off public interfaces on a VPS

    auth: {
      token: "${OPENCLAW_GATEWAY_TOKEN}"
    },

    reload: {
      mode: "hybrid"   // hybrid (default) | off
    }
  },

  // Health-monitor restarts can be switched off per channel or per account
  channels: {
    telegram: { healthMonitor: { enabled: true } }
  }
}

Reload Modes

cron — Automations

The cron block sets global behaviour for scheduled automations, including the heartbeat. It is strict. Per OpenClaw's config reference, the only accepted keys are enabled, skipMissedJobs, triggers, webhookToken, webhookSsrfPolicy, sessionRetention and failureAlert. Anything else fails validation.

{
  cron: {
    enabled: true,              // false pauses all automation execution (jobs are kept)
    skipMissedJobs: false,      // true: skip missed recurring slots at startup
    triggers: { enabled: true },// event-driven triggers
    sessionRetention: "24h",    // how long completed isolated run sessions are kept ("0h" or false to disable)
    failureAlert: { enabled: false, after: 2 }
  }
}

Individual jobs aren't defined in config. Create them with the CLI, for example openclaw automations create "0 7 * * *" "Send me a morning brief" --name "Morning brief" --session isolated, and list them with openclaw automations list --all.

Correction 2026-09-27: an earlier version of this section showed maxConcurrentRuns and runLog. They are not accepted keys, and pasting them breaks validation. It also said jobs are defined in HEARTBEAT.md.

env — Secrets & Environment Variables

{
  env: {
    // Inline values — only applied if the process environment is missing the key
    vars: {
      OPENROUTER_API_KEY: "sk-or-...",
      GROQ_API_KEY: "gsk-..."
    },

    // Import from shell environment (most secure)
    shellEnv: {
      enabled:   true,
      timeoutMs: 15000
    }
  }
}

Reference env vars anywhere in the config with "${VAR_NAME}". Only uppercase names are supported. A missing or empty variable stays unresolved and logs a warning, and any setting that requires the value fails at startup or reload; add a fallback with "${VAR_NAME:-fallback}". Use openclaw doctor to diagnose.

Multi-Agent Routing

Route different channels or accounts to different agents using bindings:

{
  agents: {
    ownership: "explicit",
    // "default: true" is retired — name the agent that owns heartbeats and system work instead
    defaults: { heartbeat: { agentId: "home" }, systemAgent: { agentId: "home" } },
    entries: {
      home: { workspace: "~/.openclaw/workspace-home" },
      work: { workspace: "~/.openclaw/workspace-work" }
    }
  },
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
    { agentId: "work", match: { channel: "telegram", accountId: "*" } }
  ]
}

Bindings resolve in a fixed order: a specific match.peer first, then guildId, then teamId, then an exact accountId, then accountId: "*" (channel-wide). Within a tier the first matching binding wins. With more than one agent configured, a message that matches no binding is refused — only a single-agent setup falls back automatically — so add a channel-wide binding for anything you want answered.

Config Includes — Split Into Multiple Files

Large configs can be split across files using $include:

// ~/.openclaw/openclaw.json
{
  agents:    { $include: "./agents.json5"                              },
  channels:  { $include: "./channels.json5"                            },
  broadcast: { $include: ["./clients/a.json5", "./clients/b.json5"]   }
}

A single file replaces the object it is assigned to. An array of files deep-merges in order, later files overriding earlier ones, and sibling keys are merged after the includes. This lets you keep Telegram credentials in a separate file with tighter filesystem permissions.