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 allowlist voor /model.
• 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 meegeeft.
• Modelverwijzingen gebruiken de indeling provider/model (bijv. anthropic/claude-opus-4-6).
• agents.defaults.imageMaxDimensionPx beheert 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 Aangepaste providers in de referentie voor aangepaste/zelf gehoste providers.

DM-toegang wordt per kanaal beheerd via dmPolicy:

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

Gebruik voor groepen groupPolicy + groupAllowFrom of kanaalspecifieke toestemmingslijsten.

Zie de volledige referentie voor details per kanaal.

Groepsberichten vereisen standaard een vermelding. Configureer triggerpatronen per agent en laat zichtbare kamerantwoorden op het standaardpad voor de berichtentool, tenzij je bewust verouderde 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 tikken-om-te-vermelden, Telegram @bot, enz.)
• Tekstpatronen: veilige regex-patronen in mentionPatterns
• Zichtbare antwoorden: messages.visibleReplies kan berichtentool-verzendingen globaal vereisen; messages.groupChat.visibleReplies overschrijft dat voor groepen/kanalen.
• Zie de volledige referentie voor modi voor zichtbare antwoorden, overschrijvingen per kanaal en zelfchatmodus.

Gebruik agents.defaults.skills voor een gedeelde basis en overschrijf vervolgens 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 over te nemen.
• Stel agents.list[].skills: [] in voor geen Skills.
• Zie Skills, Skills-configuratie en de Configuratiereferentie.

Bepaal hoe agressief de Gateway kanalen opnieuw start 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 herstarts door gezondheidsbewaking 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 bewaking uit te schakelen.
• Zie Gezondheidscontroles voor operationele debugging en de volledige referentie voor alle velden.

Geef lokale clients meer tijd om de WebSocket-handshake vóór authenticatie te voltooien op zwaar belaste of energiezuinige hosts:

{
  gateway: {
    handshakeTimeoutMs: 30000,
  },
}

• Standaard is 15000 milliseconden.
• OPENCLAW_HANDSHAKE_TIMEOUT_MS blijft voorrang houden voor eenmalige service- of shell-overschrijvingen.
• Los opstart- of event-loop-haperingen bij voorkeur eerst 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 thread-gebonden sessierouting (Discord ondersteunt /focus, /unfocus, /agents, /session idle en /session max-age).
• Zie Sessiebeheer voor scoping, identiteitskoppelingen en verzendbeleid.
• Zie de volledige referentie voor alle velden.

Voer agentsessies uit in geïsoleerde sandbox-runtimes:

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

Bouw eerst de image - voer vanuit een source checkout scripts/sandbox-setup.sh uit, of bekijk bij een npm-installatie de inline docker build-opdracht in Sandboxing § Images and setup.

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

Relay-backed push wordt geconfigureerd in openclaw.json.

Stel dit 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 via de externe relay verzenden.
• Gebruikt een verzendtoekenning met registratiescope die door de gekoppelde iOS-app wordt doorgestuurd. De Gateway heeft geen deployment-brede relay-token nodig.
• Koppelt elke relay-backed 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-backed verzendingen gelden alleen voor officieel gedistribueerde builds die via de relay zijn geregistreerd.
• Moet overeenkomen met de relay-basis-URL die in de officiële/TestFlight iOS-build is ingebakken, zodat registratie- en verzendverkeer dezelfde relay-deployment bereiken.

End-to-end-flow:

1. Installeer een officiële/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 verbinden.
4. De iOS-app haalt de Gateway-identiteit op, registreert zich bij de relay met App Attest plus het app-bewijs, en publiceert daarna de relay-backed push.apns.register-payload naar de gekoppelde Gateway.
5. De Gateway slaat de relay-handle en verzendtoekenning op en gebruikt die vervolgens 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 die een nieuwe relay-registratie kan publiceren die aan die Gateway is gekoppeld.
• Als je een nieuwe iOS-build uitbrengt die naar een andere relay-deployment verwijst, vernieuwt de app de gecachte relay-registratie 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 env-overrides.
• OPENCLAW_APNS_RELAY_ALLOW_HTTP=true blijft een ontwikkelingsnooduitgang voor alleen loopback; bewaar geen HTTP-relay-URL's 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 in op 0m 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: 2, // cron dispatch + isolated cron agent-turn execution
    sessionRetention: "24h",
    runLog: {
      maxBytes: "2mb",
      keepLines: 2000,
    },
  },
}

• sessionRetention: ruim voltooide geïsoleerde uitvoeringssessies op uit sessions.json (standaard 24h; stel in op false om uit te schakelen).
• runLog: ruim cron/runs/<jobId>.jsonl op op basis van grootte en behouden regels.
• 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 hook-/Webhook-payloadinhoud als onvertrouwde invoer.
• Gebruik een specifieke hooks.token; hergebruik de gedeelde Gateway-token niet.
• Hook-authenticatie werkt alleen via headers (Authorization: Bearer ... of x-openclaw-token); query-string-tokens worden geweigerd.
• hooks.path mag niet / zijn; houd Webhook-ingress op een specifiek subpad zoals /hooks.
• Houd bypass-flags voor onveilige inhoud uitgeschakeld (hooks.gmail.allowUnsafeExternalContent, hooks.mappings[].allowUnsafeExternalContent), behalve voor 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 modeltiers en strikt toolbeleid (bijvoorbeeld alleen messaging plus sandboxing waar mogelijk).

Zie volledige referentie voor alle mappingopties 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 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 omvattende object
• Array met bestanden: deep-merged in volgorde (later wint)
• Sibling-sleutels: samengevoegd na includes (overschrijven opgenomen waarden)
• Geneste includes: ondersteund tot 10 niveaus diep
• Relatieve paden: opgelost relatief ten opzichte van het includende bestand
• Door OpenClaw beheerde schrijfacties: wanneer een schrijfactie slechts één top-level sectie wijzigt die wordt ondersteund door een single-file include zoals plugins: { $include: "./plugins.json5" }, werkt OpenClaw dat opgenomen bestand bij en laat openclaw.json intact
• Niet-ondersteunde write-through: root-includes, include-arrays en includes met sibling-overrides falen gesloten voor door OpenClaw beheerde schrijfacties in plaats van de configuratie te flattenen
• Confinement: $include-paden moeten oplossen onder de map die openclaw.json bevat. Stel OPENCLAW_INCLUDE_ROOTS in op een padenlijst (: op POSIX, ; op Windows) met aanvullende mappen waarnaar includes mogen verwijzen om een tree tussen machines of gebruikers te delen. Symlinks worden opgelost en opnieuw gecontroleerd, dus een pad dat lexicaal in een configuratiemap 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