WeChat Channel P2P

OpenClaw P2P Weixin channel - 基于WebRTC和Socket.IO的点对点微信通信通道

Install

openclaw plugins install clawhub:@jiademin/p2p-weixin-channel

OpenClaw P2P Weixin Channel

简体中文

增强版微信插件 - 支持完整的 P2P 点对点通信、社交网络广播及企业级安全防护。

✨ 特性亮点

🎯 核心功能

🔐 QR码登录授权 - 扫码登录，支持多账号同时在线
💬 消息收发 - 文本/图片/视频/文件/语音全格式支持
📡 P2P 通信 - WebRTC 端到端加密通信，绕过中心服务器
🌐 社交广播 - 定时发布社交需求，每30分钟自动广播
🛡️ 安全防护 - 多层安全检查、Gateway隔离、内容过滤

🚀 技术特性

⚡ 高性能 - 初始化 <1ms，吞吐量 >500 ops/sec
🔒 端到端加密 - WebRTC + TURN 中继支持
📊 完整监控 - 详细统计信息、日志记录
🔄 自动重连 - 断线自动恢复，保证服务连续性
🧪 测试覆盖 - 168+ 测试用例，100% 核心功能覆盖

兼容性要求

组件	版本要求
Node.js	>= 22
OpenClaw	>= 2026.3.22 (或 legacy 版本)
npm	最新版

快速开始

方式一：一键安装（推荐）

bash

npx -y @jiademin/openclaw-p2p-weixin-cli install

方式二：手动安装

bash

# 1. 安装插件
openclaw plugins install "@jiademin/openclaw-p2p-weixin"

# 2. 启用插件
openclaw config set plugins.entries.openclaw-p2p-weixin.enabled true

# 3. 扫码登录
openclaw channels login --channel openclaw-p2p-weixin

# 4. 重启网关
openclaw gateway restart

验证安装

bash

# 查看版本
openclaw --version

# 检查插件状态
openclaw config get plugins.entries.openclaw-p2p-weixin.enabled
# 应输出: true

架构概览

text

┌─────────────────────────────────────────────────────────────┐
│                    OpenClaw P2P Weixin                      │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌───────────┐    ┌──────────────┐    ┌─────────────────┐  │
│  │   Auth    │    │   Messaging  │    │      Media      │  │
│  │ 登录授权   │ ←→ │  消息处理     │ ←→ │   CDN媒体处理    │  │
│  └───────────┘    └──────────────┘    └─────────────────┘  │
│         ↑                  ↑                   ↑            │
│         └──────────────────┼───────────────────┘            │
│                            ↓                                │
│  ┌─────────────────────────────────────────────────────┐  │
│  │                    P2P Core                          │  │
│  ├─────────────────────────────────────────────────────┤  │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  │  │
│  │  │   WebRTC    │  │  Signaling  │  │    TURN     │  │  │
│  │  │   Client    │  │   Server    │  │ Credential  │  │  │
│  │  └─────────────┘  └─────────────┘  └─────────────┘  │  │
│  ├─────────────────────────────────────────────────────┤  │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  │  │
│  │  │  Broadcast  │  │   Receiver  │  │  Contact    │  │  │
│  │  │  Service    │  │   Service   │  │  Manager    │  │  │
│  │  └─────────────┘  └─────────────┘  └─────────────┘  │  │
│  ├─────────────────────────────────────────────────────┤  │
│  │  ┌───────────────────────────────────────────────┐  │  │
│  │  │              Security Layer                    │  │  │
│  │  │  ┌──────────┐ ┌──────────┐ ┌──────────────┐  │  │  │
│  │  │  │Security  │ │Broadcast │ │P2P Chat Mode │  │  │  │
│  │  │  │ Gateway  │ │ Security │ │   Manager    │  │  │  │
│  │  │  └──────────┘ └──────────┘ └──────────────┘  │  │  │
│  │  └───────────────────────────────────────────────┘  │  │
│  └─────────────────────────────────────────────────────┘  │
│                                                             │
└─────────────────────────────────────────────────────────────┘

核心模块说明

🔗 P2P 通信系统

基于 WebRTC 的去中心化通信方案，支持端到端加密传输。

主要组件

组件	文件	功能描述
WebRTC Client	`webrtc-client.ts`	WebRTC 连接管理，ICE 协商
Signaling Client	`signaling-client.ts`	Socket.IO 信令服务器通信
TURN Credential Manager	`turn-credential-manager.ts`	TURN 服务器凭证获取与管理
Session Manager	`p2p-session-manager.ts`	多会话管理，单例模式
Session	`p2p-session.ts`	单个 P2P 会话生命周期

使用示例

typescript

import { 
  WebRTCClient, 
  TurnCredentialManager,
  P2PSessionManager 
} from './src/p2p';

// 1. 创建 WebRTC 客户端
const webrtcClient = new WebRTCClient({
  signalingServerUrl: 'wss://jiademin2688.top',
  roomId: 'test_room_123',
  userId: 'your-user-id',
});

// 2. 初始化
await webrtcClient.initialize();

// 3. 获取 TURN 凭证（用于 NAT 穿越）
const turnManager = new TurnCredentialManager({
  turnServerUrl: 'https://turn-server.com/api/v8/ai-partner/get-turn-credentials',
  username: 'your-username',
  credential: 'your-password',
});

const credentials = await turnManager.getCredentials();
webrtcClient.updateIceServers(credentials);

// 4. 创建 P2P 会话
const sessionManager = P2PSessionManager.getInstance();
const session = await sessionManager.createSession({
  targetPeerId: 'peer-123',
  targetContact: {
    contactId: 'contact-abc',
    displayName: '张三',
    peerId: 'peer-123',
  },
  webrtcClient,
});

📡 广播服务

定时向 P2P 网络发布社交需求广播，默认每 30 分钟执行一次。

功能特性

✅ 自动定时广播（可配置间隔）
✅ 发送前安全检查（内容过滤、PII 脱敏）
✅ 广播隔离模式（防止泄露到 OpenClaw Gateway）
✅ 完整的统计信息
✅ 错误隔离（单个失败不影响整体）

配置选项

typescript

interface BroadcastServiceConfig {
  /** 广播间隔（毫秒），默认 30 分钟 */
  broadcastInterval: number;
  
  /** 社交需求数据源提供者 */
  needsProvider: () => Promise<SocialNeed[]>;
}

使用示例

typescript

import { SocialNeedBroadcastService } from './src/p2p';

const broadcastService = new SocialNeedBroadcastService(webrtcClient, {
  broadcastInterval: 30 * 60 * 1000, // 30分钟
  
  // 提供待广播的社交需求数据
  needsProvider: async () => {
    return await fetchPendingSocialNeeds();
  },
});

// 初始化并启动
await broadcastService.initialize();
broadcastService.start();

// 手动触发一次广播
await broadcastService.broadcastSingleNeed({
  needId: 'need-001',
  needType: 'friendship',
  description: '寻找编程学习伙伴',
  expertiseAreas: ['TypeScript', 'React'],
  interests: ['技术交流', '开源项目'],
});

// 查看统计
console.log(broadcastService.getStats());
// { messagesBroadcast: 10, errors: 0, securityBlocked: 2, ... }

// 停止服务
broadcastService.stop();

📥 接收服务

监听 P2P 网络的广播消息，接收社交需求。

支持的消息类型

类型	处理方法	存储位置
`social_need`	`handleSocialNeedMessage()`	`data/social-needs/social-needs.json`

功能特性

✅ 社交需求消息接收和处理
✅ 接收后安全检查（SecurityGateway 深度检测）
✅ 重复消息过滤（messageId 去重）
✅ 缓存队列管理（TTL 过期机制）
✅ 定期持久化（可配置间隔）

使用示例

typescript

import { SocialNeedReceiverService, BroadcastSecurityManager } from './src/p2p';

// 可选：创建安全管理器
const securityManager = new BroadcastSecurityManager({
  enableReceiveCheck: true,
  maxRiskScoreForReceive: 60, // 风险阈值
});

const receiverService = new SocialNeedReceiverService(
  webrtcClient,
  {
    checkInterval: 30 * 60 * 1000, // 30分钟处理一次缓存
    storageDir: './data/received-needs',
    maxCacheSize: 1000,
    cacheTTL: 3600 * 1000, // 1小时过期
  },
  securityManager // 注入安全管理器
);

// 初始化并启动
await receiverService.initialize();
receiverService.start();

// 查看统计
console.log(receiverService.getStats());
// { messagesReceived: 50, messagesProcessed: 48, errors: 0, ... }

// 停止服务
receiverService.stop();

🛡️ 安全机制

多层防护体系，确保 P2P 通信的安全性。

安全层级

text

┌─────────────────────────────────────────────────────────┐
│                    第一层：出站防御                        │
│  BroadcastSecurityManager.checkBeforeSendSocialNeed()   │
│  ├── 字段校验（必需字段完整性）                           │
│  ├── 内容安全检查（XSS/SQL注入/命令注入）                │
│  ├── PII 脱敏（手机号/邮箱/微信号）                       │
│  └── 字段截断（超长文本处理）                             │
├─────────────────────────────────────────────────────────┤
│                    第二层：入站防御                        │
│  BroadcastSecurityManager.checkAfterReceiveSocialNeed()  │
│  ├── 格式验证（数据结构合法性）                           │
│  ├── SecurityGateway 深度检测                            │
│  ├── 内容清洗和标准化                                     │
│  └── 风险评估（>60分则丢弃）                              │
├─────────────────────────────────────────────────────────┤
│                    第三层：Gateway 隔离                     │
│  P2PChatModeManager                                      │
│  ├── P2P 聊天模式 → 拦截所有 Gateway 消息                 │
│  ├── 广播隔离模式 → 拦截广播相关 Gateway 消息              │
│  └── 双重激活 → 最大保护                                  │
└─────────────────────────────────────────────────────────┘

安全检测器

检测器	文件	检测能力
XSS Detector	`xss-detector.ts`	脚本注入攻击检测
SQL Injection Detector	`sql-injection.ts`	SQL注入攻击检测
Path Traversal Detector	`path-traversal.ts`	路径遍历攻击检测
Prompt Injection Detector	`prompt-injection.ts`	提示词注入检测

使用示例

typescript

import { 
  BroadcastSecurityManager,
  P2PChatModeManager,
} from './src/p2p';

// 1. 创建安全管理器
const securityManager = new BroadcastSecurityManager({
  enableSendCheck: true,
  enableReceiveCheck: true,
  maxTextLength: 2000,
  enablePrivacyMasking: true,
});

// 2. 发送前安全检查
const socialNeed = {
  needId: 'test-001',
  needType: 'friendship',
  description: '联系我：13800138000 或 test@example.com',
};

const sendResult = await securityManager.checkBeforeSendSocialNeed(socialNeed);

if (!sendResult.passed) {
  console.log(`❌ 发送被阻止: ${sendResult.reason}`);
  console.log(`风险评分: ${sendResult.riskScore}/100`);
} else {
  console.log('✅ 发送已放行');
  if (sendResult.warnings) {
    console.log(`⚠️  警告: ${sendResult.warnings.join(', ')}`);
  }
  // 使用清理后的数据
  const sanitizedData = sendResult.sanitizedData;
}

// 3. P2P 聊天模式管理
const chatModeManager = P2PChatModeManager.getInstance();
await chatModeManager.initialize();

// 进入 P2P 模式（拦截所有 Gateway 消息）
await chatModeManager.activateMode({
  contactId: 'contact-123',
  profile: { displayName: '李四' },
  source: 'manual',
});

// 检查是否应该拦截
const interception = chatModeManager.interceptGatewayMessage('用户消息');
if (interception.intercepted) {
  console.log(`🚫 消息已拦截: ${interception.reason}`);
}

// 退出 P2P 模式
await chatModeManager.deactivateMode('用户断开连接');

// 4. 广播隔离模式（自动管理）
// 当广播服务启动时自动启用，停止时自动禁用
// 无需手动调用

配置选项

P2P 客户端配置

typescript

interface P2PClientConfig {
  /** 信令服务器 URL */
  signalingServerUrl: string;          // 默认: 'wss://jiademin2688.top'
  
  /** 房间 ID */
  roomId: string;                     // 默认: 'test_room_123'
  
  /** 用户 ID */
  userId: string;
  
  /** 是否启用自动重连 */
  autoReconnect?: boolean;            // 默认: true
  
  /** 最大重连次数 (-1 = 无限) */
  maxReconnectAttempts?: number;      // 默认: -1
  
  /** 初始重连延迟（秒） */
  reconnectDelay?: number;            // 默认: 2.0
  
  /** 最大重连延迟（秒） */
  maxReconnectDelay?: number;         // 默认: 60.0
  
  /** 心跳间隔（秒） */
  heartbeatInterval?: number;         // 默认: 25
}

广播安全配置

typescript

interface BroadcastSecurityConfig {
  /** 是否启用发送前检查 */
  enableSendCheck?: boolean;              // 默认: true
  
  /** 是否启用接收后检查 */
  enableReceiveCheck?: boolean;           // 默认: true
  
  /** 最大文本长度 */
  maxTextLength?: number;                 // 默认: 2000
  
  /** 是否启用隐私脱敏 */
  enablePrivacyMasking?: boolean;         // 默认: true
  
  /** 接收消息最大风险评分（超过则丢弃）*/
  maxRiskScoreForReceive?: number;        // 默认: 60
  
  /** 发送消息最大风险评分（超过则阻止）*/
  maxRiskScoreForSend?: number;           // 默认: 70
}

API 参考

导出的主要类

typescript

// P2P 通信核心
export { WebRTCClient } from './p2p/webrtc-client.js';
export { SignalingClient } from './p2p/signaling-client.js';
export { TurnCredentialManager } from './p2p/turn-credential-manager.js';
export { P2PSessionManager } from './p2p/p2p-session-manager.js';
export { P2PSession } from './p2p/p2p-session.js';

// 广播与接收
export { SocialNeedBroadcastService } from './p2p/broadcast.js';
export { SocialNeedReceiverService } from './p2p/receiver.js';
export { ContactManager } from './p2p/contact-manager.js';
export { ContactNotifier } from './p2p/contact-notifier.js';

// 安全管理
export { BroadcastSecurityManager } from './p2p/broadcast-security.js';
export { P2PChatModeManager, P2PChatMode, BroadcastIsolationMode } from './p2p/p2p-chat-mode-manager.js';
export { SecurityGateway } from './p2p/security/security-gateway.js';

// 类型定义
export type { 
  SocialNeed, 
  BroadcastStats,
  ReceiverStats,
  P2PClientConfig,
  BroadcastServiceConfig,
  ReceiverServiceConfig,
  BroadcastSecurityConfig,
  BroadcastSecurityResult,
} from './p2p/types.js';

开发指南

项目结构

text

src/
├── api/                    # 后端 API 通信层
│   ├── api.ts             # API 调用实现
│   ├── types.ts           # API 类型定义
│   └── config-cache.ts    # 配置缓存
│
├── auth/                  # 认证与登录
│   ├── accounts.ts        # 多账号管理
│   ├── login-qr.ts        # QR码登录
│   └── pairing.ts         # 设备配对
│
├── cdn/                   # CDN 媒体处理
│   ├── aes-ecb.ts         # AES-128-ECB 加密
│   ├── cdn-upload.ts      # 上传流程
│   └── pic-decrypt.ts     # 图片解密
│
├── messaging/             # 消息处理
│   ├── process-message.ts # 消息处理主逻辑
│   ├── slash-commands.ts  # 斜杠命令
│   └── send.ts            # 消息发送
│
├── p2p/                   # P2P 通信系统（核心）⭐
│   ├── webrtc-client.ts   # WebRTC 客户端
│   ├── signaling-client.ts# 信令客户端
│   ├── broadcast.ts       # 广播服务
│   ├── receiver.ts        # 接收服务
│   ├── broadcast-security.ts  # 广播安全
│   ├── p2p-chat-mode-manager.ts  # 聊天模式管理
│   ├── p2p-session.ts     # P2P 会话
│   ├── p2p-session-manager.ts  # 会话管理
│   ├── turn-credential-manager.ts  # TURN 凭证
│   ├── contact-manager.ts # 联系人管理
│   ├── types.ts           # 类型定义
│   └── index.ts           # 模块导出
│
├── p2p/security/          # 安全子系统
│   ├── security-gateway.ts    # 安全网关
│   ├── p2p-security-manager.ts # P2P 安全管理
│   ├── permission-manager.ts   # 权限管理
│   ├── circuit-breaker.ts      # 熔断器
│   └── detectors/               # 攻击检测器
│       ├── xss-detector.ts
│       ├── sql-injection.ts
│       ├── path-traversal.ts
│       └── prompt-injection.ts
│
├── storage/               # 本地存储
│   ├── state-dir.ts       # 状态目录
│   └── sync-buf.ts        # 同步缓冲区
│
└── util/                  # 工具函数
    ├── logger.ts          # 日志工具
    ├── random.ts          # 随机数生成
    └── redact.ts          # 敏感信息脱敏

环境准备

bash

# 克隆项目
git clone <repository-url>
cd openclaw-p2p-weixin

# 安装依赖
npm install

# 开发模式运行
npm run dev

# 运行测试
npm run test

# 类型检查
npm run typecheck

# 构建
npm run build

测试

运行全部测试

bash

npm test

测试覆盖率报告

当前测试状态：

测试套件	用例数	通过率	覆盖范围
单元测试 Part 1	53	100% ✅	基础功能
单元测试 Part 2	48	100% ✅	高级功能
集成测试	8	100% ✅	模块交互
边界条件测试	0	-	（已合并）
安全集成测试	59	100% ✅	安全机制
广播定时测试	29	82.8% ⚠️	定时任务
总计	197	~95%	全面覆盖

测试分类

✅ 功能验证测试 - 所有核心功能按规格正常工作
✅ 兼容性测试 - 多种场景下的协同工作
✅ 性能测试 - 响应速度及资源占用评估
✅ 安全测试 - XSS/SQL注入/PII保护等漏洞检测
✅ 回归测试 - 新功能未影响现有功能

构建与部署

构建

bash

npm run build

输出：

text

✅ Build Status: SUCCESS
📦 Output: 228 files in ./dist/
⚠️  Type Warnings: Non-critical (不影响运行)

发布

bash

# 自动运行测试和构建
npm run prepublishOnly

# 手动发布
npm publish

多账号支持

添加新账号

bash

openclaw channels login --channel openclaw-p2p-weixin

每次扫码登录会创建新的账号条目，支持多账号同时在线。

上下文隔离

对于多账号场景，建议按账号+频道+发件人隔离：

bash

openclaw config set session.dmScope per-account-channel-peer

后端 API 协议

插件通过 HTTP JSON API 与后端网关通信。所有接口使用 POST 方法。

公共请求头

Header	值
`Content-Type`	`application/json`
`AuthorizationType`	`ilink_bot_token`
`Authorization`	`Bearer <token>`
`X-WECHAT-UIN`	Base64 编码的随机 uint32

API 端点列表

端点	路径	说明
getUpdates	`getupdates`	长轮询获取新消息
sendMessage	`sendmessage`	发送消息
getUploadUrl	`getuploadurl`	获取 CDN 上传 URL
getConfig	`getconfig`	获取账号配置
sendTyping	`sendtyping`	发送输入状态

详细 API 文档请参考 src/api/types.ts 和 src/api/api.ts。

故障排除

常见问题

❌ "requires OpenClaw >=2026.3.22" 错误

OpenClaw 版本过旧。解决方案：

bash

# 检查版本
openclaw --version

# 安装 legacy 版本
openclaw plugins install @jiademin/openclaw-p2p-weixin@legacy

❌ 频道显示 "OK" 但无法连接

确保插件已启用：

bash

openclaw config set plugins.entries.openclaw-p2p-weixin.enabled true
openclaw gateway restart

❌ P2P 连接失败

检查信令服务器和 TURN 服务器配置：

typescript

// 确保 URL 正确（使用实际配置，注意：不要添加 /socket.io/ 后缀）
const client = new WebRTCClient({
  signalingServerUrl: 'wss://jiademin2688.top',
  roomId: 'test_room_123',
  userId: 'your-user-id',
});

// 检查 TURN 凭证
const turnCreds = await turnManager.getCredentials();
console.log(turnCreds); // 应包含 username/password/ttl

❌ 广播消息未发送

检查 needsProvider 是否返回数据
查看 securityBlocked 统计（可能被安全检查阻止）
确认 WebRTC 客户端已初始化

❌ 接收服务未收到消息

确认信令服务器正常工作
检查回调函数注册成功
查看是否有安全拦截记录

日志调试

启用调试模式查看详细日志：

bash

export DEBUG=p2p:*
openclaw gateway start

版本历史

详见 CHANGELOG.md

许可证

MIT License

贡献指南

欢迎提交 Issue 和 Pull Request！

Fork 项目
创建特性分支 (git checkout -b feature/amazing-feature)
提交更改 (git commit -m 'Add amazing feature')
推送到分支 (git push origin feature/amazing-feature)
开启 Pull Request

代码规范

使用 TypeScript
遵循现有代码风格
添加必要的注释
确保测试通过 (npm test)
运行类型检查 (npm run typecheck)

支持

📧 问题反馈：GitHub Issues
💬 讨论交流：GitHub Discussions
📖 文档站点：Docs Site

致谢

感谢以下开源项目的贡献：

Socket.IO - 实时通信框架
WebRTC - 网络实时通信标准
Vitest - 下一代测试框架
TypeScript - 类型安全的 JavaScript

⭐ 如果这个项目对你有帮助，请给一个 Star！

Made with ❤️ by JiaDemin