@tencent-weixin/openclaw-weixin 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+[简体中文](CHANGELOG.zh_CN.md)
+
+This project follows the [Keep a Changelog](https://keepachangelog.com/) format.

package/CHANGELOG.zh_CN.md

@@ -0,0 +1,3 @@
+# 变更日志
+
+本项目遵循 [Keep a Changelog](https://keepachangelog.com/) 格式。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tencent Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,271 @@
+# WeChat
+
+[简体中文](README.zh_CN.md)
+
+OpenClaw's WeChat channel plugin, supporting login authorization via QR code scanning.
+
+## Prerequisites
+
+[OpenClaw](https://docs.openclaw.ai/install) must be installed (the `openclaw` CLI needs to be available).
+
+## Quick Install
+
+```bash
+npx -y @tencent-weixin/openclaw-weixin-cli install
+```
+
+## Manual Installation
+
+If the quick install doesn't work, follow these steps manually:
+
+### 1. Install the plugin
+
+```bash
+openclaw plugins install "@tencent-weixin/openclaw-weixin"
+```
+
+### 2. Enable the plugin
+
+```bash
+openclaw config set plugins.entries.openclaw-weixin.enabled true
+```
+
+### 3. 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 will be saved locally automatically — no further action is needed.
+
+### 4. Restart the gateway
+
+```bash
+openclaw gateway restart
+```
+
+## Adding More WeChat Accounts
+
+```bash
+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, all channels share the same AI conversation context. To isolate conversation context for each WeChat account:
+
+```bash
+openclaw config set agents.mode per-channel-per-peer
+```
+
+This gives each "WeChat account + message sender" combination its own independent AI memory, preventing context cross-talk between accounts.
+
+## 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).

package/README.zh_CN.md

@@ -0,0 +1,269 @@
+# 微信
+
+OpenClaw 的微信渠道插件，支持通过扫码完成登录授权。
+
+## 前提条件
+
+已安装 [OpenClaw](https://docs.openclaw.ai/install)（需要 `openclaw` CLI 可用）。
+
+## 一键安装
+
+```bash
+npx -y @tencent-weixin/openclaw-weixin-cli install
+```
+
+## 手动安装
+
+如果一键安装不适用，可以按以下步骤手动操作：
+
+### 1. 安装插件
+
+```bash
+openclaw plugins install "@tencent-weixin/openclaw-weixin"
+```
+
+### 2. 启用插件
+
+```bash
+openclaw config set plugins.entries.openclaw-weixin.enabled true
+```
+
+### 3. 扫码登录
+
+```bash
+openclaw channels login --channel openclaw-weixin
+```
+
+终端会显示一个二维码，用手机扫码并在手机上确认授权。确认后，登录凭证会自动保存到本地，无需额外操作。
+
+### 4. 重启 gateway
+
+```bash
+openclaw gateway restart
+```
+
+## 添加更多微信账号
+
+```bash
+openclaw channels login --channel openclaw-weixin
+```
+
+每次扫码登录都会创建一个新的账号条目，支持多个微信号同时在线。
+
+## 多账号上下文隔离
+
+默认情况下，所有渠道的 AI 会话共享同一个上下文。如果希望每个微信账号的对话上下文相互隔离：
+
+```bash
+openclaw config set agents.mode per-channel-per-peer
+```
+
+这样每个「微信账号 + 发消息用户」组合都会拥有独立的 AI 记忆，账号之间不会串台。
+
+## 后端 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)。

package/index.ts

@@ -0,0 +1,27 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { buildChannelConfigSchema } from "openclaw/plugin-sdk";
+
+import { weixinPlugin } from "./src/channel.js";
+import { WeixinConfigSchema } from "./src/config/config-schema.js";
+import { registerWeixinCli } from "./src/log-upload.js";
+import { setWeixinRuntime } from "./src/runtime.js";
+
+const plugin = {
+  id: "openclaw-weixin",
+  name: "Weixin",
+  description: "Weixin channel (getUpdates long-poll + sendMessage)",
+  configSchema: buildChannelConfigSchema(WeixinConfigSchema),
+  register(api: OpenClawPluginApi) {
+    if (!api?.runtime) {
+      throw new Error("[weixin] api.runtime is not available in register()");
+    }
+    setWeixinRuntime(api.runtime);
+
+    api.registerChannel({ plugin: weixinPlugin });
+    api.registerCli(({ program, config }) => registerWeixinCli({ program, config }), {
+      commands: ["openclaw-weixin"],
+    });
+  },
+};
+
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1,9 @@
+{
+  "id": "openclaw-weixin",
+  "channels": ["openclaw-weixin"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@tencent-weixin/openclaw-weixin",
+  "version": "1.0.0",
+  "description": "OpenClaw Weixin channel",
+  "license": "MIT",
+  "author": "Tencent",
+  "type": "module",
+  "files": [
+    "src/",
+    "!src/**/*.test.ts",
+    "!src/**/node_modules/",
+    "index.ts",
+    "openclaw.plugin.json",
+    "README.md",
+    "README.zh_CN.md",
+    "CHANGELOG.md",
+    "CHANGELOG.zh_CN.md"
+  ],
+  "scripts": {
+    "test": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "build": "tsc",
+    "prepublishOnly": "npm run typecheck && npm run build"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "qrcode-terminal": "0.12.0",
+    "zod": "4.3.6"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^3.1.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.1.0"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "channel": {
+      "id": "openclaw-weixin",
+      "label": "Weixin",
+      "selectionLabel": "Weixin",
+      "docsPath": "/channels/openclaw-weixin",
+      "docsLabel": "openclaw-weixin",
+      "blurb": "Weixin channel",
+      "order": 75
+    },
+    "install": {
+      "npmSpec": "@tencent-weixin/openclaw-weixin",
+      "defaultChoice": "npm"
+    }
+  }
+}