@openclaw/zalouser 2026.3.12 → 2026.5.1-beta.2

package/README.md

@@ -6,7 +6,7 @@ OpenClaw extension for Zalo Personal Account messaging via native `zca-js` integ
 
 ## Features
 
-- Channel plugin integration with onboarding + QR login
+- Channel plugin integration with setup wizard + QR login
 - In-process listener/sender via `zca-js` (no external CLI)
 - Multi-account support
 - Agent tool integration (`zalouser`)
@@ -30,8 +30,9 @@ openclaw plugins install @openclaw/zalouser
 ### Option B: local source checkout
 
 ```bash
-openclaw plugins install ./extensions/zalouser
-cd ./extensions/zalouser && pnpm install
+PLUGIN_SRC=./path/to/local/zalouser-plugin
+openclaw plugins install "$PLUGIN_SRC"
+cd "$PLUGIN_SRC" && pnpm install
 ```
 
 Restart the Gateway after install.

package/api.ts

@@ -0,0 +1,9 @@
+export { zalouserPlugin } from "./src/channel.js";
+export { zalouserSetupPlugin } from "./src/channel.setup.js";
+export { createZalouserTool } from "./src/tool.js";
+export { createZalouserSetupWizardProxy, zalouserSetupAdapter } from "./src/setup-core.js";
+export { zalouserSetupWizard } from "./src/setup-surface.js";
+export {
+  collectZalouserSecurityAuditFindings,
+  isZalouserMutableGroupEntry,
+} from "./src/security-audit.js";

package/channel-plugin-api.ts

@@ -0,0 +1,3 @@
+// Keep bundled channel entry imports narrow so bootstrap/discovery paths do
+// not drag setup-only or tool runtime surfaces into lightweight plugin loads.
+export { zalouserPlugin } from "./src/channel.js";

package/contract-api.ts

@@ -0,0 +1,2 @@
+export { collectZalouserSecurityAuditFindings } from "./src/security-audit.js";
+export { legacyConfigRules, normalizeCompatibilityConfig } from "./src/doctor-contract.js";

package/doctor-contract-api.ts

@@ -0,0 +1 @@
+export { normalizeCompatibilityConfig, legacyConfigRules } from "./src/doctor-contract.js";

package/index.ts

@@ -1,29 +1,34 @@
-import type { AnyAgentTool, OpenClawPluginApi } from "openclaw/plugin-sdk/zalouser";
-import { emptyPluginConfigSchema } from "openclaw/plugin-sdk/zalouser";
-import { zalouserDock, zalouserPlugin } from "./src/channel.js";
-import { setZalouserRuntime } from "./src/runtime.js";
-import { ZalouserToolSchema, executeZalouserTool } from "./src/tool.js";
+import {
+  type AnyAgentTool,
+  defineBundledChannelEntry,
+  loadBundledEntryExportSync,
+} from "openclaw/plugin-sdk/channel-entry-contract";
 
-const plugin = {
+function createZalouserTool(context?: unknown): AnyAgentTool {
+  const createTool = loadBundledEntryExportSync<(context?: unknown) => AnyAgentTool>(
+    import.meta.url,
+    {
+      specifier: "./api.js",
+      exportName: "createZalouserTool",
+    },
+  );
+  return createTool(context);
+}
+
+export default defineBundledChannelEntry({
   id: "zalouser",
   name: "Zalo Personal",
   description: "Zalo personal account messaging via native zca-js integration",
-  configSchema: emptyPluginConfigSchema(),
-  register(api: OpenClawPluginApi) {
-    setZalouserRuntime(api.runtime);
-    api.registerChannel({ plugin: zalouserPlugin, dock: zalouserDock });
-
-    api.registerTool({
-      name: "zalouser",
-      label: "Zalo Personal",
-      description:
-        "Send messages and access data via Zalo personal account. " +
-        "Actions: send (text message), image (send image URL), link (send link), " +
-        "friends (list/search friends), groups (list groups), me (profile info), status (auth check).",
-      parameters: ZalouserToolSchema,
-      execute: executeZalouserTool,
-    } as AnyAgentTool);
+  importMetaUrl: import.meta.url,
+  plugin: {
+    specifier: "./channel-plugin-api.js",
+    exportName: "zalouserPlugin",
   },
-};
-
-export default plugin;
+  runtime: {
+    specifier: "./runtime-api.js",
+    exportName: "setZalouserRuntime",
+  },
+  registerFull(api) {
+    api.registerTool((ctx) => createZalouserTool(ctx), { name: "zalouser" });
+  },
+});

package/openclaw.plugin.json

@@ -1,9 +1,296 @@
 {
   "id": "zalouser",
-  "channels": ["zalouser"],
+  "activation": {
+    "onStartup": false
+  },
+  "channels": [
+    "zalouser"
+  ],
+  "channelEnvVars": {
+    "zalouser": [
+      "ZALOUSER_PROFILE",
+      "ZCA_PROFILE"
+    ]
+  },
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
     "properties": {}
+  },
+  "channelConfigs": {
+    "zalouser": {
+      "schema": {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "enabled": {
+            "type": "boolean"
+          },
+          "markdown": {
+            "type": "object",
+            "properties": {
+              "tables": {
+                "type": "string",
+                "enum": [
+                  "off",
+                  "bullets",
+                  "code",
+                  "block"
+                ]
+              }
+            },
+            "additionalProperties": false
+          },
+          "profile": {
+            "type": "string"
+          },
+          "dangerouslyAllowNameMatching": {
+            "type": "boolean"
+          },
+          "dmPolicy": {
+            "type": "string",
+            "enum": [
+              "pairing",
+              "allowlist",
+              "open",
+              "disabled"
+            ]
+          },
+          "allowFrom": {
+            "type": "array",
+            "items": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "number"
+                }
+              ]
+            }
+          },
+          "historyLimit": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 9007199254740991
+          },
+          "groupAllowFrom": {
+            "type": "array",
+            "items": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "number"
+                }
+              ]
+            }
+          },
+          "groupPolicy": {
+            "default": "allowlist",
+            "type": "string",
+            "enum": [
+              "open",
+              "disabled",
+              "allowlist"
+            ]
+          },
+          "groups": {
+            "type": "object",
+            "properties": {},
+            "additionalProperties": {
+              "type": "object",
+              "properties": {
+                "enabled": {
+                  "type": "boolean"
+                },
+                "requireMention": {
+                  "type": "boolean"
+                },
+                "tools": {
+                  "type": "object",
+                  "properties": {
+                    "allow": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      }
+                    },
+                    "alsoAllow": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      }
+                    },
+                    "deny": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      }
+                    }
+                  },
+                  "additionalProperties": false
+                }
+              },
+              "additionalProperties": false
+            }
+          },
+          "messagePrefix": {
+            "type": "string"
+          },
+          "responsePrefix": {
+            "type": "string"
+          },
+          "accounts": {
+            "type": "object",
+            "properties": {},
+            "additionalProperties": {
+              "type": "object",
+              "properties": {
+                "name": {
+                  "type": "string"
+                },
+                "enabled": {
+                  "type": "boolean"
+                },
+                "markdown": {
+                  "type": "object",
+                  "properties": {
+                    "tables": {
+                      "type": "string",
+                      "enum": [
+                        "off",
+                        "bullets",
+                        "code",
+                        "block"
+                      ]
+                    }
+                  },
+                  "additionalProperties": false
+                },
+                "profile": {
+                  "type": "string"
+                },
+                "dangerouslyAllowNameMatching": {
+                  "type": "boolean"
+                },
+                "dmPolicy": {
+                  "type": "string",
+                  "enum": [
+                    "pairing",
+                    "allowlist",
+                    "open",
+                    "disabled"
+                  ]
+                },
+                "allowFrom": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "type": "number"
+                      }
+                    ]
+                  }
+                },
+                "historyLimit": {
+                  "type": "integer",
+                  "minimum": 0,
+                  "maximum": 9007199254740991
+                },
+                "groupAllowFrom": {
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "type": "number"
+                      }
+                    ]
+                  }
+                },
+                "groupPolicy": {
+                  "default": "allowlist",
+                  "type": "string",
+                  "enum": [
+                    "open",
+                    "disabled",
+                    "allowlist"
+                  ]
+                },
+                "groups": {
+                  "type": "object",
+                  "properties": {},
+                  "additionalProperties": {
+                    "type": "object",
+                    "properties": {
+                      "enabled": {
+                        "type": "boolean"
+                      },
+                      "requireMention": {
+                        "type": "boolean"
+                      },
+                      "tools": {
+                        "type": "object",
+                        "properties": {
+                          "allow": {
+                            "type": "array",
+                            "items": {
+                              "type": "string"
+                            }
+                          },
+                          "alsoAllow": {
+                            "type": "array",
+                            "items": {
+                              "type": "string"
+                            }
+                          },
+                          "deny": {
+                            "type": "array",
+                            "items": {
+                              "type": "string"
+                            }
+                          }
+                        },
+                        "additionalProperties": false
+                      }
+                    },
+                    "additionalProperties": false
+                  }
+                },
+                "messagePrefix": {
+                  "type": "string"
+                },
+                "responsePrefix": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "groupPolicy"
+              ],
+              "additionalProperties": false
+            }
+          },
+          "defaultAccount": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "groupPolicy"
+        ],
+        "additionalProperties": false
+      },
+      "label": "Zalo Personal",
+      "description": "Zalo personal account via QR code login."
+    }
   }
 }

package/package.json

@@ -1,17 +1,33 @@
 {
   "name": "@openclaw/zalouser",
-  "version": "2026.3.12",
+  "version": "2026.5.1-beta.2",
   "description": "OpenClaw Zalo Personal Account plugin via native zca-js integration",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/openclaw/openclaw"
+  },
   "type": "module",
   "dependencies": {
-    "@sinclair/typebox": "0.34.48",
-    "zca-js": "2.1.1",
-    "zod": "^4.3.6"
+    "typebox": "1.1.37",
+    "zca-js": "2.1.2"
+  },
+  "devDependencies": {
+    "@openclaw/plugin-sdk": "workspace:*",
+    "openclaw": "workspace:*"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.4.25"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": true
+    }
   },
   "openclaw": {
     "extensions": [
       "./index.ts"
     ],
+    "setupEntry": "./setup-entry.ts",
     "channel": {
       "id": "zalouser",
       "label": "Zalo Personal",
@@ -23,17 +39,28 @@
         "zlu"
       ],
       "order": 85,
-      "quickstartAllowFrom": true
+      "quickstartAllowFrom": false,
+      "doctorCapabilities": {
+        "dmAllowFromMode": "topOnly",
+        "groupModel": "hybrid",
+        "groupAllowFromFallbackToAllowFrom": false,
+        "warnOnEmptyGroupSenderAllowlist": false
+      }
     },
     "install": {
       "npmSpec": "@openclaw/zalouser",
-      "localPath": "extensions/zalouser",
-      "defaultChoice": "npm"
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.4.10"
+    },
+    "compat": {
+      "pluginApi": ">=2026.4.25"
+    },
+    "build": {
+      "openclawVersion": "2026.5.1-beta.2"
     },
-    "releaseChecks": {
-      "rootDependencyMirrorAllowlist": [
-        "zca-js"
-      ]
+    "release": {
+      "publishToClawHub": true,
+      "publishToNpm": true
     }
   }
 }

package/runtime-api.ts

@@ -0,0 +1,67 @@
+export {
+  collectZalouserSecurityAuditFindings,
+  createZalouserSetupWizardProxy,
+  createZalouserTool,
+  isZalouserMutableGroupEntry,
+  zalouserPlugin,
+  zalouserSetupAdapter,
+  zalouserSetupPlugin,
+  zalouserSetupWizard,
+} from "./api.js";
+export { setZalouserRuntime } from "./src/runtime.js";
+export type { ReplyPayload } from "openclaw/plugin-sdk/reply-runtime";
+export type {
+  BaseProbeResult,
+  ChannelAccountSnapshot,
+  ChannelDirectoryEntry,
+  ChannelGroupContext,
+  ChannelMessageActionAdapter,
+  ChannelStatusIssue,
+} from "openclaw/plugin-sdk/channel-contract";
+export type {
+  OpenClawConfig,
+  GroupToolPolicyConfig,
+  MarkdownTableMode,
+} from "openclaw/plugin-sdk/config-types";
+export type {
+  PluginRuntime,
+  AnyAgentTool,
+  ChannelPlugin,
+  OpenClawPluginToolContext,
+} from "openclaw/plugin-sdk/core";
+export type { RuntimeEnv } from "openclaw/plugin-sdk/runtime";
+export {
+  DEFAULT_ACCOUNT_ID,
+  buildChannelConfigSchema,
+  normalizeAccountId,
+} from "openclaw/plugin-sdk/core";
+export { chunkTextForOutbound } from "openclaw/plugin-sdk/text-chunking";
+export { isDangerousNameMatchingEnabled } from "openclaw/plugin-sdk/dangerous-name-runtime";
+export {
+  resolveDefaultGroupPolicy,
+  resolveOpenProviderRuntimeGroupPolicy,
+  warnMissingProviderGroupPolicyFallbackOnce,
+} from "openclaw/plugin-sdk/runtime-group-policy";
+export {
+  mergeAllowlist,
+  summarizeMapping,
+  formatAllowFromLowercase,
+} from "openclaw/plugin-sdk/allow-from";
+export { resolveInboundMentionDecision } from "openclaw/plugin-sdk/channel-inbound";
+export { createChannelPairingController } from "openclaw/plugin-sdk/channel-pairing";
+export { createChannelReplyPipeline } from "openclaw/plugin-sdk/channel-reply-pipeline";
+export { buildBaseAccountStatusSnapshot } from "openclaw/plugin-sdk/status-helpers";
+export { resolveSenderCommandAuthorization } from "openclaw/plugin-sdk/command-auth";
+export {
+  evaluateGroupRouteAccessForPolicy,
+  resolveSenderScopedGroupPolicy,
+} from "openclaw/plugin-sdk/group-access";
+export { loadOutboundMediaFromUrl } from "openclaw/plugin-sdk/outbound-media";
+export {
+  deliverTextOrMediaReply,
+  isNumericTargetId,
+  resolveSendableOutboundReplyParts,
+  sendPayloadWithChunkedTextAndMedia,
+  type OutboundReplyPayload,
+} from "openclaw/plugin-sdk/reply-payload";
+export { resolvePreferredOpenClawTmpDir } from "openclaw/plugin-sdk/temp-path";

package/secret-contract-api.ts

@@ -0,0 +1,4 @@
+// Zalo User does not expose secret-contract surfaces.
+export const secretTargetRegistryEntries: readonly [] = [];
+
+export function collectRuntimeConfigAssignments(): void {}

package/setup-entry.ts

@@ -0,0 +1,9 @@
+import { defineBundledChannelSetupEntry } from "openclaw/plugin-sdk/channel-entry-contract";
+
+export default defineBundledChannelSetupEntry({
+  importMetaUrl: import.meta.url,
+  plugin: {
+    specifier: "./setup-plugin-api.js",
+    exportName: "zalouserSetupPlugin",
+  },
+});

package/setup-plugin-api.ts

@@ -0,0 +1,2 @@
+// Keep setup-entry imports narrow so setup loads do not pull tool surfaces.
+export { zalouserSetupPlugin } from "./src/channel.setup.js";

package/src/accounts.runtime.ts

@@ -0,0 +1 @@
+export { checkZaloAuthenticated, getZaloUserInfo } from "./zalo-js.js";

package/src/accounts.test-mocks.ts

@@ -0,0 +1,14 @@
+import { vi } from "vitest";
+import { createDefaultResolvedZalouserAccount } from "./test-helpers.js";
+
+vi.mock("./accounts.js", () => {
+  return {
+    listZalouserAccountIds: () => ["default"],
+    resolveDefaultZalouserAccountId: () => "default",
+    resolveZalouserAccountSync: () => createDefaultResolvedZalouserAccount(),
+    resolveZalouserAccount: async () => createDefaultResolvedZalouserAccount(),
+    listEnabledZalouserAccounts: async () => [createDefaultResolvedZalouserAccount()],
+    getZcaUserInfo: async () => null,
+    checkZcaAuthenticated: async () => false,
+  };
+});

package/src/accounts.test.ts

@@ -1,6 +1,6 @@
 import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/account-id";
-import type { OpenClawConfig } from "openclaw/plugin-sdk/zalouser";
 import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { OpenClawConfig } from "../runtime-api.js";
 import {
   getZcaUserInfo,
   listEnabledZalouserAccounts,
@@ -124,6 +124,58 @@ describe("zalouser account resolution", () => {
     expect(resolved.config.allowFrom).toEqual(["123"]);
   });
 
+  it("uses configured defaultAccount when accountId is omitted", () => {
+    const cfg = asConfig({
+      channels: {
+        zalouser: {
+          defaultAccount: "work",
+          accounts: {
+            work: {
+              name: "Work",
+              profile: "work-profile",
+            },
+          },
+        },
+      },
+    });
+
+    const resolved = resolveZalouserAccountSync({ cfg });
+    expect(resolved.accountId).toBe("work");
+    expect(resolved.name).toBe("Work");
+    expect(resolved.profile).toBe("work-profile");
+  });
+
+  it("resolves account config when account key casing differs from normalized id", () => {
+    const cfg = asConfig({
+      channels: {
+        zalouser: {
+          accounts: {
+            Work: {
+              name: "Work",
+            },
+          },
+        },
+      },
+    });
+
+    const resolved = resolveZalouserAccountSync({ cfg, accountId: "work" });
+    expect(resolved.accountId).toBe("work");
+    expect(resolved.name).toBe("Work");
+  });
+
+  it("defaults group policy to allowlist when unset", () => {
+    const cfg = asConfig({
+      channels: {
+        zalouser: {
+          enabled: true,
+        },
+      },
+    });
+
+    const resolved = resolveZalouserAccountSync({ cfg, accountId: "default" });
+    expect(resolved.config.groupPolicy).toBe("allowlist");
+  });
+
   it("resolves profile precedence correctly", () => {
     const cfg = asConfig({
       channels: {