访问组

访问组是命名的发送者列表，你可以在 accessGroups 下定义一次，然后使用 accessGroup:<name> 从渠道允许列表中引用。

当同一批人员需要获准使用多个消息渠道，或一组受信任的人员应同时适用于私信和群组发送者授权时，可使用访问组。

访问组本身不授予任何权限。只有当允许列表字段引用它时，它才会生效。

静态消息发送者组

静态发送者组使用 type: "message.senders"。members 以消息渠道 ID 为键，此外还可使用 "*" 指定由所有渠道共享的条目：

{  accessGroups: {    operators: {      type: "message.senders",      members: {        "*": ["global-owner-id"],        discord: ["discord:123456789012345678"],        telegram: ["987654321"],        whatsapp: ["+15551234567"],      },    },  },}

条目按照目标渠道的常规 allowFrom 规则进行匹配。OpenClaw 不会在渠道之间转换发送者 ID：如果 Alice 同时拥有 Telegram ID 和 Discord ID，请将这两个 ID 分别列在对应的渠道键下。

从允许列表引用组

在消息渠道路径支持发送者允许列表的任何位置，均可使用 accessGroup:<name> 引用访问组。

私信允许列表示例：

{  accessGroups: {    operators: {      type: "message.senders",      members: {        discord: ["discord:123456789012345678"],        telegram: ["987654321"],      },    },  },  channels: {    discord: {      dmPolicy: "allowlist",      allowFrom: ["accessGroup:operators"],    },    telegram: {      dmPolicy: "allowlist",      allowFrom: ["accessGroup:operators"],    },  },}

群组发送者允许列表示例：

{  accessGroups: {    oncall: {      type: "message.senders",      members: {        whatsapp: ["+15551234567"],        googlechat: ["users/1234567890"],      },    },  },  channels: {    whatsapp: {      groupPolicy: "allowlist",      groupAllowFrom: ["accessGroup:oncall"],    },    googlechat: {      groups: {        "spaces/AAA": {          users: ["accessGroup:oncall"],        },      },    },  },}

可以混合使用访问组和直接条目：

{  channels: {    discord: {      dmPolicy: "allowlist",      allowFrom: ["accessGroup:operators", "discord:123456789012345678"],    },  },}

支持的消息渠道路径

访问组适用于共享的消息渠道授权路径：

• 私信发送者允许列表，例如 channels.<channel>.allowFrom
• 群组发送者允许列表，例如 channels.<channel>.groupAllowFrom
• 使用相同发送者匹配规则的渠道专属房间级发送者允许列表（例如 Google Chat groups.<space>.users）
• 复用消息渠道发送者允许列表的命令授权路径

渠道是否支持访问组，取决于该渠道是否接入 OpenClaw 共享的发送者授权辅助函数。目前内置支持包括 ClickClack、Discord、Feishu、Google Chat、iMessage、IRC、LINE、Mattermost、Microsoft Teams、Nextcloud Talk、Nostr、QQ Bot、Signal、Slack、SMS、Telegram、WhatsApp、Zalo 和 Zalo Personal。静态 message.senders 组与渠道无关，因此新消息渠道只要使用共享的插件 SDK 入口辅助函数，而非自定义允许列表展开逻辑，即可支持这些组。

Discord 渠道受众

Discord 还支持一种动态访问组类型：

{  accessGroups: {    maintainers: {      type: "discord.channelAudience",      guildId: "1456350064065904867",      channelId: "1456744319972282449",      membership: "canViewChannel",    },  },  channels: {    discord: {      dmPolicy: "allowlist",      allowFrom: ["accessGroup:maintainers"],    },  },}

discord.channelAudience 表示“允许当前可以查看此服务器渠道的 Discord 私信发送者”。OpenClaw 会在授权时通过 Discord 解析发送者，并应用 Discord ViewChannel 权限规则。membership 是可选项，默认值为 canViewChannel。

当某个 Discord 渠道已经是团队的事实来源时（例如 #maintainers 或 #on-call），可使用此类型。

要求和失败行为：

• Bot 需要拥有该服务器和渠道的访问权限。
• Bot 需要启用 Discord Developer Portal 中的 Server Members Intent。
• 当 Discord 返回 Missing Access、无法将发送者解析为服务器成员，或该渠道属于另一个服务器时，访问组会以拒绝访问的方式失败。

更多 Discord 专属示例：Discord 访问控制

插件诊断

插件作者可以检查结构化访问组状态，而无需将其重新展开为扁平允许列表：

 const state = await resolveAccessGroupAllowFromState({  accessGroups: cfg.accessGroups,  allowFrom: channelConfig.allowFrom,  channel: "my-channel",  accountId: "default",  senderId,  isSenderAllowed,});

结果会报告已引用、已匹配、缺失、不受支持以及失败的组。可将其用于诊断或一致性测试。仅在仍然要求扁平 allowFrom 数组的兼容路径中使用 expandAllowFromWithAccessGroups(...)。

安全注意事项

• 访问组是允许列表别名，而不是角色。它们本身不会创建所有者、批准配对请求或授予工具权限。
• dmPolicy: "open" 仍要求有效的私信允许列表中包含 "*"。引用访问组并不等同于公开访问。
• 缺失的组名会以拒绝访问的方式失败。如果 allowFrom 包含 accessGroup:operators，而 accessGroups.operators 不存在，则该条目不会授权任何人。
• 保持渠道 ID 稳定。当渠道同时支持数字/用户 ID 和显示名称时，优先使用数字/用户 ID。

故障排除

如果发送者本应匹配却被阻止：

1. 确认允许列表字段包含完全一致的 accessGroup:<name> 引用。
2. 确认 accessGroups.<name>.type 正确。
3. 确认发送者 ID 已列在对应的渠道键下或 "*" 下。
4. 确认该条目使用此渠道的常规允许列表语法。
5. 对于 Discord 渠道受众，请确认 Bot 可以查看服务器渠道，并且已启用 Server Members Intent。

编辑访问控制配置后，运行 openclaw doctor。它可以在运行时之前发现许多无效的允许列表和策略组合。