@lumachat/lumachat 0.15.3 → 0.15.4

package/README.md

@@ -1,70 +1,52 @@
-# LumaChat OpenClaw 通道
+# LumaChat OpenClaw 通道插件
 
-该目录包含 LumaChat 的 OpenClaw 通道插件实现。
+该插件用于将 OpenClaw 接入 LumaChat App，当前配对方式为 **OAuth 2.0 Device Flow**（授权码 + 扫码）。
 
-## 已实现功能
-- 完整配对流程（请求配对码+安全码、轮询状态、保存 token 到 `channels.lumachat`，兼容读取 `channels.clawdchat`）。
-- 与 LumaChat 后端保持 WebSocket 长连接。
-- 入站消息接入（LumaChat -> OpenClaw），按 `request_id` 回传回复。
-- CLI 配对入口（`openclaw channels login --channel lumachat`）。
+## 版本与安装
 
-## 安装
-先确认 Node.js 版本满足 `>=22.12.0`（`openclaw` npm 包要求）：
-```
-node -v
-```
+当前版本：`0.15.4`
 
-如需启用 pnpm（推荐）：
-```
-corepack enable
-corepack prepare pnpm@latest --activate
+```bash
+pnpm openclaw plugins install @lumachat/lumachat@0.15.4
+# 或升级
+pnpm openclaw plugins update lumachat
+openclaw gateway restart
 ```
 
-安装插件：
-```
-openclaw plugins install @lumachat/lumachat@0.15.2
-```
+## 配对流程（OAuth 设备授权）
 
-## 更新
-### 0.1.2
-- 修复 WebSocket 消息处理时 `cfg` 未定义导致网关崩溃的问题。
+1. 在 Clawdbot 机器执行：
 
-### 0.1.3
-- 默认后端地址切换为 `https://api-love2.huaizuo2029.cn`（仍可通过配置覆盖）。
+```bash
+openclaw channels login --channel lumachat
+```
 
-### 0.1.4
-- 修复配对等待在部分时区立即超时的问题（将过期时间按 UTC 解析）。
+2. 终端会输出：
+   - 二维码（可直接扫码）
+   - 6 位授权码（`user_code`，可手动输入）
 
-### 0.15.0
-- 插件对外品牌升级为 LumaChat（npm 包名改为 `@lumachat/lumachat`）。
-- 支持返回并展示 6 位安全码（pairing confirm code），与 App 双码配对流程保持一致。
-- 补齐 clawdchat 消息目标解析（`chat:<uuid>` / `clawdchat:<uuid>`），避免 `Unknown target` 导致回复丢失。
+3. 在 LumaChat App 中进入：`设置 -> Clawdbot 配对`
+   - 可扫码授权
+   - 或手动输入 6 位授权码
 
-### 0.15.1
-- 修复 `openclaw plugins install @lumachat/lumachat` 后配置校验 `plugin not found: lumachat` 的问题。
-- 插件 ID 迁移为 `lumachat`，并保持对旧 ID `clawdchat` 的兼容读取。
-- 若本地历史配置里存在 `plugins.entries.clawdchat`，请删除该键并改为 `plugins.entries.lumachat`。
+4. 授权成功后，插件会自动保存 `channelToken` 并建立连接。
 
-### 0.15.2
-- 发布 `@lumachat/lumachat@0.15.2`，作为当前稳定安装版本。
+## 常见问题
 
-升级：
-```
-openclaw plugins install @lumachat/lumachat@0.15.2
-```
+- 提示 `授权码已过期`：重新执行 `openclaw channels login --channel lumachat`
+- 提示 `OAuth client_id 无效`：升级插件和后端到最新版本
+- 一直等待授权：确认 App 已登录并在配对页完成授权
 
-## 配对流程（当前）
-1. 在 Clawdbot 机器上执行：`openclaw channels login --channel lumachat`。
-2. 终端会显示 6 位配对码和 6 位安全码。
-3. 在 LumaChat App 中：设置 -> Clawdbot 配对，先登录账号，再输入配对码和安全码。
-4. 插件会保存通道 token 并自动连接后端。
+## 可选环境变量
 
-## 可选配置
-- `LUMACHAT_API_BASE_URL`：覆盖后端地址（默认：`https://api-love2.huaizuo2029.cn`；本地开发可设为 `http://127.0.0.1:8000`）。
-- `LUMACHAT_CHANNEL_KEY` / `LUMACHAT_SHARED_KEY`：当后端要求 `X-Clawdchat-Channel-Key` 时使用。
-- `CLAWDCHAT_API_BASE_URL`：覆盖后端地址（默认：`https://api-love2.huaizuo2029.cn`；本地开发可设为 `http://127.0.0.1:8000`）。
-- `CLAWDCHAT_CHANNEL_KEY` / `CLAWDCHAT_SHARED_KEY`：当后端要求 `X-Clawdchat-Channel-Key` 时使用。
+- `LUMACHAT_API_BASE_URL`：后端地址（默认 `https://api-love2.huaizuo2029.cn`）
+- `LUMACHAT_CHANNEL_KEY` / `LUMACHAT_SHARED_KEY`：后端要求 `X-Clawdchat-Channel-Key` 时使用
+- `CLAWDCHAT_API_BASE_URL`：同上（兼容旧变量）
+- `CLAWDCHAT_CHANNEL_KEY` / `CLAWDCHAT_SHARED_KEY`：同上（兼容旧变量）
 
 ## 备注
-- 配对 API 位于 `/channel/clawdchat/*`。
-- 插件使用返回的 token 连接 `/ws/channel/clawdchat`。
+
+- 插件 OAuth 相关接口：
+  - `POST /oauth/device/code`
+  - `POST /oauth/token`
+- WebSocket 连接地址：`/ws/channel/clawdchat`

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "lumachat",
   "name": "LumaChat Channel",
   "description": "LumaChat mobile channel for OpenClaw",
-  "version": "0.15.3",
+  "version": "0.15.4",
   "channels": [
     "lumachat",
     "clawdchat"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumachat/lumachat",
-  "version": "0.15.3",
+  "version": "0.15.4",
   "description": "LumaChat channel plugin for OpenClaw",
   "type": "module",
   "license": "Apache-2.0",
@@ -14,6 +14,7 @@
     "package.json"
   ],
   "dependencies": {
+    "qrcode": "^1.5.4",
     "ws": "^8.18.0"
   },
   "openclaw": {
@@ -23,9 +24,9 @@
     "channel": {
       "id": "lumachat",
       "label": "LumaChat",
-      "selectionLabel": "LumaChat (配对码)",
+      "selectionLabel": "LumaChat (授权码/扫码)",
       "docsPath": "/channels/lumachat",
-      "blurb": "通过配对码把 Clawdbot 接入 LumaChat。",
+      "blurb": "通过 OAuth 授权码或扫码把 Clawdbot 接入 LumaChat。",
       "aliases": [
         "lumachat",
         "clawdchat"

package/src/index.ts

@@ -1,4 +1,5 @@
 import { randomUUID } from "node:crypto";
+import QRCode from "qrcode";
 import WebSocket from "ws";
 import {
   createReplyPrefixContext,
@@ -15,15 +16,19 @@ const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-
 const HEARTBEAT_INTERVAL_MS = 25_000;
 const RECONNECT_BASE_MS = 2_000;
 const RECONNECT_MAX_MS = 20_000;
-const PAIRING_POLL_INTERVAL_MS = 2_000;
 const PAIRING_WAIT_TIMEOUT_MS = 10 * 60 * 1000;
+const DEVICE_AUTH_POLL_DEFAULT_INTERVAL_SECONDS = 5;
+const DEVICE_AUTH_POLL_MIN_INTERVAL_MS = 1_000;
+const DEVICE_AUTH_SLOW_DOWN_ADD_MS = 2_000;
+const OAUTH_DEVICE_CLIENT_ID = "clawdchat-gateway";
+const OAUTH_DEVICE_SCOPE = "channel:bind";
+const OAUTH_DEVICE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code";
 const CHANNEL_ID = "lumachat";
 const LEGACY_CHANNEL_ID = "clawdchat";
 
 const HEADER_CHANNEL_KEY = "X-Clawdchat-Channel-Key";
-const HEADER_PAIRING_SECRET = "X-Pairing-Secret";
 
-const pairingSessions = new Map<string, PairingSession>();
+const deviceAuthSessions = new Map<string, DeviceAuthSession>();
 const stopControllers = new Map<string, AbortController>();
 
 type ClawdchatConfigSection = {
@@ -49,25 +54,35 @@ type ResolvedClawdchatAccount = {
   pairedAt?: string;
 };
 
-type PairingSession = {
+type DeviceAuthSession = {
   accountId: string;
   baseUrl: string;
   sharedKey?: string;
   gatewayId: string;
-  pairingId: string;
-  pairingSecret: string;
-  pairingCode: string;
-  pairingConfirmCode: string;
+  deviceCode: string;
+  userCode: string;
+  verificationUri: string;
+  verificationUriComplete: string;
+  pollIntervalSeconds: number;
   expiresAt?: string;
 };
 
-type PairingStatus = {
-  status: "pending" | "confirmed" | "expired";
+type DeviceTokenSuccess = {
+  status: "ok";
   channelToken?: string;
   bindingId?: string;
-  expiresAt?: string;
 };
 
+type DeviceTokenError = {
+  status: "error";
+  error: string;
+  errorDescription?: string;
+  statusCode: number;
+  rawBody?: string;
+};
+
+type DeviceTokenPollResult = DeviceTokenSuccess | DeviceTokenError;
+
 type InboundPayload = {
   type?: string;
   request_id?: string;
@@ -199,13 +214,32 @@ const parseUtcTimestamp = (value: string | undefined) => {
   return Number.isFinite(ms) ? ms : null;
 };
 
+const parseJsonObject = (raw: string): Record<string, unknown> => {
+  if (!raw.trim()) {
+    return {};
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed as Record<string, unknown>;
+    }
+  } catch {
+    // ignore
+  }
+  return {};
+};
+
 const fetchJson = async (url: string, options: RequestInit) => {
   const response = await fetch(url, options);
+  const text = await response.text();
+  const payload = parseJsonObject(text);
   if (!response.ok) {
-    const text = await response.text();
-    throw new Error(`Request failed (${response.status}): ${text}`);
+    const detail = typeof payload.detail === "string" && payload.detail.trim()
+      ? payload.detail.trim()
+      : text.trim();
+    throw new Error(`Request failed (${response.status}): ${detail || "Unknown error"}`);
   }
-  return (await response.json()) as Record<string, unknown>;
+  return payload;
 };
 
 const createClawdchatPlugin = (api: OpenClawPluginApi): ChannelPlugin<ResolvedClawdchatAccount> => {
@@ -237,38 +271,196 @@ const createClawdchatPlugin = (api: OpenClawPluginApi): ChannelPlugin<ResolvedCl
     return { cfg: nextCfg, gatewayId };
   };
 
-  const requestPairing = async (baseUrl: string, sharedKey: string | undefined, gatewayId: string) => {
+  const buildVerificationUriComplete = (verificationUri: string, userCode: string, existing?: string) => {
+    if (existing?.trim()) {
+      return existing.trim();
+    }
+    try {
+      const url = new URL(verificationUri);
+      url.searchParams.set("user_code", userCode);
+      return url.toString();
+    } catch {
+      const joiner = verificationUri.includes("?") ? "&" : "?";
+      return `${verificationUri}${joiner}user_code=${encodeURIComponent(userCode)}`;
+    }
+  };
+
+  const normalizePollIntervalSeconds = (value: unknown): number => {
+    if (typeof value === "number" && Number.isFinite(value) && value > 0) {
+      return Math.max(1, Math.floor(value));
+    }
+    if (typeof value === "string" && value.trim()) {
+      const parsed = Number.parseInt(value.trim(), 10);
+      if (Number.isFinite(parsed) && parsed > 0) {
+        return Math.max(1, parsed);
+      }
+    }
+    return DEVICE_AUTH_POLL_DEFAULT_INTERVAL_SECONDS;
+  };
+
+  const requestDeviceCode = async (baseUrl: string, sharedKey: string | undefined, gatewayId: string) => {
     const headers: Record<string, string> = { "Content-Type": "application/json" };
     if (sharedKey) {
       headers[HEADER_CHANNEL_KEY] = sharedKey;
     }
-    const payload = await fetchJson(`${baseUrl}/channel/clawdchat/pairings`, {
+    const payload = await fetchJson(`${baseUrl}/oauth/device/code`, {
       method: "POST",
       headers,
-      body: JSON.stringify({ gateway_id: gatewayId }),
+      body: JSON.stringify({
+        gateway_id: gatewayId,
+        client_id: OAUTH_DEVICE_CLIENT_ID,
+        scope: OAUTH_DEVICE_SCOPE,
+      }),
     });
+
+    const deviceCode = normalizeValue(typeof payload.device_code === "string" ? payload.device_code : undefined);
+    const userCode = normalizeValue(typeof payload.user_code === "string" ? payload.user_code : undefined);
+    const verificationUri = normalizeValue(
+      typeof payload.verification_uri === "string" ? payload.verification_uri : undefined,
+    );
+    const expiresAt = normalizeValue(typeof payload.expires_at === "string" ? payload.expires_at : undefined);
+    if (!deviceCode || !userCode || !verificationUri) {
+      throw new Error("OAuth device code response is missing required fields.");
+    }
+
+    const verificationUriComplete = buildVerificationUriComplete(
+      verificationUri,
+      userCode,
+      typeof payload.verification_uri_complete === "string" ? payload.verification_uri_complete : undefined,
+    );
+
     return {
-      pairingId: String(payload.pairing_id ?? ""),
-      pairingCode: String(payload.pairing_code ?? ""),
-      pairingConfirmCode: String(payload.pairing_confirm_code ?? ""),
-      pairingSecret: String(payload.pairing_secret ?? ""),
-      expiresAt: payload.expires_at ? String(payload.expires_at) : undefined,
+      deviceCode,
+      userCode,
+      verificationUri,
+      verificationUriComplete,
+      pollIntervalSeconds: normalizePollIntervalSeconds(payload.interval),
+      expiresAt,
     };
   };
 
-  const readPairingStatus = async (session: PairingSession): Promise<PairingStatus> => {
-    const headers: Record<string, string> = {
-      [HEADER_PAIRING_SECRET]: session.pairingSecret,
+  const pollDeviceToken = async (session: DeviceAuthSession): Promise<DeviceTokenPollResult> => {
+    const body = new URLSearchParams({
+      grant_type: OAUTH_DEVICE_GRANT_TYPE,
+      device_code: session.deviceCode,
+      client_id: OAUTH_DEVICE_CLIENT_ID,
+    });
+    const response = await fetch(`${session.baseUrl}/oauth/token`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+      },
+      body,
+    });
+    const rawBody = await response.text();
+    const payload = parseJsonObject(rawBody);
+
+    if (response.ok) {
+      const channelToken = normalizeValue(
+        typeof payload.channel_token === "string"
+          ? payload.channel_token
+          : typeof payload.access_token === "string"
+            ? payload.access_token
+            : undefined,
+      );
+      return {
+        status: "ok",
+        channelToken,
+        bindingId: normalizeValue(typeof payload.binding_id === "string" ? payload.binding_id : undefined),
+      };
+    }
+
+    return {
+      status: "error",
+      error: normalizeValue(typeof payload.error === "string" ? payload.error : undefined) ?? "unknown_error",
+      errorDescription: normalizeValue(
+        typeof payload.error_description === "string" ? payload.error_description : undefined,
+      ),
+      statusCode: response.status,
+      rawBody: rawBody.trim() || undefined,
     };
-    const payload = await fetchJson(
-      `${session.baseUrl}/channel/clawdchat/pairings/${session.pairingId}`,
-      { method: "GET", headers },
-    );
+  };
+
+  const formatTokenError = (result: DeviceTokenError) => {
+    switch (result.error) {
+      case "authorization_pending":
+        return "authorization_pending";
+      case "slow_down":
+        return "slow_down";
+      case "expired_token":
+        return "授权码已过期，请重新执行登录。";
+      case "invalid_client":
+        return "OAuth client_id 无效，请升级插件或检查后端配置。";
+      case "invalid_grant":
+        return "device_code 无效或已失效，请重新执行登录。";
+      default:
+        return result.errorDescription
+          ? `OAuth 授权失败：${result.errorDescription} (${result.error})`
+          : `OAuth 授权失败：${result.error}${result.rawBody ? ` | ${result.rawBody}` : ""}`;
+    }
+  };
+
+  const renderQrDataUrl = async (content: string): Promise<string | undefined> => {
+    try {
+      return await QRCode.toDataURL(content, { margin: 1, width: 360 });
+    } catch {
+      return undefined;
+    }
+  };
+
+  const renderTerminalQr = async (content: string): Promise<string | undefined> => {
+    try {
+      return await QRCode.toString(content, { type: "terminal", small: true });
+    } catch {
+      return undefined;
+    }
+  };
+
+  const waitForDeviceAuthorization = async (
+    session: DeviceAuthSession,
+    deadline: number,
+    onProgress?: (message: string) => void,
+  ) => {
+    let pollIntervalMs = Math.max(DEVICE_AUTH_POLL_MIN_INTERVAL_MS, session.pollIntervalSeconds * 1_000);
+    while (Date.now() < deadline) {
+      const result = await pollDeviceToken(session);
+      if (result.status === "ok") {
+        return result;
+      }
+      const message = formatTokenError(result);
+      if (message === "authorization_pending") {
+        if (onProgress) {
+          onProgress(`等待授权确认中（授权码 ${session.userCode}）...`);
+        }
+      } else if (message === "slow_down") {
+        pollIntervalMs += DEVICE_AUTH_SLOW_DOWN_ADD_MS;
+        if (onProgress) {
+          onProgress(`轮询过快，已调整为 ${Math.round(pollIntervalMs / 1000)} 秒间隔。`);
+        }
+      } else {
+        throw new Error(message);
+      }
+      await sleep(pollIntervalMs);
+    }
+    return null;
+  };
+
+  const persistAuthorizedBinding = async (tokenResult: DeviceTokenSuccess) => {
+    const channelToken = normalizeValue(tokenResult.channelToken);
+    if (!channelToken) {
+      throw new Error("OAuth token 响应缺少 channel_token/access_token。");
+    }
+    const latestCfg = api.runtime.config.loadConfig();
+    const nextCfg = buildConfigPatch(latestCfg, {
+      enabled: true,
+      channelToken,
+      bindingId: tokenResult.bindingId,
+      pairedAt: new Date().toISOString(),
+    });
+    await api.runtime.config.writeConfigFile(nextCfg);
     return {
-      status: (payload.status ?? "pending") as PairingStatus["status"],
-      channelToken: payload.channel_token ? String(payload.channel_token) : undefined,
-      bindingId: payload.binding_id ? String(payload.binding_id) : undefined,
-      expiresAt: payload.expires_at ? String(payload.expires_at) : undefined,
+      channelToken,
+      bindingId: tokenResult.bindingId,
     };
   };
 
@@ -696,55 +888,47 @@ const createClawdchatPlugin = (api: OpenClawPluginApi): ChannelPlugin<ResolvedCl
         const baseUrl = account.baseUrl;
         const sharedKey = account.sharedKey;
         const { gatewayId } = await ensureGatewayId(cfg);
-        const pairing = await requestPairing(baseUrl, sharedKey, gatewayId);
-        if (!pairing.pairingId || !pairing.pairingCode || !pairing.pairingConfirmCode || !pairing.pairingSecret) {
-          throw new Error("Failed to request pairing code.");
-        }
-        const session: PairingSession = {
+        const deviceCode = await requestDeviceCode(baseUrl, sharedKey, gatewayId);
+        const session: DeviceAuthSession = {
           accountId: resolvedId,
           baseUrl,
           sharedKey,
           gatewayId,
-          pairingId: pairing.pairingId,
-          pairingCode: pairing.pairingCode,
-          pairingConfirmCode: pairing.pairingConfirmCode,
-          pairingSecret: pairing.pairingSecret,
-          expiresAt: pairing.expiresAt,
+          deviceCode: deviceCode.deviceCode,
+          userCode: deviceCode.userCode,
+          verificationUri: deviceCode.verificationUri,
+          verificationUriComplete: deviceCode.verificationUriComplete,
+          pollIntervalSeconds: deviceCode.pollIntervalSeconds,
+          expiresAt: deviceCode.expiresAt,
         };
-        pairingSessions.set(resolvedId, session);
-        const expires = pairing.expiresAt ? ` (expires ${pairing.expiresAt})` : "";
+        deviceAuthSessions.set(resolvedId, session);
+        const qrDataUrl = await renderQrDataUrl(session.verificationUriComplete);
+        const expires = session.expiresAt ? ` (expires ${session.expiresAt})` : "";
         return {
-          message: `Pairing code: ${pairing.pairingCode}, confirm code: ${pairing.pairingConfirmCode}${expires}`,
+          qrDataUrl,
+          message: `OAuth user code: ${session.userCode}${expires}`,
         };
       },
       loginWithQrWait: async ({ accountId, timeoutMs }) => {
         const resolvedId = accountId ?? DEFAULT_ACCOUNT_ID;
-        const session = pairingSessions.get(resolvedId);
+        const session = deviceAuthSessions.get(resolvedId);
         if (!session) {
-          return { connected: false, message: "No pairing in progress." };
+          return { connected: false, message: "No OAuth device authorization in progress." };
         }
         const deadline = Date.now() + Math.max(1_000, timeoutMs ?? 60_000);
-        while (Date.now() < deadline) {
-          const status = await readPairingStatus(session);
-          if (status.status === "confirmed" && status.channelToken) {
-            const cfg = api.runtime.config.loadConfig();
-            const nextCfg = buildConfigPatch(cfg, {
-              enabled: true,
-              channelToken: status.channelToken,
-              bindingId: status.bindingId,
-              pairedAt: new Date().toISOString(),
-            });
-            await api.runtime.config.writeConfigFile(nextCfg);
-            pairingSessions.delete(resolvedId);
-            return { connected: true, message: "LumaChat paired." };
-          }
-          if (status.status === "expired") {
-            pairingSessions.delete(resolvedId);
-            return { connected: false, message: "Pairing code expired." };
+        try {
+          const tokenResult = await waitForDeviceAuthorization(session, deadline);
+          if (!tokenResult) {
+            return { connected: false, message: "Waiting for OAuth authorization confirmation." };
           }
-          await sleep(PAIRING_POLL_INTERVAL_MS);
+          await persistAuthorizedBinding(tokenResult);
+          return { connected: true, message: "LumaChat paired." };
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          return { connected: false, message };
+        } finally {
+          deviceAuthSessions.delete(resolvedId);
         }
-        return { connected: false, message: "Waiting for pairing confirmation." };
       },
       logoutAccount: async ({ cfg, accountId }) => {
         const resolvedId = accountId ?? DEFAULT_ACCOUNT_ID;
@@ -769,55 +953,52 @@ const createClawdchatPlugin = (api: OpenClawPluginApi): ChannelPlugin<ResolvedCl
         const baseUrl = account.baseUrl;
         const sharedKey = account.sharedKey;
         const { gatewayId } = await ensureGatewayId(cfg);
-        const pairing = await requestPairing(baseUrl, sharedKey, gatewayId);
-        if (!pairing.pairingId || !pairing.pairingCode || !pairing.pairingConfirmCode || !pairing.pairingSecret) {
-          throw new Error("Failed to request pairing code.");
-        }
-        log(`LumaChat 配对码：${pairing.pairingCode}`);
-        log(`LumaChat 安全码：${pairing.pairingConfirmCode}`);
-        log("请在 LumaChat App -> 设置 -> Clawdbot 配对 中输入配对码与安全码。");
-
-        const session: PairingSession = {
+        const deviceCode = await requestDeviceCode(baseUrl, sharedKey, gatewayId);
+        const session: DeviceAuthSession = {
           accountId: resolvedId,
           baseUrl,
           sharedKey,
           gatewayId,
-          pairingId: pairing.pairingId,
-          pairingCode: pairing.pairingCode,
-          pairingConfirmCode: pairing.pairingConfirmCode,
-          pairingSecret: pairing.pairingSecret,
-          expiresAt: pairing.expiresAt,
+          deviceCode: deviceCode.deviceCode,
+          userCode: deviceCode.userCode,
+          verificationUri: deviceCode.verificationUri,
+          verificationUriComplete: deviceCode.verificationUriComplete,
+          pollIntervalSeconds: deviceCode.pollIntervalSeconds,
+          expiresAt: deviceCode.expiresAt,
         };
+        deviceAuthSessions.set(resolvedId, session);
+
+        const terminalQr = await renderTerminalQr(session.verificationUriComplete);
+        if (terminalQr?.trim()) {
+          log("LumaChat 扫码授权二维码：");
+          log(terminalQr);
+        } else {
+          warn("二维码生成失败，请改用 6 位授权码手动输入。");
+        }
+        log(`LumaChat 授权码：${session.userCode}`);
+        log("请在 LumaChat App -> 设置 -> Clawdbot 配对 中输入授权码，或直接扫码授权。");
+        log(`授权链接：${session.verificationUriComplete}`);
 
-        const expiresAtMs = parseUtcTimestamp(pairing.expiresAt);
+        const expiresAtMs = parseUtcTimestamp(session.expiresAt);
         const deadline = expiresAtMs && Number.isFinite(expiresAtMs)
           ? Math.max(Date.now(), expiresAtMs)
           : Date.now() + PAIRING_WAIT_TIMEOUT_MS;
 
-        while (Date.now() < deadline) {
-          const status = await readPairingStatus(session);
-          if (status.status === "confirmed" && status.channelToken) {
-            const latestCfg = api.runtime.config.loadConfig();
-            const nextCfg = buildConfigPatch(latestCfg, {
-              enabled: true,
-              channelToken: status.channelToken,
-              bindingId: status.bindingId,
-              pairedAt: new Date().toISOString(),
-            });
-            await api.runtime.config.writeConfigFile(nextCfg);
+        try {
+          const tokenResult = await waitForDeviceAuthorization(
+            session,
+            deadline,
+            verbose ? log : undefined,
+          );
+          if (tokenResult) {
+            await persistAuthorizedBinding(tokenResult);
             log("LumaChat 配对成功。");
             return;
           }
-          if (status.status === "expired") {
-            throw new Error("配对码已过期，请重新执行登录。");
-          }
-          if (verbose) {
-            log("等待配对确认中...");
-          }
-          await sleep(PAIRING_POLL_INTERVAL_MS);
+          warn("等待授权超时，请确认已在 App 中完成授权后重试。");
+        } finally {
+          deviceAuthSessions.delete(resolvedId);
         }
-
-        warn("等待配对超时，请确认已在 App 中输入配对码后重试。");
       },
     },
   };