---
read_when:
    - Создание или миграция плагина канала обмена сообщениями
    - Изменение списков разрешённых пользователей для личных сообщений или групп, шлюзов маршрутизации, авторизации команд, авторизации событий или активации по упоминанию
    - Проверка редактирования входящих данных каналов или границ совместимости SDK
sidebarTitle: Channel Ingress
summary: Экспериментальный API входящих сообщений канала для авторизации входящих сообщений
title: API входящих сообщений канала
x-i18n:
    generated_at: "2026-07-13T18:36:08Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 24
    provider: openai
    source_hash: 9e7b7d16bb0d53cec824cb353f691a2e17b37ca648eaefe6c0cbbdcd68a4c155
    source_path: plugins/sdk-channel-ingress.md
    workflow: 16
---

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

Используйте `openclaw/plugin-sdk/channel-ingress-runtime` для новых путей приёма. Более старый
подпуть `openclaw/plugin-sdk/channel-ingress` по-прежнему экспортируется как
устаревший фасад совместимости для сторонних плагинов.

## Сопоставитель среды выполнения

```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
```