Skills Plugins Jobs Pricing
← Back to Plugins
Channels

Xmpp Channel

elmafioso79 By elmafioso79 ⭐ 2 stars 👁 11 views ▲ 0 votes

XMPP/Jabber channel plugin for OpenClaw, supporting Prosody, ejabberd, and other XMPP servers.

GitHub

Install

npm install
   npm

Configuration Example

{
  "channels": {
    "xmpp": {
      "accounts": {
        "work": {
          "jid": "[email protected]",
          "password": "work-pass",
          "groups": ["[email protected]"]
        },
        "personal": {
          "jid": "[email protected]",
          "password": "personal-pass",
          "dmPolicy": "open"
        }
      }
    }
  }
}

README

# XMPP Channel for OpenClaw

XMPP/Jabber channel plugin for OpenClaw, supporting Prosody, ejabberd, and other XMPP servers.

> **Note:** This plugin has been tested with [Conversations](https://conversations.im/) (Android) and [Gajim](https://gajim.org/) (Desktop). Other XMPP clients may work but have not been verified.

## Features

- **Direct Messages** β€” One-on-one chat via XMPP
- **Group Chat** β€” Group chat rooms with auto-join and invite handling
- **Multi-Account** β€” Configure multiple XMPP accounts
- **Owner Access** β€” `allowFrom` defines bot owners who always have direct chat access
- **Guest Policies** β€” `dmPolicy` controls guest access: open, disabled, pairing, or allowlist
- **Pairing** β€” Approve unknown senders with pairing codes
- **Reactions** β€” XEP-0444 message reactions support
- **Typing Indicators** β€” XEP-0085 chat state notifications
- **Read Receipts** β€” XEP-0333 chat markers
- **Reply Context** β€” XEP-0461 message replies with fallback
- **Media Upload** β€” XEP-0363 HTTP file upload with auto-discovery
- **Stream Management** β€” XEP-0198 for reliable message delivery
- **Keepalive** β€” XEP-0199 ping for connection stability
- **Auto-Reconnect** β€” Exponential backoff reconnection
- **Heartbeat** β€” Periodic status checks and notifications
- **Onboarding** β€” CLI setup wizard integration
- **Directory** β€” Contact and room listings

## Installation

### Manual Installation
1. Clone the repository:
   ```bash
   git clone https://github.com/elmafioso79/xmpp-channel.git ~/.openclaw/extensions/xmpp
   ```
2. Install dependencies and build:
   ```bash
   cd ~/.openclaw/extensions/xmpp
   npm install
   npm run build
   ```
3. Configure with openclaw or add to your `openclaw.json`:
   ```
   json
   {
     "channels": {
       "xmpp": {
         "enabled": true,
         "jid": "[email protected]",
         "password": "your-password",
         "server": "example.com",
         "port": 5222,
         "dmPolicy": "pairing",
         "allowFrom": ["[email protected]", "[email protected]"],
         "groups": ["[email protected]"],
         "actions": {
         "reactions": true
         }
       }
     }
   }
   ```
4. Enable plugin
   ```bash
   openclaw plugins enable xmpp 
   ```
### Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `jid` | string | **required** | Bot JID (e.g., `[email protected]`) |
| `password` | string | **required** | XMPP account password |
| `server` | string | JID domain | XMPP server hostname |
| `port` | number | `5222` | XMPP server port |
| `resource` | string | `openclaw` | XMPP resource identifier |
| `name` | string | - | Account display name |
| `enabled` | boolean | `true` | Whether account is enabled |
| `dmPolicy` | string | `open` | Guest direct chat policy: `disabled`, `open`, `pairing`, `allowlist` |
| `allowFrom` | string[] | `[]` | Bot owner JIDs (always have direct chat access, cannot be removed by guests) |
| `dmAllowlist` | string[] | `[]` | JIDs allowed to direct-chat when dmPolicy is `allowlist` |
| `groupPolicy` | string | `open` | Group policy: `open`, `allowlist` |
| `groups` | string[] | `[]` | Group chat rooms to auto-join |
| `nickname` | string | JID local | Nickname to use in group chats |
| `groupAllowFrom` | string[] | `allowFrom` | Allowed senders in groups (falls back to `allowFrom`) |
| `actions.reactions` | boolean | `false` | Enable XEP-0444 reactions |
| `messagePrefix` | string | - | Inbound message prefix |
| `heartbeatVisibility` | string | - | Heartbeat visibility: `visible`, `hidden` |
| `groupSettings.<roomJid>.requireMention` | boolean | `false` | Only respond when mentioned in this room |
| `groupSettings.<roomJid>.tools` | object | - | Tool policy for this room (allow/deny lists) |
| `omemo.enabled` | boolean | `false` | Enable OMEMO encryption (XEP-0384) |
| `omemo.deviceLabel` | string | - | Display label for this device in OMEMO device list |

### Multi-Account Configuration

```json
{
  "channels": {
    "xmpp": {
      "accounts": {
        "work": {
          "jid": "[email protected]",
          "password": "work-pass",
          "groups": ["[email protected]"]
        },
        "personal": {
          "jid": "[email protected]",
          "password": "personal-pass",
          "dmPolicy": "open"
        }
      }
    }
  }
}
```

## Direct Chat Policies

- **disabled** β€” Only owner JIDs (in `allowFrom`) can direct-chat the bot
- **open** β€” Accept direct chats from any sender
- **pairing** β€” Guests get a pairing code; approve via `openclaw pairing approve xmpp:<code>`
- **allowlist** β€” Only owner JIDs and JIDs in `dmAllowlist` may direct-chat; owners cannot be removed by the agent

## Actions

### Reactions (XEP-0444)

Enable reactions in config:

```json
{
  "channels": {
    "xmpp": {
      "actions": {
        "reactions": true
      }
    }
  }
}
```

The agent can then use the `react` action to add/remove reactions to messages.

### OMEMO Encryption (XEP-0384)

Enable end-to-end encryption with OMEMO:

```json
{
  "channels": {
    "xmpp": {
      "omemo": {
        "enabled": true,
        "deviceLabel": "OpenClaw Bot"
      }
    }
  }
}
```

When OMEMO is enabled:
- The bot automatically publishes its device ID and key bundle via PEP
- Incoming encrypted messages are automatically decrypted
- Outgoing messages are automatically encrypted for all recipient devices
- Group chat messages are encrypted for all room occupants (requires non-anonymous rooms)
- The bot uses **always-trust** policy (accepts any identity key without verification)
- Keys are persisted across restarts via OpenClaw's key-value storage

#### OMEMO Requirements

- **Server:** Must support PEP (XEP-0163). Most modern servers (Prosody, ejabberd) support this.
- **Group Rooms:** Must be configured as "non-anonymous" for OMEMO to work. This allows the bot to discover real JIDs of occupants.
- **Clients:** Use an OMEMO-capable client like Conversations or Gajim.

#### OMEMO Technical Details

- Uses the **legacy OMEMO namespace** (`eu.siacs.conversations.axolotl`) for maximum compatibility with Conversations and Gajim
- Signal protocol via `@privacyresearch/libsignal-protocol-typescript`
- AES-128-GCM payload encryption (OMEMO 0.3 format)
- Supports both prekey (initial) and regular Signal messages

#### OMEMO Troubleshooting

| Issue | Cause | Solution |
|-------|-------|----------|
| Messages not encrypting | OMEMO not enabled | Add `"omemo": { "enabled": true }` to config |
| Can't decrypt in group | Room is semi-anonymous | Configure room as "non-anonymous" in server |
| Client doesn't see bot's device | Device not published | Restart openclaw; check PEP is enabled on server |
| "No devices found" error | Can't fetch recipient's device list | Ensure recipient has OMEMO enabled; check PEP access |
| Decryption fails after restart | Keys not persisted | Check OpenClaw data directory is writable |
| Old messages unreadable | Forward secrecy | Normal - OMEMO can't decrypt messages from before session |

**Clearing OMEMO State:**

If you need to reset OMEMO keys (e.g., after corruption), delete the OMEMO store from OpenClaw's key-value storage and restart. The bot will generate new keys and republish its device.

## Commands

Run the onboarding wizard:

```bash
openclaw channels add
```

Check channel status:

```bash
openclaw channels status
```

## Development

```bash
npm install          # Install dependencies
npm run build        # Compile TypeScript
npm run dev          # Watch mode
```

## Architecture

```
src/
β”œβ”€β”€ index.ts           # Plugin entry point
β”œβ”€β”€ channel.ts         # Main channel plugin definition
β”œβ”€β”€ types.ts           # TypeScript interfaces
β”œβ”€β”€ config-schema.ts   # Zod schema for config validation
β”œβ”€β”€ runtime.ts         # Runtime getter/setter
β”‚
β”œβ”€β”€ monitor.ts         # Main XMPP connection entry point
β”œβ”€β”€ state.ts           # Global state maps and constants
β”œβ”€β”€ stanza-handlers.ts # Presence and invite handlers
β”œβ”€β”€ iq-handlers.ts     # XEP-0092 version, XEP-0202 time
β”œβ”€β”€ inbound.ts         # Inbound message routing to OpenClaw
β”œβ”€β”€ outbound.ts        # Send messages to XMPP
β”‚
β”œβ”€β”€ rooms.ts           # Group room management and persistence
β”œβ”€β”€ keepalive.ts       # XEP-0199 ping keepalive
β”œβ”€β”€ reconnect.ts       # Exponential backoff reconnection
β”œβ”€β”€ chat-state.ts      # XEP-0085 typing, XEP-0333 receipts
β”‚
β”œβ”€β”€ pep.ts             # XEP-0163 Personal Eventing Protocol
β”œβ”€β”€ http-upload.ts     # XEP-0363 HTTP File Upload
β”œβ”€β”€ actions.ts         # XEP-0444 message reactions
β”œβ”€β”€ xml-utils.ts       # Shared XML/stanza utilities
β”‚
β”œβ”€β”€ accounts.ts        # Account resolution utilities
β”œβ”€β”€ normalize.ts       # JID normalization utilities
β”œβ”€β”€ directory.ts       # Contact/room directory
β”œβ”€β”€ heartbeat.ts       # Heartbeat adapter
β”œβ”€β”€ onboarding.ts      # CLI setup wizard
β”œβ”€β”€ status-issues.ts   # Status issue detection
β”‚
└── omemo/             # OMEMO encryption (XEP-0384)
    β”œβ”€β”€ index.ts       # OMEMO encrypt/decrypt entry points
    β”œβ”€β”€ bundle.ts      # Key bundle generation and publishing
    β”œβ”€β”€ device.ts      # Device list management
    β”œβ”€β”€ device-cache.ts# Device list caching with TTL
    β”œβ”€β”€ muc-occupants.ts # MUC occupant tracking for real JIDs
    β”œβ”€β”€ store.ts       # Signal protocol store implementation
    └── types.ts       # OMEMO type definitions
```

## Roadmap

- [x] Phase 1: Basic XMPP connection, auth, direct messages
- [x] Phase 2: Group chat support, group message handling, onboarding
- [x] Adapters: config, security, groups, mentions, threading, directory, actions, heartbeat, status
- [x] Phase 3: XEP-0163 PEP, XEP-0363 HTTP file upload
- [x] Phase 4: XEP-0085 typing, XEP-0333 receipts, XEP-0198 stream management, XEP-0199 keepalive, XEP-0461 replies
- [x] Code Quality: Modular architecture, split monitor.ts into focused modules
- [x] Phase 5: OMEMO encryption (XEP-0384) with Signal protocol
- [x] Phase 6: Message carbons (XEP-0280)

## XEP Support

| XE

... (truncated)
channels

Comments

Sign in to leave a comment

Loading comments...

Similar Plugins in Channels

Dingtalk

Dingtalk

DingTalk (ι’‰ι’‰) channel plugin for OpenClaw.

17 18
Moltbot Wecom Channel

Moltbot Wecom Channel

Enterprise WeChat (WeCom) integration plugin for Moltbot. Fixes API compatibility issues with the latest Plugin SDK.

11 11
Moltbot Channel Feishu

Moltbot Channel Feishu

A production-grade Feishu/Lark channel plugin for Moltbot(Clawdbot).

7
Tlon

Tlon

Tlon/Urbit channel plugin for Moltbot

3 3
Moltbot Lark

Moltbot Lark

Moltbot Lark (飞书) channel plugin - Real-time messaging integration for https://github.com/moltbot/moltbot

1
Gmail

Gmail

Gmail channel plugin for Moltbot

1