​

Konfigurationsreferenz

• openclaw config schema gibt das Live-JSON-Schema aus, das für Validierung und Control UI verwendet wird, wobei gebündelte Plugin-/Kanal-Metadaten zusammengeführt werden, wenn verfügbar
• config.schema.lookup gibt einen einzelnen pfadbezogenen Schemaknoten für Drilldown-Tools zurück
• pnpm config:docs:check / pnpm config:docs:gen validieren den Hash der Konfigurationsdokumentations-Baseline gegen die aktuelle Schemaoberfläche

• Memory-Konfigurationsreferenz für agents.defaults.memorySearch.*, memory.qmd.*, memory.citations und Dreaming-Konfiguration unter plugins.entries.memory-core.config.dreaming
• Slash Commands für den aktuellen integrierten + gebündelten Befehlskatalog
• zuständige Kanal-/Plugin-Seiten für kanalspezifische Befehlsoberflächen

​

Kanäle

​

DM- und Gruppenzugriff

​

Kanal-Modellüberschreibungen

{
  channels: {
    modelByChannel: {
      discord: {
        "123456789012345678": "anthropic/claude-opus-4-6",
      },
      slack: {
        C1234567890: "openai/gpt-4.1",
      },
      telegram: {
        "-1001234567890": "openai/gpt-4.1-mini",
        "-1001234567890:topic:99": "anthropic/claude-sonnet-4-6",
      },
    },
  },
}

​

Kanal-Standardeinstellungen und Heartbeat

{
  channels: {
    defaults: {
      groupPolicy: "allowlist", // open | allowlist | disabled
      contextVisibility: "all", // all | allowlist | allowlist_quote
      heartbeat: {
        showOk: false,
        showAlerts: true,
        useIndicator: true,
      },
    },
  },
}

• channels.defaults.groupPolicy: Fallback-Gruppenrichtlinie, wenn eine providerbezogene groupPolicy nicht gesetzt ist.
• channels.defaults.contextVisibility: Standardmodus für die Sichtbarkeit ergänzenden Kontexts für alle Kanäle. Werte: all (Standard, schließt allen zitierten/Thread-/Verlaufs-Kontext ein), allowlist (schließt nur Kontext von erlaubten Absendern ein), allowlist_quote (wie allowlist, behält aber expliziten Zitat-/Antwortkontext bei). Überschreibung pro Kanal: channels.<channel>.contextVisibility.
• channels.defaults.heartbeat.showOk: Gesunde Kanalstatus in die Heartbeat-Ausgabe aufnehmen.
• channels.defaults.heartbeat.showAlerts: Beeinträchtigte/Fehlerstatus in die Heartbeat-Ausgabe aufnehmen.
• channels.defaults.heartbeat.useIndicator: Kompakte Heartbeat-Ausgabe im Indikatorstil rendern.

​

WhatsApp

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["+15555550123", "+447700900123"],
      textChunkLimit: 4000,
      chunkMode: "length", // length | newline
      mediaMaxMb: 50,
      sendReadReceipts: true, // blaue Häkchen (false im Selbstchat-Modus)
      groups: {
        "*": { requireMention: true },
      },
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
  web: {
    enabled: true,
    heartbeatSeconds: 60,
    reconnect: {
      initialMs: 2000,
      maxMs: 120000,
      factor: 1.4,
      jitter: 0.2,
      maxAttempts: 0,
    },
  },
}

{
  channels: {
    whatsapp: {
      accounts: {
        default: {},
        personal: {},
        biz: {
          // authDir: "~/.openclaw/credentials/whatsapp/biz",
        },
      },
    },
  },
}

​

Telegram

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "your-bot-token",
      dmPolicy: "pairing",
      allowFrom: ["tg:123456789"],
      groups: {
        "*": { requireMention: true },
        "-1001234567890": {
          allowFrom: ["@admin"],
          systemPrompt: "Halten Sie Antworten kurz.",
          topics: {
            "99": {
              requireMention: false,
              skills: ["search"],
              systemPrompt: "Bleiben Sie beim Thema.",
            },
          },
        },
      },
      customCommands: [
        { command: "backup", description: "Git-Backup" },
        { command: "generate", description: "Ein Bild erstellen" },
      ],
      historyLimit: 50,
      replyToMode: "first", // off | first | all | batched
      linkPreview: true,
      streaming: "partial", // off | partial | block | progress (Standard: off; explizit aktivieren, um Ratenbegrenzungen bei Vorschau-Bearbeitungen zu vermeiden)
      actions: { reactions: true, sendMessage: true },
      reactionNotifications: "own", // off | own | all
      mediaMaxMb: 100,
      retry: {
        attempts: 3,
        minDelayMs: 400,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
      network: {
        autoSelectFamily: true,
        dnsResultOrder: "ipv4first",
      },
      proxy: "socks5://localhost:9050",
      webhookUrl: "https://example.com/telegram-webhook",
      webhookSecret: "secret",
      webhookPath: "/telegram-webhook",
    },
  },
}

• Bot-Token: channels.telegram.botToken oder channels.telegram.tokenFile (nur reguläre Datei; Symlinks werden abgelehnt), mit TELEGRAM_BOT_TOKEN als Fallback für das Standardkonto.
• Optional überschreibt channels.telegram.defaultAccount die Standardkontenauswahl, wenn es mit einer konfigurierten Konto-ID übereinstimmt.
• In Setups mit mehreren Konten (2+ Konto-IDs) sollten Sie einen expliziten Standard setzen (channels.telegram.defaultAccount oder channels.telegram.accounts.default), um Fallback-Routing zu vermeiden; openclaw doctor warnt, wenn dies fehlt oder ungültig ist.
• configWrites: false blockiert von Telegram initiierte Konfigurationsschreibvorgänge (Supergroup-ID-Migrationen, /config set|unset).
• Top-Level-Einträge in bindings[] mit type: "acp" konfigurieren persistente ACP-Bindings für Foren-Themen (verwenden Sie das kanonische chatId:topic:topicId in match.peer.id). Die Feldsemantik ist gemeinsam in ACP Agents beschrieben.
• Telegram-Stream-Vorschauen verwenden sendMessage + editMessageText (funktioniert in Direkt- und Gruppenchats).
• Retry-Richtlinie: siehe Retry-Richtlinie.

​

Discord

{
  channels: {
    discord: {
      enabled: true,
      token: "your-bot-token",
      mediaMaxMb: 100,
      allowBots: false,
      actions: {
        reactions: true,
        stickers: true,
        polls: true,
        permissions: true,
        messages: true,
        threads: true,
        pins: true,
        search: true,
        memberInfo: true,
        roleInfo: true,
        roles: false,
        channelInfo: true,
        voiceStatus: true,
        events: true,
        moderation: false,
      },
      replyToMode: "off", // off | first | all | batched
      dmPolicy: "pairing",
      allowFrom: ["1234567890", "123456789012345678"],
      dm: { enabled: true, groupEnabled: false, groupChannels: ["openclaw-dm"] },
      guilds: {
        "123456789012345678": {
          slug: "friends-of-openclaw",
          requireMention: false,
          ignoreOtherMentions: true,
          reactionNotifications: "own",
          users: ["987654321098765432"],
          channels: {
            general: { allow: true },
            help: {
              allow: true,
              requireMention: true,
              users: ["987654321098765432"],
              skills: ["docs"],
              systemPrompt: "Nur kurze Antworten.",
            },
          },
        },
      },
      historyLimit: 20,
      textChunkLimit: 2000,
      chunkMode: "length", // length | newline
      streaming: "off", // off | partial | block | progress (progress wird auf Discord zu partial abgebildet)
      maxLinesPerMessage: 17,
      ui: {
        components: {
          accentColor: "#5865F2",
        },
      },
      threadBindings: {
        enabled: true,
        idleHours: 24,
        maxAgeHours: 0,
        spawnSubagentSessions: false, // Opt-in für sessions_spawn({ thread: true })
      },
      voice: {
        enabled: true,
        autoJoin: [
          {
            guildId: "123456789012345678",
            channelId: "234567890123456789",
          },
        ],
        daveEncryption: true,
        decryptionFailureTolerance: 24,
        tts: {
          provider: "openai",
          openai: { voice: "alloy" },
        },
      },
      execApprovals: {
        enabled: "auto", // true | false | "auto"
        approvers: ["987654321098765432"],
        agentFilter: ["default"],
        sessionFilter: ["discord:"],
        target: "dm", // dm | channel | both
        cleanupAfterResolve: false,
      },
      retry: {
        attempts: 3,
        minDelayMs: 500,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
    },
  },
}

• Token: channels.discord.token, mit DISCORD_BOT_TOKEN als Fallback für das Standardkonto.
• Direkte ausgehende Aufrufe, die ein explizites Discord-token bereitstellen, verwenden dieses Token für den Aufruf; Kontowiederholungs-/Richtlinieneinstellungen stammen weiterhin aus dem ausgewählten Konto im aktiven Laufzeit-Snapshot.
• Optional überschreibt channels.discord.defaultAccount die Standardkontenauswahl, wenn es mit einer konfigurierten Konto-ID übereinstimmt.
• Verwenden Sie user:<id> (DM) oder channel:<id> (Guild-Kanal) für Zustellungsziele; einfache numerische IDs werden abgelehnt.
• Guild-Slugs sind kleingeschrieben, wobei Leerzeichen durch - ersetzt werden; Kanalschlüssel verwenden den Slug-Namen (ohne #). Bevorzugen Sie Guild-IDs.
• Von Bots verfasste Nachrichten werden standardmäßig ignoriert. allowBots: true aktiviert sie; verwenden Sie allowBots: "mentions", um nur Bot-Nachrichten zu akzeptieren, die den Bot erwähnen (eigene Nachrichten werden weiterhin gefiltert).
• channels.discord.guilds.<id>.ignoreOtherMentions (und Kanalüberschreibungen) verwirft Nachrichten, die einen anderen Benutzer oder eine andere Rolle erwähnen, aber nicht den Bot (ausgenommen @everyone/@here).
• maxLinesPerMessage (Standard 17) teilt hohe Nachrichten auch dann auf, wenn sie unter 2000 Zeichen liegen.
• channels.discord.threadBindings steuert an Discord-Threads gebundenes Routing:
  • enabled: Discord-Überschreibung für an Threads gebundene Sitzungsfunktionen (/focus, /unfocus, /agents, /session idle, /session max-age sowie gebundene Zustellung/Weiterleitung)
  • idleHours: Discord-Überschreibung für automatisches Entfokussieren bei Inaktivität in Stunden (0 deaktiviert)
  • maxAgeHours: Discord-Überschreibung für hartes maximales Alter in Stunden (0 deaktiviert)
  • spawnSubagentSessions: Opt-in-Schalter für die automatische Thread-Erstellung/-Bindung durch sessions_spawn({ thread: true })
• Top-Level-Einträge in bindings[] mit type: "acp" konfigurieren persistente ACP-Bindings für Kanäle und Threads (verwenden Sie Kanal-/Thread-ID in match.peer.id). Die Feldsemantik ist gemeinsam in ACP Agents beschrieben.
• channels.discord.ui.components.accentColor setzt die Akzentfarbe für Discord-Komponenten-v2-Container.
• channels.discord.voice aktiviert Unterhaltungen in Discord-Sprachkanälen sowie optionale automatische Beitritte und TTS-Überschreibungen.
• channels.discord.voice.daveEncryption und channels.discord.voice.decryptionFailureTolerance werden an DAVE-Optionen von @discordjs/voice durchgereicht (standardmäßig true bzw. 24).
• OpenClaw versucht zusätzlich, den Empfang von Sprache wiederherzustellen, indem nach wiederholten Entschlüsselungsfehlern eine Sprachsitzung verlassen und erneut beigetreten wird.
• channels.discord.streaming ist der kanonische Schlüssel für den Stream-Modus. Veraltete Werte streamMode und boolesche streaming-Werte werden automatisch migriert.
• channels.discord.autoPresence bildet die Laufzeitverfügbarkeit auf die Bot-Präsenz ab (healthy => online, degraded => idle, exhausted => dnd) und erlaubt optionale Überschreibungen des Statustexts.
• channels.discord.dangerouslyAllowNameMatching aktiviert veränderbares Namens-/Tag-Matching erneut (Break-Glass-Kompatibilitätsmodus).
• channels.discord.execApprovals: Discord-native Zustellung von Exec-Genehmigungen und Autorisierung von Genehmigern.
  • enabled: true, false oder "auto" (Standard). Im Auto-Modus werden Exec-Genehmigungen aktiviert, wenn Genehmiger aus approvers oder commands.ownerAllowFrom aufgelöst werden können.
  • approvers: Discord-Benutzer-IDs, die Exec-Anfragen genehmigen dürfen. Fällt auf commands.ownerAllowFrom zurück, wenn weggelassen.
  • agentFilter: optionale Erlaubnisliste für Agent-IDs. Weglassen, um Genehmigungen für alle Agenten weiterzuleiten.
  • sessionFilter: optionale Sitzungs-Schlüsselmuster (Teilzeichenfolge oder Regex).
  • target: wohin Genehmigungsaufforderungen gesendet werden. "dm" (Standard) sendet an DMs der Genehmiger, "channel" an den Ursprungskanal, "both" an beides. Wenn das Ziel "channel" enthält, sind Schaltflächen nur für aufgelöste Genehmiger nutzbar.
  • cleanupAfterResolve: löscht bei true Genehmigungs-DMs nach Genehmigung, Ablehnung oder Zeitüberschreitung.

​

Google Chat

{
  channels: {
    googlechat: {
      enabled: true,
      serviceAccountFile: "/path/to/service-account.json",
      audienceType: "app-url", // app-url | project-number
      audience: "https://gateway.example.com/googlechat",
      webhookPath: "/googlechat",
      botUser: "users/1234567890",
      dm: {
        enabled: true,
        policy: "pairing",
        allowFrom: ["users/1234567890"],
      },
      groupPolicy: "allowlist",
      groups: {
        "spaces/AAAA": { allow: true, requireMention: true },
      },
      actions: { reactions: true },
      typingIndicator: "message",
      mediaMaxMb: 20,
    },
  },
}

• Service-Account-JSON: inline (serviceAccount) oder dateibasiert (serviceAccountFile).
• SecretRef für den Service Account wird ebenfalls unterstützt (serviceAccountRef).
• Env-Fallbacks: GOOGLE_CHAT_SERVICE_ACCOUNT oder GOOGLE_CHAT_SERVICE_ACCOUNT_FILE.
• Verwenden Sie spaces/<spaceId> oder users/<userId> für Zustellungsziele.
• channels.googlechat.dangerouslyAllowNameMatching aktiviert veränderbares Matching von E-Mail-Principals erneut (Break-Glass-Kompatibilitätsmodus).

​

Slack

{
  channels: {
    slack: {
      enabled: true,
      botToken: "xoxb-...",
      appToken: "xapp-...",
      dmPolicy: "pairing",
      allowFrom: ["U123", "U456", "*"],
      dm: { enabled: true, groupEnabled: false, groupChannels: ["G123"] },
      channels: {
        C123: { allow: true, requireMention: true, allowBots: false },
        "#general": {
          allow: true,
          requireMention: true,
          allowBots: false,
          users: ["U123"],
          skills: ["docs"],
          systemPrompt: "Nur kurze Antworten.",
        },
      },
      historyLimit: 50,
      allowBots: false,
      reactionNotifications: "own",
      reactionAllowlist: ["U123"],
      replyToMode: "off", // off | first | all | batched
      thread: {
        historyScope: "thread", // thread | channel
        inheritParent: false,
      },
      actions: {
        reactions: true,
        messages: true,
        pins: true,
        memberInfo: true,
        emojiList: true,
      },
      slashCommand: {
        enabled: true,
        name: "openclaw",
        sessionPrefix: "slack:slash",
        ephemeral: true,
      },
      typingReaction: "hourglass_flowing_sand",
      textChunkLimit: 4000,
      chunkMode: "length",
      streaming: {
        mode: "partial", // off | partial | block | progress
        nativeTransport: true, // Slack-native Streaming-API verwenden, wenn mode=partial
      },
      mediaMaxMb: 20,
      execApprovals: {
        enabled: "auto", // true | false | "auto"
        approvers: ["U123"],
        agentFilter: ["default"],
        sessionFilter: ["slack:"],
        target: "dm", // dm | channel | both
      },
    },
  },
}

• Socket-Modus erfordert sowohl botToken als auch appToken (SLACK_BOT_TOKEN + SLACK_APP_TOKEN als Env-Fallback für das Standardkonto).
• HTTP-Modus erfordert botToken plus signingSecret (am Root oder pro Konto).
• botToken, appToken, signingSecret und userToken akzeptieren Klartextzeichenfolgen oder SecretRef-Objekte.
• Slack-Konto-Snapshots stellen pro Anmeldedaten Quelle-/Statusfelder wie botTokenSource, botTokenStatus, appTokenStatus und im HTTP-Modus signingSecretStatus bereit. configured_unavailable bedeutet, dass das Konto über SecretRef konfiguriert ist, der aktuelle Befehls-/Laufzeitpfad den Secret-Wert jedoch nicht auflösen konnte.
• configWrites: false blockiert von Slack initiierte Konfigurationsschreibvorgänge.
• Optional überschreibt channels.slack.defaultAccount die Standardkontenauswahl, wenn es mit einer konfigurierten Konto-ID übereinstimmt.
• channels.slack.streaming.mode ist der kanonische Schlüssel für den Slack-Stream-Modus. channels.slack.streaming.nativeTransport steuert den nativen Streaming-Transport von Slack. Veraltete Werte streamMode, boolesche streaming-Werte und nativeStreaming werden automatisch migriert.
• Verwenden Sie user:<id> (DM) oder channel:<id> für Zustellungsziele.

• Slack-natives Streaming sowie der Slack-assistentenartige Thread-Status „is typing…“ erfordern ein Antwort-Thread-Ziel. DMs auf oberster Ebene bleiben standardmäßig außerhalb von Threads, daher verwenden sie stattdessen typingReaction oder normale Zustellung anstelle der Thread-Vorschau.
• typingReaction fügt der eingehenden Slack-Nachricht während der Antwortausführung vorübergehend eine Reaktion hinzu und entfernt sie nach Abschluss wieder. Verwenden Sie einen Slack-Emoji-Shortcode wie "hourglass_flowing_sand".
• channels.slack.execApprovals: Slack-native Zustellung von Exec-Genehmigungen und Autorisierung von Genehmigern. Gleiches Schema wie bei Discord: enabled (true/false/"auto"), approvers (Slack-Benutzer-IDs), agentFilter, sessionFilter und target ("dm", "channel" oder "both").

​

Mattermost

{
  channels: {
    mattermost: {
      enabled: true,
      botToken: "mm-token",
      baseUrl: "https://chat.example.com",
      dmPolicy: "pairing",
      chatmode: "oncall", // oncall | onmessage | onchar
      oncharPrefixes: [">", "!"],
      groups: {
        "*": { requireMention: true },
        "team-channel-id": { requireMention: false },
      },
      commands: {
        native: true, // Opt-in
        nativeSkills: true,
        callbackPath: "/api/channels/mattermost/command",
        // Optional explizite URL für Reverse-Proxy-/öffentliche Deployments
        callbackUrl: "https://gateway.example.com/api/channels/mattermost/command",
      },
      textChunkLimit: 4000,
      chunkMode: "length",
    },
  },
}

• commands.callbackPath muss ein Pfad sein (zum Beispiel /api/channels/mattermost/command), keine vollständige URL.
• commands.callbackUrl muss zum OpenClaw-Gateway-Endpunkt aufgelöst werden und vom Mattermost-Server aus erreichbar sein.
• Native Slash-Callbacks werden mit den pro Befehl verwendeten Token authentifiziert, die Mattermost bei der Registrierung von Slash-Befehlen zurückgibt. Wenn die Registrierung fehlschlägt oder keine Befehle aktiviert werden, lehnt OpenClaw Callbacks mit Unauthorized: invalid command token. ab.
• Für private/Tailnet-/interne Callback-Hosts kann Mattermost verlangen, dass ServiceSettings.AllowedUntrustedInternalConnections den Callback-Host bzw. die Domain enthält. Verwenden Sie Host-/Domainwerte, keine vollständigen URLs.
• channels.mattermost.configWrites: Mattermost-initiierte Konfigurationsschreibvorgänge erlauben oder verweigern.
• channels.mattermost.requireMention: @mention vor der Antwort in Kanälen verlangen.
• channels.mattermost.groups.<channelId>.requireMention: Überschreibung des Mention-Gatings pro Kanal ("*" für Standard).
• Optional überschreibt channels.mattermost.defaultAccount die Standardkontenauswahl, wenn es mit einer konfigurierten Konto-ID übereinstimmt.

​

Signal

{
  channels: {
    signal: {
      enabled: true,
      account: "+15555550123", // optionale Kontobindung
      dmPolicy: "pairing",
      allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"],
      configWrites: true,
      reactionNotifications: "own", // off | own | all | allowlist
      reactionAllowlist: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"],
      historyLimit: 50,
    },
  },
}

• channels.signal.account: Kanalstart auf eine bestimmte Signal-Kontoidentität festlegen.
• channels.signal.configWrites: von Signal initiierte Konfigurationsschreibvorgänge erlauben oder verweigern.
• Optional überschreibt channels.signal.defaultAccount die Standardkontenauswahl, wenn es mit einer konfigurierten Konto-ID übereinstimmt.

​

BlueBubbles

{
  channels: {
    bluebubbles: {
      enabled: true,
      dmPolicy: "pairing",
      // serverUrl, password, webhookPath, group controls, and advanced actions:
      // siehe /channels/bluebubbles
    },
  },
}

• Zentrale Schlüsselpfade, die hier behandelt werden: channels.bluebubbles, channels.bluebubbles.dmPolicy.
• Optional überschreibt channels.bluebubbles.defaultAccount die Standardkontenauswahl, wenn es mit einer konfigurierten Konto-ID übereinstimmt.
• Top-Level-Einträge in bindings[] mit type: "acp" können BlueBubbles-Unterhaltungen an persistente ACP-Sitzungen binden. Verwenden Sie einen BlueBubbles-Handle oder Ziel-String (chat_id:*, chat_guid:*, chat_identifier:*) in match.peer.id. Gemeinsame Feldsemantik: ACP Agents.
• Die vollständige BlueBubbles-Kanalkonfiguration ist unter BlueBubbles dokumentiert.

​

iMessage

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "imsg",
      dbPath: "~/Library/Messages/chat.db",
      remoteHost: "user@gateway-host",
      dmPolicy: "pairing",
      allowFrom: ["+15555550123", "user@example.com", "chat_id:123"],
      historyLimit: 50,
      includeAttachments: false,
      attachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      mediaMaxMb: 16,
      service: "auto",
      region: "US",
    },
  },
}

• Optional überschreibt channels.imessage.defaultAccount die Standardkontenauswahl, wenn es mit einer konfigurierten Konto-ID übereinstimmt.
• Erfordert Vollzugriff auf die Messages-Datenbank.
• Bevorzugen Sie Ziele im Format chat_id:<id>. Verwenden Sie imsg chats --limit 20, um Chats aufzulisten.
• cliPath kann auf einen SSH-Wrapper zeigen; setzen Sie remoteHost (host oder user@host) für den SCP-Abruf von Anhängen.
• attachmentRoots und remoteAttachmentRoots beschränken eingehende Anhangspfade (Standard: /Users/*/Library/Messages/Attachments).
• SCP verwendet strikte Host-Key-Prüfung, daher muss der Relay-Host-Key bereits in ~/.ssh/known_hosts vorhanden sein.
• channels.imessage.configWrites: von iMessage initiierte Konfigurationsschreibvorgänge erlauben oder verweigern.
• Top-Level-Einträge in bindings[] mit type: "acp" können iMessage-Unterhaltungen an persistente ACP-Sitzungen binden. Verwenden Sie einen normalisierten Handle oder ein explizites Chat-Ziel (chat_id:*, chat_guid:*, chat_identifier:*) in match.peer.id. Gemeinsame Feldsemantik: ACP Agents.

#!/usr/bin/env bash
exec ssh -T gateway-host imsg "$@"

​

Matrix

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_bot_xxx",
      proxy: "http://127.0.0.1:7890",
      encryption: true,
      initialSyncLimit: 20,
      defaultAccount: "ops",
      accounts: {
        ops: {
          name: "Ops",
          userId: "@ops:example.org",
          accessToken: "syt_ops_xxx",
        },
        alerts: {
          userId: "@alerts:example.org",
          password: "secret",
          proxy: "http://127.0.0.1:7891",
        },
      },
    },
  },
}

• Token-Authentifizierung verwendet accessToken; Passwort-Authentifizierung verwendet userId + password.
• channels.matrix.proxy leitet Matrix-HTTP-Datenverkehr über einen expliziten HTTP(S)-Proxy. Benannte Konten können ihn mit channels.matrix.accounts.<id>.proxy überschreiben.
• channels.matrix.network.dangerouslyAllowPrivateNetwork erlaubt private/interne Homeserver. proxy und dieses Netzwerk-Opt-in sind unabhängige Steuerungen.
• channels.matrix.defaultAccount wählt in Setups mit mehreren Konten das bevorzugte Konto aus.
• channels.matrix.autoJoin ist standardmäßig off, daher werden eingeladene Räume und neue DM-artige Einladungen ignoriert, bis Sie autoJoin: "allowlist" mit autoJoinAllowlist oder autoJoin: "always" setzen.
• channels.matrix.execApprovals: Matrix-native Zustellung von Exec-Genehmigungen und Autorisierung von Genehmigern.
  • enabled: true, false oder "auto" (Standard). Im Auto-Modus werden Exec-Genehmigungen aktiviert, wenn Genehmiger aus approvers oder commands.ownerAllowFrom aufgelöst werden können.
  • approvers: Matrix-Benutzer-IDs (z. B. @owner:example.org), die Exec-Anfragen genehmigen dürfen.
  • agentFilter: optionale Erlaubnisliste für Agent-IDs. Weglassen, um Genehmigungen für alle Agenten weiterzuleiten.
  • sessionFilter: optionale Sitzungs-Schlüsselmuster (Teilzeichenfolge oder Regex).
  • target: wohin Genehmigungsaufforderungen gesendet werden. "dm" (Standard), "channel" (Ursprungsraum) oder "both".
  • Überschreibungen pro Konto: channels.matrix.accounts.<id>.execApprovals.
• channels.matrix.dm.sessionScope steuert, wie Matrix-DMs in Sitzungen gruppiert werden: per-user (Standard) teilt nach weitergeleitetem Peer, während per-room jeden DM-Raum isoliert.
• Matrix-Statusprüfungen und Live-Verzeichnissuchen verwenden dieselbe Proxy-Richtlinie wie Laufzeitdatenverkehr.
• Die vollständige Matrix-Konfiguration, Zielregeln und Setup-Beispiele sind unter Matrix dokumentiert.

​

Microsoft Teams

{
  channels: {
    msteams: {
      enabled: true,
      configWrites: true,
      // appId, appPassword, tenantId, webhook, team/channel policies:
      // siehe /channels/msteams
    },
  },
}

• Zentrale Schlüsselpfade, die hier behandelt werden: channels.msteams, channels.msteams.configWrites.
• Die vollständige Teams-Konfiguration (Anmeldedaten, Webhook, DM-/Gruppenrichtlinie, Überschreibungen pro Team/pro Kanal) ist unter Microsoft Teams dokumentiert.

​

IRC

{
  channels: {
    irc: {
      enabled: true,
      dmPolicy: "pairing",
      configWrites: true,
      nickserv: {
        enabled: true,
        service: "NickServ",
        password: "${IRC_NICKSERV_PASSWORD}",
        register: false,
        registerEmail: "bot@example.com",
      },
    },
  },
}

• Zentrale Schlüsselpfade, die hier behandelt werden: channels.irc, channels.irc.dmPolicy, channels.irc.configWrites, channels.irc.nickserv.*.
• Optional überschreibt channels.irc.defaultAccount die Standardkontenauswahl, wenn es mit einer konfigurierten Konto-ID übereinstimmt.
• Die vollständige IRC-Kanalkonfiguration (Host/Port/TLS/Kanäle/Erlaubnislisten/Mention-Gating) ist unter IRC dokumentiert.

​

Mehrere Konten (alle Kanäle)

{
  channels: {
    telegram: {
      accounts: {
        default: {
          name: "Primärer Bot",
          botToken: "123456:ABC...",
        },
        alerts: {
          name: "Alerts-Bot",
          botToken: "987654:XYZ...",
        },
      },
    },
  },
}

• default wird verwendet, wenn accountId weggelassen wird (CLI + Routing).
• Env-Tokens gelten nur für das default-Konto.
• Basis-Kanaleinstellungen gelten für alle Konten, sofern sie nicht pro Konto überschrieben werden.
• Verwenden Sie bindings[].match.accountId, um jedes Konto an einen anderen Agenten weiterzuleiten.
• Wenn Sie über openclaw channels add (oder Kanal-Onboarding) ein Nicht-Standardkonto hinzufügen, während Sie sich noch auf einer Top-Level-Kanalkonfiguration für ein einzelnes Konto befinden, verschiebt OpenClaw zunächst kontobezogene Top-Level-Werte für ein einzelnes Konto in die Kontozuordnung des Kanals, damit das ursprüngliche Konto weiter funktioniert. Die meisten Kanäle verschieben sie nach channels.<channel>.accounts.default; Matrix kann stattdessen ein vorhandenes passendes benanntes/default-Ziel beibehalten.
• Bestehende nur kanalbezogene Bindings (ohne accountId) passen weiterhin auf das Standardkonto; kontoabhängige Bindings bleiben optional.
• openclaw doctor --fix repariert auch gemischte Formen, indem kontobezogene Top-Level-Werte für ein einzelnes Konto in das für diesen Kanal ausgewählte verschobene Konto verschoben werden. Die meisten Kanäle verwenden accounts.default; Matrix kann stattdessen ein vorhandenes passendes benanntes/default-Ziel beibehalten.

​

Andere extension-basierte Kanäle

​

Mention-Gating in Gruppenchats

• Metadaten-Erwähnungen: Native Plattform-@-Erwähnungen. Im WhatsApp-Selbstchat-Modus ignoriert.
• Textmuster: Sichere Regex-Muster in agents.list[].groupChat.mentionPatterns. Ungültige Muster und unsichere verschachtelte Wiederholungen werden ignoriert.
• Mention-Gating wird nur erzwungen, wenn eine Erkennung möglich ist (native Erwähnungen oder mindestens ein Muster).

{
  messages: {
    groupChat: { historyLimit: 50 },
  },
  agents: {
    list: [{ id: "main", groupChat: { mentionPatterns: ["@openclaw", "openclaw"] } }],
  },
}

​

DM-Verlaufsgrenzen

{
  channels: {
    telegram: {
      dmHistoryLimit: 30,
      dms: {
        "123456789": { historyLimit: 50 },
      },
    },
  },
}

​

Selbstchat-Modus

{
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: { mentionPatterns: ["reisponde", "@openclaw"] },
      },
    ],
  },
}

​

Befehle (Chat-Befehlsverarbeitung)

{
  commands: {
    native: "auto", // native Befehle registrieren, wenn unterstützt
    nativeSkills: "auto", // native Skills-Befehle registrieren, wenn unterstützt
    text: true, // /commands in Chat-Nachrichten parsen
    bash: false, // ! erlauben (Alias: /bash)
    bashForegroundMs: 2000,
    config: false, // /config erlauben
    mcp: false, // /mcp erlauben
    plugins: false, // /plugins erlauben
    debug: false, // /debug erlauben
    restart: true, // /restart + Gateway-Neustart-Tool erlauben
    ownerAllowFrom: ["discord:123456789012345678"],
    ownerDisplay: "raw", // raw | hash
    ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}",
    allowFrom: {
      "*": ["user1"],
      discord: ["user:123"],
    },
    useAccessGroups: true,
  },
}

​

Agent-Standardeinstellungen

​

agents.defaults.workspace

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
}

​

agents.defaults.repoRoot

{
  agents: { defaults: { repoRoot: "~/Projects/openclaw" } },
}

​

agents.defaults.skills

{
  agents: {
    defaults: { skills: ["github", "weather"] },
    list: [
      { id: "writer" }, // erbt github, weather
      { id: "docs", skills: ["docs-search"] }, // ersetzt Standardwerte
      { id: "locked-down", skills: [] }, // keine Skills
    ],
  },
}

• Lassen Sie agents.defaults.skills weg, um standardmäßig uneingeschränkte Skills zu erlauben.
• Lassen Sie agents.list[].skills weg, um die Standardwerte zu erben.
• Setzen Sie agents.list[].skills: [] für keine Skills.
• Eine nicht leere Liste in agents.list[].skills ist die endgültige Menge für diesen Agenten; sie wird nicht mit den Standardwerten zusammengeführt.

​

agents.defaults.skipBootstrap

{
  agents: { defaults: { skipBootstrap: true } },
}

​

agents.defaults.contextInjection

• "continuation-skip": Sichere Fortsetzungs-Turns (nach einer abgeschlossenen Assistant-Antwort) überspringen das erneute Einfügen des Workspace-Bootstraps, wodurch die Prompt-Größe reduziert wird. Heartbeat-Läufe und Wiederholungen nach Kompaktierung bauen den Kontext weiterhin neu auf.

{
  agents: { defaults: { contextInjection: "continuation-skip" } },
}

​

agents.defaults.bootstrapMaxChars

{
  agents: { defaults: { bootstrapMaxChars: 20000 } },
}

​

agents.defaults.bootstrapTotalMaxChars

{
  agents: { defaults: { bootstrapTotalMaxChars: 150000 } },
}

​

agents.defaults.bootstrapPromptTruncationWarning

• "off": Niemals Warntext in den System-Prompt einfügen.
• "once": Warnung einmal pro eindeutiger Kürzungssignatur einfügen (empfohlen).
• "always": Warnung bei jedem Lauf einfügen, wenn eine Kürzung vorliegt.

{
  agents: { defaults: { bootstrapPromptTruncationWarning: "once" } }, // off | once | always
}

​

agents.defaults.imageMaxDimensionPx

{
  agents: { defaults: { imageMaxDimensionPx: 1200 } },
}

​

agents.defaults.userTimezone

{
  agents: { defaults: { userTimezone: "America/Chicago" } },
}

​

agents.defaults.timeFormat

{
  agents: { defaults: { timeFormat: "auto" } }, // auto | 12 | 24
}

​

agents.defaults.model

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-6": { alias: "opus" },
        "minimax/MiniMax-M2.7": { alias: "minimax" },
      },
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["minimax/MiniMax-M2.7"],
      },
      imageModel: {
        primary: "openrouter/qwen/qwen-2.5-vl-72b-instruct:free",
        fallbacks: ["openrouter/google/gemini-2.0-flash-vision:free"],
      },
      imageGenerationModel: {
        primary: "openai/gpt-image-1",
        fallbacks: ["google/gemini-3.1-flash-image-preview"],
      },
      videoGenerationModel: {
        primary: "qwen/wan2.6-t2v",
        fallbacks: ["qwen/wan2.6-i2v"],
      },
      pdfModel: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["openai/gpt-5.4-mini"],
      },
      params: { cacheRetention: "long" }, // globale Standard-Provider-Parameter
      pdfMaxBytesMb: 10,
      pdfMaxPages: 20,
      thinkingDefault: "low",
      verboseDefault: "off",
      elevatedDefault: "on",
      timeoutSeconds: 600,
      mediaMaxMb: 5,
      contextTokens: 200000,
      maxConcurrent: 3,
    },
  },
}

• model: akzeptiert entweder eine Zeichenfolge ("provider/model") oder ein Objekt ({ primary, fallbacks }).
  • Die Zeichenfolgenform setzt nur das primäre Modell.
  • Die Objektform setzt das primäre Modell plus geordnete Failover-Modelle.
• imageModel: akzeptiert entweder eine Zeichenfolge ("provider/model") oder ein Objekt ({ primary, fallbacks }).
  • Wird vom Tool-Pfad image als Vision-Modellkonfiguration verwendet.
  • Wird auch als Fallback-Routing verwendet, wenn das ausgewählte/standardmäßige Modell keine Bildeingaben akzeptieren kann.
• imageGenerationModel: akzeptiert entweder eine Zeichenfolge ("provider/model") oder ein Objekt ({ primary, fallbacks }).
  • Wird von der gemeinsamen Bildgenerierungsfunktion und jeder zukünftigen Tool-/Plugin-Oberfläche verwendet, die Bilder generiert.
  • Typische Werte: google/gemini-3.1-flash-image-preview für native Gemini-Bildgenerierung, fal/fal-ai/flux/dev für fal oder openai/gpt-image-1 für OpenAI Images.
  • Wenn Sie direkt einen Provider/ein Modell auswählen, konfigurieren Sie auch die passende Provider-Authentifizierung bzw. den API-Schlüssel (zum Beispiel GEMINI_API_KEY oder GOOGLE_API_KEY für google/*, OPENAI_API_KEY für openai/*, FAL_KEY für fal/*).
  • Wenn weggelassen, kann image_generate dennoch einen authentifizierungsbasierten Provider-Standard ableiten. Es versucht zuerst den aktuellen Standard-Provider, dann die übrigen registrierten Bildgenerierungs-Provider in Provider-ID-Reihenfolge.
• musicGenerationModel: akzeptiert entweder eine Zeichenfolge ("provider/model") oder ein Objekt ({ primary, fallbacks }).
  • Wird von der gemeinsamen Musikgenerierungsfunktion und dem integrierten Tool music_generate verwendet.
  • Typische Werte: google/lyria-3-clip-preview, google/lyria-3-pro-preview oder minimax/music-2.5+.
  • Wenn weggelassen, kann music_generate dennoch einen authentifizierungsbasierten Provider-Standard ableiten. Es versucht zuerst den aktuellen Standard-Provider, dann die übrigen registrierten Musikgenerierungs-Provider in Provider-ID-Reihenfolge.
  • Wenn Sie direkt einen Provider/ein Modell auswählen, konfigurieren Sie auch die passende Provider-Authentifizierung bzw. den API-Schlüssel.
• videoGenerationModel: akzeptiert entweder eine Zeichenfolge ("provider/model") oder ein Objekt ({ primary, fallbacks }).
  • Wird von der gemeinsamen Videogenerierungsfunktion und dem integrierten Tool video_generate verwendet.
  • Typische Werte: qwen/wan2.6-t2v, qwen/wan2.6-i2v, qwen/wan2.6-r2v, qwen/wan2.6-r2v-flash oder qwen/wan2.7-r2v.
  • Wenn weggelassen, kann video_generate dennoch einen authentifizierungsbasierten Provider-Standard ableiten. Es versucht zuerst den aktuellen Standard-Provider, dann die übrigen registrierten Videogenerierungs-Provider in Provider-ID-Reihenfolge.
  • Wenn Sie direkt einen Provider/ein Modell auswählen, konfigurieren Sie auch die passende Provider-Authentifizierung bzw. den API-Schlüssel.
  • Der gebündelte Qwen-Provider für Videogenerierung unterstützt bis zu 1 Ausgabevideo, 1 Eingabebild, 4 Eingabevideos, 10 Sekunden Dauer sowie Provider-Level-Optionen size, aspectRatio, resolution, audio und watermark.
• pdfModel: akzeptiert entweder eine Zeichenfolge ("provider/model") oder ein Objekt ({ primary, fallbacks }).
  • Wird vom Tool pdf für Modell-Routing verwendet.
  • Wenn weggelassen, fällt das PDF-Tool auf imageModel und dann auf das aufgelöste Sitzungs-/Standardmodell zurück.
• pdfMaxBytesMb: Standardgrenze für die PDF-Größe für das Tool pdf, wenn maxBytesMb nicht zur Aufrufzeit übergeben wird.
• pdfMaxPages: Standardmaximum an Seiten, die der Extraktions-Fallback-Modus im Tool pdf berücksichtigt.
• verboseDefault: Standard-Verbose-Level für Agenten. Werte: "off", "on", "full". Standard: "off".
• elevatedDefault: Standard-Level für erhöhte Ausgabe für Agenten. Werte: "off", "on", "ask", "full". Standard: "on".
• model.primary: Format provider/model (z. B. openai/gpt-5.4). Wenn Sie den Provider weglassen, versucht OpenClaw zuerst einen Alias, dann eine eindeutige konfigurierte Provider-Übereinstimmung für genau diese Modell-ID und fällt erst dann auf den konfigurierten Standard-Provider zurück (veraltetes Kompatibilitätsverhalten, daher provider/model explizit bevorzugen). Wenn dieser Provider das konfigurierte Standardmodell nicht mehr anbietet, fällt OpenClaw auf das erste konfigurierte Provider-/Modellpaar zurück, statt einen veralteten entfernten Provider-Standard anzuzeigen.
• models: der konfigurierte Modellkatalog und die Erlaubnisliste für /model. Jeder Eintrag kann alias (Kurzform) und params (providerbezogen, zum Beispiel temperature, maxTokens, cacheRetention, context1m) enthalten.
• params: globale Standard-Provider-Parameter, die auf alle Modelle angewendet werden. Festgelegt unter agents.defaults.params (z. B. { cacheRetention: "long" }).
• params-Merge-Priorität (Konfiguration): agents.defaults.params (globale Basis) wird von agents.defaults.models["provider/model"].params (pro Modell) überschrieben, dann überschreibt agents.list[].params (passende Agent-ID) schlüsselweise. Details siehe Prompt Caching.
• Konfigurationsschreiber, die diese Felder ändern (zum Beispiel /models set, /models set-image und Befehle zum Hinzufügen/Entfernen von Fallbacks), speichern die kanonische Objektform und erhalten vorhandene Fallback-Listen nach Möglichkeit.
• maxConcurrent: maximale Anzahl paralleler Agent-Läufe über Sitzungen hinweg (jede Sitzung bleibt weiterhin serialisiert). Standard: 4.

​

agents.defaults.cliBackends

{
  agents: {
    defaults: {
      cliBackends: {
        "codex-cli": {
          command: "/opt/homebrew/bin/codex",
        },
        "my-cli": {
          command: "my-cli",
          args: ["--json"],
          output: "json",
          modelArg: "--model",
          sessionArg: "--session",
          sessionMode: "existing",
          systemPromptArg: "--system",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
        },
      },
    },
  },
}

• CLI-Backends sind textorientiert; Tools sind immer deaktiviert.
• Sitzungen werden unterstützt, wenn sessionArg gesetzt ist.
• Bilddurchreichung wird unterstützt, wenn imageArg Dateipfade akzeptiert.

​

agents.defaults.systemPromptOverride

{
  agents: {
    defaults: {
      systemPromptOverride: "You are a helpful assistant.",
    },
  },
}

​

agents.defaults.heartbeat

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // 0m deaktiviert
        model: "openai/gpt-5.4-mini",
        includeReasoning: false,
        includeSystemPromptSection: true, // Standard: true; false lässt den Abschnitt Heartbeat im System-Prompt weg
        lightContext: false, // Standard: false; true behält nur HEARTBEAT.md aus den Workspace-Bootstrap-Dateien
        isolatedSession: false, // Standard: false; true führt jeden Heartbeat in einer neuen Sitzung aus (kein Gesprächsverlauf)
        session: "main",
        to: "+15555550123",
        directPolicy: "allow", // allow (Standard) | block
        target: "none", // Standard: none | Optionen: last | whatsapp | telegram | discord | ...
        prompt: "Read HEARTBEAT.md if it exists...",
        ackMaxChars: 300,
        suppressToolErrorWarnings: false,
      },
    },
  },
}

• every: Dauerzeichenfolge (ms/s/m/h). Standard: 30m (API-Key-Authentifizierung) oder 1h (OAuth-Authentifizierung). Setzen Sie 0m, um zu deaktivieren.
• includeSystemPromptSection: Wenn false, wird der Abschnitt Heartbeat aus dem System-Prompt weggelassen und das Einfügen von HEARTBEAT.md in den Bootstrap-Kontext übersprungen. Standard: true.
• suppressToolErrorWarnings: Wenn true, werden Warn-Payloads für Tool-Fehler während Heartbeat-Läufen unterdrückt.
• directPolicy: Richtlinie für direkte/DM-Zustellung. allow (Standard) erlaubt direkte Zielzustellung. block unterdrückt direkte Zielzustellung und gibt reason=dm-blocked aus.
• lightContext: Wenn true, verwenden Heartbeat-Läufe einen leichtgewichtigen Bootstrap-Kontext und behalten nur HEARTBEAT.md aus den Workspace-Bootstrap-Dateien.
• isolatedSession: Wenn true, wird jeder Heartbeat in einer neuen Sitzung ohne vorherigen Gesprächsverlauf ausgeführt. Dasselbe Isolationsmuster wie bei Cron sessionTarget: "isolated". Reduziert die Tokenkosten pro Heartbeat von ~100K auf ~2–5K Tokens.
• Pro Agent: Setzen Sie agents.list[].heartbeat. Wenn ein Agent heartbeat definiert, führen nur diese Agenten Heartbeats aus.
• Heartbeats führen vollständige Agent-Turns aus — kürzere Intervalle verbrauchen mehr Tokens.

​

agents.defaults.compaction

{
  agents: {
    defaults: {
      compaction: {
        mode: "safeguard", // default | safeguard
        provider: "my-provider", // ID eines registrierten Compaction-Provider-Plugins (optional)
        timeoutSeconds: 900,
        reserveTokensFloor: 24000,
        identifierPolicy: "strict", // strict | off | custom
        identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // verwendet, wenn identifierPolicy=custom
        postCompactionSections: ["Session Startup", "Red Lines"], // [] deaktiviert erneutes Einfügen
        model: "openrouter/anthropic/claude-sonnet-4-6", // optionale nur für Compaction geltende Modellüberschreibung
        notifyUser: true, // sendet eine kurze Mitteilung, wenn Compaction beginnt (Standard: false)
        memoryFlush: {
          enabled: true,
          softThresholdTokens: 6000,
          systemPrompt: "Session nearing compaction. Store durable memories now.",
          prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with the exact silent token NO_REPLY if nothing to store.",
        },
      },
    },
  },
}

• mode: default oder safeguard (stapelweise Zusammenfassung für lange Verläufe). Siehe Compaction.
• provider: ID eines registrierten Compaction-Provider-Plugins. Wenn gesetzt, wird summarize() des Providers anstelle der integrierten LLM-Zusammenfassung aufgerufen. Bei Fehlern erfolgt ein Fallback auf die integrierte Zusammenfassung. Das Setzen eines Providers erzwingt mode: "safeguard". Siehe Compaction.
• timeoutSeconds: maximale Anzahl an Sekunden für einen einzelnen Compaction-Vorgang, bevor OpenClaw ihn abbricht. Standard: 900.
• identifierPolicy: strict (Standard), off oder custom. strict stellt der Compaction-Zusammenfassung integrierte Hinweise zur Beibehaltung opaker Bezeichner voran.
• identifierInstructions: optionaler benutzerdefinierter Text zur Beibehaltung von Bezeichnern, verwendet bei identifierPolicy=custom.
• postCompactionSections: optionale H2-/H3-Abschnittsnamen aus AGENTS.md, die nach der Compaction erneut eingefügt werden. Standard ist ["Session Startup", "Red Lines"]; setzen Sie [], um das erneute Einfügen zu deaktivieren. Wenn nicht gesetzt oder explizit auf dieses Standardpaar gesetzt, werden ältere Überschriften Every Session/Safety auch als Legacy-Fallback akzeptiert.
• model: optionale Überschreibung provider/model-id nur für die Compaction-Zusammenfassung. Verwenden Sie dies, wenn die Hauptsitzung ein Modell beibehalten soll, Compaction-Zusammenfassungen aber auf einem anderen laufen sollen; wenn nicht gesetzt, verwendet Compaction das primäre Modell der Sitzung.
• notifyUser: sendet bei true eine kurze Mitteilung an den Benutzer, wenn Compaction beginnt (zum Beispiel „Kontext wird komprimiert…“). Standardmäßig deaktiviert, damit Compaction still bleibt.
• memoryFlush: stiller agentischer Turn vor der automatischen Compaction, um dauerhafte Memories zu speichern. Wird übersprungen, wenn der Workspace schreibgeschützt ist.

​

agents.defaults.contextPruning

{
  agents: {
    defaults: {
      contextPruning: {
        mode: "cache-ttl", // off | cache-ttl
        ttl: "1h", // Dauer (ms/s/m/h), Standardeinheit: Minuten
        keepLastAssistants: 3,
        softTrimRatio: 0.3,
        hardClearRatio: 0.5,
        minPrunableToolChars: 50000,
        softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 },
        hardClear: { enabled: true, placeholder: "[Alter Inhalt des Tool-Ergebnisses gelöscht]" },
        tools: { deny: ["browser", "canvas"] },
      },
    },
  },
}

​

Block-Streaming

{
  agents: {
    defaults: {
      blockStreamingDefault: "off", // on | off
      blockStreamingBreak: "text_end", // text_end | message_end
      blockStreamingChunk: { minChars: 800, maxChars: 1200 },
      blockStreamingCoalesce: { idleMs: 1000 },
      humanDelay: { mode: "natural" }, // off | natural | custom (verwenden Sie minMs/maxMs)
    },
  },
}

• Nicht-Telegram-Kanäle erfordern explizit *.blockStreaming: true, um Block-Antworten zu aktivieren.
• Kanalüberschreibungen: channels.<channel>.blockStreamingCoalesce (und Varianten pro Konto). Signal/Slack/Discord/Google Chat verwenden standardmäßig minChars: 1500.
• humanDelay: zufällige Pause zwischen Block-Antworten. natural = 800–2500 ms. Überschreibung pro Agent: agents.list[].humanDelay.

​

Tippindikatoren

{
  agents: {
    defaults: {
      typingMode: "instant", // never | instant | thinking | message
      typingIntervalSeconds: 6,
    },
  },
}

• Standardwerte: instant für Direktchats/Erwähnungen, message für nicht erwähnte Gruppenchats.
• Überschreibungen pro Sitzung: session.typingMode, session.typingIntervalSeconds.

​

agents.defaults.sandbox

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        backend: "docker", // docker | ssh | openshell
        scope: "agent", // session | agent | shared
        workspaceAccess: "none", // none | ro | rw
        workspaceRoot: "~/.openclaw/sandboxes",
        docker: {
          image: "openclaw-sandbox:bookworm-slim",
          containerPrefix: "openclaw-sbx-",
          workdir: "/workspace",
          readOnlyRoot: true,
          tmpfs: ["/tmp", "/var/tmp", "/run"],
          network: "none",
          user: "1000:1000",
          capDrop: ["ALL"],
          env: { LANG: "C.UTF-8" },
          setupCommand: "apt-get update && apt-get install -y git curl jq",
          pidsLimit: 256,
          memory: "1g",
          memorySwap: "2g",
          cpus: 1,
          ulimits: {
            nofile: { soft: 1024, hard: 2048 },
            nproc: 256,
          },
          seccompProfile: "/path/to/seccomp.json",
          apparmorProfile: "openclaw-sandbox",
          dns: ["1.1.1.1", "8.8.8.8"],
          extraHosts: ["internal.service:10.0.0.5"],
          binds: ["/home/user/source:/source:rw"],
        },
        ssh: {
          target: "user@gateway-host:22",
          command: "ssh",
          workspaceRoot: "/tmp/openclaw-sandboxes",
          strictHostKeyChecking: true,
          updateHostKeys: true,
          identityFile: "~/.ssh/id_ed25519",
          certificateFile: "~/.ssh/id_ed25519-cert.pub",
          knownHostsFile: "~/.ssh/known_hosts",
          // SecretRefs / Inline-Inhalte werden ebenfalls unterstützt:
          // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },
          // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },
          // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },
        },
        browser: {
          enabled: false,
          image: "openclaw-sandbox-browser:bookworm-slim",
          network: "openclaw-sandbox-browser",
          cdpPort: 9222,
          cdpSourceRange: "172.21.0.1/32",
          vncPort: 5900,
          noVncPort: 6080,
          headless: false,
          enableNoVnc: true,
          allowHostControl: false,
          autoStart: true,
          autoStartTimeoutMs: 12000,
        },
        prune: {
          idleHours: 24,
          maxAgeDays: 7,
        },
      },
    },
  },
  tools: {
    sandbox: {
      tools: {
        allow: [
          "exec",
          "process",
          "read",
          "write",
          "edit",
          "apply_patch",
          "sessions_list",
          "sessions_history",
          "sessions_send",
          "sessions_spawn",
          "session_status",
        ],
        deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"],
      },
    },
  },
}

{
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          mode: "mirror", // mirror | remote
          from: "openclaw",
          remoteWorkspaceDir: "/sandbox",
          remoteAgentWorkspaceDir: "/agent",
          gateway: "lab", // optional
          gatewayEndpoint: "https://lab.example", // optional
          policy: "strict", // optionale OpenShell-Richtlinien-ID
          providers: ["openai"], // optional
          autoProviders: true,
          timeoutSeconds: 120,
        },
      },
    },
  },
}

scripts/sandbox-setup.sh           # Haupt-Sandbox-Image
scripts/sandbox-browser-setup.sh   # optionales Browser-Image

​

agents.list (Überschreibungen pro Agent)

{
  agents: {
    list: [
      {
        id: "main",
        default: true,
        name: "Hauptagent",
        workspace: "~/.openclaw/workspace",
        agentDir: "~/.openclaw/agents/main/agent",
        model: "anthropic/claude-opus-4-6", // oder { primary, fallbacks }
        thinkingDefault: "high", // Überschreibung des Standard-Thinking-Levels pro Agent
        reasoningDefault: "on", // Überschreibung der Standard-Sichtbarkeit von Reasoning pro Agent
        fastModeDefault: false, // Überschreibung des Standard-Schnellmodus pro Agent
        params: { cacheRetention: "none" }, // überschreibt passende defaults.models-Parameter schlüsselweise
        skills: ["docs-search"], // ersetzt agents.defaults.skills, wenn gesetzt
        identity: {
          name: "Samantha",
          theme: "hilfreiches Faultier",
          emoji: "🦥",
          avatar: "avatars/samantha.png",
        },
        groupChat: { mentionPatterns: ["@openclaw"] },
        sandbox: { mode: "off" },
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
        subagents: { allowAgents: ["*"] },
        tools: {
          profile: "coding",
          allow: ["browser"],
          deny: ["canvas"],
          elevated: { enabled: true },
        },
      },
    ],
  },
}

• id: stabile Agent-ID (erforderlich).
• default: wenn mehrere gesetzt sind, gewinnt der erste (Warnung wird protokolliert). Wenn keiner gesetzt ist, ist der erste Listeneintrag der Standard.
• model: Die Zeichenfolgenform überschreibt nur primary; die Objektform { primary, fallbacks } überschreibt beide ([] deaktiviert globale Fallbacks). Cron-Jobs, die nur primary überschreiben, erben weiterhin Standard-Fallbacks, sofern Sie nicht fallbacks: [] setzen.
• params: streambezogene Parameter pro Agent, die über dem ausgewählten Modelleintrag in agents.defaults.models zusammengeführt werden. Verwenden Sie dies für agentenspezifische Überschreibungen wie cacheRetention, temperature oder maxTokens, ohne den gesamten Modellkatalog zu duplizieren.
• skills: optionale Skill-Erlaubnisliste pro Agent. Wenn weggelassen, erbt der Agent agents.defaults.skills, sofern gesetzt; eine explizite Liste ersetzt Standardwerte, anstatt sie zusammenzuführen, und [] bedeutet keine Skills.
• thinkingDefault: optionales Standard-Thinking-Level pro Agent (off | minimal | low | medium | high | xhigh | adaptive). Überschreibt agents.defaults.thinkingDefault für diesen Agenten, wenn keine Überschreibung pro Nachricht oder Sitzung gesetzt ist.
• reasoningDefault: optionale Standard-Sichtbarkeit von Reasoning pro Agent (on | off | stream). Gilt, wenn keine Überschreibung von Reasoning pro Nachricht oder Sitzung gesetzt ist.
• fastModeDefault: optionaler Standardwert für den Schnellmodus pro Agent (true | false). Gilt, wenn keine Überschreibung des Schnellmodus pro Nachricht oder Sitzung gesetzt ist.
• runtime: optionale Laufzeitbeschreibung pro Agent. Verwenden Sie type: "acp" mit den Standardwerten in runtime.acp (agent, backend, mode, cwd), wenn der Agent standardmäßig ACP-Harness-Sitzungen verwenden soll.
• identity.avatar: workspace-relativer Pfad, http(s)-URL oder data:-URI.
• identity leitet Standardwerte ab: ackReaction aus emoji, mentionPatterns aus name/emoji.
• subagents.allowAgents: Erlaubnisliste von Agent-IDs für sessions_spawn (["*"] = beliebig; Standard: nur derselbe Agent).
• Sandbox-Vererbungs-Schutz: Wenn die anfordernde Sitzung in einer Sandbox läuft, lehnt sessions_spawn Ziele ab, die ohne Sandbox laufen würden.
• subagents.requireAgentId: Wenn true, blockiert sessions_spawn Aufrufe ohne agentId (erzwingt explizite Profilauswahl; Standard: false).

​

Routing mit mehreren Agenten

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

​

Binding-Match-Felder

• type (optional): route für normales Routing (fehlender Typ bedeutet standardmäßig route), acp für persistente ACP-Unterhaltungs-Bindings.
• match.channel (erforderlich)
• match.accountId (optional; * = beliebiges Konto; weggelassen = Standardkonto)
• match.peer (optional; { kind: direct|group|channel, id })
• match.guildId / match.teamId (optional; kanalspezifisch)
• acp (optional; nur für type: "acp"): { mode, label, cwd, backend }

1. match.peer
2. match.guildId
3. match.teamId
4. match.accountId (exakt, ohne Peer/Guild/Team)
5. match.accountId: "*" (kanalweit)
6. Standard-Agent

​

Zugriffsprofile pro Agent

{
  agents: {
    list: [
      {
        id: "personal",
        workspace: "~/.openclaw/workspace-personal",
        sandbox: { mode: "off" },
      },
    ],
  },
}

{
  agents: {
    list: [
      {
        id: "family",
        workspace: "~/.openclaw/workspace-family",
        sandbox: { mode: "all", scope: "agent", workspaceAccess: "ro" },
        tools: {
          allow: [
            "read",
            "sessions_list",
            "sessions_history",
            "sessions_send",
            "sessions_spawn",
            "session_status",
          ],
          deny: ["write", "edit", "apply_patch", "exec", "process", "browser"],
        },
      },
    ],
  },
}

{
  agents: {
    list: [
      {
        id: "public",
        workspace: "~/.openclaw/workspace-public",
        sandbox: { mode: "all", scope: "agent", workspaceAccess: "none" },
        tools: {
          allow: [
            "sessions_list",
            "sessions_history",
            "sessions_send",
            "sessions_spawn",
            "session_status",
            "whatsapp",
            "telegram",
            "slack",
            "discord",
            "gateway",
          ],
          deny: [
            "read",
            "write",
            "edit",
            "apply_patch",
            "exec",
            "process",
            "browser",
            "canvas",
            "nodes",
            "cron",
            "gateway",
            "image",
          ],
        },
      },
    ],
  },
}

​

Sitzung

{
  session: {
    scope: "per-sender",
    dmScope: "main", // main | per-peer | per-channel-peer | per-account-channel-peer
    identityLinks: {
      alice: ["telegram:123456789", "discord:987654321012345678"],
    },
    reset: {
      mode: "daily", // daily | idle
      atHour: 4,
      idleMinutes: 60,
    },
    resetByType: {
      thread: { mode: "daily", atHour: 4 },
      direct: { mode: "idle", idleMinutes: 240 },
      group: { mode: "idle", idleMinutes: 120 },
    },
    resetTriggers: ["/new", "/reset"],
    store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",
    parentForkMaxTokens: 100000, // Parent-Thread-Fork oberhalb dieser Token-Anzahl überspringen (0 deaktiviert)
    maintenance: {
      mode: "warn", // warn | enforce
      pruneAfter: "30d",
      maxEntries: 500,
      rotateBytes: "10mb",
      resetArchiveRetention: "30d", // Dauer oder false
      maxDiskBytes: "500mb", // optionales hartes Budget
      highWaterBytes: "400mb", // optionales Bereinigungsziel
    },
    threadBindings: {
      enabled: true,
      idleHours: 24, // Standard für automatisches Entfokussieren bei Inaktivität in Stunden (`0` deaktiviert)
      maxAgeHours: 0, // Standard für hartes maximales Alter in Stunden (`0` deaktiviert)
    },
    mainKey: "main", // Legacy (Laufzeit verwendet immer "main")
    agentToAgent: { maxPingPongTurns: 5 },
    sendPolicy: {
      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
      default: "allow",
    },
  },
}

​

Nachrichten

{
  messages: {
    responsePrefix: "🦞", // oder "auto"
    ackReaction: "👀",
    ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all
    removeAckAfterReply: false,
    queue: {
      mode: "collect", // steer | followup | collect | steer-backlog | steer+backlog | queue | interrupt
      debounceMs: 1000,
      cap: 20,
      drop: "summarize", // old | new | summarize
      byChannel: {
        whatsapp: "collect",
        telegram: "collect",
      },
    },
    inbound: {
      debounceMs: 2000, // 0 deaktiviert
      byChannel: {
        whatsapp: 5000,
        slack: 1500,
      },
    },
  },
}

​

Antwortpräfix

​

Bestätigungsreaktion

• Standardmäßig das identity.emoji des aktiven Agenten, andernfalls "👀". Setzen Sie "", um zu deaktivieren.
• Überschreibungen pro Kanal: channels.<channel>.ackReaction, channels.<channel>.accounts.<id>.ackReaction.
• Reihenfolge der Auflösung: Konto → Kanal → messages.ackReaction → Identity-Fallback.
• Scope: group-mentions (Standard), group-all, direct, all.
• removeAckAfterReply: entfernt die Bestätigungsreaktion nach der Antwort auf Slack, Discord und Telegram.
• messages.statusReactions.enabled: aktiviert Lifecycle-Statusreaktionen auf Slack, Discord und Telegram. Auf Slack und Discord bleibt bei nicht gesetztem Wert die Statusreaktion aktiviert, wenn Bestätigungsreaktionen aktiv sind. Auf Telegram muss sie explizit auf true gesetzt werden, um Lifecycle-Statusreaktionen zu aktivieren.

​

Inbound-Debounce

​

TTS (Text-to-Speech)

{
  messages: {
    tts: {
      auto: "always", // off | always | inbound | tagged
      mode: "final", // final | all
      provider: "elevenlabs",
      summaryModel: "openai/gpt-4.1-mini",
      modelOverrides: { enabled: true },
      maxTextLength: 4000,
      timeoutMs: 30000,
      prefsPath: "~/.openclaw/settings/tts.json",
      elevenlabs: {
        apiKey: "elevenlabs_api_key",
        baseUrl: "https://api.elevenlabs.io",
        voiceId: "voice_id",
        modelId: "eleven_multilingual_v2",
        seed: 42,
        applyTextNormalization: "auto",
        languageCode: "en",
        voiceSettings: {
          stability: 0.5,
          similarityBoost: 0.75,
          style: 0.0,
          useSpeakerBoost: true,
          speed: 1.0,
        },
      },
      openai: {
        apiKey: "openai_api_key",
        baseUrl: "https://api.openai.com/v1",
        model: "gpt-4o-mini-tts",
        voice: "alloy",
      },
    },
  },
}

• auto steuert den Standardmodus für automatisches TTS: off, always, inbound oder tagged. /tts on|off kann lokale Einstellungen überschreiben, und /tts status zeigt den effektiven Status an.
• summaryModel überschreibt agents.defaults.model.primary für die automatische Zusammenfassung.
• modelOverrides ist standardmäßig aktiviert; modelOverrides.allowProvider ist standardmäßig false (Opt-in).
• API-Schlüssel fallen auf ELEVENLABS_API_KEY/XI_API_KEY und OPENAI_API_KEY zurück.
• openai.baseUrl überschreibt den OpenAI-TTS-Endpunkt. Auflösungsreihenfolge ist Konfiguration, dann OPENAI_TTS_BASE_URL, dann https://api.openai.com/v1.
• Wenn openai.baseUrl auf einen Nicht-OpenAI-Endpunkt zeigt, behandelt OpenClaw ihn als OpenAI-kompatiblen TTS-Server und lockert die Modell-/Stimmenvalidierung.

​

Talk

{
  talk: {
    provider: "elevenlabs",
    providers: {
      elevenlabs: {
        voiceId: "elevenlabs_voice_id",
        voiceAliases: {
          Clawd: "EXAVITQu4vr4xnSDxMaL",
          Roger: "CwhRBWXzGAHq8TQ4Fs17",
        },
        modelId: "eleven_v3",
        outputFormat: "mp3_44100_128",
        apiKey: "elevenlabs_api_key",
      },
    },
    silenceTimeoutMs: 1500,
    interruptOnSpeech: true,
  },
}