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