OpenClaw Access Groups: Absenderlisten für mehrere Kanäle zentral pflegen

Drei Personen dürfen mit deinem Agenten schreiben: du, deine Partnerin und ein Freund, der beim Homelab hilft. Der Agent hängt an Telegram und Discord. Solange du beide Allowlisten getrennt pflegst, reicht eine vergessene Änderung, damit ein alter Zugang offenbleibt oder ein berechtigter Absender ausgesperrt wird.

OpenClaw löst dieses Pflegeproblem mit Access Groups. Du definierst eine benannte Absenderliste einmal unter accessGroups und referenzierst sie anschließend mit accessGroup:<name> in mehreren Kanal-Allowlisten.

Was eine Access Group ist und was nicht

Eine Access Group gewährt allein noch keinen Zugriff. Sie wirkt nur, wenn ein Allowlist-Feld auf sie verweist.

Dabei handelt es sich um einen Alias für Absenderlisten, nicht um eine Rolle. Die Gruppe macht niemanden zum Owner, genehmigt keine Pairing-Anfrage und vergibt keine Tool-Rechte. Ein Mitglied darf lediglich dort schreiben, wo die Gruppe ausdrücklich eingebunden ist.

Auch Gruppenchats folgen eigenen Regeln. Raumfreigaben, Erwähnungspflichten und Sitzungen werden weiterhin über die jeweilige Kanalkonfiguration gesteuert. Access Groups beantworten eine engere Frage: Welche Absender dürfen über mehrere Kanäle hinweg dieselben Eingänge nutzen?

Vor dem Umbau: Voraussetzungen prüfen

Access Groups funktionieren nur bei Kanälen, die an die gemeinsamen Autorisierungs-Helfer von OpenClaw angebunden sind. Die Dokumentation führt ClickClack, Discord, Feishu, Google Chat, iMessage, IRC, LINE, Mattermost, Microsoft Teams, Nextcloud Talk, Nostr, QQ Bot, Signal, Slack, SMS, Telegram, WhatsApp, Zalo und Zalo Personal auf. Fehlt dein Kanal, prüfe vor der Umstellung dessen aktuelle Dokumentation. Falls Telegram oder WhatsApp noch nicht verbunden ist, richte den Kanal zuerst wie im Tutorial zu Telegram und WhatsApp in OpenClaw beschrieben ein und teste den bisherigen Zugriff.

Bei unterstützten Kanälen greifen Access Groups in Absender-Allowlist-Pfaden: in Direktnachrichten über allowFrom, bei Gruppenabsendern über groupAllowFrom, in kanalspezifischen Raum-Allowlisten wie groups.<space>.users bei Google Chat und bei Befehlsautorisierungen, die diese Listen wiederverwenden.

Die Beispiele in diesem Artikel sind Konfigurationsfragmente. Füge sie in deine vorhandene openclaw.json ein, statt die Datei oder komplette Kanalobjekte damit zu ersetzen. Behalte Tokens, Konten, Raumregeln, Richtlinien und alle anderen vorhandenen Schlüssel bei. Der Beitrag zur Gateway-Konfiguration mit openclaw.json erläutert Aufbau und JSON5-Syntax.

Halte außerdem je Kanal zwei Testkonten bereit: ein vorgesehenes Gruppenmitglied und einen Außenstehenden. Du brauchst Zugriff auf den Host oder die Control UI, damit du die Konfiguration auch dann zurücksetzen kannst, wenn kein Nachrichtenkanal mehr reagiert.

Konfiguration sichern

Ermittle die tatsächlich vom Gateway verwendete Konfigurationsdatei. Liegt sie am Standardort, lege mit folgendem Ablauf eine Sicherung unter einem exklusiv erzeugten Namen an:

CONFIG="$HOME/.openclaw/openclaw.json"
test -f "$CONFIG" || { printf 'Konfiguration nicht gefunden: %s\n' "$CONFIG" >&2; exit 1; }
BACKUP="$(mktemp "${CONFIG}.access-groups.XXXXXX")" || exit 1
cp -p "$CONFIG" "$BACKUP" || { rm -f "$BACKUP"; exit 1; }
printf 'Sicherungspfad: %s\n' "$BACKUP"

mktemp reserviert bei jeder Ausführung einen neuen Pfad. Das anschließende cp schreibt deshalb nur in die gerade erzeugte leere Datei und überschreibt keine ältere, möglicherweise letzte funktionierende Sicherung. Wiederholst du den Ablauf, entstehen weitere Sicherungen mit jeweils eigenem Namen.

Verwendet deine Installation einen anderen Ort, setze CONFIG auf den Pfad der aktiven Datei. Halte den hinter Sicherungspfad: ausgegebenen Wert unverändert fest, zum Beispiel in einer administrativen Notiz außerhalb der Nachrichtenkanäle. Genau dieser konkrete Pfad wird beim Rollback benötigt. Prüfe zusätzlich, ob die Sicherung lesbar ist:

test -r "$BACKUP" && printf 'Sicherung lesbar: %s\n' "$BACKUP"

Notiere außerdem die aktuellen Werte von allowFrom, groupAllowFrom und kanalspezifischen Nutzerlisten. Diese direkten Einträge bleiben während der Migration erhalten. Dadurch behältst du einen bereits funktionierenden administrativen Zugang, während du die Gruppenreferenz prüfst.

Access Groups einrichten und verwenden

Eine statische Absendergruppe anlegen

Statische Gruppen verwenden den Typ message.senders. Unter members stehen die Absender-IDs, geordnet nach Kanal. Der Schlüssel "*" gilt für alle Kanäle, die diese Gruppe referenzieren.

{
  accessGroups: {
    operators: {
      type: "message.senders",
      members: {
        "*": ["global-owner-id"],
        discord: ["discord:123456789012345678"],
        telegram: ["987654321"],
        whatsapp: ["+15551234567"],
      },
    },
  },
}

Wähle einen sprechenden Gruppennamen wie operators und setze type auf "message.senders". Trage für jeden Kanal die ID in dessen normaler allowFrom-Schreibweise ein. Verwende "*" nur für einen Absender, der auf jedem referenzierenden Kanal zugelassen sein soll.

OpenClaw übersetzt Absender-IDs nicht zwischen Kanälen. Hat dieselbe Person eine Telegram-ID und eine Discord-ID, müssen beide Werte unter dem jeweiligen Kanalschlüssel stehen. Ein Eintrag unter telegram gilt nicht automatisch für Discord.

Die Gruppe neben vorhandenen Einträgen referenzieren

Die Referenz in einer Allowlist aktiviert die Gruppe für genau dieses Feld. Während der Migration bleibt die bisherige direkte ID daneben stehen:

{
  accessGroups: {
    operators: {
      type: "message.senders",
      members: {
        discord: ["discord:123456789012345678"],
        telegram: ["987654321"],
      },
    },
  },
  channels: {
    discord: {
      dmPolicy: "allowlist",
      allowFrom: [
        "discord:123456789012345678",
        "accessGroup:operators",
      ],
    },
    telegram: {
      dmPolicy: "allowlist",
      allowFrom: [
        "987654321",
        "accessGroup:operators",
      ],
    },
  },
}

Füge accessGroups auf der obersten Ebene der vorhandenen Konfiguration ein. Ergänze danach accessGroup:operators in den vorhandenen allowFrom-Arrays. Kopiere dmPolicy: "allowlist" nur dann aus dem Beispiel, wenn diese Richtlinie deinem bisherigen und gewünschten Betrieb entspricht.

Für Absender in Gruppenchats dient groupAllowFrom. Auch dort bleibt eine vorhandene direkte ID während der Umstellung erhalten. Bei Google Chat lässt sich die Gruppe pro Space unter users referenzieren:

{
  accessGroups: {
    oncall: {
      type: "message.senders",
      members: {
        whatsapp: ["+15551234567"],
        googlechat: ["users/1234567890"],
      },
    },
  },
  channels: {
    whatsapp: {
      groupPolicy: "allowlist",
      groupAllowFrom: [
        "+15551234567",
        "accessGroup:oncall",
      ],
    },
    googlechat: {
      groups: {
        "spaces/AAA": {
          users: [
            "users/1234567890",
            "accessGroup:oncall",
          ],
        },
      },
    },
  },
}

Gruppen und direkte Einträge dürfen dauerhaft kombiniert werden. Das ist sinnvoll, wenn eine weitere Person ausschließlich über Discord schreiben darf und deshalb nicht in accessGroups.operators.members.discord steht:

{
  channels: {
    discord: {
      dmPolicy: "allowlist",
      allowFrom: [
        "accessGroup:operators",
        "discord:222222222222222222",
      ],
    },
  },
}

Die Discord-ID discord:222222222222222222 unterscheidet sich bewusst vom Gruppenmitglied. Sie bleibt als eigener Direkteintrag erhalten.

Änderung prüfen und aktivieren

Prüfe die gespeicherte Konfiguration vor dem Neustart im ausdrücklich read-only ausgeführten Lint-Modus:

openclaw doctor --lint

Die Prüfung gilt für diese Migration als bestanden, wenn keine Beanstandung zu Access Groups, fehlenden Gruppenreferenzen, Allowlists oder den zugehörigen Kanalrichtlinien verbleibt. Andere gemeldete Probleme solltest du separat bewerten; verwende für diesen Prüfschritt weder --fix noch --repair.

Aktiviere die gespeicherte Änderung anschließend über den regulären Neustartweg deiner Installation, etwa über den eingerichteten Dienst oder die Control UI. Entscheidend ist, dass der Gateway-Prozess die geänderte Konfiguration neu lädt. Verlasse dich nicht auf einen unbelegten automatischen Reload und entferne zu diesem Zeitpunkt noch keine direkten Absender-IDs.

Gestuft testen und alte Duplikate entfernen

Sende nach der Aktivierung je Kanal eine Nachricht vom vorgesehenen Gruppenmitglied. Sie muss den Agenten erreichen. Sende danach eine Nachricht vom Außenstehenden. Sie darf keinen Agentenlauf und keine Antwort auslösen. Beachte bei Gruppenchats zusätzlich die vorhandenen Raum- und Erwähnungsregeln, damit ein fehlender Mention nicht mit einer Allowlist-Sperre verwechselt wird.

Wenn beide Tests je Kanal das erwartete Ergebnis liefern, entferne ausschließlich die direkten Einträge, die durch dieselbe Access Group ersetzt wurden. Dauerhafte Ausnahmen wie discord:222222222222222222 bleiben bestehen. Speichere die Konfiguration, führe erneut openclaw doctor --lint aus und aktiviere die Änderung wieder über den regulären Neustartweg.

Wiederhole danach den positiven und den negativen Test auf jedem betroffenen Kanal. Das Gruppenmitglied muss weiterhin zugelassen, der Außenstehende weiterhin abgewiesen werden. Damit prüfst du, dass der Zugriff tatsächlich über die Gruppenreferenz funktioniert und nicht unbemerkt vom alten Duplikat abhing.

Dynamische Gruppen für Discord

Discord unterstützt zusätzlich den Typ discord.channelAudience. Damit dürfen Personen Direktnachrichten senden, die einen bestimmten Serverkanal aktuell sehen können. OpenClaw prüft dafür die Discord-Berechtigung ViewChannel.

{
  accessGroups: {
    maintainers: {
      type: "discord.channelAudience",
      guildId: "1456350064065904867",
      channelId: "1456744319972282449",
      membership: "canViewChannel",
    },
  },
  channels: {
    discord: {
      dmPolicy: "allowlist",
      allowFrom: ["accessGroup:maintainers"],
    },
  },
}

membership ist optional; der Standardwert lautet canViewChannel. Diese Variante passt, wenn ein Discord-Kanal wie #maintainers bereits festlegt, wer zum zuständigen Kreis gehört. Die Mitgliedschaft wird dann in Discord gepflegt und muss nicht zusätzlich in OpenClaw nachgezogen werden.

Der Bot benötigt Zugriff auf Server und Kanal. Außerdem muss im Discord Developer Portal der Server Members Intent aktiviert sein. Kann Discord den Zugriff, die Mitgliedschaft oder die Zuordnung des Kanals zum Server nicht bestätigen, berechtigt die dynamische Gruppe den Absender nicht. Nutze auch hier die gestufte Migration und entferne vorhandene Direkteinträge nur nach erfolgreichen Tests.

Laufzeitfehler diagnostizieren

Verweist allowFrom auf accessGroup:operators, obwohl accessGroups.operators fehlt, berechtigt dieser Eintrag niemanden. Im Betrieb wirkt das oft wie ein Bot, der Nachrichten ignoriert. Prüfe dann den Gruppennamen, den type, den Kanalschlüssel und die Schreibweise der Absender-ID.

Bleibt openclaw doctor --lint unauffällig, obwohl eine Nachricht ignoriert wird, untersuche die Laufzeitprotokolle des betroffenen Kanals:

openclaw channels logs --channel discord

Für Telegram verwendest du:

openclaw channels logs --channel telegram

Suche rund um den Versandzeitpunkt nach Hinweisen auf einen abgewiesenen Absender, eine fehlende oder unpassende Access Group, eine Allowlist- oder Policy-Entscheidung sowie fehlende Raumfreigaben oder Erwähnungen. Bei dynamischen Discord-Gruppen kommen fehlender Kanalzugriff, eine nicht bestätigte Mitgliedschaft und ein deaktivierter Server Members Intent als Ursachen hinzu.

Eine Access Group ersetzt auch keinen öffentlichen Zugriff. dmPolicy: "open" verlangt weiterhin "*" in der effektiven DM-Allowlist. Unterstützt ein Kanal Anzeigenamen und stabile IDs, sind numerische IDs oder Nutzer-IDs für die Zuordnung verlässlicher.

Rollback ohne Nachrichtenkanal

Schlägt ein positiver Test fehl oder werden berechtigte Absender ausgesperrt, stelle die vor der Migration angelegte Sicherung über den Host oder die Control UI wieder her. Setze BACKUP dabei auf exakt den Pfad, den der Sicherungsbefehl hinter Sicherungspfad: ausgegeben hat. Für eine beispielhafte Ausgabe Sicherungspfad: /home/alex/.openclaw/openclaw.json.access-groups.a1B2C3 lautet der Rückweg:

CONFIG="$HOME/.openclaw/openclaw.json"
BACKUP="/home/alex/.openclaw/openclaw.json.access-groups.a1B2C3"
test -f "$BACKUP" || { printf 'Sicherung nicht gefunden: %s\n' "$BACKUP" >&2; exit 1; }
cp -p "$BACKUP" "$CONFIG"

Übernimm den Beispielpfad nicht wörtlich, sondern ersetze ihn durch deinen zuvor festgehaltenen, tatsächlich erzeugten Sicherungspfad. Die Existenzprüfung verhindert, dass ein Tippfehler zu einem Kopierversuch mit einer falschen Quelle führt.

Starte den Gateway danach über den regulären Betriebsweg deiner Installation neu. Prüfe die wiederhergestellte Konfiguration mit openclaw doctor --lint und teste den bisherigen administrativen Absender. Dieser Rückfallweg hängt nicht davon ab, dass Discord, Telegram oder ein anderer Nachrichtenkanal noch Befehle annimmt.

Für Plugin-Entwickler: gemeinsame Helfer verwenden

Neue Kanäle erhalten statische Gruppen vom Typ message.senders, wenn sie die gemeinsamen Ingress-Helfer des Plugin SDK verwenden. Eine eigene Expansion in flache Allowlisten ist dafür nicht nötig.

Für Diagnosen und Konformitätstests liefert resolveAccessGroupAllowFromState aus openclaw/plugin-sdk/access-groups einen strukturierten Zustand mit referenzierten, passenden, fehlenden, nicht unterstützten und fehlgeschlagenen Gruppen. expandAllowFromWithAccessGroups(...) bleibt Kompatibilitätspfaden vorbehalten, die weiterhin ein flaches allowFrom-Array erwarten.

Kernpunkte

Access Groups bündeln Absender-IDs, ohne Owner-Status, Pairing oder Tool-Rechte zu verändern. Sichere vor dem Umbau die aktive Konfiguration unter einem exklusiv erzeugten Namen und halte den ausgegebenen Pfad für den Rollback fest. Füge Gruppen und Referenzen in vorhandene Objekte ein, statt Kanalblöcke zu ersetzen.

Behalte direkte IDs während der Migration, prüfe die Konfiguration mit openclaw doctor --lint und teste je Kanal ein Gruppenmitglied sowie einen Außenstehenden. Entferne ersetzte Duplikate nur nach erfolgreichen Tests und wiederhole beide Prüfungen danach. Falls der Zugang scheitert, liefern die kanalbezogenen Logs Hinweise; die unabhängige Sicherung ermöglicht den Rollback.