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 <iamdoctorclaw@gmail.com>' ]
# 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:

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.