Each channel has its own config section under channels.<provider>. See the dedicated channel page for setup steps:

• WhatsApp — channels.whatsapp
• Telegram — channels.telegram
• Discord — channels.discord
• Slack — channels.slack
• Signal — channels.signal
• iMessage — channels.imessage
• Google Chat — channels.googlechat
• Mattermost — channels.mattermost
• MS Teams — channels.msteams

All channels share the same DM policy pattern:

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",   // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"], // only for allowlist/open
    },
  },
}

Set the primary model and optional fallbacks:

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["openai/gpt-5.2"],
      },
      models: {
        "anthropic/claude-sonnet-4-5": { alias: "Sonnet" },
        "openai/gpt-5.2": { alias: "GPT" },
      },
    },
  },
}

• agents.defaults.models defines the model catalog and acts as the allowlist for /model.
• Model refs use provider/model format (e.g. anthropic/claude-opus-4-6).
• See Models CLI for switching models in chat and Model Failover for auth rotation and fallback behavior.
• For custom/self-hosted providers, see Custom providers in the reference.

DM access is controlled per channel via dmPolicy:

• "pairing" (default): unknown senders get a one-time pairing code to approve
• "allowlist": only senders in allowFrom (or the paired allow store)
• "open": allow all inbound DMs (requires allowFrom: ["*"])
• "disabled": ignore all DMs

For groups, use groupPolicy + groupAllowFrom or channel-specific allowlists.

See the full reference for per-channel details.

Group messages default to require mention. Configure patterns per agent:

{
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"],
        },
      },
    ],
  },
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}

• Metadata mentions: native @-mentions (WhatsApp tap-to-mention, Telegram @bot, etc.)
• Text patterns: regex patterns in mentionPatterns
• See full reference for per-channel overrides and self-chat mode.

Sessions control conversation continuity and isolation:

{
  session: {
    dmScope: "per-channel-peer",  // recommended for multi-user
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 120,
    },
  },
}

• dmScope: main (shared) | per-peer | per-channel-peer | per-account-channel-peer
• See Session Management for scoping, identity links, and send policy.
• See full reference for all fields.

Run agent sessions in isolated Docker containers:

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",  // off | non-main | all
        scope: "agent",    // session | agent | shared
      },
    },
  },
}

Build the image first: scripts/sandbox-setup.sh

See Sandboxing for the full guide and full reference for all options.

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
      },
    },
  },
}

• every: duration string (30m, 2h). Set 0m to disable.
• target: last | whatsapp | telegram | discord | none
• See Heartbeat for the full guide.

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
    sessionRetention: "24h",
  },
}

See Cron jobs for the feature overview and CLI examples.

Enable HTTP webhook endpoints on the Gateway:

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    defaultSessionKey: "hook:ingress",
    allowRequestSessionKey: false,
    allowedSessionKeyPrefixes: ["hook:"],
    mappings: [
      {
        match: { path: "gmail" },
        action: "agent",
        agentId: "main",
        deliver: true,
      },
    ],
  },
}

See full reference for all mapping options and Gmail integration.

Run multiple isolated agents with separate workspaces and sessions:

{
  agents: {
    list: [
      { id: "home", default: true, workspace: "~/.openclaw/workspace-home" },
      { id: "work", workspace: "~/.openclaw/workspace-work" },
    ],
  },
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
  ],
}

See Multi-Agent and full reference for binding rules and per-agent access profiles.

Use $include to organize large configs:

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

• Single file: replaces the containing object
• Array of files: deep-merged in order (later wins)
• Sibling keys: merged after includes (override included values)
• Nested includes: supported up to 10 levels deep
• Relative paths: resolved relative to the including file
• Error handling: clear errors for missing files, parse errors, and circular includes

Validates + writes the full config and restarts the Gateway in one step.

Params:

• raw (string) — JSON5 payload for the entire config
• baseHash (optional) — config hash from config.get (required when config exists)
• sessionKey (optional) — session key for the post-restart wake-up ping
• note (optional) — note for the restart sentinel
• restartDelayMs (optional) — delay before restart (default 2000)

openclaw gateway call config.get --params '{}'  # capture payload.hash
openclaw gateway call config.apply --params '{
  "raw": "{ agents: { defaults: { workspace: \"~/.openclaw/workspace\" } } }",
  "baseHash": "<hash>",
  "sessionKey": "agent:main:whatsapp:dm:+15555550123"
}'

Merges a partial update into the existing config (JSON merge patch semantics):

• Objects merge recursively
• null deletes a key
• Arrays replace

Params:

• raw (string) — JSON5 with just the keys to change
• baseHash (required) — config hash from config.get
• sessionKey, note, restartDelayMs — same as config.apply

openclaw gateway call config.patch --params '{
  "raw": "{ channels: { telegram: { groups: { \"*\": { requireMention: false } } } } }",
  "baseHash": "<hash>"
}'