OpenClaw XMPP
A native XMPP direct-message channel plugin for OpenClaw. It runs inside the OpenClaw Gateway and uses OpenClaw's normal routing, sessions, commands, delivery pipeline, pairing store, and status surfaces.
The canonical source repository is
SDF Gitea. The
soilDNRA/openclaw-xmpp repository
is a clearly labelled one-way GitHub mirror that points back to SDF as the
source of truth. Eric is the initial maintainer.
This project is pre-release. The source tree is 0.1.2-beta.6, including
opt-in legacy OMEMO, trusted-device delivery and a stale-parser crash guard.
The ClawHub beta release is 0.1.2-beta.6; there is no stable/default release
yet. Releases remain on the explicit beta tag.
Install the reviewed beta explicitly with:
openclaw plugins install clawhub:openclaw-xmpp@0.1.2-beta.6
Core interoperability has been exercised against both Prosody and ejabberd, and with Conversations and Gajim clients.
The durable project goal, status, decisions, and roadmap are maintained in
PROJECT.md.
Supported
- XMPP direct chats over verified TLS
- Multiple named accounts
- Bare-JID allowlists and OpenClaw pairing
- Per-sender OpenClaw session routing
- XEP-0085 chat states
- XEP-0184 delivery receipts
- XEP-0203 delayed-delivery timestamps
- XEP-0359 origin/stanza IDs for deduplication
- XEP-0363 HTTP upload for outbound local media
- XEP-0447/XEP-0446 inline file sharing with MIME type, name, size, and XEP-0300 SHA-256 integrity metadata for uploaded local media
- XEP-0066 out-of-band URL fallback for uploaded media
- Structured OpenClaw message-tool sends using
media,mediaUrl,path, orfilePath; captions are sent immediately before a URL-only XEP-0428 fallback media stanza so Conversations renders supported files inline
MUC/group chats, reactions, edits, retractions, and inbound file downloads are not supported. Beta.6 provides explicitly opt-in legacy OMEMO with manual trust controls. OMEMO 2 has no independent live-client interoperability proof and is experimental.
Development
Development, issues, and release tags belong on the canonical SDF Gitea repository. The GitHub copy is a visibility and upstream-review mirror, not a second source of truth.
npm ci
npm run verify
Package-shape validation:
npm pack --dry-run
Installing a packed artefact changes the active OpenClaw installation. Follow the release checklist and preserve a known-good rollback package before doing that on a live Gateway.
Compatibility
- Node.js 22.22.3 or newer is required.
- OpenClaw 2026.8.2 is the minimum supported Gateway and plugin API version.
- CI runs the pinned OpenClaw 2026.8.2 baseline on Node.js 22.22.3 and Node.js 24.
- Before each release, the packed artefact must also pass loader and live smoke tests against the current stable OpenClaw release. A lower-bound version range is not a promise of compatibility with an untested future SDK.
Configuration
Environment variables provide a minimal single-account setup:
export XMPP_JID='bot@example.org'
export XMPP_PASSWORD='use-an-app-password'
Equivalent OpenClaw configuration:
{
"channels": {
"xmpp": {
"enabled": true,
"jid": "bot@example.org",
"password": {
"source": "env",
"provider": "default",
"id": "XMPP_PASSWORD"
},
"resource": "openclaw",
"textChunkLimit": 4000,
"dmPolicy": "pairing",
"allowFrom": []
}
}
}
For named accounts:
{
"channels": {
"xmpp": {
"defaultAccount": "personal",
"accounts": {
"personal": {
"enabled": true,
"jid": "bot@example.org",
"password": {
"source": "env",
"provider": "default",
"id": "XMPP_PASSWORD"
},
"dmPolicy": "allowlist",
"allowFrom": [
"owner@example.org"
]
}
}
}
}
}
allowFrom entries are normalized to bare JIDs. "*" is accepted only when
dmPolicy is "open".
Long replies are split at paragraph boundaries where practical. Set
textChunkLimit on the channel or an individual named account to change the
maximum outbound message size; the default is 4,000 characters. A smaller
value can improve compatibility with clients that truncate very long message
bodies.
If normal DNS SRV discovery is unavailable, configure service or
websocketUrl. Explicit xmpp: services must negotiate STARTTLS; xmpps:
uses direct TLS, and WebSocket connections must use wss:. The plugin closes
the connection before sending presence or messages if transport security is
not active.
Session continuity
XMPP uses OpenClaw's core session routing and lifecycle; the plugin does not
silently impose its own reset schedule. For a personal conversational account,
session.dmScope: "per-channel-peer" keeps each XMPP peer isolated while
preserving a stable conversation binding. OpenClaw 2026.9.2 defaults to no
automatic reset when no reset policy is configured, and compaction bounds the
active model context as a conversation grows. Send /new or /reset when you
deliberately want a fresh conversation; verify the default for other OpenClaw
versions before relying on it.
Operators who want to make the no-automatic-reset choice explicit can use:
{
"session": {
"dmScope": "per-channel-peer",
"resetByChannel": {
"xmpp": { "mode": "none" }
}
}
}
Automatic daily or idle reset policies are optional operator choices and
can cause a later follow-up to start a fresh transcript generation. Check the
session documentation for the OpenClaw version you deploy rather than assuming
a fixed clock boundary across releases.
Opt-in OMEMO operator lifecycle
The source tree contains an explicitly opt-in OMEMO implementation. It remains
disabled by default and is not a claim of general OMEMO 2 interoperability.
When an approved test or private activation enables it, the Gateway owner can
use /xmpp-omemo to review and change trust without editing SQLite state:
/xmpp-omemo list <account>
/xmpp-omemo trust <account> <jid.device> <expected-state> <fingerprint> <next-state>
/xmpp-omemo replace <account> <jid.device> <expected-state> <old-fingerprint> <new-fingerprint> <next-state>
/xmpp-omemo retire-device <account> <legacy|omemo2> <local-device-id>
/xmpp-omemo activate-device <account> <legacy|omemo2> <local-device-id>
Fingerprints printed by list are copy-safe 64-character hexadecimal values.
Every mutation compares the reviewed prior state and fingerprint. Identity
replacement additionally requires the exact newly observed fingerprint and
removes the old ratchet in the same local transaction.
Device retirement writes a durable local marker before changing PEP, removes
only the exact local device from the conflict-aware device list, and then
retracts its bundle. An interrupted retirement is completed before presence on
restart. While retired, reconnect cannot republish the device and encrypted
sends fail closed. Local keys remain available for rollback; activate-device
publishes the exact retained bundle before clearing the marker. Production
configuration changes, Gateway restarts, and activation remain separate
operator decisions.
With trustMode: "manual", a first inbound encrypted stanza is rejected in
the same transaction that would otherwise change ratchet state. If no trust
record exists yet, make one outbound encrypted attempt to that peer first; it
resolves the advertised bundle and records the fingerprint as undecided
without sending plaintext. Review that fingerprint independently, apply the
exact compare-and-set trust command, then retry encrypted traffic.
Multi-device delivery and review
Existing configurations retain omemo.deliveryPolicy: "strict-all". To allow
trusted devices to keep receiving when a new device appears, explicitly set
channels.xmpp.omemo.deliveryPolicy (or the account's omemo.deliveryPolicy)
to "trusted-devices". Keep the existing profile and trust mode. This excludes
undecided, distrusted, retired and missing-bundle devices; at least one device
of the actual recipient must remain trusted/verified. Changed keys, corrupt
records and encryption failures still block delivery. There is no plaintext
fallback. trustMode: "tofu" is a separate first-use choice, not verification,
and does not approve an existing undecided record.
Delivery status exposes deliveryState, lastDeliveryError,
lastDeliveryFailureAt, excludedDeviceCount and pendingDeviceCount.
Counts describe the most recent send attempt, not a complete account inventory.
A successful ping does not clear a delivery error. A successful encrypted send
clears the error and reports healthy or degraded according to excluded devices.
Rate-limited notices are inside the encrypted reply, never its outer body.
On an authenticated non-XMPP owner channel:
/xmpp-omemo review <account>
/xmpp-omemo approve <account> <review-code>
Review displays full fingerprints and ready-to-use approval commands. Only
approve a device you recognise. Approval sets trusted, not verified; keep
using the exact fingerprint command after independent comparison for verified
trust. Review codes expire after ten minutes, are single-use, bound to the
reviewer/account/key/state, and invalidated by refreshed reviews or restart.
Changed keys require the existing explicit replacement workflow.
Authenticated admin clients can call xmpp.omemo.review with { "accountId": "default" }, then xmpp.omemo.approve with { "accountId": "default", "code": "<returned-code>" }. Both require an operator with operator.admin scope.
Use the same authenticated user, or the same connection when the host does not
supply an authenticated user ID. These are Gateway RPCs, not a new built-in
Control UI page or model tools. XMPP short-code approval is deliberately
unavailable until the host carries verified sender-device provenance.
A deployment must explicitly enable the new policy. Rollback restores the previous package and removes the new policy field (older schemas reject it). Keep the OMEMO state and keys: no state migration or trust reset is needed. Previously failed replies were not queued and are not automatically replayed; send a fresh message after activation.
Acknowledgements
This project's roadmap has been informed by Mickaël Rémond and ProcessOne's earlier OpenClaw XMPP implementation, particularly its work on active health probing, reconnect visibility, onboarding, reactions, replies/threads, and MUC. Their implementation and maintenance offer are important prior work, and we gratefully credit them even where this project uses a fresh implementation.
Exact reviewed revisions, source paths, licence information, and the boundary
between influence and adapted source are recorded in
THIRD_PARTY_NOTICES.md.
Licence
OpenClaw XMPP is free software licensed under the GNU General Public License,
version 3 or (at your option) any later version. See LICENSE.
Security
Please use the private reporting route described in
SECURITY.md. Do not put credentials, private JIDs, message
contents, server addresses, or exploit details in a public issue.
Release checklist
- The licence is
GPL-3.0-or-later; Eric is the initial maintainer. The reviewed source prerelease is public, but keepprivate: trueuntil the package-release gates pass and package publication is separately approved. - Keep the SDF repository, issue tracker, and homepage metadata canonical. GitHub Private Vulnerability Reporting is enabled on the labelled mirror.
- Run
npm run verifyon the minimum supported Node/OpenClaw versions. - Install the packed tarball using
npm-pack:and inspect the loaded runtime. - Run live tests against at least two XMPP servers and clients.
- Verify STARTTLS/direct TLS certificate failures are fail-closed.
- Verify pairing, allowlist, reconnect, receipt, delayed stanza, and upload behavior.
- Review the packed file list for secrets and machine-specific paths.
- Require separate explicit owner approval for release tags, ClawHub publication, npm publication, and standard-installer inclusion.
Interactive OpenClaw channel setup now supports named accounts without hand-editing JSON. It requires a password environment-variable name and saves that reference as a SecretRef; the resolved password is never written to the configuration or displayed. Setup requires an explicit direct-message policy, refuses insecure WebSockets, explains explicit-host certificate verification, and validates TLS, authentication, and resource binding before returning a configuration to be saved.
XEP-0199 health probing is enabled conservatively by default (every 300
seconds with a 15-second timeout). Set healthProbe: false to disable it, or
use healthProbeIntervalSeconds, healthProbeTimeoutSeconds, and
reconnectDelaySeconds within the manifest bounds. Channel status reports
probe health, reconnect attempts, and XEP-0198 resume/full-rebind outcomes.