Weixin-Claw

English

微信 iLink 协议库 —— weixin-bridge CLI 的核心运行时。

本包提供微信登录、消息收发、媒体上传/下载、CDN 加密等能力，供 weixin-bridge CLI 实现微信 ↔ Claude Desktop 桥接。

快速开始

通常你不需要直接安装本包，安装 CLI 即可：

npm install -g @weixin-claw/cli --registry https://registry.npmjs.org/

然后：

weixin-bridge login      # 扫码登录微信
weixin-bridge doctor     # 检查环境
weixin-bridge bridge     # 启动微信 ↔ Claude 桥接

功能

• 扫码登录（iLink bot 网关）
• 多账号支持（再扫一次即可添加）
• 长轮询消息接收（getUpdates）
• 文本 / 图片 / 语音 / 文件 / 视频消息收发
• CDN 媒体传输 + AES-128-ECB 加密
• 输入状态指示（正在输入）
• 用户白名单管理

CLI 命令

weixin-bridge login [--account <id>]               扫码登录
weixin-bridge bridge [--account <id>] [选项]        启动桥接（长驻运行）
weixin-bridge dispatch "<prompt>"                   一次性任务执行
weixin-bridge doctor                                环境检查
weixin-bridge status                                查看运行状态
weixin-bridge help                                  帮助

bridge 选项

| 选项 | 说明 | |------|------| | --model <model> | Claude 模型（默认 claude-sonnet-4-6） | | --permission-mode <mode> | 权限模式（默认 bypassPermissions） | | --max-sessions <n> | 最大并发会话数（默认 5） | | --allowed-users <id1,id2> | 用户白名单（逗号分隔） |

微信斜杠命令

在微信对话中发送以下命令：

| 命令 | 说明 | |------|------| | /help | 显示可用命令 | | /reset | 重置 Claude 会话 | | /status | 查看会话状态 | | /whoami | 查看你的用户 ID | | /echo <text> | 回显测试（含延迟） | | /export | 导出当前对话 | | /dispatch <task> | 一次性任务 | | /cron add <cron> <task> | 添加定时任务 | | /cron list | 列出定时任务 | | /cron remove <id> | 删除定时任务 | | /cron pause <id> | 暂停定时任务 | | /cron resume <id> | 恢复定时任务 |

MCP Server（Claude Desktop 集成）

weixin-bridge 提供 MCP Server，可在 Claude Desktop 中直接操作微信：

| 工具 | 说明 | |------|------| | weixin_send_text | 发送文本消息 | | weixin_get_updates | 拉取最新消息 | | weixin_get_contacts | 查看联系人 | | weixin_send_file | 发送文件 | | weixin_list_sessions | 查看活跃会话 | | weixin_send_typing | 发送输入状态 |

二次开发

如果你想基于协议库做二次开发：

npm install @weixin-claw/core

import { loginQr } from "@weixin-claw/core/auth/login-qr.js";
import { getUpdates, sendMessage } from "@weixin-claw/core/api/api.js";
import { downloadMediaFromItem } from "@weixin-claw/core/media/media-download.js";

后端 API 协议

本库通过 HTTP JSON API 与微信 iLink bot 网关通信。所有接口均为 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

长轮询接口。服务端在有新消息或超时后返回。

请求体：

{
  "get_updates_buf": ""
}

| 字段 | 类型 | 说明 | |------|------|------| | get_updates_buf | string | 上次响应返回的同步游标，首次请求传空字符串 |

响应体：

{
  "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

发送一条消息给用户。

请求体：

{
  "msg": {
    "to_user_id": "<目标用户 ID>",
    "context_token": "<会话上下文令牌>",
    "item_list": [
      {
        "type": 1,
        "text_item": { "text": "你好" }
      }
    ]
  }
}

getUploadUrl

获取 CDN 上传预签名参数。上传文件前需先调用此接口获取 upload_param 和 thumb_upload_param。

请求体：

{
  "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 时必填） |

响应体：

{
  "upload_param": "<原图上传加密参数>",
  "thumb_upload_param": "<缩略图上传加密参数>"
}

getConfig

获取账号配置，包括 typing ticket。

请求体：

{
  "ilink_user_id": "<用户 ID>",
  "context_token": "<可选，会话上下文令牌>"
}

响应体：

{
  "ret": 0,
  "typing_ticket": "<base64 编码的 typing ticket>"
}

sendTyping

发送或取消输入状态指示。

请求体：

{
  "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，API 调用实现见 src/api/api.ts。