npm package: @luxuelin/openclaw-tai-channel
Description: TAI智能体通道 - 连接AS-Gateway
Author: luxuelin
Latest version: 1.0.0

# @luxuelin/openclaw-tai-channel

OpenClaw 的 TAI 智能体通道插件，用于连接 AS-Gateway。

## 功能特性

- ✅ 支持 AS-Gateway WebSocket 连接
- ✅ 协议双向转换（AS ↔ OpenClaw）
- ✅ 流式数据处理与智能聚合
- ✅ 自动心跳和重连机制
- ✅ 符合 AS 协议规范

## 安装方式

### 方式 1: npm 安装（推荐）

从 GitHub 克隆 OpenClaw 后，可以直接安装 TAI Channel：

```bash
# 1. 克隆 OpenClaw 项目
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 2. 安装 TAI Channel npm 包
npm install @lenovo/openclaw-tai-channel

# 3. 配置（见下方配置说明）
# 编辑 ~/.openclaw/openclaw.json

# 4. 启动 OpenClaw Gateway
npm start
```

### 方式 2: 本地开发（yalc）

```bash
# 安装 yalc
npm install -g yalc

# 在 TAI Channel 目录发布到本地
cd /path/to/openclaw-tai-channel
yalc publish

# 在 OpenClaw 项目中链接
cd /path/to/openclaw
yalc add @luxuelin/openclaw-tai-channel
```

### 方式 3: 复制扩展（开发调试）

```bash
# 复制到 OpenClaw extensions 目录
cp -r /path/to/openclaw-tai-channel /path/to/openclaw/extensions/tai

# 安装依赖并构建
cd /path/to/openclaw/extensions/tai
npm install
npm run build
```

## 配置说明

### 配置文件位置
`~/.openclaw/openclaw.json`

### 配置示例

```json
{
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "loopback"
  },
  "plugins": {
    "entries": {
      "tai": {
        "enabled": true,
        "config": {
          "as_gateway": {
            "url": "wss://as-gateway.mbgtest.lenovomm.com/rest/v1/events",
            "device_id": "openclaw-device-001",
            "heartbeat_interval": 30000
          }
        }
      }
    }
  },
  "logging": {
    "level": "debug"
  }
}
```

### 配置参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `url` | string | ✅ | AS-Gateway WebSocket URL |
| `device_id` | string | ✅ | 设备唯一标识 |
| `heartbeat_interval` | number | ❌ | 心跳间隔（毫秒），默认 30000 |

## 使用方法

### 启动 OpenClaw Gateway

```bash
# 方式 1: 使用 npm 脚本
npm start

# 方式 2: 直接运行
node openclaw.mjs gateway run

# 方式 3: 指定绑定地址
node openclaw.mjs gateway run --bind loopback
```

### 验证安装

```bash
# 检查插件状态
node openclaw.mjs plugins list | grep TAI

# 应该看到：
# │ TAI │ tai │ loaded │ stock:tai/dist/index.js │ 1.0.0 │
```

### 查看日志

```bash
# 查看 Gateway 日志
tail -f ~/.openclaw/logs/gateway.log

# 过滤 TAI 相关日志
tail -f ~/.openclaw/logs/gateway.log | grep -i tai
```

## 开发

### 项目结构

```
extensions/tai/
├── src/
│   ├── index.ts                    # 插件入口
│   ├── plugin/
│   │   └── TAIChannel.ts           # 主插件类
│   ├── client/
│   │   ├── ASGatewayClient.ts      # WebSocket 客户端
│   │   └── types.ts                # AS 协议类型定义
│   ├── adapter/
│   │   ├── ProtocolAdapter.ts      # 协议适配器
│   │   └── types.ts                # MsgContext 类型
│   ├── streaming/
│   │   └── StreamingHandler.ts     # 流式处理器
│   └── utils/
│       ├── logger.ts               # 日志工具
│       └── message-id.ts           # 消息 ID 生成
├── dist/                            # 编译输出
├── test/                            # 测试文件
├── package.json
└── tsconfig.json
```

### 构建和测试

```bash
# 安装依赖
npm install

# 构建
npm run build

# 运行测试
npm test

# 开发模式（监听文件变化）
npm run dev
```

## 运行测试

### 单元测试
```bash
npm test
```

### 集成测试
```bash
node test/integration-test.js test
```

### 测试覆盖
- WebSocket 客户端测试
- 协议转换测试
- 流式处理测试
- 工具函数测试

## 故障排除

### 问题 1: 插件未加载

**症状**: `openclaw plugins list` 中没有 TAI

**解决方案**:
1. 检查 `extensions/tai/dist/index.js` 是否存在
2. 重新构建: `cd extensions/tai && npm run build`
3. 检查配置文件中 `plugins.entries.tai.enabled` 是否为 `true`

### 问题 2: 配置验证失败

**症状**: `unknown channel id: tai`

**解决方案**:
- 确保使用 `plugins.entries.tai` 而不是 `channels.tai`
- 检查 JSON 格式是否正确

### 问题 3: WebSocket 连接失败

**症状**: 日志显示连接 AS-Gateway 失败

**解决方案**:
1. 验证 AS-Gateway URL 可访问
2. 检查网络连接
3. 确认防火墙规则

## 更多文档

- [安装指南](./INSTALL.md) - 详细的安装和配置说明
- [项目总结](./PROJECT_SUMMARY.md) - 完整的项目文档

## 许可证

MIT

---

**维护者**: luxuelin