Plugin maintainer reference

API voor inkomend kanaalverkeer

Channel-ingress is de experimentele toegangscontrolegrens voor inkomende kanaalgebeurtenissen. Plugins beheren platformspecifieke feiten en bijwerkingen; de kern beheert generiek beleid: toelatingslijsten voor privéberichten/groepen, privéberichtvermeldingen in de koppelingsopslag, routepoorten, opdrachtpoorten, gebeurtenisautorisatie, activering via vermeldingen, geredigeerde diagnostiek en toelating.

Gebruik openclaw/plugin-sdk/channel-ingress-runtime voor nieuwe ontvangstpaden. Het oudere subpad openclaw/plugin-sdk/channel-ingress blijft geëxporteerd als een verouderde compatibiliteitsfacade voor Plugins van derden.

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,});

Bereken effectieve toelatingslijsten, opdrachteigenaren of opdrachtgroepen niet vooraf. De resolver leidt deze af uit onbewerkte toelatingslijsten, opslagcallbacks, routebeschrijvingen, toegangsgroepen, beleid en het soort gesprek.

Resultaat

Meegeleverde Plugins moeten moderne projecties rechtstreeks gebruiken:

Veld	Betekenis
`ingress`	geordende poortbeslissing en toelating
`senderAccess`	uitsluitend autorisatie van afzender/gesprek
`routeAccess`	projectie van route en routeafzender
`commandAccess`	opdrachtautorisatie; `requested: false` wanneer geen opdrachtpoort is uitgevoerd
`activationAccess`	resultaat van vermelding/activering

Gebeurtenisautorisatie blijft beschikbaar in de geordende ingress.graph en de doorslaggevende ingress.reasonCode; er wordt geen afzonderlijke gebeurtenisprojectie gegenereerd.

Verouderde SDK-helpers van derden mogen intern oudere structuren opnieuw opbouwen. Nieuwe meegeleverde ontvangstpaden mogen moderne resultaten niet terugvertalen naar lokale DTO's.

Toegangsgroepen

accessGroup:<name>-vermeldingen blijven geredigeerd. De kern verwerkt statische message.senders-groepen zelf en roept resolveAccessGroupMembership alleen aan voor dynamische groepen waarvoor een platformopzoeking nodig is. Ontbrekende, niet-ondersteunde en mislukte groepen worden standaard geweigerd.

Gebeurtenismodi

`authMode`	Betekenis
`inbound`	normale afzenderpoorten voor inkomende gebeurtenissen
`command`	opdrachtpoorten voor callbacks of afgebakende knoppen
`origin-subject`	actor moet overeenkomen met het onderwerp van het oorspronkelijke bericht
`route-only`	uitsluitend routepoorten voor vertrouwde routegebonden gebeurtenissen
`none`	interne gebeurtenissen die door de Plugin worden beheerd, omzeilen gedeelde autorisatie

Gebruik mayPair: false voor reacties, knoppen, callbacks en systeemeigen opdrachten.

Routes en activering

Gebruik routebeschrijvingen voor beleid voor ruimtes, onderwerpen, guilds, threads of geneste routes:

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

Gebruik channelIngressRoutes(...) wanneer een Plugin meerdere optionele routebeschrijvingen heeft; deze functie filtert uitgeschakelde vertakkingen, terwijl routefeiten generiek blijven en worden geordend volgens de precedence van elke beschrijving.

Controle op vermeldingen is een activeringspoort. Een ontbrekende vermelding retourneert admission: "skip", zodat de turn-kernel geen beurt verwerkt die alleen ter observatie dient. De meeste kanalen moeten activering na de afzender- en opdrachtpoorten laten plaatsvinden. Openbare chatoppervlakken die niet-vermeld verkeer moeten dempen voordat ruis van afzendertoelatingslijsten ontstaat, kunnen kiezen voor activation.order: "before-sender" wanneer het omzeilen via tekstopdrachten is uitgeschakeld. Kanalen met impliciete activering, zoals antwoorden in botthreads, kunnen activation.allowedImplicitMentionKinds doorgeven; de geprojecteerde activationAccess.shouldBypassMention meldt vervolgens wanneer een opdracht of impliciete activering een expliciete vermelding heeft omzeild.

Redactie

Onbewerkte afzenderwaarden en onbewerkte toelatingslijstvermeldingen dienen uitsluitend als invoer voor de resolver. Ze mogen niet voorkomen in opgeloste status, beslissingen, diagnostiek, momentopnamen of compatibiliteitsfeiten. Gebruik ondoorzichtige onderwerp-id's, vermeldings-id's, route-id's en diagnostische id's.

Verificatie

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?