Files

HenryXiaoYang ba754ccc31 feat: add WeChat QR code login and AGP WebSocket channel plugin

- Auth module: WeChat OAuth2 scan-to-login flow with terminal QR code
- Token persistence to ~/.openclaw/wechat-access-auth.json (chmod 600)
- Token resolution: config > saved state > interactive login
- Invite code verification (configurable bypass)
- Production/test environment support
- AGP WebSocket client with heartbeat, reconnect, wake detection
- Message handler: Agent dispatch with streaming text and tool calls
- Random device GUID generation (persisted, no real machine ID)

2026-03-10 02:29:06 +08:00

4.0 KiB

Raw Blame History

Fuwuhao (微信服务号) 模块

📁 文件结构

src/
├── types.ts              # 类型定义
├── crypto-utils.ts       # 加密解密工具
├── http-utils.ts         # HTTP 请求处理工具
├── callback-service.ts   # 后置回调服务
├── message-context.ts    # 消息上下文构建
├── message-handler.ts    # 消息处理器（核心业务逻辑）
├── webhook.ts            # Webhook 处理器（主入口）
├── runtime.ts            # Runtime 配置
└── index.ts              # 模块导出索引

📦 模块说明

1. `types.ts` - 类型定义

定义所有 TypeScript 类型和接口：

AgentEventPayload - Agent 事件载荷
FuwuhaoMessage - 服务号消息格式
SimpleAccount - 账号配置
CallbackPayload - 回调数据格式
StreamChunk - 流式消息块
StreamCallback - 流式回调函数类型

2. `crypto-utils.ts` - 加密解密工具

处理微信服务号的签名验证和消息加密解密：

verifySignature() - 验证签名
decryptMessage() - 解密消息

3. `http-utils.ts` - HTTP 工具

处理 HTTP 请求相关的工具方法：

parseQuery() - 解析查询参数
readBody() - 读取请求体
isFuwuhaoWebhookPath() - 检查是否是服务号 webhook 路径

4. `callback-service.ts` - 后置回调服务

将处理结果发送到外部回调服务：

sendToCallbackService() - 发送回调数据

5. `message-context.ts` - 消息上下文构建

构建消息处理所需的上下文信息：

buildMessageContext() - 构建消息上下文（路由、会话、格式化等）

6. `message-handler.ts` - 消息处理器

核心业务逻辑，处理消息并调用 Agent：

handleMessage() - 同步处理消息
handleMessageStream() - 流式处理消息（SSE）

7. `webhook.ts` - Webhook 处理器

主入口，处理微信服务号的 webhook 请求：

handleSimpleWecomWebhook() - 处理 GET/POST 请求，支持同步和流式返回

8. `runtime.ts` - Runtime 配置

获取 OpenClaw 运行时实例

9. `index.ts` - 模块导出

统一导出所有公共 API

🔄 数据流

微信服务号
    ↓
webhook.ts (入口)
    ↓
http-utils.ts (解析请求)
    ↓
crypto-utils.ts (验证签名/解密)
    ↓
message-context.ts (构建上下文)
    ↓
message-handler.ts (处理消息)
    ↓
OpenClaw Agent (AI 处理)
    ↓
callback-service.ts (后置回调)
    ↓
返回响应

🚀 使用示例

基本使用

import { handleSimpleWecomWebhook } from "./src/webhook.js";

// 在 HTTP 服务器中使用
server.on("request", async (req, res) => {
  const handled = await handleSimpleWecomWebhook(req, res);
  if (!handled) {
    // 处理其他路由
  }
});

流式返回（SSE）

// 客户端请求时添加 stream 参数
fetch("/fuwuhao?stream=true", {
  headers: {
    "Accept": "text/event-stream"
  }
});

🔧 配置

环境变量

FUWUHAO_CALLBACK_URL - 后置回调服务 URL（默认：http://localhost:3001/api/fuwuhao/callback）

账号配置

在 webhook.ts 中修改 mockAccount 对象：

const mockAccount: SimpleAccount = {
  token: "your_token_here",
  encodingAESKey: "your_encoding_aes_key_here", 
  receiveId: "your_receive_id_here"
};

📝 注意事项

加密解密：当前 crypto-utils.ts 中的加密解密方法是简化版，生产环境需要实现真实的加密逻辑
签名验证：同样需要在生产环境中实现真实的签名验证算法
错误处理：所有模块都包含完善的错误处理和日志记录
类型安全：所有模块都使用 TypeScript 严格类型检查

🎯 设计原则

单一职责：每个文件只负责一个特定功能
低耦合：模块之间通过明确的接口通信
高内聚：相关功能集中在同一模块
可测试：每个模块都可以独立测试
可扩展：易于添加新功能或修改现有功能

4.0 KiB Raw Blame History Unescape Escape