Plugin maintainer reference

Kanal-Eingangs-API

Channel Ingress ist die experimentelle Zugriffssteuerungsgrenze für eingehende Channel-Ereignisse. Plugins sind für plattformspezifische Fakten und Nebenwirkungen zuständig; der Core ist für generische Richtlinien zuständig: DM-/Gruppen-Zulassungslisten, DM-Einträge im Pairing-Speicher, Route-Gates, Befehls-Gates, Ereignisautorisierung, Erwähnungsaktivierung, geschwärzte Diagnosen und Zulassung.

Verwenden Sie openclaw/plugin-sdk/channel-ingress-runtime für neue Empfangspfade. Der ältere Unterpfad openclaw/plugin-sdk/channel-ingress bleibt als veraltete Kompatibilitätsfassade für Plugins von Drittanbietern exportiert.

Runtime-Resolver

   defineStableChannelIngressIdentity,  resolveChannelMessageIngress,} from "openclaw/plugin-sdk/channel-ingress-runtime"; const identity = defineStableChannelIngressIdentity({  key: "platform-user-id",  normalize: normalizePlatformUserId,  sensitivity: "pii",}); const result = await resolveChannelMessageIngress({  channelId: "my-channel",  accountId,  identity,  subject: { stableId: platformUserId },  conversation: { kind: isGroup ? "group" : "direct", id: conversationId },  event: { kind: "message", authMode: "inbound", mayPair: !isGroup },  policy: {    dmPolicy: config.dmPolicy,    groupPolicy: config.groupPolicy,    groupAllowFromFallbackToAllowFrom: true,  },  allowFrom: config.allowFrom,  groupAllowFrom: config.groupAllowFrom,  accessGroups: cfg.accessGroups,  route,  readStoreAllowFrom,  command: hasControlCommand ? { allowTextCommands: true, hasControlCommand } : undefined,});

Berechnen Sie effektive Zulassungslisten, Befehlsverantwortliche oder Befehlsgruppen nicht vorab. Der Resolver leitet sie aus unverarbeiteten Zulassungslisten, Speicher-Callbacks, Route-Deskriptoren, Zugriffsgruppen, Richtlinien und der Konversationsart ab.

Ergebnis

Gebündelte Plugins sollten moderne Projektionen direkt verwenden:

Feld	Bedeutung
`ingress`	geordnete Gate-Entscheidung und Zulassung
`senderAccess`	ausschließlich Autorisierung von Absender und Konversation
`routeAccess`	Projektion von Route und Route-Absender
`commandAccess`	Befehlsautorisierung; `requested: false`, wenn kein Befehls-Gate ausgeführt wurde
`activationAccess`	Ergebnis der Erwähnung/Aktivierung

Die Ereignisautorisierung bleibt im geordneten ingress.graph und über den entscheidenden ingress.reasonCode verfügbar; es wird keine separate Ereignisprojektion ausgegeben.

Veraltete SDK-Hilfsfunktionen für Drittanbieter dürfen ältere Strukturen intern rekonstruieren. Neue gebündelte Empfangspfade sollten moderne Ergebnisse nicht wieder in lokale DTOs übersetzen.

Zugriffsgruppen

accessGroup:<name>-Einträge bleiben geschwärzt. Der Core löst statische message.senders-Gruppen selbst auf und ruft resolveAccessGroupMembership nur für dynamische Gruppen auf, die eine Plattformabfrage erfordern. Fehlende, nicht unterstützte und fehlgeschlagene Gruppen werden standardmäßig abgelehnt.

Ereignismodi

`authMode`	Bedeutung
`inbound`	normale Gates für eingehende Absender
`command`	Befehls-Gates für Callbacks oder bereichsgebundene Schaltflächen
`origin-subject`	der Akteur muss dem Subjekt der ursprünglichen Nachricht entsprechen
`route-only`	ausschließlich Route-Gates für vertrauenswürdige, routengebundene Ereignisse
`none`	Plugin-eigene interne Ereignisse umgehen die gemeinsame Autorisierung

Verwenden Sie mayPair: false für Reaktionen, Schaltflächen, Callbacks und native Befehle.

Routen und Aktivierung

Verwenden Sie Route-Deskriptoren für Richtlinien zu Räumen, Themen, Guilds, Threads oder verschachtelten Routen:

route: {  id: "room",  allowed: roomAllowed,  enabled: roomEnabled,  senderPolicy: "replace",  senderAllowFrom: roomAllowFrom,  blockReason: "room_sender_not_allowlisted",}

Verwenden Sie channelIngressRoutes(...), wenn ein Plugin mehrere optionale Route-Deskriptoren besitzt; die Funktion filtert deaktivierte Zweige heraus, während sie Route-Fakten generisch und nach der precedence jedes Deskriptors geordnet hält.

Die Erwähnungsprüfung ist ein Aktivierungs-Gate. Eine fehlende Erwähnung gibt admission: "skip" zurück, damit der Turn-Kernel keinen ausschließlich beobachtenden Turn verarbeitet. Bei den meisten Channels sollte die Aktivierung nach den Absender- und Befehls-Gates erfolgen. Öffentliche Chat-Oberflächen, die nicht erwähnten Datenverkehr vor Meldungen zu Absender-Zulassungslisten unterdrücken müssen, können activation.order: "before-sender" verwenden, wenn die Umgehung durch Textbefehle deaktiviert ist. Channels mit impliziter Aktivierung, etwa Antworten in Bot-Threads, können activation.allowedImplicitMentionKinds übergeben; das projizierte activationAccess.shouldBypassMention meldet dann, wenn eine ausdrückliche Erwähnung durch einen Befehl oder eine implizite Aktivierung umgangen wurde.

Schwärzung

Unverarbeitete Absenderwerte und unverarbeitete Einträge in Zulassungslisten dienen ausschließlich als Resolver-Eingaben. Sie dürfen nicht im aufgelösten Zustand, in Entscheidungen, Diagnosen, Snapshots oder Kompatibilitätsinformationen erscheinen. Verwenden Sie undurchsichtige Subjekt-IDs, Eintrags-IDs, Route-IDs und Diagnose-IDs.

Verifizierung

bash

pnpm test src/channels/message-access/message-access.test.ts src/plugin-sdk/channel-ingress-runtime.test.tspnpm plugin-sdk:api:check

Was this useful?