Turms Channel for OpenClaw

Turms IM 即时通讯通道插件，用于 OpenClaw 平台。

功能特性

• 支持 Turms Gateway TCP 连接（端口 11510）
• 支持用户认证登录
• 支持私聊消息发送和接收
• 支持群聊消息发送和接收
• 自动重连机制
• 心跳保活

安装

# 安装最新版本
openclaw plugins install openclaw-channel-turms

# 安装指定版本
openclaw plugins install [email protected]

本地开发安装

cd turms-openclaw-channel
pnpm install
openclaw plugins install -l .

配置

在 ~/.openclaw/openclaw.json 中添加以下配置：

{
  "plugins": {
    "entries": {
      "turms": {
        "enabled": true,
        "config": {
          "host": "playground.turms.im",
          "port": 11510,
          "userId": 1,
          "password": "123"
        }
      }
    }
  }
}

注意：配置完成后需要重启 Gateway：openclaw gateway --force 或重启 OpenClaw 服务。

配置项说明

| 配置项 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | name | string | - | 通道显示名称 | | enabled | boolean | true | 启用/禁用通道 | | host | string | localhost | Turms Gateway 主机地址 | | port | integer | 11510 | Turms Gateway TCP 端口 | | userId | integer | - | 用户 ID（必填） | | password | string | - | 用户密码（必填） | | deviceType | integer | 1 | 设备类型：1=Android, 2=iOS, 3=PC, 4=Web | | connectTimeout | integer | 30000 | 连接超时（毫秒） | | requestTimeout | integer | 60000 | 请求超时（毫秒） | | heartbeatInterval | integer | 30000 | 心跳间隔（毫秒） | | autoReconnect | boolean | true | 自动重连 | | maxReconnectAttempts | integer | 10 | 最大重连次数 | | reconnectDelay | integer | 5000 | 重连延迟（毫秒） | | debug | boolean | false | 调试日志 |

使用示例

发送消息

# 发送私聊消息
openclaw send --channel turms --to 123 "Hello, Turms!"

# 发送群聊消息
openclaw send --channel turms --to 456 --group "Hello, group!"

目标 ID 格式

• 私聊：--to 123 或 --to turms:123
• 群聊：--to 456 --group

开发

# 安装依赖
pnpm install

# 类型检查
pnpm type-check

# 代码格式化
pnpm format

# Lint 检查
pnpm lint

架构说明

通信协议

Turms 使用 WebSocket 协议与 Gateway 通信：

1. 连接建立: WebSocket 连接到 ws://host:port
2. 用户认证: 发送 createSessionRequest 进行登录
3. 消息发送: 使用 Protobuf 编码的 TurmsRequest
4. 消息接收: 接收 Protobuf 编码的 TurmsNotification

消息格式

请求和响应使用以下格式：

• WebSocket: 正文（Protobuf 编码的 TurmsRequest/TurmsNotification）
• 纯 TCP: varint 编码的正文长度 + 正文

模块结构

turms-openclaw-channel/
├── index.ts                    # 插件入口
├── src/
│   ├── types.ts                # 类型定义
│   ├── config.ts               # 配置解析
│   ├── config-schema.ts        # Zod 配置 Schema
│   ├── turms-client.ts         # Turms TCP 客户端
│   ├── connection-manager.ts   # 连接管理器
│   ├── gateway/
│   │   └── channel-gateway.ts  # Gateway 实现
│   ├── messaging/
│   │   ├── send-service.ts     # 消息发送服务
│   │   ├── inbound-handler.ts  # 入站消息处理
│   │   └── channel-outbound.ts # Outbound 适配器
│   └── platform/
│       └── channel-status.ts   # 状态检查

故障排查

连接失败

1. 检查 host 和 port 配置是否正确
2. 确认网络可达性：telnet host port
3. 检查用户凭证是否正确

认证失败

1. 确认 userId 和 password 正确
2. 检查服务端是否启用了认证
3. 查看调试日志：设置 debug: true

消息发送失败

1. 检查目标用户 ID 是否存在
2. 确认是否有发送权限
3. 查看服务端日志

许可

Apache License 2.0

相关链接

• Turms GitHub
• Turms 文档
• OpenClaw 文档