@cxyhhhhh/openclaw-qqbot 2.0.0-dev.202607101321 → 2.0.0-dev.202607101939

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cxyhhhhh/openclaw-qqbot",
-  "version": "2.0.0-dev.202607101321",
+  "version": "2.0.0-dev.202607101939",
   "description": "QQ Bot channel plugin for OpenClaw",
   "publishConfig": {
     "access": "public"
@@ -42,7 +42,7 @@
   },
   "dependencies": {
     "@tencent-connect/qqbot-connector": "1.2.0",
-    "@tencent-connect/qqbot-nodejs": "npm:@cxyhhhhh/qqbot-nodejs@1.0.2-dev.202607101142"
+    "@tencent-connect/qqbot-nodejs": "npm:@cxyhhhhh/qqbot-nodejs@1.0.2-dev.202607101530"
   },
   "devDependencies": {
     "@types/node": "^20.19.43",

package/src/adapter/contract.ts

@@ -8,7 +8,7 @@
 import type { PluginRuntime } from 'openclaw/plugin-sdk';
 import { createPluginLogger } from '../utils/plugin-logger.js';
 
-const log = createPluginLogger({ prefix: '[contract]', forceConsole: true });
+const log = createPluginLogger({ prefix: '[contract]', forceConsole: false });
 
 interface ApiProbe {
   name: string;

package/src/adapter/resolve.ts

@@ -285,6 +285,44 @@ export function getAdapters(
   return _cachedAdapters;
 }
 
+/**
+ * 持久化配置（auth.login 场景，兼容高低版本）。
+ *
+ * 探测顺序：
+ *   1. config.mutateConfigFile  — 新版原子操作
+ *   2. config.writeConfigFile   — 旧版整体覆盖
+ *   3. writeConfigFile          — 更旧的顶层 API
+ */
+export async function persistAuthConfig(
+  runtime: Record<string, unknown>,
+  cfg: Record<string, unknown>,
+  afterWrite = 'restart',
+): Promise<void> {
+  const config: Record<string, unknown> | undefined = runtime.config as any;
+
+  if (typeof config?.mutateConfigFile === 'function') {
+    await (config.mutateConfigFile as Function)({
+      mutate: () => cfg,
+      afterWrite,
+    });
+    return;
+  }
+  if (typeof config?.writeConfigFile === 'function') {
+    await (config.writeConfigFile as Function)(cfg);
+    return;
+  }
+  if (typeof runtime.writeConfigFile === 'function') {
+    await (runtime.writeConfigFile as Function)(cfg);
+    return;
+  }
+
+  // 最后兜底：裸写文件
+  const { homedir } = await import('node:os');
+  const { join } = await import('node:path');
+  const { writeFileSync } = await import('node:fs');
+  writeFileSync(join(homedir(), '.openclaw', 'openclaw.json'), JSON.stringify(cfg, null, 2) + '\n', 'utf-8');
+}
+
 /**
  * 强制清除 adapter 缓存（仅测试用）
  */

package/src/channel.ts

@@ -29,6 +29,7 @@ import { sendText, getGateway } from './outbound/outbound-service.js';
 import { sendMedia } from './outbound/media-send.js';
 import type { PluginLogger } from './utils/plugin-logger.js';
 import { qqbotSetupWizard } from './setup/surface.js';
+import { qqbotLogin, startQrLogin, waitQrLogin } from './setup/login.js';
 import { normalizeTarget, isQQBotTarget } from './outbound/target.js';
 import { sanitizeQQBotText } from './outbound/sanitize.js';
 import { startAccountWithCredentialRecovery, logoutAndClearCredentials, stopAccountGracefully } from './gateway/lifecycle.js';
@@ -72,6 +73,7 @@ export const qqbotPlugin: ChannelPlugin<ResolvedQQBotAccount> = {
     threads: false,
     blockStreaming: false,
   },
+  gatewayMethods: ['web.login.start', 'web.login.wait'],
   reload: { configPrefixes: ['channels.qqbot'] },
 
   // ── 群消息策略 ──
@@ -266,6 +268,19 @@ export const qqbotPlugin: ChannelPlugin<ResolvedQQBotAccount> = {
       });
     },
     logoutAccount: (params) => logoutAndClearCredentials(params),
+    loginWithQrStart: async ({ accountId }: { accountId?: string }) => startQrLogin(accountId),
+    loginWithQrWait: async ({ accountId }: { accountId?: string }) => {
+      const result = await waitQrLogin(accountId);
+      return { connected: result.connected, message: result.message };
+    },
+  },
+
+  // ── 登录认证 ──
+  auth: {
+    login: qqbotLogin as any,
+    // 审批权限（从 approvalStubs 迁移）
+    authorizeActorAction: () => ({ authorized: true } as const),
+    getActionAvailabilityState: () => ({ kind: 'enabled' as const } as const),
   },
 
   // ── 状态 ──

package/src/dispatch/body-assembler.ts

@@ -298,8 +298,8 @@ function buildAgentBody(input: {
 }): string {
   const { userContent, base, isGroup, wasMentioned, history } = input;
 
-  // 斜杠命令直通：去除一切装饰
-  if (userContent.startsWith('/')) {
+  // 斜杠命令直通：去除一切装饰及首尾空白
+  if (userContent.trim().startsWith('/')) {
     return userContent;
   }
 

package/src/features/approval-utils.ts

@@ -28,10 +28,6 @@ export const approvalStubs = {
     buildPendingPayload: () => null,
     buildResolvedPayload: () => null,
   },
-  auth: {
-    authorizeActorAction: () => ({ authorized: true }),
-    getActionAvailabilityState: () => ({ kind: 'enabled' as const }),
-  },
   approvals: {
     delivery: {
       hasConfiguredDmRoute: () => true,

package/src/gateway/middleware-setup.ts

@@ -27,6 +27,7 @@ import { getPersistedRefIndexStore } from '../features/ref-index-store.js';
 import { createPolicyInjector } from '../middleware/policy-injector.js';
 import { getHistoryStore, historyGroupKey } from '../features/history-store.js';
 import { dynamicAccessControl } from '../middleware/access-control.js';
+import { stripMentionText } from '../utils/mention.js';
 
 export interface MiddlewareSetupOptions {
   /** 获取 runtime */
@@ -66,14 +67,23 @@ export function setupMiddlewares(bot: QQBot, account: ResolvedQQBotAccount, opts
 
   // 6. 群聊 @bot 门控（从 ctx.state.policy.group 读取动态配置）
   bot.use(mentionGate());
-
   // 7. 内容清洗（去 @marker、表情标签、多余空白）
-  bot.use(contentSanitizer({ parseFaceTags: true }));
+  // SDK 用 appId 匹配 @标记，但 QQ openid 不等于 appId，追加 stripMentionText 正确剥离
+  bot.use(contentSanitizer({
+    parseFaceTags: true,
+    transform: (content, ctx) => stripMentionText(content, (ctx.message as any).mentions),
+  }));
 
   // 8. 三层限流（sender / group / global）
   bot.use(rateLimiter());
 
-  // 9. 并发串行+合并（在副作用中间件之前）
+  // 9. 斜杠命令（在并发锁之前，命令匹配后直接 reply + stop，不排队）
+  //    依赖：ctx.state.policy（policyInjector, #3）、ctx.message.*（原始消息）
+  //    注意：/stop 是框架级命令，不在 qqbot 命令列表中，仍由 urgentPredicate 处理
+  const slash = slashCommand({ commands: buildCommandList(account, { getRuntime: opts.getRuntime }) });
+  bot.use(slash.middleware);
+
+  // 10. 并发串行+合并（在副作用中间件之前）
   //     - 同 peer 串行处理，避免平台 session conflict
   //     - 处理中消息暂存 buffer；完成后合并为一条，继续走完剩余中间件链
   //       （typingIndicator/quoteRef/attachmentProcessor/... 直到 bot.on("message")）
@@ -107,18 +117,18 @@ export function setupMiddlewares(bot: QQBot, account: ResolvedQQBotAccount, opts
     },
   }));
 
-  // 10. C2C 输入状态指示器
+  // 11. C2C 输入状态指示器
   bot.use(typingIndicator());
 
-  // 11. 引用消息解析（默认优先 msg_elements 获取文件名等丰富信息）
+  // 12. 引用消息解析（默认优先 msg_elements 获取文件名等丰富信息）
   bot.use(quoteRef({
     store: getPersistedRefIndexStore(account.accountId),
   }));
 
-  // 12. 附件处理（语音 STT 转录 + 图片/文件下载）
+  // 13. 附件处理（语音 STT 转录 + 图片/文件下载）
   bot.use(attachmentProcessor({ getRuntime: opts.getRuntime }));
 
-  // 13. 上下文组装（构建框架规约的 body）
+  // 14. 上下文组装（构建框架规约的 body）
   bot.use(envelopeFormatter({
     format: (ctx) => {
       const assembled = assembleBody(ctx, ctx.message as never, account, opts.getRuntime);
@@ -126,8 +136,4 @@ export function setupMiddlewares(bot: QQBot, account: ResolvedQQBotAccount, opts
       return assembled.agentBody;
     },
   }));
-
-  // 14. 斜杠命令（命令被匹配后直接回复，不再向下传递）
-  const slash = slashCommand({ commands: buildCommandList(account, { getRuntime: opts.getRuntime }) });
-  bot.use(slash.middleware);
 }

package/src/openclaw-plugin-sdk.d.ts

@@ -691,7 +691,23 @@ declare module "openclaw/plugin-sdk/setup" {
   export interface ChannelSetupWizard {
     channel: string;
     status: ChannelSetupWizardStatus;
+    /** 解析配置时使用哪个账户 ID：无账户时默认 'default' */
+    resolveAccountIdForConfigure?: (params: {
+      cfg: unknown;
+      prompter: unknown;
+      options?: unknown;
+      accountOverride?: string;
+      shouldPromptAccountIds: boolean;
+      listAccountIds: (cfg: unknown) => string[];
+      defaultAccountId: string;
+    }) => string | Promise<string>;
+    resolveShouldPromptAccountIds?: (params: {
+      cfg: unknown;
+      options?: unknown;
+      shouldPromptAccountIds: boolean;
+    }) => boolean;
     credentials?: Array<{ id: string; label: string }>;
+    textInputs?: Array<{ id: string; label: string; placeholder?: string }>;
     onStatusChange?: (params: { cfg: unknown }) => void | Promise<void>;
     configure?: (params: { cfg: unknown; accountId: string; prompter: unknown; runtime: unknown }) => Promise<unknown>;
     finalize: (params: { cfg: unknown; accountId: string; prompter: unknown; runtime: unknown }) => Promise<unknown>;

package/src/outbound/media-send.ts

@@ -78,14 +78,51 @@ function resolveTempRoots(): string[] {
   return [...roots];
 }
 
-const ALLOWED_MEDIA_ROOTS = [
-  path.join(os.homedir(), '.openclaw', 'media'),
-  path.join(os.homedir(), '.openclaw', 'workspace'),
-  // 框架 outbound 目录（saveMediaBuffer 写入）
-  path.join(os.homedir(), '.openclaw', 'outbound'),
-  // TTS 语音临时目录（deliver-pipeline 已通过 isTtsPathSafe 预检）
-  ...resolveTempRoots(),
-];
+/**
+ * 构建动态白名单目录列表。
+ *
+ * 从 openclaw 核心已解析的 workspaceDir 反向推导配置目录，
+ * 同时保留已知配置目录名以向后兼容。
+ */
+function buildDynamicAllowedRoots(workspaceDir?: string): string[] {
+  const home = os.homedir();
+  const derivedBase = workspaceDir ? path.dirname(workspaceDir) : path.join(home, '.openclaw');
+  const roots: string[] = [];
+  const added = new Set<string>();
+
+  const addRoot = (p: string) => {
+    try {
+      const real = fs.existsSync(p) ? fs.realpathSync(p) : p;
+      if (!added.has(real)) {
+        added.add(real);
+        roots.push(real);
+      }
+    } catch { /* skip */ }
+  };
+
+  // 已知配置目录名（包括默认和开发模式）
+  const knownBases = [path.join(home, '.openclaw'), path.join(home, '.openclaw-dev')];
+
+  // 当前配置目录优先（从 workspaceDir 反推）
+  if (workspaceDir) {
+    addRoot(path.join(derivedBase, 'media'));
+    addRoot(path.join(derivedBase, 'workspace'));
+    addRoot(path.join(derivedBase, 'outbound'));
+    addRoot(workspaceDir);
+  }
+
+  // 所有已知配置目录（去重，确保向后兼容）
+  for (const base of knownBases) {
+    addRoot(path.join(base, 'media'));
+    addRoot(path.join(base, 'workspace'));
+    addRoot(path.join(base, 'outbound'));
+  }
+
+  // 临时目录
+  for (const t of resolveTempRoots()) addRoot(t);
+
+  return roots;
+}
 
 /** 入站 Base64 / Data URL 最大字节数（10MB） */
 const MAX_DATA_URL_BYTES = 10 * 1024 * 1024;
@@ -198,7 +235,9 @@ async function resolveMediaPath(source: string, log?: SendMediaParams['log'], wo
     return { ok: false, error: `Cannot resolve path: ${resolved}` };
   }
 
-  const allowed = isPathInAllowedRoots(real, ALLOWED_MEDIA_ROOTS);
+  // 动态白名单：静态根目录 + 当前 agent 工作区
+  const dynamicRoots = buildDynamicAllowedRoots(workspaceDir);
+  const allowed = isPathInAllowedRoots(real, dynamicRoots);
 
   if (!allowed) {
     log?.warn(`path blocked — not in allowed directory: ${real}`);

package/src/setup/account-key.ts

@@ -0,0 +1,41 @@
+/**
+ * 账户键解析 — setup / login 共用
+ *
+ * 统一确定扫码/绑定凭据应写入哪个账户键。
+ */
+
+import type { OpenClawConfig } from 'openclaw/plugin-sdk';
+import { listQQBotAccountIds, resolveQQBotAccount } from '../config.js';
+
+/**
+ * 解析凭据写入的目标账户键。
+ *
+ * @param cfg    当前配置
+ * @param appId  扫码或输入的 AppID
+ * @param resolvedId  用户显式指定的账户名（如 --account / setup wizard），可选
+ * @returns 账户键
+ *
+ * 优先级：
+ *   1. resolvedId 指定 → 直接使用
+ *   2. 已有同 appId 的账户 → 刷新凭据（复用该账户键）
+ *   3. 零账户 → 'default'（首次配置）
+ *   4. 已有其他账户 → appId（新增独立账户）
+ */
+export function resolveAccountKey(
+  cfg: OpenClawConfig,
+  appId: string,
+  resolvedId?: string | null,
+): string {
+  if (resolvedId) return resolvedId;
+
+  // 同 appId → 刷新
+  for (const id of listQQBotAccountIds(cfg)) {
+    if (resolveQQBotAccount(cfg, id).appId === appId) return id;
+  }
+
+  // 零账户 → default
+  if (listQQBotAccountIds(cfg).length === 0) return 'default';
+
+  // 新增账户
+  return appId;
+}

package/src/setup/finalize.ts

@@ -5,6 +5,7 @@ import type { OpenClawConfig } from 'openclaw/plugin-sdk';
 import { DEFAULT_ACCOUNT_ID, formatDocsLink } from '../adapter/setup.js';
 import { qrConnect } from '@tencent-connect/qqbot-connector';
 import { applyQQBotAccountConfig, resolveQQBotAccount } from '../config.js';
+import { resolveAccountKey } from './account-key.js';
 
 type Prompter = {
   select: (opts: { message: string; options: Array<{ value: string; label: string; hint?: string }> }) => Promise<string>;
@@ -22,7 +23,7 @@ function isConfigured(cfg: OpenClawConfig, accountId: string): boolean {
   return Boolean(account.appId && account.clientSecret);
 }
 
-async function linkViaQrCode(cfg: OpenClawConfig, accountId: string, prompter: Prompter, rt: Runtime): Promise<OpenClawConfig> {
+async function linkViaQrCode(cfg: OpenClawConfig, _accountId: string, prompter: Prompter, rt: Runtime): Promise<OpenClawConfig> {
   try {
     const accounts: Array<{ appId: string; appSecret: string; userOpenid?: string }> = await qrConnect({ source: 'openclaw' });
 
@@ -33,15 +34,13 @@ async function linkViaQrCode(cfg: OpenClawConfig, accountId: string, prompter: P
 
     let next = cfg;
     for (const { appId, appSecret, userOpenid } of accounts) {
-      next = applyQQBotAccountConfig(next, appId, { appId, clientSecret: appSecret });
-      next = applyAccountDefaults(next, appId, userOpenid);
+      // 同 appId 刷新；零账户 default；已有账户新增 appId
+      const key = resolveAccountKey(cfg, appId);
+      next = applyQQBotAccountConfig(next, key, { appId, clientSecret: appSecret });
+      next = applyAccountDefaults(next, key, userOpenid);
+      rt.log(`绑定成功！账户: ${key} (AppID: ${appId})`);
     }
 
-    if (accounts.length === 1) {
-      rt.log(`✔ QQ Bot 绑定成功！(AppID: ${accounts[0].appId})`);
-    } else {
-      rt.log(`✔ ${accounts.length} 个 QQ Bot 绑定成功！(AppID: ${accounts.map((a) => a.appId).join(', ')})`);
-    }
     return next;
   } catch (err) {
     rt.error(`QQ Bot 绑定失败: ${String(err)}`);
@@ -50,11 +49,13 @@ async function linkViaQrCode(cfg: OpenClawConfig, accountId: string, prompter: P
   }
 }
 
-async function linkViaManual(cfg: OpenClawConfig, prompter: Prompter): Promise<OpenClawConfig> {
-  const appId = await prompter.text({ message: '请输入 QQ Bot AppID', validate: (v) => v.trim() ? undefined : 'AppID 不能为空' });
+async function linkViaManual(cfg: OpenClawConfig, _accountId: string, prompter: Prompter): Promise<OpenClawConfig> {
+  const appIdInput = await prompter.text({ message: '请输入 QQ Bot AppID', validate: (v) => v.trim() ? undefined : 'AppID 不能为空' });
   const secret = await prompter.text({ message: '请输入 QQ Bot AppSecret', validate: (v) => v.trim() ? undefined : 'AppSecret 不能为空' });
-  let next = applyQQBotAccountConfig(cfg, appId.trim(), { appId: appId.trim(), clientSecret: secret.trim() });
-  next = applyAccountDefaults(next, appId.trim());
+  const appId = appIdInput.trim();
+  const key = resolveAccountKey(cfg, appId);
+  let next = applyQQBotAccountConfig(cfg, key, { appId, clientSecret: secret.trim() });
+  next = applyAccountDefaults(next, key);
   await prompter.note('✔ QQ Bot 配置完成！', 'QQ Bot');
   return next;
 }
@@ -81,7 +82,7 @@ export async function finalizeQQBotSetup(params: {
   if (mode === 'qr') {
     next = await linkViaQrCode(next, accountId, params.prompter, params.runtime);
   } else if (mode === 'manual') {
-    next = await linkViaManual(next, params.prompter);
+    next = await linkViaManual(next, accountId, params.prompter);
   } else if (!configured) {
     await params.prompter.note('您可以稍后运行以下命令重新配置：\n  openclaw channels add', 'QQ Bot');
   }
@@ -89,7 +90,7 @@ export async function finalizeQQBotSetup(params: {
   return { cfg: next };
 }
 
-function applyAccountDefaults(cfg: OpenClawConfig, accountId: string, userOpenid?: string): OpenClawConfig {
+export function applyAccountDefaults(cfg: OpenClawConfig, accountId: string, userOpenid?: string): OpenClawConfig {
   const next = { ...cfg, channels: { ...cfg.channels } };
   const qqbot = { ...(next.channels?.qqbot as Record<string, unknown> ?? {}) } as Record<string, unknown>;
 

package/src/setup/login.ts

@@ -0,0 +1,197 @@
+/**
+ * QQ Bot QR 登录 — 两阶段接口适配
+ *
+ * 使用 @tencent-connect/qqbot-connector 的 startQrConnect 回调 API，
+ * 将扫码绑定流程拆分为 start / wait 两个阶段，对接 ChannelPlugin 的
+ * gateway.loginWithQrStart / loginWithQrWait。
+ */
+import { startQrConnect, type QrConnectCredentials } from '@tencent-connect/qqbot-connector';
+
+// ── 类型 ──
+
+export interface QrLoginStartResult {
+  qrDataUrl?: string;
+  message: string;
+}
+
+export interface QrLoginWaitResult {
+  connected: boolean;
+  message: string;
+  credentials?: QrConnectCredentials[];
+}
+
+// ── 挂起的登录会话 ──
+
+interface PendingSession {
+  /** 等待扫码结果的 Promise（onSuccess resolve, onFailure reject） */
+  credentialsPromise: Promise<QrConnectCredentials[]>;
+  /** 取消当前流程 */
+  dispose: () => void;
+}
+
+const pendingSessions = new Map<string, PendingSession>();
+
+// ── 启动 QR 登录 ──
+
+export function startQrLogin(accountId?: string, source = 'openclaw'): Promise<QrLoginStartResult> {
+  const key = accountId ?? 'default';
+
+  // 清理旧会话
+  pendingSessions.get(key)?.dispose();
+  pendingSessions.delete(key);
+
+  return new Promise((resolve) => {
+    let credentialsResolve: (creds: QrConnectCredentials[]) => void;
+    let credentialsReject: (err: Error) => void;
+
+    // 凭据 Promise — 在 onSuccess/onFailure 中 settle
+    const credentialsPromise = new Promise<QrConnectCredentials[]>((res, rej) => {
+      credentialsResolve = res;
+      credentialsReject = rej;
+    });
+
+    const dispose = startQrConnect(
+      {
+        onQrDisplayed(url) {
+          resolve({
+            qrDataUrl: url,
+            message: '请使用手机 QQ 扫描二维码完成绑定',
+          });
+        },
+        onSuccess: (creds) => credentialsResolve!(creds),
+        onFailure: (err) => credentialsReject!(err),
+      },
+      { displayQrCodeToConsole: true, source },
+    );
+
+    pendingSessions.set(key, { dispose, credentialsPromise });
+  });
+}
+
+// ── 等待扫码结果 ──
+
+export async function waitQrLogin(accountId?: string): Promise<QrLoginWaitResult> {
+  const key = accountId ?? 'default';
+  const session = pendingSessions.get(key);
+
+  if (!session) {
+    return { connected: false, message: '没有正在进行的登录会话，请先运行 login 命令。' };
+  }
+
+  try {
+    const credentials = await session.credentialsPromise;
+    pendingSessions.delete(key);
+
+    if (credentials.length === 0) {
+      return { connected: false, message: '未获取到 QQ Bot 凭据。' };
+    }
+
+    return {
+      connected: true,
+      message: `绑定成功！AppID: ${credentials.map((c) => c.appId).join(', ')}`,
+      credentials,
+    };
+  } catch (err) {
+    pendingSessions.delete(key);
+    return {
+      connected: false,
+      message: `绑定失败: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+}
+
+// ── 主动取消 ──
+
+export function cancelQrLogin(accountId?: string): void {
+  const key = accountId ?? 'default';
+  pendingSessions.get(key)?.dispose();
+  pendingSessions.delete(key);
+}
+
+// ── 解析 channelInput (appId:clientSecret) ──
+
+export function parseChannelInput(channelInput?: string | null): { appId: string; clientSecret: string } | null {
+  if (!channelInput) return null;
+  const parts = channelInput.trim().split(':');
+  if (parts.length === 2 && parts[0] && parts[1]) {
+    return { appId: parts[0], clientSecret: parts[1] };
+  }
+  return null;
+}
+
+// ── auth.login 入口 ──
+
+export interface QqbotLoginParams {
+  cfg: Record<string, unknown>;
+  accountId?: string | null;
+  channelInput?: string | null;
+  verbose?: boolean;
+  /** 框架注入的 runtime（含 config 持久化 API） */
+  [key: string]: unknown;
+}
+
+/**
+ * auth.login 完整实现。
+ *
+ * 账号策略：
+ *   --account <id>  → 写入指定账户
+ *   channelInput     → 用 appId 作为账户键
+ *   QR 扫码         → 用扫码返回的 appId 作为新账户键
+ */
+export async function qqbotLogin({
+  cfg,
+  accountId,
+  channelInput,
+  verbose,
+  ...rest
+}: QqbotLoginParams): Promise<void> {
+  // 延迟导入，避免循环依赖
+  const { applyQQBotAccountConfig } = await import('../config.js');
+  const { persistAuthConfig } = await import('../adapter/resolve.js');
+  const { applyAccountDefaults } = await import('./finalize.js');
+  const { resolveAccountKey } = await import('./account-key.js');
+
+  const runtime: Record<string, unknown> = rest as any;
+  const resolvedId = accountId ? accountId.trim().toLowerCase() : null;
+
+  // 如果传了 appId:clientSecret，直接写入配置
+  const parsed = parseChannelInput(channelInput);
+  if (parsed) {
+    const key = resolveAccountKey(cfg as any, parsed.appId, resolvedId);
+    const result = applyQQBotAccountConfig(cfg as any, key, {
+      appId: parsed.appId,
+      clientSecret: parsed.clientSecret,
+    });
+    Object.assign(cfg, result);
+    // 对齐 setup：写入默认 streaming/dmPolicy
+    const withDefaults = applyAccountDefaults(cfg as any, key);
+    Object.assign(cfg, withDefaults);
+    await persistAuthConfig(runtime, cfg, 'restart');
+    if (verbose) console.log(`QQ Bot 已配置 (${key}) AppID: ${parsed.appId}`);
+    return;
+  }
+
+  // QR 扫码登录
+  const { qrDataUrl, message } = await startQrLogin(resolvedId || 'pending');
+  console.log(`\n${message}`);
+  if (qrDataUrl) console.log(`QR 链接: ${qrDataUrl}`);
+
+  const result = await waitQrLogin(resolvedId || 'pending');
+  if (!result.connected || !result.credentials) {
+    throw new Error(result.message);
+  }
+
+  for (const cred of result.credentials) {
+    const key = resolveAccountKey(cfg as any, cred.appId, resolvedId);
+    const next = applyQQBotAccountConfig(cfg as any, key, {
+      appId: cred.appId,
+      clientSecret: cred.appSecret,
+    });
+    Object.assign(cfg, next);
+    // 对齐 setup：写入默认 streaming/dmPolicy，扫码用户加入白名单
+    const withDefaults = applyAccountDefaults(cfg as any, key, cred.userOpenid);
+    Object.assign(cfg, withDefaults);
+  }
+  await persistAuthConfig(runtime, cfg, 'restart');
+  console.log(`QQ Bot 登录成功！`);
+}

package/src/setup/surface.ts

@@ -3,7 +3,7 @@
  */
 import type { ChannelSetupWizard } from '../adapter/setup.js';
 import { createStandardChannelSetupStatus, setSetupChannelEnabled } from '../adapter/setup.js';
-import { listQQBotAccountIds, resolveQQBotAccount } from '../config.js';
+import { listQQBotAccountIds, resolveQQBotAccount, resolveDefaultQQBotAccountId } from '../config.js';
 import { finalizeQQBotSetup } from './finalize.js';
 
 const CHANNEL = 'qqbot' as const;
@@ -24,6 +24,14 @@ export const qqbotSetupWizard: ChannelSetupWizard = {
         return Boolean(account.appId && account.clientSecret);
       }),
   }),
+  // 未配置时默认使用 default 账号，有账户时框架会提示选择
+  resolveAccountIdForConfigure: async ({ cfg, shouldPromptAccountIds, accountOverride, defaultAccountId }) => {
+    if (accountOverride) return accountOverride;
+    const ids = listQQBotAccountIds(cfg as any);
+    if (ids.length === 0) return 'default';
+    if (!shouldPromptAccountIds) return ids[0];
+    return defaultAccountId || resolveDefaultQQBotAccountId(cfg as any);
+  },
   credentials: [],
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   finalize: (async ({ cfg, accountId, prompter, runtime }: any) =>