@tencent-connect/openclaw-qqbot 1.7.1 → 1.7.2

package/dist/src/transport/webhook-transport.js

@@ -0,0 +1,245 @@
+/**
+ * Webhook Transport — receive QQ Bot events via HTTP POST callbacks.
+ *
+ * Uses OpenClaw plugin-sdk's `registerWebhookTargetWithPluginRoute` (模式 C)
+ * to register webhook HTTP routes through the framework's gateway HTTP server,
+ * sharing the same port and benefiting from built-in rate limiting & in-flight guards.
+ *
+ * Architecture:
+ *   1. On gateway startAccount, register a webhook target via plugin-sdk
+ *   2. Framework routes POST requests to our handler
+ *   3. Handler verifies Ed25519 signatures and dispatches events
+ *   4. Returns op:12 ACK immediately, processes events asynchronously
+ *   5. On account stop (abortSignal), unregister the target
+ *
+ * Configuration (openclaw.yaml):
+ * ```yaml
+ * channels:
+ *   qqbot:
+ *     appId: "xxx"
+ *     clientSecret: "xxx"
+ *     transport: webhook
+ *     webhook:
+ *       path: /qqbot/webhook
+ * ```
+ */
+import { registerWebhookTargetWithPluginRoute, withResolvedWebhookRequestPipeline, resolveWebhookTargetWithAuthOrRejectSync, createWebhookInFlightLimiter, createFixedWindowRateLimiter, readWebhookBodyOrReject, } from "openclaw/plugin-sdk/webhook-ingress";
+import { verifyWebhookSignature, signValidationResponse } from "./webhook-verify.js";
+// ============ Constants ============
+const OP_DISPATCH = 0;
+const OP_HTTP_CALLBACK_ACK = 12;
+const OP_VALIDATION = 13;
+const PLUGIN_ID = "openclaw-qqbot";
+const DEFAULT_WEBHOOK_PATH = "/qqbot/webhook";
+// ============ Module state ============
+/** Per-path target registry (shared across all accounts) */
+const webhookTargets = new Map();
+/** Per-account event handler map */
+const eventHandlers = new Map();
+/** Module-level logger (set by the last startWebhookTransport call) */
+let log;
+/** Shared rate limiter (fixed window, per source IP) */
+let rateLimiter = null;
+/** Shared in-flight limiter */
+let inFlightLimiter = null;
+function ensureGuards() {
+    if (!rateLimiter) {
+        rateLimiter = createFixedWindowRateLimiter({
+            windowMs: 60_000,
+            maxRequests: 600,
+            maxTrackedKeys: 4096,
+        });
+    }
+    if (!inFlightLimiter) {
+        inFlightLimiter = createWebhookInFlightLimiter({
+            maxInFlightPerKey: 8,
+            maxTrackedKeys: 4096,
+        });
+    }
+    return { rateLimiter, inFlightLimiter };
+}
+// ============ Main handler ============
+/**
+ * Shared HTTP handler for all QQBot webhook routes.
+ * Registered once per unique path, dispatches to the correct account target.
+ */
+async function handleQQBotWebhookRequest(req, res) {
+    const guards = ensureGuards();
+    const handled = await withResolvedWebhookRequestPipeline({
+        req,
+        res,
+        targetsByPath: webhookTargets,
+        rateLimiter: guards.rateLimiter,
+        inFlightLimiter: guards.inFlightLimiter,
+        requireJsonContentType: true,
+        handle: async ({ targets }) => {
+            // Read raw body (up to 1MB, 30s timeout)
+            const bodyResult = await readWebhookBodyOrReject({
+                req,
+                res,
+                maxBytes: 1024 * 1024,
+                timeoutMs: 30_000,
+            });
+            if (!bodyResult.ok)
+                return;
+            const rawBodyStr = bodyResult.value;
+            const rawBody = Buffer.from(rawBodyStr, "utf-8");
+            let payload;
+            try {
+                payload = JSON.parse(rawBodyStr);
+            }
+            catch (err) {
+                log?.error(`[qqbot:webhook] Failed to parse request body as JSON: ${err instanceof Error ? err.message : String(err)}, body preview: ${rawBodyStr.slice(0, 200)}`);
+                res.statusCode = 400;
+                res.end(JSON.stringify({ error: "invalid json" }));
+                return;
+            }
+            // ── op:13 — Callback URL validation (before signature check) ──
+            if (payload.op === OP_VALIDATION) {
+                handleValidation(payload, targets, res);
+                return;
+            }
+            // ── Signature verification → resolve target ──
+            const timestamp = getHeader(req, "x-signature-timestamp") ?? "";
+            const signature = getHeader(req, "x-signature-ed25519") ?? "";
+            if (!timestamp || !signature) {
+                log?.warn?.(`[qqbot:webhook] Missing signature headers — timestamp: "${timestamp}", signature: "${signature}", url: ${req.url}`);
+                res.statusCode = 401;
+                res.end(JSON.stringify({ error: "missing signature headers" }));
+                return;
+            }
+            const matchedTarget = resolveWebhookTargetWithAuthOrRejectSync({
+                targets,
+                res,
+                isMatch: (target) => verifyWebhookSignature({
+                    body: rawBody,
+                    timestamp,
+                    signature,
+                    botSecret: target.clientSecret,
+                }),
+                unauthorizedStatusCode: 401,
+                unauthorizedMessage: JSON.stringify({ error: "invalid signature" }),
+            });
+            if (!matchedTarget) {
+                log?.warn?.(`[qqbot:webhook] Signature verification failed for path: ${req.url}, timestamp: ${timestamp}`);
+                return; // response already sent by resolver
+            }
+            // ── ACK immediately ──
+            res.statusCode = 200;
+            res.setHeader("Content-Type", "application/json");
+            res.end(JSON.stringify({ op: OP_HTTP_CALLBACK_ACK, d: 0 }));
+            // ── Async dispatch (fire-and-forget) ──
+            if (payload.op === OP_DISPATCH) {
+                const handler = eventHandlers.get(matchedTarget.accountId);
+                if (handler) {
+                    Promise.resolve(handler({
+                        eventType: payload.t ?? "",
+                        data: payload.d,
+                        seq: payload.s,
+                    })).catch((err) => {
+                        log?.error(`[qqbot:${matchedTarget.accountId}] Event handler error for "${payload.t}": ${err instanceof Error ? err.message : String(err)}`);
+                    });
+                }
+                else {
+                    log?.warn?.(`[qqbot:webhook] No event handler registered for account: ${matchedTarget.accountId}, event: ${payload.t}`);
+                }
+            }
+        },
+    });
+    return handled;
+}
+// ============ Validation handler (op:13) ============
+function handleValidation(payload, targets, res) {
+    const d = payload.d;
+    if (!d?.plain_token || !d?.event_ts) {
+        log?.warn?.(`[qqbot:webhook] Invalid validation payload (op:13): missing plain_token or event_ts, got: ${JSON.stringify(d)}`);
+        res.statusCode = 400;
+        res.end(JSON.stringify({ error: "invalid validation payload" }));
+        return;
+    }
+    // Use the first target's secret for validation
+    // (op:13 is sent during URL registration, only one bot should be using the path at that time)
+    const target = targets[0];
+    if (!target) {
+        log?.error(`[qqbot:webhook] No target registered for validation (op:13), cannot sign response`);
+        res.statusCode = 500;
+        res.end(JSON.stringify({ error: "no target registered" }));
+        return;
+    }
+    const response = signValidationResponse({
+        plainToken: d.plain_token,
+        eventTs: d.event_ts,
+        botSecret: target.clientSecret,
+    });
+    res.statusCode = 200;
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify(response));
+}
+// ============ Public API ============
+/**
+ * Start the webhook transport for a given account.
+ *
+ * Registers a webhook target on the framework's plugin HTTP route system.
+ * The handler verifies Ed25519 signatures, ACKs immediately, and dispatches
+ * events asynchronously via the provided `onEvent` callback.
+ *
+ * Returns when the abortSignal is triggered (account stopped).
+ */
+export async function startWebhookTransport(opts) {
+    const { account, abortSignal, onEvent, onReady, onError, log: optLog } = opts;
+    log = optLog;
+    const webhookPath = account.config.webhook?.path ?? DEFAULT_WEBHOOK_PATH;
+    log?.info(`[qqbot:${account.accountId}] Starting webhook transport on path: ${webhookPath}`);
+    // Register event handler for this account
+    eventHandlers.set(account.accountId, onEvent);
+    // Register webhook target + plugin HTTP route
+    const { unregister } = registerWebhookTargetWithPluginRoute({
+        targetsByPath: webhookTargets,
+        target: {
+            path: webhookPath,
+            accountId: account.accountId,
+            appId: account.appId,
+            clientSecret: account.clientSecret,
+        },
+        route: {
+            auth: "plugin",
+            match: "exact",
+            pluginId: PLUGIN_ID,
+            source: "qqbot-webhook",
+            accountId: account.accountId,
+            replaceExisting: true,
+            log: (msg) => log?.info(msg),
+            handler: handleQQBotWebhookRequest,
+        },
+        onLastPathTargetRemoved: () => {
+            log?.info(`[qqbot] Last webhook target removed from path: ${webhookPath}`);
+        },
+    });
+    log?.info(`[qqbot:${account.accountId}] Webhook transport registered on path: ${webhookPath}`);
+    onReady?.();
+    // Wait until abort signal fires
+    await new Promise((resolve) => {
+        if (abortSignal.aborted) {
+            resolve();
+            return;
+        }
+        abortSignal.addEventListener("abort", () => resolve(), { once: true });
+    });
+    // Cleanup
+    unregister();
+    eventHandlers.delete(account.accountId);
+    log?.info(`[qqbot:${account.accountId}] Webhook transport stopped`);
+}
+/**
+ * Resolve the webhook path for a given account (for external configuration / setWebhook calls).
+ */
+export function resolveWebhookPath(account) {
+    return account.config.webhook?.path ?? DEFAULT_WEBHOOK_PATH;
+}
+// ============ Helpers ============
+function getHeader(req, key) {
+    const val = req.headers[key];
+    if (Array.isArray(val))
+        return val[0];
+    return val;
+}

package/dist/src/transport/webhook-verify.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Webhook signature verification — Ed25519.
+ *
+ * QQ Open Platform uses Ed25519 for webhook callback verification:
+ *   1. Bot secret is padded/truncated to 32 bytes as the Ed25519 seed.
+ *   2. The public key verifies `timestamp + body` against `X-Signature-Ed25519`.
+ *   3. For callback URL validation (op:13), signs `event_ts + plain_token`.
+ *
+ * Reference: https://bot.q.qq.com/wiki/develop/api-v2/dev-prepare/interface-framework/event-emit.html
+ */
+/**
+ * Sign a message using the bot's Ed25519 private key.
+ * Returns hex-encoded signature.
+ */
+export declare function ed25519Sign(botSecret: string, message: Buffer): string;
+/**
+ * Verify an Ed25519 signature from a QQ webhook callback request.
+ *
+ * @param params.body - Raw request body (Buffer)
+ * @param params.timestamp - Value of `X-Signature-Timestamp` header
+ * @param params.signature - Value of `X-Signature-Ed25519` header (hex string)
+ * @param params.botSecret - The bot's AppSecret
+ * @returns `true` if signature is valid
+ */
+export declare function verifyWebhookSignature(params: {
+    body: Buffer;
+    timestamp: string;
+    signature: string;
+    botSecret: string;
+}): boolean;
+/**
+ * Generate the response for callback URL validation (op:13).
+ *
+ * QQ sends `{ op: 13, d: { plain_token, event_ts } }` to verify
+ * the callback URL. We must return `{ plain_token, signature }`.
+ *
+ * @param params.plainToken - The `plain_token` from the validation request
+ * @param params.eventTs - The `event_ts` from the validation request
+ * @param params.botSecret - The bot's AppSecret
+ */
+export declare function signValidationResponse(params: {
+    plainToken: string;
+    eventTs: string;
+    botSecret: string;
+}): {
+    plain_token: string;
+    signature: string;
+};

package/dist/src/transport/webhook-verify.js

@@ -0,0 +1,98 @@
+/**
+ * Webhook signature verification — Ed25519.
+ *
+ * QQ Open Platform uses Ed25519 for webhook callback verification:
+ *   1. Bot secret is padded/truncated to 32 bytes as the Ed25519 seed.
+ *   2. The public key verifies `timestamp + body` against `X-Signature-Ed25519`.
+ *   3. For callback URL validation (op:13), signs `event_ts + plain_token`.
+ *
+ * Reference: https://bot.q.qq.com/wiki/develop/api-v2/dev-prepare/interface-framework/event-emit.html
+ */
+import * as crypto from "node:crypto";
+// ============ Seed derivation ============
+/**
+ * Derive an Ed25519 seed (32 bytes) from the bot secret.
+ * QQ's spec: repeat the secret until >= 32 chars, then truncate to 32.
+ */
+function deriveSeed(botSecret) {
+    let seed = botSecret;
+    while (seed.length < 32) {
+        seed = seed + seed;
+    }
+    return Buffer.from(seed.slice(0, 32), "utf-8");
+}
+/**
+ * Generate Ed25519 key pair from bot secret.
+ */
+function getKeyPair(botSecret) {
+    const seed = deriveSeed(botSecret);
+    // Node.js Ed25519: create private key from raw 32-byte seed
+    const privateKey = crypto.createPrivateKey({
+        key: Buffer.concat([
+            // Ed25519 PKCS8 DER prefix for 32-byte seed
+            Buffer.from("302e020100300506032b657004220420", "hex"),
+            seed,
+        ]),
+        format: "der",
+        type: "pkcs8",
+    });
+    const publicKey = crypto.createPublicKey(privateKey);
+    return { privateKey, publicKey };
+}
+// ============ Signature generation ============
+/**
+ * Sign a message using the bot's Ed25519 private key.
+ * Returns hex-encoded signature.
+ */
+export function ed25519Sign(botSecret, message) {
+    const { privateKey } = getKeyPair(botSecret);
+    const signature = crypto.sign(null, message, privateKey);
+    return signature.toString("hex");
+}
+// ============ Signature verification ============
+/**
+ * Verify an Ed25519 signature from a QQ webhook callback request.
+ *
+ * @param params.body - Raw request body (Buffer)
+ * @param params.timestamp - Value of `X-Signature-Timestamp` header
+ * @param params.signature - Value of `X-Signature-Ed25519` header (hex string)
+ * @param params.botSecret - The bot's AppSecret
+ * @returns `true` if signature is valid
+ */
+export function verifyWebhookSignature(params) {
+    const { body, timestamp, signature, botSecret } = params;
+    try {
+        const { publicKey } = getKeyPair(botSecret);
+        const message = Buffer.concat([
+            Buffer.from(timestamp, "utf-8"),
+            body,
+        ]);
+        const sigBuffer = Buffer.from(signature, "hex");
+        return crypto.verify(null, message, publicKey, sigBuffer);
+    }
+    catch (err) {
+        console.warn(`[qqbot:webhook-verify] Ed25519 verification threw: ${err instanceof Error ? err.message : String(err)}`);
+        return false;
+    }
+}
+// ============ Callback URL validation (op:13) ============
+/**
+ * Generate the response for callback URL validation (op:13).
+ *
+ * QQ sends `{ op: 13, d: { plain_token, event_ts } }` to verify
+ * the callback URL. We must return `{ plain_token, signature }`.
+ *
+ * @param params.plainToken - The `plain_token` from the validation request
+ * @param params.eventTs - The `event_ts` from the validation request
+ * @param params.botSecret - The bot's AppSecret
+ */
+export function signValidationResponse(params) {
+    const { plainToken, eventTs, botSecret } = params;
+    // Sign: event_ts + plain_token
+    const message = Buffer.from(eventTs + plainToken, "utf-8");
+    const signature = ed25519Sign(botSecret, message);
+    return {
+        plain_token: plainToken,
+        signature,
+    };
+}

package/dist/src/types.d.ts

@@ -26,6 +26,8 @@ export interface ResolvedQQBotAccount {
     imageServerBaseUrl?: string;
     /** 是否支持 markdown 消息（默认 true） */
     markdownSupport: boolean;
+    /** User-Agent 追加后缀（从通道级配置 channels.qqbot.userAgentSuffix 解析） */
+    userAgentSuffix?: string;
     config: QQBotAccountConfig;
 }
 /** 群消息策略：open=全响应 | allowlist=白名单 | disabled=不响应 */
@@ -50,6 +52,13 @@ export interface GroupConfig {
     /** 群历史消息缓存条数（0 禁用，默认 20） */
     historyLimit?: number;
 }
+/** 消息接收传输方式 */
+export type TransportMode = "websocket" | "webhook";
+/** Webhook 传输配置 */
+export interface WebhookTransportConfig {
+    /** 监听路径（默认 /qqbot/webhook） */
+    path?: string;
+}
 /**
  * QQ Bot 账户配置
  */
@@ -61,6 +70,10 @@ export interface QQBotAccountConfig {
     clientSecretFile?: string;
     dmPolicy?: "open" | "pairing" | "allowlist";
     allowFrom?: string[];
+    /** 消息接收传输方式：websocket（默认）| webhook */
+    transport?: TransportMode;
+    /** webhook 传输配置（transport="webhook" 时生效） */
+    webhook?: WebhookTransportConfig;
     /** 群消息策略（默认 allowlist） */
     groupPolicy?: GroupPolicy;
     /** 群白名单（groupPolicy 为 allowlist 时生效） */
@@ -107,6 +120,12 @@ export interface QQBotAccountConfig {
      * 示例: "ryantest/openclaw-qqbot"
      */
     upgradePkg?: string;
+    /**
+     * 群消息是否默认需要 @机器人才响应（默认 true）
+     * 优先级低于 groups.{groupId}.requireMention 和 groups."*".requireMention
+     * 设为 false 时，所有群默认无需 @ 即触发回复（仍可被群级配置覆盖）
+     */
+    defaultRequireMention?: boolean;
     /**
      * 出站消息合并回复（debounce）配置
      * 当短时间内收到多次 deliver 时，将文本合并为一条消息发送，避免消息轰炸

package/dist/src/utils/audio-convert.js

@@ -1,8 +1,29 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { execFile } from "node:child_process";
-import { decode, encode, isSilk } from "silk-wasm";
 import { detectFfmpeg, isWindows } from "./platform.js";
+// silk-wasm 动态加载（可选依赖，未安装时降级为不支持语音编解码）
+let silkWasm = null;
+let silkWasmLoaded = false;
+async function loadSilkWasm() {
+    if (silkWasmLoaded)
+        return silkWasm;
+    silkWasmLoaded = true;
+    try {
+        silkWasm = await import("silk-wasm");
+    }
+    catch {
+        console.warn("[audio-convert] silk-wasm not available, voice encoding/decoding disabled");
+        silkWasm = null;
+    }
+    return silkWasm;
+}
+// 同步版本的 isSilk（用于不方便 await 的场景），首次调用前需先 loadSilkWasm
+function isSilkSync(data) {
+    if (!silkWasm)
+        return false;
+    return silkWasm.isSilk(data);
+}
 /**
  * 检查文件是否为 SILK 格式（QQ/微信语音常用格式）
  * QQ 语音文件通常以 .amr 扩展名保存，但实际编码可能是 SILK v3
@@ -11,7 +32,7 @@ import { detectFfmpeg, isWindows } from "./platform.js";
 function isSilkFile(filePath) {
     try {
         const buf = fs.readFileSync(filePath);
-        return isSilk(new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength));
+        return isSilkSync(new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength));
     }
     catch {
         return false;
@@ -76,13 +97,14 @@ export async function convertSilkToWav(inputPath, outputDir) {
     // 转为 Uint8Array 以兼容 silk-wasm 类型要求
     const rawData = new Uint8Array(strippedBuf.buffer, strippedBuf.byteOffset, strippedBuf.byteLength);
     // 验证是否为 SILK 格式
-    if (!isSilk(rawData)) {
+    const silk = await loadSilkWasm();
+    if (!silk || !silk.isSilk(rawData)) {
         return null;
     }
     // SILK 解码为 PCM (s16le)
     // QQ 语音通常采样率为 24000Hz
     const sampleRate = 24000;
-    const result = await decode(rawData, sampleRate);
+    const result = await silk.decode(rawData, sampleRate);
     // PCM → WAV
     const wavBuffer = pcmToWav(result.data, sampleRate);
     // 写入 WAV 文件
@@ -317,8 +339,12 @@ export async function textToSpeechPCM(text, ttsCfg) {
     throw lastError ?? new Error("TTS failed: all formats exhausted");
 }
 export async function pcmToSilk(pcmBuffer, sampleRate) {
+    const silk = await loadSilkWasm();
+    if (!silk) {
+        throw new Error("silk-wasm not available, cannot encode PCM to SILK. Install silk-wasm to enable voice sending.");
+    }
     const pcmData = new Uint8Array(pcmBuffer.buffer, pcmBuffer.byteOffset, pcmBuffer.byteLength);
-    const result = await encode(pcmData, sampleRate);
+    const result = await silk.encode(pcmData, sampleRate);
     return {
         silkBuffer: Buffer.from(result.data.buffer, result.data.byteOffset, result.data.byteLength),
         duration: result.duration,
@@ -365,10 +391,11 @@ export async function audioFileToSilkBase64(filePath, directUploadFormats) {
         return buf.toString("base64");
     }
     // 1. .slk / .amr 扩展名 → 检测 SILK 魔数，是 SILK 则直传
+    const silk = await loadSilkWasm();
     if ([".slk", ".slac"].includes(ext)) {
         const stripped = stripAmrHeader(buf);
         const raw = new Uint8Array(stripped.buffer, stripped.byteOffset, stripped.byteLength);
-        if (isSilk(raw)) {
+        if (silk?.isSilk(raw)) {
             console.log(`[audio-convert] SILK file, direct use: ${filePath} (${buf.length} bytes)`);
             return buf.toString("base64");
         }
@@ -377,7 +404,7 @@ export async function audioFileToSilkBase64(filePath, directUploadFormats) {
     const rawCheck = new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
     const strippedCheck = stripAmrHeader(buf);
     const strippedRaw = new Uint8Array(strippedCheck.buffer, strippedCheck.byteOffset, strippedCheck.byteLength);
-    if (isSilk(rawCheck) || isSilk(strippedRaw)) {
+    if (silk?.isSilk(rawCheck) || silk?.isSilk(strippedRaw)) {
         console.log(`[audio-convert] SILK detected by header: ${filePath} (${buf.length} bytes)`);
         return buf.toString("base64");
     }
@@ -458,10 +485,11 @@ export async function audioFileToSilkFile(filePath, directUploadFormats) {
         return filePath;
     }
     // 1. 已经是 SILK 编码 → 直接返回原文件
+    const silk = await loadSilkWasm();
     if ([".slk", ".slac"].includes(ext)) {
         const stripped = stripAmrHeader(buf);
         const raw = new Uint8Array(stripped.buffer, stripped.byteOffset, stripped.byteLength);
-        if (isSilk(raw)) {
+        if (silk?.isSilk(raw)) {
             console.log(`[audio-convert] SILK file, direct use: ${filePath} (${buf.length} bytes)`);
             return filePath;
         }
@@ -469,7 +497,7 @@ export async function audioFileToSilkFile(filePath, directUploadFormats) {
     const rawCheck = new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
     const strippedCheck = stripAmrHeader(buf);
     const strippedRaw = new Uint8Array(strippedCheck.buffer, strippedCheck.byteOffset, strippedCheck.byteLength);
-    if (isSilk(rawCheck) || isSilk(strippedRaw)) {
+    if (silk?.isSilk(rawCheck) || silk?.isSilk(strippedRaw)) {
         console.log(`[audio-convert] SILK detected by header: ${filePath} (${buf.length} bytes)`);
         return filePath;
     }

package/index.ts

@@ -29,3 +29,4 @@ export * from "./src/api.js";
 export * from "./src/config.js";
 export * from "./src/gateway.js";
 export * from "./src/outbound.js";
+export * from "./src/transport/index.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tencent-connect/openclaw-qqbot",
-  "version": "1.7.1",
+  "version": "1.7.2",
   "publishConfig": {
     "access": "public"
   },

package/scripts/postinstall-link-sdk.js

@@ -110,6 +110,50 @@ if (!openclawRoot) {
   }
 }
 
+// Strategy 4: pnpm global installation
+// pnpm stores globals in ~/Library/pnpm/global/<ver>/.pnpm/<pkg>@<version>.../node_modules/<pkg>
+// or resolves via `pnpm root -g`
+if (!openclawRoot) {
+  // 4a: try `pnpm root -g`
+  try {
+    const pnpmGlobalRoot = execSync("pnpm root -g", { encoding: "utf-8" }).trim();
+    for (const name of CLI_NAMES) {
+      const candidate = join(pnpmGlobalRoot, name);
+      if (existsSync(join(candidate, "package.json"))) {
+        openclawRoot = candidate;
+        break;
+      }
+    }
+  } catch {}
+
+  // 4b: resolve from the real binary path into .pnpm store
+  if (!openclawRoot) {
+    const whichCmd = process.platform === "win32" ? "where" : "which";
+    for (const name of CLI_NAMES) {
+      try {
+        const bin = execSync(`${whichCmd} ${name}`, { encoding: "utf-8" }).trim().split("\n")[0];
+        if (!bin) continue;
+        const realBin = realpathSync(bin);
+        // pnpm bin layout: .../node_modules/.pnpm/<pkg>@<ver>.../node_modules/<pkg>/dist/bin.js
+        // or .../node_modules/<pkg>/dist/bin.js (hoisted)
+        // Walk up to find node_modules/<name>/package.json
+        let dir = dirname(realBin);
+        for (let i = 0; i < 8; i++) {
+          const candidate = join(dir, "node_modules", name);
+          if (existsSync(join(candidate, "package.json"))) {
+            openclawRoot = candidate;
+            break;
+          }
+          const parent = dirname(dir);
+          if (parent === dir) break;
+          dir = parent;
+        }
+        if (openclawRoot) break;
+      } catch {}
+    }
+  }
+}
+
 if (!openclawRoot) {
   // Not fatal — plugin may work if openclaw loads it with proper alias resolution
   // But log a warning so upgrade scripts can detect the failure