chore(sync): mirror docs from openclaw/openclaw@df069f7b02

.openclaw-sync/source.json

@@ -1,15 +1,15 @@
 {
   "repository": "openclaw/openclaw",
-  "sha": "cde99c3349e960b02fcb50a48119f9b3c02db4f2",
+  "sha": "df069f7b022247e8818cc8ef981deff6ed453966",
   "sources": {
     "openclaw": {
       "repository": "openclaw/openclaw",
-      "sha": "cde99c3349e960b02fcb50a48119f9b3c02db4f2"
+      "sha": "df069f7b022247e8818cc8ef981deff6ed453966"
     },
     "clawhub": {
       "repository": "openclaw/clawhub",
       "sha": "f14d70759dcc14b24890f5a50e1f9ce06f38eacd"
     }
   },
-  "syncedAt": "2026-05-08T02:44:53.590Z"
+  "syncedAt": "2026-05-08T03:10:32.397Z"
 }

docs/channels/imessage-from-bluebubbles.md

@@ -85,7 +85,12 @@ The bundled iMessage plugin runs **two** separate group allowlist gates back-to-
    - a `groups: { "*": { ... } }` wildcard entry (sets `allowAll = true`), or
    - an explicit per-`chat_id` entry under `groups`.
 
-If gate 1 passes but gate 2 fails, the message is dropped and the rejection logs **only at `verbose`/`debug` level** (`inbound-processing.ts:337`). At the default `info` log level every group message vanishes silently — DMs continue to work because they take a different code path.
+If gate 1 passes but gate 2 fails, the message is dropped. The plugin emits two `warn`-level signals so this is no longer silent at default log level:
+
+- A one-time startup `warn` per account when `groupPolicy: "allowlist"` is set but `channels.imessage.groups` is empty (no `"*"` wildcard, no per-`chat_id` entries) — fired before any messages land.
+- A one-time per-`chat_id` `warn` the first time a specific group is dropped at runtime, naming the chat_id and the exact key to add to `groups` to allow it.
+
+DMs continue to work because they take a different code path.
 
 This is the most common BlueBubbles → bundled-iMessage migration failure mode: operators copy `groupAllowFrom` and `groupPolicy` but skip the `groups` block, because BlueBubbles' `groups: { "*": { "requireMention": true } }` looks like an unrelated mention setting. It's actually load-bearing for the registry gate.
 
@@ -107,15 +112,7 @@ The minimum config to keep group messages flowing after `groupPolicy: "allowlist
 
 `requireMention: true` under `*` is harmless when no mention patterns are configured: the runtime sets `canDetectMention = false` and short-circuits the mention drop at `inbound-processing.ts:512`. With mention patterns configured (`agents.list[].groupChat.mentionPatterns`), it works as expected.
 
-To debug a suspected silent drop, raise log level temporarily:
-
-```bash
-OPENCLAW_LOG_LEVEL=debug openclaw gateway
-```
-
-Then look for `imessage: skipping group message (<chat_id>) not in allowlist`. If you see that line, gate 2 is dropping — add the `groups` block.
-
-Tracker for raising the drop's log severity so this is no longer silent at `info`: [openclaw#78749](https://github.com/openclaw/openclaw/issues/78749).
+If the gateway logs `imessage: dropping group message from chat_id=<id>` or the startup line `imessage: groupPolicy="allowlist" but channels.imessage.groups is empty`, gate 2 is dropping — add the `groups` block.
 
 ## Step-by-step
 
@@ -174,7 +171,7 @@ Tracker for raising the drop's log severity so this is no longer silent at `info
 
 4. **Verify DMs.** Send the agent a direct message; confirm the reply lands.
 
-5. **Verify groups separately.** DMs and groups take different code paths — DM success does not prove groups are routing. Send the agent a message in a paired group chat and confirm the reply lands. If the group goes silent (no agent reply, no error), restart the gateway with `OPENCLAW_LOG_LEVEL=debug openclaw gateway` and look for `imessage: skipping group message (...) not in allowlist`. If that line appears, your `groups` block is missing or empty — see "Group registry footgun" above.
+5. **Verify groups separately.** DMs and groups take different code paths — DM success does not prove groups are routing. Send the agent a message in a paired group chat and confirm the reply lands. If the group goes silent (no agent reply, no error), check the gateway log for `imessage: dropping group message from chat_id=<id>` or the startup `imessage: groupPolicy="allowlist" but channels.imessage.groups is empty` line — both fire at the default log level. If either appears, your `groups` block is missing or empty — see "Group registry footgun" above.
 
 6. **Verify the action surface** — from a paired DM, ask the agent to react, edit, unsend, reply, send a photo, and (in a group) rename the group / add or remove a participant. Each action should land natively in Messages.app. If any throws "iMessage `<action>` requires the imsg private API bridge", run `imsg launch` again and refresh `channels status --probe`.
 

docs/channels/imessage.md

@@ -239,7 +239,12 @@ If SIP-disabled isn't acceptable for your threat model:
     1. **Sender / chat-target allowlist** (`channels.imessage.groupAllowFrom`) — handle, `chat_guid`, `chat_identifier`, or `chat_id`.
     2. **Group registry** (`channels.imessage.groups`) — with `groupPolicy: "allowlist"`, this gate requires either a `groups: { "*": { ... } }` wildcard entry (sets `allowAll = true`), or an explicit per-`chat_id` entry under `groups`.
 
-    If gate 2 has nothing in it, every group message is dropped — and the rejection logs only at `verbose`/`debug` level, so the drops are silent at the default `info` log level. DMs continue to work because they take a different code path.
+    If gate 2 has nothing in it, every group message is dropped. The plugin emits two `warn`-level signals at the default log level:
+
+    - one-time per account at startup: `imessage: groupPolicy="allowlist" but channels.imessage.groups is empty for account "<id>"`
+    - one-time per `chat_id` at runtime: `imessage: dropping group message from chat_id=<id> ...`
+
+    DMs continue to work because they take a different code path.
 
     Minimum config to keep groups flowing under `groupPolicy: "allowlist"`:
 
@@ -255,7 +260,7 @@ If SIP-disabled isn't acceptable for your threat model:
     }
     ```
 
-    To debug a suspected silent drop, run `OPENCLAW_LOG_LEVEL=debug openclaw gateway` and look for `imessage: skipping group message (<chat_id>) not in allowlist`. If that line appears, gate 2 is dropping — add the `groups` block.
+    If those `warn` lines appear in the gateway log, gate 2 is dropping — add the `groups` block.
     </Warning>
 
     Mention gating for groups: