remote-relay-test

v1.0.3

Published

22 days ago

OpenClaw Remote Relay channel plugin for remote control via WebSocket

Downloads

388

0High
0Medium
0Low

gengyixin

openclaw openclaw-plugin websocket relay remote-control ai-agent

OpenClaw Remote Relay 插件

OpenClaw 的远程控制通道插件，通过 WebSocket 中继服务器实现对内网 OpenClaw AI 智能体的远程控制。该插件使用反向隧道技术，允许通过公网控制内网中的 OpenClaw 实例。

功能特性

基于 WebSocket 的通信 - 与中继服务器进行实时双向通信
自动重连 - 处理网络中断，支持可配置的重试间隔
心跳监控 - 使用 ping/pong 自动检查连接健康状态
流式传输支持 - 高效处理 AI 响应的流式传输
灵活配置 - 支持按账户或全局配置
内存安全 - 内置限制防止待处理请求导致的内存泄漏

架构说明

HTTP 客户端（远程）
        │
        ▼
中继服务器（公网）
        │
        ▼ WebSocket 连接
OpenClaw 设备（内网）
  └── Remote Relay 插件
        └── OpenClaw AI 智能体

插件与中继服务器保持持久的 WebSocket 连接，允许外部客户端发送查询，由本地 OpenClaw 实例执行。响应通过相同的连接流式传回。

安装

作为 OpenClaw 用户

如果你正在使用 OpenClaw 并希望添加远程控制功能：

# 克隆或下载此插件到 OpenClaw 扩展目录
cd /path/to/openclaw/extensions
git clone <仓库地址> remote-relay

# 或通过 npm 安装（发布后）
npm install remote-relay-test

OpenClaw 会在启动时自动检测并加载插件。

作为插件开发者

如果你要开发或修改此插件：

# 克隆仓库
git clone <仓库地址>
cd remote-relay

# 此插件需要 OpenClaw 运行时 - 无需安装依赖
# TypeScript 类型从宿主 OpenClaw 安装中解析

配置

基础配置

在你的 OpenClaw 配置文件中添加（~/.openclaw/config.json 或 config.json）：

{
  "channels": {
    "remote-relay": {
      "service": {
        "relayUrl": "ws://your-relay-server.com:8080/api/v1/ws",
        "deviceId": "my-device-001",
        "authToken": "your-secret-token"
      },
      "accounts": {
        "default": {
          "name": "我的远程连接",
          "enabled": true,
          "config": {}
        }
      }
    }
  }
}

高级配置

按账户配置

为特定账户覆盖全局设置：

{
  "channels": {
    "remote-relay": {
      "service": {
        "relayUrl": "ws://relay.example.com:8080/api/v1/ws",
        "deviceId": "device-001",
        "authToken": "global-token"
      },
      "accounts": {
        "production": {
          "name": "生产环境",
          "enabled": true,
          "config": {
            "relayUrl": "wss://relay-prod.example.com/api/v1/ws",
            "deviceId": "prod-device-001",
            "authToken": "prod-secret-token"
          }
        },
        "development": {
          "name": "开发环境",
          "enabled": true,
          "config": {
            "relayUrl": "ws://localhost:8080/api/v1/ws",
            "deviceId": "dev-device-001",
            "authToken": "dev-token"
          }
        }
      }
    }
  }
}

简化配置

对于单账户设置，可以使用简化结构：

{
  "channels": {
    "remote-relay": {
      "accounts": {
        "default": {
          "name": "我的连接",
          "enabled": true,
          "relayUrl": "ws://relay.example.com:8080/api/v1/ws",
          "deviceId": "my-device",
          "authToken": "my-token"
        }
      }
    }
  }
}

配置选项

| 选项 | 类型 | 默认值 | 说明 | |------|------|--------|------| | relayUrl | string (URL) | ws://localhost:8080/api/v1/ws | WebSocket 中继服务器 URL | | deviceId | string | local | 唯一设备标识符 | | authToken | string | default-token-change-in-production | 中继服务器认证令牌 | | reconnectInterval | number | 5000 | 重连延迟（毫秒，1000-60000） | | pingInterval | number | 30000 | 心跳 ping 间隔（毫秒，5000-120000） |

使用方法

启动插件

插件会在 OpenClaw 加载时自动启动。查看日志了解连接状态：

[default] Starting Remote Relay connection to ws://relay.example.com:8080/api/v1/ws
[default] Connected to relay server

从远程客户端发送查询

远程客户端可以通过中继服务器的 HTTP API 发送查询。详见中继服务器文档。

使用 curl 的示例：

curl -N -X POST "http://relay.example.com:8080/api/v1/device/execute?device_id=my-device&token=your-token" \
  -H "Content-Type: application/json" \
  -d '{"query": "今天天气怎么样？"}'

插件会：

通过 WebSocket 连接接收查询
使用 OpenClaw 的 AI 智能体处理查询
通过中继服务器流式传回响应
客户端通过 SSE（服务器发送事件）接收响应

监控连接状态

使用 OpenClaw 的状态命令监控插件：

# 检查通道状态
openclaw status channels

# 检查详细状态
openclaw status --verbose

开发

前置要求

OpenClaw >= 2026.3.0
Node.js >= 22.12.0（用于 OpenClaw 运行时）
TypeScript 知识

项目结构

remote-relay/
├── index.ts              # 插件入口点
├── src/
│   ├── channel.ts        # 通道插件实现
│   ├── config-schema.ts  # Zod 配置架构
│   ├── runtime.ts        # 运行时状态管理
│   └── types.ts          # TypeScript 类型定义
├── bin/
│   └── push-message.ts   # 发送消息的测试工具
├── package.json
├── tsconfig.json
└── README.md

构建

此插件设计为在 OpenClaw 运行时直接使用 TypeScript 源文件运行。开发期间无需构建步骤。

生产/分发时：

# 如果使用构建流程
tsc

测试

使用附带的工具测试插件：

# 发送测试消息
node bin/push-message.ts --device-id my-device --token your-token --query "你好"

TypeScript 配置

插件的 TypeScript 配置专为 OpenClaw 插件开发设计：

noImplicitAny: false - 允许动态运行时场景的灵活类型
moduleResolution: "bundler" - 使用现代模块解析
skipLibCheck: true - 更快的编译

openclaw/plugin-sdk 类型在运行时由 OpenClaw 解析，因此开发期间无需将 OpenClaw 安装为依赖。

消息协议

插件使用基于 JSON 的 WebSocket 协议：

客户端 → 设备（中继 → OpenClaw）

// 查询消息
{
  "type": "query",
  "msg_id": "unique-message-id",
  "payload": {
    "query": "你的问题"
  }
}

// 取消消息
{
  "type": "cancel",
  "msg_id": "要取消的消息 ID"
}

// Pong 响应
{
  "type": "pong"
}

设备 → 客户端（OpenClaw → 中继）

// 认证消息（连接时）
{
  "type": "auth",
  "payload": {
    "deviceId": "my-device-001"
  }
}

// 响应块（流式传输）
{
  "type": "response_chunk",
  "msg_id": "原始消息 ID",
  "payload": {
    "text": "响应文本块..."
  }
}

// 响应完成
{
  "type": "response_done",
  "msg_id": "原始消息 ID",
  "payload": {
    "status": "completed" | "error",
    "message": "可选的错误消息"
  }
}

// Ping 心跳
{
  "type": "ping"
}

故障排查

连接问题

问题：插件无法连接到中继服务器

解决方案：

验证 relayUrl 是否正确且可访问
检查防火墙设置是否允许 WebSocket 连接
确保 authToken 与中继服务器配置匹配
检查中继服务器日志中的连接尝试

自动重连

问题：插件频繁断开连接

解决方案：

检查网络稳定性
如果网络延迟高，增加 pingInterval
检查中继服务器心跳超时设置
检查 NAT/代理超时问题

内存泄漏

问题：内存使用随时间增长

插件包含内置保护：

最多 100 个待处理请求（自动清理）
最多 100 个流式会话（自动清理）
重连时自动清理

如果问题仍然存在：

定期重启 OpenClaw
检查中继服务器是否导致请求堆积

TypeScript 错误

问题："找不到模块 'openclaw/plugin-sdk'"

解决方案：这在开发期间是预期的。该模块在运行时由 OpenClaw 提供。要修复 IDE 错误：

确保已安装 OpenClaw：npm install openclaw
或在导入行上方添加 // @ts-ignore
或在 tsconfig.json 中使用 paths 配置

安全注意事项

认证令牌：生产环境始终使用强且唯一的令牌
TLS/WSS：生产部署使用 wss://（WebSocket Secure）
网络隔离：中继服务器应验证所有令牌
速率限制：配置中继服务器速率限制以防止滥用
设备 ID：使用唯一且不可猜测的设备 ID

许可证

MIT License - 详见 LICENSE 文件

贡献

欢迎贡献！请：

Fork 仓库
创建功能分支
进行更改
添加测试（如适用）
提交 Pull Request

支持

问题反馈：GitHub Issues
文档：OpenClaw 文档
社区：OpenClaw Discord

更新日志

1.0.0（初始版本）

基于 WebSocket 的中继连接
指数退避的自动重连
心跳监控（ping/pong）
流式响应支持
内存泄漏保护
按账户配置
连接状态监控