---
read_when:
    - Створення або перенесення плагіна каналу обміну повідомленнями
    - Зміна списків дозволених для приватних повідомлень або груп, шлюзів маршрутизації, авторизації команд, авторизації подій або активації згадування
    - Перевірка редагування конфіденційних даних у вхідних повідомленнях каналу або меж сумісності SDK
sidebarTitle: Channel Ingress
summary: Експериментальний API приймання повідомлень каналу для авторизації вхідних повідомлень
title: API вхідних повідомлень каналу
x-i18n:
    generated_at: "2026-07-16T18:23:28Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: 3339af82a5dc3572d581f13960286f8b9ac933e7f491e8c4e0daba093caccc73
    source_path: plugins/sdk-channel-ingress.md
    workflow: 16
---

Вхідний контроль каналу — це експериментальна межа контролю доступу для вхідних
подій каналу. Плагіни відповідають за факти платформи та побічні ефекти; ядро відповідає за
загальну політику: списки дозволених для особистих повідомлень і груп, записи особистих повідомлень у сховищі сполучень, шлюзи маршрутів,
шлюзи команд, авторизацію подій, активацію за згадкою, редаговану діагностику та
допуск.

Використовуйте `openclaw/plugin-sdk/channel-ingress-runtime` для шляхів отримання.

## Розпізнавач середовища виконання

```ts
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` для реакцій, кнопок, зворотних викликів і власних команд.

## Маршрути та активація

Використовуйте дескриптори маршрутів для політики кімнати, теми, гільдії, гілки або вкладеного маршруту:

```ts
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` тоді повідомляє, коли команда або неявна
активація обійшла явну згадку.

## Редагування

Необроблені значення відправників і необроблені записи списків дозволених є лише вхідними даними розпізнавача. Вони
не повинні з’являтися в розпізнаному стані, рішеннях, діагностиці, знімках або
фактах сумісності. Використовуйте непрозорі ідентифікатори суб’єктів, записів, маршрутів і
діагностики.

## Перевірка

```bash
pnpm test src/channels/message-access/message-access.test.ts src/plugin-sdk/channel-ingress-runtime.test.ts
pnpm plugin-sdk:api:check
```
