概述
Channel Ingress 是入站 Channel 事件的实验性访问控制边界。插件拥有平台事实和副作用；核心拥有通用策略：DM/群组 allowlist、配对存储 DM 条目、路由门控、命令门控、事件授权、提及激活、脱敏诊断和准入决策。
使用 openclaw/plugin-sdk/channel-ingress-runtime 处理接收路径。旧的 openclaw/plugin-sdk/channel-ingress 子路径保留为废弃兼容性外观。
核心 API
运行时解析器
import {
defineStableChannelIngressIdentity,
resolveChannelMessageIngress,
} from "openclaw/plugin-sdk/channel-ingress-runtime";resolveChannelMessageIngress 参数：
| 参数 | 说明 |
|---|---|
channelId | Channel ID |
accountId | 账号 ID |
identity | 稳定身份描述符（defineStableChannelIngressIdentity 创建） |
subject | 发送者稳定 ID |
conversation | 会话类型（direct/group）和 ID |
event | 事件类型和授权模式 |
policy | DM/群组策略 |
allowFrom | DM allowlist |
route | 路由描述符 |
结果投影
ingress— 有序门控决策和准入senderAccess— 发送者/会话授权routeAccess— 路由和路由发送者投影commandAccess— 命令授权activationAccess— 提及/激活结果
事件授权模式（authMode）
| 模式 | 含义 |
|---|---|
inbound | 正常入站发送者门控 |
command | 回调或作用域按钮的命令门控 |
origin-subject | 操作者必须匹配原始消息主体 |
route-only | 仅路由门控（路由作用域受信任事件） |
none | 插件拥有的内部事件绕过共享授权 |
路由描述符
route: {
id: "room",
allowed: roomAllowed,
enabled: roomEnabled,
senderPolicy: "replace",
senderAllowFrom: roomAllowFrom,
blockReason: "room_sender_not_allowlisted",
}脱敏规则
原始发送者值和原始 allowlist 条目仅作为解析器输入。不得出现在已解析状态、决策、诊断、快照或兼容性事实中。使用不透明的主体 ID、条目 ID、路由 ID 和诊断 ID。
使用示例
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,
route,
readStoreAllowFrom,
});相关页面
- concepts/plugin-sdk-channel-plugins — Channel 插件构建指南
- concepts/plugin-sdk-channel-turn — 入站轮次内核
- concepts/plugin-sdk-subpaths — SDK 子路径目录