@vclaw/linkdood

OpenClaw linkdood 渠道插件，用来把 Linkdood 消息接入 OpenClaw，再把 Agent 回复送回 Linkdood。

当前代码已经拆成两层：

• 插件层：负责 OpenClaw 运行时接入、路由、SSE、webhook、原生 websocket、日志和账号配置
• SDK 层：负责密信 DDIO 初始化、Socket.IO 建连、消息解码、消息发送

插件不会直接创建、也不会直接导入 socket.io-client，这部分已经收进独立 SDK @vrv-platform/linkdood-sdk。

兼容性

• openclaw >= 2026.3.23

出站链路

插件现在支持四条链路：

1. sdk 当配置了 channels.linkdood.sdk.server、appId、appSecret 时启用。 插件会先调 SDK 初始化 DDIO，再由 SDK 用 Socket.IO 建立连接。
2. websocket 原生 websocket realtime connector，适合兼容老的 Linkdood websocket 服务。
3. SSE 外部客户端订阅 GET /linkdood/stream?sessionKey=<sessionKey>。
4. webhook 兜底回调到 webhookUrl。

回复时的实际优先级：

1. sdk
2. websocket
3. SSE
4. webhook

也就是说：

• 配了 sdk.server 时，优先走 SDK 这条第四类链路
• 没配 sdk.server 时，继续走原有 websocket、SSE、webhook

入站链路

插件接收入站消息有三种方式：

1. POST /linkdood/message
2. 原生 websocket
3. sdk

其中 sdk 模式下的完整流程是：

1. 插件发现账号配置了 channels.linkdood.sdk.server
2. gateway.startAccount 调用 src/linkdood/realtime.ts
3. realtime-sdk.ts 调用 src/linkdood/client.ts
4. client 调用 @vrv-platform/linkdood-sdk 的公开 API
5. SDK 调 DDIO 初始化接口，拿到 endpoint、短期 token、expiresAt、namespace
6. SDK 自己创建 socket.io-client
7. SDK 用 token + appId 建连，发送 sys.init
8. 收到 sys.connected 后认为连接完成
9. SDK 收到业务消息后，先解码成统一结构
10. src/linkdood/linkdood-sdk.ts 把 SDK 入站转换成插件内部入站格式
11. monitor 再继续后面的 OpenClaw 入站处理流程

目录结构

关键目录如下：

• packages/linkdood-sdk 面向所有 Node.js 调用方的独立 SDK
• src/linkdood Linkdood 相关代码，其中 realtime.ts 负责总入口分流，realtime-native.ts 负责原生 websocket，realtime-sdk.ts 负责 SDK 链路，client.ts 负责创建连接，linkdood-sdk.ts 负责 OpenClaw 和独立 SDK 的桥接
• src/http webhook、SSE 和 HTTP 入站编排
• src/outbound OpenClaw 回复消息、结构化动作和最终选路

安装

openclaw plugins install @vclaw/linkdood
openclaw gateway restart

插件会注册：

POST /linkdood/message
GET  /linkdood/stream

配置

推荐使用 CLI：

openclaw config --section channels

原生三链路模式

如果你不配置 channels.linkdood.sdk.server，插件继续按原有方式工作：

• 收消息：
  • POST /linkdood/message
  • 原生 websocket
• 回消息：
  • 原生 websocket
  • SSE
  • webhook

相关配置：

• webhookUrl
• websocket.enabled
• websocket.url
• websocket.headers

SDK 模式

如果你配置了：

• channels.linkdood.sdk.server
• channels.linkdood.sdk.appId
• channels.linkdood.sdk.appSecret

插件会把这个账号切到 SDK 模式：

• 入站由 SDK 的 Socket.IO 连接接收
• 回复和结构化动作也由 SDK 连接发送
• 不再依赖插件里原生 websocket 的协议包装

SDK 相关可选配置：

• sdk.rejectUnauthorized 是否验证 SSL 证书，默认 true；开发环境自签名证书可设为 false
• sdk.ddioInitPath DDIO 初始化路径，默认 /platform/api3/ws/ticket
• sdk.socketInitEvent 默认 sys.init
• sdk.socketConnectedEvent 默认 sys.connected
• sdk.replyEvent 默认 message.reply
• sdk.actionEvent 默认 message.action

其他常用配置

• signingSecret 统一签名密钥
• capabilities 结构化能力声明
• directoryApi 目录查询接口
• groupPolicy 群消息接入策略
• groupAllowFrom 群消息 allowlist
• groupRequireMention 群里是否必须 mention
• groupToolPolicy 群工具权限
• defaultAccount 默认账户
• accounts 多账户配置

开发说明

当前代码里和 SDK 相关的边界是：

• packages/linkdood-sdk/src/index.ts 纯 SDK，对所有 Node.js 项目开放
• src/linkdood/realtime.ts 账户级监听总入口，对标飞书 monitorFeishuProvider
• src/linkdood/realtime-native.ts 只处理原生 websocket 链路
• src/linkdood/realtime-sdk.ts 只处理 SDK Socket.IO 链路
• src/linkdood/client.ts Linkdood 连接创建层，只负责创建 SDK/原生 websocket 连接，不直接依赖 socket.io-client
• src/linkdood/linkdood-sdk.ts OpenClaw 适配层，只负责把 SDK 接到插件运行时
• src/outbound/push.ts 统一决定回复最终走 sdk、websocket、SSE 还是 webhook

当前代码里的“realtime”语义特指两类长连接：

• 原生 websocket
• SDK socket.io

对应的运行时方法已经统一使用 realtime 命名，例如：

• countLinkdoodRealtimeConnections
• resolveLinkdoodActiveRealtimeMode
• publishLinkdoodRealtimeReply

依赖约束

为了保持边界稳定，当前仓库约定：

• 插件 src/ 目录禁止直接依赖或导入 socket.io-client
• socket.io-client 只能存在于 packages/linkdood-sdk
• 插件只能通过 @vrv-platform/linkdood-sdk 的公开 API 使用 SDK 能力

文档索引

• 服务端对接说明：docs/对接linkdood服务端说明.md
• 手动 JSON 配置：docs/MANUAL_CONFIG.md
• 本地开发和联调：docs/DEVELOPMENT.md
• 独立 SDK 文档：packages/linkdood-sdk/README.md