@thclouds/openclaw-channel-taidesk 0.1.1 → 0.1.3

package/README.md

@@ -1,12 +1,10 @@
 # openclaw-channel-taidesk
 
-OpenClaw 渠道插件：**Taidesk MQTT 入站**（订阅 `/open/{agentId}`）+ **HTTP 出站**。
+OpenClaw 渠道插件：**Taidesk MQTT 入站**（订阅 **`/open` + agentId**，中间无 `/`）+ **HTTP 出站**。
 
-## 文档
+## 技术说明
 
-- [MQTT / HTTP 契约](docs/TAIDESK-WS-CONTRACT.zh-CN.md)
-- [四渠道对比与选型](docs/CHANNEL-COMPARISON.zh-CN.md)
-- [开发计划](docs/TAIDESK-PLUGIN-DEV-PLAN.zh-CN.md)
+- [MQTT / HTTP 契约与字段说明](docs/TAIDESK-WS-CONTRACT.zh-CN.md)
 
 ## 依赖
 
@@ -35,13 +33,43 @@ OpenClaw 渠道插件：**Taidesk MQTT 入站**（订阅 `/open/{agentId}`）+ *
 }
 ```
 
-订阅 topic：**`/open/{agentId}`**。入站 JSON 见契约文档中的 `agent_msg` 示例。
+**MQTT 鉴权**：未配置 `mqttUsername` 且未显式配置 `mqttPassword` 时为**匿名连接**（`apiKey` 仅用于 HTTP 出站，不会当作 MQTT 密码）。若 Broker 要求用户名/密码，请配置 `mqttUsername` 或 `mqttPassword`。
+
+订阅 topic：**`/open` + `agentId`**（例：`agentId` 为 `2014147198056767490` 时 topic 为 `/open2014147198056767490`）。入站 JSON 见契约文档中的 `agent_msg` 示例。
+
+## 本地 MQTT 自测（连接 + 可选触发下行）
+
+联调脚本位于 **`tests/live/taidesk-mqtt-smoke.ts`**（与 `tests/unit` 同属 `tests/`，目录说明见 [`tests/README.md`](tests/README.md)）。脚本会：
+
+1. 用与线上一致的参数连接 MQTT、订阅 `/open`+`agentId`；
+2. 若设置 **`TAIDESK_TEST_BEARER`**，在连接成功后 **GET** `TAIDESK_TEST_GET_URL`（默认  
+   `https://demo.devlake.thclouds.com:17443/api/app-console/ai/v1/agent/<agentId>/test`），由控制台经 MQTT 下发测试消息，脚本打印收到的 payload；
+3. 默认运行 **120s**（`TAIDESK_SMOKE_MS` 可改）。
+
+仅连 MQTT、不调用 HTTP（例如只等自然消息）：
+
+```bash
+npm run smoke:mqtt
+```
+
+连接 + 触发测试接口（Bearer **不要提交到仓库**，只在本地或 CI 密钥里配置）：
+
+```powershell
+$env:TAIDESK_MQTT_TLS_INSECURE='1'
+$env:TAIDESK_TEST_BEARER='你的BearerToken'
+npm run smoke:mqtt
+```
+
+若 Node 报错 **`certificate has expired`**，说明 HTTPS/MQTT 的 TLS 证书已过期；`TAIDESK_MQTT_TLS_INSECURE=1` 会同时作用于 **MQTT 与上述测试 GET**（**仅开发**）。OpenClaw 网关跑插件时也可设该变量；**根治**请更换服务端证书。
+
+可用 `TAIDESK_MQTT_URL`、`TAIDESK_AGENT_ID`、`TAIDESK_TEST_GET_URL` 等覆盖；`TAIDESK_SKIP_HTTP_TEST=1` 只测 MQTT、不发 GET。
 
 ## 脚本
 
 | 命令 | 说明 |
 |------|------|
 | `npm run type-check` | TypeScript 检查 |
+| `npm run smoke:mqtt` | 实连 MQTT，收消息冒烟 |
 | `npm test` | Vitest 单元测试 |
 
 ## 许可

package/index.ts

@@ -1,9 +1,9 @@
-import { buildChannelConfigSchema } from "openclaw/plugin-sdk/channel-config-schema";
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
+import { buildChannelConfigSchema } from "openclaw/plugin-sdk/channel-config-schema";
 
 import { taideskPlugin } from "./src/channel.js";
 import { assertHostCompatibility } from "./src/compat.js";
-import { TaideskChannelConfigSchema } from "./src/config-schema.js";
+import { TaideskChannelConfigSchema } from "./src/config/config-schema.js";
 import { setTaideskRuntime } from "./src/runtime.js";
 
 export { taideskPlugin, setTaideskRuntime };
@@ -14,6 +14,7 @@ export default {
   description: "Taidesk channel (MQTT inbound + HTTP webhook outbound)",
   configSchema: buildChannelConfigSchema(TaideskChannelConfigSchema),
   register(api: OpenClawPluginApi) {
+    // Fail-fast: reject incompatible host versions before any side-effects.
     assertHostCompatibility(api.runtime?.version);
 
     if (api.runtime) {
@@ -22,6 +23,7 @@ export default {
 
     api.registerChannel({ plugin: taideskPlugin });
 
+    // registrationMode exists in 2026.3.22+; skip heavy registrations in setup-only mode.
     const mode = (api as { registrationMode?: string }).registrationMode;
     if (mode && mode !== "full") return;
   },

package/openclaw.plugin.json

@@ -1,6 +1,5 @@
 {
   "id": "taidesk",
-  "version": "0.1.1",
   "channels": ["taidesk"],
   "configSchema": {
     "type": "object",

package/package.json

@@ -1,20 +1,24 @@
 {
   "name": "@thclouds/openclaw-channel-taidesk",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "OpenClaw Taidesk channel plugin (MQTT inbound + HTTP outbound)",
   "license": "MIT",
   "author": "thclouds",
   "type": "module",
   "files": [
     "src/",
+    "!src/**/*.test.ts",
+    "!src/**/node_modules/",
     "index.ts",
     "openclaw.plugin.json",
     "README.md"
   ],
   "scripts": {
     "type-check": "tsc -p tsconfig.json --noEmit",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run",
-    "prepublishOnly": "npm run type-check && npm test"
+    "smoke:mqtt": "tsx tests/live/taidesk-mqtt-smoke.ts",
+    "prepublishOnly": "npm run typecheck && npm test"
   },
   "publishConfig": {
     "access": "public",
@@ -33,6 +37,7 @@
   "devDependencies": {
     "@types/node": "^22.10.0",
     "openclaw": "2026.3.23",
+    "tsx": "^4.19.0",
     "typescript": "^5.8.0",
     "vitest": "^3.1.0"
   },

package/src/api/{taidesk-outbound.ts → api.ts}

@@ -1,6 +1,6 @@
 import type { OpenClawConfig } from "openclaw/plugin-sdk/core";
 
-import { resolveTaideskAccount } from "../config.js";
+import { resolveTaideskAccount } from "../config/config.js";
 import type { TaideskAccountConfig } from "../types.js";
 
 function resolveTaideskWebhookUrl(config: TaideskAccountConfig): string {
@@ -10,12 +10,12 @@ function resolveTaideskWebhookUrl(config: TaideskAccountConfig): string {
 export async function sendTaideskText(params: {
   cfg: OpenClawConfig;
   accountId: string;
-  conversationId: string;
+  sessionId: string;
   text: string;
   log?: (m: string) => void;
   errLog?: (m: string) => void;
 }): Promise<{ ok: boolean; status: number; body?: string }> {
-  const { cfg, accountId, conversationId, text } = params;
+  const { cfg, accountId, sessionId, text } = params;
   const log = params.log ?? (() => {});
   const errLog = params.errLog ?? log;
   const { config } = resolveTaideskAccount(cfg, accountId);
@@ -28,7 +28,7 @@ export async function sendTaideskText(params: {
     headers.Authorization = `Bearer ${bearer}`;
   }
   const body = JSON.stringify({
-    conversationId,
+    sessionId,
     text,
   });
   log(`taidesk outbound POST ${url.toString()} len=${body.length}`);

package/src/channel.ts

@@ -7,9 +7,9 @@ import {
   applyTaideskAccountDefaults,
   getTaideskConfig,
   isTaideskAccountConfigured,
-} from "./config.js";
-import { startTaideskMonitor } from "./monitor/taidesk-monitor.js";
-import { sendTaideskText } from "./api/taidesk-outbound.js";
+} from "./config/config.js";
+import { sendTaideskText } from "./api/api.js";
+import { monitorTaideskProvider } from "./monitor/monitor.js";
 import type { TaideskAccountConfig } from "./types.js";
 
 export type ResolvedTaideskAccount = {
@@ -39,7 +39,7 @@ export const taideskPlugin: ChannelPlugin<ResolvedTaideskAccount> = {
     selectionLabel: "Taidesk (MQTT)",
     docsPath: "/channels/taidesk",
     docsLabel: "Taidesk",
-    blurb: "Taidesk：MQTT 入站 `/open/{agentId}` + HTTP 出站",
+    blurb: "Taidesk：MQTT 入站 `/open`+agentId + HTTP 出站",
     order: 76,
   },
   configSchema: {
@@ -117,7 +117,7 @@ export const taideskPlugin: ChannelPlugin<ResolvedTaideskAccount> = {
     resolveTarget: ({ to }: { to?: string }) => {
       const trimmed = to?.trim();
       if (!trimmed) {
-        return { ok: false as const, error: new Error("taidesk: --to <conversationId> required") };
+        return { ok: false as const, error: new Error("taidesk: --to <sessionId> required") };
       }
       return { ok: true as const, to: trimmed };
     },
@@ -127,7 +127,7 @@ export const taideskPlugin: ChannelPlugin<ResolvedTaideskAccount> = {
       const result = await sendTaideskText({
         cfg,
         accountId: id,
-        conversationId: to,
+        sessionId: to,
         text,
         log: (m) => {
           console.info(`[taidesk] ${m}`);
@@ -151,7 +151,7 @@ export const taideskPlugin: ChannelPlugin<ResolvedTaideskAccount> = {
       if (!isTaideskAccountConfigured(account.config)) {
         throw new Error("taidesk: mqttUrl、agentId、webhook、apiKey 为必填（且需替换默认占位 agentId/apiKey）");
       }
-      const mon = startTaideskMonitor({
+      const mon = monitorTaideskProvider({
         cfg,
         accountId: account.accountId,
         accountConfig: account.config,

package/src/compat.ts

@@ -1,9 +1,30 @@
 /**
- * OpenClaw 宿主版本校验（日期版本 YYYY.M.DD，如 2026.3.22）。
- * 对齐微信插件 openclaw-weixin 的 compat 行为，避免在过低版本主机上误加载。
+ * Runtime host-version compatibility check for openclaw-channel-taidesk.
+ *
+ * OpenClaw uses a date-based version format: YYYY.M.DD (e.g. 2026.3.22).
+ * This module parses that format and validates the running host is within
+ * the supported range for this plugin version.
  */
 
-export const PLUGIN_VERSION = "0.1.1";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { logger } from "./util/logger.js";
+
+function readPluginVersion(): string {
+  try {
+    const dir = path.dirname(fileURLToPath(import.meta.url));
+    const pkgPath = path.resolve(dir, "..", "package.json");
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8")) as { version?: string };
+    return pkg.version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+/** Package version (from package.json); single source of truth with npm publish. */
+export const PLUGIN_VERSION = readPluginVersion();
 
 export const SUPPORTED_HOST_MIN = "2026.3.22";
 
@@ -13,7 +34,12 @@ export interface OpenClawVersion {
   day: number;
 }
 
+/**
+ * Parse an OpenClaw date version string (e.g. "2026.3.22") into components.
+ * Returns null for unparseable strings.
+ */
 export function parseOpenClawVersion(version: string): OpenClawVersion | null {
+  // Strip any pre-release suffix (e.g. "2026.3.22-beta.1" -> "2026.3.22")
   const base = version.trim().split("-")[0];
   const parts = base.split(".");
   if (parts.length !== 3) return null;
@@ -22,6 +48,9 @@ export function parseOpenClawVersion(version: string): OpenClawVersion | null {
   return { year, month, day };
 }
 
+/**
+ * Compare two parsed versions.  Returns -1 | 0 | 1.
+ */
 export function compareVersions(a: OpenClawVersion, b: OpenClawVersion): -1 | 0 | 1 {
   for (const key of ["year", "month", "day"] as const) {
     if (a[key] < b[key]) return -1;
@@ -30,6 +59,9 @@ export function compareVersions(a: OpenClawVersion, b: OpenClawVersion): -1 | 0
   return 0;
 }
 
+/**
+ * Check whether a host version string is >= SUPPORTED_HOST_MIN.
+ */
 export function isHostVersionSupported(hostVersion: string): boolean {
   const host = parseOpenClawVersion(hostVersion);
   if (!host) return false;
@@ -37,15 +69,26 @@ export function isHostVersionSupported(hostVersion: string): boolean {
   return compareVersions(host, min) >= 0;
 }
 
+/**
+ * Fail-fast guard.  Call at the very start of `register()` to prevent the
+ * plugin from loading on an incompatible host.
+ *
+ * @throws {Error} with a human-readable message when the host is out of range.
+ */
 export function assertHostCompatibility(hostVersion: string | undefined): void {
   if (!hostVersion || hostVersion === "unknown") {
+    logger.warn(
+      `[compat] Could not determine host OpenClaw version; skipping compatibility check.`,
+    );
     return;
   }
   if (isHostVersionSupported(hostVersion)) {
+    logger.info(`[compat] Host OpenClaw ${hostVersion} >= ${SUPPORTED_HOST_MIN}, OK.`);
     return;
   }
   throw new Error(
     `@thclouds/openclaw-channel-taidesk@${PLUGIN_VERSION} requires OpenClaw >=${SUPPORTED_HOST_MIN}, ` +
-      `but found ${hostVersion}. Please upgrade OpenClaw.`,
+      `but found ${hostVersion}. ` +
+      `Please upgrade OpenClaw.`,
   );
 }

package/src/{config.ts → config/config.ts}

@@ -1,7 +1,7 @@
 import type { OpenClawConfig } from "openclaw/plugin-sdk/core";
 
 import { TAIDESK_ACCOUNT_DEFAULTS } from "./config-schema.js";
-import type { TaideskAccountConfig } from "./types.js";
+import type { TaideskAccountConfig } from "../types.js";
 
 export function getTaideskSection(cfg: OpenClawConfig): Record<string, unknown> {
   const ch = cfg.channels as Record<string, unknown> | undefined;

package/src/inbound-handler.ts

@@ -1,5 +1,11 @@
+import { createHash } from "node:crypto";
+
 import type { TaideskInboundEvent } from "./types.js";
 
+function stableEventIdFromRawPayload(raw: string): string {
+  return createHash("sha256").update(raw, "utf8").digest("hex").slice(0, 32);
+}
+
 function parseTaideskCreateTimeMs(createTime: string): number {
   if (!createTime.trim()) {
     return Date.now();
@@ -11,9 +17,9 @@ function parseTaideskCreateTimeMs(createTime: string): number {
 
 /**
  * Taidesk MQTT 载荷：`event: agent_msg`，`data` 为业务体。
- * @see 用户约定示例
+ * 完整形态含 `data.id` / `sessionId` / `userId`；根级发送方回退为 **`agentId`**（兼容旧版根级 `userId`）；精简形态仅根级 `agentId` 作会话路由，不作发送方。
  */
-function parseAgentMsgEnvelope(v: Record<string, unknown>): TaideskInboundEvent | null {
+function parseAgentMsgEnvelope(v: Record<string, unknown>, raw: string): TaideskInboundEvent | null {
   if (v.event !== "agent_msg") {
     return null;
   }
@@ -22,9 +28,32 @@ function parseAgentMsgEnvelope(v: Record<string, unknown>): TaideskInboundEvent
     return null;
   }
   const d = data as Record<string, unknown>;
-  const eventId = d.id != null ? String(d.id) : "";
-  const sessionId = d.sessionId != null ? String(d.sessionId) : "";
-  const userId = d.userId != null ? String(d.userId) : "";
+  const idStr = d.id != null ? String(d.id).trim() : "";
+  const eventId = idStr !== "" ? idStr : stableEventIdFromRawPayload(raw);
+
+  const sessionStr = d.sessionId != null ? String(d.sessionId).trim() : "";
+  const rootAgent =
+    v.agentId != null && String(v.agentId).trim() !== "" ? String(v.agentId).trim() : "";
+  /** 会话维度：优先 `data.sessionId`，否则根级 `agentId`（控制台精简推送无 sessionId 时）。 */
+  const sessionId = sessionStr !== "" ? sessionStr : rootAgent;
+  if (!sessionId) {
+    return null;
+  }
+
+  const fromData = d.userId != null ? String(d.userId).trim() : "";
+  /** 有 `data.sessionId` 时根级 `agentId` 表示发送方回退；无 `data.sessionId` 时根级 `agentId` 已用于会话路由，发送方仅认根级 `userId`（兼容）。 */
+  let fromRoot = "";
+  if (sessionStr !== "") {
+    const rootAgentId =
+      v.agentId != null && String(v.agentId).trim() !== "" ? String(v.agentId).trim() : "";
+    const rootUserId =
+      typeof v.userId === "string" && v.userId.trim() !== "" ? v.userId.trim() : "";
+    fromRoot = rootAgentId !== "" ? rootAgentId : rootUserId;
+  } else {
+    fromRoot = typeof v.userId === "string" && v.userId.trim() !== "" ? v.userId.trim() : "";
+  }
+  const userId = fromData !== "" ? fromData : fromRoot !== "" ? fromRoot : "0";
+
   const content = d.content;
   let text = "";
   if (content && typeof content === "object") {
@@ -35,14 +64,11 @@ function parseAgentMsgEnvelope(v: Record<string, unknown>): TaideskInboundEvent
   }
   const tenantId = typeof d.tenantId === "string" ? d.tenantId : undefined;
   const createTime = typeof d.createTime === "string" ? d.createTime : "";
-  const timestamp = parseTaideskCreateTimeMs(createTime);
-  if (!eventId || !sessionId || !userId) {
-    return null;
-  }
+  const timestamp = createTime ? parseTaideskCreateTimeMs(createTime) : Date.now();
   return {
     type: "agent_msg",
     eventId,
-    conversationId: sessionId,
+    sessionId,
     tenantId,
     userId,
     text,
@@ -50,23 +76,29 @@ function parseAgentMsgEnvelope(v: Record<string, unknown>): TaideskInboundEvent
   };
 }
 
-/** 兼容旧版扁平 JSON（测试/迁移） */
+/** 兼容旧版扁平 JSON（测试/迁移）；会话字段优先 `sessionId`，否则 `conversationId`。 */
 function parseLegacyFlat(v: Record<string, unknown>): TaideskInboundEvent | null {
   if (v.type === "ping" || v.type === "pong") {
     return null;
   }
   const eventId = typeof v.eventId === "string" ? v.eventId : "";
-  const conversationId = typeof v.conversationId === "string" ? v.conversationId : "";
+  const sessionIdFromSession =
+    typeof v.sessionId === "string" && v.sessionId.trim() !== "" ? v.sessionId.trim() : "";
+  const sessionIdFromConv =
+    typeof v.conversationId === "string" && v.conversationId.trim() !== ""
+      ? v.conversationId.trim()
+      : "";
+  const sessionId = sessionIdFromSession !== "" ? sessionIdFromSession : sessionIdFromConv;
   const userId = typeof v.userId === "string" ? v.userId : "";
   const text = typeof v.text === "string" ? v.text : "";
   const timestamp = typeof v.timestamp === "number" ? v.timestamp : Date.now();
-  if (!eventId || !conversationId || !userId) {
+  if (!eventId || !sessionId || !userId) {
     return null;
   }
   return {
     type: typeof v.type === "string" ? v.type : "message",
     eventId,
-    conversationId,
+    sessionId,
     tenantId: typeof v.tenantId === "string" ? v.tenantId : undefined,
     userId,
     text,
@@ -77,7 +109,7 @@ function parseLegacyFlat(v: Record<string, unknown>): TaideskInboundEvent | null
 export function parseTaideskInboundJson(raw: string): TaideskInboundEvent | null {
   try {
     const v = JSON.parse(raw) as Record<string, unknown>;
-    const agent = parseAgentMsgEnvelope(v);
+    const agent = parseAgentMsgEnvelope(v, raw);
     if (agent) {
       return agent;
     }

package/src/messaging/{process-inbound.ts → process-message.ts}

@@ -3,7 +3,7 @@ import type { PluginRuntime } from "openclaw/plugin-sdk/core";
 import { createTypingCallbacks } from "openclaw/plugin-sdk/channel-runtime";
 import type { MsgContext } from "openclaw/plugin-sdk/reply-runtime";
 
-import { sendTaideskText } from "../api/taidesk-outbound.js";
+import { sendTaideskText } from "../api/api.js";
 import type { TaideskInboundEvent } from "../types.js";
 
 export async function processTaideskInbound(params: {
@@ -21,14 +21,14 @@ export async function processTaideskInbound(params: {
   const ctx: MsgContext = {
     Body: event.text ?? "",
     From: event.userId,
-    To: event.conversationId,
+    To: event.sessionId,
     MessageSid: event.eventId,
     Timestamp: event.timestamp,
     OriginatingChannel: "taidesk",
-    OriginatingTo: event.conversationId,
+    OriginatingTo: event.sessionId,
     AccountId: accountId,
     ChatType: "direct",
-    NativeChannelId: event.conversationId,
+    NativeChannelId: event.sessionId,
     CommandAuthorized: true,
   };
 
@@ -36,7 +36,7 @@ export async function processTaideskInbound(params: {
     cfg,
     channel: "taidesk",
     accountId,
-    peer: { kind: "direct", id: event.conversationId },
+    peer: { kind: "direct", id: event.sessionId },
   });
 
   ctx.SessionKey = route.sessionKey;
@@ -54,7 +54,7 @@ export async function processTaideskInbound(params: {
     updateLastRoute: {
       sessionKey: route.mainSessionKey,
       channel: "taidesk",
-      to: event.conversationId,
+      to: event.sessionId,
       accountId,
     },
     onRecordError: (err) => errLog(`recordInboundSession: ${String(err)}`),
@@ -78,7 +78,7 @@ export async function processTaideskInbound(params: {
         await sendTaideskText({
           cfg,
           accountId,
-          conversationId: event.conversationId,
+          sessionId: event.sessionId,
           text,
           log,
           errLog,

package/src/monitor/{taidesk-monitor.ts → monitor.ts}

@@ -3,8 +3,11 @@ import type { PluginRuntime } from "openclaw/plugin-sdk/core";
 
 import { shouldSkipDedup } from "../dedup.js";
 import { parseTaideskInboundJson } from "../inbound-handler.js";
-import { createTaideskMqttConnection } from "../mqtt/taidesk-mqtt-client.js";
-import { processTaideskInbound } from "../messaging/process-inbound.js";
+import {
+  buildMqttConnectAuth,
+  createTaideskMqttConnection,
+} from "../mqtt/taidesk-mqtt-client.js";
+import { processTaideskInbound } from "../messaging/process-message.js";
 import { resolveTaideskChannelRuntime } from "../runtime.js";
 import type { TaideskAccountConfig } from "../types.js";
 
@@ -19,23 +22,26 @@ export type MonitorTaideskOpts = {
 };
 
 /**
- * 替代微信 `monitorWeixinProvider`：MQTT 订阅 `/open/{agentId}` → 单条处理。
+ * Taidesk 入站：MQTT 订阅 `/open`+agentId → 单条处理（对应微信 `monitorWeixinProvider`）。
  */
-export function startTaideskMonitor(opts: MonitorTaideskOpts): { close: () => void } {
+export function monitorTaideskProvider(opts: MonitorTaideskOpts): { close: () => void } {
   const log = opts.log ?? (() => {});
   const errLog = opts.errLog ?? log;
-  const pwd = opts.accountConfig.mqttPassword ?? opts.accountConfig.apiKey ?? opts.accountConfig.token;
+  const mqttAuth = buildMqttConnectAuth(opts.accountConfig);
+  log(
+    `taidesk mqtt connecting account=${opts.accountId} topic=/open${opts.accountConfig.agentId} auth=${mqttAuth.mode}`,
+  );
 
   const conn = createTaideskMqttConnection({
     mqttUrl: opts.accountConfig.mqttUrl,
     agentId: opts.accountConfig.agentId,
-    mqttUsername: opts.accountConfig.mqttUsername,
-    mqttPassword: pwd,
+    mqttUsername: mqttAuth.username,
+    mqttPassword: mqttAuth.password,
     clientId: opts.accountConfig.mqttClientId,
     abortSignal: opts.abortSignal,
     onConnect: () => {
       log(
-        `taidesk mqtt connected account=${opts.accountId} topic=/open/${opts.accountConfig.agentId}`,
+        `taidesk mqtt connected account=${opts.accountId} topic=/open${opts.accountConfig.agentId}`,
       );
     },
     onMessage: (_topic, raw) => {

package/src/mqtt/taidesk-mqtt-client.ts

@@ -1,4 +1,46 @@
-import mqtt from "mqtt";
+import mqtt, { type IClientOptions } from "mqtt";
+
+export type MqttConnectAuthMode = "none" | "password-only" | "user-pass";
+
+export type MqttConnectAuth = {
+  mode: MqttConnectAuthMode;
+  username?: string;
+  password?: string;
+};
+
+/**
+ * 从账号配置推导 MQTT CONNECT 鉴权。
+ * 多数 Taidesk/DevLake Broker 为**匿名**：不要把 HTTP 的 apiKey 默认当作 MQTT 密码，否则会被服务端断开。
+ * - 未配置 mqttUsername 且未显式配置 mqttPassword → 不传用户名/密码
+ * - 配置了 mqttUsername → 密码为 mqttPassword ?? apiKey ?? token
+ * - 仅显式配置 mqttPassword（非空）且无 username → 仅密码（password-only）
+ * - mqttPassword 为空字符串 → 不传密码（可与 mqttUsername 组合表示「只要用户名」）
+ */
+export function buildMqttConnectAuth(account: {
+  mqttUsername?: string;
+  mqttPassword?: string;
+  apiKey?: string;
+  token?: string;
+}): MqttConnectAuth {
+  const user = account.mqttUsername?.trim();
+  const explicitPwd = account.mqttPassword;
+
+  if (explicitPwd !== undefined) {
+    if (explicitPwd === "") {
+      if (user) return { mode: "user-pass", username: user };
+      return { mode: "none" };
+    }
+    if (user) return { mode: "user-pass", username: user, password: explicitPwd };
+    return { mode: "password-only", password: explicitPwd };
+  }
+
+  if (user) {
+    const password = account.apiKey ?? account.token ?? "";
+    return { mode: "user-pass", username: user, password };
+  }
+
+  return { mode: "none" };
+}
 
 /** Taidesk 控制台常用 https://host/ws，mqtt.js WebSocket 需 wss:// */
 export function normalizeMqttConnectUrl(mqttUrl: string): string {
@@ -14,8 +56,9 @@ export function normalizeMqttConnectUrl(mqttUrl: string): string {
 export type TaideskMqttClientOptions = {
   /** 例如 mqtt://、mqtts://、ws://、wss://（MQTT over WebSocket）；https/http 会规范为 wss/ws */
   mqttUrl: string;
-  /** 订阅 topic：`/open/{agentId}` */
+  /** 订阅 topic：`/open` + agentId（与 Taidesk Broker 一致，中间无 `/`） */
   agentId: string;
+  /** 已由 buildMqttConnectAuth 解析；未设置时不要传 apiKey 作为默认密码 */
   mqttUsername?: string;
   mqttPassword?: string;
   clientId?: string;
@@ -24,22 +67,39 @@ export type TaideskMqttClientOptions = {
   onClose?: () => void;
   onError?: (err: Error) => void;
   abortSignal?: AbortSignal;
+  /**
+   * 默认遵循 Node TLS 校验。设为 `false` 仅用于自签/过期证书的开发环境（勿用于生产）。
+   * 也可设置环境变量 `TAIDESK_MQTT_TLS_INSECURE=1`（在 options 未传时生效）。
+   */
+  rejectUnauthorized?: boolean;
 };
 
 /**
- * Taidesk 入站：MQTT 订阅 `/open/{agentId}`。
+ * Taidesk 入站：MQTT 订阅 `/open` + agentId（示例：`/open2014147198056767490`）。
  * 重连由 mqtt.js 内置 `reconnectPeriod` 处理。
  */
 export function createTaideskMqttConnection(opts: TaideskMqttClientOptions): { close: () => void } {
-  const topic = `/open/${opts.agentId}`;
+  const topic = `/open${opts.agentId.trim()}`;
   const connectUrl = normalizeMqttConnectUrl(opts.mqttUrl);
-  const client = mqtt.connect(connectUrl, {
-    username: opts.mqttUsername,
-    password: opts.mqttPassword,
+  const clientOpts: IClientOptions = {
+    protocolVersion: 4,
+    clean: true,
     clientId: opts.clientId ?? `openclaw-taidesk-${Date.now()}`,
     reconnectPeriod: 5_000,
     connectTimeout: 30_000,
-  });
+  };
+  if (opts.mqttUsername !== undefined && opts.mqttUsername !== "") {
+    clientOpts.username = opts.mqttUsername;
+  }
+  if (opts.mqttPassword !== undefined && opts.mqttPassword !== "") {
+    clientOpts.password = opts.mqttPassword;
+  }
+  const tlsInsecure =
+    opts.rejectUnauthorized === false || process.env.TAIDESK_MQTT_TLS_INSECURE === "1";
+  if (tlsInsecure) {
+    clientOpts.rejectUnauthorized = false;
+  }
+  const client = mqtt.connect(connectUrl, clientOpts);
 
   const onAbort = (): void => {
     client.end(true);
@@ -49,7 +109,7 @@ export function createTaideskMqttConnection(opts: TaideskMqttClientOptions): { c
   client.on("connect", () => {
     client.subscribe(topic, { qos: 0 }, (err) => {
       if (err) {
-        opts.onError?.(err);
+        opts.onError?.(err instanceof Error ? err : new Error(String(err)));
         return;
       }
       opts.onConnect?.();

package/src/types.ts

@@ -4,7 +4,8 @@
 export type TaideskInboundEvent = {
   type: string;
   eventId: string;
-  conversationId: string;
+  /** Taidesk 会话：`data.sessionId`；无则根级 `agentId`（精简推送）。用于 peer 路由与出站 HTTP。 */
+  sessionId: string;
   tenantId?: string;
   userId: string;
   text?: string;
@@ -16,14 +17,16 @@ export type TaideskAccountConfig = {
   name?: string;
   /** MQTT Broker，如 mqtts://host:8883、wss://host/mqtt；https:// 会在连接前规范为 wss:// */
   mqttUrl: string;
-  /** 订阅 topic `/open/{agentId}` */
+  /** 订阅 topic 为 `/open` + 本字段（无中间斜杠，如 `/open2014147198056767490`） */
   agentId: string;
   /** 出站 Webhook 完整 URL；可用 `{id}` 占位，发送前替换为 agentId */
   webhook: string;
   apiKey: string;
+  /** 若设置：MQTT 密码为 mqttPassword ?? apiKey ?? token */
   mqttUsername?: string;
+  /** 显式 MQTT 密码；与 mqttUsername 均未配置时**不会**把 apiKey 当作 MQTT 密码（匿名连接） */
   mqttPassword?: string;
   mqttClientId?: string;
-  /** HTTP 出站 Bearer；若未设 mqttPassword 也可作 MQTT 密码 */
+  /** HTTP 出站 Bearer；在已配置 mqttUsername 时可作为 MQTT 密码后备 */
   token?: string;
 };

package/src/util/logger.ts

@@ -0,0 +1,145 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { resolvePreferredOpenClawTmpDir } from "openclaw/plugin-sdk/infra-runtime";
+
+/**
+ * Plugin logger — writes JSON lines to the main openclaw log file:
+ *   <tmpDir>/openclaw-YYYY-MM-DD.log
+ * Same file and format used by all other channels.
+ */
+
+const MAIN_LOG_DIR = resolvePreferredOpenClawTmpDir();
+const SUBSYSTEM = "gateway/channels/taidesk";
+const RUNTIME = "node";
+const RUNTIME_VERSION = process.versions.node;
+const HOSTNAME = os.hostname() || "unknown";
+const PARENT_NAMES = ["openclaw"];
+
+/** tslog-compatible level IDs (higher = more severe). */
+const LEVEL_IDS: Record<string, number> = {
+  TRACE: 1,
+  DEBUG: 2,
+  INFO: 3,
+  WARN: 4,
+  ERROR: 5,
+  FATAL: 6,
+};
+
+const DEFAULT_LOG_LEVEL = "INFO";
+
+function resolveMinLevel(): number {
+  const env = process.env.OPENCLAW_LOG_LEVEL?.toUpperCase();
+  if (env && env in LEVEL_IDS) return LEVEL_IDS[env];
+  return LEVEL_IDS[DEFAULT_LOG_LEVEL];
+}
+
+let minLevelId = resolveMinLevel();
+
+/** Dynamically change the minimum log level at runtime. */
+export function setLogLevel(level: string): void {
+  const upper = level.toUpperCase();
+  if (!(upper in LEVEL_IDS)) {
+    throw new Error(`Invalid log level: ${level}. Valid levels: ${Object.keys(LEVEL_IDS).join(", ")}`);
+  }
+  minLevelId = LEVEL_IDS[upper];
+}
+
+/** Shift a Date into local time so toISOString() renders local clock digits. */
+function toLocalISO(now: Date): string {
+  const offsetMs = -now.getTimezoneOffset() * 60_000;
+  const sign = offsetMs >= 0 ? "+" : "-";
+  const abs = Math.abs(now.getTimezoneOffset());
+  const offStr = `${sign}${String(Math.floor(abs / 60)).padStart(2, "0")}:${String(abs % 60).padStart(2, "0")}`;
+  return new Date(now.getTime() + offsetMs).toISOString().replace("Z", offStr);
+}
+
+function localDateKey(now: Date): string {
+  return toLocalISO(now).slice(0, 10);
+}
+
+function resolveMainLogPath(): string {
+  const dateKey = localDateKey(new Date());
+  return path.join(MAIN_LOG_DIR, `openclaw-${dateKey}.log`);
+}
+
+let logDirEnsured = false;
+
+export type Logger = {
+  info(message: string): void;
+  debug(message: string): void;
+  warn(message: string): void;
+  error(message: string): void;
+  /** Returns a child logger whose messages are prefixed with `[accountId]`. */
+  withAccount(accountId: string): Logger;
+  /** Returns the current main log file path. */
+  getLogFilePath(): string;
+  close(): void;
+};
+
+function buildLoggerName(accountId?: string): string {
+  return accountId ? `${SUBSYSTEM}/${accountId}` : SUBSYSTEM;
+}
+
+function writeLog(level: string, message: string, accountId?: string): void {
+  const levelId = LEVEL_IDS[level] ?? LEVEL_IDS.INFO;
+  if (levelId < minLevelId) return;
+
+  const now = new Date();
+  const loggerName = buildLoggerName(accountId);
+  const prefixedMessage = accountId ? `[${accountId}] ${message}` : message;
+  const entry = JSON.stringify({
+    "0": loggerName,
+    "1": prefixedMessage,
+    _meta: {
+      runtime: RUNTIME,
+      runtimeVersion: RUNTIME_VERSION,
+      hostname: HOSTNAME,
+      name: loggerName,
+      parentNames: PARENT_NAMES,
+      date: now.toISOString(),
+      logLevelId: LEVEL_IDS[level] ?? LEVEL_IDS.INFO,
+      logLevelName: level,
+    },
+    time: toLocalISO(now),
+  });
+  try {
+    if (!logDirEnsured) {
+      fs.mkdirSync(MAIN_LOG_DIR, { recursive: true });
+      logDirEnsured = true;
+    }
+    fs.appendFileSync(resolveMainLogPath(), `${entry}\n`, "utf-8");
+  } catch {
+    // Best-effort; never block on logging failures.
+  }
+}
+
+/** Creates a logger instance, optionally bound to a specific account. */
+function createLogger(accountId?: string): Logger {
+  return {
+    info(message: string): void {
+      writeLog("INFO", message, accountId);
+    },
+    debug(message: string): void {
+      writeLog("DEBUG", message, accountId);
+    },
+    warn(message: string): void {
+      writeLog("WARN", message, accountId);
+    },
+    error(message: string): void {
+      writeLog("ERROR", message, accountId);
+    },
+    withAccount(id: string): Logger {
+      return createLogger(id);
+    },
+    getLogFilePath(): string {
+      return resolveMainLogPath();
+    },
+    close(): void {
+      // No-op: appendFileSync has no persistent handle to close.
+    },
+  };
+}
+
+export const logger: Logger = createLogger();