Plugin maintainer reference
API de entrada de canales
La entrada de canales es el límite experimental de control de acceso para los eventos entrantes de canales. Los Plugins son responsables de los datos específicos de la plataforma y de los efectos secundarios; el núcleo es responsable de la política genérica: listas de permitidos de mensajes directos y grupos, entradas de mensajes directos del almacén de emparejamiento, controles de rutas, controles de comandos, autorización de eventos, activación por mención, diagnósticos censurados y admisión.
Use openclaw/plugin-sdk/channel-ingress-runtime para las nuevas rutas de recepción. La subruta anterior openclaw/plugin-sdk/channel-ingress continúa exportándose como una fachada de compatibilidad obsoleta para Plugins de terceros.
Resolutor en tiempo de ejecución
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,});No calcule previamente las listas de permitidos efectivas, los propietarios de comandos ni los grupos de comandos. El resolutor los deriva de las listas de permitidos sin procesar, las devoluciones de llamada del almacén, los descriptores de rutas, los grupos de acceso, la política y el tipo de conversación.
Resultado
Los Plugins incluidos deben consumir directamente las proyecciones modernas:
| Campo | Significado |
|---|---|
ingress |
decisión ordenada de los controles y admisión |
senderAccess |
solo autorización del remitente y de la conversación |
routeAccess |
proyección de la ruta y del remitente de la ruta |
commandAccess |
autorización de comandos; requested: false si no se ejecutó ningún control de comandos |
activationAccess |
resultado de mención o activación |
La autorización de eventos continúa disponible en el ingress.graph ordenado y en el ingress.reasonCode decisivo; no se emite ninguna proyección de eventos independiente.
Los auxiliares obsoletos del SDK para terceros pueden reconstruir internamente las estructuras anteriores. Las nuevas rutas de recepción incluidas no deben volver a convertir los resultados modernos en DTO locales.
Grupos de acceso
Las entradas accessGroup:<name> permanecen censuradas. El núcleo resuelve por sí mismo los grupos estáticos message.senders y llama a resolveAccessGroupMembership únicamente para los grupos dinámicos que requieren una consulta a la plataforma. Los grupos ausentes, no compatibles o con errores deniegan el acceso de forma predeterminada.
Modos de eventos
authMode |
Significado |
|---|---|
inbound |
controles normales del remitente entrante |
command |
controles de comandos para devoluciones de llamada o botones con ámbito |
origin-subject |
el actor debe coincidir con el sujeto del mensaje original |
route-only |
solo controles de rutas para eventos de confianza con ámbito de ruta |
none |
los eventos internos gestionados por el Plugin omiten la autorización compartida |
Use mayPair: false para reacciones, botones, devoluciones de llamada y comandos nativos.
Rutas y activación
Use descriptores de rutas para políticas de salas, temas, servidores, hilos o rutas anidadas:
route: { id: "room", allowed: roomAllowed, enabled: roomEnabled, senderPolicy: "replace", senderAllowFrom: roomAllowFrom, blockReason: "room_sender_not_allowlisted",}Use channelIngressRoutes(...) cuando un Plugin tenga varios descriptores de rutas opcionales; filtra las ramas deshabilitadas mientras mantiene los datos de las rutas genéricos y ordenados según la precedence de cada descriptor.
El control de menciones es un control de activación. Una mención no detectada devuelve admission: "skip" para que el núcleo de turnos no procese un turno exclusivamente de observación. La mayoría de los canales deben mantener la activación después de los controles de remitente y comandos. Las superficies de chat públicas que deban silenciar el tráfico sin menciones antes del ruido de las listas de permitidos de remitentes pueden optar por activation.order: "before-sender" cuando la omisión mediante comandos de texto esté deshabilitada. Los canales con activación implícita, como las respuestas en hilos de bots, pueden pasar activation.allowedImplicitMentionKinds; la proyección activationAccess.shouldBypassMention indica entonces cuándo un comando o una activación implícita omitieron una mención explícita.
Censura
Los valores sin procesar de los remitentes y las entradas sin procesar de las listas de permitidos son únicamente datos de entrada del resolutor. No deben aparecer en el estado resuelto, las decisiones, los diagnósticos, las instantáneas ni los datos de compatibilidad. Use identificadores opacos de sujetos, entradas, rutas y diagnósticos.
Verificación
pnpm test src/channels/message-access/message-access.test.ts src/plugin-sdk/channel-ingress-runtime.test.tspnpm plugin-sdk:api:check