@netcat-ai/openclaw-weixin 2.4.7

package/README.md

@@ -0,0 +1,355 @@
+# WeChat
+
+[简体中文](./README.zh_CN.md)
+
+OpenClaw's WeChat channel plugin, supporting login authorization via QR code scanning.
+
+## Compatibility
+
+| Plugin Version | OpenClaw Version       | npm dist-tag | Status      |
+|---------------|------------------------|--------------|-------------|
+| 2.0.x         | >=2026.3.22            | `latest`     | Active      |
+| 1.0.x         | >=2026.1.0 <2026.3.22  | `legacy`     | Maintenance |
+
+> The plugin checks the host version at startup and will refuse to load if the
+> running OpenClaw version is outside the supported range.
+
+## Prerequisites
+
+[OpenClaw](https://docs.openclaw.ai/install) must be installed (the `openclaw` CLI needs to be available).
+
+Check your version: `openclaw --version`
+
+## Installation
+
+```bash
+openclaw plugins install @netcat-ai/openclaw-weixin
+```
+
+Enable the plugin:
+
+```bash
+openclaw config set plugins.entries.openclaw-weixin.enabled true
+```
+
+For a custom iLink backend, set the service URL before the login that should use it:
+
+```bash
+openclaw config set channels.openclaw-weixin.baseUrl http://127.0.0.1:38080
+```
+
+Then start QR code login:
+
+```bash
+openclaw channels login --channel openclaw-weixin
+```
+
+A QR code will appear in the terminal. Scan it with your phone and confirm the authorization. Once confirmed, the login credentials and service URL are saved with that account.
+
+Changing the channel-level `baseUrl` later only affects the next new account login. Existing accounts keep their saved backend, so one `openclaw-weixin` channel can use the official backend and multiple Webox instances at the same time.
+
+Restart the gateway:
+
+```bash
+openclaw gateway restart
+```
+
+## Adding More WeChat Accounts
+
+Log in through the official backend:
+
+```bash
+openclaw config set channels.openclaw-weixin.baseUrl https://ilinkai.weixin.qq.com
+openclaw channels login --channel openclaw-weixin
+```
+
+Log in through another Webox instance:
+
+```bash
+openclaw config set channels.openclaw-weixin.baseUrl http://127.0.0.1:38081
+openclaw channels login --channel openclaw-weixin
+```
+
+Each QR code login creates a new account entry, supporting multiple WeChat accounts online simultaneously.
+
+## Multi-Account Context Isolation
+
+By default, DMs can share one session bucket. For **multiple logged-in WeChat accounts**, isolate by account + channel + sender:
+
+```bash
+openclaw config set session.dmScope per-account-channel-peer
+```
+
+## Custom BotAgent (optional)
+
+Every outbound request to the WeChat backend carries a self-declared `bot_agent`
+identifier — analogous to an HTTP `User-Agent` — used for log attribution and
+monitoring aggregation. The default is `OpenClaw`. Declaring your own app name
+makes it much easier to trace your traffic in backend logs.
+
+Add one line to `openclaw.json`:
+
+```json
+{
+  "channels": {
+    "openclaw-weixin": {
+      "botAgent": "MyBot/1.2.0"
+    }
+  }
+}
+```
+
+**Format** (UA-style):
+
+- One or more `Name/Version` tokens, space-separated
+- Each token may optionally be followed by ` (comment)`
+- ASCII only; total length ≤ 256 bytes
+- Invalid tokens are silently dropped during sanitization; falls back to
+  `OpenClaw` if nothing valid remains
+
+Examples that pass through unchanged:
+
+- `MyBot/1.2.0`
+- `MyBot/1.2.0 (region=cn;env=prod)`
+- `MyBot/1.2.0 LangChain/0.3.5`
+- `MyBot/1.2.0-rc.1+build.5`
+
+**Note**: `bot_agent` is for observability only — it is not used for
+authentication or routing. All registered agents on this plugin instance
+currently share the same `botAgent` declaration; per-agent overrides may be
+added in a future version if needed.
+
+## Backend API Protocol
+
+This plugin communicates with the backend gateway via HTTP JSON API. Developers integrating with their own backend need to implement the following interfaces.
+
+All endpoints use `POST` with JSON request and response bodies. Common request headers:
+
+| Header | Description |
+|--------|-------------|
+| `Content-Type` | `application/json` |
+| `AuthorizationType` | Fixed value `ilink_bot_token` |
+| `Authorization` | `Bearer <token>` (obtained after login) |
+| `X-WECHAT-UIN` | Base64-encoded random uint32 |
+
+### Endpoint List
+
+| Endpoint | Path | Description |
+|----------|------|-------------|
+| getUpdates | `getupdates` | Long-poll for new messages |
+| sendMessage | `sendmessage` | Send a message (text/image/video/file) |
+| getUploadUrl | `getuploadurl` | Get CDN upload pre-signed URL |
+| getConfig | `getconfig` | Get account config (typing ticket, etc.) |
+| sendTyping | `sendtyping` | Send/cancel typing status indicator |
+
+### getUpdates
+
+Long-polling endpoint. The server responds when new messages arrive or on timeout.
+
+**Request body:**
+
+```json
+{
+  "get_updates_buf": ""
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `get_updates_buf` | `string` | Sync cursor from the previous response; empty string for the first request |
+
+**Response body:**
+
+```json
+{
+  "ret": 0,
+  "msgs": [...],
+  "get_updates_buf": "<new cursor>",
+  "longpolling_timeout_ms": 35000
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `ret` | `number` | Return code, `0` = success |
+| `errcode` | `number?` | Error code (e.g., `-14` = session timeout) |
+| `errmsg` | `string?` | Error description |
+| `msgs` | `WeixinMessage[]` | Message list (structure below) |
+| `get_updates_buf` | `string` | New sync cursor to pass in the next request |
+| `longpolling_timeout_ms` | `number?` | Server-suggested long-poll timeout for the next request (ms) |
+
+### sendMessage
+
+Send a message to a user.
+
+**Request body:**
+
+```json
+{
+  "msg": {
+    "to_user_id": "<target user ID>",
+    "context_token": "<conversation context token>",
+    "item_list": [
+      {
+        "type": 1,
+        "text_item": { "text": "Hello" }
+      }
+    ]
+  }
+}
+```
+
+### getUploadUrl
+
+Get CDN upload pre-signed parameters. Call this endpoint before uploading a file to obtain `upload_param` and `thumb_upload_param`.
+
+**Request body:**
+
+```json
+{
+  "filekey": "<file identifier>",
+  "media_type": 1,
+  "to_user_id": "<target user ID>",
+  "rawsize": 12345,
+  "rawfilemd5": "<plaintext MD5>",
+  "filesize": 12352,
+  "thumb_rawsize": 1024,
+  "thumb_rawfilemd5": "<thumbnail plaintext MD5>",
+  "thumb_filesize": 1040
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `media_type` | `number` | `1` = IMAGE, `2` = VIDEO, `3` = FILE |
+| `rawsize` | `number` | Original file plaintext size |
+| `rawfilemd5` | `string` | Original file plaintext MD5 |
+| `filesize` | `number` | Ciphertext size after AES-128-ECB encryption |
+| `thumb_rawsize` | `number?` | Thumbnail plaintext size (required for IMAGE/VIDEO) |
+| `thumb_rawfilemd5` | `string?` | Thumbnail plaintext MD5 (required for IMAGE/VIDEO) |
+| `thumb_filesize` | `number?` | Thumbnail ciphertext size (required for IMAGE/VIDEO) |
+
+**Response body:**
+
+```json
+{
+  "upload_param": "<original image upload encrypted parameters>",
+  "thumb_upload_param": "<thumbnail upload encrypted parameters>"
+}
+```
+
+### getConfig
+
+Get account configuration, including the typing ticket.
+
+**Request body:**
+
+```json
+{
+  "ilink_user_id": "<user ID>",
+  "context_token": "<optional, conversation context token>"
+}
+```
+
+**Response body:**
+
+```json
+{
+  "ret": 0,
+  "typing_ticket": "<base64-encoded typing ticket>"
+}
+```
+
+### sendTyping
+
+Send or cancel the typing status indicator.
+
+**Request body:**
+
+```json
+{
+  "ilink_user_id": "<user ID>",
+  "typing_ticket": "<obtained from getConfig>",
+  "status": 1
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `status` | `number` | `1` = typing, `2` = cancel typing |
+
+### Message Structure
+
+#### WeixinMessage
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `seq` | `number?` | Message sequence number |
+| `message_id` | `number?` | Unique message ID |
+| `from_user_id` | `string?` | Sender ID |
+| `to_user_id` | `string?` | Receiver ID |
+| `create_time_ms` | `number?` | Creation timestamp (ms) |
+| `session_id` | `string?` | Session ID |
+| `message_type` | `number?` | `1` = USER, `2` = BOT |
+| `message_state` | `number?` | `0` = NEW, `1` = GENERATING, `2` = FINISH |
+| `item_list` | `MessageItem[]?` | Message content list |
+| `context_token` | `string?` | Conversation context token, must be passed back when replying |
+
+#### MessageItem
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | `number` | `1` TEXT, `2` IMAGE, `3` VOICE, `4` FILE, `5` VIDEO |
+| `text_item` | `{ text: string }?` | Text content |
+| `image_item` | `ImageItem?` | Image (with CDN reference and AES key) |
+| `voice_item` | `VoiceItem?` | Voice (SILK encoded) |
+| `file_item` | `FileItem?` | File attachment |
+| `video_item` | `VideoItem?` | Video |
+| `ref_msg` | `RefMessage?` | Referenced message |
+
+#### CDN Media Reference (CDNMedia)
+
+All media types (image/voice/file/video) are transferred via CDN using AES-128-ECB encryption:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `encrypt_query_param` | `string?` | Encrypted parameters for CDN download/upload |
+| `aes_key` | `string?` | Base64-encoded AES-128 key |
+
+### CDN Upload Flow
+
+1. Calculate the file's plaintext size, MD5, and ciphertext size after AES-128-ECB encryption
+2. If a thumbnail is needed (image/video), calculate the thumbnail's plaintext and ciphertext parameters as well
+3. Call `getUploadUrl` to get `upload_param` (and `thumb_upload_param`)
+4. Encrypt the file content with AES-128-ECB and PUT upload to the CDN URL
+5. Encrypt and upload the thumbnail in the same way
+6. Use the returned `encrypt_query_param` to construct a `CDNMedia` reference, include it in the `MessageItem`, and send
+
+> For complete type definitions, see [`src/api/types.ts`](src/api/types.ts). For API call implementations, see [`src/api/api.ts`](src/api/api.ts).
+
+## Uninstall
+
+```bash
+openclaw plugins uninstall @netcat-ai/openclaw-weixin
+```
+
+## Troubleshooting
+
+### "requires OpenClaw >=2026.3.22" error
+
+Your OpenClaw version is too old for this plugin version. Check with:
+
+```bash
+openclaw --version
+```
+
+Upgrade OpenClaw before installing this plugin.
+
+### Channel shows "OK" but doesn't connect
+
+Ensure `plugins.entries.openclaw-weixin.enabled` is `true` in `~/.openclaw/openclaw.json`:
+
+```bash
+openclaw config set plugins.entries.openclaw-weixin.enabled true
+openclaw gateway restart
+```

package/README.zh_CN.md

@@ -0,0 +1,351 @@
+# 微信
+
+[English](./README.md)
+
+OpenClaw 的微信渠道插件，支持通过扫码完成登录授权。
+
+## 兼容性
+
+| 插件版本 | OpenClaw 版本            | npm dist-tag | 状态   |
+|---------|--------------------------|--------------|--------|
+| 2.0.x   | >=2026.3.22              | `latest`     | 活跃   |
+| 1.0.x   | >=2026.1.0 <2026.3.22    | `legacy`     | 维护中 |
+
+> 插件在启动时会检查宿主版本，如果运行的 OpenClaw 版本超出支持范围，插件将拒绝加载。
+
+## 前提条件
+
+已安装 [OpenClaw](https://docs.openclaw.ai/install)（需要 `openclaw` CLI 可用）。
+
+查看版本：`openclaw --version`
+
+## 安装
+
+```bash
+openclaw plugins install @netcat-ai/openclaw-weixin
+```
+
+启用插件：
+
+```bash
+openclaw config set plugins.entries.openclaw-weixin.enabled true
+```
+
+使用自定义 iLink 后端时，在扫码登录前设置本次登录使用的服务地址：
+
+```bash
+openclaw config set channels.openclaw-weixin.baseUrl http://127.0.0.1:38080
+```
+
+开始扫码登录：
+
+```bash
+openclaw channels login --channel openclaw-weixin
+```
+
+终端会显示一个二维码，用手机扫码并在手机上确认授权。确认后，登录凭证和本次使用的服务地址会自动保存到该账号。
+
+之后修改渠道级 `baseUrl` 只影响下一次新账号登录，不会改变已有账号使用的后端。因此，同一个 `openclaw-weixin` 渠道可以同时连接官方后端和多个 Webox。
+
+重启 gateway：
+
+```bash
+openclaw gateway restart
+```
+
+## 添加更多微信账号
+
+登录官方后端：
+
+```bash
+openclaw config set channels.openclaw-weixin.baseUrl https://ilinkai.weixin.qq.com
+openclaw channels login --channel openclaw-weixin
+```
+
+登录另一个 Webox：
+
+```bash
+openclaw config set channels.openclaw-weixin.baseUrl http://127.0.0.1:38081
+openclaw channels login --channel openclaw-weixin
+```
+
+每次扫码登录都会创建一个新的账号条目，支持多个微信号同时在线。
+
+## 多账号上下文隔离
+
+默认情况下，私聊可能共用同一会话桶。**多个微信号同时登录**时，建议按「账号 + 渠道 + 对端」隔离：
+
+```bash
+openclaw config set session.dmScope per-account-channel-peer
+```
+
+## 自定义 BotAgent（可选）
+
+每条出站请求会带一个自我声明的 `bot_agent` 字段——类似 HTTP `User-Agent`——用于
+后台日志归因和监控聚合。**默认值为 `OpenClaw`**。声明自己的应用名能让你的流量
+在后台日志中更容易识别。
+
+在 `openclaw.json` 中加一行即可：
+
+```json
+{
+  "channels": {
+    "openclaw-weixin": {
+      "botAgent": "MyBot/1.2.0"
+    }
+  }
+}
+```
+
+**格式规范**（UA 风格）：
+
+- 一个或多个 `Name/Version` token，空格分隔
+- 每个 token 可选地跟一个 ` (comment)`
+- 仅允许 ASCII 字符；总长 ≤ 256 字节
+- 不合规的 token 在清洗时静默丢弃；如果最终为空，回退到 `OpenClaw`
+
+可直接使用的示例：
+
+- `MyBot/1.2.0`
+- `MyBot/1.2.0 (region=cn;env=prod)`
+- `MyBot/1.2.0 LangChain/0.3.5`
+- `MyBot/1.2.0-rc.1+build.5`
+
+**注意**：`bot_agent` 仅用于观测，**不参与鉴权或路由**。当前本插件实例下所有
+已注册的 agent 共享同一个 `botAgent` 声明；如有需要按 agent 单独标识的场景，
+可在后续版本扩展配置。
+
+## 后端 API 协议
+
+本插件通过 HTTP JSON API 与后端网关通信。二次开发者若需对接自有后端，需实现以下接口。
+
+所有接口均为 `POST`，请求和响应均为 JSON。通用请求头：
+
+| Header | 说明 |
+|--------|------|
+| `Content-Type` | `application/json` |
+| `AuthorizationType` | 固定值 `ilink_bot_token` |
+| `Authorization` | `Bearer <token>`（登录后获取） |
+| `X-WECHAT-UIN` | 随机 uint32 的 base64 编码 |
+
+### 接口列表
+
+| 接口 | 路径 | 说明 |
+|------|------|------|
+| getUpdates | `getupdates` | 长轮询获取新消息 |
+| sendMessage | `sendmessage` | 发送消息（文本/图片/视频/文件） |
+| getUploadUrl | `getuploadurl` | 获取 CDN 上传预签名 URL |
+| getConfig | `getconfig` | 获取账号配置（typing ticket 等） |
+| sendTyping | `sendtyping` | 发送/取消输入状态指示 |
+
+### getUpdates
+
+长轮询接口。服务端在有新消息或超时后返回。
+
+**请求体：**
+
+```json
+{
+  "get_updates_buf": ""
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `get_updates_buf` | `string` | 上次响应返回的同步游标，首次请求传空字符串 |
+
+**响应体：**
+
+```json
+{
+  "ret": 0,
+  "msgs": [...],
+  "get_updates_buf": "<新游标>",
+  "longpolling_timeout_ms": 35000
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `ret` | `number` | 返回码，`0` = 成功 |
+| `errcode` | `number?` | 错误码（如 `-14` = 会话超时） |
+| `errmsg` | `string?` | 错误描述 |
+| `msgs` | `WeixinMessage[]` | 消息列表（结构见下方） |
+| `get_updates_buf` | `string` | 新的同步游标，下次请求时回传 |
+| `longpolling_timeout_ms` | `number?` | 服务端建议的下次长轮询超时（ms） |
+
+### sendMessage
+
+发送一条消息给用户。
+
+**请求体：**
+
+```json
+{
+  "msg": {
+    "to_user_id": "<目标用户 ID>",
+    "context_token": "<会话上下文令牌>",
+    "item_list": [
+      {
+        "type": 1,
+        "text_item": { "text": "你好" }
+      }
+    ]
+  }
+}
+```
+
+### getUploadUrl
+
+获取 CDN 上传预签名参数。上传文件前需先调用此接口获取 `upload_param` 和 `thumb_upload_param`。
+
+**请求体：**
+
+```json
+{
+  "filekey": "<文件标识>",
+  "media_type": 1,
+  "to_user_id": "<目标用户 ID>",
+  "rawsize": 12345,
+  "rawfilemd5": "<明文 MD5>",
+  "filesize": 12352,
+  "thumb_rawsize": 1024,
+  "thumb_rawfilemd5": "<缩略图明文 MD5>",
+  "thumb_filesize": 1040
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `media_type` | `number` | `1` = IMAGE, `2` = VIDEO, `3` = FILE |
+| `rawsize` | `number` | 原文件明文大小 |
+| `rawfilemd5` | `string` | 原文件明文 MD5 |
+| `filesize` | `number` | AES-128-ECB 加密后的密文大小 |
+| `thumb_rawsize` | `number?` | 缩略图明文大小（IMAGE/VIDEO 时必填） |
+| `thumb_rawfilemd5` | `string?` | 缩略图明文 MD5（IMAGE/VIDEO 时必填） |
+| `thumb_filesize` | `number?` | 缩略图密文大小（IMAGE/VIDEO 时必填） |
+
+**响应体：**
+
+```json
+{
+  "upload_param": "<原图上传加密参数>",
+  "thumb_upload_param": "<缩略图上传加密参数>"
+}
+```
+
+### getConfig
+
+获取账号配置，包括 typing ticket。
+
+**请求体：**
+
+```json
+{
+  "ilink_user_id": "<用户 ID>",
+  "context_token": "<可选，会话上下文令牌>"
+}
+```
+
+**响应体：**
+
+```json
+{
+  "ret": 0,
+  "typing_ticket": "<base64 编码的 typing ticket>"
+}
+```
+
+### sendTyping
+
+发送或取消输入状态指示。
+
+**请求体：**
+
+```json
+{
+  "ilink_user_id": "<用户 ID>",
+  "typing_ticket": "<从 getConfig 获取>",
+  "status": 1
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `status` | `number` | `1` = 正在输入，`2` = 取消输入 |
+
+### 消息结构
+
+#### WeixinMessage
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `seq` | `number?` | 消息序列号 |
+| `message_id` | `number?` | 消息唯一 ID |
+| `from_user_id` | `string?` | 发送者 ID |
+| `to_user_id` | `string?` | 接收者 ID |
+| `create_time_ms` | `number?` | 创建时间戳（ms） |
+| `session_id` | `string?` | 会话 ID |
+| `message_type` | `number?` | `1` = USER, `2` = BOT |
+| `message_state` | `number?` | `0` = NEW, `1` = GENERATING, `2` = FINISH |
+| `item_list` | `MessageItem[]?` | 消息内容列表 |
+| `context_token` | `string?` | 会话上下文令牌，回复时需回传 |
+
+#### MessageItem
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `type` | `number` | `1` TEXT, `2` IMAGE, `3` VOICE, `4` FILE, `5` VIDEO |
+| `text_item` | `{ text: string }?` | 文本内容 |
+| `image_item` | `ImageItem?` | 图片（含 CDN 引用和 AES 密钥） |
+| `voice_item` | `VoiceItem?` | 语音（SILK 编码） |
+| `file_item` | `FileItem?` | 文件附件 |
+| `video_item` | `VideoItem?` | 视频 |
+| `ref_msg` | `RefMessage?` | 引用消息 |
+
+#### CDN 媒体引用 (CDNMedia)
+
+所有媒体类型（图片/语音/文件/视频）通过 CDN 传输，使用 AES-128-ECB 加密：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `encrypt_query_param` | `string?` | CDN 下载/上传的加密参数 |
+| `aes_key` | `string?` | base64 编码的 AES-128 密钥 |
+
+### CDN 上传流程
+
+1. 计算文件明文大小、MD5，以及 AES-128-ECB 加密后的密文大小
+2. 如需缩略图（图片/视频），同样计算缩略图的明文和密文参数
+3. 调用 `getUploadUrl` 获取 `upload_param`（和 `thumb_upload_param`）
+4. 使用 AES-128-ECB 加密文件内容，PUT 上传到 CDN URL
+5. 缩略图同理加密并上传
+6. 使用返回的 `encrypt_query_param` 构造 `CDNMedia` 引用，放入 `MessageItem` 发送
+
+> 完整的类型定义见 [`src/api/types.ts`](src/api/types.ts)，API 调用实现见 [`src/api/api.ts`](src/api/api.ts)。
+
+## 卸载
+
+```bash
+openclaw plugins uninstall @netcat-ai/openclaw-weixin
+```
+
+## 故障排查
+
+### "requires OpenClaw >=2026.3.22" 报错
+
+你的 OpenClaw 版本太旧，不兼容当前插件版本。检查版本：
+
+```bash
+openclaw --version
+```
+
+请先升级 OpenClaw，再安装此插件。
+
+### Channel 显示 "OK" 但未连接
+
+确保 `~/.openclaw/openclaw.json` 中 `plugins.entries.openclaw-weixin.enabled` 为 `true`：
+
+```bash
+openclaw config set plugins.entries.openclaw-weixin.enabled true
+openclaw gateway restart
+```