# ws-channel-plugin

**Repository Path**: jfld/ws-channel-plugin

## Basic Information

- **Project Name**: ws-channel-plugin
- **Description**: 浮浮沉沉吃醋烦烦烦烦烦烦烦烦烦
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-22
- **Last Updated**: 2026-03-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# WebSocket Channel Plugin

通过 WebSocket 连接外部服务的 OpenClaw Channel 插件。

## 功能

- ✅ 连接到外部 WebSocket 服务器
- ✅ 通过 WebSocket 接收入站消息
- ✅ 通过 WebSocket 发送回复和执行过程事件
- ✅ 通过 WebSocket 发送 Outbound 消息（cron/heartbeat）
- ✅ 自动重连（指数退避）
- ✅ 消息队列（断线时缓存消息）

## 安装

```bash
# 1. 解压
unzip ws-channel.zip && cd ws-channel

# 2. 安装依赖并编译
npm install && npm run build

# 3. 安装到 OpenClaw
openclaw plugins install .

# 4. 重启
openclaw gateway restart
```

## 配置

在 `openclaw.json` 中添加：

```json
{
  "channels": {
    "ws-channel": {
      "enabled": true,
      "wsUrl": "ws://your-server/v1/stream",
      "apiKey": "your-api-key",
      "useTls": false,
      "reconnect": {
        "enabled": true,
        "maxAttempts": 10,
        "baseDelayMs": 1000,
        "maxDelayMs": 30000
      },
      "events": {
        "sendToolProgress": true,
        "sendStreamProgress": false,
        "sendReasoningProgress": false
      }
    }
  }
}
```

### 配置说明

| 字段 | 说明 | 默认值 |
|------|------|--------|
| `wsUrl` | WebSocket 服务器地址 | 必填 |
| `apiKey` | API 密钥（用于认证） | - |
| `useTls` | 是否使用 wss:// | false |
| `reconnect.enabled` | 启用自动重连 | true |
| `reconnect.maxAttempts` | 最大重连次数 | 10 |
| `reconnect.baseDelayMs` | 重连基础延迟 | 1000 |
| `reconnect.maxDelayMs` | 重连最大延迟 | 30000 |
| `events.sendToolProgress` | 发送工具事件 | true |
| `events.sendStreamProgress` | 发送流式事件 | false |
| `events.sendReasoningProgress` | 发送推理事件 | false |

## 消息协议

### 入站消息（外部 → OpenClaw）

```json
{
  "type": "message",
  "data": {
    "id": "msg_001",
    "userId": "user_123",
    "conversationId": "conv_456",
    "text": "你好",
    "userName": "张三"
  }
}
```

### 出站消息 - 回复

```json
{
  "type": "message",
  "data": {
    "text": "你好！有什么可以帮你的？",
    "recipientId": "user_123",
    "conversationId": "conv_456",
    "replyToId": "msg_001",
    "timestamp": 1710000000000
  }
}
```

### 出站消息 - 执行过程

```json
{
  "type": "process",
  "data": {
    "eventType": "tool_start",
    "eventData": { "name": "exec", "phase": "start" },
    "recipientId": "user_123",
    "conversationId": "conv_456",
    "messageId": "msg_001",
    "timestamp": 1710000000000
  }
}
```

### 出站消息 - 主动推送

```json
{
  "type": "outbound",
  "data": {
    "text": "定时任务消息",
    "recipientId": "user_123",
    "conversationId": "default",
    "source": "cron",
    "timestamp": 1710000000000
  }
}
```

### 事件类型

- `model_selected` - 模型选定
- `tool_start` - 工具开始
- `tool_result` - 工具结果
- `partial_reply` - 流式输出
- `block_reply` - 块输出
- `reasoning_stream` - 推理过程
- `reasoning_end` - 推理结束
- `assistant_message_start` - 新消息开始
- `final_reply` - 最终回复
- `error` - 错误

## 测试

### 模拟 WebSocket 服务器

```javascript
// test-server.js
const WebSocket = require("ws");
const wss = new WebSocket.Server({ port: 8080 });

wss.on("connection", (ws) => {
  console.log("客户端已连接");

  ws.on("message", (data) => {
    console.log("收到:", JSON.parse(data.toString()));
  });

  // 发送测试消息
  setTimeout(() => {
    ws.send(JSON.stringify({
      type: "message",
      data: {
        id: "test_001",
        userId: "user_123",
        conversationId: "conv_456",
        text: "你好",
      },
    }));
  }, 1000);
});

console.log("WebSocket 服务器运行在 ws://localhost:8080");
```

运行测试：

```bash
node test-server.js
```

## 文档

- 设计文档: https://feishu.cn/docx/Y8LHdjT1zozIsdxDSdpctIqrnTb
- Channel 开发指南: https://feishu.cn/docx/JpCkdsLqiowL6mx50w3cR2xznpe