@openclaw/zalo 2026.3.1 → 2026.3.2

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 2026.3.2
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
 ## 2026.3.1
 
 ### Changes

package/index.ts

@@ -1,7 +1,6 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
 import { zaloDock, zaloPlugin } from "./src/channel.js";
-import { handleZaloWebhookRequest } from "./src/monitor.js";
 import { setZaloRuntime } from "./src/runtime.js";
 
 const plugin = {
@@ -12,7 +11,6 @@ const plugin = {
   register(api: OpenClawPluginApi) {
     setZaloRuntime(api.runtime);
     api.registerChannel({ plugin: zaloPlugin, dock: zaloDock });
-    api.registerHttpHandler(handleZaloWebhookRequest);
   },
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/zalo",
-  "version": "2026.3.1",
+  "version": "2026.3.2",
   "description": "OpenClaw Zalo channel plugin",
   "type": "module",
   "dependencies": {

package/src/accounts.ts

@@ -62,6 +62,7 @@ function mergeZaloAccountConfig(cfg: OpenClawConfig, accountId: string): ZaloAcc
 export function resolveZaloAccount(params: {
   cfg: OpenClawConfig;
   accountId?: string | null;
+  allowUnresolvedSecretRef?: boolean;
 }): ResolvedZaloAccount {
   const accountId = normalizeAccountId(params.accountId);
   const baseEnabled = (params.cfg.channels?.zalo as ZaloConfig | undefined)?.enabled !== false;
@@ -71,6 +72,7 @@ export function resolveZaloAccount(params: {
   const tokenResolution = resolveZaloToken(
     params.cfg.channels?.zalo as ZaloConfig | undefined,
     accountId,
+    { allowUnresolvedSecretRef: params.allowUnresolvedSecretRef },
   );
 
   return {

package/src/channel.sendpayload.test.ts

@@ -0,0 +1,102 @@
+import type { ReplyPayload } from "openclaw/plugin-sdk";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { zaloPlugin } from "./channel.js";
+
+vi.mock("./send.js", () => ({
+  sendMessageZalo: vi.fn().mockResolvedValue({ ok: true, messageId: "zl-1" }),
+}));
+
+function baseCtx(payload: ReplyPayload) {
+  return {
+    cfg: {},
+    to: "123456789",
+    text: "",
+    payload,
+  };
+}
+
+describe("zaloPlugin outbound sendPayload", () => {
+  let mockedSend: ReturnType<typeof vi.mocked<(typeof import("./send.js"))["sendMessageZalo"]>>;
+
+  beforeEach(async () => {
+    const mod = await import("./send.js");
+    mockedSend = vi.mocked(mod.sendMessageZalo);
+    mockedSend.mockClear();
+    mockedSend.mockResolvedValue({ ok: true, messageId: "zl-1" });
+  });
+
+  it("text-only delegates to sendText", async () => {
+    mockedSend.mockResolvedValue({ ok: true, messageId: "zl-t1" });
+
+    const result = await zaloPlugin.outbound!.sendPayload!(baseCtx({ text: "hello" }));
+
+    expect(mockedSend).toHaveBeenCalledWith("123456789", "hello", expect.any(Object));
+    expect(result).toMatchObject({ channel: "zalo", messageId: "zl-t1" });
+  });
+
+  it("single media delegates to sendMedia", async () => {
+    mockedSend.mockResolvedValue({ ok: true, messageId: "zl-m1" });
+
+    const result = await zaloPlugin.outbound!.sendPayload!(
+      baseCtx({ text: "cap", mediaUrl: "https://example.com/a.jpg" }),
+    );
+
+    expect(mockedSend).toHaveBeenCalledWith(
+      "123456789",
+      "cap",
+      expect.objectContaining({ mediaUrl: "https://example.com/a.jpg" }),
+    );
+    expect(result).toMatchObject({ channel: "zalo" });
+  });
+
+  it("multi-media iterates URLs with caption on first", async () => {
+    mockedSend
+      .mockResolvedValueOnce({ ok: true, messageId: "zl-1" })
+      .mockResolvedValueOnce({ ok: true, messageId: "zl-2" });
+
+    const result = await zaloPlugin.outbound!.sendPayload!(
+      baseCtx({
+        text: "caption",
+        mediaUrls: ["https://example.com/1.jpg", "https://example.com/2.jpg"],
+      }),
+    );
+
+    expect(mockedSend).toHaveBeenCalledTimes(2);
+    expect(mockedSend).toHaveBeenNthCalledWith(
+      1,
+      "123456789",
+      "caption",
+      expect.objectContaining({ mediaUrl: "https://example.com/1.jpg" }),
+    );
+    expect(mockedSend).toHaveBeenNthCalledWith(
+      2,
+      "123456789",
+      "",
+      expect.objectContaining({ mediaUrl: "https://example.com/2.jpg" }),
+    );
+    expect(result).toMatchObject({ channel: "zalo", messageId: "zl-2" });
+  });
+
+  it("empty payload returns no-op", async () => {
+    const result = await zaloPlugin.outbound!.sendPayload!(baseCtx({}));
+
+    expect(mockedSend).not.toHaveBeenCalled();
+    expect(result).toEqual({ channel: "zalo", messageId: "" });
+  });
+
+  it("chunking splits long text", async () => {
+    mockedSend
+      .mockResolvedValueOnce({ ok: true, messageId: "zl-c1" })
+      .mockResolvedValueOnce({ ok: true, messageId: "zl-c2" });
+
+    const longText = "a".repeat(3000);
+    const result = await zaloPlugin.outbound!.sendPayload!(baseCtx({ text: longText }));
+
+    // textChunkLimit is 2000 with chunkTextForOutbound, so it should split
+    expect(mockedSend.mock.calls.length).toBeGreaterThanOrEqual(2);
+    for (const call of mockedSend.mock.calls) {
+      expect((call[1] as string).length).toBeLessThanOrEqual(2000);
+    }
+    expect(result).toMatchObject({ channel: "zalo" });
+  });
+});

package/src/channel.ts

@@ -32,6 +32,7 @@ import { ZaloConfigSchema } from "./config-schema.js";
 import { zaloOnboardingAdapter } from "./onboarding.js";
 import { probeZalo } from "./probe.js";
 import { resolveZaloProxyFetch } from "./proxy.js";
+import { normalizeSecretInputString } from "./secret-input.js";
 import { sendMessageZalo } from "./send.js";
 import { collectZaloStatusIssues } from "./status-issues.js";
 
@@ -302,6 +303,40 @@ export const zaloPlugin: ChannelPlugin<ResolvedZaloAccount> = {
     chunker: chunkTextForOutbound,
     chunkerMode: "text",
     textChunkLimit: 2000,
+    sendPayload: async (ctx) => {
+      const text = ctx.payload.text ?? "";
+      const urls = ctx.payload.mediaUrls?.length
+        ? ctx.payload.mediaUrls
+        : ctx.payload.mediaUrl
+          ? [ctx.payload.mediaUrl]
+          : [];
+      if (!text && urls.length === 0) {
+        return { channel: "zalo", messageId: "" };
+      }
+      if (urls.length > 0) {
+        let lastResult = await zaloPlugin.outbound!.sendMedia!({
+          ...ctx,
+          text,
+          mediaUrl: urls[0],
+        });
+        for (let i = 1; i < urls.length; i++) {
+          lastResult = await zaloPlugin.outbound!.sendMedia!({
+            ...ctx,
+            text: "",
+            mediaUrl: urls[i],
+          });
+        }
+        return lastResult;
+      }
+      const outbound = zaloPlugin.outbound!;
+      const limit = outbound.textChunkLimit;
+      const chunks = limit && outbound.chunker ? outbound.chunker(text, limit) : [text];
+      let lastResult: Awaited<ReturnType<NonNullable<typeof outbound.sendText>>>;
+      for (const chunk of chunks) {
+        lastResult = await outbound.sendText!({ ...ctx, text: chunk });
+      }
+      return lastResult!;
+    },
     sendText: async ({ to, text, accountId, cfg }) => {
       const result = await sendMessageZalo(to, text, {
         accountId: accountId ?? undefined,
@@ -388,7 +423,7 @@ export const zaloPlugin: ChannelPlugin<ResolvedZaloAccount> = {
         abortSignal: ctx.abortSignal,
         useWebhook: Boolean(account.config.webhookUrl),
         webhookUrl: account.config.webhookUrl,
-        webhookSecret: account.config.webhookSecret,
+        webhookSecret: normalizeSecretInputString(account.config.webhookSecret),
         webhookPath: account.config.webhookPath,
         fetcher,
         statusSink: (patch) => ctx.setStatus({ accountId: ctx.accountId, ...patch }),

package/src/config-schema.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest";
+import { ZaloConfigSchema } from "./config-schema.js";
+
+describe("ZaloConfigSchema SecretInput", () => {
+  it("accepts SecretRef botToken and webhookSecret at top-level", () => {
+    const result = ZaloConfigSchema.safeParse({
+      botToken: { source: "env", provider: "default", id: "ZALO_BOT_TOKEN" },
+      webhookUrl: "https://example.com/zalo",
+      webhookSecret: { source: "env", provider: "default", id: "ZALO_WEBHOOK_SECRET" },
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it("accepts SecretRef botToken and webhookSecret on account", () => {
+    const result = ZaloConfigSchema.safeParse({
+      accounts: {
+        work: {
+          botToken: { source: "env", provider: "default", id: "ZALO_WORK_BOT_TOKEN" },
+          webhookUrl: "https://example.com/zalo/work",
+          webhookSecret: {
+            source: "env",
+            provider: "default",
+            id: "ZALO_WORK_WEBHOOK_SECRET",
+          },
+        },
+      },
+    });
+    expect(result.success).toBe(true);
+  });
+});

package/src/config-schema.ts

@@ -1,5 +1,6 @@
 import { MarkdownConfigSchema } from "openclaw/plugin-sdk";
 import { z } from "zod";
+import { buildSecretInputSchema } from "./secret-input.js";
 
 const allowFromEntry = z.union([z.string(), z.number()]);
 
@@ -7,10 +8,10 @@ const zaloAccountSchema = z.object({
   name: z.string().optional(),
   enabled: z.boolean().optional(),
   markdown: MarkdownConfigSchema,
-  botToken: z.string().optional(),
+  botToken: buildSecretInputSchema().optional(),
   tokenFile: z.string().optional(),
   webhookUrl: z.string().optional(),
-  webhookSecret: z.string().optional(),
+  webhookSecret: buildSecretInputSchema().optional(),
   webhookPath: z.string().optional(),
   dmPolicy: z.enum(["pairing", "allowlist", "open", "disabled"]).optional(),
   allowFrom: z.array(allowFromEntry).optional(),

package/src/monitor.ts

@@ -3,9 +3,11 @@ import type { MarkdownTableMode, OpenClawConfig, OutboundReplyPayload } from "op
 import {
   createScopedPairingAccess,
   createReplyPrefixOptions,
-  resolveSenderCommandAuthorization,
+  resolveDirectDmAuthorizationOutcome,
+  resolveSenderCommandAuthorizationWithRuntime,
   resolveOutboundMediaUrls,
   resolveDefaultGroupPolicy,
+  resolveInboundRouteEnvelopeBuilderWithRuntime,
   sendMediaWithLeadingCaption,
   resolveWebhookPath,
   warnMissingProviderGroupPolicyFallbackOnce,
@@ -73,7 +75,24 @@ function logVerbose(core: ZaloCoreRuntime, runtime: ZaloRuntimeEnv, message: str
 }
 
 export function registerZaloWebhookTarget(target: ZaloWebhookTarget): () => void {
-  return registerZaloWebhookTargetInternal(target);
+  return registerZaloWebhookTargetInternal(target, {
+    route: {
+      auth: "plugin",
+      match: "exact",
+      pluginId: "zalo",
+      source: "zalo-webhook",
+      accountId: target.account.accountId,
+      log: target.runtime.log,
+      handler: async (req, res) => {
+        const handled = await handleZaloWebhookRequest(req, res);
+        if (!handled && !res.headersSent) {
+          res.statusCode = 404;
+          res.setHeader("Content-Type", "text/plain; charset=utf-8");
+          res.end("Not Found");
+        }
+      },
+    },
+  });
 }
 
 export {
@@ -366,82 +385,76 @@ async function processMessageWithPipeline(params: {
   }
 
   const rawBody = text?.trim() || (mediaPath ? "<media:image>" : "");
-  const { senderAllowedForCommands, commandAuthorized } = await resolveSenderCommandAuthorization({
-    cfg: config,
-    rawBody,
+  const { senderAllowedForCommands, commandAuthorized } =
+    await resolveSenderCommandAuthorizationWithRuntime({
+      cfg: config,
+      rawBody,
+      isGroup,
+      dmPolicy,
+      configuredAllowFrom: configAllowFrom,
+      configuredGroupAllowFrom: groupAllowFrom,
+      senderId,
+      isSenderAllowed: isZaloSenderAllowed,
+      readAllowFromStore: pairing.readAllowFromStore,
+      runtime: core.channel.commands,
+    });
+
+  const directDmOutcome = resolveDirectDmAuthorizationOutcome({
     isGroup,
     dmPolicy,
-    configuredAllowFrom: configAllowFrom,
-    configuredGroupAllowFrom: groupAllowFrom,
-    senderId,
-    isSenderAllowed: isZaloSenderAllowed,
-    readAllowFromStore: pairing.readAllowFromStore,
-    shouldComputeCommandAuthorized: (body, cfg) =>
-      core.channel.commands.shouldComputeCommandAuthorized(body, cfg),
-    resolveCommandAuthorizedFromAuthorizers: (params) =>
-      core.channel.commands.resolveCommandAuthorizedFromAuthorizers(params),
+    senderAllowedForCommands,
   });
-
-  if (!isGroup) {
-    if (dmPolicy === "disabled") {
-      logVerbose(core, runtime, `Blocked zalo DM from ${senderId} (dmPolicy=disabled)`);
-      return;
-    }
-
-    if (dmPolicy !== "open") {
-      const allowed = senderAllowedForCommands;
-
-      if (!allowed) {
-        if (dmPolicy === "pairing") {
-          const { code, created } = await pairing.upsertPairingRequest({
-            id: senderId,
-            meta: { name: senderName ?? undefined },
-          });
-
-          if (created) {
-            logVerbose(core, runtime, `zalo pairing request sender=${senderId}`);
-            try {
-              await sendMessage(
-                token,
-                {
-                  chat_id: chatId,
-                  text: core.channel.pairing.buildPairingReply({
-                    channel: "zalo",
-                    idLine: `Your Zalo user id: ${senderId}`,
-                    code,
-                  }),
-                },
-                fetcher,
-              );
-              statusSink?.({ lastOutboundAt: Date.now() });
-            } catch (err) {
-              logVerbose(
-                core,
-                runtime,
-                `zalo pairing reply failed for ${senderId}: ${String(err)}`,
-              );
-            }
-          }
-        } else {
-          logVerbose(
-            core,
-            runtime,
-            `Blocked unauthorized zalo sender ${senderId} (dmPolicy=${dmPolicy})`,
+  if (directDmOutcome === "disabled") {
+    logVerbose(core, runtime, `Blocked zalo DM from ${senderId} (dmPolicy=disabled)`);
+    return;
+  }
+  if (directDmOutcome === "unauthorized") {
+    if (dmPolicy === "pairing") {
+      const { code, created } = await pairing.upsertPairingRequest({
+        id: senderId,
+        meta: { name: senderName ?? undefined },
+      });
+
+      if (created) {
+        logVerbose(core, runtime, `zalo pairing request sender=${senderId}`);
+        try {
+          await sendMessage(
+            token,
+            {
+              chat_id: chatId,
+              text: core.channel.pairing.buildPairingReply({
+                channel: "zalo",
+                idLine: `Your Zalo user id: ${senderId}`,
+                code,
+              }),
+            },
+            fetcher,
           );
+          statusSink?.({ lastOutboundAt: Date.now() });
+        } catch (err) {
+          logVerbose(core, runtime, `zalo pairing reply failed for ${senderId}: ${String(err)}`);
         }
-        return;
       }
+    } else {
+      logVerbose(
+        core,
+        runtime,
+        `Blocked unauthorized zalo sender ${senderId} (dmPolicy=${dmPolicy})`,
+      );
     }
+    return;
   }
 
-  const route = core.channel.routing.resolveAgentRoute({
+  const { route, buildEnvelope } = resolveInboundRouteEnvelopeBuilderWithRuntime({
     cfg: config,
     channel: "zalo",
     accountId: account.accountId,
     peer: {
-      kind: isGroup ? "group" : "direct",
+      kind: isGroup ? ("group" as const) : ("direct" as const),
       id: chatId,
     },
+    runtime: core.channel,
+    sessionStore: config.session?.store,
   });
 
   if (
@@ -454,20 +467,10 @@ async function processMessageWithPipeline(params: {
   }
 
   const fromLabel = isGroup ? `group:${chatId}` : senderName || `user:${senderId}`;
-  const storePath = core.channel.session.resolveStorePath(config.session?.store, {
-    agentId: route.agentId,
-  });
-  const envelopeOptions = core.channel.reply.resolveEnvelopeFormatOptions(config);
-  const previousTimestamp = core.channel.session.readSessionUpdatedAt({
-    storePath,
-    sessionKey: route.sessionKey,
-  });
-  const body = core.channel.reply.formatAgentEnvelope({
+  const { storePath, body } = buildEnvelope({
     channel: "Zalo",
     from: fromLabel,
     timestamp: date ? date * 1000 : undefined,
-    previousTimestamp,
-    envelope: envelopeOptions,
     body: rawBody,
   });
 

package/src/monitor.webhook.test.ts

@@ -2,6 +2,8 @@ import { createServer, type RequestListener } from "node:http";
 import type { AddressInfo } from "node:net";
 import type { OpenClawConfig, PluginRuntime } from "openclaw/plugin-sdk";
 import { afterEach, describe, expect, it, vi } from "vitest";
+import { createEmptyPluginRegistry } from "../../../src/plugins/registry.js";
+import { setActivePluginRegistry } from "../../../src/plugins/runtime.js";
 import {
   clearZaloWebhookSecurityStateForTest,
   getZaloWebhookRateLimitStateSizeForTest,
@@ -47,13 +49,16 @@ function registerTarget(params: {
   path: string;
   secret?: string;
   statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
+  account?: ResolvedZaloAccount;
+  config?: OpenClawConfig;
+  core?: PluginRuntime;
 }): () => void {
   return registerZaloWebhookTarget({
     token: "tok",
-    account: DEFAULT_ACCOUNT,
-    config: {} as OpenClawConfig,
+    account: params.account ?? DEFAULT_ACCOUNT,
+    config: params.config ?? ({} as OpenClawConfig),
     runtime: {},
-    core: {} as PluginRuntime,
+    core: params.core ?? ({} as PluginRuntime),
     secret: params.secret ?? "secret",
     path: params.path,
     mediaMaxMb: 5,
@@ -61,9 +66,59 @@ function registerTarget(params: {
   });
 }
 
+function createPairingAuthCore(params?: { storeAllowFrom?: string[]; pairingCreated?: boolean }): {
+  core: PluginRuntime;
+  readAllowFromStore: ReturnType<typeof vi.fn>;
+  upsertPairingRequest: ReturnType<typeof vi.fn>;
+} {
+  const readAllowFromStore = vi.fn().mockResolvedValue(params?.storeAllowFrom ?? []);
+  const upsertPairingRequest = vi
+    .fn()
+    .mockResolvedValue({ code: "PAIRCODE", created: params?.pairingCreated ?? false });
+  const core = {
+    logging: {
+      shouldLogVerbose: () => false,
+    },
+    channel: {
+      pairing: {
+        readAllowFromStore,
+        upsertPairingRequest,
+        buildPairingReply: vi.fn(() => "Pairing code: PAIRCODE"),
+      },
+      commands: {
+        shouldComputeCommandAuthorized: vi.fn(() => false),
+        resolveCommandAuthorizedFromAuthorizers: vi.fn(() => false),
+      },
+    },
+  } as unknown as PluginRuntime;
+  return { core, readAllowFromStore, upsertPairingRequest };
+}
+
 describe("handleZaloWebhookRequest", () => {
   afterEach(() => {
     clearZaloWebhookSecurityStateForTest();
+    setActivePluginRegistry(createEmptyPluginRegistry());
+  });
+
+  it("registers and unregisters plugin HTTP route at path boundaries", () => {
+    const registry = createEmptyPluginRegistry();
+    setActivePluginRegistry(registry);
+    const unregisterA = registerTarget({ path: "/hook" });
+    const unregisterB = registerTarget({ path: "/hook" });
+
+    expect(registry.httpRoutes).toHaveLength(1);
+    expect(registry.httpRoutes[0]).toEqual(
+      expect.objectContaining({
+        pluginId: "zalo",
+        path: "/hook",
+        source: "zalo-webhook",
+      }),
+    );
+
+    unregisterA();
+    expect(registry.httpRoutes).toHaveLength(1);
+    unregisterB();
+    expect(registry.httpRoutes).toHaveLength(0);
   });
 
   it("returns 400 for non-object payloads", async () => {
@@ -206,7 +261,6 @@ describe("handleZaloWebhookRequest", () => {
       unregister();
     }
   });
-
   it("does not grow status counters when query strings churn on unauthorized requests", async () => {
     const unregister = registerTarget({ path: "/hook-query-status" });
 
@@ -259,4 +313,65 @@ describe("handleZaloWebhookRequest", () => {
       unregister();
     }
   });
+
+  it("scopes DM pairing store reads and writes to accountId", async () => {
+    const { core, readAllowFromStore, upsertPairingRequest } = createPairingAuthCore({
+      pairingCreated: false,
+    });
+    const account: ResolvedZaloAccount = {
+      ...DEFAULT_ACCOUNT,
+      accountId: "work",
+      config: {
+        dmPolicy: "pairing",
+        allowFrom: [],
+      },
+    };
+    const unregister = registerTarget({
+      path: "/hook-account-scope",
+      account,
+      core,
+    });
+
+    const payload = {
+      event_name: "message.text.received",
+      message: {
+        from: { id: "123", name: "Attacker" },
+        chat: { id: "dm-work", chat_type: "PRIVATE" },
+        message_id: "msg-work-1",
+        date: Math.floor(Date.now() / 1000),
+        text: "hello",
+      },
+    };
+
+    try {
+      await withServer(webhookRequestHandler, async (baseUrl) => {
+        const response = await fetch(`${baseUrl}/hook-account-scope`, {
+          method: "POST",
+          headers: {
+            "x-bot-api-secret-token": "secret",
+            "content-type": "application/json",
+          },
+          body: JSON.stringify(payload),
+        });
+
+        expect(response.status).toBe(200);
+      });
+    } finally {
+      unregister();
+    }
+
+    expect(readAllowFromStore).toHaveBeenCalledWith(
+      expect.objectContaining({
+        channel: "zalo",
+        accountId: "work",
+      }),
+    );
+    expect(upsertPairingRequest).toHaveBeenCalledWith(
+      expect.objectContaining({
+        channel: "zalo",
+        id: "123",
+        accountId: "work",
+      }),
+    );
+  });
 });

package/src/monitor.webhook.ts

@@ -7,6 +7,9 @@ import {
   createWebhookAnomalyTracker,
   readJsonWebhookBodyOrReject,
   applyBasicWebhookRequestGuards,
+  registerWebhookTargetWithPluginRoute,
+  type RegisterWebhookTargetOptions,
+  type RegisterWebhookPluginRouteOptions,
   registerWebhookTarget,
   resolveSingleWebhookTarget,
   resolveWebhookTargets,
@@ -106,8 +109,24 @@ function recordWebhookStatus(
   });
 }
 
-export function registerZaloWebhookTarget(target: ZaloWebhookTarget): () => void {
-  return registerWebhookTarget(webhookTargets, target).unregister;
+export function registerZaloWebhookTarget(
+  target: ZaloWebhookTarget,
+  opts?: {
+    route?: RegisterWebhookPluginRouteOptions;
+  } & Pick<
+    RegisterWebhookTargetOptions<ZaloWebhookTarget>,
+    "onFirstPathTarget" | "onLastPathTargetRemoved"
+  >,
+): () => void {
+  if (opts?.route) {
+    return registerWebhookTargetWithPluginRoute({
+      targetsByPath: webhookTargets,
+      target,
+      route: opts.route,
+      onLastPathTargetRemoved: opts.onLastPathTargetRemoved,
+    }).unregister;
+  }
+  return registerWebhookTarget(webhookTargets, target, opts).unregister;
 }
 
 export async function handleZaloWebhookRequest(

package/src/onboarding.status.test.ts

@@ -0,0 +1,24 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import { describe, expect, it } from "vitest";
+import { zaloOnboardingAdapter } from "./onboarding.js";
+
+describe("zalo onboarding status", () => {
+  it("treats SecretRef botToken as configured", async () => {
+    const status = await zaloOnboardingAdapter.getStatus({
+      cfg: {
+        channels: {
+          zalo: {
+            botToken: {
+              source: "env",
+              provider: "default",
+              id: "ZALO_BOT_TOKEN",
+            },
+          },
+        },
+      } as OpenClawConfig,
+      accountOverrides: {},
+    });
+
+    expect(status.configured).toBe(true);
+  });
+});

package/src/onboarding.ts

@@ -2,14 +2,17 @@ import type {
   ChannelOnboardingAdapter,
   ChannelOnboardingDmPolicy,
   OpenClawConfig,
+  SecretInput,
   WizardPrompter,
 } from "openclaw/plugin-sdk";
 import {
   addWildcardAllowFrom,
   DEFAULT_ACCOUNT_ID,
+  hasConfiguredSecretInput,
   mergeAllowFromEntries,
   normalizeAccountId,
   promptAccountId,
+  promptSingleChannelSecretInput,
 } from "openclaw/plugin-sdk";
 import { listZaloAccountIds, resolveDefaultZaloAccountId, resolveZaloAccount } from "./accounts.js";
 
@@ -41,7 +44,7 @@ function setZaloUpdateMode(
   accountId: string,
   mode: UpdateMode,
   webhookUrl?: string,
-  webhookSecret?: string,
+  webhookSecret?: SecretInput,
   webhookPath?: string,
 ): OpenClawConfig {
   const isDefault = accountId === DEFAULT_ACCOUNT_ID;
@@ -210,9 +213,18 @@ export const zaloOnboardingAdapter: ChannelOnboardingAdapter = {
   channel,
   dmPolicy,
   getStatus: async ({ cfg }) => {
-    const configured = listZaloAccountIds(cfg).some((accountId) =>
-      Boolean(resolveZaloAccount({ cfg: cfg, accountId }).token),
-    );
+    const configured = listZaloAccountIds(cfg).some((accountId) => {
+      const account = resolveZaloAccount({
+        cfg: cfg,
+        accountId,
+        allowUnresolvedSecretRef: true,
+      });
+      return (
+        Boolean(account.token) ||
+        hasConfiguredSecretInput(account.config.botToken) ||
+        Boolean(account.config.tokenFile?.trim())
+      );
+    });
     return {
       channel,
       configured,
@@ -243,62 +255,49 @@ export const zaloOnboardingAdapter: ChannelOnboardingAdapter = {
     }
 
     let next = cfg;
-    const resolvedAccount = resolveZaloAccount({ cfg: next, accountId: zaloAccountId });
+    const resolvedAccount = resolveZaloAccount({
+      cfg: next,
+      accountId: zaloAccountId,
+      allowUnresolvedSecretRef: true,
+    });
     const accountConfigured = Boolean(resolvedAccount.token);
     const allowEnv = zaloAccountId === DEFAULT_ACCOUNT_ID;
     const canUseEnv = allowEnv && Boolean(process.env.ZALO_BOT_TOKEN?.trim());
     const hasConfigToken = Boolean(
-      resolvedAccount.config.botToken || resolvedAccount.config.tokenFile,
+      hasConfiguredSecretInput(resolvedAccount.config.botToken) || resolvedAccount.config.tokenFile,
     );
 
-    let token: string | null = null;
+    let token: SecretInput | null = null;
     if (!accountConfigured) {
       await noteZaloTokenHelp(prompter);
     }
-    if (canUseEnv && !resolvedAccount.config.botToken) {
-      const keepEnv = await prompter.confirm({
-        message: "ZALO_BOT_TOKEN detected. Use env var?",
-        initialValue: true,
-      });
-      if (keepEnv) {
-        next = {
-          ...next,
-          channels: {
-            ...next.channels,
-            zalo: {
-              ...next.channels?.zalo,
-              enabled: true,
-            },
+    const tokenResult = await promptSingleChannelSecretInput({
+      cfg: next,
+      prompter,
+      providerHint: "zalo",
+      credentialLabel: "bot token",
+      accountConfigured,
+      canUseEnv: canUseEnv && !hasConfigToken,
+      hasConfigToken,
+      envPrompt: "ZALO_BOT_TOKEN detected. Use env var?",
+      keepPrompt: "Zalo token already configured. Keep it?",
+      inputPrompt: "Enter Zalo bot token",
+      preferredEnvVar: "ZALO_BOT_TOKEN",
+    });
+    if (tokenResult.action === "set") {
+      token = tokenResult.value;
+    }
+    if (tokenResult.action === "use-env" && zaloAccountId === DEFAULT_ACCOUNT_ID) {
+      next = {
+        ...next,
+        channels: {
+          ...next.channels,
+          zalo: {
+            ...next.channels?.zalo,
+            enabled: true,
           },
-        } as OpenClawConfig;
-      } else {
-        token = String(
-          await prompter.text({
-            message: "Enter Zalo bot token",
-            validate: (value) => (value?.trim() ? undefined : "Required"),
-          }),
-        ).trim();
-      }
-    } else if (hasConfigToken) {
-      const keep = await prompter.confirm({
-        message: "Zalo token already configured. Keep it?",
-        initialValue: true,
-      });
-      if (!keep) {
-        token = String(
-          await prompter.text({
-            message: "Enter Zalo bot token",
-            validate: (value) => (value?.trim() ? undefined : "Required"),
-          }),
-        ).trim();
-      }
-    } else {
-      token = String(
-        await prompter.text({
-          message: "Enter Zalo bot token",
-          validate: (value) => (value?.trim() ? undefined : "Required"),
-        }),
-      ).trim();
+        },
+      } as OpenClawConfig;
     }
 
     if (token) {
@@ -338,12 +337,13 @@ export const zaloOnboardingAdapter: ChannelOnboardingAdapter = {
 
     const wantsWebhook = await prompter.confirm({
       message: "Use webhook mode for Zalo?",
-      initialValue: false,
+      initialValue: Boolean(resolvedAccount.config.webhookUrl),
     });
     if (wantsWebhook) {
       const webhookUrl = String(
         await prompter.text({
           message: "Webhook URL (https://...) ",
+          initialValue: resolvedAccount.config.webhookUrl,
           validate: (value) =>
             value?.trim()?.startsWith("https://") ? undefined : "HTTPS URL required",
         }),
@@ -355,22 +355,47 @@ export const zaloOnboardingAdapter: ChannelOnboardingAdapter = {
           return "/zalo-webhook";
         }
       })();
-      const webhookSecret = String(
-        await prompter.text({
-          message: "Webhook secret (8-256 chars)",
-          validate: (value) => {
-            const raw = String(value ?? "");
-            if (raw.length < 8 || raw.length > 256) {
-              return "8-256 chars";
-            }
-            return undefined;
-          },
-        }),
-      ).trim();
+      let webhookSecretResult = await promptSingleChannelSecretInput({
+        cfg: next,
+        prompter,
+        providerHint: "zalo-webhook",
+        credentialLabel: "webhook secret",
+        accountConfigured: hasConfiguredSecretInput(resolvedAccount.config.webhookSecret),
+        canUseEnv: false,
+        hasConfigToken: hasConfiguredSecretInput(resolvedAccount.config.webhookSecret),
+        envPrompt: "",
+        keepPrompt: "Zalo webhook secret already configured. Keep it?",
+        inputPrompt: "Webhook secret (8-256 chars)",
+        preferredEnvVar: "ZALO_WEBHOOK_SECRET",
+      });
+      while (
+        webhookSecretResult.action === "set" &&
+        typeof webhookSecretResult.value === "string" &&
+        (webhookSecretResult.value.length < 8 || webhookSecretResult.value.length > 256)
+      ) {
+        await prompter.note("Webhook secret must be between 8 and 256 characters.", "Zalo webhook");
+        webhookSecretResult = await promptSingleChannelSecretInput({
+          cfg: next,
+          prompter,
+          providerHint: "zalo-webhook",
+          credentialLabel: "webhook secret",
+          accountConfigured: false,
+          canUseEnv: false,
+          hasConfigToken: false,
+          envPrompt: "",
+          keepPrompt: "Zalo webhook secret already configured. Keep it?",
+          inputPrompt: "Webhook secret (8-256 chars)",
+          preferredEnvVar: "ZALO_WEBHOOK_SECRET",
+        });
+      }
+      const webhookSecret =
+        webhookSecretResult.action === "set"
+          ? webhookSecretResult.value
+          : resolvedAccount.config.webhookSecret;
       const webhookPath = String(
         await prompter.text({
           message: "Webhook path (optional)",
-          initialValue: defaultPath,
+          initialValue: resolvedAccount.config.webhookPath ?? defaultPath,
         }),
       ).trim();
       next = setZaloUpdateMode(

package/src/secret-input.ts

@@ -0,0 +1,19 @@
+import {
+  hasConfiguredSecretInput,
+  normalizeResolvedSecretInputString,
+  normalizeSecretInputString,
+} from "openclaw/plugin-sdk";
+import { z } from "zod";
+
+export { hasConfiguredSecretInput, normalizeResolvedSecretInputString, normalizeSecretInputString };
+
+export function buildSecretInputSchema() {
+  return z.union([
+    z.string(),
+    z.object({
+      source: z.enum(["env", "file", "exec"]),
+      provider: z.string().min(1),
+      id: z.string().min(1),
+    }),
+  ]);
+}

package/src/token.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from "vitest";
+import { resolveZaloToken } from "./token.js";
+import type { ZaloConfig } from "./types.js";
+
+describe("resolveZaloToken", () => {
+  it("falls back to top-level token for non-default accounts without overrides", () => {
+    const cfg = {
+      botToken: "top-level-token",
+      accounts: {
+        work: {},
+      },
+    } as ZaloConfig;
+    const res = resolveZaloToken(cfg, "work");
+    expect(res.token).toBe("top-level-token");
+    expect(res.source).toBe("config");
+  });
+
+  it("uses accounts.default botToken for default account when configured", () => {
+    const cfg = {
+      botToken: "top-level-token",
+      accounts: {
+        default: {
+          botToken: "default-account-token",
+        },
+      },
+    } as ZaloConfig;
+    const res = resolveZaloToken(cfg, "default");
+    expect(res.token).toBe("default-account-token");
+    expect(res.source).toBe("config");
+  });
+
+  it("does not inherit top-level token when account token is explicitly blank", () => {
+    const cfg = {
+      botToken: "top-level-token",
+      accounts: {
+        work: {
+          botToken: "",
+        },
+      },
+    } as ZaloConfig;
+    const res = resolveZaloToken(cfg, "work");
+    expect(res.token).toBe("");
+    expect(res.source).toBe("none");
+  });
+
+  it("resolves account token when account key casing differs from normalized id", () => {
+    const cfg = {
+      accounts: {
+        Work: {
+          botToken: "work-token",
+        },
+      },
+    } as ZaloConfig;
+    const res = resolveZaloToken(cfg, "work");
+    expect(res.token).toBe("work-token");
+    expect(res.source).toBe("config");
+  });
+});

package/src/token.ts

@@ -1,5 +1,7 @@
 import { readFileSync } from "node:fs";
-import { type BaseTokenResolution, DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk";
+import type { BaseTokenResolution } from "openclaw/plugin-sdk";
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk/account-id";
+import { normalizeResolvedSecretInputString, normalizeSecretInputString } from "./secret-input.js";
 import type { ZaloConfig } from "./types.js";
 
 export type ZaloTokenResolution = BaseTokenResolution & {
@@ -9,17 +11,36 @@ export type ZaloTokenResolution = BaseTokenResolution & {
 export function resolveZaloToken(
   config: ZaloConfig | undefined,
   accountId?: string | null,
+  options?: { allowUnresolvedSecretRef?: boolean },
 ): ZaloTokenResolution {
   const resolvedAccountId = accountId ?? DEFAULT_ACCOUNT_ID;
   const isDefaultAccount = resolvedAccountId === DEFAULT_ACCOUNT_ID;
   const baseConfig = config;
-  const accountConfig =
-    resolvedAccountId !== DEFAULT_ACCOUNT_ID
-      ? (baseConfig?.accounts?.[resolvedAccountId] as ZaloConfig | undefined)
-      : undefined;
+  const resolveAccountConfig = (id: string): ZaloConfig | undefined => {
+    const accounts = baseConfig?.accounts;
+    if (!accounts || typeof accounts !== "object") {
+      return undefined;
+    }
+    const direct = accounts[id] as ZaloConfig | undefined;
+    if (direct) {
+      return direct;
+    }
+    const normalized = normalizeAccountId(id);
+    const matchKey = Object.keys(accounts).find((key) => normalizeAccountId(key) === normalized);
+    return matchKey ? ((accounts as Record<string, ZaloConfig>)[matchKey] ?? undefined) : undefined;
+  };
+  const accountConfig = resolveAccountConfig(resolvedAccountId);
+  const accountHasBotToken = Boolean(
+    accountConfig && Object.prototype.hasOwnProperty.call(accountConfig, "botToken"),
+  );
 
-  if (accountConfig) {
-    const token = accountConfig.botToken?.trim();
+  if (accountConfig && accountHasBotToken) {
+    const token = options?.allowUnresolvedSecretRef
+      ? normalizeSecretInputString(accountConfig.botToken)
+      : normalizeResolvedSecretInputString({
+          value: accountConfig.botToken,
+          path: `channels.zalo.accounts.${resolvedAccountId}.botToken`,
+        });
     if (token) {
       return { token, source: "config" };
     }
@@ -36,8 +57,25 @@ export function resolveZaloToken(
     }
   }
 
-  if (isDefaultAccount) {
-    const token = baseConfig?.botToken?.trim();
+  const accountTokenFile = accountConfig?.tokenFile?.trim();
+  if (!accountHasBotToken && accountTokenFile) {
+    try {
+      const fileToken = readFileSync(accountTokenFile, "utf8").trim();
+      if (fileToken) {
+        return { token: fileToken, source: "configFile" };
+      }
+    } catch {
+      // ignore read failures
+    }
+  }
+
+  if (!accountHasBotToken) {
+    const token = options?.allowUnresolvedSecretRef
+      ? normalizeSecretInputString(baseConfig?.botToken)
+      : normalizeResolvedSecretInputString({
+          value: baseConfig?.botToken,
+          path: "channels.zalo.botToken",
+        });
     if (token) {
       return { token, source: "config" };
     }
@@ -52,6 +90,9 @@ export function resolveZaloToken(
         // ignore read failures
       }
     }
+  }
+
+  if (isDefaultAccount) {
     const envToken = process.env.ZALO_BOT_TOKEN?.trim();
     if (envToken) {
       return { token: envToken, source: "env" };

package/src/types.ts

@@ -1,16 +1,18 @@
+import type { SecretInput } from "openclaw/plugin-sdk";
+
 export type ZaloAccountConfig = {
   /** Optional display name for this account (used in CLI/UI lists). */
   name?: string;
   /** If false, do not start this Zalo account. Default: true. */
   enabled?: boolean;
   /** Bot token from Zalo Bot Creator. */
-  botToken?: string;
+  botToken?: SecretInput;
   /** Path to file containing the bot token. */
   tokenFile?: string;
   /** Webhook URL for receiving updates (HTTPS required). */
   webhookUrl?: string;
   /** Webhook secret token (8-256 chars) for request verification. */
-  webhookSecret?: string;
+  webhookSecret?: SecretInput;
   /** Webhook path for the gateway HTTP server (defaults to webhook URL path). */
   webhookPath?: string;
   /** Direct message access policy (default: pairing). */