访问群组

访问组是您在 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> 引用一个组。

DM 允许列表示例：

{
  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。

要求和失败行为：

• 机器人需要能够访问该服务器和频道。
• 机器人需要 Discord Developer Portal 中的 Server Members Intent。
• 当 Discord 返回 Missing Access、无法将发送者解析为服务器成员，或该频道属于另一个服务器时，访问组会失败时关闭。

更多 Discord 特定示例：Discord access control

插件诊断¶

插件作者可以在不将其展开回扁平允许列表的情况下，检查结构化的访问组状态：

import { resolveAccessGroupAllowFromState } from "openclaw/plugin-sdk/access-groups";

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

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

安全说明¶

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

故障排除¶

如果某个发送者本应匹配但被阻止：

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

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

相关¶

• 群组 — 群聊行为和提及门控
• 配对 — 用于频道发送者的独立 DM 配对流程
• 频道概览 — 这些群组适用的频道