Channel ingress API 是 OpenClaw 实验性的通道入站消息访问控制边界，用于决定是否允许消息进入工作区。使用 resolveChannelMessageIngress 运行时解析器，传入身份、会话、策略和路由描述符；结果包含门控决策、发送者授权、路由授权、命令授权和提及激活。所有原始发送者值和白名单条目会被自动脱敏，不会出现在诊断中。验证可运行 pnpm test src/channels/... 和 pnpm plugin-sdk:api:check。

OpenClaw 通道入口 API：入站消息授权与路由配置

Channel ingress 是 OpenClaw 实验性的入站通道事件访问控制边界。插件接收路径应使用 openclaw/plugin-sdk/channel-ingress-runtime。旧的 openclaw/plugin-sdk/channel-ingress 子路径作为弃用兼容层保留给第三方插件。

插件拥有平台事实和副作用。Core 拥有通用策略：DM/群组白名单、配对存储中的 DM 条目、路由门、命令门、事件认证、提及激活、脱敏诊断和准入控制。

运行时解析器

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

不要预计算有效的白名单、命令所有者或命令组。解析器从原始白名单、存储回调、路由描述符、访问组、策略和会话类型中派生它们。

返回结果字段说明

绑定插件应直接使用现代投影：

• ingress：有序的门控决策和准入
• senderAccess：发送者/会话授权
• routeAccess：路由和路由-发送者投影
• commandAccess：命令授权；未执行命令门时为 false
• activationAccess：提及/激活结果

事件授权仍在有序的 ingress.graph 和决定性 ingress.reasonCode 上可用；不单独发射事件投影。

弃用的第三方 SDK 辅助函数可能在内部重建旧形状。新的绑定接收路径不应将现代结果转换回本地 DTO。

访问组与脱敏

accessGroup:<name> 条目保持脱敏。Core 自己解析静态的 message.senders 组，并仅对需要平台查找的动态组调用 resolveAccessGroupMembership。缺失、不支持、失败组以失败关闭。

事件认证模式

authMode	含义
inbound	普通入站发送者门
command	针对回调解绑或作用域按钮的命令门
origin-subject	操作者必须与原始消息主体匹配
route-only	仅路由门，用于路由作用域的受信任事件
none	插件拥有的内部事件，跳过共享认证

对于表情回复、按钮、回调和原生命令，使用 mayPair: false。

路由与提及激活

使用路由描述符处理房间、话题、公会、线程或嵌套路由策略：

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

当插件有多个可选路由描述符时，使用 channelIngressRoutes(...)；它过滤禁用的分支，同时保持路由事实通用且按每个描述符的 precedence 排序。

提及门控是激活门。提及缺失返回 admission: "skip"，因此 turn 核心不会处理仅观察的 turn。大多数通道应在发送者门和命令门之后进行激活。需要在发送者白名单干扰前静默非提及流量的公共聊天表面，可以在文本命令旁路禁用时选择 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

常见问题

怎么配置 channel ingress 的 DM 白名单

在 policy 对象中设置 dmPolicy 字段，值为 allow、deny 或 pairing。同时可在 allowFrom 中传入允许列表。对于群组消息，使用 groupPolicy 和 groupAllowFrom，并可设置 groupAllowFromFallbackToAllowFrom: true 回退到发送者白名单。

resolveChannelMessageIngress 返回的 ingress 结果怎么解读

ingress 对象包含 graph（有序门控列表）和 reasonCode（最终拒绝原因）。如果 admission 为 "allow"，则消息通过；为 "deny" 时可在 reasonCode 中查看具体原因，如 "dm_not_allowed"、"group_not_allowed"、"command_not_authorized" 等。

群组消息总是被拒绝是什么原因

首先检查 groupPolicy 是否设置为 allow，以及 groupAllowFrom 是否包含发送者 ID。如果 groupAllowFromFallbackToAllowFrom 为 true，也会检查 allowFrom。另外确认 accessGroups 中无失败组（失败组导致失败关闭）。最后查看 ingress.reasonCode 获取具体拒绝原因。