@ryantest/openclaw-qqbot 0.0.1

package/src/bot-logs-2026-03-21T11-21-47(2).txt

@@ -0,0 +1,46 @@
+
+========== gateway.log (last 44 of 44 lines) ==========
+from: C:\Users\v_qachchen\.openclaw
+[2026-03-20T15:55:33.816Z] state: stopped → starting
+[2026-03-20T15:55:33.819Z] [extract] 检测到 runtime.tar.gz，开始解压...
+[2026-03-20T15:55:37.282Z] [extract] runtime.tar.gz 解压完成 (3.5s)
+[2026-03-20T15:55:37.286Z] [extract] 检测到 gateway.tar.gz，开始解压...
+[2026-03-20T15:56:05.916Z] [extract] gateway.tar.gz 解压完成 (28.6s)
+[2026-03-20T15:56:05.924Z] --- gateway start ---
+[2026-03-20T15:56:05.926Z] platform=win32 arch=x64 packaged=true
+[2026-03-20T15:56:05.927Z] resourcesPath=C:\Users\v_qachchen\AppData\Local\Programs\HoldClaw\resources\resources
+[2026-03-20T15:56:05.928Z] nodeBin=C:\Users\v_qachchen\AppData\Local\Programs\HoldClaw\resources\resources\runtime\node.exe exists=true
+[2026-03-20T15:56:05.928Z] entry=C:\Users\v_qachchen\AppData\Local\Programs\HoldClaw\resources\resources\gateway\node_modules\openclaw\openclaw.mjs exists=true
+[2026-03-20T15:56:05.929Z] cwd=C:\Users\v_qachchen\.openclaw\workspace exists=true
+[2026-03-20T15:56:05.929Z] token=a98d...06c4 port=19789
+[2026-03-20T15:56:05.978Z] TTS 未配置，使用默认 SiliconFlow URL
+[2026-03-20T15:56:05.979Z] spawn: C:\Users\v_qachchen\AppData\Local\Programs\HoldClaw\resources\resources\runtime\node.exe C:\Users\v_qachchen\AppData\Local\Programs\HoldClaw\resources\resources\gateway\node_modules\openclaw\openclaw.mjs gateway run --port 19789 --bind loopback
+[2026-03-20T15:56:14.259Z] stdout: |
+o  Doctor warnings ------------------------------------------------------+
+|                                                                        |
+|  - channels.imessage.groupPolicy is "allowlist" but groupAllowFrom is  |
+|    empty — this channel does not fall back to allowFrom, so all group  |
+|    messages will be silently dropped. Add sender IDs to                |
+|    channels.imessage.groupAllowFrom, or set groupPolicy to "open".     |
+|                                                                        |
++------------------------------------------------------------------------+
+[2026-03-20T15:56:44.457Z] stdout: 2026-03-20T15:56:44.457Z [canvas] host mounted at http://127.0.0.1:19789/__openclaw__/canvas/ (root C:\Users\v_qachchen\.openclaw\canvas)
+[2026-03-20T15:56:44.786Z] stdout: 2026-03-20T15:56:44.784Z [heartbeat] started
+[2026-03-20T15:56:44.791Z] stdout: 2026-03-20T15:56:44.791Z [health-monitor] started (interval: 300s, startup-grace: 60s, channel-connect-grace: 120s)
+[2026-03-20T15:56:44.804Z] stdout: 2026-03-20T15:56:44.802Z [gateway] agent model: custom/hy-hunyuan-instruct
+[2026-03-20T15:56:44.806Z] stdout: 2026-03-20T15:56:44.806Z [gateway] listening on ws://127.0.0.1:19789, ws://[::1]:19789 (PID 224544)
+[2026-03-20T15:56:44.812Z] stdout: 2026-03-20T15:56:44.812Z [gateway] log file: \tmp\openclaw\openclaw-2026-03-20.log
+[2026-03-20T15:56:44.929Z] stdout: 2026-03-20T15:56:44.929Z [browser/server] Browser control listening on http://127.0.0.1:19791/ (auth=token)
+[2026-03-20T15:56:45.150Z] health check passed, child alive
+[2026-03-20T15:56:45.151Z] state: starting → running
+[2026-03-20T15:56:46.272Z] stdout: 2026-03-20T15:56:46.112Z [hooks:loader] Registered hook: boot-md -> gateway:startup
+2026-03-20T15:56:46.179Z [hooks:loader] Registered hook: bootstrap-extra-files -> agent:bootstrap
+2026-03-20T15:56:46.247Z [hooks:loader] Registered hook: command-logger -> command
+[2026-03-20T15:56:46.273Z] stderr: 2026-03-20T15:56:46.166Z [ws] closed before connect conn=bd4ae208-a072-4475-8c6b-63daad0e7025 remote=127.0.0.1 fwd=n/a origin=file:// host=127.0.0.1:19789 ua=Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) HoldClaw/1.0.14 Chrome/144.0.7559.225 Electron/40.7.0 Safari/537.36 code=1006 reason=n/a
+2026-03-20T15:56:46.235Z [ws] unauthorized conn=723433fc-d3d5-4065-b919-924e0992dcfe remote=127.0.0.1 client=openclaw-control-ui webchat vdev reason=token_mismatch
+2026-03-20T15:56:46.252Z [ws] closed before connect conn=723433fc-d3d5-4065-b919-924e0992dcfe remote=127.0.0.1 fwd=n/a origin=file:// host=127.0.0.1:19789 ua=Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) HoldClaw/1.0.14 Chrome/144.0.7559.225 Electron/40.7.0 Safari/537.36 code=1008 reason=unauthorized: gateway token mismatch (open the dashboard URL and paste the token in Control UI settings)
+[2026-03-20T15:56:46.318Z] stdout: 2026-03-20T15:56:46.302Z [hooks:loader] Registered hook: session-memory -> command:new, command:reset
+2026-03-20T15:56:46.308Z [hooks] loaded 4 internal hook handlers
+[2026-03-20T15:56:46.637Z] stdout: 2026-03-20T15:56:46.637Z [gateway] update available (latest): v2026.3.13 (current v2026.3.2). Run: openclaw update
+[2026-03-20T15:56:47.076Z] stdout: 2026-03-20T15:56:47.076Z [gateway] device pairing auto-approved device=bd0fa7fe507891dfe0875c53fd38d0582145228b1478b4e62ad102f07d9254df role=operator
+[2026-03-20T15:56:47.081Z] stdout: 2026-03-20T15:56:47.081Z [ws] webchat connected conn=200f754d-9791-4dcc-bfaa-93c839311f65 remote=127.0.0.1 client=openclaw-control-ui webchat vdev

package/src/channel.ts

@@ -0,0 +1,381 @@
+import {
+  type ChannelPlugin,
+  type OpenClawConfig,
+  applyAccountNameToChannelSection,
+  deleteAccountFromConfigSection,
+  setAccountEnabledInConfigSection,
+} from "openclaw/plugin-sdk";
+
+import type { ResolvedQQBotAccount } from "./types.js";
+import { DEFAULT_ACCOUNT_ID, listQQBotAccountIds, resolveQQBotAccount, applyQQBotAccountConfig, resolveDefaultQQBotAccountId } from "./config.js";
+import { sendText, sendMedia } from "./outbound.js";
+import { startGateway } from "./gateway.js";
+import { qqbotOnboardingAdapter } from "./onboarding.js";
+import { getQQBotRuntime } from "./runtime.js";
+import { saveCredentialBackup, loadCredentialBackup } from "./credential-backup.js";
+import { initApiConfig } from "./api.js";
+
+/** QQ Bot 单条消息文本长度上限 */
+export const TEXT_CHUNK_LIMIT = 5000;
+
+/**
+ * Markdown 感知的文本分块函数
+ * 委托给 SDK 内置的 channel.text.chunkMarkdownText
+ * 支持代码块自动关闭/重开、括号感知等
+ */
+export function chunkText(text: string, limit: number): string[] {
+  const runtime = getQQBotRuntime();
+  return runtime.channel.text.chunkMarkdownText(text, limit);
+}
+
+export const qqbotPlugin: ChannelPlugin<ResolvedQQBotAccount> = {
+  id: "qqbot",
+  meta: {
+    id: "qqbot",
+    label: "QQ Bot",
+    selectionLabel: "QQ Bot",
+    docsPath: "/docs/channels/qqbot",
+    blurb: "Connect to QQ via official QQ Bot API",
+    order: 50,
+  },
+  capabilities: {
+    chatTypes: ["direct", "group"],
+    media: true,
+    reactions: false,
+    threads: false,
+    /**
+     * blockStreaming: true 表示该 Channel 支持块流式
+     * 框架会收集流式响应，然后通过 deliver 回调发送
+     */
+    blockStreaming: true,
+  },
+  reload: { configPrefixes: ["channels.qqbot"] },
+  // CLI onboarding wizard
+  onboarding: qqbotOnboardingAdapter,
+
+  config: {
+    listAccountIds: (cfg) => listQQBotAccountIds(cfg),
+    resolveAccount: (cfg, accountId) => resolveQQBotAccount(cfg, accountId),
+    defaultAccountId: (cfg) => resolveDefaultQQBotAccountId(cfg),
+    // 新增：设置账户启用状态
+    setAccountEnabled: ({ cfg, accountId, enabled }) =>
+      setAccountEnabledInConfigSection({
+        cfg,
+        sectionKey: "qqbot",
+        accountId,
+        enabled,
+        allowTopLevel: true,
+      }),
+    // 新增：删除账户
+    deleteAccount: ({ cfg, accountId }) =>
+      deleteAccountFromConfigSection({
+        cfg,
+        sectionKey: "qqbot",
+        accountId,
+        clearBaseFields: ["appId", "clientSecret", "clientSecretFile", "name"],
+      }),
+    isConfigured: (account) => {
+      if (account?.appId && account?.clientSecret) return true;
+      // 配置为空但有凭证备份时仍返回 true，让 startAccount 有机会恢复凭证
+      const backup = loadCredentialBackup(account?.accountId);
+      return backup !== null;
+    },
+    describeAccount: (account) => ({
+      accountId: account?.accountId ?? DEFAULT_ACCOUNT_ID,
+      name: account?.name,
+      enabled: account?.enabled ?? false,
+      configured: Boolean(account?.appId && account?.clientSecret),
+      tokenSource: account?.secretSource,
+    }),
+    // 关键：解析 allowFrom 配置，用于命令授权
+    resolveAllowFrom: ({ cfg, accountId }: { cfg: OpenClawConfig; accountId?: string }) => {
+      const account = resolveQQBotAccount(cfg, accountId);
+      const allowFrom = account.config?.allowFrom ?? [];
+      console.log(`[qqbot] resolveAllowFrom: accountId=${accountId}, allowFrom=${JSON.stringify(allowFrom)}`);
+      return allowFrom.map((entry: string | number) => String(entry));
+    },
+    // 格式化 allowFrom 条目（移除 qqbot: 前缀，统一大写）
+    formatAllowFrom: ({ allowFrom }: { allowFrom: Array<string | number> }) =>
+      allowFrom
+        .map((entry: string | number) => String(entry).trim())
+        .filter(Boolean)
+        .map((entry: string) => entry.replace(/^qqbot:/i, ""))
+        .map((entry: string) => entry.toUpperCase()), // QQ openid 是大写的
+  },
+  setup: {
+    // 新增：规范化账户 ID
+    resolveAccountId: ({ accountId }) => accountId?.trim().toLowerCase() || DEFAULT_ACCOUNT_ID,
+    // 新增：应用账户名称
+    applyAccountName: ({ cfg, accountId, name }) =>
+      applyAccountNameToChannelSection({
+        cfg,
+        channelKey: "qqbot",
+        accountId,
+        name,
+      }),
+    validateInput: ({ input }) => {
+      if (!input.token && !input.tokenFile && !input.useEnv) {
+        return "QQBot requires --token (format: appId:clientSecret) or --use-env";
+      }
+      return null;
+    },
+    applyAccountConfig: ({ cfg, accountId, input }) => {
+      let appId = "";
+      let clientSecret = "";
+
+      if (input.token) {
+        const parts = input.token.split(":");
+        if (parts.length === 2) {
+          appId = parts[0];
+          clientSecret = parts[1];
+        }
+      }
+
+      return applyQQBotAccountConfig(cfg, accountId, {
+        appId,
+        clientSecret,
+        clientSecretFile: input.tokenFile,
+        name: input.name,
+        imageServerBaseUrl: input.imageServerBaseUrl,
+      });
+    },
+  },
+  // Messaging 配置：用于解析目标地址
+  messaging: {
+    /**
+     * 规范化目标地址
+     * 支持以下格式：
+     * - qqbot:c2c:openid -> 私聊
+     * - qqbot:group:groupid -> 群聊
+     * - qqbot:channel:channelid -> 频道
+     * - c2c:openid -> 私聊
+     * - group:groupid -> 群聊
+     * - channel:channelid -> 频道
+     * - 纯 openid（32位十六进制）-> 私聊
+     */
+    normalizeTarget: (target: string): string | undefined => {
+      // 去掉 qqbot: 前缀（如果有）
+      const id = target.replace(/^qqbot:/i, "");
+      
+      // 检查是否是已知格式
+      if (id.startsWith("c2c:") || id.startsWith("group:") || id.startsWith("channel:")) {
+        return `qqbot:${id}`;
+      }
+      
+      // 检查是否是纯 openid（32位十六进制，不带连字符）
+      // QQ Bot OpenID 格式类似: 207A5B8339D01F6582911C014668B77B
+      const openIdHexPattern = /^[0-9a-fA-F]{32}$/;
+      if (openIdHexPattern.test(id)) {
+        return `qqbot:c2c:${id}`;
+      }
+
+      // 检查是否是 UUID 格式的 openid（带连字符）
+      const openIdUuidPattern = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+      if (openIdUuidPattern.test(id)) {
+        return `qqbot:c2c:${id}`;
+      }
+      
+      // 不认识的格式，返回 undefined 让核心使用原始值
+      return undefined;
+    },
+    /**
+     * 目标解析器配置
+     * 用于判断一个目标 ID 是否看起来像 QQ Bot 的格式
+     */
+    targetResolver: {
+      /**
+       * 判断目标 ID 是否可能是 QQ Bot 格式
+       * 支持以下格式：
+       * - qqbot:c2c:xxx
+       * - qqbot:group:xxx  
+       * - qqbot:channel:xxx
+       * - c2c:xxx
+       * - group:xxx
+       * - channel:xxx
+       * - UUID 格式的 openid
+       */
+      looksLikeId: (id: string): boolean => {
+        // 带 qqbot: 前缀的格式
+        if (/^qqbot:(c2c|group|channel):/i.test(id)) {
+          return true;
+        }
+        // 不带前缀但有类型标识
+        if (/^(c2c|group|channel):/i.test(id)) {
+          return true;
+        }
+        // 32位十六进制 openid（不带连字符）
+        if (/^[0-9a-fA-F]{32}$/.test(id)) {
+          return true;
+        }
+        // UUID 格式的 openid（带连字符）
+        const openIdPattern = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+        return openIdPattern.test(id);
+      },
+      hint: "QQ Bot 目标格式: qqbot:c2c:openid (私聊) 或 qqbot:group:groupid (群聊)",
+    },
+  },
+  outbound: {
+    deliveryMode: "direct",
+    chunker: (text, limit) => getQQBotRuntime().channel.text.chunkMarkdownText(text, limit),
+    chunkerMode: "markdown",
+    textChunkLimit: 5000,
+    sendText: async ({ to, text, accountId, replyToId, cfg }) => {
+      console.log(`[qqbot:channel] sendText called — accountId=${accountId}, to=${to}, replyToId=${replyToId}, text.length=${text?.length ?? 0}`);
+      console.log(`[qqbot:channel] sendText text preview: ${text?.slice(0, 100)}${(text?.length ?? 0) > 100 ? "..." : ""}`);
+      const account = resolveQQBotAccount(cfg, accountId);
+      initApiConfig({ markdownSupport: account.markdownSupport });
+      console.log(`[qqbot:channel] sendText resolved account: id=${account.accountId}, appId=${account.appId}, enabled=${account.enabled}`);
+      const result = await sendText({ to, text, accountId, replyToId, account });
+      console.log(`[qqbot:channel] sendText result: messageId=${result.messageId}, error=${result.error ?? "none"}`);
+      return {
+        channel: "qqbot",
+        messageId: result.messageId,
+        error: result.error ? new Error(result.error) : undefined,
+      };
+    },
+    sendMedia: async ({ to, text, mediaUrl, accountId, replyToId, cfg }) => {
+      console.log(`[qqbot:channel] sendMedia called — accountId=${accountId}, to=${to}, replyToId=${replyToId}, mediaUrl=${mediaUrl?.slice(0, 80)}, text.length=${text?.length ?? 0}`);
+      const account = resolveQQBotAccount(cfg, accountId);
+      initApiConfig({ markdownSupport: account.markdownSupport });
+      console.log(`[qqbot:channel] sendMedia resolved account: id=${account.accountId}, appId=${account.appId}, enabled=${account.enabled}`);
+      const result = await sendMedia({ to, text: text ?? "", mediaUrl: mediaUrl ?? "", accountId, replyToId, account });
+      console.log(`[qqbot:channel] sendMedia result: messageId=${result.messageId}, error=${result.error ?? "none"}`);
+      return {
+        channel: "qqbot",
+        messageId: result.messageId,
+        error: result.error ? new Error(result.error) : undefined,
+      };
+    },
+  },
+  gateway: {
+    startAccount: async (ctx) => {
+      let { account } = ctx;
+      const { abortSignal, log, cfg } = ctx;
+
+      // 凭证恢复：如果 appId/secret 为空（热更新打断可能导致配置丢失），尝试从暂存文件恢复
+      if (!account.appId || !account.clientSecret) {
+        const backup = loadCredentialBackup(account.accountId);
+        if (backup) {
+          log?.info(`[qqbot:${account.accountId}] 配置中凭证为空，从暂存文件恢复 (appId=${backup.appId}, savedAt=${backup.savedAt})`);
+          try {
+            const runtime = getQQBotRuntime();
+            const restoredCfg = applyQQBotAccountConfig(cfg, account.accountId, {
+              appId: backup.appId,
+              clientSecret: backup.clientSecret,
+            });
+            const configApi = runtime.config as { writeConfigFile: (cfg: unknown) => Promise<void> };
+            await configApi.writeConfigFile(restoredCfg);
+            // 重新解析 account 以获取恢复后的值
+            account = resolveQQBotAccount(restoredCfg, account.accountId);
+            log?.info(`[qqbot:${account.accountId}] 凭证已恢复`);
+          } catch (e) {
+            log?.error(`[qqbot:${account.accountId}] 凭证恢复失败: ${e}`);
+          }
+        }
+      }
+
+      log?.info(`[qqbot:${account.accountId}] Starting gateway — appId=${account.appId}, enabled=${account.enabled}, name=${account.name ?? "unnamed"}`);
+      console.log(`[qqbot:channel] startAccount: accountId=${account.accountId}, appId=${account.appId}, secretSource=${account.secretSource}`);
+
+      await startGateway({
+        account,
+        abortSignal,
+        cfg,
+        log,
+        onReady: () => {
+          log?.info(`[qqbot:${account.accountId}] Gateway ready`);
+          // 启动成功，保存凭证快照供后续恢复使用
+          saveCredentialBackup(account.accountId, account.appId, account.clientSecret);
+          ctx.setStatus({
+            ...ctx.getStatus(),
+            running: true,
+            connected: true,
+            lastConnectedAt: Date.now(),
+          });
+        },
+        onError: (error) => {
+          log?.error(`[qqbot:${account.accountId}] Gateway error: ${error.message}`);
+          ctx.setStatus({
+            ...ctx.getStatus(),
+            lastError: error.message,
+          });
+        },
+      });
+    },
+    // 新增：登出账户（清除配置中的凭证）
+    logoutAccount: async ({ accountId, cfg }) => {
+      const nextCfg = { ...cfg } as OpenClawConfig;
+      const nextQQBot = cfg.channels?.qqbot ? { ...cfg.channels.qqbot } : undefined;
+      let cleared = false;
+      let changed = false;
+
+      if (nextQQBot) {
+        const qqbot = nextQQBot as Record<string, unknown>;
+        if (accountId === DEFAULT_ACCOUNT_ID && qqbot.clientSecret) {
+          delete qqbot.clientSecret;
+          cleared = true;
+          changed = true;
+        }
+        const accounts = qqbot.accounts as Record<string, Record<string, unknown>> | undefined;
+        if (accounts && accountId in accounts) {
+          const entry = accounts[accountId] as Record<string, unknown> | undefined;
+          if (entry && "clientSecret" in entry) {
+            delete entry.clientSecret;
+            cleared = true;
+            changed = true;
+          }
+          if (entry && Object.keys(entry).length === 0) {
+            delete accounts[accountId];
+            changed = true;
+          }
+        }
+      }
+
+      if (changed && nextQQBot) {
+        nextCfg.channels = { ...nextCfg.channels, qqbot: nextQQBot };
+        const runtime = getQQBotRuntime();
+        const configApi = runtime.config as { writeConfigFile: (cfg: OpenClawConfig) => Promise<void> };
+        await configApi.writeConfigFile(nextCfg);
+      }
+
+      const resolved = resolveQQBotAccount(changed ? nextCfg : cfg, accountId);
+      const loggedOut = resolved.secretSource === "none";
+      const envToken = Boolean(process.env.QQBOT_CLIENT_SECRET);
+
+      return { ok: true, cleared, envToken, loggedOut };
+    },
+  },
+  status: {
+    defaultRuntime: {
+      accountId: DEFAULT_ACCOUNT_ID,
+      running: false,
+      connected: false,
+      lastConnectedAt: null,
+      lastError: null,
+      lastInboundAt: null,
+      lastOutboundAt: null,
+    },
+    // 新增：构建通道摘要
+    buildChannelSummary: ({ snapshot }: { snapshot: Record<string, unknown> }) => ({
+      configured: snapshot.configured ?? false,
+      tokenSource: snapshot.tokenSource ?? "none",
+      running: snapshot.running ?? false,
+      connected: snapshot.connected ?? false,
+      lastConnectedAt: snapshot.lastConnectedAt ?? null,
+      lastError: snapshot.lastError ?? null,
+    }),
+    buildAccountSnapshot: ({ account, runtime }: { account?: ResolvedQQBotAccount; runtime?: Record<string, unknown> }) => ({
+      accountId: account?.accountId ?? DEFAULT_ACCOUNT_ID,
+      name: account?.name,
+      enabled: account?.enabled ?? false,
+      configured: Boolean(account?.appId && account?.clientSecret),
+      tokenSource: account?.secretSource,
+      running: runtime?.running ?? false,
+      connected: runtime?.connected ?? false,
+      lastConnectedAt: runtime?.lastConnectedAt ?? null,
+      lastError: runtime?.lastError ?? null,
+      lastInboundAt: runtime?.lastInboundAt ?? null,
+      lastOutboundAt: runtime?.lastOutboundAt ?? null,
+    }),
+  },
+};

package/src/config.ts

@@ -0,0 +1,187 @@
+import type { ResolvedQQBotAccount, QQBotAccountConfig } from "./types.js";
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+
+export const DEFAULT_ACCOUNT_ID = "default";
+
+interface QQBotChannelConfig extends QQBotAccountConfig {
+  accounts?: Record<string, QQBotAccountConfig>;
+}
+
+function normalizeAppId(raw: unknown): string {
+  if (raw === null || raw === undefined) return "";
+  return String(raw).trim();
+}
+
+/**
+ * 列出所有 QQBot 账户 ID
+ */
+export function listQQBotAccountIds(cfg: OpenClawConfig): string[] {
+  const ids = new Set<string>();
+  const qqbot = cfg.channels?.qqbot as QQBotChannelConfig | undefined;
+
+  if (qqbot?.appId) {
+    ids.add(DEFAULT_ACCOUNT_ID);
+  }
+
+  if (qqbot?.accounts) {
+    for (const accountId of Object.keys(qqbot.accounts)) {
+      if (qqbot.accounts[accountId]?.appId) {
+        ids.add(accountId);
+      }
+    }
+  }
+
+  return Array.from(ids);
+}
+
+/**
+ * 获取默认账户 ID
+ */
+export function resolveDefaultQQBotAccountId(cfg: OpenClawConfig): string {
+  const qqbot = cfg.channels?.qqbot as QQBotChannelConfig | undefined;
+  // 如果有默认账户配置，返回 default
+  if (qqbot?.appId) {
+    return DEFAULT_ACCOUNT_ID;
+  }
+  // 否则返回第一个配置的账户
+  if (qqbot?.accounts) {
+    const ids = Object.keys(qqbot.accounts);
+    if (ids.length > 0) {
+      return ids[0];
+    }
+  }
+  return DEFAULT_ACCOUNT_ID;
+}
+
+/**
+ * 解析 QQBot 账户配置
+ */
+export function resolveQQBotAccount(
+  cfg: OpenClawConfig,
+  accountId?: string | null
+): ResolvedQQBotAccount {
+  const resolvedAccountId = accountId ?? DEFAULT_ACCOUNT_ID;
+  const qqbot = cfg.channels?.qqbot as QQBotChannelConfig | undefined;
+
+  // 基础配置
+  let accountConfig: QQBotAccountConfig = {};
+  let appId = "";
+  let clientSecret = "";
+  let secretSource: "config" | "file" | "env" | "none" = "none";
+
+  if (resolvedAccountId === DEFAULT_ACCOUNT_ID) {
+    // 默认账户从顶层读取
+    accountConfig = {
+      enabled: qqbot?.enabled,
+      name: qqbot?.name,
+      appId: qqbot?.appId,
+      clientSecret: qqbot?.clientSecret,
+      clientSecretFile: qqbot?.clientSecretFile,
+      dmPolicy: qqbot?.dmPolicy,
+      allowFrom: qqbot?.allowFrom,
+      systemPrompt: qqbot?.systemPrompt,
+      imageServerBaseUrl: qqbot?.imageServerBaseUrl,
+      markdownSupport: qqbot?.markdownSupport ?? true,
+    };
+    appId = normalizeAppId(qqbot?.appId);
+  } else {
+    // 命名账户从 accounts 读取
+    const account = qqbot?.accounts?.[resolvedAccountId];
+    accountConfig = account ?? {};
+    appId = normalizeAppId(account?.appId);
+  }
+
+  // 解析 clientSecret
+  if (accountConfig.clientSecret) {
+    clientSecret = accountConfig.clientSecret;
+    secretSource = "config";
+  } else if (accountConfig.clientSecretFile) {
+    // 从文件读取（运行时处理）
+    secretSource = "file";
+  } else if (process.env.QQBOT_CLIENT_SECRET && resolvedAccountId === DEFAULT_ACCOUNT_ID) {
+    clientSecret = process.env.QQBOT_CLIENT_SECRET;
+    secretSource = "env";
+  }
+
+  // AppId 也可以从环境变量读取
+  if (!appId && process.env.QQBOT_APP_ID && resolvedAccountId === DEFAULT_ACCOUNT_ID) {
+    appId = normalizeAppId(process.env.QQBOT_APP_ID);
+  }
+
+  return {
+    accountId: resolvedAccountId,
+    name: accountConfig.name,
+    enabled: accountConfig.enabled !== false,
+    appId,
+    clientSecret,
+    secretSource,
+    systemPrompt: accountConfig.systemPrompt,
+    imageServerBaseUrl: accountConfig.imageServerBaseUrl || process.env.QQBOT_IMAGE_SERVER_BASE_URL,
+    markdownSupport: accountConfig.markdownSupport !== false,
+    config: accountConfig,
+  };
+}
+
+/**
+ * 应用账户配置
+ */
+export function applyQQBotAccountConfig(
+  cfg: OpenClawConfig,
+  accountId: string,
+  input: { appId?: string; clientSecret?: string; clientSecretFile?: string; name?: string; imageServerBaseUrl?: string }
+): OpenClawConfig {
+  const next = { ...cfg };
+
+  if (accountId === DEFAULT_ACCOUNT_ID) {
+    // 如果没有设置过 allowFrom，默认设置为 ["*"]
+    const existingConfig = (next.channels?.qqbot as QQBotChannelConfig) || {};
+    const allowFrom = existingConfig.allowFrom ?? ["*"];
+    
+    next.channels = {
+      ...next.channels,
+      qqbot: {
+        ...(next.channels?.qqbot as Record<string, unknown> || {}),
+        enabled: true,
+        allowFrom,
+        ...(input.appId ? { appId: input.appId } : {}),
+        ...(input.clientSecret
+          ? { clientSecret: input.clientSecret }
+          : input.clientSecretFile
+            ? { clientSecretFile: input.clientSecretFile }
+            : {}),
+        ...(input.name ? { name: input.name } : {}),
+        ...(input.imageServerBaseUrl ? { imageServerBaseUrl: input.imageServerBaseUrl } : {}),
+      },
+    };
+  } else {
+    // 如果没有设置过 allowFrom，默认设置为 ["*"]
+    const existingAccountConfig = (next.channels?.qqbot as QQBotChannelConfig)?.accounts?.[accountId] || {};
+    const allowFrom = existingAccountConfig.allowFrom ?? ["*"];
+    
+    next.channels = {
+      ...next.channels,
+      qqbot: {
+        ...(next.channels?.qqbot as Record<string, unknown> || {}),
+        enabled: true,
+        accounts: {
+          ...((next.channels?.qqbot as QQBotChannelConfig)?.accounts || {}),
+          [accountId]: {
+            ...((next.channels?.qqbot as QQBotChannelConfig)?.accounts?.[accountId] || {}),
+            enabled: true,
+            allowFrom,
+            ...(input.appId ? { appId: input.appId } : {}),
+            ...(input.clientSecret
+              ? { clientSecret: input.clientSecret }
+              : input.clientSecretFile
+                ? { clientSecretFile: input.clientSecretFile }
+                : {}),
+            ...(input.name ? { name: input.name } : {}),
+            ...(input.imageServerBaseUrl ? { imageServerBaseUrl: input.imageServerBaseUrl } : {}),
+          },
+        },
+      },
+    };
+  }
+
+  return next;
+}

package/src/credential-backup.ts

@@ -0,0 +1,72 @@
+/**
+ * 凭证暂存与恢复
+ *
+ * 解决热更新被打断时 openclaw.json 中 appId/secret 丢失的问题。
+ *
+ * 原理：
+ *   - 每次 gateway 成功启动后，把当前账户的 appId/secret 写入暂存文件
+ *   - 插件启动时如果检测到配置中 appId/secret 为空，尝试从暂存文件恢复
+ *   - 暂存文件存储在 ~/.openclaw/qqbot/data/ 下，不受插件目录替换影响
+ *
+ * 安全保障：
+ *   - 只在 appId/secret **确实为空** 时才尝试恢复（不干扰正常配置变更）
+ *   - 恢复后通过 openclaw 的 config API 写回配置文件，确保框架感知到变更
+ *   - 暂存文件使用原子写入（先写 .tmp 再 rename）防止损坏
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { getQQBotDataDir } from "./utils/platform.js";
+
+const BACKUP_FILENAME = "credential-backup.json";
+
+interface CredentialBackup {
+  accountId: string;
+  appId: string;
+  clientSecret: string;
+  savedAt: string;
+}
+
+function getBackupPath(): string {
+  return path.join(getQQBotDataDir("data"), BACKUP_FILENAME);
+}
+
+/**
+ * 保存凭证快照到暂存文件（gateway 成功启动后调用）
+ */
+export function saveCredentialBackup(accountId: string, appId: string, clientSecret: string): void {
+  if (!appId || !clientSecret) return; // 不保存空凭证
+  try {
+    const backupPath = getBackupPath();
+    const data: CredentialBackup = {
+      accountId,
+      appId,
+      clientSecret,
+      savedAt: new Date().toISOString(),
+    };
+    const tmpPath = backupPath + ".tmp";
+    fs.writeFileSync(tmpPath, JSON.stringify(data, null, 2) + "\n", "utf8");
+    fs.renameSync(tmpPath, backupPath);
+  } catch {
+    // 非关键操作，静默忽略
+  }
+}
+
+/**
+ * 从暂存文件读取凭证（仅在配置为空时调用）
+ * 返回 null 表示无可用备份
+ */
+export function loadCredentialBackup(accountId?: string): CredentialBackup | null {
+  try {
+    const backupPath = getBackupPath();
+    if (!fs.existsSync(backupPath)) return null;
+    const raw = fs.readFileSync(backupPath, "utf8");
+    const data: CredentialBackup = JSON.parse(raw);
+    if (!data.appId || !data.clientSecret) return null;
+    // 如果指定了 accountId，校验是否匹配
+    if (accountId && data.accountId !== accountId) return null;
+    return data;
+  } catch {
+    return null;
+  }
+}