Plugin maintainer reference
API de entrada de canais
A entrada de canal é o limite experimental de controle de acesso para eventos de canal recebidos. Os Plugins controlam os fatos e efeitos colaterais da plataforma; o núcleo controla a política genérica: listas de permissões de MD/grupo, entradas de MD no armazenamento de pareamento, bloqueios de rota, bloqueios de comando, autorização de eventos, ativação por menção, diagnósticos com dados ocultados e admissão.
Use openclaw/plugin-sdk/channel-ingress-runtime para novos fluxos de
recebimento. O subcaminho mais antigo
openclaw/plugin-sdk/channel-ingress continua exportado como uma fachada de
compatibilidade obsoleta para Plugins de terceiros.
Resolvedor de tempo de execução
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,});Não pré-calcule listas de permissões efetivas, proprietários de comandos nem grupos de comandos. O resolvedor os deriva de listas de permissões brutas, retornos de chamada do armazenamento, descritores de rota, grupos de acesso, política e tipo de conversa.
Resultado
Os Plugins incluídos devem consumir diretamente as projeções modernas:
| Campo | Significado |
|---|---|
ingress |
decisão ordenada dos bloqueios e admissão |
senderAccess |
somente autorização do remetente/conversa |
routeAccess |
projeção da rota e do remetente da rota |
commandAccess |
autorização de comando; requested: false quando nenhum bloqueio foi aplicado |
activationAccess |
resultado da menção/ativação |
A autorização de eventos continua disponível no ingress.graph ordenado e no
ingress.reasonCode decisivo; nenhuma projeção de evento separada é emitida.
Auxiliares obsoletos do SDK para terceiros podem reconstruir internamente formatos mais antigos. Novos fluxos de recebimento incluídos não devem converter resultados modernos de volta em DTOs locais.
Grupos de acesso
As entradas accessGroup:<name> permanecem ocultadas. O núcleo resolve por
conta própria os grupos estáticos de message.senders e chama
resolveAccessGroupMembership somente para grupos dinâmicos que exigem uma
consulta à plataforma. Grupos ausentes, incompatíveis ou com falha são
bloqueados por padrão.
Modos de evento
authMode |
Significado |
|---|---|
inbound |
bloqueios normais do remetente de entrada |
command |
bloqueios de comando para retornos de chamada ou botões com escopo |
origin-subject |
o agente deve corresponder ao sujeito da mensagem original |
route-only |
somente bloqueios de rota para eventos confiáveis com escopo de rota |
none |
eventos internos controlados pelo Plugin ignoram a autorização compartilhada |
Use mayPair: false para reações, botões, retornos de chamada e comandos
nativos.
Rotas e ativação
Use descritores de rota para políticas de sala, tópico, servidor, thread ou rota aninhada:
route: { id: "room", allowed: roomAllowed, enabled: roomEnabled, senderPolicy: "replace", senderAllowFrom: roomAllowFrom, blockReason: "room_sender_not_allowlisted",}Use channelIngressRoutes(...) quando um Plugin tiver vários descritores de
rota opcionais; ele filtra ramificações desativadas enquanto mantém os fatos
de rota genéricos e ordenados pela precedence de cada descritor.
O bloqueio por menção é um bloqueio de ativação. A ausência de menção retorna
admission: "skip" para que o núcleo de turnos não processe um turno apenas
de observação. A maioria dos canais deve manter a ativação após os bloqueios
de remetente e comando. Superfícies públicas de bate-papo que precisam
silenciar o tráfego sem menções antes do ruído da lista de permissões de
remetentes podem optar por activation.order: "before-sender" quando o desvio
por comando de texto estiver desativado. Canais com ativação implícita, como
respostas em threads de bots, podem fornecer
activation.allowedImplicitMentionKinds; o
activationAccess.shouldBypassMention projetado então informa quando um
comando ou uma ativação implícita dispensou uma menção explícita.
Ocultação
Valores brutos de remetentes e entradas brutas de listas de permissões são apenas dados de entrada do resolvedor. Eles não devem aparecer no estado resolvido, nas decisões, nos diagnósticos, nos instantâneos nem nos fatos de compatibilidade. Use IDs opacos de sujeitos, entradas, rotas e diagnósticos.
Verificação
pnpm test src/channels/message-access/message-access.test.ts src/plugin-sdk/channel-ingress-runtime.test.tspnpm plugin-sdk:api:check