灵爻 (Lingyao) - OpenClaw 与鸿蒙 App 通信桥梁

灵爻是一个完整的双端通信系统，实现 OpenClaw Gateway 和鸿蒙 App 之间的实时双向消息同步，通过 lingyao.live 服务器中转。

当前仓库仅保留“服务器中转 + 双端主动 WebSocket 连接”实现。

快速开始

🚀 完整部署指南

查看 完整部署指南 获取三端完整部署流程：

1. Lingyao Live 服务器部署
2. OpenClaw Gateway 插件安装
3. 鸿蒙 App 部署

系统架构

┌─────────────────────┐                    ┌─────────────────────┐
│   OpenClaw Gateway   │                    │   HarmonyOS App      │
│   (WebSocket Client) │                    │   (WebSocket Client) │
│                      │                    │                      │
│ 代码: src/           │                    │ 代码: harmonyos-app/ │
│ 部署: 作为插件运行   │                    │ 部署: 鸿蒙设备       │
└──────────┬───────────┘                    └──────────┬───────────┘
           │                                            │
           │ WebSocket                                  │ WebSocket
           │ wss://api.lingyao.live/v1/gateway/ws      │ wss://api.lingyao.live/v1/app/ws
           │                                            │
           ▼                                            ▼
┌─────────────────────────────────────────────────────────────┐
│               Lingyao Live Server (lingyao.live)            │
│               (WebSocket Relay Server)                     │
│                                                               │
│ 代码: server/src/server.ts                                  │
│ 部署: 云服务器 (需要公网 IP 和域名)                          │
│ WebSocket: /v1/gateway/ws, /v1/app/ws                       │
│ HTTP API: /v1/gateway/*, /v1/app/*                          │
└─────────────────────────────────────────────────────────────┘

三端组件

1. Lingyao Live 服务器 (server/)

WebSocket 中转服务器，实现 Gateway 和 App 之间的消息转发。

关键文件:

• server/src/server.ts - 主服务器实现
• server/package.json - 依赖配置
• server/README.md - 服务器文档

功能:

• 双 WebSocket 服务器处理 Gateway 和 App 连接
• HTTP REST API 提供注册、心跳、消息发送
• 离线消息队列（每设备最多 100 条）
• 心跳监控和超时检测

2. OpenClaw Gateway 端 (src/)

OpenClaw 插件，作为 WebSocket 客户端连接到服务器。

关键文件:

• src/channel.ts - 主频道类
• src/websocket-client.ts - WebSocket 客户端
• src/server-client.ts - HTTP API 客户端
• src/metrics.ts - 监控指标
• src/errors.ts - 错误处理

功能:

• 自动连接到 lingyao.live 服务器
• 接收来自鸿蒙 App 的同步消息
• 发送通知到鸿蒙 App
• 自动重连和心跳保活

3. 鸿蒙 App 端 (harmonyos-app/)

鸿蒙应用，作为 WebSocket 客户端连接到服务器。

关键文件:

• harmonyos-app/src/websocket/LingyaoWSClient.ts - WebSocket 客户端
• harmonyos-app/src/sync/DataSyncManager.ts - 数据同步管理器
• harmonyos-app/src/models/Message.ts - 消息模型
• harmonyos-app/src/utils/Logger.ts - 日志工具
• harmonyos-app/entry/src/main/ets/entryability/EntryAbility.ts - 应用入口
• harmonyos-app/README.md - App 文档

功能:

• 连接到 lingyao.live 服务器
• 发送日记和记忆数据到 Gateway
• 接收来自 Gateway 的通知
• 离线消息队列和自动同步

核心功能

| 功能 | 描述 | |------|------| | 双向实时通信 | WebSocket 双向消息传递 | | 服务器中转 | 双方作为客户端连接，无需公网 IP | | 离线消息 | 服务器缓存，上线自动推送 | | 自动重连 | 指数退避策略，最多 10 次重试 | | 心跳保活 | 30 秒心跳，60 秒超时检测 | | 消息类型 | 日记、记忆、通知同步 |

消息类型

| 类型 | 方向 | 描述 | |------|------|------| | sync_diary | App → Gateway | 同步日记数据 | | sync_memory | App → Gateway | 同步记忆数据 | | notify_text | Gateway → App | 文本通知 | | notify_action | Gateway → App | 动作通知 | | heartbeat | 双向 | 心跳保活 |

API 端点

Gateway 端点

| 端点 | 方法 | 功能 | |------|------|------| | /v1/gateway/register | POST | 注册 Gateway | | /v1/gateway/heartbeat | POST | 发送心跳 | | /v1/gateway/messages | POST | 发送消息到 App | | /v1/gateway/ws | WS | WebSocket 连接 |

App 端点

| 端点 | 方法 | 功能 | |------|------|------| | /v1/app/register | POST | 注册 App 设备 | | /v1/app/heartbeat | POST | 发送心跳 | | /v1/app/sync | POST | 上传数据到 Gateway | | /v1/app/messages | GET | 拉取消息 | | /v1/app/ws | WS | WebSocket 连接 |

详细 API 规范查看 server-api-spec.yaml

开发

构建

# 构建 OpenClaw 端
npm run build

# 构建服务器端
cd server && npm run build

# 构建鸿蒙 App
# 使用 DevEco Studio 打开 harmonyos-app 并构建

测试

# OpenClaw 端测试
npm test

# 服务器端测试
cd server && npm test

开发模式

# OpenClaw 端开发模式
npm run dev

# 服务器端开发模式
cd server && npm run dev

# 鸿蒙 App 开发
# 使用 DevEco Studio 的调试功能

文档

| 文档 | 描述 | |------|------| | DEPLOYMENT_GUIDE.md | 完整部署指南 | | IMPLEMENTATION_SUMMARY.md | 实现总结 | | server/README.md | 服务器文档 | | harmonyos-app/README.md | App 文档 | | server-api-spec.yaml | OpenAPI 规范 |

项目结构

lingyao/
├── src/                      # OpenClaw Gateway 端代码
│   ├── channel.ts            # 主频道类
│   ├── websocket-client.ts   # WebSocket 客户端
│   ├── server-client.ts      # HTTP 客户端
│   ├── metrics.ts            # 监控指标
│   ├── errors.ts             # 错误处理
│   └── ...
├── server/                   # Lingyao Live 服务器
│   ├── src/
│   │   └── server.ts         # 主服务器
│   ├── package.json
│   ├── tsconfig.json
│   └── README.md
├── harmonyos-app/           # 鸿蒙 App 端
│   ├── src/
│   │   ├── websocket/        # WebSocket 客户端
│   │   ├── sync/             # 数据同步
│   │   ├── models/           # 数据模型
│   │   └── utils/            # 工具类
│   ├── entry/                # 应用入口
│   └── README.md
├── test/                     # 测试文件
├── DEPLOYMENT_GUIDE.md       # 部署指南
├── IMPLEMENTATION_SUMMARY.md # 实现总结
├── server-api-spec.yaml      # API 规范
├── README.md                 # 本文件
└── package.json

配置

OpenClaw Gateway 配置

{
  "plugins": {
    "entries": {
      "lingyao": {
        "enabled": true
      }
    }
  }
}

服务器配置

# server/.env
PORT=3000
HOST=0.0.0.0
HEARTBEAT_INTERVAL=30000
HEARTBEAT_TIMEOUT=60000
MAX_OFFLINE_MESSAGES=100

鸿蒙 App 配置

// EntryAbility.ts
const wsClient = new LingyaoWSClient({
  url: 'wss://api.lingyao.live/v1/app/ws',
  deviceId: deviceId,
  appToken: appToken,
});

监控和调试

查看日志

| 组件 | 命令 | |------|------| | 服务器 | sudo journalctl -u lingyao-live -f | | Gateway | openclaw logs | | App | DevEco Studio 日志窗口 |

健康检查

# 服务器健康检查
curl https://api.lingyao.live/health

# Gateway 状态
openclaw channels status --channel lingyao

# App 连接状态
# 查看 App 界面中的连接状态显示

故障排查

服务器端

# 检查服务状态
sudo systemctl status lingyao-live

# 查看错误日志
sudo journalctl -u lingyao-live -n 50 --no-pager

# 重启服务
sudo systemctl restart lingyao-live

Gateway 端

# 检查插件状态
openclaw plugins list

# 查看日志
openclaw logs

# 重启 Gateway
openclaw gateway restart

App 端

• 检查设备网络连接
• 确认服务器 URL 正确
• 查看应用日志

贡献

欢迎提交 Issue 和 Pull Request！

许可证

MIT License

联系方式

• 项目主页: https://github.com/your-org/lingyao
• 问题反馈: https://github.com/your-org/lingyao/issues