Configuratie

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

• Discord - channels.discord
• Feishu - channels.feishu
• Google Chat - channels.googlechat
• iMessage - channels.imessage
• Mattermost - channels.mattermost
• Microsoft Teams - channels.msteams
• Signal - channels.signal
• Slack - channels.slack
• Telegram - channels.telegram
• WhatsApp - channels.whatsapp

Alle kanalen gebruiken hetzelfde patroon voor DM-beleid:

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

Stel het primaire model en optionele terugvalmodellen 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 bewaart aliassen en instellingen per model; het toevoegen van een vermelding beperkt overschrijvingen via /model of --model nooit.
• agents.defaults.modelPolicy.allow is de expliciete toelatingslijst voor overschrijvingen en modelkiezers. Deze accepteert exacte verwijzingen en jokertekens van provider/*; laat dit weg of gebruik [] om elk model toe te staan.
• Modelverwijzingen gebruiken de indeling provider/model (bijvoorbeeld anthropic/claude-opus-4-6).
• agents.defaults.imageMaxDimensionPx bepaalt het verkleinen van afbeeldingen uit transcripties/tools (standaard 1200); lagere waarden verminderen doorgaans het gebruik van vision-tokens bij uitvoeringen met veel schermafbeeldingen.
• Zie CLI voor modellen voor het wisselen van model in een chat en Modelomschakeling bij storingen voor autorisatierotatie en terugvalgedrag.
• Zie voor aangepaste/zelfgehoste providers Aangepaste providers in de naslaginformatie.

DM-toegang wordt per kanaal geregeld via dmPolicy (standaard "pairing"):

• "pairing": onbekende afzenders krijgen een eenmalige koppelingscode ter goedkeuring
• "allowlist": alleen afzenders in allowFrom (of de opslag met gekoppelde toegestane afzenders)
• "open": alle inkomende DM's toestaan (vereist allowFrom: ["*"])
• "disabled": alle DM's negeren

Gebruik voor groepen groupPolicy ("allowlist" | "open" | "disabled") plus groupAllowFrom of kanaalspecifieke toelatingslijsten.

Zie de volledige naslaginformatie voor details per kanaal.

Voor groepsberichten is standaard een vermelding vereist. Configureer activeringspatronen per agent. Normale antwoorden in groepen/kanalen worden automatisch geplaatst; schakel het pad via de berichtentool in voor gedeelde ruimten waarin de agent moet beslissen wanneer deze spreekt:

{  messages: {    visibleReplies: "automatic", // stel "message_tool" in om overal verzending via de berichtentool te vereisen    groupChat: {      visibleReplies: "message_tool", // opt-in; zichtbare uitvoer vereist message(action=send)      unmentionedInbound: "room_event", // groepsgesprekken zonder vermelding die altijd actief zijn, vormen stille context    },  },  agents: {    list: [      {        id: "main",        groupChat: {          mentionPatterns: ["@openclaw", "openclaw"],        },      },    ],  },  channels: {    whatsapp: {      groups: { "*": { requireMention: true } },    },  },}

• Vermeldingen in metagegevens: systeemeigen @-vermeldingen (tikken om te vermelden in WhatsApp, Telegram @bot enzovoort)
• Tekstpatronen: veilige reguliere-expressiepatronen in mentionPatterns
• Zichtbare antwoorden: messages.visibleReplies kan verzending via de berichtentool globaal verplichten; messages.groupChat.visibleReplies overschrijft dit voor groepen/kanalen.
• Zie de volledige naslaginformatie voor modi voor zichtbare antwoorden, overschrijvingen per kanaal en de zelfchatmodus.

Gebruik agents.defaults.skills voor een gedeelde basis en overschrijf vervolgens specifieke agents met agents.entries.*.skills:

{  agents: {    defaults: {      skills: ["github", "weather"],    },    list: [      { id: "writer" }, // neemt github, weather over      { id: "docs", skills: ["docs-search"] }, // vervangt de standaardwaarden      { id: "locked-down", skills: [] }, // geen skills    ],  },}

• Laat agents.defaults.skills weg voor standaard onbeperkte skills.
• Laat agents.entries.*.skills weg om de standaardwaarden over te nemen.
• Stel agents.entries.*.skills: [] in voor geen skills.
• Zie Skills, Skills-configuratie en de configuratienaslag.

Schakel automatische herstarts voor de status van een kanaal of account uit of in:

{  channels: {    telegram: {      healthMonitor: { enabled: false },      accounts: {        alerts: {          healthMonitor: { enabled: true },        },      },    },  },}

• Gebruik channels.<provider>.healthMonitor.enabled of channels.<provider>.accounts.<id>.healthMonitor.enabled om automatische herstarts voor één kanaal of account te regelen.
• Zie Statuscontroles voor operationele foutopsporing en de volledige naslaginformatie voor alle velden.

Sessies bepalen de continuïteit en isolatie van gesprekken:

{  session: {    dmScope: "per-channel-peer",  // aanbevolen voor meerdere gebruikers    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: algemene standaardwaarden voor sessieroutering die aan threads is gekoppeld. /focus, /unfocus, /agents, /session idle en /session max-age koppelen, ontkoppelen, vermelden en configureren dit per sessie (Discord koppelt threads, Telegram koppelt onderwerpen/gesprekken).
• Zie Sessiebeheer voor bereik, identiteitskoppelingen en verzendbeleid.
• Zie de volledige referentie voor alle velden.

Voer agentsessies uit in geïsoleerde 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 raadpleeg bij een npm-installatie de inlineopdracht docker build in Sandboxing § Images en configuratie.

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

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

Aangepaste relayimplementaties vereisen een bewust afzonderlijk iOS-build- en implementatiepad waarvan de relay-URL overeenkomt met de relay-URL van de Gateway. Als je een aangepaste relaybuild gebruikt, stel je dit in de Gateway-configuratie in:

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

CLI-equivalent:

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

Wat dit doet:

• Hiermee kan de Gateway push.test, activeringssignalen en herverbindingssignalen via de externe relay verzenden.
• Gebruikt een verzendmachtiging met registratiebereik die door de gekoppelde iOS-app wordt doorgestuurd. De Gateway heeft geen implementatiebreed relaytoken nodig.
• Koppelt elke relaygebaseerde registratie aan de Gateway-identiteit waarmee de iOS-app is gekoppeld, zodat een andere Gateway de opgeslagen registratie niet kan hergebruiken.
• Houdt lokale/handmatige iOS-builds op directe APNs. Relaygebaseerde verzending is alleen van toepassing op officieel gedistribueerde builds die via de relay zijn geregistreerd.
• Moet overeenkomen met de relaybasis-URL die in de iOS-build is ingebouwd, zodat registratie- en verzendverkeer dezelfde relayimplementatie bereiken.

End-to-end-flow:

1. Installeer de officiële iOS-app.
2. Optioneel: configureer gateway.push.apns.relay.baseUrl op de Gateway alleen wanneer je een bewust afzonderlijke aangepaste relaybuild 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 en het appbewijs en publiceert vervolgens de relaygebaseerde push.apns.register-payload naar de gekoppelde Gateway.
5. De Gateway slaat de relayhandle en verzendmachtiging op en gebruikt deze vervolgens voor push.test, activeringssignalen en herverbindingssignalen.

Operationele opmerkingen:

• Als je de iOS-app naar een andere Gateway overschakelt, verbind je de app opnieuw zodat deze een nieuwe, aan die Gateway gekoppelde relayregistratie kan publiceren.
• Als je een nieuwe iOS-build uitbrengt die naar een andere relayimplementatie verwijst, vernieuwt de app de gecachte relayregistratie in plaats van de oude relayoorsprong opnieuw te gebruiken.

Compatibiliteitsopmerking:

• OPENCLAW_APNS_RELAY_BASE_URL en OPENCLAW_APNS_RELAY_TIMEOUT_MS werken nog steeds als tijdelijke omgevingsoverschrijvingen.
• Aangepaste relay-URL's voor de Gateway moeten overeenkomen met de relaybasis-URL die in de iOS-build is ingebouwd; het openbare App Store-releasekanaal weigert aangepaste iOS-relay-URL-overschrijvingen.
• OPENCLAW_APNS_RELAY_ALLOW_HTTP=true blijft een uitsluitend voor loopback bestemde noodoplossing voor ontwikkeling; sla HTTP-relay-URL's niet permanent op in de configuratie.

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

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

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

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

• sessionRetention: verwijder voltooide geïsoleerde uitvoeringssessies uit SQLite-sessierijen (standaard 24h; stel false in om dit uit te schakelen).
• De uitvoeringsgeschiedenis bewaart automatisch de nieuwste 2000 terminalrijen per taak; verloren rijen behouden hun opschoningsvenster van 24 uur.
• Zie Cron-taken voor een functieoverzicht en CLI-voorbeelden.

Schakel HTTP-webhook-eindpunten op de Gateway in:

{  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 inhoud van hook-/webhook-payloads als niet-vertrouwde invoer.
• Gebruik een afzonderlijke hooks.token; gebruik actieve authenticatiegeheimen van de Gateway niet opnieuw (gateway.auth.token / OPENCLAW_GATEWAY_TOKEN of gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD).
• Hookauthenticatie werkt uitsluitend via headers (Authorization: Bearer ... of x-openclaw-token); tokens in queryreeksen worden geweigerd.
• hooks.path kan niet / zijn; houd webhookinvoer op een afzonderlijk subpad, zoals /hooks.
• Laat omzeilingsvlaggen voor onveilige inhoud uitgeschakeld (hooks.gmail.allowUnsafeExternalContent, hooks.mappings[].allowUnsafeExternalContent), tenzij je strikt afgebakende foutopsporing uitvoert.
• Als je hooks.allowRequestSessionKey inschakelt, stel dan ook hooks.allowedSessionKeyPrefixes in om door aanroepers geselecteerde sessiesleutels te begrenzen.
• Geef voor door hooks aangestuurde agents de voorkeur aan sterke, moderne modelniveaus en een strikt toolbeleid (bijvoorbeeld alleen berichten plus sandboxing waar mogelijk).

Zie de volledige referentie voor alle toewijzingsopties en Gmail-integratie.

Voer meerdere geïsoleerde agents uit met afzonderlijke werkruimten 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 de volledige referentie voor koppelingsregels 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"],  },}

• Eén bestand: vervangt het omsluitende object
• Bestandsarray: wordt op volgorde diep samengevoegd (de laatste wint), tot 10 geneste niveaus diep
• Sleutels op hetzelfde niveau: worden na de includes samengevoegd (overschrijven opgenomen waarden)
• Relatieve paden: worden relatief ten opzichte van het includerende bestand omgezet
• Padindeling: includepaden mogen geen nullbytes bevatten en moeten vóór en na omzetting strikt korter zijn dan 4096 tekens
• Door OpenClaw beheerde schrijfbewerkingen: wanneer een schrijfbewerking slechts één sectie op het hoogste niveau wijzigt die wordt ondersteund door een include van één bestand, zoals plugins: { $include: "./plugins.json5" }, werkt OpenClaw dat opgenomen bestand bij en laat het openclaw.json intact
• Niet-ondersteund doorschrijven: root-includes, includearrays en includes met overschrijvingen op hetzelfde niveau worden bij door OpenClaw beheerde schrijfbewerkingen veilig geweigerd in plaats van de configuratie af te vlakken
• Beperking: $include-paden moeten worden omgezet naar een locatie onder de map die openclaw.json bevat. Als je een boomstructuur tussen machines of gebruikers wilt delen, stel je OPENCLAW_INCLUDE_ROOTS in op een padenlijst (: op POSIX, ; op Windows) met aanvullende mappen waarnaar includes mogen verwijzen. Symbolische koppelingen worden omgezet en opnieuw gecontroleerd. Een pad dat zich lexicaal in een configuratiemap bevindt, maar waarvan het werkelijke doel buiten elke toegestane root valt, wordt daarom nog steeds geweigerd.
• Foutafhandeling: duidelijke fouten voor ontbrekende bestanden, parseerfouten, circulaire includes, een ongeldige padindeling en een te grote lengte