跳转至

访问控制

谁被准入,消息如何路由到会话,以及哪些聊天可以写入配置。

访问控制与路由

channels.imessage.dmPolicy 控制私信:

  • pairing(默认)
  • allowlist(需要至少一个 allowFrom 条目)
  • open(要求 allowFrom 包含 "*")
  • disabled

允许列表字段:channels.imessage.allowFrom。

允许列表条目必须标识发送者:handles 或静态发送者访问组(accessGroup:<name>)。对于 chat_id:*、chat_guid:* 或 chat_identifier:* 这类聊天目标,使用 channels.imessage.groupAllowFrom;对于数字 chat_id 注册表键,使用 channels.imessage.groups。

`channels.imessage.groupPolicy` 控制群聊处理:

- `allowlist`(默认)
- `open`
- `disabled`

群聊发送者允许列表:`channels.imessage.groupAllowFrom`。

`groupAllowFrom` 条目也可以引用静态发送者访问组(`accessGroup:<name>`)。

运行时回退:如果未设置 `groupAllowFrom`,iMessage 群聊发送者检查会使用 `allowFrom`;当私信和群聊准入策略需要不同时,请设置 `groupAllowFrom`。显式的空值 `groupAllowFrom: []` 不会回退——在 `allowlist` 策略下它会阻止所有群聊发送者。
运行时注意:如果 `channels.imessage` 完全缺失,运行时会回退到 `groupPolicy="allowlist"` 并记录警告(即使设置了 `channels.defaults.groupPolicy` 也是如此)。

Warning

在 groupPolicy: "allowlist" 下,群聊路由会连续运行 两 道闸门:

  1. 发送者允许列表(channels.imessage.groupAllowFrom)—— handle、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> ... —— 修复方法是在 channels.imessage.groups 下添加该 chat_id(或 "*")。

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

在 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 推导模式
  • 群聊默认要求提及,即使没有显式配置任何模式;因此,允许列表中的发送者消息也可能会被跳过,除非其中包含代理的名称或 emoji
  • 在所选代理或全局级别显式设置 mentionPatterns: [] 会抑制从身份推导出的模式;当没有可用模式时,iMessage 无法强制执行提及门控
  • 来自授权发送者的控制命令绕过提及门控

如果要在某个群聊中处理来自已允许发送者的每条消息,请将该聊天的 requireMention 设为 false:

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

用 imsg chats --limit 20 --json 返回的数字聊天 ID 替换 123。编辑已经为该账户提供群聊策略的映射: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 条消息,持续六小时,并在该时间窗口内重启后依然存活。未知或被驱逐的根线程保持正常的提及要求。在别人的线程中回复机器人消息不会使该线程归机器人所有。

保留现有的通配符以及每个群组的所有设置,仅修改目标聊天的 requireMention。账户映射会替换整个继承的映射,因此如果你有意创建账户特定的覆盖,请先复制完整的继承映射,包括所有通配符和每个群组的策略。如果之前没有应用任何映射,"*": {} 会保留对其他群组的准入,同时保持它们默认的提及要求。保持受限映射的受限状态。groupAllowFrom 仍然控制发送者访问。

    一条未提及而被跳过的消息会在默认日志级别产生警告,其中包含聊天 ID 以及 `requireMention: false` 修复建议。同一聊天的重复警告会被一个有界的内存缓存抑制;重启通道或驱逐缓存条目后,警告可以再次出现。

    每个群组的 `systemPrompt`:

    `channels.imessage.groups.*` 下的每个条目都接受一个可选的 `systemPrompt` 字符串,它会在处理该群组中消息的每一轮中注入到代理的系统提示中。解析方式与 `channels.whatsapp.groups` 相同:

    1. **群组特定系统提示**(`groups["<chat_id>"].systemPrompt`):当映射中存在特定群组条目**并且**其 `systemPrompt` 键已定义时使用。如果 `systemPrompt` 是空字符串(`""`),则通配符被抑制,并且不会向该群组应用任何系统提示。
    2. **群组通配符系统提示**(`groups["*"].systemPrompt`):当特定群组条目完全不存在于映射中,或者它存在但未定义 `systemPrompt` 键时使用。

    ```json5
    {
      channels: {
        imessage: {
          groupPolicy: "allowlist",
          groupAllowFrom: ["+15555550123"],
          groups: {
            "*": { systemPrompt: "Use British spelling." },
            "8421": {
              requireMention: true,
              systemPrompt: "This is the on-call rotation chat. Keep replies under 3 sentences.",
            },
            "9907": {
              // explicit suppression: the wildcard "Use British spelling." does not apply here
              systemPrompt: "",
            },
          },
        },
      },
    }
    ```

    每个群组的提示仅适用于群组消息——直接消息不受影响。
  • 直接消息使用直接路由;群组使用群组路由。
  • 在默认 session.dmScope=main 下,iMessage 直接消息会合并到代理主会话中。
  • 群组会话是隔离的(agent:<agentId>:imessage:group:<chat_id>)。
  • 回复会使用来源通道/目标元数据路由回 iMessage。

类似群组的线程行为:

一些多参与者 iMessage 线程可能以 is_group=false 到达。 如果该 chat_id 在 channels.imessage.groups 下被显式配置,OpenClaw 会将其视为群组流量(群组门控 + 群组会话隔离)。

ACP 会话绑定

iMessage 聊天可以绑定到 ACP 会话。

快速操作员流程:

  • 在直接消息或允许的群组聊天中运行 /acp spawn codex --bind here。
  • 该同一 iMessage 对话中的后续消息会路由到已生成的 ACP 会话。
  • /new 和 /reset 会就地重置同一个已绑定的 ACP 会话。
  • /acp close 关闭 ACP 会话并移除绑定。

已配置的持久绑定使用顶层 bindings[] 条目,其中 type: "acp" 且 match.channel: "imessage"。

match.peer.id 可以使用:

  • 规范化直接消息句柄,例如 +15555550123 或 user@example.com
  • chat_id:<id>(推荐用于稳定的群组绑定)
  • chat_guid:<guid>
  • chat_identifier:<identifier>

示例:

{
  agents: {
    entries: {
      codex: {
        runtime: {
          type: "acp",
          acp: { agent: "codex", backend: "acpx", mode: "persistent" },
        },
      },
    },
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "imessage",
        accountId: "default",
        peer: { kind: "group", id: "chat_id:123" },
      },
      acp: { label: "codex-group" },
    },
  ],
}

有关共享的 ACP 绑定行为,请参阅 ACP 代理。

配置写入

iMessage 默认允许通道发起的配置写入(当 commands.config: true 时,用于 /config set|unset)。

禁用:

{
  channels: {
    imessage: {
      configWrites: false,
    },
  },
}

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw