Configuratie

Elk kanaal heeft zijn eigen configuratiesectie onder channels.<provider>. Zie de specifieke 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 allowlist voor /model; provider/*-vermeldingen filteren /model, /models en modelkiezers naar geselecteerde providers, terwijl ze nog steeds dynamische modelontdekking gebruiken.
• Gebruik openclaw config set agents.defaults.models '<json>' --strict-json --merge om allowlist-vermeldingen toe te voegen zonder bestaande modellen te verwijderen. Gewone vervangingen die vermeldingen zouden verwijderen, worden geweigerd tenzij je --replace doorgeeft.
• Modelrefs gebruiken de indeling provider/model (bijv. anthropic/claude-opus-4-6).
• agents.defaults.imageMaxDimensionPx bepaalt 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 fallbackgedrag.
• Zie Custom providers in de referentie voor aangepaste/zelfgehoste providers.

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-opslag)
• "open": alle binnenkomende 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. Normale groeps-/kanaalantwoorden worden automatisch geplaatst; kies het message-tool-pad voor gedeelde rooms waar de agent moet beslissen wanneer hij spreekt:

{  messages: {    visibleReplies: "automatic", // set "message_tool" to require message-tool sends everywhere    groupChat: {      visibleReplies: "message_tool", // opt-in; visible output requires message(action=send)      unmentionedInbound: "room_event", // unmentioned always-on group chatter is quiet context    },  },  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 message-tool-verzendingen globaal verplicht maken; messages.groupChat.visibleReplies overschrijft dat voor groepen/kanalen.
• Zie volledige referentie voor zichtbare-antwoordmodi, overschrijvingen per kanaal en self-chat-modus.

Gebruik agents.defaults.skills voor een gedeelde basislijn en overschrijf daarna specifieke agents 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 hosts of hosts met weinig vermogen:

{  gateway: {    handshakeTimeoutMs: 30000,  },}

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

Sessies beheren gesprekscontinuïteit 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 standaardinstellingen voor sessierouting 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 sandbox-runtimes:

{  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 gids en volledige referentie voor alle opties.

Relay-ondersteunde push voor openbare App Store-builds gebruikt de gehoste OpenClaw-relay: https://ios-push-relay.openclaw.ai.

Aangepaste relay-implementaties vereisen een bewust gescheiden iOS-build-/implementatiepad waarvan de relay-URL overeenkomt met de Gateway-relay-URL. Als je een aangepaste relay-build gebruikt, stel dit dan in de Gateway-configuratie 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 verzenden via de externe relay.
• Gebruikt een registratiegebonden verzendmachtiging die wordt doorgestuurd door de gekoppelde iOS-app. De Gateway heeft geen implementatiebrede relay-token nodig.
• Bindt elke relay-ondersteunde registratie aan de Gateway-identiteit 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 iOS-build is ingebakken, zodat registratie- en verzendverkeer dezelfde relay-implementatie bereiken.

End-to-end-flow:

1. Installeer de officiele iOS-app.
2. Optioneel: configureer gateway.push.apns.relay.baseUrl op de Gateway alleen wanneer je een bewust gescheiden aangepaste relay-build gebruikt.
3. Koppel de iOS-app aan de Gateway en laat zowel node- als operatorsessies verbinding maken.
4. De iOS-app haalt de Gateway-identiteit op, registreert zich bij de relay met App Attest plus de app-bon, 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 deze daarna voor push.test, wake nudges en reconnect wakes.

Operationele opmerkingen:

• Als je de iOS-app naar een andere Gateway overschakelt, verbind de app dan opnieuw zodat deze een nieuwe relay-registratie kan publiceren die aan die Gateway is gebonden.
• Als je een nieuwe iOS-build uitbrengt die naar een andere relay-implementatie wijst, vernieuwt de app de gecachte relay-registratie in plaats van de oude relay-origin opnieuw te gebruiken.

Compatibiliteitsopmerking:

• OPENCLAW_APNS_RELAY_BASE_URL en OPENCLAW_APNS_RELAY_TIMEOUT_MS blijven werken als tijdelijke env-overrides.
• Aangepaste Gateway-relay-URL's moeten overeenkomen met de relay-basis-URL die in de iOS-build is ingebakken. De openbare App Store-release-lane weigert aangepaste iOS-relay-URL-overrides.
• OPENCLAW_APNS_RELAY_ALLOW_HTTP=true blijft een ontwikkelingsuitweg alleen voor local loopback; sla geen HTTP-relay-URL's permanent op in configuratie.

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

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

• every: duurtekenreeks (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 Heartbeat-doelen
• Zie Heartbeat voor de volledige gids.

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

• sessionRetention: ruim voltooide geisoleerde runsessies op uit sessions.json (standaard 24h; stel false in om uit te schakelen).
• runLog: ruim bewaarde Cron-runhistorierijen per taak op. maxBytes blijft geaccepteerd voor oudere bestandsgebaseerde runlogs.
• Zie Cron-jobs voor een functieoverzicht en CLI-voorbeelden.

Schakel HTTP-Webhook-eindpunten 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-/Webhook-payloadinhoud als niet-vertrouwde invoer.
• Gebruik een specifieke hooks.token; hergebruik geen actieve Gateway-authgeheimen (gateway.auth.token / OPENCLAW_GATEWAY_TOKEN of gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD).
• Hook-authenticatie werkt alleen via headers (Authorization: Bearer ... of x-openclaw-token); querystring-tokens worden geweigerd.
• hooks.path mag niet / zijn; houd Webhook-ingress op een specifiek subpad zoals /hooks.
• Houd bypass-vlaggen voor onveilige inhoud uitgeschakeld (hooks.gmail.allowUnsafeExternalContent, hooks.mappings[].allowUnsafeExternalContent), behalve bij strak afgebakende debugging.
• Als je hooks.allowRequestSessionKey inschakelt, stel dan ook hooks.allowedSessionKeyPrefixes in om door callers gekozen sessiesleutels te begrenzen.
• Geef voor hook-gestuurde agents de voorkeur aan sterke moderne modeltiers en strikt toolbeleid (bijvoorbeeld alleen berichten plus sandboxing waar mogelijk).

Zie volledige referentie voor alle mappingopties en Gmail-integratie.

Voer meerdere geisoleerde agents uit met gescheiden 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 toegangsprofielen 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: diep samengevoegd in volgorde (latere wint)
• Zusterkeys: samengevoegd na includes (overschrijven opgenomen waarden)
• Geneste includes: ondersteund tot 10 niveaus diep
• Relatieve paden: opgelost relatief aan het include-bestand
• Padindeling: include-paden mogen geen null-bytes bevatten en moeten strikt korter zijn dan 4096 tekens voor en na resolutie
• OpenClaw-beheerde writes: wanneer een write slechts een top-levelsectie wijzigt die wordt ondersteund door een enkelbestand-include zoals plugins: { $include: "./plugins.json5" }, werkt OpenClaw dat opgenomen bestand bij en laat het openclaw.json intact
• Niet-ondersteunde write-through: root-includes, include-arrays en includes met zuster-overschrijvingen falen gesloten voor OpenClaw-beheerde writes in plaats van de configuratie af te vlakken
• Insluiting: $include-paden moeten oplossen onder de directory die openclaw.json bevat. Om een boom tussen machines of gebruikers te delen, stel je OPENCLAW_INCLUDE_ROOTS in op een padenlijst (: op POSIX, ; op Windows) van 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, circulaire includes, ongeldige padindeling en overmatige lengte