@lumachat/lumachat 0.15.2 → 0.15.4

package/README.md

@@ -1,60 +1,52 @@
-# LumaChat OpenClaw 通道
+# LumaChat OpenClaw 通道插件
 
-该目录包含 LumaChat 的 OpenClaw 通道插件实现。
+该插件用于将 OpenClaw 接入 LumaChat App，当前配对方式为 **OAuth 2.0 Device Flow**（授权码 + 扫码）。
 
-## 已实现功能
-- 完整配对流程（请求配对码+安全码、轮询状态、保存 token 到 `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.0
+## 配对流程（OAuth 设备授权）
+
+1. 在 Clawdbot 机器执行：
+
+```bash
+openclaw channels login --channel lumachat
 ```
 
-## 更新
-### 0.1.2
-- 修复 WebSocket 消息处理时 `cfg` 未定义导致网关崩溃的问题。
+2. 终端会输出：
+   - 二维码（可直接扫码）
+   - 6 位授权码（`user_code`，可手动输入）
 
-### 0.1.3
-- 默认后端地址切换为 `https://api-love2.huaizuo2029.cn`（仍可通过配置覆盖）。
+3. 在 LumaChat App 中进入：`设置 -> Clawdbot 配对`
+   - 可扫码授权
+   - 或手动输入 6 位授权码
 
-### 0.1.4
-- 修复配对等待在部分时区立即超时的问题（将过期时间按 UTC 解析）。
+4. 授权成功后，插件会自动保存 `channelToken` 并建立连接。
 
-### 0.15.0
-- 插件对外品牌升级为 LumaChat（npm 包名改为 `@lumachat/lumachat`）。
-- 支持返回并展示 6 位安全码（pairing confirm code），与 App 双码配对流程保持一致。
-- 补齐 clawdchat 消息目标解析（`chat:<uuid>` / `clawdchat:<uuid>`），避免 `Unknown target` 导致回复丢失。
+## 常见问题
 
-升级：
-```
-openclaw plugins install @lumachat/lumachat@0.15.0
-```
+- 提示 `授权码已过期`：重新执行 `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 并自动连接后端。
+## 可选环境变量
 
-## 可选配置
-- `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

@@ -1,9 +1,10 @@
 {
-  "id": "clawdchat",
+  "id": "lumachat",
   "name": "LumaChat Channel",
   "description": "LumaChat mobile channel for OpenClaw",
-  "version": "0.15.2",
+  "version": "0.15.4",
   "channels": [
+    "lumachat",
     "clawdchat"
   ],
   "configSchema": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumachat/lumachat",
-  "version": "0.15.2",
+  "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": {
@@ -21,14 +22,14 @@
       "./src/index.ts"
     ],
     "channel": {
-      "id": "clawdchat",
+      "id": "lumachat",
       "label": "LumaChat",
-      "selectionLabel": "LumaChat (配对码)",
-      "docsPath": "/channels/clawdchat",
-      "blurb": "通过配对码把 Clawdbot 接入 LumaChat。",
+      "selectionLabel": "LumaChat (授权码/扫码)",
+      "docsPath": "/channels/lumachat",
+      "blurb": "通过 OAuth 授权码或扫码把 Clawdbot 接入 LumaChat。",
       "aliases": [
-        "clawdchat",
-        "lumachat"
+        "lumachat",
+        "clawdchat"
       ]
     },
     "install": {

package/src/index.ts

@@ -1,4 +1,5 @@
 import { randomUUID } from "node:crypto";
+import QRCode from "qrcode";
 import WebSocket from "ws";
 import {
   createReplyPrefixContext,
@@ -15,13 +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 = {
@@ -47,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;
@@ -83,15 +100,18 @@ const normalizeValue = (value?: string | null): string | undefined => {
 };
 
 const resolveClawdchatSection = (cfg: OpenClawConfig): ClawdchatConfigSection =>
-  (cfg.channels?.clawdchat ?? {}) as ClawdchatConfigSection;
+  (cfg.channels?.lumachat ?? cfg.channels?.clawdchat ?? {}) as ClawdchatConfigSection;
 
 const resolveBaseUrl = (cfg: OpenClawConfig): string =>
   normalizeValue(resolveClawdchatSection(cfg).baseUrl) ??
+  normalizeValue(process.env.LUMACHAT_API_BASE_URL) ??
   normalizeValue(process.env.CLAWDCHAT_API_BASE_URL) ??
   DEFAULT_BASE_URL;
 
 const resolveSharedKey = (cfg: OpenClawConfig): string | undefined =>
   normalizeValue(resolveClawdchatSection(cfg).sharedKey) ??
+  normalizeValue(process.env.LUMACHAT_CHANNEL_KEY) ??
+  normalizeValue(process.env.LUMACHAT_SHARED_KEY) ??
   normalizeValue(process.env.CLAWDCHAT_CHANNEL_KEY) ??
   normalizeValue(process.env.CLAWDCHAT_SHARED_KEY);
 
@@ -101,7 +121,7 @@ const buildConfigPatch = (cfg: OpenClawConfig, patch: Partial<ClawdchatConfigSec
     ...cfg,
     channels: {
       ...cfg.channels,
-      clawdchat: {
+      lumachat: {
         ...current,
         ...patch,
       },
@@ -111,14 +131,17 @@ const buildConfigPatch = (cfg: OpenClawConfig, patch: Partial<ClawdchatConfigSec
 
 const removeClawdchatFields = (cfg: OpenClawConfig, fields: Array<keyof ClawdchatConfigSection>) => {
   const current = { ...resolveClawdchatSection(cfg) } as Record<string, unknown>;
+  const legacy = { ...(cfg.channels?.clawdchat ?? {}) } as Record<string, unknown>;
   for (const field of fields) {
     delete current[field as string];
+    delete legacy[field as string];
   }
   return {
     ...cfg,
     channels: {
       ...cfg.channels,
-      clawdchat: current,
+      lumachat: current,
+      clawdchat: legacy,
     },
   } as OpenClawConfig;
 };
@@ -191,20 +214,39 @@ 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> => {
   const resolveAccount = (cfg: OpenClawConfig, accountId?: string | null): ResolvedClawdchatAccount => {
     const section = resolveClawdchatSection(cfg);
     const resolvedId = accountId ?? DEFAULT_ACCOUNT_ID;
-    const name = section.name?.trim() || "Clawdchat";
+    const name = section.name?.trim() || "LumaChat";
     return {
       accountId: resolvedId,
       name,
@@ -229,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,
     };
   };
 
@@ -299,18 +499,18 @@ const createClawdchatPlugin = (api: OpenClawPluginApi): ChannelPlugin<ResolvedCl
     };
 
     if (!requestId || !conversationId || !content) {
-      await respondError("invalid_message", "Invalid clawdchat payload.");
+      await respondError("invalid_message", "Invalid lumachat payload.");
       return;
     }
 
     const timestampMs = payload.timestamp ? Date.parse(payload.timestamp) : Date.now();
     const route = api.runtime.channel.routing.resolveAgentRoute({
       cfg,
-      channel: "clawdchat",
+      channel: CHANNEL_ID,
       peer: { kind: "dm", id: conversationId },
     });
 
-    const senderLabel = `clawdchat:${conversationId}`;
+    const senderLabel = `${CHANNEL_ID}:${conversationId}`;
     const storePath = api.runtime.channel.session.resolveStorePath(cfg.session?.store, {
       agentId: route.agentId,
     });
@@ -320,7 +520,7 @@ const createClawdchatPlugin = (api: OpenClawPluginApi): ChannelPlugin<ResolvedCl
     });
     const envelopeOptions = api.runtime.channel.reply.resolveEnvelopeFormatOptions(cfg);
     const body = api.runtime.channel.reply.formatAgentEnvelope({
-      channel: "Clawdchat",
+      channel: "LumaChat",
       from: senderLabel,
       timestamp: timestampMs,
       previousTimestamp,
@@ -340,13 +540,13 @@ const createClawdchatPlugin = (api: OpenClawPluginApi): ChannelPlugin<ResolvedCl
       ConversationLabel: senderLabel,
       SenderName: senderLabel,
       SenderId: conversationId,
-      Provider: "clawdchat" as const,
-      Surface: "clawdchat" as const,
+      Provider: CHANNEL_ID as const,
+      Surface: CHANNEL_ID as const,
       MessageSid: requestId,
       Timestamp: timestampMs,
       CommandAuthorized: true,
       CommandSource: "text" as const,
-      OriginatingChannel: "clawdchat" as const,
+      OriginatingChannel: CHANNEL_ID as const,
       OriginatingTo: `chat:${conversationId}`,
     });
 
@@ -394,7 +594,7 @@ const createClawdchatPlugin = (api: OpenClawPluginApi): ChannelPlugin<ResolvedCl
           }
         },
         onError: (err) => {
-          log?.warn?.(`clawdchat reply error: ${String(err)}`);
+          log?.warn?.(`lumachat reply error: ${String(err)}`);
         },
       });
 
@@ -420,7 +620,7 @@ const createClawdchatPlugin = (api: OpenClawPluginApi): ChannelPlugin<ResolvedCl
         }
       }
     } catch (err) {
-      log?.error?.(`clawdchat dispatch failed: ${String(err)}`);
+      log?.error?.(`lumachat dispatch failed: ${String(err)}`);
       await respondError("assistant_unavailable", "Assistant unavailable.");
     }
   };
@@ -466,7 +666,7 @@ const createClawdchatPlugin = (api: OpenClawPluginApi): ChannelPlugin<ResolvedCl
         heartbeat = setInterval(() => {
           sendJson(socket, { type: "heartbeat" }).catch(() => undefined);
         }, HEARTBEAT_INTERVAL_MS);
-        log?.info?.("clawdchat channel connected");
+        log?.info?.("lumachat channel connected");
       });
 
       socket.on("message", (data) => {
@@ -475,7 +675,7 @@ const createClawdchatPlugin = (api: OpenClawPluginApi): ChannelPlugin<ResolvedCl
         try {
           payload = JSON.parse(text) as InboundPayload;
         } catch (err) {
-          log?.warn?.(`clawdchat payload parse error: ${String(err)}`);
+          log?.warn?.(`lumachat payload parse error: ${String(err)}`);
           return;
         }
         if (payload.type === "heartbeat") {
@@ -495,7 +695,7 @@ const createClawdchatPlugin = (api: OpenClawPluginApi): ChannelPlugin<ResolvedCl
       });
 
       socket.on("error", (err) => {
-        log?.warn?.(`clawdchat socket error: ${String(err)}`);
+        log?.warn?.(`lumachat socket error: ${String(err)}`);
       });
 
       socket.on("close", (code, reason) => {
@@ -503,7 +703,7 @@ const createClawdchatPlugin = (api: OpenClawPluginApi): ChannelPlugin<ResolvedCl
         signal.removeEventListener("abort", abortHandler);
         update({ running: false, lastStopAt: new Date().toISOString() });
         const reasonText = reason?.toString?.() ?? "";
-        log?.warn?.(`clawdchat channel closed (${code}) ${reasonText}`);
+        log?.warn?.(`lumachat channel closed (${code}) ${reasonText}`);
         resolve();
       });
 
@@ -557,14 +757,14 @@ const createClawdchatPlugin = (api: OpenClawPluginApi): ChannelPlugin<ResolvedCl
   };
 
   return {
-    id: "clawdchat",
+    id: CHANNEL_ID,
     meta: {
-      id: "clawdchat",
-      label: "Clawdchat",
-      selectionLabel: "Clawdchat (pair code)",
-      docsPath: "/channels/clawdchat",
-      blurb: "Pair Clawdchat with a 6-digit code.",
-      aliases: ["clawdchat"],
+      id: CHANNEL_ID,
+      label: "LumaChat",
+      selectionLabel: "LumaChat (pair code)",
+      docsPath: "/channels/lumachat",
+      blurb: "Pair LumaChat with a 6-digit code.",
+      aliases: [CHANNEL_ID, LEGACY_CHANNEL_ID],
     },
     capabilities: {
       chatTypes: ["direct"],
@@ -580,7 +780,10 @@ const createClawdchatPlugin = (api: OpenClawPluginApi): ChannelPlugin<ResolvedCl
         if (!trimmed) return undefined;
         const lower = trimmed.toLowerCase();
         if (lower.startsWith("chat:")) return trimmed;
-        if (lower.startsWith("clawdchat:")) return `chat:${trimmed.slice("clawdchat:".length)}`;
+        if (lower.startsWith(`${CHANNEL_ID}:`)) return `chat:${trimmed.slice(`${CHANNEL_ID}:`.length)}`;
+        if (lower.startsWith(`${LEGACY_CHANNEL_ID}:`)) {
+          return `chat:${trimmed.slice(`${LEGACY_CHANNEL_ID}:`.length)}`;
+        }
         if (UUID_REGEX.test(trimmed)) return `chat:${trimmed}`;
         return undefined;
       },
@@ -588,13 +791,20 @@ const createClawdchatPlugin = (api: OpenClawPluginApi): ChannelPlugin<ResolvedCl
         looksLikeId: (raw, normalized) => {
           const lower = raw.trim().toLowerCase();
           if (!lower) return false;
-          if (lower.startsWith("chat:") || lower.startsWith("clawdchat:")) return true;
+          if (
+            lower.startsWith("chat:") ||
+            lower.startsWith(`${CHANNEL_ID}:`) ||
+            lower.startsWith(`${LEGACY_CHANNEL_ID}:`)
+          ) {
+            return true;
+          }
           if (UUID_REGEX.test(lower)) return true;
           return Boolean(normalized && normalized.toLowerCase().startsWith("chat:"));
         },
-        hint: "使用 clawdchat 会话 ID（形如 chat:<uuid>）。",
+        hint: "使用 lumachat 会话 ID（形如 chat:<uuid>）。",
       },
-      formatTargetDisplay: ({ target }) => target.replace(/^chat:/i, "").replace(/^clawdchat:/i, ""),
+      formatTargetDisplay: ({ target }) =>
+        target.replace(/^chat:/i, "").replace(/^lumachat:/i, "").replace(/^clawdchat:/i, ""),
     },
     config: {
       listAccountIds: () => [DEFAULT_ACCOUNT_ID],
@@ -616,7 +826,7 @@ const createClawdchatPlugin = (api: OpenClawPluginApi): ChannelPlugin<ResolvedCl
     outbound: {
       deliveryMode: "direct",
       sendText: async () => {
-        throw new Error("Clawdchat outbound is only supported for inbound replies.");
+        throw new Error("LumaChat outbound is only supported for inbound replies.");
       },
     },
     status: {
@@ -632,10 +842,10 @@ const createClawdchatPlugin = (api: OpenClawPluginApi): ChannelPlugin<ResolvedCl
         for (const account of accounts) {
           if (!account.configured) {
             issues.push({
-              channel: "clawdchat",
+              channel: CHANNEL_ID,
               accountId: account.accountId ?? DEFAULT_ACCOUNT_ID,
               kind: "config",
-              message: "Clawdchat channel not paired",
+              message: "LumaChat channel not paired",
             });
           }
         }
@@ -673,60 +883,52 @@ const createClawdchatPlugin = (api: OpenClawPluginApi): ChannelPlugin<ResolvedCl
         const cfg = api.runtime.config.loadConfig();
         const account = resolveAccount(cfg, resolvedId);
         if (account.channelToken && !force) {
-          return { message: "Clawdchat already paired." };
+          return { message: "LumaChat already paired." };
         }
         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: "Clawdchat 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;
@@ -744,62 +946,59 @@ const createClawdchatPlugin = (api: OpenClawPluginApi): ChannelPlugin<ResolvedCl
         const warn = runtime.error ?? console.warn;
 
         if (account.channelToken) {
-          log("Clawdchat 已配对。若需重新配对，请先执行 `openclaw channels logout --channel clawdchat`。");
+          log("LumaChat 已配对。若需重新配对，请先执行 `openclaw channels logout --channel lumachat`。");
           return;
         }
 
         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(`Clawdchat 配对码：${pairing.pairingCode}`);
-        log(`Clawdchat 安全码：${pairing.pairingConfirmCode}`);
-        log("请在 clawdchat 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);
-            log("Clawdchat 配对成功。");
+        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 中输入配对码后重试。");
       },
     },
   };