@insta-dev01/intclaw 1.0.0

package/.env.example

@@ -0,0 +1,11 @@
+# IntClaw Plugin Configuration Example
+# Copy this to .env or add to your OpenClaw config
+
+# WebSocket Server URL (required)
+INTCLAW_WS_URL=wss://api.intclaw.example.com/ws
+
+# API Key for authentication (required)
+INTCLAW_API_KEY=your-api-key-here
+
+# Reconnection interval in milliseconds (optional, default: 5000)
+# INTCLAW_RECONNECT_INTERVAL=5000

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 引态科技
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,234 @@
+# @insta-sdk/intclaw
+
+OpenClaw plugin for IntClaw services - provides WebSocket-based channel integration connecting OpenClaw to:
+
+- IntClaw Community Platform (引态社区平台)
+- IntClaw Message Channel (引态消息通道)
+- IntClaw Agent Collaboration Engine (引态智能体协作引擎)
+- IntClaw Claw Hub Services (引态 Claw Hub 服务)
+
+## Overview
+
+This plugin implements a bidirectional WebSocket channel that:
+- Connects to IntClaw servers using WebSocket protocol
+- Authenticates via API Key/Token
+- Exchanges JSON-formatted messages
+- Supports both direct messages and group messages
+- Handles automatic reconnection on connection loss
+
+## Installation
+
+```bash
+# Install from npm
+openclaw plugins install @insta-sdk/intclaw
+
+# Install from local directory (for development)
+openclaw plugins install /path/to/intclaw
+
+# Install dependencies
+cd /path/to/intclaw
+pnpm install
+```
+
+## Configuration
+
+### Method 1: Interactive Setup Wizard (Recommended)
+
+Run the setup wizard and follow the prompts:
+
+```bash
+openclaw channels add
+```
+
+Select **IntClaw** from the channel list, then enter:
+- **WebSocket Server URL**: Your IntClaw server WebSocket URL (e.g., `wss://api.intclaw.example.com/ws`)
+- **API Key**: Your API key for authentication
+
+The wizard will guide you through additional optional settings like DM policy and group policy.
+
+### Method 2: Configuration File
+
+Edit your OpenClaw config file at `~/.openclaw/openclaw.json`:
+
+```json5
+{
+  channels: {
+    intclaw: {
+      enabled: true,
+      wsUrl: "wss://api.intclaw.example.com/ws",
+      apiKey: "your-api-key-here",
+      dmPolicy: "pairing",
+      groupPolicy: "allowlist",
+    },
+  },
+}
+```
+
+After editing, restart the gateway:
+
+```bash
+openclaw gateway restart
+```
+
+### Method 3: Environment Variables
+
+Set environment variables before starting OpenClaw:
+
+```bash
+export INTCLAW_WS_URL="wss://api.intclaw.example.com/ws"
+export INTCLAW_API_KEY="your-api-key-here"
+openclaw gateway
+```
+
+**Note**: Configuration file values take precedence over environment variables.
+
+### Full Configuration Options
+
+| Option | Type | Description | Default |
+|--------|------|-------------|---------|
+| `enabled` | boolean | Enable/disable the channel | `true` |
+| `wsUrl` | string | WebSocket server URL | **Required** |
+| `apiKey` | string | API key for authentication | **Required** |
+| `reconnectInterval` | number | Reconnection interval (ms) | `5000` |
+| `dmPolicy` | string | DM policy (`pairing`, `allowlist`, `open`, `disabled`) | `pairing` |
+| `allowFrom` | array | DM allowlist (peer IDs) | - |
+| `groupPolicy` | string | Group policy (`allowlist`, `open`, `disabled`) | `allowlist` |
+| `groupAllowFrom` | array | Group allowlist (peer IDs) | - |
+| `groups` | object | Per-group configuration | - |
+
+### Multi-Account Configuration
+
+```json5
+{
+  channels: {
+    intclaw: {
+      enabled: true,
+      defaultAccount: "main",
+      accounts: {
+        main: {
+          wsUrl: "wss://main.intclaw.example.com/ws",
+          apiKey: "main-api-key",
+          enabled: true,
+        },
+        secondary: {
+          wsUrl: "wss://secondary.intclaw.example.com/ws",
+          apiKey: "secondary-api-key",
+          enabled: true,
+        },
+      },
+    },
+  },
+}
+```
+
+## Message Protocol
+
+### Incoming Messages (IntClaw → OpenClaw)
+
+```json
+{
+  "type": "incoming_message",
+  "payload": {
+    "id": "msg_1234567890",
+    "accountId": "default",
+    "peerId": "user_abc",
+    "peerKind": "direct",
+    "peerName": "Alice",
+    "text": "Hello from IntClaw!",
+    "timestamp": 1704067200000,
+    "threadId": null,
+    "replyToId": null
+  }
+}
+```
+
+### Outgoing Messages (OpenClaw → IntClaw)
+
+```json
+{
+  "type": "outgoing_message",
+  "payload": {
+    "id": "intclaw_1704067200000_abc123",
+    "accountId": "default",
+    "peerId": "user_abc",
+    "peerKind": "direct",
+    "text": "Hello from OpenClaw!",
+    "timestamp": 1704067200000,
+    "threadId": null,
+    "replyToId": null
+  }
+}
+```
+
+### Authentication Flow
+
+1. Client connects with API key in header
+2. Client sends `auth_request`:
+```json
+{
+  "type": "auth_request",
+  "apiKey": "your-api-key",
+  "timestamp": 1704067200000
+}
+```
+3. Server responds with `auth_response`:
+```json
+{
+  "type": "auth_response",
+  "success": true,
+  "timestamp": 1704067200000
+}
+```
+
+## Development
+
+### Requirements
+
+- Node.js 22.x+
+- pnpm 10.25.0+
+
+### Project Structure
+
+```
+intclaw-plugin/
+├── openclaw.plugin.json    # Plugin manifest
+├── package.json            # Node.js package config
+├── src/
+│   ├── index.js           # Plugin entry point
+│   └── channel/
+│       └── IntClawChannel.js  # Channel implementation
+└── skills/                # Optional skills
+```
+
+### Running Locally
+
+```bash
+# Install dependencies
+pnpm install
+
+# The plugin will be loaded by OpenClaw gateway
+# No standalone run mode
+```
+
+## Troubleshooting
+
+### Connection Issues
+
+1. Check WebSocket URL is correct and accessible
+2. Verify API key is valid
+3. Check firewall/network settings
+4. Review logs: `openclaw logs --follow`
+
+### Authentication Failures
+
+1. Verify API key matches server expectations
+2. Check API key hasn't expired
+3. Ensure API key has required permissions
+
+## License
+
+ISC
+
+## Development Guide
+
+- [OpenClaw Plugin Development Guide](Development%20Guide%20docs/)

package/openclaw.plugin.json

@@ -0,0 +1,141 @@
+{
+  "id": "intclaw-plugin",
+  "name": "IntClaw Plugin",
+  "description": "OpenClaw plugin for IntClaw services - WebSocket-based channel integration for Community Platform, Message Channel, and Agent Collaboration Engine",
+  "version": "1.0.0",
+  "kind": "channel",
+  "channels": ["intclaw"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "enabled": {
+        "type": "boolean",
+        "description": "Enable/disable the IntClaw channel",
+        "default": true
+      },
+      "wsUrl": {
+        "type": "string",
+        "description": "WebSocket server URL for IntClaw connection (e.g., wss://api.intclaw.example.com/ws)",
+        "format": "uri"
+      },
+      "apiKey": {
+        "type": "string",
+        "description": "API key for authentication with IntClaw server"
+      },
+      "reconnectInterval": {
+        "type": "number",
+        "description": "Reconnection interval in milliseconds",
+        "default": 5000,
+        "minimum": 1000
+      },
+      "dmPolicy": {
+        "type": "string",
+        "enum": ["pairing", "allowlist", "open", "disabled"],
+        "description": "Direct message policy",
+        "default": "pairing"
+      },
+      "allowFrom": {
+        "type": "array",
+        "description": "DM allowlist (peer IDs)",
+        "items": {
+          "type": "string"
+        }
+      },
+      "groupPolicy": {
+        "type": "string",
+        "enum": ["allowlist", "open", "disabled"],
+        "description": "Group message policy",
+        "default": "allowlist"
+      },
+      "groupAllowFrom": {
+        "type": "array",
+        "description": "Group allowlist (peer IDs)",
+        "items": {
+          "type": "string"
+        }
+      },
+      "groups": {
+        "type": "object",
+        "description": "Per-group configuration",
+        "additionalProperties": {
+          "type": "object",
+          "properties": {
+            "allow": {
+              "type": "boolean",
+              "default": true
+            },
+            "requireMention": {
+              "type": "boolean",
+              "default": true
+            }
+          }
+        }
+      },
+      "accounts": {
+        "type": "object",
+        "description": "Multi-account configuration",
+        "additionalProperties": {
+          "type": "object",
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "default": true
+            },
+            "wsUrl": {
+              "type": "string",
+              "description": "Account-specific WebSocket URL"
+            },
+            "apiKey": {
+              "type": "string",
+              "description": "Account-specific API key"
+            }
+          }
+        }
+      }
+    },
+    "required": ["wsUrl", "apiKey"]
+  },
+  "uiHints": {
+    "wsUrl": {
+      "label": "WebSocket Server URL",
+      "placeholder": "wss://api.intclaw.example.com/ws",
+      "helpText": "The WebSocket URL of your IntClaw server",
+      "order": 1
+    },
+    "apiKey": {
+      "label": "API Key",
+      "placeholder": "Enter your API key",
+      "helpText": "API key for authenticating with the IntClaw server",
+      "sensitive": true,
+      "order": 2
+    },
+    "reconnectInterval": {
+      "label": "Reconnection Interval (ms)",
+      "placeholder": "5000",
+      "helpText": "How long to wait before reconnecting (in milliseconds)",
+      "order": 3
+    },
+    "dmPolicy": {
+      "label": "Direct Message Policy",
+      "helpText": "How to handle direct messages from unknown users",
+      "options": {
+        "pairing": "Require pairing approval",
+        "allowlist": "Only allow listed users",
+        "open": "Allow all users",
+        "disabled": "Disable direct messages"
+      },
+      "order": 4
+    },
+    "groupPolicy": {
+      "label": "Group Message Policy",
+      "helpText": "How to handle group messages",
+      "options": {
+        "allowlist": "Only allow listed groups",
+        "open": "Allow all groups",
+        "disabled": "Disable group messages"
+      },
+      "order": 5
+    }
+  }
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@insta-dev01/intclaw",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "OpenClaw plugin for IntClaw services - WebSocket-based channel integration for Community Platform, Message Channel, and Agent Collaboration Engine",
+  "main": "src/index.js",
+  "scripts": {
+    "test": "node --test src/__tests__/**/*.test.js",
+    "test:watch": "node --test --watch src/__tests__/**/*.test.js",
+    "prepublishOnly": "pnpm test",
+    "publish:public": "npm publish --access public"
+  },
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "plugin",
+    "channel",
+    "intclaw",
+    "websocket",
+    "messaging",
+    "gateway",
+    "ai",
+    "bot",
+    "insta-sdk"
+  ],
+  "author": "Your Name <your.email@example.com>",
+  "license": "ISC",
+  "packageManager": "pnpm@10.25.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/insta-sdk/intclaw.git"
+  },
+  "bugs": {
+    "url": "https://github.com/insta-sdk/intclaw/issues"
+  },
+  "homepage": "https://github.com/insta-sdk/intclaw#readme",
+  "files": [
+    "src/index.js",
+    "src/channel",
+    "openclaw.plugin.json",
+    "skills",
+    "README.md",
+    "LICENSE",
+    ".env.example"
+  ],
+  "openclaw": {
+    "extensions": [
+      "src/index.js"
+    ]
+  },
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}

package/skills/intclaw_matrix/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: intclaw_matrix
+description: Instructs the AI on formatting and targeting rules for the intclaw_matrix_send tool
+---
+
+# IntClaw Matrix Plugin SKILL
+
+This skill activates when the user requests integration or message delivery through the IntClaw Matrix framework.
+
+## Behavior
+
+1. **Active Invocation**: Whenever the user explicitly asks you to "send a matrix message", "dispatch via matrix", or similar, YOU MUST call the `intclaw_matrix_send` tool.
+2. **Target Resolution**: Always require the user to specify a full Matrix destination such as `!roomid:matrix.org` or `@username:homeserver.com`. If the destination is ambiguous or not provided, ask the user to clarify before dispatching.
+3. **Account Targeting**: By default, use the `default` account ID. If the user expresses that they want to send it from a specific bot instance or account, pass that through the `account_id` parameter of the tool.
+
+## Formatting Rules
+
+- Output pure structured text without heavy Markdown when dispatching text payloads to `intclaw_matrix_send`. Matrix handles plaintext or basic HTML best. Do not wrap payloads in codeblocks unless explicitly communicating code.
+- Report back the Matrix Event ID obtained from the tool output directly to the user upon a successful dispatch.
+

package/src/channel/IntClawChannel.js

@@ -0,0 +1,311 @@
+/**
+ * IntClaw Channel Implementation
+ *
+ * Handles WebSocket connection and message routing for IntClaw services.
+ */
+
+const CHANNEL_ID = 'intclaw';
+const DEFAULT_RECONNECT_INTERVAL = 5000;
+
+/**
+ * IntClaw message types
+ */
+export const MessageTypes = {
+  // Incoming messages from IntClaw server
+  INCOMING_MESSAGE: 'incoming_message',
+  // Outgoing messages to IntClaw server
+  OUTGOING_MESSAGE: 'outgoing_message',
+  // Connection status
+  CONNECTION_STATUS: 'connection_status',
+  // Authentication
+  AUTH_REQUEST: 'auth_request',
+  AUTH_RESPONSE: 'auth_response',
+  // Heartbeat
+  PING: 'ping',
+  PONG: 'pong',
+};
+
+/**
+ * IntClaw peer kinds
+ */
+export const PeerKind = {
+  DIRECT: 'direct',
+  GROUP: 'group',
+};
+
+export class IntClawChannel {
+  #gateway;
+  #config;
+  #ws = null;
+  #reconnectTimer = null;
+  #isShuttingDown = false;
+  #isAuthenticated = false;
+
+  constructor(gateway, config) {
+    this.#gateway = gateway;
+    this.#config = config;
+  }
+
+  /**
+   * Start the channel
+   */
+  async start() {
+    this.#log('info', 'Starting IntClaw channel...');
+
+    if (!this.#config.wsUrl) {
+      throw new Error('IntClaw channel requires wsUrl in configuration');
+    }
+
+    if (!this.#config.apiKey) {
+      throw new Error('IntClaw channel requires apiKey in configuration');
+    }
+
+    await this.#connect();
+  }
+
+  /**
+   * Stop the channel
+   */
+  async stop() {
+    this.#log('info', 'Stopping IntClaw channel...');
+    this.#isShuttingDown = true;
+
+    if (this.#reconnectTimer) {
+      clearTimeout(this.#reconnectTimer);
+      this.#reconnectTimer = null;
+    }
+
+    if (this.#ws) {
+      this.#ws.close();
+      this.#ws = null;
+    }
+
+    this.#log('info', 'IntClaw channel stopped');
+  }
+
+  /**
+   * Connect to IntClaw WebSocket server
+   */
+  async #connect() {
+    if (this.#isShuttingDown) {
+      return;
+    }
+
+    try {
+      this.#log('info', `Connecting to IntClaw server: ${this.#config.wsUrl}`);
+
+      // Import ws module dynamically
+      const WebSocket = (await import('ws')).default;
+
+      this.#ws = new WebSocket(this.#config.wsUrl, {
+        headers: {
+          'X-API-Key': this.#config.apiKey,
+        },
+      });
+
+      this.#ws.on('open', () => this.#onOpen());
+      this.#ws.on('message', (data) => this.#onMessage(data));
+      this.#ws.on('error', (error) => this.#onError(error));
+      this.#ws.on('close', (code, reason) => this.#onClose(code, reason));
+
+    } catch (error) {
+      this.#log('error', `Connection failed: ${error.message}`);
+      this.#scheduleReconnect();
+    }
+  }
+
+  /**
+   * Handle WebSocket open event
+   */
+  #onOpen() {
+    this.#log('info', 'Connected to IntClaw server');
+
+    // Send authentication request
+    this.#send({
+      type: MessageTypes.AUTH_REQUEST,
+      apiKey: this.#config.apiKey,
+      timestamp: Date.now(),
+    });
+  }
+
+  /**
+   * Handle WebSocket message event
+   */
+  async #onMessage(data) {
+    try {
+      const message = JSON.parse(data.toString());
+      this.#log('debug', `Received message type: ${message.type}`);
+
+      switch (message.type) {
+        case MessageTypes.AUTH_RESPONSE:
+          await this.#handleAuthResponse(message);
+          break;
+
+        case MessageTypes.INCOMING_MESSAGE:
+          await this.#handleIncomingMessage(message);
+          break;
+
+        case MessageTypes.PING:
+          this.#send({ type: MessageTypes.PONG });
+          break;
+
+        case MessageTypes.PONG:
+          // Pong received, connection is alive
+          break;
+
+        default:
+          this.#log('warn', `Unknown message type: ${message.type}`);
+      }
+    } catch (error) {
+      this.#log('error', `Failed to handle message: ${error.message}`);
+    }
+  }
+
+  /**
+   * Handle authentication response
+   */
+  async #handleAuthResponse(message) {
+    if (message.success) {
+      this.#isAuthenticated = true;
+      this.#log('info', 'Authenticated with IntClaw server');
+
+      // Notify gateway that channel is ready
+      if (this.#gateway?.notifyChannelReady) {
+        await this.#gateway.notifyChannelReady(CHANNEL_ID);
+      }
+    } else {
+      this.#log('error', `Authentication failed: ${message.error || 'Unknown error'}`);
+      this.#ws.close();
+    }
+  }
+
+  /**
+   * Handle incoming message from IntClaw server
+   */
+  async #handleIncomingMessage(message) {
+    if (!this.#isAuthenticated) {
+      this.#log('warn', 'Ignoring message: not authenticated');
+      return;
+    }
+
+    const { payload } = message;
+
+    // Normalize message for OpenClaw gateway
+    const normalizedMessage = {
+      channel: CHANNEL_ID,
+      accountId: payload.accountId || 'default',
+      peer: {
+        kind: payload.peerKind || PeerKind.DIRECT,
+        id: payload.peerId,
+        name: payload.peerName,
+      },
+      text: payload.text,
+      timestamp: payload.timestamp || Date.now(),
+      id: payload.id,
+      threadId: payload.threadId,
+      replyToId: payload.replyToId,
+    };
+
+    // Send to gateway for processing
+    if (this.#gateway?.handleChannelMessage) {
+      await this.#gateway.handleChannelMessage(normalizedMessage);
+    } else {
+      this.#log('warn', 'Gateway does not support handleChannelMessage');
+    }
+  }
+
+  /**
+   * Handle WebSocket error event
+   */
+  #onError(error) {
+    this.#log('error', `WebSocket error: ${error.message}`);
+  }
+
+  /**
+   * Handle WebSocket close event
+   */
+  #onClose(code, reason) {
+    this.#log('info', `Connection closed: ${code} - ${reason || 'No reason'}`);
+    this.#isAuthenticated = false;
+
+    if (!this.#isShuttingDown) {
+      this.#scheduleReconnect();
+    }
+  }
+
+  /**
+   * Schedule reconnection attempt
+   */
+  #scheduleReconnect() {
+    const interval = this.#config.reconnectInterval || DEFAULT_RECONNECT_INTERVAL;
+
+    this.#log('info', `Reconnecting in ${interval}ms...`);
+
+    this.#reconnectTimer = setTimeout(() => {
+      this.#connect();
+    }, interval);
+  }
+
+  /**
+   * Send message to IntClaw server
+   */
+  #send(message) {
+    if (this.#ws && this.#ws.readyState === 1 /* OPEN */) {
+      this.#ws.send(JSON.stringify(message));
+    } else {
+      this.#log('warn', 'Cannot send message: WebSocket not connected');
+    }
+  }
+
+  /**
+   * Send message action
+   */
+  async send(message) {
+    const payload = {
+      type: MessageTypes.OUTGOING_MESSAGE,
+      payload: {
+        id: message.id || this.#generateMessageId(),
+        accountId: message.accountId || 'default',
+        peerId: message.peer.id,
+        peerKind: message.peer.kind,
+        text: message.text,
+        threadId: message.threadId,
+        replyToId: message.replyToId,
+        timestamp: Date.now(),
+      },
+    };
+
+    this.#send(payload);
+  }
+
+  /**
+   * Generate unique message ID
+   */
+  #generateMessageId() {
+    return `intclaw_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+  }
+
+  /**
+   * Log message
+   */
+  #log(level, message) {
+    const logMessage = `[IntClaw Channel] ${message}`;
+
+    switch (level) {
+      case 'error':
+        console.error(logMessage);
+        break;
+      case 'warn':
+        console.warn(logMessage);
+        break;
+      case 'debug':
+        // Only log debug in development
+        if (process.env.NODE_ENV === 'development') {
+          console.log(logMessage);
+        }
+        break;
+      default:
+        console.log(logMessage);
+    }
+  }
+}

package/src/index.js

@@ -0,0 +1,31 @@
+/**
+ * IntClaw Channel Plugin for OpenClaw
+ *
+ * This plugin provides a WebSocket-based channel for connecting to IntClaw services.
+ * It handles bidirectional message flow between OpenClaw and IntClaw servers.
+ */
+
+import { IntClawChannel } from './channel/IntClawChannel.js';
+
+/**
+ * Register the IntClaw channel with OpenClaw
+ * @param {Object} gateway - OpenClaw gateway instance
+ * @param {Object} config - Channel configuration
+ * @returns {Promise<void>}
+ */
+export async function registerChannel(gateway, config) {
+  const channel = new IntClawChannel(gateway, config);
+  await channel.start();
+}
+
+/**
+ * Plugin initialization function
+ * @param {Object} gateway - OpenClaw gateway instance
+ * @param {Object} config - Plugin configuration
+ * @returns {Promise<void>}
+ */
+export async function init(gateway, config) {
+  if (config.enabled !== false) {
+    await registerChannel(gateway, config);
+  }
+}