OpenClaw 访问组（Access groups）让你定义一次发件人列表，然后在多个消息渠道的白名单中通过 accessGroup:<name> 引用。静态组（message.senders 类型）按渠道 ID 列出成员，"*" 键值对所有引用该组的渠道生效。Discord 还支持动态组（discord.channelAudience），直接以 Discord 频道观众作为允许条件。访问组自身不授权，必须被 allowlist 字段引用才生效。配置后可用 openclaw doctor 校验。

OpenClaw 访问组配置指南：跨渠道发件人白名单复用

静态发件人组

静态组使用 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> 引用组。

私信白名单示例：

{
  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
• 群发泄件人白名单，如 channels.<channel>.groupAllowFrom
• 特定房间的发件人白名单（使用相同的发件人匹配规则）
• 复用了消息渠道发件人白名单的命令授权路径

渠道支持取决于该渠道是否通过 OpenClaw 共享的发件人授权辅助工具接线。当前内置支持：Discord、飞书、Google Chat、iMessage、LINE、Mattermost、Microsoft Teams、Nextcloud Talk、Nostr、QQBot、Signal、WhatsApp、Zalo、Zalo Personal。静态 message.senders 组是渠道无关的，新消息渠道应使用共享的插件 SDK 辅助工具（而非自定义白名单展开）来支持它们。

插件诊断

插件作者可以检查结构化的访问组状态，而无需将其展开为扁平白名单：

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 私信发送者”。OpenClaw 在授权时通过 Discord 解析发送者并应用 Discord ViewChannel 权限规则。

当 Discord 频道已是团队（如 #maintainers 或 #on-call）的事实标准时使用此组。

要求与失败行为：

• 机器人需要能访问该公会和频道。
• 机器人需要在 Discord 开发者门户启用 Server Members Intent。
• 当 Discord 返回 Missing Access、无法解析发送者为公会成员或频道属于其他公会时，访问组按失败关闭（fail closed）。

更多 Discord 专属示例：Discord 接入控制

安全说明

• 访问组是白名单别名，不是角色。它们本身不会创建所有者、批准配对请求或授予工具权限。
• dmPolicy: "open" 仍然要求有效的 DM 白名单中包含 "*"。引用访问组不等于公开访问。
• 缺失的组名按失败关闭（fail closed）。如果 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。它能在运行时之前捕获许多无效的白名单和策略组合。

常见问题

访问组可以跨多个消息渠道共用吗？

可以。在多个渠道的 allowFrom 或 groupAllowFrom 中引用同一个 accessGroup:<name>，只需定义一次成员列表。

为什么我引用了访问组但发件人仍被拒绝？

检查：accessGroups 中组的名称是否精确匹配引用中的名称；type 是否设置正确；发件人 ID 是否写在了匹配渠道的键下（或 "*" 下）；渠道支持该路径；对于 Discord 频道观众组，确保机器人有 Server Members Intent 且能访问频道。

访问组和直接在白名单中写 ID 有什么区别？

访问组让你在一个位置管理多个渠道的通用发件人列表，减少重复。运行 openclaw doctor 可验证引用是否有效。如果只在一个渠道使用，直接写 ID 更简单。