访问控制

Warning

在 groupPolicy: "allowlist" 下，群组路由会连续执行两个关卡：

1. 发送者允许列表（channels.imessage.groupAllowFrom）——句柄、accessGroup:<name>、chat_guid、chat_identifier 或 chat_id。空的有效列表（没有 groupAllowFrom，也没有 allowFrom 回退）会阻止所有群组发送者。
2. 群组注册表（channels.imessage.groups）——一旦映射中存在条目即强制执行：聊天必须匹配显式的按 chat_id 条目，或 groups: { "*": { ... } } 通配符。当 groups 为空或缺失时，仅由发送者允许列表决定准入。

如果未配置有效的群组发送者允许列表，所有群组消息都会在注册表关卡之前被丢弃。每个关卡在默认日志级别下都有自己的 warn 级别信号，并且各自指明不同的修复方式：

• 启动时每个账号一次性出现，当有效的群组发送者允许列表为空时：imessage: groupPolicy="allowlist" for account "<id>" but no group sender allowlist is configured ... —— 通过设置 channels.imessage.groupAllowFrom（或 allowFrom）修复；仅添加 groups 条目仍会让关卡 1 阻止所有发送者。
• 运行时每个 chat_id 一次性出现，当发送者通过了关卡 1，但该聊天缺失于已填充的 groups 注册表时：imessage: dropping group message from chat_id=<id> ... —— 通过将该 chat_id（或 "*"）添加到 channels.imessage.groups 下修复。

私信不受影响——它们走不同的代码路径。

在 groupPolicy: "allowlist" 下，群组流程的推荐配置：

{
  channels: {
    imessage: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
      groups: { "*": { "requireMention": true } },
    },
  },
}

仅 groupAllowFrom 即可允许这些发送者在任意群组中接入；添加 groups 块可限定允许哪些聊天（并设置每个聊天的选项，例如 requireMention）。

群组的提及门控：

• iMessage 没有原生的提及元数据
• 提及检测使用 agents.entries.*.groupChat.mentionPatterns，然后是 messages.groupChat.mentionPatterns；当两者都未设置时，模式会从被路由代理的 identity.name 和 identity.emoji 派生
• 群组默认要求提及，即使未显式配置模式；因此，允许列表中的发送者消息可能会被跳过，除非其中包含代理的名称或表情符号
• 在所选代理或全局级别显式设置 mentionPatterns: [] 会抑制基于身份派生的模式；当没有可用模式时，iMessage 无法执行提及门控
• 来自授权发送者的控制命令会绕过提及门控

要处理某个群组中来自允许发送者的所有消息，请将该聊天的 requireMention 设置为 false：

{
  channels: {
    imessage: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123", "+15555550124"],
      groups: {
        "*": {},
        "123": { requireMention: false },
      },
    },
  },
}

将 123 替换为 imsg chats --limit 20 --json 中的数字聊天 ID。编辑已经提供该账号群组策略的映射：channels.imessage.groups，或者当它覆盖根映射时使用 channels.imessage.accounts.<account-id>.groups。这也适用于 accounts.default.groups；仅仅存在一个账号条目并不意味着需要它自己的 groups 映射。只有当最多配置了一个账号时，空的账号映射才会继承根映射。

要仅允许在由 OpenClaw 启动的原生回复线程中进行未提及的后续消息，请在该群组条目中将 requireMentionInBotThreads: false 与 requireMention: true 一起设置。精确的群组设置会覆盖 groups["*"].requireMentionInBotThreads。将其设置为 true 可在这些线程中要求提及，或省略它以保留正常的提及行为。发送者和群组限制仍然适用。

当提及模式被禁用时，显式的 requireMentionInBotThreads: true 仍会强制执行。配置可用的提及模式以在这些线程中提及机器人；否则，除了授权的控制命令外，它们将保持静默。

线程所有权来自原生线程根 GUID 和 OpenClaw 的按账号和会话范围的已发送消息缓存。该缓存最多保留 2,000 条消息，持续六小时，并可在该时间窗口内重启后保留。未知或被清除的根仍保持正常的提及要求。在别人的线程中回复机器人消息不会使该线程成为机器人所有。