OpenClaw Buzz plugin

@maxjb/openclaw-buzz is a standalone external plugin that connects OpenClaw agents to Buzz rooms. It preserves the host identifiers buzz (plugin ID and channel ID), so an explicit installation takes precedence over OpenClaw's bundled Buzz plugin when both are present.

Requirements and compatibility

• OpenClaw 2026.7.1-2 compatibility line (>=2026.7.1-2 <2026.7.2)
• A Buzz relay URL and a bot/agent Nostr private key

The package depends on nostr-tools and zod. OpenClaw is a peer dependency at runtime and a development dependency for typechecking and tests. The plugin ships TypeScript source because OpenClaw loads external plugin entry points directly.

Buzz Desktop provider enrollment

The package installs the Desktop provider executable buzz-backend-openclaw. It is a one-process stdin/stdout JSON executable: send {"op":"info"} and then an enrollment request matching /home/node/workspaces/block-buzz/docs/openclaw-enrollment.md, with agent.relay_url, agent.private_key_nsec, agent.auth_tag, provider_config.host, and enrollment: {"version":1,"mode":"one-time"}. The provider uses SSH to run openclaw buzz enroll --stdin on the configured host. Set provider_config.host to an SSH destination such as openclaw@agent-host, and provide the comma-separated room UUIDs in provider_config.rooms (an optional provider_config.port is also supported).

The provider returns { "ok": true, "agent_id": "..." } after importing the account and binding it to the stable agent identity derived from the Nostr public key. Failures return { "ok": false, "error": "..." } with exit code zero; secrets are never echoed. Desktop stores only the returned ID and non-secret provider config. OpenClaw connects directly to the Buzz relay; Desktop is not a Gateway, relay, proxy, or message router. SSH is only used for the one-time provisioning handoff; after enrollment, OpenClaw connects outbound directly to the Buzz relay, so the community server does not need Tailscale.

Install and override the bundled plugin

openclaw plugins install @maxjb/openclaw-buzz

The manifest intentionally keeps id: "buzz" and channels: ["buzz"]. Explicit installation therefore selects this package as the configured Buzz implementation even when the host also contains a bundled copy. Restart the Gateway after installation or replacement.

Configure Buzz

Interactive setup supports the default account and any number of named accounts. Run the fully interactive picker when adding or reconfiguring accounts:

openclaw channels add
openclaw channels status --probe

Select Buzz, then select an existing account or Add a new account. Rerunning setup for an existing account preserves its bot identity and preselects its current rooms. The room picker can add or remove rooms; setup then asks, for each selected room, whether responses are enabled and whether an @mention is required. These settings remain independently editable for every account and room through the same setup flow.

Setup accepts an optional owner-attested Buzz authTag for an existing managed agent. This is the NIP-OA identity attestation used by Buzz and grants community relay access via NIP-AA. Store the tag directly or through an OpenClaw SecretRef; never enter or store an owner private key. When an authTag is configured, do not add the agent public key to relay_members and do not run buzz-admin add-member.

Without an authTag, setup can generate a standalone bot identity. In that fallback path only, an authorized human must grant relay membership once:

buzz-admin add-member --pubkey <BOT_PUBLIC_KEY> --role member

Hosted communities should use their equivalent administrator action.

For every selected private room, a room admin must add the agent as a bot in the Buzz UI. Buzz's channel_members role bot is the automated-agent designation and is room access, not a separate agent role. After room access is visible, interactive setup discovers eligible rooms and lets you explicitly select one or many. Community membership only permits relay access, while the room bot designation makes a room discoverable to that bot. Neither grant subscribes OpenClaw to a room: only rooms retained under the account's groups configuration are accepted, and groups.<room>.enabled controls whether that configured room responds. Repeat only the room-role step in the Buzz UI when adding the same agent to more rooms. BUZZ_PRIVATE_KEY configures only the default account and must contain the bot's private key, never a human owner or administrator key. BUZZ_AUTH_TAG may hold the default account's owner-attested tag. Named accounts store their own identity and optional tag.

For multiple named accounts in one room, setup writes separate credentials under channels.buzz.accounts; bind each account to its agent:

{
  "channels": {
    "buzz": {
      "accounts": {
        "research": {
          "name": "Research",
          "relayUrl": "wss://relay.example",
          "privateKey": "<research-bot-private-key>",
          "groups": {"<room-uuid>": {"enabled": true, "requireMention": true}}
        },
        "ops": {
          "name": "Operations",
          "relayUrl": "wss://relay.example",
          "privateKey": "<ops-bot-private-key>",
          "groups": {"<room-uuid>": {"enabled": true, "requireMention": true}}
        }
      }
    }
  },
  "bindings": [
    {"agentId": "research-agent", "match": {"channel": "buzz", "accountId": "research"}},
    {"agentId": "ops-agent", "match": {"channel": "buzz", "accountId": "ops"}}
  ]
}

requireMention is intentionally not forced. Set it to false where agents must contact each other without an explicit mention, or to true where a bot should respond only when addressed. Setup preserves each room's existing value and makes it explicit on every rerun. Give each bot public key the Buzz Bot role in each selected room. Rooms use UUIDs as stable targets. DMs, media, reactions, and room creation are not currently supported.

Development

The plugin imports openclaw/plugin-sdk/* from the host. Its development toolchain pins OpenClaw 2026.7.1-2, so local typechecking and tests exercise the exact compatibility target. OpenClaw remains an optional peer at runtime.

The package-level check validates the distributable contents without contacting a relay:

npm install --include=dev
npm run check

Live-relay QA requires a configured OpenClaw environment and credentials.

Release process

This repository is independent of the OpenClaw core checkout. For a release, update the package version and compatibility metadata, run npm run check, review npm pack --dry-run, commit the release change, tag it, and publish the GitHub release. The GitHub release tarball or git tag can then be installed by OpenClaw without rebuilding the OpenClaw core image.