OpenClaw 微信插件 v2.0.1 → v2.1.1 差异分析

一句话总结：v2.1.1 主要解决了 CDN URL 服务端直传、扫码登录 IDC 跨区重定向、以及 iLink 协议头规范化三个问题，同时精简了 CLI 工具和配置项。

发布日期: 2026-03-30

变更概览

新增文件： src/weixin-cli.ts（替代 src/log-upload.ts）

删除文件： src/log-upload.ts（149 行 → 37 行，大幅精简）

1. 🔑 CDN URL 服务端直传（最重要的变更）

问题： v2.0.1 中，图片/语音/文件的上传和下载 URL 需要客户端自己拼接（cdnBaseUrl + upload_param/encrypt_query_param）。这依赖客户端正确拼接，且在 CDN 节点变化时容易出错。

v2.1.1 方案： 服务端现在可以直接返回完整 URL（upload_full_url / full_url），客户端优先使用，拼接降级为 fallback。

涉及文件：

• src/api/types.ts — 新增 upload_full_url 和 full_url 字段
• src/cdn/cdn-upload.ts — 上传优先用 uploadFullUrl
• src/cdn/cdn-url.ts — 新增 ENABLE_CDN_URL_FALLBACK 开关（默认 true）
• src/cdn/pic-decrypt.ts — 下载函数新增 fullUrl 参数，优先使用
• src/cdn/upload.ts — 上传流程适配双 URL 源
• src/media/media-download.ts — 所有媒体类型（图片/语音/文件）适配 full_url
• src/messaging/process-message.ts — 媒体检测逻辑从只检查 encrypt_query_param 改为 encrypt_query_param || full_url

影响： 这是一个面向 iLink 协议演进的改动。随着微信 iLink 平台成熟，CDN 调度可能随时切换节点，服务端直传 URL 能确保客户端不需要了解 CDN 拓扑。ENABLE_CDN_URL_FALLBACK = true 保证了向后兼容。

2. 🔄 扫码登录 IDC 重定向（关键稳定性改进）

问题： v2.0.1 的 QR 扫码登录只处理 wait/scaned/confirmed/expired 四种状态。如果用户微信账号归属的 IDC（数据中心）和二维码发起的 IDC 不同，登录会卡住或失败。

v2.1.1 方案： 新增 scaned_but_redirect 状态。当用户扫码后，如果需要跳转到另一个 IDC，服务端返回 redirect_host，客户端将后续轮询切换到新地址。

关键代码（src/auth/login-qr.ts）：

// 新增状态
status?: "wait" | "scaned" | "confirmed" | "expired" | "scaned_but_redirect";

// 新增字段
redirect_host?: string;
currentApiBaseUrl?: string;

// 处理重定向
case "scaned_but_redirect": {
  const redirectHost = statusResponse.redirect_host;
  if (redirectHost) {
    const newBaseUrl = `https://${redirectHost}`;
    activeLogin.currentApiBaseUrl = newBaseUrl;
  }
  break;
}

其他登录改进：

• 二维码请求固定走 https://ilinkai.weixin.qq.com（不再依赖用户配置的 apiBaseUrl）
• 统一使用 apiGetFetch() 替代手动 fetch()，自动带上 iLink 协议头
• 网关超时（如 Cloudflare 524）不再抛异常，改为 warn + 继续轮询
• 新增 GET_QRCODE_TIMEOUT_MS = 5000 独立超时
• 不再需要用户提前配置 baseUrl 才能登录

影响： 这解决了跨区域用户（如微信号归属广州 IDC 但 QR 发到上海 IDC）的登录失败问题，是一个实际生产环境中会遇到的稳定性 bug。

3. 📡 iLink 协议头规范化

问题： v2.0.1 的 API 请求头缺少标准 iLink 身份标识。

v2.1.1 方案： 所有 API 请求（GET 和 POST）统一携带：

iLink-App-Id: bot          （从 package.json 新增字段 ilink_appid 读取）
iLink-App-ClientVersion: 131329  （版本号编码为 uint32: major<<16 | minor<<8 | patch）

涉及文件：

• package.json — 新增 "ilink_appid": "bot" 顶层字段
• src/api/api.ts — 重构 readChannelVersion() 为 readPackageJson()，新增 buildClientVersion() 和 buildCommonHeaders()

版本编码示例： 2.1.1 → 0x00020101 = 131329

影响： 这是协议合规性改动。iLink 平台可能开始要求这些头来做流量区分、版本兼容路由、或统计分析。不加可能导致未来请求被拒绝。

4. 🧹 CLI 工具精简

删除： src/log-upload.ts（149 行）— 移除了 openclaw openclaw-weixin logs-upload 命令和 logUploadUrl 配置项

新增： src/weixin-cli.ts（37 行）— 只保留 openclaw openclaw-weixin uninstall 命令

// v2.1.1 的完整 CLI，非常精简
root.command("uninstall")
  .description("Uninstall the Weixin plugin (cleans up channel config automatically)")
  .action(async () => {
    // 清理 channels.openclaw-weixin 配置 + 卸载插件
  });

影响： 日志上传功能被移除（可能集成到了平台侧或不再需要）。卸载命令从 log-upload 文件中独立出来，职责更清晰。

5. 📋 其他改动

peerDependencies 移除

v2.0.1 要求 openclaw >=2026.3.22，v2.1.1 删除了这个约束。但 src/compat.ts 中的运行时版本检查仍然存在，所以实际兼容性要求没变——只是从安装时报错改为运行时报错。

兼容性提示信息更新

- `Please upgrade OpenClaw, or install openclaw-weixin@1.x (legacy) for older hosts:\n` +
- `  openclaw plugins install @tencent-weixin/openclaw-weixin@legacy`
+ `Please upgrade OpenClaw, or install the compatible track for older hosts:\n` +
+ `  npx @tencent-weixin/openclaw-weixin-cli install`

降级路径从 @legacy tag 改为独立 CLI 工具安装。

System Prompt 新增 MEDIA 指令格式约束

IMPORTANT: When outputting a MEDIA: directive to send a file,
the MEDIA: tag MUST be on its own line — never inline with other text.

解决了 AI 把 MEDIA: 标签和文字混在一行导致文件发送失败的问题。

配置项移除

• logUploadUrl 从 WeixinConfigSchema 中删除

升级建议

风险评估： 低风险。所有改动都有 fallback 机制（CDN URL fallback、轮询容错），不会破坏现有功能。

文件变更清单

报告生成: 2026-03-30 | 托尼 for Jay