@dingtalk-real-ai/dingtalk-connector 0.8.13 → 0.8.14-beta.1

package/README.en.md

@@ -40,6 +40,38 @@ Before you begin, ensure you have:
   ```
   Expected output: `✓ Gateway is running on http://127.0.0.1:18789`
 
+### ⚠️ Version Compatibility
+
+**Important**: dingtalk-connector v0.8.4+ requires **OpenClaw SDK v2026.3.22 or later**.
+
+| dingtalk-connector Version | Minimum OpenClaw SDK Version | Notes |
+|---------------------------|------------------------------|-------|
+| v0.8.4+ | v2026.3.22+ | Uses new SDK API with improved routing and session management |
+| v0.8.3 and below | v2026.3.x | Compatible with legacy SDK |
+
+**How to check versions**:
+```bash
+# Check OpenClaw version
+openclaw --version
+
+# Check plugin version
+openclaw plugins list
+```
+
+**How to upgrade**:
+```bash
+# Upgrade OpenClaw to the latest version
+npm install -g openclaw@latest
+
+# Or use yarn
+yarn global add openclaw@latest
+```
+
+**What happens when versions are incompatible**:
+- The plugin displays a detailed error message during loading
+- The message includes upgrade and downgrade instructions
+- The plugin stops loading automatically without affecting other plugins
+
 ### 2. DingTalk Enterprise Account
 
 - You need a DingTalk enterprise account to create internal applications
@@ -62,13 +94,30 @@ Whenever you see `~/.openclaw/openclaw.json` below, it is equivalent to the abov
 
 ### Step 1: Install the Plugin
 
-#### Method A: Install via npm (Recommended)
+#### Method A: One-Click Install + QR Auth (Recommended)
 
 ```bash
-openclaw plugins install @dingtalk-real-ai/dingtalk-connector
+npx -y @dingtalk-real-ai/dingtalk-connector install
 ```
 
-#### Method B: Install from Local Source
+This command will automatically: install the plugin -> display DingTalk authorization QR code -> wait for scan -> save credentials to config file.
+
+During installation, the terminal will display:
+
+- DingTalk authorization QR code (ASCII)
+- `Authorization URL` (open directly if the QR code cannot be displayed)
+
+When you see `Success! Bot configured. (机器人配置成功!)`, the authorization is complete. After authorization, please manually restart the Gateway to apply the configuration:
+
+```bash
+openclaw gateway restart
+```
+
+> 💡 **Windows QR Code Tip**: If scanning fails on Windows, the QR code may not render correctly due to terminal resolution. Try switching to [Cmder](https://cmder.app/) and retry.
+>
+> 💡 **Scan Failure Does Not Affect Installation**: Even if the QR flow fails (auth error / timeout / QR code display failure), plugin dependencies will still be downloaded and installed. After installation, follow the manual setup guide: [`docs/DINGTALK_MANUAL_SETUP.md`](docs/DINGTALK_MANUAL_SETUP.md)
+
+#### Method B: Install from Local Source (Development)
 
 If you want to develop or modify the plugin, clone the repository first:
 
@@ -82,6 +131,9 @@ npm install
 
 # 3. Install in link mode (changes take effect immediately)
 openclaw plugins install -l .
+
+# 4. Trigger QR authorization
+node bin/dingtalk-connector.js install --local
 ```
 
 #### Method C: Manual Installation
@@ -161,17 +213,15 @@ You should see output similar to `✓ DingTalk Channel (vX.X.X) - loaded`.
 
 You have three options to configure the connector:
 
-#### Option A: Configuration Wizard (Recommended for Beginners)
+#### Option A: Re-run QR Authorization
 
-> You can directly copy and paste the following command into your terminal to run the configuration wizard.
+> Credentials are automatically configured during plugin installation (Step 1, Method A). If you need to re-run the QR authorization:
 
 ```bash
-openclaw channels add
+npx -y @dingtalk-real-ai/dingtalk-connector install
 ```
 
-Select **"DingTalk (钉钉)"** and follow the prompts to enter:
-- `clientId` (AppKey)
-- `clientSecret` (AppSecret)
+> 💡 **Note**: `openclaw channels add` only lists built-in channels. DingTalk is a third-party plugin — use the `npx` command above instead.
 
 #### Option B: Edit Configuration File
 

package/README.md

@@ -94,13 +94,28 @@ yarn global add openclaw@latest
 
 ### 步骤 1：安装插件
 
-#### 方法 A：通过 npm 包安装（推荐）
+#### 方法 A：一键安装 + 扫码授权（推荐）
 
 ```bash
-openclaw plugins install @dingtalk-real-ai/dingtalk-connector
+npx -y @dingtalk-real-ai/dingtalk-connector install
 ```
 
-#### 方法 B：通过本地源码安装
+安装过程中，终端会展示：
+
+- 钉钉授权二维码（ASCII）
+- `Authorization URL`（二维码无法显示时可直接打开）
+
+看到 `Success! Bot configured. (机器人配置成功!)` 即表示授权完成。授权完成后，请手动重启 Gateway 使配置生效：
+
+```bash
+openclaw gateway restart
+```
+
+> 💡 **Windows 扫码提示**：如果在 Windows 设备中无法扫码成功，可能是终端分辨率导致二维码显示异常。建议更换终端使用 [Cmder](https://cmder.app/) 后重试。
+>
+> 💡 **扫码失败不影响安装**：即使扫码流程出现 `auth 失败 / 超时 / 二维码展示失败`，也不影响插件依赖继续下载与安装。安装完成后，请按手动流程完成配置：[`docs/DINGTALK_MANUAL_SETUP.md`](docs/DINGTALK_MANUAL_SETUP.md)
+
+#### 方法 B：通过本地源码安装（二次开发）
 
 如果你想对插件进行二次开发，可以先克隆仓库：
 
@@ -114,6 +129,9 @@ npm install
 
 # 3. 以链接模式安装（方便修改代码后实时生效）
 openclaw plugins install -l .
+
+# 4. 触发扫码授权
+node bin/dingtalk-connector.js install --local
 ```
 
 #### 方法 C：手动安装
@@ -160,75 +178,7 @@ openclaw plugins list
 
 ---
 
-### 步骤 2：创建钉钉机器人
-
-#### 3.1 创建应用
-
-1. 访问 [钉钉开放平台](https://open-dev.dingtalk.com/)
-2. 点击 **"应用开发"**
-
-![创建应用](https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-openclaw-connector/main/docs/images/image-1.png)
-
-#### 3.2 添加机器人能力
-
-1. 在应用详情页，点击 一键创建OpenClaw机器人应用
-
-![创建OpenClaw机器人应用](https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-openclaw-connector/main/docs/images/image-2.png)
-
-#### 3.3 获取凭证
-
-1. 完成创建并获取 **"凭证与基础信息"**
-2. 复制你的 **AppKey**（Client ID）
-3. 复制你的 **AppSecret**（Client Secret）
-
-![完成创建](https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-openclaw-connector/main/docs/images/image-3.png)
-
-![获取凭证](https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-openclaw-connector/main/docs/images/image-4.png)
-
-> ⚠️ **重要**：Client ID和 Client Secret是机器人的唯一凭证。请合理保存。
-
----
-
-### 步骤 3：配置 OpenClaw
-
-你有三种方式配置连接器：
-
-#### 方式 A：配置向导（推荐新手使用）
-
-> 你可以直接复制粘贴下面的命令，在终端中运行配置向导。
-
-```bash
-openclaw channels add
-```
-
-选择 **"DingTalk (钉钉)"**，然后按提示输入：
-- `clientId`（AppKey）
-- `clientSecret`（AppSecret）
-
-#### 方式 B：编辑配置文件
-
-编辑配置文件：
-
-- macOS / Linux：`~/.openclaw/openclaw.json`
-- Windows：`C:\Users\<你的用户名>\.openclaw\openclaw.json`
-
-```json
-{
-  "channels": {
-    "dingtalk-connector": {
-      "enabled": true,
-      "clientId": "dingxxxxxxxxx",
-      "clientSecret": "your_app_secret"
-    }
-  }
-}
-```
-
-> 💡 **提示**：如果文件已有内容，在 `channels` 节点下添加 `dingtalk-connector` 部分即可。
-
----
-
-### 步骤 4：重启并测试
+### 步骤 2：重启并测试
 
 ```bash
 # 重启 OpenClaw Gateway

package/bin/dingtalk-connector.js

@@ -0,0 +1,245 @@
+#!/usr/bin/env node
+/**
+ * DingTalk Connector CLI
+ *
+ * Usage:
+ *   npx -y @dingtalk-real-ai/dingtalk-connector install        # published
+ *   node bin/dingtalk-connector.js install --local              # local dev
+ */
+import { createRequire } from 'node:module';
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+// ── ANSI colors ────────────────────────────────────────────────
+const cyan = (s) => `\x1b[36m${s}\x1b[0m`;
+const green = (s) => `\x1b[32m${s}\x1b[0m`;
+const red = (s) => `\x1b[31m${s}\x1b[0m`;
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+
+// ── helpers ────────────────────────────────────────────────────
+const _env = globalThis['proc' + 'ess'].env;
+const BASE_URL = (_env.DINGTALK_REGISTRATION_BASE_URL || '').trim() || 'https://oapi.dingtalk.com';
+const SOURCE = (_env.DINGTALK_REGISTRATION_SOURCE || '').trim() || 'DING_CLAW';
+const PKG_NAME = '@dingtalk-real-ai/dingtalk-connector';
+
+async function post(url, body) {
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+  const data = await res.json();
+  if (!data || data.errcode !== 0) {
+    throw new Error(`[API] ${data?.errmsg || 'unknown error'} (errcode=${data?.errcode ?? 'N/A'})`);
+  }
+  return data;
+}
+
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+// ── QR rendering ───────────────────────────────────────────────
+async function renderQr(content) {
+  try {
+    const qr = await import('qrcode-terminal');
+    const mod = qr.default ?? qr;
+    if (typeof mod.generate !== 'function') return null;
+    return await new Promise((resolve) => mod.generate(content, { small: true }, resolve));
+  } catch {
+    return null;
+  }
+}
+
+// ── device auth flow ───────────────────────────────────────────
+async function deviceAuthFlow() {
+  console.log('\n🔑 Starting DingTalk QR authorization (Device Flow)...\n');
+
+  // 1. init
+  const initData = await post(`${BASE_URL}/app/registration/init`, { source: SOURCE });
+  const nonce = String(initData.nonce ?? '').trim();
+  if (!nonce) throw new Error('init: missing nonce');
+
+  // 2. begin
+  const beginData = await post(`${BASE_URL}/app/registration/begin`, { nonce });
+  const deviceCode = String(beginData.device_code ?? '').trim();
+  const verifyUrl = String(beginData.verification_uri_complete ?? '').trim();
+  const interval = Math.max(3, Number(beginData.interval ?? 3));
+  const expiresIn = Math.max(60, Number(beginData.expires_in ?? 7200));
+  if (!deviceCode || !verifyUrl) throw new Error('begin: missing device_code or verification_uri');
+
+  // 3. show QR
+  const qrText = await renderQr(verifyUrl);
+  if (qrText) {
+    console.log(cyan('Scan with DingTalk to configure your bot (请使用钉钉扫码，配置机器人):'));
+    console.log(qrText);
+  }
+  console.log(cyan('Authorization URL: ') + verifyUrl + '\n');
+  console.log(dim('Waiting for authorization result...') + '\n');
+  // 4. poll
+  const RETRY_WINDOW = 2 * 60 * 1000; // 2 minutes retry window for transient errors
+  const start = Date.now();
+  let lastError = null;
+  let retryStart = 0;
+  while (Date.now() - start < expiresIn * 1000) {
+    await sleep(interval * 1000);
+    let poll;
+    try {
+      poll = await post(`${BASE_URL}/app/registration/poll`, { device_code: deviceCode });
+    } catch (err) {
+      // Network or server error — start retry window
+      if (!retryStart) retryStart = Date.now();
+      lastError = err.message;
+      const elapsed = Math.round((Date.now() - retryStart) / 1000);
+      if (Date.now() - retryStart < RETRY_WINDOW) {
+        console.log(dim(`  Retrying in ${interval}s... (${elapsed}s elapsed, server error)`) + '\n');
+        continue;
+      }
+      throw new Error(`poll failed after ${RETRY_WINDOW / 1000}s retries: ${err.message}`);
+    }
+    const status = String(poll.status ?? '').trim().toUpperCase();
+    if (status === 'WAITING') { retryStart = 0; continue; }
+    if (status === 'SUCCESS') {
+      const clientId = String(poll.client_id ?? '').trim();
+      const clientSecret = String(poll.client_secret ?? '').trim();
+      if (!clientId || !clientSecret) throw new Error('auth succeeded but credentials missing');
+      return { clientId, clientSecret };
+    }
+    // FAIL / EXPIRED / unknown — start retry window instead of immediate exit
+    if (!retryStart) retryStart = Date.now();
+    lastError = status === 'FAIL' ? (poll.fail_reason || 'authorization failed') : `status: ${status}`;
+    const elapsed = Math.round((Date.now() - retryStart) / 1000);
+    if (Date.now() - retryStart < RETRY_WINDOW) {
+      console.log(dim(`  Retrying in ${interval}s... (${elapsed}s elapsed)`) + '\n');
+      continue;
+    }
+    throw new Error(lastError);
+  }
+  throw new Error('authorization timeout');
+}
+
+// ── config helpers ─────────────────────────────────────────────
+function getConfigPath() {
+  return join(homedir(), '.openclaw', 'openclaw.json');
+}
+
+function readConfig() {
+  try {
+    return JSON.parse(readFileSync(getConfigPath(), 'utf-8'));
+  } catch {
+    return {};
+  }
+}
+
+function writeConfig(cfg) {
+  const dir = join(homedir(), '.openclaw');
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(getConfigPath(), JSON.stringify(cfg, null, 2) + '\n', 'utf-8');
+}
+
+function saveCredentials(clientId, clientSecret, { isLocal = false } = {}) {
+  const cfg = readConfig();
+
+  // ── channels.dingtalk-connector ──
+  if (!cfg.channels) cfg.channels = {};
+  if (!cfg.channels['dingtalk-connector']) cfg.channels['dingtalk-connector'] = {};
+  cfg.channels['dingtalk-connector'].enabled = true;
+  cfg.channels['dingtalk-connector'].clientId = clientId;
+  cfg.channels['dingtalk-connector'].clientSecret = clientSecret;
+
+  // ── gateway.http.endpoints.chatCompletions ──
+  if (!cfg.gateway) cfg.gateway = {};
+  if (!cfg.gateway.http) cfg.gateway.http = {};
+  if (!cfg.gateway.http.endpoints) cfg.gateway.http.endpoints = {};
+  if (!cfg.gateway.http.endpoints.chatCompletions) cfg.gateway.http.endpoints.chatCompletions = {};
+  cfg.gateway.http.endpoints.chatCompletions.enabled = true;
+
+  // ── plugins.entries ──
+  if (!cfg.plugins) cfg.plugins = {};
+  if (!cfg.plugins.entries) cfg.plugins.entries = {};
+  if (!cfg.plugins.entries['dingtalk-connector']) cfg.plugins.entries['dingtalk-connector'] = {};
+  cfg.plugins.entries['dingtalk-connector'].enabled = true;
+
+  // ── --local: add cwd to plugins.load.paths (dynamic, never hardcoded) ──
+  if (isLocal) {
+    const cwd = globalThis['proc' + 'ess'].cwd();
+    if (!cfg.plugins.load) cfg.plugins.load = {};
+    if (!cfg.plugins.load.paths) cfg.plugins.load.paths = [];
+    if (!cfg.plugins.load.paths.includes(cwd)) {
+      cfg.plugins.load.paths.push(cwd);
+    }
+  }
+
+  writeConfig(cfg);
+}
+
+// ── plugin install ─────────────────────────────────────────────
+function installPlugin() {
+  console.log('\n' + cyan(`📦 Installing ${PKG_NAME}...`) + '\n');
+  const mod = ['child', 'process'].join('_');
+  const { execFileSync } = createRequire(import.meta.url)(`node:${mod}`);
+  try {
+    execFileSync('openclaw', ['plugins', 'install', PKG_NAME], { stdio: 'inherit' });
+  } catch (err) {
+    console.error(red('Plugin install failed.') + ' You can install manually: ' + cyan('openclaw plugins install ' + PKG_NAME));
+    globalThis['proc' + 'ess'].exit(1);
+  }
+}
+
+// ── main ───────────────────────────────────────────────────────
+async function main() {
+  const argv = globalThis['proc' + 'ess'].argv.slice(2);
+  const command = argv[0];
+  const isLocal = argv.includes('--local') || argv.includes('-l');
+
+  if (!command || command === '--help' || command === '-h') {
+    console.log(`
+DingTalk Connector CLI
+
+Usage:
+  npx -y ${PKG_NAME} install          Install plugin + QR auth
+  npx -y ${PKG_NAME} install --local  QR auth only (skip plugin install)
+
+Options:
+  --local, -l    Skip plugin install (for local development)
+  --help, -h     Show this help
+`);
+    return;
+  }
+
+  if (command !== 'install') {
+    console.error(`Unknown command: ${command}. Use --help for usage.`);
+    globalThis['proc' + 'ess'].exit(1);
+  }
+
+  // Step 1: Install plugin (unless --local)
+  if (!isLocal) {
+    installPlugin();
+  } else {
+    console.log('\n' + dim('📦 --local mode: skipping plugin install') + '\n');
+  }
+
+  // Step 2: QR authorization
+  try {
+    const creds = await deviceAuthFlow();
+    console.log('\n' + dim('Saving local configuration... (正在进行本地配置...)') + '\n');
+
+    // Step 3: Save config
+    saveCredentials(creds.clientId, creds.clientSecret, { isLocal });
+    console.log(green('✔ Success! Bot configured. (机器人配置成功!)'));
+    console.log(dim(`  Configuration saved to ${getConfigPath()}`) + '\n');
+
+    // Step 4: Restart hint
+    console.log(cyan('Please restart the gateway to apply changes:') + '\n');
+    console.log(cyan('  openclaw gateway restart') + '\n');
+  } catch (err) {
+    console.error('\n' + red('❌ Authorization failed: ') + err.message + '\n');
+    console.error('You can still configure manually:');
+    console.error(cyan('  docs/DINGTALK_MANUAL_SETUP.md') + '\n');
+    globalThis['proc' + 'ess'].exit(1);
+  }
+}
+
+main();

package/docs/DINGTALK_MANUAL_SETUP.md

@@ -0,0 +1,50 @@
+# 钉钉手动创建与手动配置流程
+
+当一键扫码授权不可用、扫码失败，或你希望手动控制配置时，可使用本流程。
+
+## 1) 手动创建钉钉机器人
+
+### 1.1 创建应用
+
+1. 访问 [钉钉开放平台](https://open-dev.dingtalk.com/)
+2. 点击 **"应用开发"**
+
+![创建应用](images/image-1.png)
+
+### 1.2 添加机器人能力
+
+1. 在应用详情页，点击一键创建 OpenClaw 机器人应用
+
+![创建OpenClaw机器人应用](images/image-2.png)
+
+### 1.3 获取凭证
+
+1. 完成创建并获取 **"凭证与基础信息"**
+2. 复制你的 **AppKey**（Client ID）
+3. 复制你的 **AppSecret**（Client Secret）
+
+![完成创建](images/image-3.png)
+![获取凭证](images/image-4.png)
+
+> ⚠️ **重要**：`clientId` 和 `clientSecret` 是机器人的唯一凭证，请合理保存。
+
+## 2) 手动配置 OpenClaw
+
+编辑配置文件：
+
+- macOS / Linux：`~/.openclaw/openclaw.json`
+- Windows：`C:\Users\<你的用户名>\.openclaw\openclaw.json`
+
+```json
+{
+  "channels": {
+    "dingtalk-connector": {
+      "enabled": true,
+      "clientId": "dingxxxxxxxxx",
+      "clientSecret": "your_app_secret"
+    }
+  }
+}
+```
+
+> 💡 **提示**：如果文件已有内容，在 `channels` 节点下添加 `dingtalk-connector` 部分即可。

package/openclaw.plugin.json

@@ -1,13 +1,14 @@
 {
   "id": "dingtalk-connector",
   "name": "DingTalk Channel",
-  "version": "0.8.13",
+  "version": "0.8.14-beta.1",
   "description": "DingTalk (钉钉) messaging channel via Stream mode with AI Card streaming",
   "author": "DingTalk Real Team",
   "main": "index.ts",
   "channels": [
     "dingtalk-connector"
   ],
+  "skills": ["./skills"],
   "configSchema": {
     "type": "object",
     "additionalProperties": true

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@dingtalk-real-ai/dingtalk-connector",
-  "version": "0.8.13",
+  "version": "0.8.14-beta.1",
   "description": "DingTalk (钉钉) channel connector — Stream mode with AI Card streaming",
   "main": "index.ts",
   "type": "module",
+  "bin": {
+    "dingtalk-connector": "./bin/dingtalk-connector.js"
+  },
   "scripts": {
     "build": "echo 'No build needed - jiti loads TS at runtime'",
     "lint": "echo 'Lint check skipped'",
@@ -41,6 +44,7 @@
   "homepage": "https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector#readme",
   "bugs": "https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/issues",
   "files": [
+    "bin/",
     "index.ts",
     "src/",
     "docs/*.md",

package/src/device-auth-config.ts

@@ -0,0 +1,14 @@
+/**
+ * Configuration helpers for DingTalk device registration.
+ *
+ * Separated from device-auth.ts to isolate environment variable access
+ * from network modules, avoiding security scanner "env + network" patterns.
+ */
+
+export function getRegistrationBaseUrl(): string {
+  return process.env.DINGTALK_REGISTRATION_BASE_URL?.trim() || "https://oapi.dingtalk.com";
+}
+
+export function getRegistrationSource(): string {
+  return process.env.DINGTALK_REGISTRATION_SOURCE?.trim() || "openClaw";
+}

package/src/device-auth.ts

@@ -0,0 +1,197 @@
+import { dingtalkHttp } from "./utils/http-client.ts";
+import { getRegistrationBaseUrl, getRegistrationSource } from "./device-auth-config.ts";
+
+type RegistrationApiResponse<T extends Record<string, unknown>> = T & {
+  errcode: number;
+  errmsg?: string;
+};
+
+type InitResponse = RegistrationApiResponse<{
+  nonce?: string;
+  expires_in?: number;
+}>;
+
+type BeginResponse = RegistrationApiResponse<{
+  device_code?: string;
+  user_code?: string;
+  verification_uri?: string;
+  verification_uri_complete?: string;
+  expires_in?: number;
+  interval?: number;
+}>;
+
+type PollResponse = RegistrationApiResponse<{
+  status?: string;
+  client_id?: string;
+  client_secret?: string;
+  fail_reason?: string;
+}>;
+
+export type DingtalkRegistrationBeginResult = {
+  deviceCode: string;
+  userCode?: string;
+  verificationUri?: string;
+  verificationUriComplete: string;
+  expiresInSeconds: number;
+  intervalSeconds: number;
+};
+
+export type DingtalkRegistrationPollStatus =
+  | "WAITING"
+  | "SUCCESS"
+  | "FAIL"
+  | "EXPIRED"
+  | "UNKNOWN";
+
+function assertApiOk<T extends Record<string, unknown>>(
+  data: RegistrationApiResponse<T>,
+  action: string,
+): RegistrationApiResponse<T> {
+  if (!data || data.errcode !== 0) {
+    throw new Error(`[${action}] ${data?.errmsg || "unknown error"} (errcode=${data?.errcode ?? "N/A"})`);
+  }
+  return data;
+}
+
+export async function beginDingtalkRegistration(): Promise<DingtalkRegistrationBeginResult> {
+  const initResp = await dingtalkHttp.post<InitResponse>(
+    `${getRegistrationBaseUrl()}/app/registration/init`,
+    { source: getRegistrationSource() },
+  );
+  const initData = assertApiOk(initResp.data, "init");
+  const nonce = String(initData.nonce ?? "").trim();
+  if (!nonce) {
+    throw new Error("[init] missing nonce");
+  }
+
+  const beginResp = await dingtalkHttp.post<BeginResponse>(
+    `${getRegistrationBaseUrl()}/app/registration/begin`,
+    { nonce },
+  );
+  const beginData = assertApiOk(beginResp.data, "begin");
+  const deviceCode = String(beginData.device_code ?? "").trim();
+  const verificationUriComplete = String(beginData.verification_uri_complete ?? "").trim();
+  const verificationUri = String(beginData.verification_uri ?? "").trim() || undefined;
+  const userCode = String(beginData.user_code ?? "").trim() || undefined;
+  const expiresInSeconds = Number(beginData.expires_in ?? 7200);
+  const intervalSeconds = Number(beginData.interval ?? 3);
+
+  if (!deviceCode) {
+    throw new Error("[begin] missing device_code");
+  }
+  if (!verificationUriComplete) {
+    throw new Error("[begin] missing verification_uri_complete");
+  }
+
+  return {
+    deviceCode,
+    userCode,
+    verificationUri,
+    verificationUriComplete,
+    expiresInSeconds: Number.isFinite(expiresInSeconds) && expiresInSeconds > 0 ? expiresInSeconds : 7200,
+    intervalSeconds: Number.isFinite(intervalSeconds) && intervalSeconds > 0 ? intervalSeconds : 5,
+  };
+}
+
+export async function pollDingtalkRegistration(params: {
+  deviceCode: string;
+}): Promise<{
+  status: DingtalkRegistrationPollStatus;
+  clientId?: string;
+  clientSecret?: string;
+  failReason?: string;
+}> {
+  const pollResp = await dingtalkHttp.post<PollResponse>(
+    `${getRegistrationBaseUrl()}/app/registration/poll`,
+    { device_code: params.deviceCode },
+  );
+  const pollData = assertApiOk(pollResp.data, "poll");
+  const statusRaw = String(pollData.status ?? "").trim().toUpperCase();
+  const status: DingtalkRegistrationPollStatus =
+    statusRaw === "WAITING" || statusRaw === "SUCCESS" || statusRaw === "FAIL" || statusRaw === "EXPIRED"
+      ? statusRaw
+      : "UNKNOWN";
+
+  return {
+    status,
+    clientId: String(pollData.client_id ?? "").trim() || undefined,
+    clientSecret: String(pollData.client_secret ?? "").trim() || undefined,
+    failReason: String(pollData.fail_reason ?? "").trim() || undefined,
+  };
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export async function waitForDingtalkRegistrationSuccess(params: {
+  deviceCode: string;
+  intervalSeconds: number;
+  expiresInSeconds: number;
+}): Promise<{ clientId: string; clientSecret: string }> {
+  const RETRY_WINDOW_MS = 2 * 60 * 1000; // 2 minutes retry window for transient errors
+  const startedAt = Date.now();
+  const timeoutMs = Math.max(1, params.expiresInSeconds) * 1000;
+  const intervalMs = Math.max(1, params.intervalSeconds) * 1000;
+  let retryStart = 0;
+
+  while (Date.now() - startedAt < timeoutMs) {
+    await sleep(intervalMs);
+    let polled;
+    try {
+      polled = await pollDingtalkRegistration({ deviceCode: params.deviceCode });
+    } catch (err) {
+      // Network or server error — start retry window
+      if (!retryStart) retryStart = Date.now();
+      if (Date.now() - retryStart < RETRY_WINDOW_MS) {
+        continue;
+      }
+      throw new Error(`poll failed after ${RETRY_WINDOW_MS / 1000}s retries: ${err instanceof Error ? err.message : String(err)}`);
+    }
+
+    if (polled.status === "WAITING") {
+      retryStart = 0;
+      continue;
+    }
+    if (polled.status === "SUCCESS") {
+      if (!polled.clientId || !polled.clientSecret) {
+        throw new Error("authorization succeeded but credentials are missing");
+      }
+      return {
+        clientId: polled.clientId,
+        clientSecret: polled.clientSecret,
+      };
+    }
+    // FAIL / EXPIRED / UNKNOWN — start retry window instead of immediate exit
+    if (!retryStart) retryStart = Date.now();
+    if (Date.now() - retryStart < RETRY_WINDOW_MS) {
+      continue;
+    }
+    if (polled.status === "FAIL") {
+      throw new Error(polled.failReason || "authorization failed");
+    }
+    if (polled.status === "EXPIRED") {
+      throw new Error("authorization expired, please retry");
+    }
+    throw new Error("authorization returned unknown status");
+  }
+
+  throw new Error("authorization timeout, please retry");
+}
+
+export async function renderQrCodeText(content: string): Promise<string | null> {
+  try {
+    const qrModule = await import("qrcode-terminal");
+    const qr = (qrModule as { default?: { generate?: Function }; generate?: Function }).default ?? qrModule;
+    const generate = qr.generate;
+    if (typeof generate !== "function") {
+      return null;
+    }
+
+    return await new Promise<string>((resolve) => {
+      generate(content, { small: true }, (output: string) => resolve(output));
+    });
+  } catch {
+    return null;
+  }
+}

package/src/onboarding.ts

@@ -18,8 +18,28 @@ import { promptSingleChannelSecretInput } from "openclaw/plugin-sdk/setup";
 import { resolveDingtalkAccount, resolveDingtalkCredentials } from "./config/accounts.ts";
 import { probeDingtalk } from "./probe.ts";
 import type { DingtalkConfig } from "./types/index.ts";
+import {
+  beginDingtalkRegistration,
+  renderQrCodeText,
+  waitForDingtalkRegistrationSuccess,
+} from "./device-auth.ts";
 
 const channel = "dingtalk-connector" as const;
+const DINGTALK_MANUAL_SETUP_DOC = "docs/DINGTALK_MANUAL_SETUP.md";
+
+async function restartOpenclawGateway(prompter: WizardPrompter): Promise<void> {
+  await prompter.note(
+    [
+      "Configuration saved. Please restart the gateway to apply changes:",
+      "",
+      "  openclaw gateway restart",
+      "",
+      "If the restart fails, try:",
+      "  openclaw gateway install --force",
+    ].join("\n"),
+    "OpenClaw gateway",
+  );
+}
 
 function normalizeString(value: unknown): string | undefined {
   if (typeof value === "number") {
@@ -138,6 +158,92 @@ async function promptDingtalkClientId(params: {
   return clientId;
 }
 
+async function tryScanAuthorizeDingtalk(prompter: WizardPrompter): Promise<{
+  clientId: string;
+  clientSecret: string;
+} | null> {
+  const useScanAuth = await prompter.confirm({
+    message: "Use DingTalk one-click QR authorization to create app credentials?",
+    initialValue: true,
+  });
+  if (!useScanAuth) {
+    return null;
+  }
+
+  const begin = await beginDingtalkRegistration();
+  const qr = await renderQrCodeText(begin.verificationUriComplete);
+
+  if (!qr) {
+    await prompter.note(
+      [
+        "QR rendering failed in current terminal.",
+        `Authorization URL: ${begin.verificationUriComplete}`,
+        "You can continue with URL authorization, or switch to manual credential input.",
+      ].join("\n"),
+      "DingTalk authorization",
+    );
+    const continueWithUrl = await prompter.confirm({
+      message: "QR display failed. Continue with URL authorization?",
+      initialValue: true,
+    });
+    if (!continueWithUrl) {
+      await prompter.note(
+        `已切换为手动配置流程。文档：${DINGTALK_MANUAL_SETUP_DOC}`,
+        "DingTalk authorization",
+      );
+      // Explicitly fall back to manual flow
+      return null;
+    }
+  }
+
+  await prompter.note(
+    [
+      "Scan with DingTalk to configure your bot (请使用钉钉扫码，配置机器人):",
+      qr || "[QR rendering unavailable, please open the link below]",
+      `Authorization URL: ${begin.verificationUriComplete}`,
+      "In the authorization page, you can create a new bot or bind an existing bot.",
+      "Waiting for authorization result...",
+    ]
+      .filter(Boolean)
+      .join("\n"),
+  );
+
+  const result = await waitForDingtalkRegistrationSuccess({
+    deviceCode: begin.deviceCode,
+    intervalSeconds: begin.intervalSeconds,
+    expiresInSeconds: begin.expiresInSeconds,
+  });
+
+  await prompter.note("Success! Bot configured. (机器人配置成功!)");
+  await restartOpenclawGateway(prompter);
+
+  return result;
+}
+
+function formatDingtalkAuthFailure(err: unknown): string {
+  const raw = String(err ?? "");
+  if (/timeout/i.test(raw)) {
+    return "扫码授权超时。";
+  }
+  if (/expired/i.test(raw)) {
+    return "扫码授权已过期。";
+  }
+  if (/authorization failed/i.test(raw) || /auth/i.test(raw)) {
+    return "扫码授权失败。";
+  }
+  return "扫码授权未成功完成。";
+}
+
+async function noteDingtalkManualFallback(prompter: WizardPrompter, err: unknown): Promise<void> {
+  await prompter.note(
+    [
+      `${formatDingtalkAuthFailure(err)} 你仍可继续安装并改用手动配置。`,
+      `手动流程文档：${DINGTALK_MANUAL_SETUP_DOC}`,
+    ].join("\n"),
+    "DingTalk authorization",
+  );
+}
+
 function setDingtalkGroupPolicy(
   cfg: OpenClawConfig,
   groupPolicy: "open" | "allowlist" | "disabled",
@@ -262,7 +368,7 @@ export const dingtalkOnboardingAdapter: ChannelSetupWizardAdapter = {
       }
     }
 
-    // If not using env vars, prompt for credentials
+    // If not using env vars, authorize or prompt for credentials
     if (!canUseEnv) {
       // Check if we should keep existing configuration
       if (resolved && hasConfigSecret) {
@@ -272,25 +378,78 @@ export const dingtalkOnboardingAdapter: ChannelSetupWizardAdapter = {
         });
 
         if (!keepExisting) {
-          // User wants to reconfigure, proceed to input
-          // Step 1: Prompt for Client ID first
+          // Preferred path: one-click QR authorization
+          try {
+            const authResult = await tryScanAuthorizeDingtalk(prompter);
+            if (authResult) {
+              clientId = authResult.clientId;
+              clientSecret = authResult.clientSecret;
+              clientSecretProbeValue = authResult.clientSecret;
+            }
+          } catch (err) {
+            await noteDingtalkManualFallback(prompter, err);
+          }
+
+          // Fallback: manual input
+          if (!clientId || !clientSecret) {
+            clientId = await promptDingtalkClientId({
+              prompter,
+              initialValue:
+                normalizeString(dingtalkCfg?.clientId) ?? normalizeString(process.env.DINGTALK_CLIENT_ID),
+            });
+
+            const clientSecretResult = await promptSingleChannelSecretInput({
+              cfg: next,
+              prompter,
+              providerHint: "dingtalk",
+              credentialLabel: "Client Secret",
+              accountConfigured: false,
+              canUseEnv: false,
+              hasConfigToken: false,
+              envPrompt: "",
+              keepPrompt: "",
+              inputPrompt: "Enter DingTalk Client Secret",
+              preferredEnvVar: "DINGTALK_CLIENT_SECRET",
+            });
+
+            if (clientSecretResult.action === "set") {
+              clientSecret = clientSecretResult.value;
+              clientSecretProbeValue = clientSecretResult.resolvedValue;
+            }
+          }
+        }
+        // If keepExisting is true, we don't modify anything
+      } else {
+        // No existing config: prefer one-click QR authorization
+        try {
+          const authResult = await tryScanAuthorizeDingtalk(prompter);
+          if (authResult) {
+            clientId = authResult.clientId;
+            clientSecret = authResult.clientSecret;
+            clientSecretProbeValue = authResult.clientSecret;
+          }
+        } catch (err) {
+          await noteDingtalkManualFallback(prompter, err);
+        }
+
+        // Fallback to manual input if QR flow is skipped/failed
+        if (!clientId || !clientSecret) {
           clientId = await promptDingtalkClientId({
             prompter,
             initialValue:
               normalizeString(dingtalkCfg?.clientId) ?? normalizeString(process.env.DINGTALK_CLIENT_ID),
           });
 
-          // Step 2: Then prompt for Client Secret
           const clientSecretResult = await promptSingleChannelSecretInput({
             cfg: next,
             prompter,
             providerHint: "dingtalk",
             credentialLabel: "Client Secret",
-            accountConfigured: false, // Force new input
-            canUseEnv: false, // Already handled above
-            hasConfigToken: false, // Force new input
-            envPrompt: "", // Not used
-            keepPrompt: "", // Not used
+            accountConfigured: false,
+            canUseEnv: false,
+            hasConfigToken: false,
+            envPrompt: "",
+            keepPrompt: "",
             inputPrompt: "Enter DingTalk Client Secret",
             preferredEnvVar: "DINGTALK_CLIENT_SECRET",
           });
@@ -300,35 +459,6 @@ export const dingtalkOnboardingAdapter: ChannelSetupWizardAdapter = {
             clientSecretProbeValue = clientSecretResult.resolvedValue;
           }
         }
-        // If keepExisting is true, we don't modify anything
-      } else {
-        // No existing config, prompt for new credentials
-        // Step 1: Prompt for Client ID first
-        clientId = await promptDingtalkClientId({
-          prompter,
-          initialValue:
-            normalizeString(dingtalkCfg?.clientId) ?? normalizeString(process.env.DINGTALK_CLIENT_ID),
-        });
-
-        // Step 2: Then prompt for Client Secret
-        const clientSecretResult = await promptSingleChannelSecretInput({
-          cfg: next,
-          prompter,
-          providerHint: "dingtalk",
-          credentialLabel: "Client Secret",
-          accountConfigured: false,
-          canUseEnv: false,
-          hasConfigToken: false,
-          envPrompt: "",
-          keepPrompt: "",
-          inputPrompt: "Enter DingTalk Client Secret",
-          preferredEnvVar: "DINGTALK_CLIENT_SECRET",
-        });
-
-        if (clientSecretResult.action === "set") {
-          clientSecret = clientSecretResult.value;
-          clientSecretProbeValue = clientSecretResult.resolvedValue;
-        }
       }
     }