채널 인그레스 API

채널 인그레스는 인바운드 채널 이벤트를 위한 실험적 액세스 제어 경계입니다. Plugin은 플랫폼 정보와 부수 효과를 담당하고, 코어는 DM/그룹 허용 목록, 페어링 저장소의 DM 항목, 경로 게이트, 명령 게이트, 이벤트 인증, 멘션 활성화, 민감 정보가 제거된 진단 및 허용 여부 결정과 같은 일반 정책을 담당합니다. 수신 경로에는 openclaw/plugin-sdk/channel-ingress-runtime을 사용하십시오.

런타임 리졸버

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,
});

유효 허용 목록, 명령 소유자 또는 명령 그룹을 미리 계산하지 마십시오. 리졸버는 원시 허용 목록, 저장소 콜백, 경로 설명자, 액세스 그룹, 정책 및 대화 종류로부터 이를 도출합니다.

결과

번들 Plugin은 최신 프로젝션을 직접 사용해야 합니다.

필드	의미
`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`	Plugin이 소유한 내부 이벤트는 공유 인증을 우회함

반응, 버튼, 콜백 및 네이티브 명령에는 mayPair: false을 사용하십시오.

경로 및 활성화

방, 주제, 길드, 스레드 또는 중첩 경로 정책에는 경로 설명자를 사용하십시오.

route: {
  id: "room",
  allowed: roomAllowed,
  enabled: roomEnabled,
  senderPolicy: "replace",
  senderAllowFrom: roomAllowFrom,
  blockReason: "room_sender_not_allowlisted",
}

Plugin에 선택적 경로 설명자가 여러 개 있는 경우 channelIngressRoutes(...)을 사용하십시오. 각 설명자의 precedence에 따라 경로 정보를 일반적으로 유지하고 순서를 지정하면서 비활성화된 분기를 필터링합니다. 멘션 게이팅은 활성화 게이트입니다. 멘션이 일치하지 않으면 admission: "skip"을 반환하므로 턴 커널이 관찰 전용 턴을 처리하지 않습니다. 대부분의 채널에서는 발신자 및 명령 게이트 이후에 활성화를 배치해야 합니다. 발신자 허용 목록으로 인한 불필요한 메시지가 발생하기 전에 멘션되지 않은 트래픽을 억제해야 하는 공개 채팅 화면에서는 텍스트 명령 우회가 비활성화된 경우 activation.order: "before-sender"을 선택할 수 있습니다. 봇 스레드의 답글처럼 암시적으로 활성화되는 채널은 activation.allowedImplicitMentionKinds을 전달할 수 있습니다. 그러면 프로젝션된 activationAccess.shouldBypassMention에서 명령 또는 암시적 활성화가 명시적 멘션을 우회한 경우를 보고합니다.

민감 정보 제거

원시 발신자 값과 원시 허용 목록 항목은 리졸버 입력으로만 사용됩니다. 이러한 값은 해석된 상태, 결정, 진단, 스냅샷 또는 호환성 정보에 나타나서는 안 됩니다. 불투명한 주체 ID, 항목 ID, 경로 ID 및 진단 ID를 사용하십시오.

검증

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

CLI commands

RPC and API

Codex harness

Plugin reference

Plugin SDK reference

Plugin maintainer reference

Templates

Technical reference

Concept internals

Project

Contributing

채널 인그레스 API

런타임 리졸버

결과

액세스 그룹

이벤트 모드

경로 및 활성화

민감 정보 제거

검증

​런타임 리졸버

​결과

​액세스 그룹

​이벤트 모드

​경로 및 활성화

​민감 정보 제거

​검증

런타임 리졸버

결과

액세스 그룹

이벤트 모드

경로 및 활성화

민감 정보 제거

검증