Xl Remote

By 4yu 👁 7 views ▲ 0 votes

OpenClaw Gateway Remote Communication Plugin - Supports end-to-end encryption and file transfer.

GitHub

Install

npm install
pnpm

Configuration Example

{
  "type": "local_file",
  "fileId": "unique-id",
  "fileName": "report.pdf",
  "path": "/absolute/path/to/report.pdf",
  "size": 102400,
  "mime": "application/pdf"
}

README

# xl-remote

OpenClaw 远程中继客户端插件 - 将消息转发到本地 OpenClaw Gateway，支持文件传输。

## 功能

- **消息中继**: 将小程序消息通过 xl-server 转发到本地 OpenClaw Gateway
- **端到端加密**: 使用 TweetNaCl 进行端到端加密，保护通信安全
- **文件传输**: AI 在回复中包含 `local_file` 消息块时自动触发文件传输
- **自动重连**: 连接断开时自动重连
- **心跳检测**: 定期发送心跳保持连接活跃

## 文件传输

xl-remote 支持通过 AI 回复自动触发文件传输。当 AI 在回复中包含 `local_file` 类型的消息块时，会自动触发文件传输到客户端。

### 消息块格式

```json
{
  "type": "local_file",
  "fileId": "unique-id",
  "fileName": "report.pdf",
  "path": "/absolute/path/to/report.pdf",
  "size": 102400,
  "mime": "application/pdf"
}
```

### 示例

当 AI 需要向用户发送一份报告时，会在回复中添加文件块：

```json
{
  "content": [
    { "type": "text", "text": "这是您的报告" },
    { "type": "local_file", "fileId": "abc123", "fileName": "report.pdf", "path": "/home/user/report.pdf", "size": 102400, "mime": "application/pdf" }
  ]
}
```

## 安装

```bash
openclaw plugins install xl-remote
```

## 配置

在 OpenClaw 配置文件中添加：

```json
{
  "plugins": {
    "entries": {
      "xl-remote": {
        "enabled": true,
        "config": {
          "serverUrl": "ws://localhost:8081/remote",
          "serverApiUrl": "http://localhost:8082",
          "localGatewayUrl": "ws://localhost:18789",
          "xlServerRequired": false,
          "reconnect": {
            "enabled": true,
            "maxRetries": 10,
            "initialDelayMs": 5000,
            "maxDelayMs": 300000,
            "backoffMultiplier": 2
          },
          "heartbeat": {
            "intervalMs": 30000,
            "timeoutMs": 60000
          }
        }
      }
    }
  }
}
```

### 配置项说明

| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `serverUrl` | string | `ws://localhost:8081/remote` | xl-server WebSocket 地址 |
| `serverApiUrl` | string | `http://localhost:8082` | xl-server HTTP API 地址 |
| `localGatewayUrl` | string | `ws://localhost:18789` | 本地 OpenClaw Gateway 地址 |
| `xlServerRequired` | boolean | `false` | 是否必须连接到 xl-server |
| `reconnect.enabled` | boolean | `true` | 是否启用自动重连 |
| `reconnect.maxRetries` | number | `10` | 最大重连次数 |
| `reconnect.initialDelayMs` | number | `5000` | 初始重连延迟（毫秒） |
| `reconnect.maxDelayMs` | number | `300000` | 最大重连延迟（毫秒） |
| `heartbeat.intervalMs` | number | `30000` | 心跳间隔（毫秒） |
| `heartbeat.timeoutMs` | number | `60000` | 心跳超时（毫秒） |

## 工作原理

```
┌─────────────┐    WebSocket     ┌─────────────┐    WebSocket    ┌─────────────┐
│ xl-mini-    │ ──────────────► │ xl-server   │ ──────────────► │ xl-remote   │
│ program     │                 │ (中继服务器) │                │ (插件)      │
└─────────────┘                 └─────────────┘                └──────┬──────┘
                                                                       │
                                                                       │ API/WS
                                                                       ▼
                                                              ┌─────────────┐
                                                              │ OpenClaw    │
                                                              │ Gateway     │
                                                              └─────────────┘
```

1. xl-remote 连接到 xl-server 作为远程客户端
2. xl-mini-program 通过 xl-server 与 xl-remote 建立加密会话
3. 消息通过端到端加密传输，xl-server 无法解密
4. xl-remote 转发消息到本地 OpenClaw Gateway
5. AI 响应中的 `local_file` 消息块触发文件传输

## 开发

### 环境要求

- Node.js >= 18
- pnpm >= 8

### 构建

```bash
pnpm install
pnpm build
```

### 测试

```bash
pnpm test
```

## 许可证

Apache License 2.0 - 参见 [LICENSE](LICENSE) 文件

tools