Konfiguration — Kanäle

Kanalspezifische Konfigurationsschlüssel unter channels.*. Behandelt DM- und Gruppenzugriff, Multi-Account-Setups, Mention-Gating und kanalspezifische Schlüssel für Slack, Discord, Telegram, WhatsApp, Matrix, iMessage und die anderen gebündelten Channel-Plugins.

Für Agents, Tools, Gateway-Laufzeit und andere Schlüssel auf oberster Ebene siehe Konfigurationsreferenz.

# Kanäle

Jeder Kanal startet automatisch, wenn sein Konfigurationsabschnitt vorhanden ist (außer bei enabled: false).

# DM- und Gruppenzugriff

Alle Kanäle unterstützen DM-Richtlinien und Gruppenrichtlinien:

# Kanalmodell-Überschreibungen

Verwenden Sie channels.modelByChannel, um bestimmte Kanal-IDs an ein Modell zu binden. Werte akzeptieren provider/model oder konfigurierte Modellaliasnamen. Die Kanalzuordnung gilt, wenn eine Sitzung nicht bereits eine Modellüberschreibung hat (zum Beispiel per /model gesetzt).

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

# Kanalstandards und Heartbeat

Verwenden Sie channels.defaults für gemeinsame Gruppenrichtlinien- und Heartbeat-Verhalten über Provider hinweg:

{
  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 Provider-weite groupPolicy nicht gesetzt ist.
• channels.defaults.contextVisibility: Standardmodus für die Sichtbarkeit von zusätzlichem Kontext für alle Kanäle. Werte: all (Standard, gesamten zitierten/Thread-/Verlaufskontext einschließen), allowlist (nur Kontext von Absendern auf der Allowlist einschließen), allowlist_quote (wie Allowlist, aber expliziten Zitat-/Antwortkontext beibehalten). Kanalspezifische Überschreibung: channels.<channel>.contextVisibility.
• channels.defaults.heartbeat.showOk: Gesunde Kanalstatus in die Heartbeat-Ausgabe einschließen.
• channels.defaults.heartbeat.showAlerts: Herabgestufte/Fehlerstatus in die Heartbeat-Ausgabe einschließen.
• channels.defaults.heartbeat.useIndicator: Kompakte Heartbeat-Ausgabe im Indikatorstil rendern.

# WhatsApp

WhatsApp läuft über den Webkanal des Gateways (Baileys Web). Es startet automatisch, wenn eine verknüpfte Sitzung vorhanden ist.

{
  web: {
    enabled: true,
    heartbeatSeconds: 60,
    whatsapp: {
      keepAliveIntervalMs: 25000,
      connectTimeoutMs: 60000,
      defaultQueryTimeoutMs: 60000,
    },
    reconnect: {
      initialMs: 2000,
      maxMs: 120000,
      factor: 1.4,
      jitter: 0.2,
      maxAttempts: 0,
    },
  },
  channels: {
    whatsapp: {
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["+15555550123", "+447700900123"],
      textChunkLimit: 4000,
      chunkMode: "length", // length | newline
      mediaMaxMb: 50,
      sendReadReceipts: true, // blue ticks (false in self-chat mode)
      groups: {
        "*": { requireMention: true },
      },
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
}

{
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: "Keep answers brief.",
          topics: {
            "99": {
              requireMention: false,
              skills: ["search"],
              systemPrompt: "Stay on topic.",
            },
          },
        },
      },
      customCommands: [
        { command: "backup", description: "Git backup" },
        { command: "generate", description: "Create an image" },
      ],
      historyLimit: 50,
      replyToMode: "first", // off | first | all | batched
      linkPreview: true,
      streaming: "partial", // off | partial | block | progress (default: off; opt in explicitly to avoid preview-edit rate limits)
      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",
      },
      apiRoot: "https://api.telegram.org",
      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 den Standard-Account.
• apiRoot ist nur der Root der Telegram Bot API. Verwenden Sie https://api.telegram.org oder Ihren selbst gehosteten/Proxy-Root, nicht https://api.telegram.org/bot<TOKEN>; openclaw doctor --fix entfernt ein versehentliches abschließendes Suffix /bot<TOKEN>.
• Optionales channels.telegram.defaultAccount überschreibt die Auswahl des Standard-Accounts, wenn es einer konfigurierten Account-ID entspricht.
• In Multi-Account-Setups (2+ Account-IDs) legen Sie einen expliziten Standard fest (channels.telegram.defaultAccount oder channels.telegram.accounts.default), um Fallback-Routing zu vermeiden; openclaw doctor warnt, wenn dieser fehlt oder ungültig ist.
• configWrites: false blockiert von Telegram initiierte Konfigurationsschreibvorgänge (Supergruppen-ID-Migrationen, /config set|unset).
• Einträge in bindings[] auf oberster Ebene mit type: "acp" konfigurieren persistente ACP-Bindings für Forum-Themen (verwenden Sie das kanonische chatId:topic:topicId in match.peer.id). Die Feldsemantik wird in ACP-Agents gemeinsam verwendet.
• Telegram-Stream-Vorschauen verwenden sendMessage + editMessageText (funktioniert in Direkt- und Gruppenchats).
• Wiederholungsrichtlinie: siehe Wiederholungsrichtlinie.

# 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: "Short answers only.",
            },
          },
        },
      },
      historyLimit: 20,
      textChunkLimit: 2000,
      chunkMode: "length", // length | newline
      streaming: {
        mode: "progress", // off | partial | block | progress (Discord default: progress)
        progress: {
          label: "auto",
          maxLines: 8,
          toolProgress: true,
        },
      },
      maxLinesPerMessage: 17,
      ui: {
        components: {
          accentColor: "#5865F2",
        },
      },
      threadBindings: {
        enabled: true,
        idleHours: 24,
        maxAgeHours: 0,
        spawnSessions: true,
        defaultSpawnContext: "fork",
      },
      voice: {
        enabled: true,
        autoJoin: [
          {
            guildId: "123456789012345678",
            channelId: "234567890123456789",
          },
        ],
        daveEncryption: true,
        decryptionFailureTolerance: 24,
        connectTimeoutMs: 30000,
        reconnectGraceMs: 15000,
        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 angeben, verwenden dieses Token für den Aufruf; Einstellungen für Konto-Wiederholungen/-Richtlinien stammen weiterhin aus dem ausgewählten Konto im aktiven Runtime-Snapshot.
• Das optionale channels.discord.defaultAccount überschreibt die Auswahl des Standardkontos, wenn es mit einer konfigurierten Konto-ID übereinstimmt.
• Verwenden Sie user:<id> (DM) oder channel:<id> (Guild-Kanal) für Zustellziele; bloße numerische IDs werden abgelehnt.
• Guild-Slugs sind kleingeschrieben und Leerzeichen werden durch - ersetzt; Kanal-Schlüssel verwenden den slugifizierten 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 Rolle, aber nicht den Bot erwähnen (ausgenommen @everyone/@here).
• channels.discord.mentionAliases ordnet stabilen ausgehenden @handle-Text vor dem Senden Discord-Benutzer-IDs zu, sodass bekannte Teammitglieder deterministisch erwähnt werden können, selbst wenn der flüchtige Verzeichnis-Cache leer ist. Kontoabhängige Überschreibungen liegen unter channels.discord.accounts.<accountId>.mentionAliases.
• maxLinesPerMessage (Standardwert 17) teilt hohe Nachrichten auf, selbst wenn sie unter 2000 Zeichen liegen.
• channels.discord.threadBindings steuert Thread-gebundenes Discord-Routing:
  • enabled: Discord-Überschreibung für Thread-gebundene Sitzungsfunktionen (/focus, /unfocus, /agents, /session idle, /session max-age sowie gebundene Zustellung/Routing)
  • idleHours: Discord-Überschreibung für automatisches Unfocus bei Inaktivität in Stunden (0 deaktiviert)
  • maxAgeHours: Discord-Überschreibung für das harte Höchstalter in Stunden (0 deaktiviert)
  • spawnSessions: Schalter für sessions_spawn({ thread: true }) und automatische ACP-Thread-Erstellung/-Bindung bei Thread-Spawns (Standardwert: true)
  • defaultSpawnContext: nativer Subagent-Kontext für Thread-gebundene Spawns (standardmäßig "fork")
• Einträge auf oberster Ebene in bindings[] mit type: "acp" konfigurieren persistente ACP-Bindungen für Kanäle und Threads (verwenden Sie die Kanal-/Thread-ID in match.peer.id). Die Feldsemantik ist in ACP-Agenten gemeinsam beschrieben.
• channels.discord.ui.components.accentColor legt die Akzentfarbe für Discord-Komponenten-v2-Container fest.
• channels.discord.voice aktiviert Discord-Sprachkanal-Unterhaltungen und optionale Auto-Join- sowie LLM- und TTS-Überschreibungen. Reine Text-Discord-Konfigurationen lassen Sprache standardmäßig deaktiviert; setzen Sie channels.discord.voice.enabled=true, um sie zu aktivieren.
• channels.discord.voice.model überschreibt optional das LLM-Modell, das für Antworten in Discord-Sprachkanälen verwendet wird.
• channels.discord.voice.daveEncryption und channels.discord.voice.decryptionFailureTolerance werden an die DAVE-Optionen von @discordjs/voice durchgereicht (standardmäßig true und 24).
• channels.discord.voice.connectTimeoutMs steuert die anfängliche @discordjs/voice-Ready-Wartezeit für /vc join und Auto-Join-Versuche (standardmäßig 30000).
• channels.discord.voice.reconnectGraceMs steuert, wie lange eine getrennte Sprachsitzung Zeit hat, in Reconnect-Signalisierung überzugehen, bevor OpenClaw sie zerstört (standardmäßig 15000).
• Discord-Sprachwiedergabe wird nicht durch das Sprechbeginn-Ereignis eines anderen Benutzers unterbrochen. Um Feedback-Schleifen zu vermeiden, ignoriert OpenClaw neue Sprachaufnahme, während TTS abgespielt wird.
• OpenClaw versucht außerdem, den Sprachempfang wiederherzustellen, indem es eine Sprachsitzung nach wiederholten Entschlüsselungsfehlern verlässt und ihr erneut beitritt.
• channels.discord.streaming ist der kanonische Schlüssel für den Stream-Modus. Discord verwendet standardmäßig streaming.mode: "progress", sodass Tool-/Arbeitsfortschritt in einer bearbeiteten Vorschau-Nachricht erscheint; setzen Sie streaming.mode: "off", um dies zu deaktivieren. Legacy-streamMode- und boolesche streaming-Werte bleiben Runtime-Aliasse; führen Sie openclaw doctor --fix aus, um persistierte Konfiguration umzuschreiben.
• channels.discord.autoPresence ordnet Runtime-Verfügbarkeit der Bot-Präsenz zu (healthy => online, degraded => idle, exhausted => dnd) und erlaubt optionale Status-Textüberschreibungen.
• channels.discord.dangerouslyAllowNameMatching aktiviert veränderliches Namens-/Tag-Matching wieder (Break-Glass-Kompatibilitätsmodus).
• channels.discord.execApprovals: Discord-native Zustellung von Exec-Genehmigungen und Autorisierung von Genehmigenden.
  • enabled: true, false oder "auto" (Standard). Im Auto-Modus werden Exec-Genehmigungen aktiviert, wenn Genehmigende 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 ausgelassen.
  • agentFilter: optionale Agent-ID-Allowlist. Weglassen, um Genehmigungen für alle Agenten weiterzuleiten.
  • sessionFilter: optionale Sitzungsschlüssel-Muster (Teilzeichenfolge oder Regex).
  • target: wohin Genehmigungsaufforderungen gesendet werden. "dm" (Standard) sendet an DMs der Genehmigenden, "channel" sendet an den Ursprungskanal, "both" sendet an beide. Wenn das Ziel "channel" enthält, sind Buttons nur für aufgelöste Genehmigende verwendbar.
  • cleanupAfterResolve: löscht bei true Genehmigungs-DMs nach Genehmigung, Ablehnung oder Timeout.

Reaktionsbenachrichtigungsmodi: off (keine), own (Nachrichten des Bots, Standard), all (alle Nachrichten), allowlist (aus guilds.<id>.users für alle Nachrichten).

# 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,
    },
  },
}

• Dienstkonto-JSON: inline (serviceAccount) oder dateibasiert (serviceAccountFile).
• Dienstkonto-SecretRef 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 Zustellziele.
• channels.googlechat.dangerouslyAllowNameMatching aktiviert veränderliches Matching von E-Mail-Principals wieder (Break-Glass-Kompatibilitätsmodus).

# Slack

{
  channels: {
    slack: {
      enabled: true,
      botToken: "xoxb-...",
      appToken: "xapp-...",
      socketMode: {
        clientPingTimeout: 15000,
        serverPingTimeout: 30000,
        pingPongLoggingEnabled: false,
      },
      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: "Short answers only.",
        },
      },
      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, // use Slack native streaming API when 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 (auf Root-Ebene oder pro Konto).
• socketMode reicht Transport-Tuning für den Socket Mode des Slack SDK an die öffentliche Bolt-Receiver-API durch. Verwenden Sie es nur, wenn Sie Ping/Pong-Timeouts oder veraltetes Websocket-Verhalten untersuchen.
• botToken, appToken, signingSecret und userToken akzeptieren Klartextzeichenfolgen oder SecretRef-Objekte.
• Slack-Konto-Snapshots legen pro Zugangsdatenquelle/-status Felder offen, etwa botTokenSource, botTokenStatus, appTokenStatus und im HTTP-Modus signingSecretStatus. configured_unavailable bedeutet, dass das Konto über SecretRef konfiguriert ist, der aktuelle Befehls-/Runtime-Pfad den Secret-Wert jedoch nicht auflösen konnte.
• configWrites: false blockiert von Slack initiierte Konfigurationsschreibvorgänge.
• Das optionale channels.slack.defaultAccount überschreibt die Auswahl des Standardkontos, wenn es mit einer konfigurierten Konto-ID übereinstimmt.
• channels.slack.streaming.mode ist der kanonische Slack-Schlüssel für den Stream-Modus. channels.slack.streaming.nativeTransport steuert Slacks nativen Streaming-Transport. Legacy-streamMode-, boolesche streaming- und nativeStreaming-Werte bleiben Runtime-Aliasse; führen Sie openclaw doctor --fix aus, um persistierte Konfiguration umzuschreiben.
• Verwenden Sie user:<id> (DM) oder channel:<id> für Zustellziele.

Reaktionsbenachrichtigungsmodi: off, own (Standard), all, allowlist (aus reactionAllowlist).

Thread-Sitzungsisolierung: thread.historyScope ist pro Thread (Standard) oder kanalweit geteilt. thread.inheritParent kopiert das Transkript des übergeordneten Kanals in neue Threads.

• Slack-natives Streaming plus der Slack-Assistant-artige Thread-Status „is typing...“ erfordern ein Antwort-Thread-Ziel. DMs auf oberster Ebene bleiben standardmäßig außerhalb von Threads, sodass sie weiterhin über Slack-Entwurfs-Post-und-Bearbeitungs-Vorschauen streamen können, anstatt die native Stream-/Statusvorschau im Thread-Stil anzuzeigen.
• typingReaction fügt der eingehenden Slack-Nachricht eine temporäre Reaktion hinzu, während eine Antwort läuft, und entfernt sie nach Abschluss. Verwenden Sie einen Slack-Emoji-Shortcode wie "hourglass_flowing_sand".
• channels.slack.execApprovals: Slack-native Zustellung von Exec-Genehmigungen und Autorisierung von Genehmigenden. Gleiches Schema wie Discord: enabled (true/false/"auto"), approvers (Slack-Benutzer-IDs), agentFilter, sessionFilter und target ("dm", "channel" oder "both").

# Mattermost

Mattermost wird in aktuellen OpenClaw-Releases als gebündeltes Plugin ausgeliefert. Ältere oder angepasste Builds können ein aktuelles npm-Paket mit openclaw plugins install @openclaw/mattermost installieren. Prüfen Sie npmjs.com/package/@openclaw/mattermost auf die aktuellen Dist-Tags, bevor Sie eine Version pinnen.

{
  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 explicit URL for reverse-proxy/public deployments
        callbackUrl: "https://gateway.example.com/api/channels/mattermost/command",
      },
      textChunkLimit: 4000,
      chunkMode: "length",
    },
  },
}

Chatmodi: oncall (Antwort bei @-Erwähnung, Standard), onmessage (jede Nachricht), onchar (Nachrichten, die mit einem Auslösepräfix beginnen).

Wenn native Mattermost-Befehle aktiviert sind:

• commands.callbackPath muss ein Pfad sein (zum Beispiel /api/channels/mattermost/command), keine vollständige URL.
• commands.callbackUrl muss zum OpenClaw-Gateway-Endpunkt auflösen und vom Mattermost-Server erreichbar sein.
• Native Slash-Callbacks werden mit den befehlsspezifischen Tokens authentifiziert, die Mattermost bei der Registrierung von Slash-Befehlen zurückgibt. Wenn die Registrierung fehlschlägt oder keine Befehle aktiviert sind, lehnt OpenClaw Callbacks mit Unauthorized: invalid command token. ab.
• Für private/tailnet/interne Callback-Hosts kann Mattermost erfordern, dass ServiceSettings.AllowedUntrustedInternalConnections den Callback-Host bzw. die Domain enthält. Verwenden Sie Host-/Domain-Werte, keine vollständigen URLs.
• channels.mattermost.configWrites: Konfigurationsschreibvorgänge, die von Mattermost initiiert werden, erlauben oder verweigern.
• channels.mattermost.requireMention: eine @mention vor Antworten in Kanälen verlangen.
• channels.mattermost.groups.<channelId>.requireMention: kanalspezifische Überschreibung für Erwähnungs-Gating ("*" als Standard).
• Optional überschreibt channels.mattermost.defaultAccount die Auswahl des Standardkontos, wenn es mit einer konfigurierten Konto-ID übereinstimmt.

# Signal

{
  channels: {
    signal: {
      enabled: true,
      account: "+15555550123", // optional account binding
      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,
    },
  },
}

Modi für Reaktionsbenachrichtigungen: off, own (Standard), all, allowlist (aus reactionAllowlist).

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

# BlueBubbles

BlueBubbles ist die ältere iMessage-Bridge (Plugin-gestützt, unter channels.bluebubbles konfiguriert). Bestehende Setups bleiben unterstützt, neue OpenClaw-iMessage-Bereitstellungen sollten jedoch channels.imessage bevorzugen, wenn imsg auf dem Messages-Host ausgeführt werden kann.

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

• Hier behandelte zentrale Schlüsselpfade: channels.bluebubbles, channels.bluebubbles.dmPolicy.
• Optional überschreibt channels.bluebubbles.defaultAccount die Auswahl des Standardkontos, wenn es mit einer konfigurierten Konto-ID übereinstimmt.
• Einträge in bindings[] auf oberster Ebene mit type: "acp" können BlueBubbles-Unterhaltungen an persistente ACP-Sitzungen binden. Verwenden Sie ein BlueBubbles-Handle oder eine Zielzeichenfolge (chat_id:*, chat_guid:*, chat_identifier:*) in match.peer.id. Gemeinsame Feldsemantik: ACP Agents.
• Die vollständige BlueBubbles-Kanalkonfiguration und die Begründung für die Einstellung sind in BlueBubbles dokumentiert.

# iMessage

OpenClaw startet imsg rpc (JSON-RPC über stdio). Kein Daemon und kein Port erforderlich. Dies ist der bevorzugte Weg für neue OpenClaw-iMessage-Setups, wenn der Host Berechtigungen für die Messages-Datenbank und Automation gewähren kann.

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "imsg",
      dbPath: "~/Library/Messages/chat.db",
      remoteHost: "user@gateway-host",
      dmPolicy: "pairing",
      allowFrom: ["+15555550123", "[email protected]", "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 Auswahl des Standardkontos, wenn es mit einer konfigurierten Konto-ID übereinstimmt.

• Erfordert Full Disk Access für die Messages-Datenbank.

• Bevorzugen Sie chat_id:<id>-Ziele. Verwenden Sie imsg chats --limit 20, um Chats aufzulisten.

• cliPath kann auf einen SSH-Wrapper verweisen; setzen Sie remoteHost (host oder user@host) für das Abrufen von Anhängen per SCP.

• attachmentRoots und remoteAttachmentRoots beschränken eingehende Anhangspfade (Standard: /Users/*/Library/Messages/Attachments).

• SCP verwendet strikte Host-Key-Prüfung; stellen Sie daher sicher, dass der Relay-Host-Schlüssel bereits in ~/.ssh/known_hosts vorhanden ist.

• channels.imessage.configWrites: Konfigurationsschreibvorgänge, die von iMessage initiiert werden, erlauben oder verweigern.

• Einträge in bindings[] auf oberster Ebene mit type: "acp" können iMessage-Unterhaltungen an persistente ACP-Sitzungen binden. Verwenden Sie ein normalisiertes 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

Matrix ist Plugin-gestützt und wird unter channels.matrix konfiguriert.

{
  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; Passwortauthentifizierung verwendet userId + password.
• channels.matrix.proxy leitet Matrix-HTTP-Datenverkehr über einen expliziten HTTP(S)-Proxy. Benannte Konten können dies mit channels.matrix.accounts.<id>.proxy überschreiben.
• channels.matrix.network.dangerouslyAllowPrivateNetwork erlaubt private/interne Homeserver. proxy und diese Netzwerk-Opt-in-Einstellung sind unabhängige Steuerungen.
• channels.matrix.defaultAccount wählt das bevorzugte Konto in Setups mit mehreren Konten aus.
• channels.matrix.autoJoin ist standardmäßig off, sodass eingeladene Räume und neue DM-artige Einladungen ignoriert werden, bis Sie autoJoin: "allowlist" mit autoJoinAllowlist oder autoJoin: "always" setzen.
• channels.matrix.execApprovals: Matrix-native Zustellung von Exec-Genehmigungen und Autorisierung von Genehmigenden.
  • enabled: true, false oder "auto" (Standard). Im Auto-Modus werden Exec-Genehmigungen aktiviert, wenn Genehmigende 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 Allowlist für Agent-IDs. Weglassen, um Genehmigungen für alle Agents weiterzuleiten.
  • sessionFilter: optionale Sitzungsschlüsselmuster (Teilzeichenfolge oder Regex).
  • target: wohin Genehmigungsaufforderungen gesendet werden. "dm" (Standard), "channel" (Ursprungsraum) oder "both".
  • Kontospezifische Überschreibungen: channels.matrix.accounts.<id>.execApprovals.
• channels.matrix.dm.sessionScope steuert, wie Matrix-DMs zu Sitzungen gruppiert werden: per-user (Standard) teilt nach geroutetem Peer, während per-room jeden DM-Raum isoliert.
• Matrix-Statusprüfungen und Live-Verzeichnisabfragen verwenden dieselbe Proxy-Richtlinie wie Laufzeitdatenverkehr.
• Die vollständige Matrix-Konfiguration, Zielregeln und Setup-Beispiele sind in Matrix dokumentiert.

# Microsoft Teams

Microsoft Teams ist Plugin-gestützt und wird unter channels.msteams konfiguriert.

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

• Hier behandelte zentrale Schlüsselpfade: channels.msteams, channels.msteams.configWrites.
• Die vollständige Teams-Konfiguration (Anmeldedaten, Webhook, DM-/Gruppenrichtlinie, Überschreibungen pro Team/pro Kanal) ist in Microsoft Teams dokumentiert.

# IRC

IRC ist Plugin-gestützt und wird unter channels.irc konfiguriert.

{
  channels: {
    irc: {
      enabled: true,
      dmPolicy: "pairing",
      configWrites: true,
      nickserv: {
        enabled: true,
        service: "NickServ",
        password: "${IRC_NICKSERV_PASSWORD}",
        register: false,
        registerEmail: "[email protected]",
      },
    },
  },
}

• Hier behandelte zentrale Schlüsselpfade: channels.irc, channels.irc.dmPolicy, channels.irc.configWrites, channels.irc.nickserv.*.
• Optional überschreibt channels.irc.defaultAccount die Auswahl des Standardkontos, wenn es mit einer konfigurierten Konto-ID übereinstimmt.
• Die vollständige IRC-Kanalkonfiguration (Host/Port/TLS/Kanäle/Allowlists/Erwähnungs-Gating) ist in IRC dokumentiert.

# Mehrere Konten (alle Kanäle)

Führen Sie mehrere Konten pro Kanal aus (jedes mit eigener accountId):

{
  channels: {
    telegram: {
      accounts: {
        default: {
          name: "Primary bot",
          botToken: "123456:ABC...",
        },
        alerts: {
          name: "Alerts bot",
          botToken: "987654:XYZ...",
        },
      },
    },
  },
}

• default wird verwendet, wenn accountId ausgelassen wird (CLI + Routing).
• Env-Tokens gelten nur für das Standardkonto.
• Basiskanaleinstellungen gelten für alle Konten, sofern sie nicht pro Konto überschrieben werden.
• Verwenden Sie bindings[].match.accountId, um jedes Konto an einen anderen Agent weiterzuleiten.
• Wenn Sie ein Nicht-Standardkonto über openclaw channels add (oder Kanal-Onboarding) hinzufügen, während Sie noch eine Einkonto-Kanalkonfiguration auf oberster Ebene verwenden, befördert OpenClaw zunächst kontobezogene Einkonto-Werte auf oberster Ebene 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/Standardziel beibehalten.
• Bestehende kanalweite Bindings (ohne accountId) stimmen weiterhin mit dem Standardkonto überein; kontobezogene Bindings bleiben optional.
• openclaw doctor --fix repariert auch gemischte Formen, indem kontobezogene Einkonto-Werte auf oberster Ebene in das für diesen Kanal ausgewählte beförderte Konto verschoben werden. Die meisten Kanäle verwenden accounts.default; Matrix kann stattdessen ein vorhandenes passendes benanntes/Standardziel beibehalten.

# Andere Plugin-Kanäle

Viele Plugin-Kanäle werden als channels.<id> konfiguriert und auf ihren jeweiligen Kanalseiten dokumentiert (zum Beispiel Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat und Twitch). Siehe den vollständigen Kanalindex: Kanäle.

# Erwähnungs-Gating für Gruppenchats

Gruppennachrichten erfordern standardmäßig eine Erwähnung (Metadaten-Erwähnung oder sichere Regex-Muster). Gilt für WhatsApp, Telegram, Discord, Google Chat und iMessage-Gruppenchats.

Sichtbare Antworten werden separat gesteuert. Gruppen-/Kanalräume verwenden standardmäßig messages.groupChat.visibleReplies: "message_tool": OpenClaw verarbeitet den Turn weiterhin, aber normale finale Antworten bleiben privat, und sichtbare Raumausgabe erfordert message(action=send). Setzen Sie "automatic" nur, wenn Sie das Legacy-Verhalten möchten, bei dem normale Antworten zurück in den Raum gepostet werden. Um dasselbe tool-only-Verhalten für sichtbare Antworten auch auf Direktchats anzuwenden, setzen Sie messages.visibleReplies: "message_tool"; der Codex-Harness verwendet dieses tool-only-Verhalten außerdem als nicht gesetzten Standard für Direktchats.

Tool-only sichtbare Antworten erfordern ein Modell/eine Runtime, die zuverlässig Tools aufruft. Wenn das Sitzungsprotokoll Assistant-Text mit didSendViaMessagingTool: false zeigt, hat das Modell eine private finale Antwort erzeugt, statt das Nachrichtentool aufzurufen. Wechseln Sie für diesen Kanal zu einem stärkeren Modell für Tool-Aufrufe, oder setzen Sie messages.groupChat.visibleReplies: "automatic", um sichtbare finale Legacy-Antworten wiederherzustellen.

Wenn das Nachrichtentool unter der aktiven Tool-Richtlinie nicht verfügbar ist, fällt OpenClaw auf automatische sichtbare Antworten zurück, statt die Antwort stillschweigend zu unterdrücken. openclaw doctor warnt vor dieser Fehlanpassung.

Das Gateway lädt die messages-Konfiguration nach dem Speichern der Datei per Hot-Reload neu. Starten Sie nur neu, wenn Dateiüberwachung oder Konfigurations-Neuladen in der Bereitstellung deaktiviert ist.

Erwähnungstypen:

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

{
  messages: {
    visibleReplies: "automatic", // global default for direct/source chats; Codex harness defaults unset direct chats to message_tool
    groupChat: {
      historyLimit: 50,
      visibleReplies: "message_tool", // default; use "automatic" for legacy final replies
    },
  },
  agents: {
    list: [{ id: "main", groupChat: { mentionPatterns: ["@openclaw", "openclaw"] } }],
  },
}

messages.groupChat.historyLimit legt den globalen Standard fest. Kanäle können ihn mit channels.<channel>.historyLimit (oder pro Konto) überschreiben. Setzen Sie 0, um ihn zu deaktivieren.

messages.visibleReplies ist der globale Standard für Source-Turns; messages.groupChat.visibleReplies überschreibt ihn für Gruppen-/Kanal-Source-Turns. Wenn messages.visibleReplies nicht gesetzt ist, kann ein Harness seinen eigenen Direkt-/Source-Standard bereitstellen; der Codex-Harness verwendet standardmäßig message_tool. Kanal-Allowlists und Erwähnungs-Gating entscheiden weiterhin, ob ein Turn verarbeitet wird.

# DM-Verlaufslimits

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

Auflösung: Pro-DM-Überschreibung → Provider-Standard → kein Limit (alles wird beibehalten).

Unterstützt: telegram, whatsapp, discord, slack, signal, imessage, msteams.

# Self-Chat-Modus

Fügen Sie Ihre eigene Nummer in allowFrom ein, um den Self-Chat-Modus zu aktivieren (ignoriert native @-Erwähnungen, antwortet nur auf Textmuster):

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

# Befehle (Chat-Befehlsverarbeitung)

{
  commands: {
    native: "auto", // register native commands when supported
    nativeSkills: "auto", // register native skill commands when supported
    text: true, // parse /commands in chat messages
    bash: false, // allow ! (alias: /bash)
    bashForegroundMs: 2000,
    config: false, // allow /config
    mcp: false, // allow /mcp
    plugins: false, // allow /plugins
    debug: false, // allow /debug
    restart: true, // allow /restart + gateway restart tool
    ownerAllowFrom: ["discord:123456789012345678"],
    ownerDisplay: "raw", // raw | hash
    ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}",
    allowFrom: {
      "*": ["user1"],
      discord: ["user:123"],
    },
    useAccessGroups: true,
  },
}

# Verwandt

• Konfigurationsreferenz — Schlüssel der obersten Ebene
• Konfiguration — Agents
• Kanalübersicht