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