Skip to main content

Documentation Index

Fetch the complete documentation index at: https://openclaw.zhcndoc.com/llms.txt

Use this file to discover all available pages before exploring further.

访问组是你一次定义并在渠道允许列表中通过 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 之类的群组发送者允许列表
  • 使用相同发送者匹配规则的、按房间划分的特定渠道发送者允许列表
  • 重用消息渠道发送者允许列表的命令授权路径
渠道支持取决于该渠道是否通过共享的 OpenClaw 发送者授权辅助工具进行接线。当前内置支持包括 Discord、Google Chat、Nostr、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 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。它会在运行前捕获许多无效的允许列表和策略组合。