@tencent-weixin/openclaw-weixin 2.1.9 → 2.3.1

package/README.md

@@ -72,6 +72,45 @@ By default, DMs can share one session bucket. For **multiple logged-in WeChat ac
 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.

package/README.zh_CN.md

@@ -71,6 +71,42 @@ openclaw channels login --channel openclaw-weixin
 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 与后端网关通信。二次开发者若需对接自有后端，需实现以下接口。

package/openclaw.plugin.json

@@ -1,6 +1,6 @@
 {
   "id": "openclaw-weixin",
-  "version": "2.1.9",
+  "version": "2.3.1",
   "channels": [
     "openclaw-weixin"
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tencent-weixin/openclaw-weixin",
-  "version": "2.1.9",
+  "version": "2.3.1",
   "description": "OpenClaw Weixin channel",
   "license": "MIT",
   "author": "Tencent",

package/src/api/api.ts

@@ -3,7 +3,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { loadConfigRouteTag } from "../auth/accounts.js";
+import { loadConfigBotAgent, loadConfigRouteTag } from "../auth/accounts.js";
 import { logger } from "../util/logger.js";
 import { redactBody, redactUrl } from "../util/redact.js";
 
@@ -13,6 +13,8 @@ import type {
   GetUploadUrlResp,
   GetUpdatesReq,
   GetUpdatesResp,
+  NotifyStopResp,
+  NotifyStartResp,
   SendMessageReq,
   SendTypingReq,
   GetConfigResp,
@@ -68,9 +70,105 @@ function buildClientVersion(version: string): number {
 
 const ILINK_APP_CLIENT_VERSION: number = buildClientVersion(pkg.version ?? "0.0.0");
 
+/**
+ * Default `bot_agent` value used when the upstream app does not declare one.
+ * Mirrors the role of HTTP `User-Agent`'s implicit "no UA" fallback.
+ */
+const DEFAULT_BOT_AGENT = "OpenClaw";
+
+/** Maximum length (bytes) of the sanitized `bot_agent` string. */
+const BOT_AGENT_MAX_LEN = 256;
+
+/**
+ * Sanitize a user-supplied `botAgent` config value into a wire-safe string.
+ *
+ * Grammar (UA-style):
+ *   bot_agent = product *( SP product )
+ *   product   = name "/" version [ SP "(" comment ")" ]
+ *   name      = 1*32( ALPHA / DIGIT / "_" / "." / "-" )
+ *   version   = 1*32( ALPHA / DIGIT / "_" / "." / "+" / "-" )
+ *   comment   = 1*64( printable ASCII minus "(" ")" )
+ *
+ * Tokens that fail to parse are dropped silently (no partial tokens kept).
+ * Returns `DEFAULT_BOT_AGENT` when the input is empty / all tokens dropped /
+ * the result exceeds the length cap after truncation.
+ */
+export function sanitizeBotAgent(raw: string | undefined): string {
+  if (!raw || typeof raw !== "string") return DEFAULT_BOT_AGENT;
+  const trimmed = raw.trim();
+  if (!trimmed) return DEFAULT_BOT_AGENT;
+
+  const productRe = /^[A-Za-z0-9_.\-]{1,32}\/[A-Za-z0-9_.+\-]{1,32}$/;
+  const commentCharRe = /^[\x20-\x27\x2A-\x7E]{1,64}$/;
+
+  // Tokenize on whitespace, but keep `(comment)` glued to the preceding product.
+  // Strategy: split by spaces, then re-attach any token that starts with "(".
+  const rawTokens = trimmed.split(/\s+/);
+  const tokens: string[] = [];
+  for (let i = 0; i < rawTokens.length; i += 1) {
+    const tok = rawTokens[i];
+    if (tok.startsWith("(") && !tok.endsWith(")")) {
+      // Multi-word comment; greedily collect until we find the closing ")".
+      let acc = tok;
+      while (i + 1 < rawTokens.length && !acc.endsWith(")")) {
+        i += 1;
+        acc += " " + rawTokens[i];
+      }
+      tokens.push(acc);
+    } else {
+      tokens.push(tok);
+    }
+  }
+
+  const accepted: string[] = [];
+  let pendingProduct: string | null = null;
+  for (const tok of tokens) {
+    if (tok.startsWith("(") && tok.endsWith(")")) {
+      const inner = tok.slice(1, -1);
+      if (pendingProduct && commentCharRe.test(inner)) {
+        accepted.push(`${pendingProduct} (${inner})`);
+        pendingProduct = null;
+      } else {
+        if (pendingProduct) {
+          accepted.push(pendingProduct);
+          pendingProduct = null;
+        }
+      }
+      continue;
+    }
+    if (pendingProduct) {
+      accepted.push(pendingProduct);
+      pendingProduct = null;
+    }
+    if (productRe.test(tok)) {
+      pendingProduct = tok;
+    }
+  }
+  if (pendingProduct) accepted.push(pendingProduct);
+
+  if (accepted.length === 0) return DEFAULT_BOT_AGENT;
+
+  const joined = accepted.join(" ");
+  if (Buffer.byteLength(joined, "utf-8") <= BOT_AGENT_MAX_LEN) return joined;
+
+  // Truncate by dropping trailing tokens until under the cap.
+  const truncated: string[] = [];
+  let len = 0;
+  for (const t of accepted) {
+    const add = (truncated.length === 0 ? 0 : 1) + Buffer.byteLength(t, "utf-8");
+    if (len + add > BOT_AGENT_MAX_LEN) break;
+    truncated.push(t);
+    len += add;
+  }
+  return truncated.length > 0 ? truncated.join(" ") : DEFAULT_BOT_AGENT;
+}
+
 /** Build the `base_info` payload included in every API request. */
 export function buildBaseInfo(): BaseInfo {
-  return { channel_version: CHANNEL_VERSION };
+  return {
+    channel_version: CHANNEL_VERSION,
+    bot_agent: sanitizeBotAgent(loadConfigBotAgent()),
+  };
 }
 
 /** Default timeout for long-poll getUpdates requests. */
@@ -164,15 +262,17 @@ export async function apiGetFetch(params: {
 }
 
 /**
- * Common fetch wrapper: POST JSON to a Weixin API endpoint with timeout + abort.
+ * Common fetch wrapper: POST JSON to a Weixin API endpoint.
+ * When `timeoutMs` is provided, the request is aborted after that many milliseconds.
+ * When omitted, no client-side timeout is applied (relies on OS/TCP stack).
  * Returns the raw response text on success; throws on HTTP error or timeout.
  */
-async function apiPostFetch(params: {
+export async function apiPostFetch(params: {
   baseUrl: string;
   endpoint: string;
   body: string;
   token?: string;
-  timeoutMs: number;
+  timeoutMs?: number;
   label: string;
 }): Promise<string> {
   const base = ensureTrailingSlash(params.baseUrl);
@@ -180,16 +280,20 @@ async function apiPostFetch(params: {
   const hdrs = buildHeaders({ token: params.token, body: params.body });
   logger.debug(`POST ${redactUrl(url.toString())} body=${redactBody(params.body)}`);
 
-  const controller = new AbortController();
-  const t = setTimeout(() => controller.abort(), params.timeoutMs);
+  const controller =
+    params.timeoutMs !== undefined ? new AbortController() : undefined;
+  const t =
+    controller != null && params.timeoutMs !== undefined
+      ? setTimeout(() => controller.abort(), params.timeoutMs)
+      : undefined;
   try {
     const res = await fetch(url.toString(), {
       method: "POST",
       headers: hdrs,
       body: params.body,
-      signal: controller.signal,
+      ...(controller ? { signal: controller.signal } : {}),
     });
-    clearTimeout(t);
+    if (t !== undefined) clearTimeout(t);
     const rawText = await res.text();
     logger.debug(`${params.label} status=${res.status} raw=${redactBody(rawText)}`);
     if (!res.ok) {
@@ -197,7 +301,7 @@ async function apiPostFetch(params: {
     }
     return rawText;
   } catch (err) {
-    clearTimeout(t);
+    if (t !== undefined) clearTimeout(t);
     throw err;
   }
 }
@@ -316,3 +420,35 @@ export async function sendTyping(
     label: "sendTyping",
   });
 }
+
+/**
+ * Notify Weixin that this channel client is stopping (gateway shutdown / channel stop).
+ * Uses a standalone timeout (not the gateway abort signal) so the request can finish
+ * after OpenClaw has already aborted the long-poll.
+ */
+export async function notifyStop(params: WeixinApiOptions): Promise<NotifyStopResp> {
+  const rawText = await apiPostFetch({
+    baseUrl: params.baseUrl,
+    endpoint: "ilink/bot/msg/notifystop",
+    body: JSON.stringify({ base_info: buildBaseInfo() }),
+    token: params.token,
+    timeoutMs: params.timeoutMs ?? DEFAULT_CONFIG_TIMEOUT_MS,
+    label: "notifyStop",
+  });
+  return JSON.parse(rawText) as NotifyStopResp;
+}
+
+/**
+ * Notify Weixin that this channel client is starting (gateway startup / channel start).
+ */
+export async function notifyStart(params: WeixinApiOptions): Promise<NotifyStartResp> {
+  const rawText = await apiPostFetch({
+    baseUrl: params.baseUrl,
+    endpoint: "ilink/bot/msg/notifystart",
+    body: JSON.stringify({ base_info: buildBaseInfo() }),
+    token: params.token,
+    timeoutMs: params.timeoutMs ?? DEFAULT_CONFIG_TIMEOUT_MS,
+    label: "notifyStart",
+  });
+  return JSON.parse(rawText) as NotifyStartResp;
+}

package/src/api/types.ts

@@ -6,6 +6,19 @@
 /** Common request metadata attached to every CGI request. */
 export interface BaseInfo {
   channel_version?: string;
+  /**
+   * Self-declared identity of the upstream bot/app, analogous to HTTP
+   * `User-Agent`. Filled from `channels.openclaw-weixin.botAgent` in
+   * openclaw.json; defaults to `"OpenClaw"` when unset.
+   *
+   * Format: UA-style `Name/Version` tokens, optionally followed by
+   * `(comment)`, multiple tokens space-separated. ASCII only, total
+   * length <= 256 bytes after sanitization.
+   *
+   * For observability only (logging, monitoring aggregation); not used
+   * for authentication or routing.
+   */
+  bot_agent?: string;
 }
 
 /** proto: UploadMediaType */
@@ -224,3 +237,25 @@ export interface GetConfigResp {
   /** Base64-encoded typing ticket for sendTyping. */
   typing_ticket?: string;
 }
+
+/** proto: NotifyStopReq — notify server when the channel client is stopping. */
+export interface NotifyStopReq {
+  base_info?: BaseInfo;
+}
+
+/** proto: NotifyStopResp */
+export interface NotifyStopResp {
+  ret?: number;
+  errmsg?: string;
+}
+
+/** proto: NotifyStartReq — notify server when the channel client is starting. */
+export interface NotifyStartReq {
+  base_info?: BaseInfo;
+}
+
+/** proto: NotifyStartResp */
+export interface NotifyStartResp {
+  ret?: number;
+  errmsg?: string;
+}

package/src/auth/accounts.ts

@@ -290,6 +290,18 @@ export function loadConfigRouteTag(accountId?: string): string | undefined {
     : undefined;
 }
 
+/**
+ * Read `botAgent` from `channels.openclaw-weixin.botAgent` in openclaw.json.
+ * Returns the raw configured string (caller is responsible for sanitization)
+ * or undefined when not set. Reuses the cached channel section.
+ */
+export function loadConfigBotAgent(): string | undefined {
+  const section = loadRouteTagSection();
+  if (!section) return undefined;
+  const value = section.botAgent;
+  return typeof value === "string" && value.trim() ? value : undefined;
+}
+
 /**
  * Bump `channels.openclaw-weixin.channelConfigUpdatedAt` in openclaw.json on each successful login
  * so the gateway reloads config from disk (no empty `accounts: {}` placeholder).

package/src/auth/login-qr.ts

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
 
-import { apiGetFetch } from "../api/api.js";
+import { apiGetFetch, apiPostFetch } from "../api/api.js";
+import { listIndexedWeixinAccountIds, loadWeixinAccount } from "./accounts.js";
 import { logger } from "../util/logger.js";
 import { redactToken } from "../util/redact.js";
 
@@ -11,10 +12,12 @@ type ActiveLogin = {
   qrcodeUrl: string;
   startedAt: number;
   botToken?: string;
-  status?: "wait" | "scaned" | "confirmed" | "expired" | "scaned_but_redirect";
+  status?: "wait" | "scaned" | "confirmed" | "expired" | "scaned_but_redirect" | "need_verifycode" | "verify_code_blocked" | "binded_redirect";
   error?: string;
   /** The current effective polling base URL; may be updated on IDC redirect. */
   currentApiBaseUrl?: string;
+  /** 待提交的配对码，用户输入后暂存，下次轮询时携带 */
+  pendingVerifyCode?: string;
 };
 
 const ACTIVE_LOGIN_TTL_MS = 5 * 60_000;
@@ -35,7 +38,7 @@ interface QRCodeResponse {
 }
 
 interface StatusResponse {
-  status: "wait" | "scaned" | "confirmed" | "expired" | "scaned_but_redirect";
+  status: "wait" | "scaned" | "confirmed" | "expired" | "scaned_but_redirect" | "need_verifycode" | "verify_code_blocked" | "binded_redirect";
   bot_token?: string;
   ilink_bot_id?: string;
   baseurl?: string;
@@ -58,22 +61,64 @@ function purgeExpiredLogins(): void {
   }
 }
 
+/** 获取本地已登录账号的 bot token 列表，最多返回最新的 10 个。 */
+function getLocalBotTokenList(): string[] {
+  const accountIds = listIndexedWeixinAccountIds();
+  const tokens: string[] = [];
+  // 从最新注册的账号开始取（列表末尾为最新）
+  for (let i = accountIds.length - 1; i >= 0 && tokens.length < 10; i--) {
+    const data = loadWeixinAccount(accountIds[i]);
+    const token = data?.token?.trim();
+    if (token) {
+      tokens.push(token);
+    }
+  }
+  return tokens;
+}
+
 async function fetchQRCode(apiBaseUrl: string, botType: string): Promise<QRCodeResponse> {
-  logger.info(`Fetching QR code from: ${apiBaseUrl} bot_type=${botType}`);
-  const rawText = await apiGetFetch({
+  logger.info(`NewFetching QR code from: ${apiBaseUrl} bot_type=${botType}`);
+  const localTokenList = getLocalBotTokenList();
+  logger.info(`newfetchQRCode: local_token_list count=${localTokenList.length}`);
+  const rawText = await apiPostFetch({
     baseUrl: apiBaseUrl,
     endpoint: `ilink/bot/get_bot_qrcode?bot_type=${encodeURIComponent(botType)}`,
+    body: JSON.stringify({ local_token_list: localTokenList }),
     label: "fetchQRCode",
   });
   return JSON.parse(rawText) as QRCodeResponse;
 }
 
-async function pollQRStatus(apiBaseUrl: string, qrcode: string): Promise<StatusResponse> {
+/** 从 stdin 读取一行用户输入，输出提示语后等待回车确认，返回 trim 后的字符串。 */
+async function readVerifyCodeFromStdin(prompt: string): Promise<string> {
+  process.stdout.write(prompt);
+  return new Promise((resolve) => {
+    let input = "";
+    const onData = (chunk: Buffer | string) => {
+      const str = chunk.toString();
+      input += str;
+      if (input.includes("\n")) {
+        process.stdin.removeListener("data", onData);
+        process.stdin.pause();
+        resolve(input.trim());
+      }
+    };
+    process.stdin.resume();
+    process.stdin.setEncoding("utf-8");
+    process.stdin.on("data", onData);
+  });
+}
+
+async function pollQRStatus(apiBaseUrl: string, qrcode: string, verifyCode?: string): Promise<StatusResponse> {
   logger.debug(`Long-poll QR status from: ${apiBaseUrl} qrcode=***`);
   try {
+    let endpoint = `ilink/bot/get_qrcode_status?qrcode=${encodeURIComponent(qrcode)}`;
+    if (verifyCode) {
+      endpoint += `&verify_code=${encodeURIComponent(verifyCode)}`;
+    }
     const rawText = await apiGetFetch({
       baseUrl: apiBaseUrl,
-      endpoint: `ilink/bot/get_qrcode_status?qrcode=${encodeURIComponent(qrcode)}`,
+      endpoint,
       timeoutMs: QR_LONG_POLL_TIMEOUT_MS,
       label: "pollQRStatus",
     });
@@ -90,6 +135,22 @@ async function pollQRStatus(apiBaseUrl: string, qrcode: string): Promise<StatusR
   }
 }
 
+/**
+ * 在终端展示二维码及备用链接。
+ * 供 CLI 登录流程和 MCP Tool 登录流程共同复用。
+ */
+export async function displayQRCode(qrcodeUrl: string): Promise<void> {
+  try {
+    const qrterm = await import("qrcode-terminal");
+    qrterm.default.generate(qrcodeUrl, { small: true });
+    process.stdout.write(`若二维码未能显示或无法使用，你可以访问以下链接以继续：\n`);
+    process.stdout.write(`${qrcodeUrl}\n`);
+  } catch {
+    process.stdout.write(`若二维码未能显示或无法使用，你可以访问以下链接以继续：\n`);
+    process.stdout.write(`${qrcodeUrl}\n`);
+  }
+}
+
 export type WeixinQrStartResult = {
   qrcodeUrl?: string;
   message: string;
@@ -108,7 +169,6 @@ export type WeixinQrWaitResult = {
 
 export async function startWeixinLoginWithQr(opts: {
   verbose?: boolean;
-  timeoutMs?: number;
   force?: boolean;
   accountId?: string;
   apiBaseUrl: string;
@@ -122,7 +182,7 @@ export async function startWeixinLoginWithQr(opts: {
   if (!opts.force && existing && isLoginFresh(existing) && existing.qrcodeUrl) {
     return {
       qrcodeUrl: existing.qrcodeUrl,
-      message: "二维码已就绪，请使用微信扫描。",
+      message: "二维码已显示，请用手机微信扫描。",
       sessionKey,
     };
   }
@@ -149,7 +209,7 @@ export async function startWeixinLoginWithQr(opts: {
 
     return {
       qrcodeUrl: qrResponse.qrcode_img_content,
-      message: "使用微信扫描以下二维码，以完成连接。",
+      message: "用手机微信扫描以下二维码，以继续连接：",
       sessionKey,
     };
   } catch (err) {
@@ -163,6 +223,34 @@ export async function startWeixinLoginWithQr(opts: {
 
 const MAX_QR_REFRESH_COUNT = 3;
 
+/**
+ * 刷新二维码并展示给用户，返回是否成功。
+ * 成功时更新 activeLogin 的 qrcode/qrcodeUrl/startedAt，并重置 scannedPrinted。
+ */
+async function refreshQRCode(
+  activeLogin: ActiveLogin,
+  botType: string,
+  qrRefreshCount: number,
+  onScannedReset: () => void,
+): Promise<{ success: true } | { success: false; message: string }> {
+  process.stdout.write(`\n⏳ 正在刷新二维码...(${qrRefreshCount}/${MAX_QR_REFRESH_COUNT})\n`);
+  logger.info(`waitForWeixinLogin: refreshing QR code (${qrRefreshCount}/${MAX_QR_REFRESH_COUNT})`);
+  try {
+    const qrResponse = await fetchQRCode(FIXED_BASE_URL, botType);
+    activeLogin.qrcode = qrResponse.qrcode;
+    activeLogin.qrcodeUrl = qrResponse.qrcode_img_content;
+    activeLogin.startedAt = Date.now();
+    onScannedReset();
+    logger.info(`waitForWeixinLogin: new QR code obtained qrcode=${redactToken(qrResponse.qrcode)}`);
+    process.stdout.write(`🔄 二维码已更新，请重新扫描。\n\n`);
+    await displayQRCode(qrResponse.qrcode_img_content);
+    return { success: true };
+  } catch (refreshErr) {
+    logger.error(`waitForWeixinLogin: failed to refresh QR code: ${String(refreshErr)}`);
+    return { success: false, message: `刷新二维码失败: ${String(refreshErr)}` };
+  }
+}
+
 export async function waitForWeixinLogin(opts: {
   timeoutMs?: number;
   verbose?: boolean;
@@ -202,7 +290,7 @@ export async function waitForWeixinLogin(opts: {
   while (Date.now() < deadline) {
     try {
       const currentBaseUrl = activeLogin.currentApiBaseUrl ?? FIXED_BASE_URL;
-      const statusResponse = await pollQRStatus(currentBaseUrl, activeLogin.qrcode);
+      const statusResponse = await pollQRStatus(currentBaseUrl, activeLogin.qrcode, activeLogin.pendingVerifyCode);
       logger.debug(`pollQRStatus: status=${statusResponse.status} hasBotToken=${Boolean(statusResponse.bot_token)} hasBotId=${Boolean(statusResponse.ilink_bot_id)}`);
       activeLogin.status = statusResponse.status;
 
@@ -213,11 +301,26 @@ export async function waitForWeixinLogin(opts: {
           }
           break;
         case "scaned":
+          // 若携带了配对码且服务端返回 scaned，说明验证码正确，清除暂存
+          if (activeLogin.pendingVerifyCode) {
+            logger.info("verify code accepted, resuming polling");
+            activeLogin.pendingVerifyCode = undefined;
+          }
           if (!scannedPrinted) {
-            process.stdout.write("\n👀 已扫码，在微信继续操作...\n");
+            process.stdout.write("\n正在验证\n");
             scannedPrinted = true;
           }
           break;
+        case "need_verifycode": {
+          // 首次进入提示输入，再次进入（已有 pendingVerifyCode）说明上次输入错误
+          const verifyPrompt = activeLogin.pendingVerifyCode
+            ? "❌ 你输入的数字不匹配，请重新输入："
+            : "输入手机微信显示的数字，以继续连接：";
+          const code = await readVerifyCodeFromStdin(verifyPrompt);
+          activeLogin.pendingVerifyCode = code;
+          // 立即进入下一次轮询，不等待 1s
+          continue;
+        }
         case "expired": {
           qrRefreshCount++;
           if (qrRefreshCount > MAX_QR_REFRESH_COUNT) {
@@ -227,43 +330,64 @@ export async function waitForWeixinLogin(opts: {
             activeLogins.delete(opts.sessionKey);
             return {
               connected: false,
-              message: "登录超时：二维码多次过期，请重新开始登录流程。",
+              message: "二维码多次失效，连接流程已停止。请稍后再试。",
             };
           }
 
-          process.stdout.write(`\n⏳ 二维码已过期，正在刷新...(${qrRefreshCount}/${MAX_QR_REFRESH_COUNT})\n`);
-          logger.info(
-            `waitForWeixinLogin: QR expired, refreshing (${qrRefreshCount}/${MAX_QR_REFRESH_COUNT})`,
+          process.stdout.write(`\n⏳ 二维码已过期，正在刷新...\n`);
+          const expiredRefreshResult = await refreshQRCode(
+            activeLogin,
+            opts.botType || DEFAULT_ILINK_BOT_TYPE,
+            qrRefreshCount,
+            () => { scannedPrinted = false; },
+          );
+          if (!expiredRefreshResult.success) {
+            activeLogins.delete(opts.sessionKey);
+            return { connected: false, message: expiredRefreshResult.message };
+          }
+          break;
+        }
+        case "verify_code_blocked": {
+          logger.warn(
+            `waitForWeixinLogin: verify code blocked, qrRefreshCount=${qrRefreshCount} sessionKey=${opts.sessionKey}`,
           );
+          process.stdout.write("\n⛔ 多次输入错误，请稍后再试。\n");
+          // 清除配对码暂存
+          activeLogin.pendingVerifyCode = undefined;
 
-          try {
-            const botType = opts.botType || DEFAULT_ILINK_BOT_TYPE;
-            const qrResponse = await fetchQRCode(FIXED_BASE_URL, botType);
-            activeLogin.qrcode = qrResponse.qrcode;
-            activeLogin.qrcodeUrl = qrResponse.qrcode_img_content;
-            activeLogin.startedAt = Date.now();
-            scannedPrinted = false;
-            logger.info(`waitForWeixinLogin: new QR code obtained qrcode=${redactToken(qrResponse.qrcode)}`);
-            process.stdout.write(`🔄 新二维码已生成，请重新扫描\n\n`);
-            try {
-              const qrterm = await import("qrcode-terminal");
-              qrterm.default.generate(qrResponse.qrcode_img_content, { small: true });
-              process.stdout.write(`如果二维码未能成功展示，请用浏览器打开以下链接扫码：\n`);
-              process.stdout.write(`${qrResponse.qrcode_img_content}\n`);
-            } catch {
-              process.stdout.write(`二维码未加载成功，请用浏览器打开以下链接扫码：\n`);
-              process.stdout.write(`${qrResponse.qrcode_img_content}\n`);
-            }          
-          } catch (refreshErr) {
-            logger.error(`waitForWeixinLogin: failed to refresh QR code: ${String(refreshErr)}`);
+          qrRefreshCount++;
+          if (qrRefreshCount > MAX_QR_REFRESH_COUNT) {
+            logger.warn(
+              `waitForWeixinLogin: verify_code_blocked and QR refresh limit reached, giving up sessionKey=${opts.sessionKey}`,
+            );
             activeLogins.delete(opts.sessionKey);
             return {
               connected: false,
-              message: `刷新二维码失败: ${String(refreshErr)}`,
+              message: "多次输入错误，连接流程已停止。请稍后再试。",
             };
           }
+
+          const blockedRefreshResult = await refreshQRCode(
+            activeLogin,
+            opts.botType || DEFAULT_ILINK_BOT_TYPE,
+            qrRefreshCount,
+            () => { scannedPrinted = false; },
+          );
+          if (!blockedRefreshResult.success) {
+            activeLogins.delete(opts.sessionKey);
+            return { connected: false, message: blockedRefreshResult.message };
+          }
           break;
         }
+        case "binded_redirect": {
+          logger.info(`waitForWeixinLogin: binded_redirect received, bot already bound sessionKey=${opts.sessionKey}`);
+          process.stdout.write("\n✅ 已连接过此 OpenClaw，无需重复连接。\n");
+          activeLogins.delete(opts.sessionKey);
+          return {
+            connected: false,
+            message: "已连接过此 OpenClaw，无需重复连接。",
+          };
+        }
         case "scaned_but_redirect": {
           const redirectHost = statusResponse.redirect_host;
           if (redirectHost) {
@@ -298,7 +422,7 @@ export async function waitForWeixinLogin(opts: {
             accountId: statusResponse.ilink_bot_id,
             baseUrl: statusResponse.baseurl,
             userId: statusResponse.ilink_user_id,
-            message: "✅ 与微信连接成功！",
+            message: "已将此 OpenClaw 连接到微信。",
           };
         }
       }

package/src/channel.ts

@@ -15,6 +15,7 @@ import {
   DEFAULT_BASE_URL,
 } from "./auth/accounts.js";
 import type { ResolvedWeixinAccount } from "./auth/accounts.js";
+import { notifyStop, notifyStart } from "./api/api.js";
 import { assertSessionActive } from "./api/session-guard.js";
 import { getContextToken, findAccountIdsByContextToken, restoreContextTokens, clearContextTokensForAccount } from "./messaging/inbound.js";
 import { logger } from "./util/logger.js";
@@ -22,6 +23,7 @@ import {
   DEFAULT_ILINK_BOT_TYPE,
   startWeixinLoginWithQr,
   waitForWeixinLogin,
+  displayQRCode,
 } from "./auth/login-qr.js";
 import type { WeixinQrStartResult, WeixinQrWaitResult } from "./auth/login-qr.js";
 // Lazy-imported inside startAccount to avoid pulling in the monitor -> process-message ->
@@ -319,7 +321,7 @@ export const weixinPlugin: ChannelPlugin<ResolvedWeixinAccount> = {
         runtime?.log?.(msg);
       };
 
-      log(`正在启动微信扫码登录...`);
+      log(`正在启动...`);
       const startResult: WeixinQrStartResult = await startWeixinLoginWithQr({
         accountId: account.accountId,
         apiBaseUrl: account.baseUrl,
@@ -335,27 +337,11 @@ export const weixinPlugin: ChannelPlugin<ResolvedWeixinAccount> = {
         throw new Error(startResult.message);
       }
 
-      log(`\n使用微信扫描以下二维码，以完成连接：\n`);
-      try {
-        const qrcodeterminal = await import("qrcode-terminal");
-        await new Promise<void>((resolve) => {
-          qrcodeterminal.default.generate(startResult.qrcodeUrl!, { small: true }, (qr: string) => {
-            console.log(qr);
-            log(`如果二维码未能成功展示，请用浏览器打开以下链接扫码：`);
-            log(startResult.qrcodeUrl!);
-            resolve();
-          });
-        });
-      } catch (err) {
-        logger.warn(
-          `auth.login: qrcode-terminal unavailable, falling back to URL err=${String(err)}`,
-        );
-        log(`二维码未加载成功，请用浏览器打开以下链接扫码：`);
-        log(startResult.qrcodeUrl!);
-      }
+      log(`\n用手机微信扫描以下二维码，以继续连接：\n`);
+      await displayQRCode(startResult.qrcodeUrl!);
 
       const loginTimeoutMs = 480_000;
-      log(`\n等待连接结果...\n`);
+      log(`\n正在等待操作...\n`);
 
       const waitResult: WeixinQrWaitResult = await waitForWeixinLogin({
         sessionKey: startResult.sessionKey,
@@ -380,7 +366,7 @@ export const weixinPlugin: ChannelPlugin<ResolvedWeixinAccount> = {
             clearStaleAccountsForUserId(normalizedId, waitResult.userId, clearContextTokensForAccount);
           }
           void triggerWeixinChannelReload();
-          log(`\n✅ 与微信连接成功！`);
+          log(`\n已将此 OpenClaw 连接到微信。`);
         } catch (err) {
           logger.error(
             `auth.login: failed to save account data accountId=${waitResult.accountId} err=${String(err)}`,
@@ -427,6 +413,18 @@ export const weixinPlugin: ChannelPlugin<ResolvedWeixinAccount> = {
 
       ctx.log?.info?.(`[${account.accountId}] starting weixin provider (${DEFAULT_BASE_URL})`);
 
+      try {
+        const resp = await notifyStart({
+          baseUrl: account.baseUrl,
+          token: account.token,
+        });
+        if (resp.ret !== undefined && resp.ret !== 0) {
+          aLog.warn(`notifyStart: ret=${resp.ret} errmsg=${resp.errmsg ?? ""}`);
+        }
+      } catch (err) {
+        aLog.warn(`notifyStart failed during startup (ignored): ${String(err)}`);
+      }
+
       const logPath = aLog.getLogFilePath();
       ctx.log?.info?.(`[${account.accountId}] weixin logs: ${logPath}`);
 
@@ -442,7 +440,26 @@ export const weixinPlugin: ChannelPlugin<ResolvedWeixinAccount> = {
         setStatus: ctx.setStatus,
       });
     },
-    loginWithQrStart: async ({ accountId, force, timeoutMs, verbose }) => {
+    stopAccount: async (ctx) => {
+      const account = ctx.account;
+      const aLog = logger.withAccount(account.accountId);
+      if (!account.configured || !account.token?.trim()) {
+        aLog.debug(`gateway.stopAccount: skip notifyStop (not configured or no token)`);
+        return;
+      }
+      try {
+        const resp = await notifyStop({
+          baseUrl: account.baseUrl,
+          token: account.token,
+        });
+        if (resp.ret !== undefined && resp.ret !== 0) {
+          aLog.warn(`notifyStop: ret=${resp.ret} errmsg=${resp.errmsg ?? ""}`);
+        }
+      } catch (err) {
+        aLog.warn(`notifyStop failed during shutdown (ignored): ${String(err)}`);
+      }
+    },
+    loginWithQrStart: async ({ accountId, force, verbose }) => {
       // For re-login: use saved baseUrl from account data; fall back to default for new accounts.
       const savedBaseUrl = accountId ? loadWeixinAccount(accountId)?.baseUrl?.trim() : "";
       const result: WeixinQrStartResult = await startWeixinLoginWithQr({
@@ -450,7 +467,6 @@ export const weixinPlugin: ChannelPlugin<ResolvedWeixinAccount> = {
         apiBaseUrl: savedBaseUrl || DEFAULT_BASE_URL,
         botType: DEFAULT_ILINK_BOT_TYPE,
         force,
-        timeoutMs,
         verbose,
       });
       // Return sessionKey so the client can pass it back in loginWithQrWait.