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.

Install

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

# From npm (coming soon)
# npm install -g rocketchat-openclaw

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 (30+)

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

| Action | Description | |--------|-------------| | read | Read message history | | 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 | | 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 |

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 10-minute expiry and 500 hard cap
• 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.