Configuratie

Elk kanaal heeft zijn eigen configuratiesectie onder channels.<provider>. Zie de speciale kanaalpagina voor installatiestappen:

• 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

Alle kanalen delen hetzelfde DM-beleidspatroon:

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

Stel het primaire model en optionele fallbacks in:

{  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 definieert de modelcatalogus en fungeert als de allowlist voor /model; provider/*-items filteren /model, /models en modelkiezers tot geselecteerde providers, terwijl ze nog steeds dynamische modelontdekking gebruiken.
• Gebruik openclaw config set agents.defaults.models '<json>' --strict-json --merge om allowlist-items toe te voegen zonder bestaande modellen te verwijderen. Gewone vervangingen die items zouden verwijderen, worden geweigerd tenzij je --replace doorgeeft.
• Modelverwijzingen gebruiken de indeling provider/model (bijv. anthropic/claude-opus-4-6).
• agents.defaults.imageMaxDimensionPx regelt het verkleinen van transcript-/toolafbeeldingen (standaard 1200); lagere waarden verminderen meestal het gebruik van vision-tokens bij runs met veel screenshots.
• Zie Models CLI voor het wisselen van modellen in chat en Model Failover voor auth-rotatie en fallback-gedrag.
• Voor aangepaste/zelf gehoste providers, zie Aangepaste providers in de referentie.

DM-toegang wordt per kanaal beheerd via dmPolicy:

• "pairing" (standaard): onbekende afzenders krijgen een eenmalige koppelcode om goed te keuren
• "allowlist": alleen afzenders in allowFrom (of de gekoppelde allow-store)
• "open": alle inkomende DM's toestaan (vereist allowFrom: ["*"])
• "disabled": alle DM's negeren

Gebruik voor groepen groupPolicy + groupAllowFrom of kanaalspecifieke allowlists.

Zie de volledige referentie voor details per kanaal.

Groepsberichten vereisen standaard een vermelding. Configureer triggerpatronen per agent, en houd zichtbare kamerantwoorden op het standaard bericht-toolpad tenzij je bewust oude automatische eindantwoorden wilt:

{  messages: {    visibleReplies: "automatic", // set "message_tool" to require message-tool sends everywhere    groupChat: {      visibleReplies: "message_tool", // default; use "automatic" for legacy room replies    },  },  agents: {    list: [      {        id: "main",        groupChat: {          mentionPatterns: ["@openclaw", "openclaw"],        },      },    ],  },  channels: {    whatsapp: {      groups: { "*": { requireMention: true } },    },  },}

• Metadatavermeldingen: native @-vermeldingen (WhatsApp tik-om-te-vermelden, Telegram @bot, enz.)
• Tekstpatronen: veilige regex-patronen in mentionPatterns
• Zichtbare antwoorden: messages.visibleReplies kan bericht-toolverzendingen globaal vereisen; messages.groupChat.visibleReplies overschrijft dat voor groepen/kanalen.
• Zie volledige referentie voor modi voor zichtbare antwoorden, overschrijvingen per kanaal en zelfchatmodus.

Gebruik agents.defaults.skills voor een gedeelde basislijn en overschrijf daarna specifieke agenten met 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    ],  },}

• Laat agents.defaults.skills weg voor standaard onbeperkte Skills.
• Laat agents.list[].skills weg om de standaardwaarden te erven.
• Stel agents.list[].skills: [] in voor geen Skills.
• Zie Skills, Skills-configuratie en de Configuratiereferentie.

Bepaal hoe agressief de gateway kanalen herstart die verouderd lijken:

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

• Stel gateway.channelHealthCheckMinutes: 0 in om health-monitor-herstarts globaal uit te schakelen.
• channelStaleEventThresholdMinutes moet groter zijn dan of gelijk zijn aan het controle-interval.
• Gebruik channels.<provider>.healthMonitor.enabled of channels.<provider>.accounts.<id>.healthMonitor.enabled om automatische herstarts voor één kanaal of account uit te schakelen zonder de globale monitor uit te schakelen.
• Zie Health Checks voor operationeel debuggen en de volledige referentie voor alle velden.

Geef lokale clients meer tijd om de pre-auth WebSocket-handshake te voltooien op belaste of energiezuinige hosts:

{  gateway: {    handshakeTimeoutMs: 30000,  },}

• Standaard is 15000 milliseconden.
• OPENCLAW_HANDSHAKE_TIMEOUT_MS heeft nog steeds voorrang voor eenmalige service- of shell-overschrijvingen.
• Los bij voorkeur eerst startup-/event-loop-stalls op; deze knop is bedoeld voor hosts die gezond zijn maar traag tijdens het opwarmen.

Sessies regelen gesprekscontinuiteit en isolatie:

{  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 (gedeeld) | per-peer | per-channel-peer | per-account-channel-peer
• threadBindings: globale standaardwaarden voor sessieroutering die aan threads is gebonden (Discord ondersteunt /focus, /unfocus, /agents, /session idle en /session max-age).
• Zie Sessiebeheer voor scoping, identiteitskoppelingen en verzendbeleid.
• Zie volledige referentie voor alle velden.

Voer agentsessies uit in geisoleerde sandboxruntimes:

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

Bouw eerst de image - voer vanuit een broncheckout scripts/sandbox-setup.sh uit, of zie vanuit een npm-installatie de inline docker build-opdracht in Sandboxing § Images en installatie.

Zie Sandboxing voor de volledige handleiding en volledige referentie voor alle opties.

Relay-ondersteunde push wordt geconfigureerd in openclaw.json.

Stel dit in de gatewayconfiguratie in:

{  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

Wat dit doet:

• Laat de gateway push.test, wake-nudges en reconnect-wakes via de externe relay verzenden.
• Gebruikt een registratie-gebonden verzendmachtiging die door de gekoppelde iOS-app wordt doorgestuurd. De gateway heeft geen implementatiebrede relay-token nodig.
• Bindt elke relay-ondersteunde registratie aan de gatewayidentiteit waarmee de iOS-app is gekoppeld, zodat een andere gateway de opgeslagen registratie niet opnieuw kan gebruiken.
• Houdt lokale/handmatige iOS-builds op directe APNs. Relay-ondersteunde verzendingen gelden alleen voor officieel gedistribueerde builds die via de relay zijn geregistreerd.
• Moet overeenkomen met de relay-basis-URL die in de officiele/TestFlight iOS-build is ingebakken, zodat registratie- en verzendverkeer dezelfde relay-implementatie bereiken.

End-to-end-flow:

1. Installeer een officiele/TestFlight iOS-build die met dezelfde relay-basis-URL is gecompileerd.
2. Configureer gateway.push.apns.relay.baseUrl op de gateway.
3. Koppel de iOS-app aan de gateway en laat zowel node- als operatorsessies verbinding maken.
4. De iOS-app haalt de gatewayidentiteit op, registreert zich bij de relay met App Attest plus de appreceipt en publiceert daarna de relay-ondersteunde push.apns.register-payload naar de gekoppelde gateway.
5. De gateway slaat de relay-handle en verzendmachtiging op en gebruikt ze daarna voor push.test, wake-nudges en reconnect-wakes.

Operationele opmerkingen:

• Als je de iOS-app naar een andere gateway omschakelt, verbind de app dan opnieuw zodat deze een nieuwe relayregistratie kan publiceren die aan die gateway is gebonden.
• Als je een nieuwe iOS-build verzendt die naar een andere relay-implementatie verwijst, vernieuwt de app de gecachete relayregistratie in plaats van de oude relay-oorsprong opnieuw te gebruiken.

Compatibiliteitsopmerking:

• OPENCLAW_APNS_RELAY_BASE_URL en OPENCLAW_APNS_RELAY_TIMEOUT_MS werken nog steeds als tijdelijke omgevingsoverschrijvingen.
• OPENCLAW_APNS_RELAY_ALLOW_HTTP=true blijft een local loopback-ontwikkeluitweg; sla geen HTTP-relay-URL's blijvend op in configuratie.

Zie iOS-app voor de end-to-end-flow en Authenticatie- en vertrouwensflow voor het relaybeveiligingsmodel.

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

• every: duurstring (30m, 2h). Stel 0m in om uit te schakelen.
• target: last | none | <channel-id> (bijvoorbeeld discord, matrix, telegram of whatsapp)
• directPolicy: allow (standaard) of block voor DM-achtige heartbeatdoelen
• Zie Heartbeat voor de volledige handleiding.

{  cron: {    enabled: true,    maxConcurrentRuns: 2, // cron dispatch + isolated cron agent-turn execution    sessionRetention: "24h",    runLog: {      maxBytes: "2mb",      keepLines: 2000,    },  },}

• sessionRetention: verwijder voltooide geisoleerde runsessies uit sessions.json (standaard 24h; stel false in om uit te schakelen).
• runLog: snoei cron/runs/<jobId>.jsonl op grootte en behouden regels.
• Zie Cron-taken voor een functieoverzicht en CLI-voorbeelden.

Schakel HTTP-webhookeindpunten in op de 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,      },    ],  },}

Beveiligingsopmerking:

• Behandel alle hook-/webhookpayloadinhoud als niet-vertrouwde invoer.
• Gebruik een speciale hooks.token; hergebruik de gedeelde Gateway-token niet.
• Hookauthenticatie werkt alleen via headers (Authorization: Bearer ... of x-openclaw-token); querystringtokens worden geweigerd.
• hooks.path mag niet / zijn; houd webhookingress op een speciaal subpad zoals /hooks.
• Houd bypassvlaggen voor onveilige inhoud uitgeschakeld (hooks.gmail.allowUnsafeExternalContent, hooks.mappings[].allowUnsafeExternalContent), behalve bij strikt afgebakende debugging.
• Als je hooks.allowRequestSessionKey inschakelt, stel dan ook hooks.allowedSessionKeyPrefixes in om door de aanroeper gekozen sessiesleutels te begrenzen.
• Geef voor hook-gestuurde agents de voorkeur aan sterke moderne modelniveaus en strikt toolbeleid (bijvoorbeeld alleen messaging plus waar mogelijk sandboxing).

Zie volledige referentie voor alle mappingopties en Gmail-integratie.

Voer meerdere geisoleerde agents uit met aparte workspaces en sessies:

{  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" } },  ],}

Zie Multi-Agent en volledige referentie voor bindingsregels en toegangprofielen per agent.

Gebruik $include om grote configuraties te organiseren:

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

• Enkel bestand: vervangt het bevattende object
• Array van bestanden: in volgorde diep samengevoegd (latere wint)
• Sibling keys: samengevoegd na includes (overschrijven geinclude waarden)
• Geneste includes: ondersteund tot 10 niveaus diep
• Relatieve paden: opgelost relatief aan het includende bestand
• OpenClaw-owned writes: wanneer een schrijfactie slechts een top-level sectie wijzigt die wordt ondersteund door een single-file include zoals plugins: { $include: "./plugins.json5" }, werkt OpenClaw dat geinclude bestand bij en laat openclaw.json intact
• Niet-ondersteunde write-through: root-includes, include-arrays en includes met sibling-overschrijvingen falen gesloten voor OpenClaw-owned writes in plaats van de configuratie af te vlakken
• Inperking: $include-paden moeten uitkomen onder de directory die openclaw.json bevat. Om een boomstructuur tussen machines of gebruikers te delen, stel OPENCLAW_INCLUDE_ROOTS in op een padenlijst (: op POSIX, ; op Windows) met extra directories waarnaar includes mogen verwijzen. Symlinks worden opgelost en opnieuw gecontroleerd, dus een pad dat lexicaal in een configuratiedirectory staat maar waarvan het echte doel buiten elke toegestane root valt, wordt nog steeds geweigerd.
• Foutafhandeling: duidelijke fouten voor ontbrekende bestanden, parsefouten en circulaire includes