https://github.com/alexwoo-awso/openclaw-rocketchat

OpenClaw channel plugin for Rocket.Chat — DDP/REST, DMs, groups, threads, media, multi-account
https://github.com/alexwoo-awso/openclaw-rocketchat

ai-assistant channel-plugin chatbot ddp npm-package openclaw rocketchat typescript

Last synced: about 2 months ago
JSON representation

OpenClaw channel plugin for Rocket.Chat — DDP/REST, DMs, groups, threads, media, multi-account

Host: GitHub
URL: https://github.com/alexwoo-awso/openclaw-rocketchat
Owner: alexwoo-awso
License: mit
Created: 2026-02-16T16:38:49.000Z (4 months ago)
Default Branch: main
Last Pushed: 2026-04-25T10:07:56.000Z (about 2 months ago)
Last Synced: 2026-04-25T11:27:55.642Z (about 2 months ago)
Topics: ai-assistant, channel-plugin, chatbot, ddp, npm-package, openclaw, rocketchat, typescript
Language: TypeScript
Homepage:
Size: 686 KB
Stars: 13
Watchers: 1
Forks: 5
Open Issues: 2
Metadata Files:
- Readme: README.md
- License: LICENSE
- Security: SECURITY.md

Awesome Lists containing this project

README

# OpenClaw Rocket.Chat Plugin

Channel plugin for connecting OpenClaw to [Rocket.Chat](https://rocket.chat/) instances.

**npm package:** `@alexwoo-awso/openclaw-rocketchat`

## Features

- Direct messages, channels, private groups, and threads
- Media/file upload and download
- Mention-gated channel behavior, `onmessage`, and `onchar` trigger modes
- Conversation windows for follow-up messages after a mention or trigger
- Multi-account support
- Pairing-based DM access control
- Block streaming with configurable coalescing
- DDP WebSocket realtime monitoring with auto-reconnect

## Setup

### Authentication methods

The plugin supports both Rocket.Chat auth paths:

- **Personal Access Token (PAT):** configure `authToken` + `userId`
- **Username/password login:** configure `username` + `password`

PAT is usually the better choice when your Rocket.Chat plan exposes Personal Access Tokens. Username/password works on plans where PAT is unavailable.

### Secret storage

Prefer environment variables for secrets instead of committing them into `openclaw.json`.

OpenClaw can load env vars from:

- the gateway process environment
- `~/.openclaw/.env`

### Base URL

Use the Rocket.Chat server base URL, for example:

- `https://chat.example.com`

Do not use `/api/v1` in config examples unless you want to; the plugin strips a trailing slash and also normalizes a trailing `/api/v1`.

### Important config rules

- The bot user must already be a member of channels or private groups you want it to monitor.
- Only the **default** Rocket.Chat account can read `ROCKETCHAT_*` environment variables.
- Config values override env vars **field by field**.
- If you define `channels.rocketchat.accounts`, the top-level `channels.rocketchat` values still act as shared defaults for those named accounts unless a per-account value overrides them.
- A Rocket.Chat account is considered configured when it has `baseUrl` plus either `authToken` + `userId` or `username` + `password`.

### Option A: Default account from environment variables

PAT:

```bash
export ROCKETCHAT_URL=https://chat.example.com
export ROCKETCHAT_AUTH_TOKEN=your-personal-access-token
export ROCKETCHAT_USER_ID=your-user-id
```

Username/password:

```bash
export ROCKETCHAT_URL=https://chat.example.com
export ROCKETCHAT_USERNAME=openclaw-bot
export ROCKETCHAT_PASSWORD=your-password
```

### Option B: Default account in `openclaw.json`

PAT:

```json
{
"channels": {
"rocketchat": {
"enabled": true,
"baseUrl": "https://chat.example.com",
"authToken": "your-personal-access-token",
"userId": "your-user-id"
}
}
}
```

Username/password:

```json
{
"channels": {
"rocketchat": {
"enabled": true,
"baseUrl": "https://chat.example.com",
"username": "openclaw-bot",
"password": "your-password"
}
}
}
```

### Option C: Multi-account config

Named accounts are config-only. `ROCKETCHAT_*` env vars do not apply to them.

This example also shows shared top-level defaults inherited by each account:

```yaml
channels:
rocketchat:
enabled: true
chatmode: oncall
conversationWindowMinutes: 10
groupPolicy: allowlist
accounts:
primary:
baseUrl: https://chat.example.com
authToken: token-1
userId: user-1
allowFrom: ["@admin"]
secondary:
baseUrl: https://other-chat.example.com
username: openclaw-bot
password: secret
chatmode: onchar
oncharPrefixes: ["!"]
rooms:
GENERAL_ROOM_ID:
conversationWindowMinutes: 20
```

## Configuration Reference

The same account-level options can be set either:

- at `channels.rocketchat.*` for the default/shared config
- at `channels.rocketchat.accounts..*` for a named account

### Authentication and connection

| Option | Type | Description |
|--------|------|-------------|
| `enabled` | boolean | Enables or disables the channel or account. Default is enabled. |
| `name` | string | Optional display name for the account in CLI/UI lists. |
| `baseUrl` | string | Rocket.Chat base URL such as `https://chat.example.com`. |
| `authToken` | string | Personal Access Token. |
| `userId` | string | Rocket.Chat user ID paired with `authToken`. |
| `username` | string | Username for login auth instead of PAT. |
| `password` | string | Password for login auth instead of PAT. |

### Inbound trigger behavior

| Option | Type | Description |
|--------|------|-------------|
| `chatmode` | string | `oncall`, `onmessage`, or `onchar`. |
| `oncharPrefixes` | string[] | Prefixes that trigger `chatmode: onchar`. Default: `">"` and `"!"`. |
| `requireMention` | boolean | Mention gate for groups/channels when `chatmode` does not force behavior. |
| `conversationWindowMinutes` | number | Keeps a room active for follow-up messages after a valid mention/trigger. `0` or unset disables it. |
| `rooms..conversationWindowMinutes` | number | Per-room override for the conversation window. |

Behavior notes:

- Direct messages are not mention-gated.
- `chatmode: oncall` effectively requires a mention in channels/groups.
- `chatmode: onmessage` effectively disables mention gating in channels/groups.
- `chatmode: onchar` accepts channel/group messages that start with a configured prefix, and strips that prefix before sending the message to OpenClaw.
- Conversation windows only relax the mention/trigger requirement; they do not bypass access-control policy.

### Access control

| Option | Type | Description |
|--------|------|-------------|
| `dmPolicy` | string | DM policy: `pairing`, `allowlist`, `open`, or `disabled`. Default: `pairing`. |
| `allowFrom` | array | Allowed DM senders as Rocket.Chat user IDs, `user:ID`, `rocketchat:ID`, plain usernames, or `@username`. |
| `groupPolicy` | string | Group/channel policy: `allowlist`, `open`, or `disabled`. Default: `allowlist`. |
| `groupAllowFrom` | array | Allowed senders in channels/private groups. |

Important:

- If `dmPolicy` is `open`, `allowFrom` must include `"*"` or schema validation fails.
- `allowFrom` and `groupAllowFrom` comparisons are case-insensitive for usernames.

### Outbound reply behavior

| Option | Type | Description |
|--------|------|-------------|
| `textChunkLimit` | number | Maximum characters per outbound text message. Default: `4000`. |
| `chunkMode` | string | Outbound chunking mode: `length` or `newline`. |
| `blockStreaming` | boolean | Enables or disables block streaming for this channel/account. |
| `blockStreamingCoalesce.minChars` | number | Minimum buffered characters before a streamed block reply is flushed. |
| `blockStreamingCoalesce.idleMs` | number | Idle timeout before a buffered streamed block reply is flushed. |
| `responsePrefix` | string | Optional outbound reply prefix override for this channel/account. |
| `markdown` | object | Standard OpenClaw markdown configuration for this channel/account. |

Current streaming defaults for Rocket.Chat:

- `blockStreamingCoalesce.minChars`: `1500`
- `blockStreamingCoalesce.idleMs`: `1000`

Delivery notes:

- Long text replies are split into sequential Rocket.Chat messages.
- `chunkMode: newline` splits more aggressively than `chunkMode: length`.
- If media upload fails and the media source was an `http://` or `https://` URL, the plugin falls back to sending the URL as text.

### Miscellaneous

| Option | Type | Description |
|--------|------|-------------|
| `configWrites` | boolean | Allows channel-initiated config writes. |
| `capabilities` | string[] | Optional capability tags used for agent/runtime guidance. |

## Sending Messages

```bash
# Send to a room id directly
openclaw send --channel rocketchat --to ROOM_ID "Hello"

# Send to a room id with an explicit prefix
openclaw send --channel rocketchat --to channel:ROOM_ID "Hello"

# Send to a user
openclaw send --channel rocketchat --to @username "Hello"
openclaw send --channel rocketchat --to user:USER_ID "Hello"
```

Accepted `--to` formats:

- `ROOM_ID`
- `channel:ROOM_ID`
- `@username`
- `user:USER_ID`
- `rocketchat:USER_ID`

When sending to a user, the plugin creates or reuses a Rocket.Chat DM room for that user.

## Architecture

- DDP WebSocket for realtime inbound messages
- Rocket.Chat REST API for login, sending messages, uploads, user lookup, and room lookup
- Threads are sent with Rocket.Chat `tmid`
- Room types handled: channels (`c`), private groups (`p`), direct messages (`d`), and livechat (`l`)

## Troubleshooting

- No replies in channels:
- make sure the bot user is in the room
- `chatmode: oncall` requires a mention unless a conversation window is active
- `chatmode: onchar` requires a configured prefix such as `!hello`
- `chatmode: onmessage` replies to accepted channel/group messages without a mention
- Auth problems:
- PAT mode needs both `authToken` and `userId`
- login mode needs both `username` and `password`
- the plugin logs in through `/api/v1/login` when using username/password and can log in again later if needed
- env vars only apply to the default account
- Base URL problems:
- use the server base URL, not a deep REST path
- trailing `/` and `/api/v1` are normalized away

Security review notes for scanner findings and manual audits are tracked in `SECURITY.md`.

## License

MIT

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/alexwoo-awso/openclaw-rocketchat

Awesome Lists containing this project

README