API входящих сообщений канала

Входной контроль каналов — это экспериментальная граница управления доступом для входящих событий каналов. Плагины отвечают за сведения о платформах и побочные эффекты; ядро отвечает за общую политику: списки разрешённых отправителей для личных сообщений и групп, записи личных сообщений в хранилище сопряжений, проверки маршрутов, проверки команд, авторизацию событий, активацию по упоминанию, диагностику с редактированием конфиденциальных данных и допуск. Используйте openclaw/plugin-sdk/channel-ingress-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,
});

Не вычисляйте заранее эффективные списки разрешённых отправителей, владельцев команд или группы команд. Сопоставитель выводит их из исходных списков разрешённых отправителей, обратных вызовов хранилища, дескрипторов маршрутов, групп доступа, политики и типа беседы.

Результат

Встроенные плагины должны напрямую использовать современные проекции:

Поле	Значение
`ingress`	упорядоченное решение проверок и допуск
`senderAccess`	только авторизация отправителя и беседы
`routeAccess`	проекция маршрута и отправителя маршрута
`commandAccess`	авторизация команд; `requested: false`, если проверка команд не выполнялась
`activationAccess`	результат упоминания и активации

Авторизация событий остаётся доступной в упорядоченном ingress.graph и определяющем ingress.reasonCode; отдельная проекция событий не создаётся. Устаревшие вспомогательные функции стороннего SDK могут внутренне воссоздавать прежние структуры. Новые встроенные пути приёма не должны преобразовывать современные результаты обратно в локальные DTO.

Группы доступа

Записи accessGroup:<name> остаются отредактированными. Ядро самостоятельно разрешает статические группы message.senders и вызывает resolveAccessGroupMembership только для динамических групп, которым требуется запрос к платформе. При отсутствии, неподдерживаемом типе или ошибке группы доступ запрещается.

Режимы событий

`authMode`	Значение
`inbound`	обычные проверки входящего отправителя
`command`	проверки команд для обратных вызовов или кнопок с ограниченной областью действия
`origin-subject`	субъект должен совпадать с субъектом исходного сообщения
`route-only`	только проверки маршрутов для доверенных событий в области маршрута
`none`	внутренние события плагина обходят общую авторизацию

Используйте mayPair: false для реакций, кнопок, обратных вызовов и нативных команд.

Маршруты и активация

Используйте дескрипторы маршрутов для политики комнаты, темы, гильдии, ветки или вложенного маршрута:

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

Используйте channelIngressRoutes(...), когда плагин имеет несколько необязательных дескрипторов маршрутов; он отфильтровывает отключённые ветви, сохраняя сведения о маршрутах универсальными и упорядоченными по precedence каждого дескриптора. Проверка упоминания является проверкой активации. Отсутствие упоминания возвращает admission: "skip", чтобы ядро обработки хода не обрабатывало ход только для наблюдения. В большинстве каналов активацию следует проверять после проверок отправителя и команд. Общедоступные чаты, где трафик без упоминаний необходимо блокировать до появления сообщений о списке разрешённых отправителей, могут включить activation.order: "before-sender", когда обход для текстовых команд отключён. Каналы с неявной активацией, например ответы в ветках бота, могут передавать activation.allowedImplicitMentionKinds; проекция activationAccess.shouldBypassMention затем сообщает, когда команда или неявная активация позволили обойти требование явного упоминания.

Редактирование конфиденциальных данных

Исходные значения отправителей и исходные записи списков разрешённых отправителей служат только входными данными сопоставителя. Они не должны присутствовать в разрешённом состоянии, решениях, диагностике, снимках или данных совместимости. Используйте непрозрачные идентификаторы субъектов, записей, маршрутов и диагностики.

Проверка

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 входящих сообщений канала

Сопоставитель среды выполнения

Результат

Группы доступа

Режимы событий

Маршруты и активация

Редактирование конфиденциальных данных

Проверка

​Сопоставитель среды выполнения

​Результат

​Группы доступа

​Режимы событий

​Маршруты и активация

​Редактирование конфиденциальных данных

​Проверка

Сопоставитель среды выполнения

Результат

Группы доступа

Режимы событий

Маршруты и активация

Редактирование конфиденциальных данных

Проверка