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