rocketchat-openclaw

Open-source Rocket.Chat channel plugin for OpenClaw.

Drop-in replacement for @cloudrise/openclaw-channel-rocketchat with 29 bug fixes, proper file uploads, and a bunch of new features. Production-tested with 92+ actions and full RC API coverage.

Install

# From git
npm install -g git+https://gitlab.com/doctorclaw/rocketchat-openclaw.git

# From npm
npm install -g rocketchat-openclaw

Verify you have the right package

Several similarly named packages exist on npm from other authors (openclaw-rocketchat, @alexwoo-awso/openclaw-rocketchat, @cloudrise/openclaw-channel-rocketchat). This package is maintained by iamdoctorclaw with source at gitlab.com/doctorclaw/rocketchat-openclaw.

npm view rocketchat-openclaw maintainers repository.url
# maintainers: [ 'iamdoctorclaw <[email protected]>' ]
# repository.url: 'git+https://gitlab.com/doctorclaw/rocketchat-openclaw.git'

Configure

Add to your openclaw.json:

{
  "plugins": {
    "load": {
      "paths": ["rocketchat-openclaw"]
    },
    "entries": {
      "rocketchat": { "enabled": true }
    }
  },
  "channels": {
    "rocketchat": {
      "baseUrl": "https://your-rc-instance.com",
      "userId": "your-bot-user-id",
      "authToken": "your-bot-auth-token",
      // Optional
      "replyMode": "auto",        // "thread" | "channel" | "auto"
      "autoThreadChars": 280,     // auto-thread responses longer than this
      "ackReaction": "eyes",      // react to incoming messages (or false to disable)
      "markAsRead": true,         // mark rooms as read on message receipt
      "allowFrom": ["username1", "username2"],
      "rooms": {
        "ROOM_ID": {
          "requireMention": false,
          "replyMode": "thread",
          "autoThreadChars": 500,
          "ackReaction": { "emoji": "eyes", "on": "mention" }
        }
      }
    }
  }
}

Multi-Account

{
  "channels": {
    "rocketchat": {
      "accounts": {
        "main": {
          "baseUrl": "https://rc1.example.com",
          "userId": "...",
          "authToken": "..."
        },
        "secondary": {
          "baseUrl": "https://rc2.example.com",
          "userId": "...",
          "authToken": "..."
        }
      }
    }
  }
}

Environment Variables

For the default account, you can use environment variables instead of config:

• ROCKETCHAT_URL — base URL
• ROCKETCHAT_USER_ID — bot user ID
• ROCKETCHAT_AUTH_TOKEN — bot auth token

Features

Threading

• Auto-threading — short responses stay in channel, long responses auto-thread
• autoThreadChars — configurable threshold (default 280 chars or 3+ lines)
• !thread / !channel — per-message override prefixes
• replyToModeByChatType — different reply linking for DMs vs groups vs threads

Message Actions (92+)

Full set of actions available via OpenClaw's message tool:

| Action | Description | |--------|-------------| | send | Send a message | | read | Read message history (supports threadId to read thread replies) | | search | Search messages in a room | | edit | Edit a message | | delete | Delete a message | | pin / unpin / list-pins | Pin management | | react / reactions | Add/remove reactions, list reactions | | channel-info / channel-list | Room information | | channel-create / channel-edit / channel-delete | Room CRUD | | member-info | User information | | thread-list / thread-reply | Thread management (list threads in room, reply to threads) | | emoji-list / emoji-upload | Custom emoji | | set-presence / get-presence | User status | | invite / kick | Room membership | | role-add / role-remove | Role management | | send-rich | Rich messages with attachments, colors, fields | | star / unstar / list-starred | Message starring | | discussion-create / discussion-list | Discussions | | list-commands / run-command | Slash commands | | read-receipts | Message read receipts | | send-no-preview | Send without URL previews | | mark-read | Mark room as read | | voice-status | Online users | | team-* | Full Teams support (create, delete, members, rooms, update, leave) | | channel-archive / channel-unarchive | Archive management | | channel-set-* | Set read-only, announcement, type, join code | | add/remove-moderator / add/remove-owner / add/remove-leader | Role management | | set-avatar | Set user avatar | | room-notification / room-favorite | Room preferences | | ignore-user / report-message | Moderation | | rooms-admin / autocomplete-rooms | Admin queries | | server-statistics | Server stats | | integration-* | Webhook integrations (create, list, remove, history) | | custom-status-* | Custom status CRUD | | custom-sounds-list | Custom sounds | | assets-list / asset-set / asset-unset | Server assets | | banner-* | Banner management | | video-conference-* | Video conferencing | | sticker-search | Sticker search | | follow-message / unfollow-message | Message following | | get-mentioned / get-deleted | Message queries | | channel-members / channel-online | Member queries |

All room operations (edit, delete, invite, kick) auto-detect room type (public channel vs private group) and use the correct API endpoint.

Reliability

• Dynamic room subscription — auto-subscribes to new rooms without restart
• Reconnect with full state restore — room subscriptions + user events survive disconnects
• Dedup with TTL — timestamped message dedup with 6-hour expiry (outlasts reconnect replays) and 500 hard cap
• Stale message rejection — drops messages older than 5 minutes after WebSocket reconnect to prevent replay floods
• Room cache with TTL — 5-minute cache with stale fallback on fetch failure
• Proper file uploads — two-step rooms.media + rooms.mediaConfirm flow, errors throw (no silent degradation)
• Clean shutdown — all timers, intervals, and WebSocket connections properly cleaned up

Why?

The original @cloudrise/openclaw-channel-rocketchat plugin is closed-source with several bugs:

• File uploads silently fall back to [File: path] text on failure
• DM room IDs rejected by regex (17-char limit, DMs are 34+)
• getReactions returns read receipts instead of actual reactions
• Room cache never expires
• Dedup allows replay attacks
• Private group operations fail (hardcoded channels.* endpoints)
• Debug logging left in production code
• And 23 more issues (see CHANGELOG.md)

This plugin fixes all of them and adds features the original never had.

For AI Agents

See AGENT.md — a complete reference for AI agents using this plugin. Includes all available actions, tips for rich messages, and automatic features. Add it to your agent's workspace or reference it from your TOOLS.md.

Development

# Install dependencies
npm install

# Type-check
npm run typecheck

# Run live integration tests (needs RC credentials)
# Edit test-live.mjs with your test bot credentials first
node --import tsx test-live.mjs

License

MIT — see LICENSE.