# API nhận vào của kênh

Nhận vào của kênh là ranh giới kiểm soát truy cập thử nghiệm cho các sự kiện kênh gửi đến. Dùng openclaw/plugin-sdk/channel-ingress-runtime cho các đường dẫn nhận. Subpath cũ hơn openclaw/plugin-sdk/channel-ingress vẫn được xuất như một facade tương thích đã lỗi thời cho Plugin bên thứ ba.

Plugin sở hữu dữ kiện nền tảng và hiệu ứng phụ. Core sở hữu chính sách chung: danh sách cho phép DM/nhóm, mục DM trong kho ghép cặp, cổng tuyến, cổng lệnh, xác thực sự kiện, kích hoạt bằng nhắc đến, chẩn đoán đã biên tập, và tiếp nhận.

# Bộ phân giải 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,
});

Không tính trước danh sách cho phép hiệu lực, chủ sở hữu lệnh, hoặc nhóm lệnh. Bộ phân giải suy ra chúng từ danh sách cho phép thô, callback kho, bộ mô tả tuyến, nhóm truy cập, chính sách, và loại cuộc trò chuyện.

# Kết quả

Các Plugin đi kèm nên dùng trực tiếp các phép chiếu hiện đại:

• ingress: quyết định cổng và tiếp nhận theo thứ tự
• senderAccess: chỉ ủy quyền người gửi/cuộc trò chuyện
• routeAccess: phép chiếu tuyến và người gửi theo tuyến
• commandAccess: ủy quyền lệnh; false khi không có cổng lệnh nào chạy
• activationAccess: kết quả nhắc đến/kích hoạt

Ủy quyền sự kiện vẫn có sẵn trên ingress.graph theo thứ tự và ingress.reasonCode mang tính quyết định; không phát ra phép chiếu sự kiện riêng.

Các helper SDK bên thứ ba đã lỗi thời có thể dựng lại các dạng cũ hơn nội bộ. Các đường dẫn nhận đi kèm mới không nên dịch kết quả hiện đại ngược lại thành DTO cục bộ.

# Nhóm truy cập

Các mục accessGroup:<name> vẫn được biên tập. Core tự phân giải các nhóm tĩnh message.senders và chỉ gọi resolveAccessGroupMembership cho các nhóm động cần tra cứu nền tảng. Nhóm bị thiếu, không được hỗ trợ, và thất bại đều đóng khi lỗi.

# Chế độ sự kiện

authMode	Ý nghĩa
inbound	cổng người gửi gửi đến bình thường
command	cổng lệnh cho callback hoặc nút có phạm vi
origin-subject	tác nhân phải khớp với chủ thể tin nhắn gốc
route-only	chỉ cổng tuyến cho sự kiện tin cậy theo tuyến
none	sự kiện nội bộ do Plugin sở hữu bỏ qua xác thực dùng chung

Dùng mayPair: false cho phản ứng, nút, callback, và lệnh gốc.

# Tuyến và kích hoạt

Dùng bộ mô tả tuyến cho chính sách phòng, chủ đề, guild, luồng, hoặc tuyến lồng nhau:

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

Dùng channelIngressRoutes(...) khi một Plugin có vài bộ mô tả tuyến tùy chọn; nó lọc các nhánh đã tắt trong khi vẫn giữ dữ kiện tuyến ở dạng chung và được sắp theo precedence của từng bộ mô tả.

Cổng nhắc đến là cổng kích hoạt. Một lần nhắc đến bị trượt trả về admission: "skip" để kernel lượt không xử lý lượt chỉ quan sát. Hầu hết kênh nên để kích hoạt sau cổng người gửi và cổng lệnh. Các bề mặt chat công khai cần làm im lưu lượng không được nhắc đến trước nhiễu danh sách cho phép người gửi có thể chọn activation.order: "before-sender" khi bỏ qua lệnh văn bản bị tắt. Các kênh có kích hoạt ngầm định, chẳng hạn như trả lời trong luồng bot, có thể truyền activation.allowedImplicitMentionKinds; activationAccess.shouldBypassMention được chiếu sau đó báo cáo khi lệnh hoặc kích hoạt ngầm định đã bỏ qua một lần nhắc đến rõ ràng.

# Biên tập

Giá trị người gửi thô và mục danh sách cho phép thô chỉ là đầu vào của bộ phân giải. Chúng không được xuất hiện trong trạng thái đã phân giải, quyết định, chẩn đoán, snapshot, hoặc dữ kiện tương thích. Dùng id chủ thể mờ, id mục, id tuyến, và id chẩn đoán.

# Xác minh

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