@openclaw/discord 2026.3.13 → 2026.5.1-beta.1

package/src/token.ts

@@ -0,0 +1,60 @@
+import type { BaseTokenResolution } from "openclaw/plugin-sdk/channel-contract";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk/routing";
+import { resolveAccountEntry } from "openclaw/plugin-sdk/routing";
+import { normalizeResolvedSecretInputString } from "openclaw/plugin-sdk/secret-input";
+
+type DiscordTokenSource = "env" | "config" | "none";
+
+export type DiscordTokenResolution = BaseTokenResolution & {
+  source: DiscordTokenSource;
+};
+
+export function normalizeDiscordToken(raw: unknown, path: string): string | undefined {
+  const trimmed = normalizeResolvedSecretInputString({ value: raw, path });
+  if (!trimmed) {
+    return undefined;
+  }
+  return trimmed.replace(/^Bot\s+/i, "");
+}
+
+export function resolveDiscordToken(
+  cfg: OpenClawConfig,
+  opts: { accountId?: string | null; envToken?: string | null } = {},
+): DiscordTokenResolution {
+  const accountId = normalizeAccountId(opts.accountId);
+  const discordCfg = cfg?.channels?.discord;
+  const accountCfg = resolveAccountEntry(discordCfg?.accounts, accountId);
+  const hasAccountToken = Boolean(
+    accountCfg &&
+    Object.prototype.hasOwnProperty.call(accountCfg as Record<string, unknown>, "token"),
+  );
+  const accountToken = normalizeDiscordToken(
+    (accountCfg as { token?: unknown } | undefined)?.token ?? undefined,
+    `channels.discord.accounts.${accountId}.token`,
+  );
+  if (accountToken) {
+    return { token: accountToken, source: "config" };
+  }
+  if (hasAccountToken) {
+    return { token: "", source: "none" };
+  }
+
+  const configToken = normalizeDiscordToken(
+    discordCfg?.token ?? undefined,
+    "channels.discord.token",
+  );
+  if (configToken) {
+    return { token: configToken, source: "config" };
+  }
+
+  const allowEnv = accountId === DEFAULT_ACCOUNT_ID;
+  const envToken = allowEnv
+    ? normalizeDiscordToken(opts.envToken ?? process.env.DISCORD_BOT_TOKEN, "DISCORD_BOT_TOKEN")
+    : undefined;
+  if (envToken) {
+    return { token: envToken, source: "env" };
+  }
+
+  return { token: "", source: "none" };
+}

package/src/ui-colors.ts

@@ -0,0 +1,27 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import { inspectDiscordAccount } from "./account-inspect.js";
+
+const DEFAULT_DISCORD_ACCENT_COLOR = "#5865F2";
+
+type ResolveDiscordAccentColorParams = {
+  cfg: OpenClawConfig;
+  accountId?: string | null;
+};
+
+export function normalizeDiscordAccentColor(raw?: string | null): string | null {
+  const trimmed = (raw ?? "").trim();
+  if (!trimmed) {
+    return null;
+  }
+  const normalized = trimmed.startsWith("#") ? trimmed : `#${trimmed}`;
+  if (!/^#[0-9a-fA-F]{6}$/.test(normalized)) {
+    return null;
+  }
+  return normalized.toUpperCase();
+}
+
+export function resolveDiscordAccentColor(params: ResolveDiscordAccentColorParams): string {
+  const account = inspectDiscordAccount({ cfg: params.cfg, accountId: params.accountId });
+  const configured = normalizeDiscordAccentColor(account.config.ui?.components?.accentColor);
+  return configured ?? DEFAULT_DISCORD_ACCENT_COLOR;
+}

package/src/ui.ts

@@ -0,0 +1,20 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import { Container } from "./internal/discord.js";
+import { normalizeDiscordAccentColor, resolveDiscordAccentColor } from "./ui-colors.js";
+
+type DiscordContainerComponents = ConstructorParameters<typeof Container>[0];
+
+export class DiscordUiContainer extends Container {
+  constructor(params: {
+    cfg: OpenClawConfig;
+    accountId?: string | null;
+    components?: DiscordContainerComponents;
+    accentColor?: string;
+    spoiler?: boolean;
+  }) {
+    const accentOverride = normalizeDiscordAccentColor(params.accentColor);
+    const accentColor =
+      accentOverride ?? resolveDiscordAccentColor({ cfg: params.cfg, accountId: params.accountId });
+    super(params.components, { accentColor, spoiler: params.spoiler });
+  }
+}

package/src/voice/access.test.ts

@@ -0,0 +1,217 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import type { DiscordAccountConfig } from "openclaw/plugin-sdk/config-types";
+import { describe, expect, it } from "vitest";
+import { authorizeDiscordVoiceIngress } from "./access.js";
+
+const baseCfg = { commands: { useAccessGroups: true } } as OpenClawConfig;
+
+describe("authorizeDiscordVoiceIngress", () => {
+  it("blocks speakers outside the configured channel user allowlist", async () => {
+    const access = await authorizeDiscordVoiceIngress({
+      cfg: baseCfg,
+      discordConfig: {
+        guilds: {
+          g1: {
+            channels: {
+              c1: {
+                users: ["discord:u-owner"],
+              },
+            },
+          },
+        },
+      } as DiscordAccountConfig,
+      groupPolicy: "allowlist",
+      guildId: "g1",
+      channelId: "c1",
+      channelSlug: "",
+      memberRoleIds: [],
+      sender: {
+        id: "u-guest",
+        name: "guest",
+      },
+    });
+
+    expect(access).toEqual({
+      ok: false,
+      message: "You are not authorized to use this command.",
+    });
+  });
+
+  it("allows speakers that match the configured channel user allowlist", async () => {
+    const access = await authorizeDiscordVoiceIngress({
+      cfg: baseCfg,
+      discordConfig: {
+        guilds: {
+          g1: {
+            channels: {
+              c1: {
+                users: ["discord:u-owner"],
+              },
+            },
+          },
+        },
+      } as DiscordAccountConfig,
+      groupPolicy: "allowlist",
+      guildId: "g1",
+      channelId: "c1",
+      channelSlug: "",
+      memberRoleIds: [],
+      sender: {
+        id: "u-owner",
+        name: "owner",
+      },
+    });
+
+    expect(access).toMatchObject({ ok: true });
+    expect(access.ok && access.channelConfig?.users).toEqual(["discord:u-owner"]);
+  });
+
+  it("allows slug-keyed guild configs when manager context only has guild name", async () => {
+    const access = await authorizeDiscordVoiceIngress({
+      cfg: baseCfg,
+      discordConfig: {
+        guilds: {
+          "guild-one": {
+            channels: {
+              "*": {
+                users: ["discord:u-owner"],
+              },
+            },
+          },
+        },
+      } as DiscordAccountConfig,
+      groupPolicy: "allowlist",
+      guildId: "g1",
+      guildName: "Guild One",
+      channelId: "c1",
+      channelSlug: "",
+      memberRoleIds: [],
+      sender: {
+        id: "u-owner",
+        name: "owner",
+      },
+    });
+
+    expect(access).toMatchObject({ ok: true });
+  });
+
+  it("allows wildcard guild configs when only the guild id is available", async () => {
+    const access = await authorizeDiscordVoiceIngress({
+      cfg: baseCfg,
+      discordConfig: {
+        guilds: {
+          "*": {
+            channels: {
+              "*": {
+                users: ["discord:u-owner"],
+              },
+            },
+          },
+        },
+      } as DiscordAccountConfig,
+      groupPolicy: "allowlist",
+      guildId: "g1",
+      channelId: "c1",
+      channelSlug: "",
+      memberRoleIds: [],
+      sender: {
+        id: "u-owner",
+        name: "owner",
+      },
+    });
+
+    expect(access).toMatchObject({ ok: true });
+  });
+
+  it("blocks commands when channel id is unavailable for an allowlisted channel", async () => {
+    const access = await authorizeDiscordVoiceIngress({
+      cfg: baseCfg,
+      discordConfig: {
+        guilds: {
+          g1: {
+            users: ["discord:u-owner"],
+            channels: {
+              c1: {
+                users: ["discord:u-owner"],
+              },
+            },
+          },
+        },
+      } as DiscordAccountConfig,
+      groupPolicy: "allowlist",
+      guildId: "g1",
+      channelId: "",
+      channelSlug: "",
+      memberRoleIds: [],
+      sender: {
+        id: "u-owner",
+        name: "owner",
+      },
+    });
+
+    expect(access).toEqual({
+      ok: false,
+      message: "This channel is not allowlisted for voice commands.",
+    });
+  });
+
+  it("ignores dangerous name matching for voice ingress", async () => {
+    const access = await authorizeDiscordVoiceIngress({
+      cfg: baseCfg,
+      discordConfig: {
+        dangerouslyAllowNameMatching: true,
+        guilds: {
+          g1: {
+            channels: {
+              c1: {
+                users: ["owner"],
+              },
+            },
+          },
+        },
+      } as DiscordAccountConfig,
+      groupPolicy: "allowlist",
+      guildId: "g1",
+      channelId: "c1",
+      channelSlug: "",
+      memberRoleIds: [],
+      sender: {
+        id: "u-guest",
+        name: "owner",
+      },
+    });
+
+    expect(access).toEqual({
+      ok: false,
+      message: "You are not authorized to use this command.",
+    });
+  });
+
+  it("uses resolved account owner allowFrom over merged Discord config", async () => {
+    const access = await authorizeDiscordVoiceIngress({
+      cfg: baseCfg,
+      discordConfig: {
+        allowFrom: ["discord:u-root"],
+        guilds: {
+          g1: {
+            channels: {
+              c1: {},
+            },
+          },
+        },
+      } as DiscordAccountConfig,
+      groupPolicy: "allowlist",
+      guildId: "g1",
+      channelId: "c1",
+      channelSlug: "",
+      memberRoleIds: [],
+      ownerAllowFrom: ["discord:u-account"],
+      sender: {
+        id: "u-account",
+        name: "owner",
+      },
+    });
+
+    expect(access).toMatchObject({ ok: true });
+  });
+});

package/src/voice/access.ts

@@ -0,0 +1,124 @@
+import { resolveCommandAuthorizedFromAuthorizers } from "openclaw/plugin-sdk/command-auth-native";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import type { DiscordAccountConfig } from "openclaw/plugin-sdk/config-types";
+import { resolveOpenProviderRuntimeGroupPolicy } from "openclaw/plugin-sdk/runtime-group-policy";
+import type { Guild } from "../internal/discord.js";
+import {
+  isDiscordGroupAllowedByPolicy,
+  resolveDiscordChannelConfigWithFallback,
+  type DiscordChannelConfigResolved,
+  resolveDiscordGuildEntry,
+  resolveDiscordMemberAccessState,
+  resolveDiscordOwnerAccess,
+} from "../monitor/allow-list.js";
+
+export async function authorizeDiscordVoiceIngress(params: {
+  cfg: OpenClawConfig;
+  discordConfig: DiscordAccountConfig;
+  groupPolicy?: "open" | "disabled" | "allowlist";
+  useAccessGroups?: boolean;
+  guild?: Guild<true> | Guild | null;
+  guildName?: string;
+  guildId: string;
+  channelId: string;
+  channelName?: string;
+  channelSlug: string;
+  parentId?: string;
+  parentName?: string;
+  parentSlug?: string;
+  scope?: "channel" | "thread";
+  channelLabel?: string;
+  memberRoleIds: string[];
+  ownerAllowFrom?: string[];
+  sender: { id: string; name?: string; tag?: string };
+}): Promise<
+  { ok: true; channelConfig?: DiscordChannelConfigResolved | null } | { ok: false; message: string }
+> {
+  const groupPolicy =
+    params.groupPolicy ??
+    resolveOpenProviderRuntimeGroupPolicy({
+      providerConfigPresent: params.cfg.channels?.discord !== undefined,
+      groupPolicy: params.discordConfig.groupPolicy,
+      defaultGroupPolicy: params.cfg.channels?.defaults?.groupPolicy,
+    }).groupPolicy;
+  const guild =
+    params.guild ??
+    ({ id: params.guildId, ...(params.guildName ? { name: params.guildName } : {}) } as Guild);
+  const guildInfo = resolveDiscordGuildEntry({
+    guild,
+    guildId: params.guildId,
+    guildEntries: params.discordConfig.guilds,
+  });
+  const channelConfig = params.channelId
+    ? resolveDiscordChannelConfigWithFallback({
+        guildInfo,
+        channelId: params.channelId,
+        channelName: params.channelName,
+        channelSlug: params.channelSlug,
+        parentId: params.parentId,
+        parentName: params.parentName,
+        parentSlug: params.parentSlug,
+        scope: params.scope,
+      })
+    : null;
+
+  if (channelConfig?.enabled === false) {
+    return { ok: false, message: "This channel is disabled." };
+  }
+
+  const channelAllowlistConfigured =
+    Boolean(guildInfo?.channels) && Object.keys(guildInfo?.channels ?? {}).length > 0;
+  if (!params.channelId && groupPolicy === "allowlist" && channelAllowlistConfigured) {
+    return {
+      ok: false,
+      message: `${params.channelLabel ?? "This channel"} is not allowlisted for voice commands.`,
+    };
+  }
+
+  const channelAllowed = channelConfig ? channelConfig.allowed : !channelAllowlistConfigured;
+  if (
+    !isDiscordGroupAllowedByPolicy({
+      groupPolicy,
+      guildAllowlisted: Boolean(guildInfo),
+      channelAllowlistConfigured,
+      channelAllowed,
+    }) ||
+    channelConfig?.allowed === false
+  ) {
+    return {
+      ok: false,
+      message: `${params.channelLabel ?? "This channel"} is not allowlisted for voice commands.`,
+    };
+  }
+
+  const { hasAccessRestrictions, memberAllowed } = resolveDiscordMemberAccessState({
+    channelConfig,
+    guildInfo,
+    memberRoleIds: params.memberRoleIds,
+    sender: params.sender,
+    allowNameMatching: false,
+  });
+
+  const { ownerAllowList, ownerAllowed } = resolveDiscordOwnerAccess({
+    allowFrom:
+      params.ownerAllowFrom ?? params.discordConfig.allowFrom ?? params.discordConfig.dm?.allowFrom,
+    sender: params.sender,
+    allowNameMatching: false,
+  });
+
+  const useAccessGroups = params.useAccessGroups ?? params.cfg.commands?.useAccessGroups !== false;
+  const authorizers = useAccessGroups
+    ? [
+        { configured: ownerAllowList != null, allowed: ownerAllowed },
+        { configured: hasAccessRestrictions, allowed: memberAllowed },
+      ]
+    : [{ configured: hasAccessRestrictions, allowed: memberAllowed }];
+
+  return resolveCommandAuthorizedFromAuthorizers({
+    useAccessGroups,
+    authorizers,
+    modeWhenAccessGroupsOff: "configured",
+  })
+    ? { ok: true, channelConfig }
+    : { ok: false, message: "You are not authorized to use this command." };
+}

package/src/voice/audio.ts

@@ -0,0 +1,173 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import { createRequire } from "node:module";
+import path from "node:path";
+import type { Readable } from "node:stream";
+import { logVerbose, shouldLogVerbose } from "openclaw/plugin-sdk/runtime-env";
+import { formatErrorMessage } from "openclaw/plugin-sdk/ssrf-runtime";
+import { resolvePreferredOpenClawTmpDir } from "openclaw/plugin-sdk/temp-path";
+
+const require = createRequire(import.meta.url);
+
+const SAMPLE_RATE = 48_000;
+const CHANNELS = 2;
+const BIT_DEPTH = 16;
+
+type OpusDecoder = {
+  decode: (buffer: Buffer) => Buffer;
+};
+
+type OpusDecoderFactory = {
+  load: () => OpusDecoder;
+  name: string;
+};
+
+let warnedOpusMissing = false;
+let cachedOpusDecoderFactory: OpusDecoderFactory | null | "unresolved" = "unresolved";
+
+function buildWavBuffer(pcm: Buffer): Buffer {
+  const blockAlign = (CHANNELS * BIT_DEPTH) / 8;
+  const byteRate = SAMPLE_RATE * blockAlign;
+  const header = Buffer.alloc(44);
+  header.write("RIFF", 0);
+  header.writeUInt32LE(36 + pcm.length, 4);
+  header.write("WAVE", 8);
+  header.write("fmt ", 12);
+  header.writeUInt32LE(16, 16);
+  header.writeUInt16LE(1, 20);
+  header.writeUInt16LE(CHANNELS, 22);
+  header.writeUInt32LE(SAMPLE_RATE, 24);
+  header.writeUInt32LE(byteRate, 28);
+  header.writeUInt16LE(blockAlign, 32);
+  header.writeUInt16LE(BIT_DEPTH, 34);
+  header.write("data", 36);
+  header.writeUInt32LE(pcm.length, 40);
+  return Buffer.concat([header, pcm]);
+}
+
+function resolveOpusDecoderFactory(params: {
+  onWarn: (message: string) => void;
+}): OpusDecoderFactory | null {
+  const factories: OpusDecoderFactory[] = [
+    {
+      name: "@discordjs/opus",
+      load: () => {
+        const DiscordOpus = require("@discordjs/opus") as {
+          OpusEncoder: new (
+            sampleRate: number,
+            channels: number,
+          ) => {
+            decode: (buffer: Buffer) => Buffer;
+          };
+        };
+        return new DiscordOpus.OpusEncoder(SAMPLE_RATE, CHANNELS);
+      },
+    },
+    {
+      name: "opusscript",
+      load: () => {
+        const OpusScript = require("opusscript") as {
+          new (sampleRate: number, channels: number, application: number): OpusDecoder;
+          Application: { AUDIO: number };
+        };
+        return new OpusScript(SAMPLE_RATE, CHANNELS, OpusScript.Application.AUDIO);
+      },
+    },
+  ];
+
+  const failures: string[] = [];
+  for (const factory of factories) {
+    try {
+      factory.load();
+      return factory;
+    } catch (err) {
+      failures.push(`${factory.name}: ${formatErrorMessage(err)}`);
+    }
+  }
+
+  if (!warnedOpusMissing) {
+    warnedOpusMissing = true;
+    params.onWarn(
+      `discord voice: no usable opus decoder available (${failures.join("; ")}); cannot decode voice audio`,
+    );
+  }
+  return null;
+}
+
+function getOrCreateOpusDecoderFactory(params: {
+  onWarn: (message: string) => void;
+}): OpusDecoderFactory | null {
+  if (cachedOpusDecoderFactory !== "unresolved") {
+    return cachedOpusDecoderFactory;
+  }
+  cachedOpusDecoderFactory = resolveOpusDecoderFactory(params);
+  return cachedOpusDecoderFactory;
+}
+
+function createOpusDecoder(params: {
+  onWarn: (message: string) => void;
+}): { decoder: OpusDecoder; name: string } | null {
+  const factory = getOrCreateOpusDecoderFactory(params);
+  if (!factory) {
+    return null;
+  }
+  return { decoder: factory.load(), name: factory.name };
+}
+
+export async function decodeOpusStream(
+  stream: Readable,
+  params: { onVerbose: (message: string) => void; onWarn: (message: string) => void },
+): Promise<Buffer> {
+  const selected = createOpusDecoder({ onWarn: params.onWarn });
+  if (!selected) {
+    return Buffer.alloc(0);
+  }
+  params.onVerbose(`opus decoder: ${selected.name}`);
+  const chunks: Buffer[] = [];
+  try {
+    for await (const chunk of stream) {
+      if (!chunk || !(chunk instanceof Buffer) || chunk.length === 0) {
+        continue;
+      }
+      const decoded = selected.decoder.decode(chunk);
+      if (decoded && decoded.length > 0) {
+        chunks.push(Buffer.from(decoded));
+      }
+    }
+  } catch (err) {
+    if (shouldLogVerbose()) {
+      logVerbose(`discord voice: opus decode failed: ${formatErrorMessage(err)}`);
+    }
+  }
+  return chunks.length > 0 ? Buffer.concat(chunks) : Buffer.alloc(0);
+}
+
+function estimateDurationSeconds(pcm: Buffer): number {
+  const bytesPerSample = (BIT_DEPTH / 8) * CHANNELS;
+  if (bytesPerSample <= 0) {
+    return 0;
+  }
+  return pcm.length / (bytesPerSample * SAMPLE_RATE);
+}
+
+export async function writeVoiceWavFile(
+  pcm: Buffer,
+): Promise<{ path: string; durationSeconds: number }> {
+  const tempDir = await fs.mkdtemp(path.join(resolvePreferredOpenClawTmpDir(), "discord-voice-"));
+  const filePath = path.join(tempDir, `segment-${randomUUID()}.wav`);
+  const wav = buildWavBuffer(pcm);
+  await fs.writeFile(filePath, wav);
+  scheduleTempCleanup(tempDir);
+  return { path: filePath, durationSeconds: estimateDurationSeconds(pcm) };
+}
+
+function scheduleTempCleanup(tempDir: string, delayMs: number = 30 * 60 * 1000): void {
+  const timer = setTimeout(() => {
+    fs.rm(tempDir, { recursive: true, force: true }).catch((err) => {
+      if (shouldLogVerbose()) {
+        logVerbose(`discord voice: temp cleanup failed for ${tempDir}: ${formatErrorMessage(err)}`);
+      }
+    });
+  }, delayMs);
+  timer.unref();
+}

package/src/voice/capture-state.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  beginVoiceCapture,
+  clearVoiceCaptureFinalizeTimer,
+  createVoiceCaptureState,
+  finishVoiceCapture,
+  scheduleVoiceCaptureFinalize,
+} from "./capture-state.js";
+
+describe("voice capture state", () => {
+  it("increments generations per speaker", () => {
+    const state = createVoiceCaptureState();
+    const first = beginVoiceCapture(state, "u1", { destroy: vi.fn() } as never);
+    finishVoiceCapture(state, "u1", first);
+    const second = beginVoiceCapture(state, "u1", { destroy: vi.fn() } as never);
+
+    expect(first).toBe(1);
+    expect(second).toBe(2);
+  });
+
+  it("clears active speaker state before destroying a finalized capture", async () => {
+    vi.useFakeTimers();
+    try {
+      const state = createVoiceCaptureState();
+      const destroy = vi.fn(() => {
+        expect(state.activeSpeakers.has("u1")).toBe(false);
+        expect(state.activeCaptureStreams.has("u1")).toBe(false);
+      });
+      beginVoiceCapture(state, "u1", { destroy } as never);
+
+      expect(scheduleVoiceCaptureFinalize({ state, userId: "u1", delayMs: 1_200 })).toBe(true);
+      await vi.advanceTimersByTimeAsync(1_200);
+
+      expect(destroy).toHaveBeenCalledTimes(1);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("lets a pending finalize be canceled for the same generation", () => {
+    const state = createVoiceCaptureState();
+    const generation = beginVoiceCapture(state, "u1", { destroy: vi.fn() } as never);
+
+    expect(scheduleVoiceCaptureFinalize({ state, userId: "u1", delayMs: 1_200 })).toBe(true);
+    expect(clearVoiceCaptureFinalizeTimer(state, "u1", generation)).toBe(true);
+    expect(state.captureFinalizeTimers.has("u1")).toBe(false);
+  });
+});