Plugin maintainer reference

API masukan saluran

Ingress kanal adalah batas kontrol akses eksperimental untuk peristiwa kanal masuk. Plugin memiliki fakta platform dan efek samping; inti memiliki kebijakan generik: daftar izin DM/grup, entri DM penyimpanan pemasangan, gerbang rute, gerbang perintah, autentikasi peristiwa, aktivasi sebutan, diagnostik tersunting, dan penerimaan.

Gunakan openclaw/plugin-sdk/channel-ingress-runtime untuk jalur penerimaan baru. Subjalur openclaw/plugin-sdk/channel-ingress yang lebih lama tetap diekspor sebagai fasad kompatibilitas usang untuk plugin pihak ketiga.

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

Jangan melakukan prakomputasi daftar izin efektif, pemilik perintah, atau grup perintah. Resolver menurunkannya dari daftar izin mentah, callback penyimpanan, deskriptor rute, grup akses, kebijakan, dan jenis percakapan.

Hasil

Plugin bawaan harus menggunakan proyeksi modern secara langsung:

Bidang	Makna
`ingress`	keputusan gerbang dan penerimaan yang berurutan
`senderAccess`	hanya otorisasi pengirim/percakapan
`routeAccess`	proyeksi rute dan pengirim rute
`commandAccess`	otorisasi perintah; `requested: false` saat tidak ada gerbang perintah yang dijalankan
`activationAccess`	hasil sebutan/aktivasi

Otorisasi peristiwa tetap tersedia pada ingress.graph yang berurutan dan ingress.reasonCode yang menentukan; tidak ada proyeksi peristiwa terpisah yang dihasilkan.

Pembantu SDK pihak ketiga yang usang dapat membangun ulang bentuk lama secara internal. Jalur penerimaan bawaan baru tidak boleh menerjemahkan hasil modern kembali menjadi DTO lokal.

Grup akses

Entri accessGroup:<name> tetap disunting. Inti menyelesaikan grup statis message.senders sendiri dan memanggil resolveAccessGroupMembership hanya untuk grup dinamis yang memerlukan pencarian platform. Grup yang tidak ada, tidak didukung, dan gagal akan ditolak secara tertutup.

Mode peristiwa

`authMode`	Makna
`inbound`	gerbang pengirim masuk normal
`command`	gerbang perintah untuk callback atau tombol bercakupan
`origin-subject`	aktor harus cocok dengan subjek pesan asli
`route-only`	gerbang rute saja untuk peristiwa tepercaya bercakupan rute
`none`	peristiwa internal milik plugin melewati autentikasi bersama

Gunakan mayPair: false untuk reaksi, tombol, callback, dan perintah native.

Rute dan aktivasi

Gunakan deskriptor rute untuk kebijakan ruang, topik, guild, utas, atau rute bertingkat:

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

Gunakan channelIngressRoutes(...) saat plugin memiliki beberapa deskriptor rute opsional; fungsi ini memfilter cabang yang dinonaktifkan sekaligus menjaga fakta rute tetap generik dan diurutkan berdasarkan precedence setiap deskriptor.

Gerbang sebutan adalah gerbang aktivasi. Sebutan yang tidak cocok menghasilkan admission: "skip" agar kernel giliran tidak memproses giliran khusus pengamatan. Sebagian besar kanal harus menempatkan aktivasi setelah gerbang pengirim dan perintah. Permukaan obrolan publik yang harus meredam lalu lintas tanpa sebutan sebelum derau daftar izin pengirim dapat memilih activation.order: "before-sender" saat bypass perintah teks dinonaktifkan. Kanal dengan aktivasi implisit, seperti balasan dalam utas bot, dapat meneruskan activation.allowedImplicitMentionKinds; proyeksi activationAccess.shouldBypassMention kemudian melaporkan ketika aktivasi perintah atau implisit melewati sebutan eksplisit.

Penyuntingan

Nilai pengirim mentah dan entri daftar izin mentah hanya merupakan input resolver. Keduanya tidak boleh muncul dalam status terselesaikan, keputusan, diagnostik, snapshot, atau fakta kompatibilitas. Gunakan ID subjek buram, ID entri, ID rute, dan ID diagnostik.

Verifikasi

bash

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

Was this useful?