Access Groups & Broadcast Groups

Most permission messes do not start with malice. They start with convenience. One quick allowlist becomes three. Three become ten. A month later nobody is sure who can see what, who can trigger what, or why an internal update landed in the wrong room.

That is the gap access groups are meant to close. In OpenClaw, they give you a reusable way to describe who belongs inside a permission boundary instead of hardcoding the same decision in twenty places.

Broadcast groups solve a different problem. They are not about who gets access in the first place. They are about controlled fan-out after a message or event is already allowed. Think permission first, distribution second. Mixing those two jobs is how setups become sloppy.

What access groups actually solve

The official docs describe access groups as reusable membership lists for access control, referenced from allowlists with accessGroup:<name>. That sounds dry, but the practical win is huge: you stop repeating the same users, roles, or channel participants everywhere you need a boundary.

If you have ever maintained five separate allowlists that were supposed to mean the same thing, you already know the pain. One person joins the team. Another leaves. Somebody forgets one list. Suddenly your policy exists in theory, but not in reality.

Access groups give you one named source of truth. A room, route, or feature can point at the group instead of re-declaring everybody each time. Just keep one thing straight: an access group does not grant access on its own. It matters only when an allowlist field references it.

• private operator rooms can share one trusted group
• sensitive admin actions can reuse the same approved membership
• channel surfaces can stay aligned when the team changes
• auditing gets easier because the intent is visible

It is the same reason good teams use role-based access instead of pasting names into every system. Reuse is not just cleaner. It is safer.

Broadcast groups solve distribution, not trust

This is where people get tripped up. A broadcast group is not a magic permission shortcut. It is a delivery map.

The current OpenClaw broadcast docs describe a per-source destination list. In plain English, that means one eligible source peer can fan out to a defined set of destination peers. The design is intentionally explicit because message amplification gets dangerous fast.

There is also an important scope limit in the current docs: broadcast groups are marked experimental and currently apply to the WhatsApp web channel. So this is not a universal answer for every channel surface in OpenClaw.

Think of a museum. Access groups decide who is allowed past the staff door. Broadcast groups decide which internal rooms should hear the radio call once somebody inside reports an issue. Those are related questions, but they are not the same question.

That distinction matters because a clean setup can say:

• only trusted operators may trigger a workflow
• only certain rooms may receive the resulting updates
• not every trusted operator room needs every broadcast

Once you see access and fan-out as separate layers, the architecture gets much easier to reason about.

Why accidental oversharing usually happens

Oversharing rarely needs a dramatic bug. It usually comes from broad groups, vague naming, or a broadcast list that grew by habit instead of design.

The classic failure pattern looks like this:

1. a team creates one broad trusted group
2. that group gets reused in places with different sensitivity
3. a broadcast map points one source at too many destinations
4. an internal or private detail lands somewhere it should not

It is a little like using one email list for customers, contractors, executives, and incident responders because creating separate lists felt annoying. The setup feels efficient right up until the wrong update goes to the wrong audience.

What the local source verification reinforces

Current local OpenClaw build artifacts reinforce this split between permission and distribution. The runtime schema exposes broadcast as an intentional config block with documented destination lists and delivery order. Local channel runtime code also exposes group access controls such as groupAllowFrom and group policy handling. In other words, the product itself treats room access and message fan-out as separate knobs. Your architecture should too.

Design pattern 1: one trust boundary per job

Give groups names that describe why the members belong together, not just where they happen to work.

• ops-core for people who can receive deployment and incident updates
• support-leads for people allowed to trigger customer-facing workflows
• finance-private for rooms or members that can see sensitive numbers

This sounds boring. Good. Boring permission design is usually the healthy kind.

Avoid names like main-team or trusted if the boundary is fuzzy. Fuzzy names create fuzzy decisions later.

Design pattern 2: keep broadcast destinations painfully intentional

The broadcast docs lean toward explicit per-source mapping for a reason. Fan-out should feel deliberate, almost a little annoying to widen. That friction is useful.

If one source room broadcasts to three destinations, somebody should be able to explain all three without hand-waving. If they cannot, the list is too broad.

{
  accessGroups: {
    opsCore: ["telegram:-100111:7", "slack:team-ops"],
    supportLeads: ["discord:guild:lead-room"]
  },
  broadcast: {
    "telegram:-100111:9": [
      "telegram:-100111:7",
      "slack:C045OPS"
    ]
  }
}

The syntax is not the lesson here. The lesson is that the source and every destination are named on purpose. Nothing about this is accidental.

Design pattern 3: separate operator visibility from customer visibility

A useful real-world pattern is to let one internal room trigger or monitor work while a different public-facing room receives a shorter, safer version of the outcome. Access groups help define who can touch the workflow. Broadcast groups help define where status should travel.

This keeps one important truth intact: the people allowed to operate a system are not automatically the same audience who should see every raw detail produced by that system.

Design pattern 4: review groups whenever routing changes

Channel routing and group design are close cousins. If you change routing, add a new room type, or give an agent a new operational surface, revisit the groups. Otherwise you get neat routing on top of stale trust boundaries.

A strong habit is to review three things together:

• who can trigger work
• who can see results
• which rooms receive fan-out automatically

That small audit catches a surprising amount of nonsense before it becomes public nonsense.

When broadcast groups help, and when they do not

Broadcast groups help when the same source message truly needs controlled delivery to several destinations. Good examples include:

• alerts that should hit both an operator topic and a backup room
• one source thread feeding a tightly scoped monitoring channel
• workflows where the input arrives in one room but review happens elsewhere

They do not help when you simply need normal replies in the same room, or when you are using fan-out to compensate for unclear routing. That is not distribution. That is architecture debt wearing a fake mustache.

The practical rule of thumb

Use access groups to define trust once and reuse it. Use broadcast groups only when one approved source should intentionally spread information to a few other places.

If you remember nothing else, remember this: permission boundaries should be small and named clearly. Broadcast lists should be short and defensible. That is how OpenClaw stays useful without becoming a gossip engine with webhooks.