xl-remote

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

功能

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

文件传输

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

消息块格式

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

示例

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

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

安装

openclaw plugins install xl-remote

配置

在 OpenClaw 配置文件中添加：

{
  "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

构建

pnpm install
pnpm build

测试

pnpm test

许可证

Apache License 2.0 - 参见 LICENSE 文件