# openclaw-weixin-forward

**Repository Path**: pior/openclaw-weixin-forward

## Basic Information

- **Project Name**: openclaw-weixin-forward
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-13
- **Last Updated**: 2026-06-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# weixin-forward

HTTP webhook 插件，将收到的消息广播到所有已知的微信联系人。

‼️注意‼️：微信的iLink有响应时间限制，微信端发出一条消息，iLink最多允许转发24小时内的回复消息。所以间隔时间太长，如24小时之后的再向微信会失败。需要在微信端发送消息进行交互。
```mermaid
sequenceDiagram
    participant WX as 微信
    participant IL as iLink
    participant SYS as openclaw
    Note over WX,SYS: iLink转发时效要求：只转发24小时内的回复
    WX->>IL: 发送1条原始消息
    loop 24小时内
        SYS->>IL: 回复消息N
        IL-->>WX: 成功转发
    end
    SYS-XIL: 超过24小时内回复转发（失败，消息丢弃）
    WX->>IL: 发送1条原始消息
    SYS->>IL: 回复消息
    IL-->>WX: 成功转发
```

‼️注意‼️：微信的iLink有响应条数限制，微信端发出一条消息，iLink最多允许转发十条回复消息。所以连续向微信推送条数过多时，会导致消息发送失败。需要在微信端发送消息进行交互。
```mermaid
sequenceDiagram
    participant WX as 微信
    participant IL as iLink
    participant SYS as openclaw
    Note over WX,SYS: iLink转发上限：单消息最多10条回复
    WX->>IL: 发送1条原始消息
    loop 1~10条回复
        SYS->>IL: 回复消息N
        IL-->>WX: 成功转发
    end
    SYS-XIL: 第11条回复转发（失败，消息丢弃）
    WX->>IL: 发送1条原始消息
    SYS->>IL: 回复消息
    IL-->>WX: 成功转发
```

 ⚠️ 另外，通过插件转发的消息，是直接调用微信接口处理，Agent不会收到，好处是不会花费token，坏处是Agent看不到这个消息，后续处理不会包括这部分记忆。

## 工作方式

```
三方系统  POST /plugins/weixin-forward/webhook  {"text": "告警信息"}
   → 读取 openclaw-weixin 插件的 context-tokens.json，获取所有已知联系人
   → 通过 openclaw-weixin channel 的 sendText adapter 逐个发送
   ← 200 {"sent": 3, "failed": 0, "errors": []}
```

## 前置条件

- OpenClaw Gateway 已运行
- `openclaw-weixin` 插件已安装并已登录（至少有一个联系人跟 bot 聊过天）

```bash
openclaw plugins list          # 确认 openclaw-weixin 已安装
openclaw channels status       # 确认 weixin 通道在线
```

## 部署

### 1. 安装依赖 & 编译

```bash
git clone https://gitee.com/pior/openclaw-weixin-forward.git
cd extensions/weixin-forward
pnpm install
pnpm build
```

### 2. 安装插件

```bash
openclaw plugins install .
```

### 3. 重启 Gateway

```bash
openclaw gateway restart
```

### 4. 验证

重启后检查日志确认路由注册成功：

```bash
openclaw logs tail | grep weixin-forward
```

应该看到：

```
[weixin-forward] registered webhook route: /plugins/weixin-forward/webhook
```

### 5. 测试

```bash
curl -X POST http://localhost:18789/plugins/weixin-forward/webhook \
  -H "Content-Type: application/json" \
  -d '{"text": "测试消息"}'
```

成功响应：

```json
{"sent": 3, "failed": 0, "errors": []}
```

## 配置

插件无需额外配置。默认行为：

| 项目 | 值 |
|------|-----|
| Webhook 路径 | `/plugins/weixin-forward/webhook` |
| 认证 | 无需认证（内网使用） |
| Recipient | 自动从 weixin 插件 context token 文件中读取全部已知联系人 |
| 请求体格式 | `{"text": "消息内容"}` |

## 错误响应

| 状态码 | 含义 |
|--------|------|
| `200` | 成功（部分失败也可能是 200，检查 `failed` 字段） |
| `400` | 请求体不是合法 JSON |
| `405` | 非 POST 方法 |
| `413` | 请求体过大或读取超时 |
| `422` | `text` 字段缺失/为空，或无已知联系人 |
| `503` | `openclaw-weixin` channel adapter 不可用 |

## 日志

所有日志带 `[weixin-forward]` 前缀，可通过 `openclaw logs` 查看。