# tai_lan_channel_plugin

**Repository Path**: dq2021/tai_lan_channel_plugin

## Basic Information

- **Project Name**: tai_lan_channel_plugin
- **Description**: tai openclaw 插件
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-01
- **Last Updated**: 2026-04-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Tai Channel Plugin

一个 OpenClaw Channel 插件，通过 WebSocket 将 Web 前端与 OpenClaw Agent 连接。

## 功能特性

- 🔌 **WebSocket 实时通信** - 双向消息推送
- 👥 **多账户支持** - 可配置多个独立账户
- 🤖 **多 Agent 绑定** - 不同账户可绑定不同 Agent
- 📊 **实时状态监控** - 推送 Agent 工作状态（思考中、执行工具、回复完成等）
- 🔄 **自动重连** - 连接断开自动恢复
- 🔐 **Token 鉴权** - 安全的后端连接

## 系统架构

```
Web 前端  ←→  Web 后端  ←→  Tai 插件  ←→  OpenClaw Agent
            WebSocket     WebSocket      OpenClaw API
```

## 快速安装

### 1. 运行安装脚本

```bash
cd scripts
node setup.mjs <app_key> <app_secret> [base_url] [websocket_url]
```

**示例：**
```bash
node setup.mjs my-app-key my-app-secret http://116.237.73.145:18891 ws://116.237.73.145:18891
```

### 2. 重启 OpenClaw

```bash
openclaw gateway restart
```

### 3. 验证状态

```bash
openclaw status
```

## 配置说明

### 最小配置

```json
{
  "channels": {
    "tai": {
      "enabled": true,
      "accounts": {
        "default": {
          "enabled": true,
          "appKey": "your-app-key",
          "appSecret": "your-app-secret",
          "baseUrl": "http://116.237.73.145:18891",
          "websocketUrl": "ws://116.237.73.145:18891"
        }
      }
    }
  },
  "bindings": [
    {
      "agentId": "main",
      "match": {
        "channel": "tai",
        "accountId": "default"
      }
    }
  ]
}
```

### 多账户配置

```json
{
"channels": {
    "tai": {
      "enabled": true,
      "accounts": {
        "your-main": {
          "enabled": true,
          "appKey": "your-app-key-main",
          "appSecret": "your-app-secret-main",
          "baseUrl": "http://116.237.73.145:18891",
          "websocketUrl": "ws://116.237.73.145:18891"
        },
        "your-reviewer": {
          "enabled": true,
          "appKey": "your-app-key-reviewer",
          "appSecret": "your-app-secret-reviewer",
          "baseUrl": "http://116.237.73.145:18891",
          "websocketUrl": "ws://116.237.73.145:18891"
        },
        "your-dev": {
          "enabled": true,
          "appKey": "your-app-key-dev",
          "appSecret": "your-app-secret-dev",
          "baseUrl": "http://your-backend:3000",
          "websocketUrl": "ws://your-backend:3000"
        }
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "your-model"
      },
      "models": {
        "your-models": {}
      },
      "workspace": "/root/.openclaw/workspace"
    },
    "list": [
      {
        "id": "main"
      },
      {
        "id": "code-reviewer",
        "name": "code-reviewer",
        "workspace": "/root/.openclaw/workspaces-code-reviewer",
        "agentDir": "/root/.openclaw/agents/code-reviewer/agent",
        "model": "ark/ark-code-latest"
      },
      {
        "id": "code-tester",
        "name": "code-tester",
        "workspace": "/root/.openclaw/workspaces-code-tester",
        "agentDir": "/root/.openclaw/agents/code-tester/agent"
      }
    ]
  },
  "bindings": [
    {
      "agentId": "main",
      "match": {
        "channel": "tai",
        "accountId": "your-main"
      }
    },
    {
      "agentId": "code-reviewer",
      "match": {
        "channel": "tai",
        "accountId": "your-reviewer"
      }
    },
    {
      "agentId": "main",
      "match": {
        "channel": "tai",
        "accountId": "your-dev"
      }
    }
  ]
}
```

**配置说明：**

| 配置项 | 说明 |
|--------|------|
| `agents.defaults` | 所有 Agent 的默认配置（模型、工作目录、超时等） |
| `agents.list` | Agent 列表，可覆盖默认配置 |
| `agents.list[].id` | Agent 唯一标识 |
| `agents.list[].workspace` | Agent 独立工作目录 |
| `agents.list[].agentDir` | Agent 自定义配置目录（可选） |
| `agents.list[].model` | 指定使用的模型（可选，覆盖默认） |
| `bindings` | 绑定规则，将账户与 Agent 关联 |
| `bindings[].match.accountId` | 匹配账户 ID |
| `bindings[].agentId` | 绑定的 Agent ID |

## 配置项说明

| 配置项 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `enabled` | boolean | 是 | 是否启用账户 |
| `appKey` | string | 是 | 应用标识符（后端鉴权） |
| `appSecret` | string | 是 | 应用密钥（后端鉴权） |
| `baseUrl` | string | 是 | 后端 HTTP 地址 |
| `websocketUrl` | string | 是 | 后端 WebSocket 地址 |

## 工作原理

### 消息流程

```
1. 用户发送消息 → Web 前端
2. Web 前端 → WebSocket → Web 后端
3. Web 后端 → WebSocket → Tai 插件
4. Tai 插件 → OpenClaw API → Agent 处理
5. Agent 回复 → Tai 插件 → WebSocket → Web 后端
6. Web 后端 → WebSocket → Web 前端显示
```

### 状态推送

插件每 3 秒扫描 Agent 会话文件，推送以下状态：

| 状态 | 说明 |
|------|------|
| `waiting` | ⏳ 等待响应 |
| `thinking` | 🤔 思考中 |
| `tool_call` | 🔧 执行工具 |
| `tool_running` | 🔄 命令运行中 |
| `success` | ✅ 执行成功 |
| `error` | ❌ 执行出错 |
| `reply_done` | 💬 回复完成 |
| `idle` | ⏸️ 空闲 |

## WebSocket 消息格式

### 入站消息（前端 → 插件）

```json
{
  "type": "message",
  "text": "用户消息",
  "from": "user_xxx",
  "to": "account-id",
  "messageId": "1700000000000",
  "chatType": "dm"
}
```

### 出站消息（插件 → 前端）

```json
{
  "type": "response",
  "payload": {
    "content": "AI 回复",
    "messageId": "1700000000000",
    "to": "user_xxx"
  }
}
```

### 状态推送（插件 → 前端）

```json
{
  "type": "session_status",
  "payload": {
    "accountId": "account-id",
    "agentId": "main",
    "isWorking": true,
    "totalSessions": 5,
    "latestSession": {
      "sessionId": "xxx",
      "status": "thinking",
      "statusText": "🤔 思考中",
      "lastMessage": {
        "role": "assistant",
        "hasThinking": true
      }
    }
  }
}
```

## 开发

### 项目结构

```
tai/
├── index.ts              # 插件入口
├── src/
│   ├── channel.ts        # Channel 实现
│   ├── websocket-client.ts  # WebSocket 客户端
│   ├── session-watcher.ts   # 会话状态监控
│   ├── types.ts          # 类型定义
│   ├── config-schema.ts  # 配置验证
│   ├── accounts.ts       # 账户管理
│   └── runtime.ts        # 运行时存储
├── scripts/
│   └── setup.mjs         # 安装脚本
├── package.json
└── tsconfig.json
```

### 构建

```bash
npm install
npm run build
```

### 开发模式

```bash
npm run dev
```

## 依赖

- **Node.js**: >= 18.0.0
- **OpenClaw**: >= 2026.3.12
- **ws**: WebSocket 客户端
- **zod**: 配置验证
- **chokidar**: 文件监听

## 日志输出

### 查看日志

```bash
# 查看所有 Tai 相关日志
openclaw logs | grep -i tai

# 实时跟踪日志
openclaw logs -f | grep -i tai
```

### 日志类型

#### 1. 账户生命周期

| 日志内容 | 说明 |
|----------|------|
| `starting tai[default]` | 账户启动 |
| `[Tai] Auth success, token: xxx...` | 鉴权成功 |
| `[Tai] WebSocket connected` | WebSocket 连接成功 |
| `[Tai] SessionWatcher started` | 会话监视器启动 |
| `[Tai] Stopping account: default` | 账户停止 |

#### 2. 消息处理

| 日志内容 | 说明 |
|----------|------|
| `[Tai] Received WebSocket message: {...}` | 收到前端消息 |
| `[Tai] Calling dispatchReplyWithBufferedBlockDispatcher...` | 开始处理消息 |
| `[Tai] deliver called! payload: {...}` | AI 回复回调触发 |
| `[Tai] AI reply: xxx` | AI 回复内容 |
| `22:30:45 [tai] >>> 推送到中央服务器: messageId=xxx...` | 消息推送成功 |

#### 3. WebSocket 连接

| 日志内容 | 说明 |
|----------|------|
| `[WebSocketClient] ✅ 连接成功` | 连接建立 |
| `[WebSocketClient] 🔌 关闭 [code=xxx]` | 连接断开 |
| `[WebSocketClient] ❌ 认证失败` | 鉴权失败 |
| `[WebSocketClient] ❌ 服务器未启动` | 后端服务不可达 |
| `[WebSocketClient] ⏳ 5秒后重连 [第3次]` | 自动重连 |

#### 4. 状态监控（每3秒，状态变化时）

```
[Tai] ====== 状态轮询 [main] ======
22:30:45 [tai] 当前: thinking | 🤔 思考中，会话: 5 | 活跃: YES
22:30:45 [tai] 原因: role=assistant, thinking=是, toolCall=否
22:30:45 [tai] >>> 推送到中央服务器: type=session_status...
[Tai] ======================================
```

**状态说明：**

| 状态 | 显示 | 含义 |
|------|------|------|
| `waiting` | ⏳ 等待响应中 | 等待 AI 回复 |
| `thinking` | 🤔 思考中 | AI 正在思考 |
| `tool_call` | 🔧 执行工具中 | 调用工具 |
| `tool_running` | 🔄 命令运行中 | 命令执行中 |
| `success` | ✅ 执行成功 | 工具执行成功 |
| `error` | ❌ 执行出错 | 工具执行失败 |
| `reply_done` | 💬 回复完成 | AI 回复已发送 |
| `idle` | ⏸️ 用户已离开 | 空闲状态 |

## 故障排查

### 连接失败

```bash
# 检查后端服务
nc -zv backend-host 3000

# 查看插件日志
openclaw logs | grep -i tai
```

### 鉴权失败

- 确认 `appKey` 和 `appSecret` 与后端配置一致
- 检查是否有空格或特殊字符

### AI 无响应

- 检查 Agent 绑定配置：`bindings`
- 检查 Agent 是否存在：`agents.list`
- 检查模型配置是否正确

### 常见问题诊断

| 现象 | 检查日志 | 解决方案 |
|------|----------|----------|
| WebSocket 连接不上 | `[WebSocketClient] ❌ 服务器未启动` | 检查后端服务是否启动 |
| 鉴权失败 | `[WebSocketClient] ❌ 认证失败` | 检查 appKey/appSecret 配置 |
| AI 不回复 | `[Tai] dispatchReplyWithBufferedBlockDispatcher error` | 检查 Agent 和模型配置 |
| 消息发不出去 | `[Tai] sendText: WebSocket not connected` | 检查网络连接和重连状态 |

## 许可证

MIT