vultr/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-08-02 10:21:34 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(buzz): shorten plugin readme (#114156)

Browse Source
This commit is contained in:
Patrick Erichsen
2026-07-26 14:21:36 -05:00
committed by GitHub
parent 96aa6be670
commit 898e10c0f4
1 changed files with 22 additions and 148 deletions
Download Patch File Download Diff File Expand all files Collapse all files

170
extensions/buzz/README.md
View File

@@ -1,74 +1,16 @@
# @openclaw/buzz
Official Buzz channel plugin for OpenClaw.
Official Buzz channel plugin for OpenClaw. It connects an OpenClaw agent to approved Buzz rooms for text conversations and threaded replies.
Bring an OpenClaw agent into Buzz so people can work with it from the same rooms
as the rest of their team. Conversations stay in the room and thread where they
started, while OpenClaw supplies the agent's model, workspace, skills, memory,
tools, and automation.
## Requirements
## What you can do
You need:
- Give support, engineering, or operations rooms their own specialized agents
- Let room members ask an agent to research, write, run approved tools, or use
team-specific skills and memory
- Send proactive updates from OpenClaw automations and operators into Buzz
- Keep one Gateway and bot identity while routing different rooms to different
agents, models, and workspaces
- Control who can activate an agent with mentions and sender allowlists
- Keep replies attached to the originating Buzz conversation
- A Buzz relay URL
- A Buzz owner or admin
- A room where the bot can receive the **Bot** role
## How Buzz maps to OpenClaw
Buzz identities are Nostr keypairs. OpenClaw owns a dedicated bot private key;
Buzz admins receive only its public key. A single OpenClaw Gateway and bot
identity can serve multiple approved Buzz rooms, and normal OpenClaw bindings can
route each room to a different agent, model, or workspace.
Each room is identified by a UUID. Incoming room messages enter the normal
OpenClaw conversation flow, while replies stay in the originating Buzz room and
preserve thread context.
The high-level message flow is:
```text
Buzz room <-> Buzz relay <-> Buzz plugin <-> routed OpenClaw agent
```
## What the plugin adds
- Buzz as an OpenClaw group-chat channel
- Guided bot identity and room setup
- Room discovery after a Buzz admin approves the bot
- Mention requirements and sender allowlists
- Connection recovery without replaying the same message twice
- Room-to-agent routing through standard OpenClaw bindings
### Agent tools
The plugin does not register a separate Buzz-only agent tool. Once configured,
Buzz is available through OpenClaw's built-in `message` tool for text sends and
threaded replies. Incoming Buzz messages enter the normal OpenClaw conversation
flow.
OpenClaw agents, automations, and operators can also send proactive text
messages to approved rooms through the same channel delivery path. Because Buzz
messages enter the normal agent flow, each room can be routed to an agent with
its own workspace, model, skills, memory, and tool policy.
## Before you start
You need a Buzz workspace relay URL, a Buzz owner or admin who can approve the
bot, and at least one room where the bot can receive the **Bot** role. Use a
`wss://` relay outside local development.
## Install
```bash
openclaw plugins install @openclaw/buzz
```
Restart the Gateway after installing or updating the plugin.
Use `wss://` outside local development.
## Set up
@@ -76,39 +18,9 @@ Restart the Gateway after installing or updating the plugin.
openclaw channels add --channel buzz
```
The guided flow asks for your Buzz relay URL and creates a dedicated bot
identity automatically when one is not already configured. Give the displayed
**public key only** to a Buzz admin, who must add the identity to each room with
the **Bot** role.
OpenClaw installs the plugin if needed, asks for the relay URL, and generates a dedicated bot identity.
After the Gateway connects, OpenClaw preserves an existing Buzz profile display
name. For a new profile it uses the explicit Buzz account name, then the
identity name of the single agent routed to the configured rooms, and finally
`OpenClaw`. A configured NIP-OA `authTag` is preserved in that profile so Buzz
can display its verified owner.
OpenClaw also registers the public identity in Buzz's agent directory while
preserving any existing directory profile and channel-add policy. Buzz can then
recognize the identity as an agent and assign the **Bot** role when it is added
to more rooms. Those rooms still require explicit OpenClaw configuration before
the Gateway accepts messages from them.
While the Gateway remains connected, OpenClaw also refreshes the bot's Buzz
presence so room members see it as online. Buzz clears that presence when the
last Gateway connection for the bot identity closes.
OpenClaw immediately attempts authenticated room discovery. If room access is
not ready, it waits for Buzz to confirm the Bot role and continues
automatically. If the bounded wait expires, setup offers authenticated
Retry/Back controls without disabling Buzz, exiting setup, or generating
another key.
One discovered room is selected automatically. With several rooms, setup asks
which rooms to use and which one is the default outbound target. Fresh setup
accepts normal messages from current room members without requiring a composer
mention, verifies the saved configuration, and does not post a test message.
For local Buzz development, `just dev` does not require separate relay
membership by default. Buzz desktop cannot reliably assign the Bot role to an
externally managed identity, so add the bot directly with the CLI:
Give the displayed **public key only** to a Buzz owner or admin:
```bash
buzz channels add-member \
@@ -117,71 +29,33 @@ buzz channels add-member \
--role bot
```
Run the command as an existing human owner or admin. Hosted or closed relays may
also require community membership before room membership can be granted.
Closed relays may also require the bot to be added as a relay member. Setup waits for approval, discovers accessible rooms, and saves the selected rooms and default target.
### Security notes
- Never give OpenClaw a human Buzz owner's private key.
- Share only the bot public key with Buzz owners and room admins.
- Generated bot keys follow OpenClaw's current plaintext config convention.
- Existing keys can use plaintext or an existing `env`, `file`, or `exec`
SecretRef.
- Fresh guided setup accepts normal messages from current members of the
selected rooms. Manual configuration can require mentions when the Buzz
client can address the bot, or restrict activation to specific member public
keys.
- OpenClaw keeps an in-memory copy of Buzz's relay-signed room roster and
refreshes it on membership changes; it does not query the relay for each
message or poll from the Gateway.
- Buzz messages are untrusted input to the routed agent. Match that agent's tool
policy and sandbox access to the room's trust level.
- Anyone who obtains the bot private key can impersonate it. Treat the key like
a password, use a SecretRef when appropriate, and never paste it into Buzz.
- Treat a hosted relay `authTag` as a delegated reusable secret. Keep it out of
logs, screenshots, chat, and source control; prefer a SecretRef and rotate or
revoke it when the bot identity or relay authorization changes.
- Key rotation requires the new public key to be approved for the relay and
rooms before the old identity is removed.
Restart the Gateway if it was already running.
## Verify
```bash
openclaw channels status --channel buzz --probe
openclaw channels status --probe
```
Then send a real room message:
Send a test message:
```bash
openclaw message send \
--channel buzz \
--target buzz:<ROOM_UUID> \
--target <ROOM_UUID> \
--message "Hello from OpenClaw"
```
For a full round trip, have an allowed Buzz user mention the bot and confirm
that OpenClaw replies in the room.
## Security and scope
## Roadmap, not supported today
- Never give OpenClaw a human owner's private key.
- The generated bot private key is stored in OpenClaw configuration; only its public key is displayed.
- Treat Buzz messages as untrusted agent input.
- Currently supported: text conversations in group rooms.
- Not yet supported: DMs, media, reactions, or creating rooms from OpenClaw.
The current plugin supports text conversations in group rooms. The following
areas are planned but are not shipped yet:
Full documentation: https://docs.openclaw.ai/channels/buzz
- Direct messages
- Media and files
- Native reactions
- Creating rooms from OpenClaw
- Automatic relay and room-role approval
- Guided bot identity rotation
## Docs
Full setup, configuration, access controls, and troubleshooting:
- https://docs.openclaw.ai/channels/buzz
## Package
- Plugin id: `buzz`
- Package: `@openclaw/buzz`
- Minimum OpenClaw host: `2026.7.2`
Package: `@openclaw/buzz` · Plugin ID: `buzz`