Skip to main content
访问组是你一次定义并在渠道允许列表中通过 accessGroup:<name> 引用的命名发送者列表。 当同一批人需要在多个消息渠道中被允许，或者同一组受信任对象需要同时适用于 DM 和群组发送者授权时使用它们。 访问组本身不会授予访问权限。只有当允许列表字段引用它时，某个组才会生效。

​
静态消息发送者组

静态发送者组使用 type: "message.senders"。 
{
  accessGroups: {
    operators: {
      type: "message.senders",
      members: {
        "*": ["global-owner-id"],
        discord: ["discord:123456789012345678"],
        telegram: ["987654321"],
        whatsapp: ["+15551234567"],
      },
    },
  },
}
成员列表按消息渠道 id 进行键控：
键含义
"*"对于引用该组的每个消息渠道都会检查的共享条目。
discord仅在 Discord 允许列表匹配时检查的条目。
telegram仅在 Telegram 允许列表匹配时检查的条目。
whatsapp仅在 WhatsApp 允许列表匹配时检查的条目。
条目使用目标渠道的常规 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: {
      spaces: {
        "spaces/AAA": {
          users: ["accessGroup:oncall"],
        },
      },
    },
  },
}
你可以混合使用组和直接条目： 
{
  channels: {
    discord: {
      dmPolicy: "allowlist",
      allowFrom: ["accessGroup:operators", "discord:123456789012345678"],
    },
  },
}

​
支持的消息渠道路径

访问组可用于共享的消息渠道授权路径，包括：
  • 如 channels.<channel>.allowFrom 之类的 DM 发送者允许列表
  • 如 channels.<channel>.groupAllowFrom 之类的群组发送者允许列表
  • 使用相同发送者匹配规则的、按房间划分的特定渠道发送者允许列表
  • 重用消息渠道发送者允许列表的命令授权路径
Channel support depends on whether that channel is wired through the shared OpenClaw sender-authorization helpers. Current bundled support includes Discord, Feishu, Google Chat, iMessage, LINE, Mattermost, Microsoft Teams, Nextcloud Talk, Nostr, QQBot, Signal, WhatsApp, Zalo, and Zalo Personal. Static message.senders groups are designed to be channel-agnostic, so new message channels should support them by using the shared plugin SDK helpers instead of custom allowlist expansion.

​
插件诊断

插件作者可以在不将其展开回扁平 allowlist 的情况下检查结构化的访问组状态： 
import { resolveAccessGroupAllowFromState } from "openclaw/plugin-sdk/security-runtime";

const state = await resolveAccessGroupAllowFromState({
  accessGroups: cfg.accessGroups,
  allowFrom: channelConfig.allowFrom,
  channel: "my-channel",
  accountId: "default",
  senderId,
  isSenderAllowed,
});
结果会报告已引用、已匹配、缺失、不支持和失败的组。当你需要诊断或一致性测试时使用它。仅在仍然期望扁平 allowFrom 数组的兼容性路径中使用 expandAllowFromWithAccessGroups(...)。

​
Discord 渠道受众

Discord 还支持一种动态访问组类型： 
{
  accessGroups: {
    maintainers: {
      type: "discord.channelAudience",
      guildId: "1456350064065904867",
      channelId: "1456744319972282449",
      membership: "canViewChannel",
    },
  },
  channels: {
    discord: {
      dmPolicy: "allowlist",
      allowFrom: ["accessGroup:maintainers"],
    },
  },
}
discord.channelAudience 的意思是：“允许当前可以查看此服务器频道的 Discord DM 发送者”。OpenClaw 会在授权时通过 Discord 解析发送者，并应用 Discord 的 ViewChannel 权限规则。 当某个 Discord 频道已经是团队的事实来源时使用它，例如 #maintainers 或 #on-call。 要求与失败行为：
  • 机器人需要能够访问该服务器和频道。
  • 机器人需要启用 Discord Developer Portal 的 Server Members Intent。
  • 当 Discord 返回 Missing Access、发送者无法被解析为服务器成员，或该频道属于另一个服务器时，访问组会以关闭失败的方式处理。
更多 Discord 特定示例：Discord 访问控制

​
安全说明

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

​
故障排查

如果某个发送者本应匹配却被阻止：
  1. 确认允许列表字段包含精确的 accessGroup:<name> 引用。
  2. 确认 accessGroups.<name>.type 正确。
  3. 确认发送者 id 列在匹配的渠道键下，或者列在 "*" 下。
  4. 确认该条目使用的是该渠道的常规允许列表语法。
  5. 对于 Discord 渠道受众，请确认机器人能够看到该服务器频道，并且已启用 Server Members Intent。
编辑访问控制配置后运行 openclaw doctor。它会在运行前捕获许多无效的允许列表和策略组合。