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
• Feishu — channels.feishu
• Google Chat — channels.googlechat
• Microsoft Teams — channels.msteams
• Slack — channels.slack
• Signal — channels.signal
• iMessage — channels.imessage
• Mattermost — channels.mattermost

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-6",
        fallbacks: ["openai/gpt-5.4"],
      },
      models: {
        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
        "openai/gpt-5.4": { 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).
• agents.defaults.imageMaxDimensionPx controls transcript/tool image downscaling (default 1200); lower values usually reduce vision-token usage on screenshot-heavy runs.
• 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: safe regex patterns in mentionPatterns
• See full reference for per-channel overrides and self-chat mode.

Use agents.defaults.skills for a shared baseline, then override specific agents with agents.list[].skills:

{
  agents: {
    defaults: {
      skills: ["github", "weather"],
    },
    list: [
      { id: "writer" }, // inherits github, weather
      { id: "docs", skills: ["docs-search"] }, // replaces defaults
      { id: "locked-down", skills: [] }, // no skills
    ],
  },
}

• Omit agents.defaults.skills for unrestricted skills by default.
• Omit agents.list[].skills to inherit the defaults.
• Set agents.list[].skills: [] for no skills.
• See Skills, Skills config, and the Configuration Reference.

Control how aggressively the gateway restarts channels that look stale:

{
  gateway: {
    channelHealthCheckMinutes: 5,
    channelStaleEventThresholdMinutes: 30,
    channelMaxRestartsPerHour: 10,
  },
  channels: {
    telegram: {
      healthMonitor: { enabled: false },
      accounts: {
        alerts: {
          healthMonitor: { enabled: true },
        },
      },
    },
  },
}

• Set gateway.channelHealthCheckMinutes: 0 to disable health-monitor restarts globally.
• channelStaleEventThresholdMinutes should be greater than or equal to the check interval.
• Use channels.<provider>.healthMonitor.enabled or channels.<provider>.accounts.<id>.healthMonitor.enabled to disable auto-restarts for one channel or account without disabling the global monitor.
• See Health Checks for operational debugging and the full reference for all fields.

Sessions control conversation continuity and isolation:

{
  session: {
    dmScope: "per-channel-peer",  // recommended for multi-user
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 120,
    },
  },
}

• dmScope: main (shared) | per-peer | per-channel-peer | per-account-channel-peer
• threadBindings: global defaults for thread-bound session routing (Discord supports /focus, /unfocus, /agents, /session idle, and /session max-age).
• 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.

Relay-backed push is configured in openclaw.json.

Set this in gateway config:

{
  gateway: {
    push: {
      apns: {
        relay: {
          baseUrl: "https://relay.example.com",
          // Optional. Default: 10000
          timeoutMs: 10000,
        },
      },
    },
  },
}

CLI equivalent:

openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com

What this does:

• Lets the gateway send push.test, wake nudges, and reconnect wakes through the external relay.
• Uses a registration-scoped send grant forwarded by the paired iOS app. The gateway does not need a deployment-wide relay token.
• Binds each relay-backed registration to the gateway identity that the iOS app paired with, so another gateway cannot reuse the stored registration.
• Keeps local/manual iOS builds on direct APNs. Relay-backed sends apply only to official distributed builds that registered through the relay.
• Must match the relay base URL baked into the official/TestFlight iOS build, so registration and send traffic reach the same relay deployment.

End-to-end flow:

1. Install an official/TestFlight iOS build that was compiled with the same relay base URL.
2. Configure gateway.push.apns.relay.baseUrl on the gateway.
3. Pair the iOS app to the gateway and let both node and operator sessions connect.
4. The iOS app fetches the gateway identity, registers with the relay using App Attest plus the app receipt, and then publishes the relay-backed push.apns.register payload to the paired gateway.
5. The gateway stores the relay handle and send grant, then uses them for push.test, wake nudges, and reconnect wakes.

Operational notes:

• If you switch the iOS app to a different gateway, reconnect the app so it can publish a new relay registration bound to that gateway.
• If you ship a new iOS build that points at a different relay deployment, the app refreshes its cached relay registration instead of reusing the old relay origin.

Compatibility note:

• OPENCLAW_APNS_RELAY_BASE_URL and OPENCLAW_APNS_RELAY_TIMEOUT_MS still work as temporary env overrides.
• OPENCLAW_APNS_RELAY_ALLOW_HTTP=true remains a loopback-only development escape hatch; do not persist HTTP relay URLs in config.

See iOS App for the end-to-end flow and Authentication and trust flow for the relay security model.

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

• every: duration string (30m, 2h). Set 0m to disable.
• target: last | none | <channel-id> (for example discord, matrix, telegram, or whatsapp)
• directPolicy: allow (default) or block for DM-style heartbeat targets
• See Heartbeat for the full guide.

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
    sessionRetention: "24h",
    runLog: {
      maxBytes: "2mb",
      keepLines: 2000,
    },
  },
}

• sessionRetention: prune completed isolated run sessions from sessions.json (default 24h; set false to disable).
• runLog: prune cron/runs/<jobId>.jsonl by size and retained lines.
• See Cron jobs for 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,
      },
    ],
  },
}

Security note:

• Treat all hook/webhook payload content as untrusted input.
• Use a dedicated hooks.token; do not reuse the shared Gateway token.
• Hook auth is header-only (Authorization: Bearer ... or x-openclaw-token); query-string tokens are rejected.
• hooks.path cannot be /; keep webhook ingress on a dedicated subpath such as /hooks.
• Keep unsafe-content bypass flags disabled (hooks.gmail.allowUnsafeExternalContent, hooks.mappings[].allowUnsafeExternalContent) unless doing tightly scoped debugging.
• If you enable hooks.allowRequestSessionKey, also set hooks.allowedSessionKeyPrefixes to bound caller-selected session keys.
• For hook-driven agents, prefer strong modern model tiers and strict tool policy (for example messaging-only plus sandboxing where possible).

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)

Restart requests are coalesced while one is already pending/in-flight, and a 30-second cooldown applies between restart cycles.

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:direct:+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

Restart behavior matches config.apply: coalesced pending restarts plus a 30-second cooldown between restart cycles.

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