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