API de entrada de canais

O ingresso de canais é o limite experimental de controle de acesso para eventos recebidos de canais. Os plugins são responsáveis pelos fatos da plataforma e pelos efeitos colaterais; o núcleo é responsável pela política genérica: listas de permissões de mensagens diretas/grupos, entradas de mensagens diretas do armazenamento de pareamento, gates de rota, gates de comando, autenticação de eventos, ativação por menção, diagnósticos com dados ocultados e admissão. Use openclaw/plugin-sdk/channel-ingress-runtime nos caminhos de recebimento.

Resolvedor de runtime

import {
  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, callbacks de armazenamento, descritores de rota, grupos de acesso, política e tipo de conversa.

Resultado

Os plugins incluídos no pacote devem consumir diretamente as projeções modernas:

Campo	Significado
`ingress`	decisão ordenada dos gates e admissão
`senderAccess`	somente autorização do remetente/da conversa
`routeAccess`	projeção da rota e do remetente da rota
`commandAccess`	autorização de comando; `requested: false` quando nenhum gate de comando foi executado
`activationAccess`	resultado de menção/ativação

A autorização de eventos continua disponível no ingress.graph ordenado e no ingress.reasonCode decisivo; nenhuma projeção separada de evento é emitida. Helpers obsoletos do SDK de terceiros podem reconstruir formatos antigos internamente. Novos caminhos de recebimento incluídos no pacote não devem converter resultados modernos de volta em DTOs locais.

Grupos de acesso

As entradas de accessGroup:<name> permanecem com dados ocultados. O núcleo resolve por conta própria os grupos message.senders estáticos e chama resolveAccessGroupMembership somente para grupos dinâmicos que exigem uma consulta à plataforma. Grupos ausentes, sem suporte ou com falha são bloqueados por padrão.

Modos de evento

`authMode`	Significado
`inbound`	gates normais de remetente para eventos recebidos
`command`	gates de comando para callbacks ou botões com escopo
`origin-subject`	o ator deve corresponder ao sujeito da mensagem original
`route-only`	somente gates de rota para eventos confiáveis com escopo de rota
`none`	eventos internos pertencentes ao plugin ignoram a autenticação compartilhada

Use mayPair: false para reações, botões, callbacks e comandos nativos.

Rotas e ativação

Use descritores de rota para políticas de sala, tópico, guilda, 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 desabilitadas, mantendo os fatos das rotas genéricos e ordenados pelo precedence de cada descritor. O gate de menção é um gate de ativação. A ausência de uma menção retorna admission: "skip" para que o kernel do turno não processe um turno somente de observação. A maioria dos canais deve manter a ativação depois dos gates de remetente e de comando. Superfícies de chat público que precisam silenciar tráfego sem menção antes do ruído da lista de permissões do remetente podem optar por activation.order: "before-sender" quando o bypass de comandos de texto estiver desabilitado. Canais com ativação implícita, como respostas em threads do bot, podem passar activation.allowedImplicitMentionKinds; o activationAccess.shouldBypassMention projetado então informa quando um comando ou uma ativação implícita ignorou a exigência de uma menção explícita.

Ocultação de dados

Valores brutos de remetente e entradas brutas de listas de permissões servem apenas como entrada do resolvedor. Eles nunca devem aparecer no estado resolvido, nas decisões, nos diagnósticos, nos snapshots 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.ts
pnpm plugin-sdk:api:check

CLI commands

RPC and API

Codex harness

Plugin reference

Plugin SDK reference

Plugin maintainer reference

Templates

Technical reference

Concept internals

Project

Contributing

API de entrada de canais

Resolvedor de runtime

Resultado

Grupos de acesso

Modos de evento

Rotas e ativação

Ocultação de dados

Verificação

​Resolvedor de runtime

​Resultado

​Grupos de acesso

​Modos de evento

​Rotas e ativação

​Ocultação de dados

​Verificação

Resolvedor de runtime

Resultado

Grupos de acesso

Modos de evento

Rotas e ativação

Ocultação de dados

Verificação