npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@nhtio/rocket-chat-openclaw-integration

v1.20260404.11

Published

An OpenClaw Plugin which allows RocketChat to be used as a communications channel

Vulnerabilities

Powered byPowered by Snyk
  • 0High
  • 0Medium
  • 0Low

Links

Maintainers

jakgurujakguru

Keywords

Readme

Rocket.Chat OpenClaw Integration (Spec)

This repository specifies and implements an integration between:

  • Rocket.Chat (self-hosted, via Realtime API WebSocket/DDP)
  • OpenClaw (via a first-class "channel" plugin integration, comparable to Slack/Telegram/Discord)

Primary docs referenced by this spec:

Goals

  • Provide a Rocket.Chat "channel" integration for OpenClaw that matches existing channel behavior (send/receive, threading/replies where applicable, identity mapping, attachments, reactions, etc.).
  • Implement as an OpenClaw channel plugin that connects directly to Rocket.Chat.
  • Keep OpenClaw-side changes minimal; introduce additional OpenClaw plugin capabilities only if required to achieve parity with existing channel integrations.

Non-goals (initial)

  • Re-implement Rocket.Chat's full permission/admin surface; only what is required for install, auth, and message/event delivery.
  • Multi-workspace support (assume one Rocket.Chat workspace per OpenClaw gateway for v1).
  • Backfilling historical messages (focus on real-time sync first).

High-level Architecture

We expect a single OpenClaw channel plugin that connects directly to Rocket.Chat.

  • Transport: Rocket.Chat Realtime API (WebSocket/DDP) (deprecated per Rocket.Chat docs; accept risk for v1)
  • Target Rocket.Chat version (v1): 8.2.0 (self-hosted; upgrades are controlled)
  • Bot identity: one Rocket.Chat user per OpenClaw agent, each with the bot role (admin-provisioned)
  • Auth: Personal Access Token (PAT) per bot user (manual provisioning)

A Rocket.Chat Apps-Engine app is explicitly out of scope for v1 (keeps deployment and ops simpler). If Rocket.Chat later removes or breaks Realtime API subscription streams we rely on, we will revisit an Apps-Engine-based design.

OpenClaw Channel Plugin Expectations (Draft)

Per the OpenClaw channel plugin documentation, OpenClaw core owns the shared message tool and core prompt wiring. The channel plugin typically owns:

  • Config (account resolution + setup)
  • Security (DM policy + allowlists)
  • Pairing (DM approval flow)
  • Session grammar (mapping provider conversation ids to base chats + threads)
  • Outbound delivery (send text/media/polls)
  • Threading semantics (reply behavior)

Canonical session-id parsing hook:

  • messaging.resolveSessionConversation(...) (and optionally a bootstrap-safe session-key-api.ts export for bundled plugins)

Reference: https://docs.openclaw.ai/plugins/sdk-channel-plugins#how-channel-plugins-work

Interfaces & Data Flow (Draft)

  • Inbound (Rocket.Chat -> OpenClaw)
    • OpenClaw channel plugin maintains a Realtime API WebSocket connection per configured bot account.
    • The plugin subscribes to message streams for allowlisted rooms and forwards eligible events into OpenClaw sessions.
  • Outbound (OpenClaw -> Rocket.Chat)
    • OpenClaw issues channel actions (send text/media/reactions/etc) which the channel plugin executes via Rocket.Chat APIs.

Authentication & Trust (v1)

Trust boundary is Rocket.Chat <-> OpenClaw. There is no intermediate Apps-Engine app.

  • Bot auth mechanism: Rocket.Chat Personal Access Tokens (PATs) + userId (manual admin provisioning).
  • Transport security:
    • The plugin MUST use wss:// for Realtime API connections and https:// for any REST calls.
    • TLS certificate validation MUST be enabled (no insecure / skip-verify) unless an explicit dangerouslyAllowInsecure: true-style config flag is set for local dev.
  • Secret storage: PATs are stored only in OpenClaw config (not in repo) and treated as credentials equivalent to a password.
  • Rotation / revocation: rotating or deleting a PAT in Rocket.Chat must revoke OpenClaw access for that bot. Enforcement requirements for long-lived connections:
    • On any auth error/unauthorized response on the WebSocket (or any REST call), the plugin MUST immediately close the WebSocket and stop processing events for that account.
    • The plugin MUST periodically re-validate credentials (REST check) on a fixed cadence to bound worst-case revocation delay. Default target: <= 5 minutes.
  • Blast radius: one bot account per OpenClaw agent id; compromising one PAT should not compromise other agents.
  • Session-level authorization: inbound events must still pass OpenClaw allowlist + policy checks (DM policy, group policy, mention gating, per-room/per-user allowlists) before reaching the model.

Message Semantics (Draft)

For v1, feature scope should match the Slack channel integration behavior and capabilities as documented here:

At minimum, Slack documents inbound event subscriptions for:

  • message events across channel types (message.channels, message.groups, message.im, message.mpim)
  • reactions (reaction_added, reaction_removed)

We should target comparable Rocket.Chat capabilities over the Realtime API.

Chat type semantics (Slack-aligned):

  • DMs: 1:1 conversations (no mention requirement by default; gated by dmPolicy)
  • Group chats: any multi-user room (public channels + private groups)
    • mention-gated by default
    • gated by group policy + allowlists (Slack-style defaults)

Draft mapping:

  • Identity mapping: Rocket.Chat users <-> OpenClaw authors
  • Rooms/channels: Rocket.Chat rooms <-> OpenClaw channel targets
  • Threads/replies: follow Slack-style reply controls (reply-to mode + thread session keys)
  • Attachments: deferred until explicitly specified (v1 supports plain text only)
  • Edits/deletes: parity with Slack channel behavior
  • Reactions: v1 supports reaction add/remove (Slack parity)

Deliverables

  • An OpenClaw channel plugin for Rocket.Chat.
  • Minimal installation/configuration steps.

Provisioning assumptions (v1):

  • One Rocket.Chat bot user per OpenClaw agent id.
  • Admin provides per-bot credentials/config into OpenClaw:
    • serverUrl
    • userId
    • username (for mention gating)
    • pat (personal access token)
  • Room allowlists accept room ids and/or room names; names are resolved to ids at startup when possible (Slack-style).

Compatibility Targets (Slack-parity)

Slack parity is the reference for how features should behave when implemented. For v1, this spec is explicit about what is in-scope vs deferred.

V1 required support (MUST):

  • Inbound: new messages (DMs + group chats), mention-gating in group chats
  • Outbound: send text, reply in thread when inbound is threaded
  • Reactions: reaction add/remove
  • Commands: minimal prefix commands in-message (see below)

Deferred until explicitly specified (NOT v1):

  • Edits
  • Deletes
  • Attachments (beyond plain text)

When we add any deferred item, it must match Slack semantics unless Rocket.Chat cannot represent it.

Commands (v1)

We intentionally do not use Rocket.Chat slash commands.

  • Syntax: prefix ! at the start of the message (after trim)
    • Examples: !status, !model g5.2, !stop
  • Parsing precedence:
    • If the trimmed message starts with !, treat it as a command; do not send the command text to the model.
    • Otherwise treat as normal chat content.

Authorization model:

  • Baseline gating (all commands): the sender must already be authorized for this room/DM by the normal channel policy (room allowlist + group policy + user allowlists / dmPolicy).
  • Risky commands are more restricted:
    • !status: allowed for any authorized sender.
    • !model and !stop: allowed only for command operators.

Command operators (v1):

  • Explicit allowlist per Rocket.Chat account (Slack-style).
  • If commandAllowFrom is unset/empty, default is deny for !model + !stop in group chats.

Reply target:

  • Reply publicly in the same room/thread (no DM fallback).

Semantics:

Milestones (Draft)

  • Event ingestion: new message events from allowlisted Rocket.Chat rooms arrive in OpenClaw
  • Routing: inbound messages route to the OpenClaw agent represented by the bot account that was mentioned/DM'd
  • Outbound send: OpenClaw can post messages into Rocket.Chat (thread replies supported)
  • Parity pass (post-v1): edits, deletes, attachments
  • Operational hardening: retries, idempotency, observability

Open Questions

These block finalizing the interface and auth model:

  1. Rocket.Chat Realtime API scope: which subscription streams cover all Slack-parity features (new messages, reactions, edits, deletes, pins/renames/membership if applicable)?
  2. Rocket.Chat thread model: what is the exact mapping between Rocket.Chat thread/reply metadata and OpenClaw's reply_to + optional :thread: session keys (Slack-style semantics)? Default: reply in thread when inbound is threaded.
  3. Rocket.Chat mention semantics: confirm how mention metadata is exposed on Realtime API payloads (preferred) vs requiring text scanning for @<username>.
  4. Slack-default access control mapping: mirror Slack's dmPolicy, groupPolicy, allowlists, and mention gating defaults in Rocket.Chat.
  5. Realtime API deprecation: Rocket.Chat docs mark DDP methods as deprecated/unreliable and recommend REST for new development; v1 accepts this risk because Rocket.Chat upgrades are controlled (target version 8.2.0).

Development Notes

  • Keep top-level spec in this README.md.
  • If/when the spec becomes too large, create a specs/ directory with focused documents (auth, message model, retry/idempotency, etc.).