> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API tiếp nhận của kênh

Luồng 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. Plugin sở hữu các dữ kiện nền tảng và tác dụng phụ; phần lõi sở hữu
chính sách dùng chung: danh sách cho phép DM/nhóm, mục DM trong kho ghép nối, cổng tuyến,
cổng lệnh, xác thực sự kiện, kích hoạt bằng lượt nhắc, chẩn đoán đã che thông tin, và
tiếp nhận.

Sử dụng `openclaw/plugin-sdk/channel-ingress-runtime` cho các đường dẫn nhận.

## Bộ phân giải thời gian chạy

```ts theme={"theme":{"light":"min-light","dark":"min-dark"}}
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,
});
```

Không tính toán trước danh sách cho phép có 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 của 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 sử dụng trực tiếp các phép chiếu hiện đại:

| Trường             | Ý nghĩa                                                                |
| ------------------ | ---------------------------------------------------------------------- |
| `ingress`          | quyết định cổng theo thứ tự và việc tiếp nhận                          |
| `senderAccess`     | chỉ xác thực 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`    | xác thực lệnh; `requested: false` khi không có cổng lệnh nào được chạy |
| `activationAccess` | kết quả lượt nhắc/kích hoạt                                            |

Xác thực 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 trình trợ giúp SDK bên thứ ba đã lỗi thời có thể tái tạo các dạng cũ trong nội bộ. Các
đường dẫn nhận đi kèm mới không nên chuyển đổi kết quả hiện đại trở lại thành DTO
cục bộ.

## Nhóm truy cập

Các mục `accessGroup:<name>` vẫn được che thông tin. Phần lõi tự phân giải các nhóm
`message.senders` tĩnh và chỉ gọi `resolveAccessGroupMembership`
cho các nhóm động cần tra cứu nền tảng. Các nhóm bị thiếu, không được hỗ trợ và
không thành công đều từ chối theo chế độ đóng.

## Chế độ sự kiện

| `authMode`       | Ý nghĩa                                                              |
| ---------------- | -------------------------------------------------------------------- |
| `inbound`        | cổng người gửi đến thông 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ể của tin nhắn gốc                      |
| `route-only`     | chỉ áp dụng cổng tuyến cho các sự kiện đáng tin cậy có phạm vi tuyến |
| `none`           | sự kiện nội bộ do Plugin sở hữu bỏ qua xác thực dùng chung           |

Sử dụng `mayPair: false` cho phản ứng, nút, callback và lệnh gốc.

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

Sử 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:

```ts theme={"theme":{"light":"min-light","dark":"min-dark"}}
route: {
  id: "room",
  allowed: roomAllowed,
  enabled: roomEnabled,
  senderPolicy: "replace",
  senderAllowFrom: roomAllowFrom,
  blockReason: "room_sender_not_allowlisted",
}
```

Sử dụng `channelIngressRoutes(...)` khi một Plugin có nhiều bộ mô tả tuyến
tùy chọn; nó lọc các nhánh bị tắt trong khi giữ dữ kiện tuyến ở dạng dùng chung
và sắp xếp theo `precedence` của từng bộ mô tả.

Cổng lượt nhắc là một cổng kích hoạt. Khi không có lượt nhắc, nó trả về
`admission: "skip"` để nhân lượt không xử lý một lượt chỉ quan sát.
Hầu hết các kênh nên đặt kích hoạt sau cổng người gửi và cổng lệnh. Các bề mặt
trò chuyện công khai phải giảm lưu lượng không được nhắc trước khi phát sinh nhiễu từ danh sách
cho phép người gửi có thể chọn `activation.order: "before-sender"` khi tính năng bỏ qua bằng 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ư câu trả lời trong
luồng của bot, phân giải `channels.defaults.implicitMentions` cùng các giá trị ghi đè của kênh và tài khoản
bằng `resolveChannelImplicitMentions(...)`, rồi truyền kết quả dưới dạng
`activation.implicitMentions`. Phép chiếu
`activationAccess.shouldBypassMention` báo cáo khi lệnh hoặc kích hoạt ngầm định
đã bỏ qua yêu cầu lượt nhắc tường minh.

## Che thông tin

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, ảnh chụp trạng thái hoặc
dữ kiện tương thích. Sử dụng mã định danh chủ thể, mã định danh mục, mã định danh tuyến và
mã định danh chẩn đoán dạng bất minh.

## Xác minh

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
pnpm test src/channels/message-access/message-access.test.ts src/plugin-sdk/channel-ingress-runtime.test.ts
pnpm plugin-sdk:api:check
```