访问控制
谁被准入,消息如何路由到会话,以及哪些聊天可以写入配置。
访问控制与路由¶
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" 下,群聊路由会连续运行 两 道闸门:
- 发送者允许列表(
channels.imessage.groupAllowFrom)—— handle、accessGroup:<name>、chat_guid、chat_identifier或chat_id。空的有效列表(没有groupAllowFrom也没有allowFrom回退)会阻止所有群聊发送者。 - 群聊注册表(
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)。
禁用:
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw