@rlynicrisis/link 0.0.1

package/README.md

@@ -0,0 +1,64 @@
+# OpenClaw Link Channel Plugin
+
+这是一个 OpenClaw 的 Link 消息服务接入插件。
+
+## 功能
+- 接入 Link 消息服务 (TCP 协议)
+- 支持接收文本消息
+- 支持回复文本消息
+- **安全限制**: 仅允许接收和回复自己账号的消息（Bot 自言自语模式）
+
+## 安装与配置
+
+### 1. 构建插件
+
+在插件根目录下运行：
+
+```bash
+npm install
+npm run build
+```
+
+这将生成 `dist` 目录。
+
+### 2. 配置 OpenClaw
+
+在您的 OpenClaw 主配置文件（通常是 `config.yaml` 或 `config.json`）中，添加以下内容：
+
+#### 注册插件
+如果 OpenClaw 支持本地插件加载，请确保插件路径被包含在加载列表中，或者将本插件发布/链接到 `node_modules`。
+
+#### 频道配置
+在 `channels` 部分添加 `link` 配置：
+
+```yaml
+channels:
+  link:
+    enabled: true
+    # Link 服务地址
+    host: "embtcpbeta.bingolink.biz"
+    port: 20081
+    # 鉴权信息 (必填)
+    accessToken: "your_access_token"
+    # 可选配置
+    # heartbeatIntervalMs: 30000
+    # verifyInfo: # 如果需要覆盖默认生成的设备信息，可在此配置
+    #   deviceName: "CustomBotName"
+```
+
+> **注意**：
+> - `userId` 将自动从 `accessToken` (JWT) 中解析。
+> - `deviceUID` 将根据机器特征自动生成，确保同一设备上的稳定性。
+> - 其他参数如 `version`, `deviceToken` 等已内置默认值。
+
+### 3. 启动 OpenClaw
+
+启动 OpenClaw 主程序，插件将自动连接 Link 服务。
+
+## 开发调试
+
+可以使用 `test/manual-connect.ts` 脚本单独测试连接：
+
+```bash
+npx tsx test/manual-connect.ts
+```

package/index.ts

@@ -0,0 +1,22 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { setLinkRuntime } from "./src/runtime.js";
+import { linkPlugin } from "./src/channel.js";
+
+const plugin = {
+  id: "link",
+  name: "Link",
+  description: "Link channel plugin",
+  configSchema: {
+    type: "object",
+    properties: {
+      host: { type: "string" },
+      port: { type: "number" }
+    }
+  },
+  register(api: OpenClawPluginApi) {
+    setLinkRuntime(api.runtime);
+    api.registerChannel(linkPlugin);
+  },
+};
+
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1,14 @@
+{
+  "id": "link",
+  "channels": ["link"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "host": { "type": "string", "description": "Link Server Host (e.g. embtcpbeta.bingolink.biz)" },
+      "port": { "type": "number", "description": "Link Server Port (e.g. 20081)" },
+      "accessToken": { "type": "string", "description": "User Access Token" },
+      "heartbeatIntervalMs": { "type": "number", "default": 30000 }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@rlynicrisis/link",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "OpenClaw Link channel plugin",
+  "files": [
+    "index.ts",
+    "src/**/*.ts",
+    "!src/**/__tests__/**",
+    "!src/**/*.test.ts",
+    "openclaw.plugin.json"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "ws": "^8.18.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.5.4",
+    "@types/ws": "^8.5.12",
+    "openclaw": "latest",
+    "typescript": "^5.5.4",
+    "vitest": "^2.0.5"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "channel": {
+      "id": "link",
+      "label": "Link",
+      "selectionLabel": "Link Messaging Service",
+      "blurb": "Integration with Link messaging service.",
+      "order": 100
+    },
+    "install": {
+      "npmSpec": "@rlynicrisis/link",
+      "localPath": ".",
+      "defaultChoice": "npm"
+    }
+  }
+}

package/src/bot.ts

@@ -0,0 +1,138 @@
+import {
+  type ClawdbotConfig,
+  type RuntimeEnv,
+} from "openclaw/plugin-sdk";
+import { LinkConfig } from "./types.js";
+import { createLinkClient, getLinkClient } from "./client-manager.js";
+import { getLinkRuntime } from "./runtime.js";
+import { createLinkReplyDispatcher } from "./reply-dispatcher.js";
+import { EmbMessage } from "./link/types.js";
+import { MsgType, ParticipantType } from "./link/constants.js";
+
+export async function startLinkBot(cfg: ClawdbotConfig, runtime: RuntimeEnv) {
+  const linkCfg = cfg.channels?.link as LinkConfig | undefined;
+  
+  // Basic validation
+  if (!linkCfg) {
+    // Channel not enabled or configured
+    return;
+  }
+  
+  if (!linkCfg.accessToken) {
+    runtime.log?.("Link channel configured but missing accessToken");
+    return;
+  }
+  
+  const accountId = "default"; // For now single account support
+  
+  let client = getLinkClient(accountId);
+  if (!client) {
+    client = createLinkClient(accountId, linkCfg);
+    
+    client.on('connected', () => {
+      runtime.log?.("Link client connected");
+    });
+    
+    client.on('disconnected', () => {
+      runtime.log?.("Link client disconnected");
+    });
+    
+    client.on('error', (err) => {
+      runtime.error?.(`Link client error: ${err}`);
+    });
+
+    client.on('message', (msg: EmbMessage) => {
+      handleLinkMessage({ cfg, msg, runtime, accountId, linkCfg }).catch(err => {
+        runtime.error?.(`Error handling Link message: ${err}`);
+      });
+    });
+    
+    client.connect();
+  }
+}
+
+export async function stopLinkBot() {
+  // Implement cleanup if needed
+}
+
+async function handleLinkMessage(params: {
+  cfg: ClawdbotConfig;
+  msg: EmbMessage;
+  runtime: RuntimeEnv;
+  accountId: string;
+  linkCfg: LinkConfig;
+}) {
+  const { cfg, msg, runtime, accountId, linkCfg } = params;
+  const core = getLinkRuntime();
+
+  if (msg.type !== MsgType.TEXT) {
+    // Only support text for now
+    return;
+  }
+
+  const senderId = msg.fromId || "unknown";
+  const toId = msg.toId || "unknown";
+  
+  // SECURITY: Only process messages sent by the bot user itself
+  // Note: userId is populated in client.ts into verifyInfo during connection
+  const allowedUserId = linkCfg.verifyInfo?.userId;
+  if (!allowedUserId || senderId !== allowedUserId || toId !== allowedUserId) {
+    return;
+  }
+
+  // Determine chat ID (for reply)
+  // If group message, reply to group (toId). If DM, reply to sender (fromId).
+  // Assuming if toType is GROUP, then it's a group chat.
+  const isGroup = msg.toType === ParticipantType.GROUP;
+  const chatId = isGroup ? msg.toId : senderId;
+
+  // Map Link message to OpenClaw InboundContext
+  const sessionKey = `link:${chatId}`; 
+  
+  const ctx = core.channel.reply.finalizeInboundContext({
+    Body: msg.content,
+    RawBody: msg.content,
+    CommandBody: msg.content,
+    From: senderId,
+    To: "bot", 
+    SessionKey: sessionKey,
+    AccountId: accountId,
+    ChatType: isGroup ? "group" : "direct",
+    GroupSubject: isGroup ? chatId : undefined,
+    SenderName: msg.fromName || senderId,
+    SenderId: senderId,
+    Provider: "link" as any, 
+    Surface: "link" as any,
+    MessageSid: msg.id || `temp-${Date.now()}`,
+    Timestamp: msg.sendTime || Date.now(),
+    WasMentioned: !isGroup, // Assume DM is always mentioned. For group, need mention logic.
+    OriginatingChannel: "link" as any,
+    OriginatingTo: "bot",
+  });
+
+  // Resolve route (Agent)
+  const route = core.channel.routing.resolveAgentRoute({
+    cfg,
+    channel: "link",
+    accountId,
+    peer: { kind: isGroup ? "group" : "direct", id: chatId }
+  });
+
+  const { dispatcher, replyOptions, markDispatchIdle } = createLinkReplyDispatcher({
+    cfg,
+    agentId: route.agentId,
+    runtime,
+    chatId: chatId,
+    accountId,
+    linkConfig: linkCfg
+  });
+
+  await core.channel.reply.dispatchReplyFromConfig({
+    ctx,
+    cfg,
+    dispatcher,
+    replyOptions
+  });
+  
+  markDispatchIdle();
+}

package/src/channel.ts

@@ -0,0 +1,90 @@
+import type { ChannelPlugin } from "openclaw/plugin-sdk";
+import { startLinkBot, stopLinkBot } from "./bot.js";
+import { linkOnboardingAdapter } from "./onboarding.js";
+
+export const linkPlugin: ChannelPlugin<any> = {
+  id: "link",
+  onboarding: linkOnboardingAdapter,
+  meta: {
+    id: "link",
+    label: "Link",
+    selectionLabel: "Link Messaging",
+    docsPath: "",
+    docsLabel: "link",
+    blurb: "Integration with Link messaging service",
+    order: 100
+  },
+  capabilities: {
+    chatTypes: ["direct", "channel"],
+    polls: false,
+    threads: false,
+    media: false,
+    reactions: false,
+    edit: false,
+    reply: true
+  },
+  configSchema: {
+     schema: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+           host: { type: "string" },
+           port: { type: "number" },
+           verifyInfo: { 
+             type: "object",
+             properties: {
+               userId: { type: "string" },
+               deviceUID: { type: "string" },
+               deviceName: { type: "string" },
+               deviceToken: { type: "string" },
+               accessToken: { type: "string" },
+               version: { type: "string" },
+               force: { type: "boolean" },
+               protocolVersion: { type: "number" },
+               isFirstLogin: { type: "boolean" },
+               secret: { type: "string" }
+             }
+           },
+           heartbeatIntervalMs: { type: "number" }
+        }
+     }
+  },
+  config: {
+    listAccountIds: (cfg) => {
+        // Return default account if channel is configured
+        if (cfg?.channels?.link?.accessToken) { return ["default"]; }
+        return []; 
+    },
+    resolveAccount: (cfg, accountId) => {
+      // Return dummy account for now
+      return {
+        accountId,
+        enabled: true,
+        configured: true,
+        name: "Link Bot",
+      } as any;
+    },
+    defaultAccountId: (cfg) => "default",
+    setAccountEnabled: ({ cfg, accountId, enabled }) => cfg,
+    deleteAccount: ({ cfg, accountId }) => cfg,
+    isConfigured: (account) => true,
+    describeAccount: (account) => ({
+      accountId: account.accountId,
+      enabled: true,
+      configured: true,
+      name: "Link Bot",
+    }),
+  },
+  gateway: {
+    startAccount: async (ctx) => {
+      await startLinkBot(ctx.cfg, ctx.runtime);
+      
+      return new Promise((resolve) => {
+        ctx.abortSignal.addEventListener("abort", () => {
+          stopLinkBot();
+          resolve(undefined);
+        });
+      });
+    }
+  }
+};

package/src/client-manager.ts

@@ -0,0 +1,27 @@
+import { LinkClient } from "./link/client.js";
+import { LinkConfig } from "./types.js";
+
+const clients = new Map<string, LinkClient>();
+
+export function getLinkClient(accountId: string = "default"): LinkClient | undefined {
+  return clients.get(accountId);
+}
+
+export function createLinkClient(accountId: string, config: LinkConfig): LinkClient {
+  const existing = clients.get(accountId);
+  if (existing) {
+    existing.disconnect();
+  }
+  
+  const client = new LinkClient(config);
+  clients.set(accountId, client);
+  return client;
+}
+
+export function removeLinkClient(accountId: string) {
+  const client = clients.get(accountId);
+  if (client) {
+    client.disconnect();
+    clients.delete(accountId);
+  }
+}

package/src/link/client.ts

@@ -0,0 +1,281 @@
+import * as net from 'net';
+import { EventEmitter } from 'events';
+import { Buffer } from 'buffer';
+import * as os from 'os';
+import * as crypto from 'crypto';
+import { CmdCodes } from './constants.js';
+import { decodePacket, encodePacket, encodeMessage, decodeMessage, ProtocolError } from './protocol.js';
+import { EmbMessage, ClientVerifyInfo } from './types.js';
+
+export class LinkClient extends EventEmitter {
+  private socket: net.Socket | null = null;
+  private buffer: Buffer = Buffer.alloc(0);
+  private heartbeatInterval: NodeJS.Timeout | null = null;
+  private reconnectTimeout: NodeJS.Timeout | null = null;
+  private isConnected = false;
+  
+  constructor(
+    public readonly config: {
+      host: string;
+      port: number;
+      accessToken: string;
+      verifyInfo?: Partial<ClientVerifyInfo>;
+      heartbeatIntervalMs?: number;
+    }
+  ) {
+    super();
+  }
+
+  public connect() {
+    if (this.socket) {
+      this.socket.destroy();
+    }
+
+    this.socket = new net.Socket();
+    
+    this.socket.on('connect', () => {
+      console.log('LinkClient connected');
+      this.isConnected = true;
+      this.sendVerify();
+      this.startHeartbeat();
+      this.emit('connected');
+    });
+
+    this.socket.on('data', (data) => {
+      this.buffer = Buffer.concat([this.buffer, data]);
+      this.processBuffer();
+    });
+
+    this.socket.on('close', () => {
+      console.log('LinkClient disconnected');
+      this.isConnected = false;
+      this.stopHeartbeat();
+      this.emit('disconnected');
+      this.scheduleReconnect();
+    });
+
+    this.socket.on('error', (err) => {
+      console.error('LinkClient error:', err);
+      this.emit('error', err);
+    });
+
+    this.socket.connect(this.config.port, this.config.host);
+  }
+
+  public disconnect() {
+    this.stopHeartbeat();
+    if (this.reconnectTimeout) {
+      clearTimeout(this.reconnectTimeout);
+    }
+    if (this.socket) {
+      this.socket.destroy();
+      this.socket = null;
+    }
+  }
+
+  public sendMessage(msg: EmbMessage) {
+    if (!this.isConnected || !this.socket) {
+      throw new Error('Client not connected');
+    }
+    // Encode message body
+    const body = encodeMessage(msg);
+    // Encode packet
+    const packet = encodePacket(CmdCodes.SEND_MSG, body);
+    this.socket.write(packet);
+  }
+
+  private sendVerify() {
+    // Derive userId from accessToken (JWT sub claim)
+    const tokenParts = this.config.accessToken.split('.');
+    let userId = 'unknown';
+    if (tokenParts.length === 3) {
+      try {
+        const payload = JSON.parse(Buffer.from(tokenParts[1], 'base64').toString());
+        userId = payload.sub || payload.user_id || 'unknown';
+      } catch (e) {
+        console.error('Failed to parse accessToken for userId', e);
+      }
+    }
+
+    // Generate stable deviceUID based on machine info if not provided
+    // Use a hash of hostname + user info + mac address (if available) to ensure stability on the same machine
+    let deviceUID = this.config.verifyInfo?.deviceUID;
+    if (!deviceUID) {
+      try {
+        const interfaces = os.networkInterfaces();
+        let mac = '';
+        for (const key in interfaces) {
+           const iface = interfaces[key];
+           if (iface) {
+             const macEntry = iface.find(i => i.mac && i.mac !== '00:00:00:00:00:00' && !i.internal);
+             if (macEntry) {
+               mac = macEntry.mac;
+               break;
+             }
+           }
+        }
+        const machineId = `${os.hostname()}-${os.platform()}-${os.arch()}-${mac || 'nomac'}`;
+        // Use MD5 or SHA256 to keep it short and clean
+        deviceUID = crypto.createHash('md5').update(machineId).digest('hex');
+      } catch (e) {
+        // Fallback
+        deviceUID = `openclaw-link-${userId}`;
+      }
+    }
+
+    const info = {
+        userId: userId,
+        deviceUID: deviceUID!, // deviceUID is definitely assigned
+        deviceName: 'OpenClawBot',
+        deviceToken: 'openclaw-device-token', 
+        accessToken: this.config.accessToken,
+        version: '1.0.0',
+        force: true,
+        // protocolVersion: 3.0,
+        isFirstLogin: false,
+        secret: '',
+        ...this.config.verifyInfo // Allow override
+      };
+
+    // Update config with derived values for reference (e.g. sender checks)
+    // We need to cast or update the type definition if we want to store it back cleanly, 
+    // but for now let's just use local `info` object for the verify packet.
+    // Also need to make sure `this.config.verifyInfo` is updated so `bot.ts` can use it for `userId` check.
+    if (!this.config.verifyInfo) {
+       this.config.verifyInfo = {};
+    }
+    this.config.verifyInfo.userId = info.userId;
+    this.config.verifyInfo.deviceUID = info.deviceUID;
+
+    // Construct verify body JSON
+    const body = JSON.stringify({
+      UserId: info.userId,
+      DeviceUID: info.deviceUID,
+      DeviceName: info.deviceName,
+      DeviceToken: info.deviceToken,
+      AccessToken: info.accessToken,
+      Version: info.version,
+      Force: info.force,
+      protocolVersion: info.protocolVersion,
+      isFirstLogin: info.isFirstLogin,
+      secret: info.secret
+    });
+    
+    const packet = encodePacket(CmdCodes.CLIENT_VERIFY_UP, body);
+    if (this.socket) this.socket.write(packet);
+  }
+
+  private startHeartbeat() {
+    this.stopHeartbeat();
+    this.heartbeatInterval = setInterval(() => {
+      if (this.socket && this.isConnected) {
+        const packet = encodePacket(CmdCodes.HEART_BEAT_UP);
+        this.socket.write(packet);
+      }
+    }, this.config.heartbeatIntervalMs || 30000);
+  }
+
+  private stopHeartbeat() {
+    if (this.heartbeatInterval) {
+      clearInterval(this.heartbeatInterval);
+      this.heartbeatInterval = null;
+    }
+  }
+
+  private scheduleReconnect() {
+    if (this.reconnectTimeout) return;
+    this.reconnectTimeout = setTimeout(() => {
+      this.reconnectTimeout = null;
+      console.log('Reconnecting...');
+      this.connect();
+    }, 5000);
+  }
+
+  private processBuffer() {
+    while (this.buffer.length > 0) {
+      try {
+        // Try to decode one packet
+        // We need to peek header first
+        if (this.buffer.length < 4) return; // Wait for more data
+        
+        // decodePacket throws if incomplete body, but we need to handle that gracefully
+        // The decodePacket implementation I wrote throws "Incomplete body" which is not ideal for stream processing
+        // Let's modify decodePacket or handle it here. 
+        // Better: implement a peek function or modify decodePacket to return null if incomplete.
+        // For now, I'll rely on the length check I added in decodePacket:
+        // if (buffer.length < 8 + bodyLen) throw ...
+        
+        // Wait, if it throws "Incomplete body", I should catch it and return.
+        // But "ProtocolError" might mean malformed too.
+        // I should probably improve decodePacket to differentiate "Need more data" vs "Invalid data".
+        
+        // Let's do a manual check here to be safe and efficient
+        const bodyCount = this.buffer[3];
+        let requiredLen = 4;
+        if (bodyCount === 1) {
+            if (this.buffer.length < 8) return; // Need length bytes
+            const bodyLen = this.buffer.readUInt32BE(4);
+            requiredLen = 8 + bodyLen;
+        }
+        
+        if (this.buffer.length < requiredLen) return; // Wait for more data
+
+        // Now we have a full packet
+        const packetData = this.buffer.subarray(0, requiredLen);
+        const { cmdCode, body } = decodePacket(packetData); // This shouldn't throw "Incomplete" now
+        
+        // Advance buffer
+        this.buffer = this.buffer.subarray(requiredLen);
+
+        this.handleCommand(cmdCode, body);
+
+      } catch (err) {
+        if (err instanceof ProtocolError) {
+             // If it's truly a protocol error (e.g. invalid header), we might need to close connection or skip byte?
+             // For simplicity, let's log and maybe close.
+             console.error('Protocol error:', err);
+             this.socket?.destroy();
+             return;
+        }
+        throw err;
+      }
+    }
+  }
+
+  private handleCommand(cmdCode: number, body?: string) {
+    switch (cmdCode) {
+      case CmdCodes.HEART_BEAT_DOWN:
+        // Heartbeat ack, ignore or reset timer
+        break;
+      case CmdCodes.SEND_MSG:
+        if (body) {
+          try {
+            const msg = decodeMessage(body);
+            this.emit('message', msg);
+          } catch (e) {
+            console.error('Failed to decode message:', e);
+            console.error('Raw body:', body);
+          }
+        }
+        break;
+      case CmdCodes.CLIENT_VERIFY_DOWN:
+        console.log('Client verify success');
+        break;
+      case CmdCodes.ERROR_UP:
+        console.error('Link server returned error:', body);
+        break;
+      case CmdCodes.OFFLINE_UNEND_DOWN:
+      case CmdCodes.OFFLINE_END_DOWN:
+      case CmdCodes.SINGLE_DEVICE_DOWN:
+      case CmdCodes.REFRESH_TOKEN_DOWN:
+      case CmdCodes.SLEEP_DOWN:
+      case CmdCodes.SEND_MSG_RECEIPT:
+      case CmdCodes.REC_READ_DOWN:
+        // Ignore for now or log
+        // console.log(`Received cmd: 0x${cmdCode.toString(16)}, body: ${body}`);
+        break;
+      default:
+         console.log(`Received unknown cmd: 0x${cmdCode.toString(16)}, body: ${body}`);
+    }
+  }
+}

package/src/link/constants.ts

@@ -0,0 +1,42 @@
+export const CmdCodes = {
+  HEART_BEAT_UP: 0x6,
+  HEART_BEAT_DOWN: 0x10,
+  CLIENT_VERIFY_UP: 0xB,
+  CLIENT_VERIFY_DOWN: 0xC8,
+  SINGLE_DEVICE_DOWN: 0xC9,
+  REFRESH_TOKEN_DOWN: 0x63,
+  SLEEP_DOWN: 0x64,
+  SEND_MSG: 0x3,
+  SEND_MSG_RECEIPT: 0xD,
+  ERROR_UP: 0x62,
+  
+  REC_READ_UP: 0xE,
+  REC_READ_DOWN: 0x13,
+  OFFLINE_UNEND_DOWN: 0x65,
+  OFFLINE_GET_UP: 0x66,
+  OFFLINE_END_DOWN: 0x61,
+  SERVICE_UP: 0xF,
+  SERVICE_TOKEN_UP: 0x10,
+  SERVICE_TOKEN_DOWN: 0x11,
+  CLEAR_DEVICE_OFFMSG: 0x14,
+} as const;
+
+export enum MsgType {
+  TEXT = 1,
+  IMAGE = 2,
+  AUDIO = 3,
+  VIDEO = 4,
+  FILE = 5,
+  LOCATION = 6,
+  CMD = 7,
+  LINK = 8,
+  CONTACT = 9,
+  // ...
+}
+
+export enum ParticipantType {
+  USER = 1,
+  GROUP = 2,
+  SYSTEM = 3,
+  // ...
+}

package/src/link/protocol.ts

@@ -0,0 +1,295 @@
+import { Buffer } from 'buffer';
+import { CmdCodes } from './constants.js';
+import { EmbMessage, EmbCommand } from './types.js';
+
+const HEAD = 0x5;
+const OPT = 0x0;
+
+export class ProtocolError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ProtocolError';
+  }
+}
+
+// Simple encryption from Java client: ~byte then Base64
+export function encryptContent(raw: string): string {
+  if (!raw) return raw;
+  const buffer = Buffer.from(raw, 'utf-8');
+  for (let i = 0; i < buffer.length; i++) {
+    buffer[i] = ~buffer[i];
+  }
+  return buffer.toString('base64');
+}
+
+export function decryptContent(encoded: string): string {
+  if (!encoded) return encoded;
+  const buffer = Buffer.from(encoded, 'base64');
+  for (let i = 0; i < buffer.length; i++) {
+    buffer[i] = ~buffer[i];
+  }
+  return buffer.toString('utf-8');
+}
+
+export function encodePacket(cmdCode: number, body?: string): Buffer {
+  const header = Buffer.alloc(4);
+  header[0] = HEAD;
+  header[1] = cmdCode;
+  header[2] = OPT;
+  
+  if (!body) {
+    header[3] = 0;
+    return header;
+  }
+
+  header[3] = 1; // Body count = 1
+  const bodyBuffer = Buffer.from(body, 'utf-8');
+  const lenBuffer = Buffer.alloc(4);
+  lenBuffer.writeUInt32BE(bodyBuffer.length, 0);
+  
+  return Buffer.concat([header, lenBuffer, bodyBuffer]);
+}
+
+export function decodePacket(buffer: Buffer): { cmdCode: number; body?: string; consumed: number } {
+  if (buffer.length < 4) {
+    throw new ProtocolError('Incomplete header');
+  }
+
+  if (buffer[0] !== HEAD) {
+    throw new ProtocolError(`Invalid header: ${buffer[0]}`);
+  }
+
+  const cmdCode = buffer[1];
+  // const opt = buffer[2];
+  const bodyCount = buffer[3];
+
+  if (bodyCount === 0) {
+    return { cmdCode, consumed: 4 };
+  }
+
+  if (bodyCount === 1) {
+    if (buffer.length < 8) { // 4 header + 4 length
+      throw new ProtocolError('Incomplete body length');
+    }
+    const bodyLen = buffer.readUInt32BE(4);
+    if (buffer.length < 8 + bodyLen) {
+      throw new ProtocolError('Incomplete body');
+    }
+    const body = buffer.toString('utf-8', 8, 8 + bodyLen);
+    return { cmdCode, body, consumed: 8 + bodyLen };
+  }
+
+  throw new ProtocolError(`Unsupported body count: ${bodyCount}`);
+}
+
+export function encodeMessage(msg: EmbMessage): string {
+  // Map fields to JSON keys as per Java implementation
+  const json = {
+    msg_id: msg.id,
+    msg_type: msg.type,
+    content: msg.sign ? msg.content : encryptContent(msg.content),
+    from_type: msg.fromType,
+    from_id: msg.fromId,
+    from_name: msg.fromName,
+    from_company: msg.fromCompany,
+    to_type: msg.toType,
+    to_id: msg.toId,
+    to_name: msg.toName,
+    to_company: msg.toCompany,
+    send_time: msg.sendTime,
+    is_read: msg.read ? 1 : 0,
+    sign: msg.sign
+  };
+  return JSON.stringify(json);
+}
+
+export function decodeMessage(jsonStr: string): EmbMessage {
+  // Try to fix malformed JSON if it has leading garbage
+  let cleanJsonStr = jsonStr;
+  
+  // Find first '{'
+  const braceIndex = jsonStr.indexOf('{');
+  if (braceIndex >= 0) {
+     cleanJsonStr = jsonStr.substring(braceIndex);
+  } else {
+     // No JSON object start found?
+     throw new Error("No JSON object found in message body");
+  }
+
+  // Find last '}' to handle trailing garbage if any
+  const lastBraceIndex = cleanJsonStr.lastIndexOf('}');
+  if (lastBraceIndex >= 0 && lastBraceIndex < cleanJsonStr.length - 1) {
+    cleanJsonStr = cleanJsonStr.substring(0, lastBraceIndex + 1);
+  }
+
+  // Attempt to remove non-JSON prefix if '{' check wasn't enough (e.g. if body starts with garbage but contains {)
+  // The logs show bodies starting with $UUID... then JSON content?
+  // Actually the logs show: $UUID... and then some binary/garbage? Or maybe the body IS just that string?
+  // Wait, the logs show: "$c8b8dca6-..." ... is not valid JSON
+  // And Raw Body: $c8b8dca6-... followed by some binary chars.
+  
+  // It seems the body received is NOT JSON.
+  // The Java code suggests:
+  // protected EmbMessage decode(JsonObject json) { ... }
+  // And TcpProtocolV2.java:
+  // public EmbCommand decodeCommandWithBody(byte[] body) {
+  //    if(bodyCount == 1) {
+  //        EmbCommandWithBody cmd = newInstance();
+  //        cmd.setCmdBody(Strings.newStringUtf8(body));
+  //        return cmd;
+  //    }
+  // }
+  
+  // However, `SendMessage` (Cmd 0x3) is `EmbCommandWithMsgBase`.
+  // Wait, `SendMessage` extends `EmbCommandWithMsgBase`.
+  // `EmbCommandWithMsgBase` implements `EmbCommandWithMsg`.
+  // `EmbCommandWithMsg` extends `EmbCommandWithBody`.
+  
+  // The `TcpProtocolV2` decodes the body as a UTF-8 string.
+  // Then `MessageProtocol` decodes that string into an `EmbMessage`.
+  // `MessageProtocolV3.decode(JsonObject json)` expects a JSON object.
+  
+  // BUT the logs show the body content starting with a UUID (maybe msgId?) and NOT a JSON object.
+  // Example: $c8b8dca6-a423-48e1-8c15-911eebc316b0c...
+  
+  // Is it possible the server is sending V2 protocol or a different format?
+  // Or maybe the body is encrypted?
+  // `MessageProtocolV2` has `encrypt`/`decrypt`.
+  // But `decode` calls `JsonObject.parse(body)`.
+  
+  // Let's look closely at the Java code again.
+  // TcpProtocolV2:
+  //   byte[] body = ...
+  //   cmd.setCmdBody(Strings.newStringUtf8(body));
+  
+  // If the server sends `SEND_MSG` (0x3), the client receives it.
+  // The body SHOULD be a JSON string representing the message.
+  
+  // Why does the log show `$UUID...`?
+  // Maybe the `TcpProtocolV2` logic for parsing the packet is slightly off?
+  // Packet structure:
+  // HEAD(1) + CMD(1) + OPT(1) + BODY_COUNT(1)
+  // If BODY_COUNT=1: + LENGTH(4) + BODY(LENGTH)
+  
+  // My implementation:
+  // header[0] = HEAD;
+  // header[1] = cmdCode;
+  // header[3] = bodyCount;
+  // ...
+  // const bodyLen = buffer.readUInt32BE(4);
+  
+  // Let's verify if I am reading the length correctly.
+  // If I read length wrong, I might be reading into the next packet or reading garbage.
+  
+  // In the logs:
+  // Raw body: $c8b8dca6-a423-48e1-8c15-911eebc316b0c...
+  // This looks like a UUID.
+  // Maybe the body IS just a UUID? But SEND_MSG expects a full message.
+  
+  // Is it possible that `0x3` (SEND_MSG) from server to client has a different format?
+  // `SendMessage` class:
+  // public byte getCmdCode() { return CmdCodes.SEND_MSG; }
+  
+  // Wait, `SendMessage` is typically Client -> Server.
+  // Server -> Client message push is also `SEND_MSG`?
+  // Java client `TcpClient` handles received messages.
+  // It decodes the command.
+  
+  // If the server is sending `SEND_MSG`, it should contain the message.
+  // The logs show what looks like a message ID (UUID).
+  
+  // Maybe the packet has multiple bodies?
+  // My code throws "Unsupported body count" if != 0 or 1.
+  // It didn't throw that. So bodyCount is 1.
+  
+  // Maybe the length includes something else?
+  // `TcpProtocolV2`: `Bytes.bytes4ToInt(bytesLen)` (Big Endian usually).
+  
+  // Let's try to parse the body as if it might be encrypted or formatted differently?
+  // Or maybe I should log the hex of the body to see what's going on.
+  
+  // If I look at the "Raw body" output again:
+  // $c8b8dca6-a423-48e1-8c15-911eebc316b0c...
+  // It starts with `$`.
+  // A UUID is 36 chars.
+  // The log shows more chars after it.
+  // It looks like `UUID` + `Content`?
+  
+  // Wait! In Java `MessageProtocolV2`:
+  // encode: writes JSON.
+  // decode: parses JSON.
+  
+  // Is it possible the server is using a custom serialization that is NOT JSON?
+  // Or maybe I am connecting to a server version that uses a different protocol?
+  
+  // Let's relax the JSON requirement and return a raw message if JSON fails, just to see what happens.
+  
+  try {
+    const json = JSON.parse(cleanJsonStr);
+    const sign = json.sign;
+    const content = sign ? json.content : decryptContent(json.content);
+    
+    return {
+      id: json.msg_id,
+      type: json.msg_type,
+      content: content,
+      fromType: json.from_type,
+      fromId: json.from_id,
+      fromName: json.from_name,
+      fromCompany: json.from_company,
+      toType: json.to_type,
+      toId: json.to_id,
+      toName: json.to_name,
+      toCompany: json.to_company,
+      sendTime: json.send_time,
+      read: json.is_read === 1,
+      sign: sign
+    };
+  } catch (e) {
+    // If parsing fails, use regex to extract key fields as a fallback
+    // The raw body seems to have format: $UUID...{JSON content}...binary?
+    // Or maybe: $UUID...JSON...
+    
+    // Let's try to extract JSON-like structure using regex if standard parsing fails
+    // This is risky but might work for the mixed content we are seeing
+    const jsonMatch = jsonStr.match(/(\{.*\})/s);
+    if (jsonMatch) {
+       try {
+         const json = JSON.parse(jsonMatch[1]);
+         const sign = json.sign;
+         const content = sign ? json.content : decryptContent(json.content);
+         return {
+            id: json.msg_id,
+            type: json.msg_type,
+            content: content,
+            fromType: json.from_type,
+            fromId: json.from_id,
+            fromName: json.from_name,
+            fromCompany: json.from_company,
+            toType: json.to_type,
+            toId: json.to_id,
+            toName: json.to_name,
+            toCompany: json.to_company,
+            sendTime: json.send_time,
+            read: json.is_read === 1,
+            sign: sign
+         };
+       } catch (innerE) {
+         // ignore
+       }
+    }
+
+    // Fallback: return raw content for debugging
+    return {
+      id: 'unknown',
+      type: 1, // TEXT
+      content: jsonStr, // Return original string
+      fromType: 1,
+      fromId: 'unknown',
+      toType: 1,
+      toId: 'unknown',
+      sendTime: Date.now(),
+      read: false
+    };
+  }
+}

package/src/link/types.ts

@@ -0,0 +1,36 @@
+import { MsgType, ParticipantType } from './constants.js';
+
+export interface EmbMessage {
+  id: string;
+  type: MsgType;
+  content: string; // Encrypted or plain? Java code suggests encryption.
+  fromType: ParticipantType;
+  fromId: string;
+  fromName?: string;
+  fromCompany?: string;
+  toType: ParticipantType;
+  toId: string;
+  toName?: string;
+  toCompany?: string;
+  sendTime: number;
+  read: boolean;
+  sign?: string;
+}
+
+export interface ClientVerifyInfo {
+  userId: string;
+  deviceUID: string;
+  deviceName: string;
+  deviceToken: string;
+  accessToken: string;
+  version: string;
+  force: boolean;
+  protocolVersion: number;
+  isFirstLogin: boolean;
+  secret?: string;
+}
+
+export interface EmbCommand {
+  cmdCode: number;
+  body?: string; // JSON string
+}

package/src/onboarding.ts

@@ -0,0 +1,99 @@
+import type {
+  ChannelOnboardingAdapter,
+  ClawdbotConfig,
+  WizardPrompter,
+} from "openclaw/plugin-sdk";
+import type { LinkConfig } from "./types.js";
+
+const channel = "link" as const;
+
+function getLinkConfig(cfg: ClawdbotConfig): LinkConfig | undefined {
+  return cfg.channels?.link as LinkConfig | undefined;
+}
+
+export const linkOnboardingAdapter: ChannelOnboardingAdapter = {
+  channel,
+  getStatus: async ({ cfg }) => {
+    const linkCfg = getLinkConfig(cfg);
+    const configured = Boolean(
+      linkCfg?.host && linkCfg?.port && linkCfg?.accessToken
+    );
+
+    const statusLines: string[] = [];
+    if (!configured) {
+      statusLines.push("Link: needs host, port, and accessToken");
+    } else {
+      statusLines.push(`Link: configured (host: ${linkCfg?.host})`);
+    }
+
+    return {
+      channel,
+      configured,
+      statusLines,
+      selectionHint: configured ? "configured" : "needs config",
+      quickstartScore: configured ? 2 : 0,
+    };
+  },
+
+  configure: async ({ cfg, prompter }) => {
+    let next = cfg;
+    const linkCfg = getLinkConfig(next) || {} as LinkConfig;
+
+    const host = await prompter.text({
+      message: "Link Server Host",
+      initialValue: linkCfg.host,
+      placeholder: "e.g. embtcpbeta.bingolink.biz",
+      validate: (value) => (value?.trim() ? undefined : "Required"),
+    });
+
+    const portStr = await prompter.text({
+      message: "Link Server Port",
+      initialValue: linkCfg.port ? String(linkCfg.port) : undefined,
+      placeholder: "e.g. 20081",
+      validate: (value) => {
+        if (!value?.trim()) return "Required";
+        const n = Number(value);
+        if (isNaN(n) || n <= 0) return "Must be a positive number";
+        return undefined;
+      },
+    });
+    const port = Number(portStr);
+
+    const accessToken = await prompter.text({
+      message: "User Access Token",
+      initialValue: linkCfg.accessToken,
+      validate: (value) => (value?.trim() ? undefined : "Required"),
+    });
+
+    const newLinkConfig: LinkConfig = {
+      ...linkCfg,
+      host: String(host).trim(),
+      port,
+      accessToken: String(accessToken).trim(),
+    };
+
+    next = {
+      ...next,
+      channels: {
+        ...next.channels,
+        link: newLinkConfig,
+      },
+    };
+
+    return { cfg: next };
+  },
+
+  disable: (cfg) => {
+    // To disable, we might just remove the config or set a disabled flag if supported.
+    // Since LinkConfig doesn't have an 'enabled' flag in the type definition yet,
+    // we can just return the config as is or remove the link section.
+    // However, usually 'enabled' is checked at the framework level or added to the config.
+    // For now, let's just return the config.
+    // Better yet, let's remove the link config to effectively disable it since we don't have an enabled flag.
+    const { link, ...otherChannels } = cfg.channels || {};
+    return {
+      ...cfg,
+      channels: otherChannels,
+    };
+  },
+};

package/src/reply-dispatcher.ts

@@ -0,0 +1,60 @@
+import {
+  type ClawdbotConfig,
+  type ReplyPayload,
+  type RuntimeEnv,
+} from "openclaw/plugin-sdk";
+import { sendMessageLink } from "./send.js";
+import { getLinkRuntime } from "./runtime.js";
+import { LinkConfig } from "./types.js";
+
+export type CreateLinkReplyDispatcherParams = {
+  cfg: ClawdbotConfig;
+  agentId: string;
+  runtime: RuntimeEnv;
+  chatId: string;
+  replyToMessageId?: string;
+  accountId?: string;
+  linkConfig: LinkConfig;
+};
+
+export function createLinkReplyDispatcher(params: CreateLinkReplyDispatcherParams) {
+  const core = getLinkRuntime();
+  const { cfg, agentId, chatId, accountId, linkConfig } = params;
+
+  const { dispatcher, replyOptions, markDispatchIdle } =
+    (core.channel.reply as any).createReplyDispatcherWithTyping({
+      onReplyStart: () => {},
+      deliver: async (payload: ReplyPayload, info: any) => {
+        const text = payload.text ?? "";
+        if (!text.trim()) {
+          return;
+        }
+
+        try {
+          await sendMessageLink({
+            to: chatId,
+            text,
+            accountId,
+            cfg: linkConfig
+          });
+        } catch (error) {
+          params.runtime.error?.(
+            `link[${accountId}] ${info?.kind} reply failed: ${String(error)}`,
+          );
+        }
+      },
+      onError: async (error: any, info: any) => {
+        params.runtime.error?.(
+          `link[${accountId}] ${info.kind} reply failed: ${String(error)}`,
+        );
+      },
+      onIdle: async () => {},
+      onCleanup: () => {},
+    });
+
+  return {
+    dispatcher,
+    replyOptions,
+    markDispatchIdle,
+  };
+}

package/src/runtime.ts

@@ -0,0 +1,14 @@
+import type { PluginRuntime } from "openclaw/plugin-sdk";
+
+let runtime: PluginRuntime | null = null;
+
+export function setLinkRuntime(next: PluginRuntime) {
+  runtime = next;
+}
+
+export function getLinkRuntime(): PluginRuntime {
+  if (!runtime) {
+    throw new Error("Link runtime not initialized");
+  }
+  return runtime;
+}

package/src/send.ts

@@ -0,0 +1,43 @@
+import { randomUUID } from 'node:crypto';
+import { getLinkClient } from "./client-manager.js";
+import { CmdCodes, MsgType, ParticipantType } from "./link/constants.js";
+import { EmbMessage } from "./link/types.js";
+import { LinkConfig } from "./types.js";
+
+export async function sendMessageLink(params: {
+  to: string;
+  text: string;
+  accountId?: string;
+  cfg: LinkConfig; // Might need config for some context
+}): Promise<void> {
+  const accountId = params.accountId || "default";
+  const client = getLinkClient(accountId);
+  
+  if (!client) {
+    throw new Error(`Link client not found for account ${accountId}`);
+  }
+
+  // SECURITY: Only allow sending messages to self
+  // Note: verifyInfo.userId is populated in client.ts
+  const allowedUserId = client.config.verifyInfo?.userId;
+  if (!allowedUserId || params.to !== allowedUserId) {
+    // console.warn(`Link: Blocked outgoing message to ${params.to}. Only self-messages are allowed.`);
+    // Silently fail or throw? Throwing might cause retries or errors in logs.
+    // Let's throw for now to make it explicit.
+    throw new Error(`Link: Sending messages to others (${params.to}) is restricted. Only self-messages allowed.`);
+  }
+
+  const msg: EmbMessage = {
+    id: randomUUID(),
+    type: MsgType.TEXT,
+    content: params.text,
+    fromType: ParticipantType.USER, // Or SYSTEM? Using USER for bot acting as user
+    fromId: allowedUserId,
+    toType: ParticipantType.USER,  
+    toId: params.to,
+    sendTime: Date.now(),
+    read: false
+  };
+
+  client.sendMessage(msg);
+}

package/src/types.ts

@@ -0,0 +1,16 @@
+import type { ClawdbotConfig } from "openclaw/plugin-sdk";
+import { ClientVerifyInfo } from "./link/types.js";
+
+export interface LinkConfig {
+  host: string;
+  port: number;
+  accessToken: string;
+  verifyInfo?: Partial<ClientVerifyInfo>;
+  heartbeatIntervalMs?: number;
+  protocol?: "tcp" | "ws"; // Default tcp
+}
+
+export interface LinkAccountConfig {
+  accountId?: string;
+  config: LinkConfig;
+}