Add README with usage examples and documentation

2026-03-31 21:36:29 +02:00
parent 843242241b
commit f8bc254d30
1 changed files with 243 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,243 @@
+# WebSocket Channel Plugin for OpenClaw
+
+Custom WebSocket-based messaging channel plugin for OpenClaw. Enables custom messaging platforms to connect via WebSocket with configurable capabilities and API key authentication.
+
+## Features
+
+- 🔐 **API Key Authentication** - Secure connections via `X-API-Key` header or query parameter
+- 🏢 **Multi-tenant** - Support for multiple accounts with unique API keys
+- ⚙️ **Configurable Capabilities** - Per-account configuration for:
+  - Text messages
+  - Images
+  - Files
+  - Voice messages
+  - Reactions
+  - Threads
+  - Typing indicators
+- 🛡️ **DM Security** - Three policies: `allowlist`, `open`, `closed`
+- 🔗 **Threading** - Full support for threaded conversations
+- 🤝 **Pairing Flow** - Text-based pairing with code exchange
+- 📊 **CLI Commands** - Management via `openclaw websocket status` and `openclaw websocket accounts`
+
+## Installation
+
+### Local Development
+
+```bash
+# Plugin is already in extensions/websocket-channel
+# OpenClaw will auto-load it
+```
+
+### From Git
+
+```bash
+git clone https://git.azimkin.dev/Azimkin/openclaw-websocket-channel.git
+cd openclaw-websocket-channel
+openclaw plugins install ./openclaw-websocket-channel
+```
+
+## Configuration
+
+Add to your `openclaw.json`:
+
+```json
+{
+  "channels": {
+    "websocket": {
+      "port": 8765,
+      "path": "/ws",
+      "accounts": [
+        {
+          "accountId": "default",
+          "apiKey": "sk_test_your_api_key_here",
+          "allowFrom": ["user-123", "user-456"],
+          "dmPolicy": "allowlist",
+          "capabilities": {
+            "text": true,
+            "images": true,
+            "files": false,
+            "voice": false,
+            "reactions": false,
+            "threads": true,
+            "typing": true
+          },
+          "metadata": {
+            "serverName": "My WebSocket Server",
+            "region": "eu-west"
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+## WebSocket Protocol
+
+### Connection
+
+```
+ws://localhost:8765/ws?key=YOUR_API_KEY
+```
+
+Or with header:
+```javascript
+const ws = new WebSocket('ws://localhost:8765/ws', {
+  headers: { 'X-API-Key': 'YOUR_API_KEY' }
+});
+```
+
+### Message Format
+
+**Client → Server:**
+```json
+{
+  "type": "message",
+  "from": "user-123",
+  "content": {
+    "type": "text",
+    "text": "Hello, bot!"
+  }
+}
+```
+
+**Server → Client (Handshake):**
+```json
+{
+  "type": "handshake",
+  "accountId": "default",
+  "capabilities": {
+    "text": true,
+    "images": true,
+    "files": false,
+    "voice": false,
+    "reactions": false,
+    "threads": true,
+    "typing": true
+  },
+  "metadata": {
+    "serverName": "My WebSocket Server"
+  }
+}
+```
+
+**Server → Client (Message):**
+```json
+{
+  "type": "message",
+  "to": "user-123",
+  "content": {
+    "type": "text",
+    "text": "Hello! How can I help?"
+  },
+  "messageId": "msg_abc123",
+  "timestamp": 1703275200000
+}
+```
+
+## Client Examples
+
+### JavaScript
+
+```javascript
+import WebSocket from 'ws';
+
+const ws = new WebSocket('ws://localhost:8765/ws?key=YOUR_API_KEY');
+
+ws.on('message', (data) => {
+  const msg = JSON.parse(data.toString());
+  if (msg.type === 'message') {
+    console.log('Bot:', msg.content.text);
+  }
+});
+
+// Send message
+ws.send(JSON.stringify({
+  type: 'message',
+  from: 'user-123',
+  content: { type: 'text', text: 'Hello!' }
+}));
+```
+
+### Python
+
+```python
+import websocket
+import json
+
+def on_message(ws, message):
+    data = json.loads(message)
+    if data['type'] == 'message':
+        print(f"Bot: {data['content']['text']}")
+
+ws = websocket.WebSocketApp(
+    "ws://localhost:8765/ws?key=YOUR_API_KEY",
+    on_message=on_message
+)
+ws.run_forever()
+```
+
+## CLI Commands
+
+```bash
+# Show WebSocket status
+openclaw websocket status
+
+# List configured accounts
+openclaw websocket accounts
+```
+
+## Testing
+
+```bash
+# Install wscat
+npm install -g wscat
+
+# Connect
+wscat -c "ws://localhost:8765/ws?key=YOUR_API_KEY"
+
+# Send message
+> {"type":"message","from":"user-123","content":{"type":"text","text":"Hello!"}}
+```
+
+## Documentation
+
+- [Client Specification](../../specs/websocket-client-spec.md) - Full protocol documentation
+- [Plugin Specification](../../specs/websocket-channel-plugin.md) - Development spec
+- [OpenClaw Docs](https://docs.openclaw.ai) - General OpenClaw documentation
+
+## Development
+
+### Project Structure
+
+```
+websocket-channel/
+├── package.json              # Package metadata
+├── openclaw.plugin.json      # Plugin manifest
+├── index.ts                  # Main entry point
+├── setup-entry.ts            # Setup entry point
+├── api.ts                    # Public API exports
+└── src/
+    ├── config.ts             # Types and defaults
+    ├── auth.ts               # Authentication utilities
+    ├── websocket-server.ts   # WebSocket server
+    ├── client.ts             # Connection handler
+    ├── channel.ts            # Channel plugin config
+    └── channel.test.ts       # Test suite
+```
+
+### Running Tests
+
+```bash
+cd extensions/websocket-channel
+pnpm test
+```
+
+## License
+
+MIT
+
+## Support
+
+- Issues: https://git.azimkin.dev/Azimkin/openclaw-websocket-channel/issues
+- OpenClaw Discord: https://discord.com/invite/clawd