Registry / messaging / openclaw-websocket

openclaw-websocket

library0.0.9jsnpmunverified

OpenClaw WebSocket channel plugin version 0.0.9 for connecting external applications to OpenClaw AI agents via WebSocket. Released under MIT license with stable releases from Taichi-Labs. Supports real-time bidirectional communication, streaming responses, independent session memory per user, direct messages and group chats, media attachments, reply quotes, and optional external JWT authentication. Differentiates from other WebSocket chat plugins through deep integration with the OpenClaw ecosystem including built-in dynamic per-user agent creation for multi-tenant scenarios.

messaging

npm install openclaw-websocket

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · OPENCLAW-WEBSOCKET

openclaw-websocket

messagingjavascriptv0.0.9

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import openclawWebSocket from '@taichi-labs/openclaw-websocket'

ESM default import; the plugin is configured via OpenClaw config file, not imported directly in code

WebSocketChannel

✓ import { WebSocketChannel } from '@taichi-labs/openclaw-websocket'

✗ const { WebSocketChannel } = require('@taichi-labs/openclaw-websocket')

Named export available since v0.0.5; CommonJS require may cause issues with some bundlers

Shows plugin installation, minimal OpenClaw config to enable WebSocket channel, and a basic Node.js WebSocket client to send/receive messages.

// Install plugin // openclaw plugins install @taichi-labs/openclaw-websocket // add to OpenClaw config (openclaw.json) { "channels": { "websocket": { "enabled": true, "port": 18800, "host": "0.0.0.0", "path": "/ws", "auth": { "enabled": false } } } } // Start OpenClaw // openclaw start // Client connection example (Node.js client) const WebSocket = require('ws'); const ws = new WebSocket('ws://localhost:18800/ws'); ws.on('open', () => { // Send a message to the default agent ws.send(JSON.stringify({ type: 'message', conversation: 'default', text: 'Hello, AI!' })); }); ws.on('message', (data) => { const msg = JSON.parse(data); if (msg.type === 'text') { console.log('AI:', msg.text); } }); ws.on('error', console.error);

Debug

Known issues

breakingAuth enabled by default; clients must provide a valid JWT token as ?token= URL parameter or connection will be rejected

fix

Set 'auth.enabled': false in config to allow unauthenticated connections temporarily during development

affects: >=0.0.1

gotchaThe auth endpoint receives POST with JSON body { "token": "..." } and must return { "success": true, "data": { "userId": "...", "username": "..." } }. Any other response format causes connection rejection.

fix

Ensure auth service follows exact request/response contract; customizing via code changes not supported

affects: >=0.0.1

gotchaDynamic agent creation creates new agents and workspaces on disk per DM user; maxAgents not set defaults to unlimited, could lead to disk space exhaustion

fix

Set a reasonable maxAgents limit in dynamicAgentCreation config

affects: >=0.0.5

deprecatedThe 'path' option may be renamed to 'endpoint' in future releases for consistency with other OpenClaw channel plugins

fix

Use 'path' for now but expect migration notes on next major release

affects: 0.0.9

Errors

Common errors & fixes

Error: listen EADDRINUSE :::18800

Port 18800 is already in use by another process or instance

fix

Kill existing process using port or change websocket.port in OpenClaw config to an available port

Error: Authentication failed: invalid token format

Client connected without ?token= URL parameter or token is not a valid JWT

fix

Include token parameter: ws://host:port/ws?token=YOUR_JWT_TOKEN or disable auth in config

Error: Auth service request timed out after 5000ms

Auth service endpoint not reachable or responds too slowly

fix

Check auth service URL and network; increase auth.timeout or ensure service is running

Upgrade

Version history

0.0.9latest on npm

Audit

Dependencies

openclawrequiredRequired peer dependency as a plugin for the OpenClaw framework

Agent activity

12 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/Taichi-Labs/openclaw-websocket ↗

packageopenclaw-websocket ↗

homepagehttps://github.com/Taichi-Labs/openclaw-websocket#readme ↗