@openclaw/twitch 2026.2.21

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## 2026.1.23
+
+### Features
+
+- Initial Twitch plugin release
+- Twitch chat integration via @twurple (IRC connection)
+- Multi-account support with per-channel configuration
+- Access control via user ID allowlists and role-based restrictions
+- Automatic token refresh with RefreshingAuthProvider
+- Environment variable fallback for default account token
+- Message actions support
+- Status monitoring and probing
+- Outbound message delivery with markdown stripping
+
+### Improvements
+
+- Added proper configuration schema with Zod validation
+- Added plugin descriptor (openclaw.plugin.json)
+- Added comprehensive README and documentation

package/README.md

@@ -0,0 +1,89 @@
+# @openclaw/twitch
+
+Twitch channel plugin for OpenClaw.
+
+## Install (local checkout)
+
+```bash
+openclaw plugins install ./extensions/twitch
+```
+
+## Install (npm)
+
+```bash
+openclaw plugins install @openclaw/twitch
+```
+
+Onboarding: select Twitch and confirm the install prompt to fetch the plugin automatically.
+
+## Config
+
+Minimal config (simplified single-account):
+
+**⚠️ Important:** `requireMention` defaults to `true`. Add access control (`allowFrom` or `allowedRoles`) to prevent unauthorized users from triggering the bot.
+
+```json5
+{
+  channels: {
+    twitch: {
+      enabled: true,
+      username: "openclaw",
+      accessToken: "oauth:abc123...", // OAuth Access Token (add oauth: prefix)
+      clientId: "xyz789...", // Client ID from Token Generator
+      channel: "vevisk", // Channel to join (required)
+      allowFrom: ["123456789"], // (recommended) Your Twitch user ID only (Convert your twitch username to ID at https://www.streamweasels.com/tools/convert-twitch-username-%20to-user-id/)
+    },
+  },
+}
+```
+
+**Access control options:**
+
+- `requireMention: false` - Disable the default mention requirement to respond to all messages
+- `allowFrom: ["your_user_id"]` - Restrict to your Twitch user ID only (find your ID at https://www.twitchangles.com/xqc or similar)
+- `allowedRoles: ["moderator", "vip", "subscriber"]` - Restrict to specific roles
+
+Multi-account config (advanced):
+
+```json5
+{
+  channels: {
+    twitch: {
+      enabled: true,
+      accounts: {
+        default: {
+          username: "openclaw",
+          accessToken: "oauth:abc123...",
+          clientId: "xyz789...",
+          channel: "vevisk",
+        },
+        channel2: {
+          username: "openclaw",
+          accessToken: "oauth:def456...",
+          clientId: "uvw012...",
+          channel: "secondchannel",
+        },
+      },
+    },
+  },
+}
+```
+
+## Setup
+
+1. Create a dedicated Twitch account for the bot, then generate credentials: [Twitch Token Generator](https://twitchtokengenerator.com/)
+   - Select **Bot Token**
+   - Verify scopes `chat:read` and `chat:write` are selected
+   - Copy the **Access Token** to `token` property
+   - Copy the **Client ID** to `clientId` property
+2. Start the gateway
+
+## Full documentation
+
+See https://docs.openclaw.ai/channels/twitch for:
+
+- Token refresh setup
+- Access control patterns
+- Multi-account configuration
+- Troubleshooting
+- Capabilities & limits

package/index.ts

@@ -0,0 +1,20 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import { twitchPlugin } from "./src/plugin.js";
+import { setTwitchRuntime } from "./src/runtime.js";
+
+export { monitorTwitchProvider } from "./src/monitor.js";
+
+const plugin = {
+  id: "twitch",
+  name: "Twitch",
+  description: "Twitch channel plugin",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: OpenClawPluginApi) {
+    setTwitchRuntime(api.runtime);
+    // oxlint-disable-next-line typescript/no-explicit-any
+    api.registerChannel({ plugin: twitchPlugin as any });
+  },
+};
+
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1,9 @@
+{
+  "id": "twitch",
+  "channels": ["twitch"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@openclaw/twitch",
+  "version": "2026.2.21",
+  "description": "OpenClaw Twitch channel plugin",
+  "type": "module",
+  "dependencies": {
+    "@twurple/api": "^8.0.3",
+    "@twurple/auth": "^8.0.3",
+    "@twurple/chat": "^8.0.3",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "openclaw": "workspace:*"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}

package/src/access-control.test.ts

@@ -0,0 +1,491 @@
+import { describe, expect, it } from "vitest";
+import { checkTwitchAccessControl, extractMentions } from "./access-control.js";
+import type { TwitchAccountConfig, TwitchChatMessage } from "./types.js";
+
+describe("checkTwitchAccessControl", () => {
+  const mockAccount: TwitchAccountConfig = {
+    username: "testbot",
+    accessToken: "test",
+    clientId: "test-client-id",
+    channel: "testchannel",
+  };
+
+  const mockMessage: TwitchChatMessage = {
+    username: "testuser",
+    userId: "123456",
+    message: "hello bot",
+    channel: "testchannel",
+  };
+
+  describe("when no restrictions are configured", () => {
+    it("allows messages that mention the bot (default requireMention)", () => {
+      const message: TwitchChatMessage = {
+        ...mockMessage,
+        message: "@testbot hello",
+      };
+      const result = checkTwitchAccessControl({
+        message,
+        account: mockAccount,
+        botUsername: "testbot",
+      });
+      expect(result.allowed).toBe(true);
+    });
+  });
+
+  describe("requireMention default", () => {
+    it("defaults to true when undefined", () => {
+      const message: TwitchChatMessage = {
+        ...mockMessage,
+        message: "hello bot",
+      };
+
+      const result = checkTwitchAccessControl({
+        message,
+        account: mockAccount,
+        botUsername: "testbot",
+      });
+      expect(result.allowed).toBe(false);
+      expect(result.reason).toContain("does not mention the bot");
+    });
+
+    it("allows mention when requireMention is undefined", () => {
+      const message: TwitchChatMessage = {
+        ...mockMessage,
+        message: "@testbot hello",
+      };
+
+      const result = checkTwitchAccessControl({
+        message,
+        account: mockAccount,
+        botUsername: "testbot",
+      });
+      expect(result.allowed).toBe(true);
+    });
+  });
+
+  describe("requireMention", () => {
+    it("allows messages that mention the bot", () => {
+      const account: TwitchAccountConfig = {
+        ...mockAccount,
+        requireMention: true,
+      };
+      const message: TwitchChatMessage = {
+        ...mockMessage,
+        message: "@testbot hello",
+      };
+
+      const result = checkTwitchAccessControl({
+        message,
+        account,
+        botUsername: "testbot",
+      });
+      expect(result.allowed).toBe(true);
+    });
+
+    it("blocks messages that don't mention the bot", () => {
+      const account: TwitchAccountConfig = {
+        ...mockAccount,
+        requireMention: true,
+      };
+
+      const result = checkTwitchAccessControl({
+        message: mockMessage,
+        account,
+        botUsername: "testbot",
+      });
+      expect(result.allowed).toBe(false);
+      expect(result.reason).toContain("does not mention the bot");
+    });
+
+    it("is case-insensitive for bot username", () => {
+      const account: TwitchAccountConfig = {
+        ...mockAccount,
+        requireMention: true,
+      };
+      const message: TwitchChatMessage = {
+        ...mockMessage,
+        message: "@TestBot hello",
+      };
+
+      const result = checkTwitchAccessControl({
+        message,
+        account,
+        botUsername: "testbot",
+      });
+      expect(result.allowed).toBe(true);
+    });
+  });
+
+  describe("allowFrom allowlist", () => {
+    it("allows users in the allowlist", () => {
+      const account: TwitchAccountConfig = {
+        ...mockAccount,
+        allowFrom: ["123456", "789012"],
+      };
+      const message: TwitchChatMessage = {
+        ...mockMessage,
+        message: "@testbot hello",
+      };
+
+      const result = checkTwitchAccessControl({
+        message,
+        account,
+        botUsername: "testbot",
+      });
+      expect(result.allowed).toBe(true);
+      expect(result.matchKey).toBe("123456");
+      expect(result.matchSource).toBe("allowlist");
+    });
+
+    it("blocks users not in allowlist when allowFrom is set", () => {
+      const account: TwitchAccountConfig = {
+        ...mockAccount,
+        allowFrom: ["789012"],
+      };
+      const message: TwitchChatMessage = {
+        ...mockMessage,
+        message: "@testbot hello",
+      };
+
+      const result = checkTwitchAccessControl({
+        message,
+        account,
+        botUsername: "testbot",
+      });
+      expect(result.allowed).toBe(false);
+      expect(result.reason).toContain("allowFrom");
+    });
+
+    it("blocks messages without userId", () => {
+      const account: TwitchAccountConfig = {
+        ...mockAccount,
+        allowFrom: ["123456"],
+      };
+      const message: TwitchChatMessage = {
+        ...mockMessage,
+        message: "@testbot hello",
+        userId: undefined,
+      };
+
+      const result = checkTwitchAccessControl({
+        message,
+        account,
+        botUsername: "testbot",
+      });
+      expect(result.allowed).toBe(false);
+      expect(result.reason).toContain("user ID not available");
+    });
+
+    it("bypasses role checks when user is in allowlist", () => {
+      const account: TwitchAccountConfig = {
+        ...mockAccount,
+        allowFrom: ["123456"],
+        allowedRoles: ["owner"],
+      };
+      const message: TwitchChatMessage = {
+        ...mockMessage,
+        message: "@testbot hello",
+        isOwner: false,
+      };
+
+      const result = checkTwitchAccessControl({
+        message,
+        account,
+        botUsername: "testbot",
+      });
+      expect(result.allowed).toBe(true);
+    });
+
+    it("blocks user with role when not in allowlist", () => {
+      const account: TwitchAccountConfig = {
+        ...mockAccount,
+        allowFrom: ["789012"],
+        allowedRoles: ["moderator"],
+      };
+      const message: TwitchChatMessage = {
+        ...mockMessage,
+        message: "@testbot hello",
+        userId: "123456",
+        isMod: true,
+      };
+
+      const result = checkTwitchAccessControl({
+        message,
+        account,
+        botUsername: "testbot",
+      });
+      expect(result.allowed).toBe(false);
+      expect(result.reason).toContain("allowFrom");
+    });
+
+    it("blocks user not in allowlist even when roles configured", () => {
+      const account: TwitchAccountConfig = {
+        ...mockAccount,
+        allowFrom: ["789012"],
+        allowedRoles: ["moderator"],
+      };
+      const message: TwitchChatMessage = {
+        ...mockMessage,
+        message: "@testbot hello",
+        userId: "123456",
+        isMod: false,
+      };
+
+      const result = checkTwitchAccessControl({
+        message,
+        account,
+        botUsername: "testbot",
+      });
+      expect(result.allowed).toBe(false);
+      expect(result.reason).toContain("allowFrom");
+    });
+  });
+
+  describe("allowedRoles", () => {
+    it("allows users with matching role", () => {
+      const account: TwitchAccountConfig = {
+        ...mockAccount,
+        allowedRoles: ["moderator"],
+      };
+      const message: TwitchChatMessage = {
+        ...mockMessage,
+        message: "@testbot hello",
+        isMod: true,
+      };
+
+      const result = checkTwitchAccessControl({
+        message,
+        account,
+        botUsername: "testbot",
+      });
+      expect(result.allowed).toBe(true);
+      expect(result.matchSource).toBe("role");
+    });
+
+    it("allows users with any of multiple roles", () => {
+      const account: TwitchAccountConfig = {
+        ...mockAccount,
+        allowedRoles: ["moderator", "vip", "subscriber"],
+      };
+      const message: TwitchChatMessage = {
+        ...mockMessage,
+        message: "@testbot hello",
+        isVip: true,
+        isMod: false,
+        isSub: false,
+      };
+
+      const result = checkTwitchAccessControl({
+        message,
+        account,
+        botUsername: "testbot",
+      });
+      expect(result.allowed).toBe(true);
+    });
+
+    it("blocks users without matching role", () => {
+      const account: TwitchAccountConfig = {
+        ...mockAccount,
+        allowedRoles: ["moderator"],
+      };
+      const message: TwitchChatMessage = {
+        ...mockMessage,
+        message: "@testbot hello",
+        isMod: false,
+      };
+
+      const result = checkTwitchAccessControl({
+        message,
+        account,
+        botUsername: "testbot",
+      });
+      expect(result.allowed).toBe(false);
+      expect(result.reason).toContain("does not have any of the required roles");
+    });
+
+    it("allows all users when role is 'all'", () => {
+      const account: TwitchAccountConfig = {
+        ...mockAccount,
+        allowedRoles: ["all"],
+      };
+      const message: TwitchChatMessage = {
+        ...mockMessage,
+        message: "@testbot hello",
+      };
+
+      const result = checkTwitchAccessControl({
+        message,
+        account,
+        botUsername: "testbot",
+      });
+      expect(result.allowed).toBe(true);
+      expect(result.matchKey).toBe("all");
+    });
+
+    it("handles moderator role", () => {
+      const account: TwitchAccountConfig = {
+        ...mockAccount,
+        allowedRoles: ["moderator"],
+      };
+      const message: TwitchChatMessage = {
+        ...mockMessage,
+        message: "@testbot hello",
+        isMod: true,
+      };
+
+      const result = checkTwitchAccessControl({
+        message,
+        account,
+        botUsername: "testbot",
+      });
+      expect(result.allowed).toBe(true);
+    });
+
+    it("handles subscriber role", () => {
+      const account: TwitchAccountConfig = {
+        ...mockAccount,
+        allowedRoles: ["subscriber"],
+      };
+      const message: TwitchChatMessage = {
+        ...mockMessage,
+        message: "@testbot hello",
+        isSub: true,
+      };
+
+      const result = checkTwitchAccessControl({
+        message,
+        account,
+        botUsername: "testbot",
+      });
+      expect(result.allowed).toBe(true);
+    });
+
+    it("handles owner role", () => {
+      const account: TwitchAccountConfig = {
+        ...mockAccount,
+        allowedRoles: ["owner"],
+      };
+      const message: TwitchChatMessage = {
+        ...mockMessage,
+        message: "@testbot hello",
+        isOwner: true,
+      };
+
+      const result = checkTwitchAccessControl({
+        message,
+        account,
+        botUsername: "testbot",
+      });
+      expect(result.allowed).toBe(true);
+    });
+
+    it("handles vip role", () => {
+      const account: TwitchAccountConfig = {
+        ...mockAccount,
+        allowedRoles: ["vip"],
+      };
+      const message: TwitchChatMessage = {
+        ...mockMessage,
+        message: "@testbot hello",
+        isVip: true,
+      };
+
+      const result = checkTwitchAccessControl({
+        message,
+        account,
+        botUsername: "testbot",
+      });
+      expect(result.allowed).toBe(true);
+    });
+  });
+
+  describe("combined restrictions", () => {
+    it("checks requireMention before allowlist", () => {
+      const account: TwitchAccountConfig = {
+        ...mockAccount,
+        requireMention: true,
+        allowFrom: ["123456"],
+      };
+      const message: TwitchChatMessage = {
+        ...mockMessage,
+        message: "hello", // No mention
+      };
+
+      const result = checkTwitchAccessControl({
+        message,
+        account,
+        botUsername: "testbot",
+      });
+      expect(result.allowed).toBe(false);
+      expect(result.reason).toContain("does not mention the bot");
+    });
+
+    it("checks allowlist before allowedRoles", () => {
+      const account: TwitchAccountConfig = {
+        ...mockAccount,
+        allowFrom: ["123456"],
+        allowedRoles: ["owner"],
+      };
+      const message: TwitchChatMessage = {
+        ...mockMessage,
+        message: "@testbot hello",
+        isOwner: false,
+      };
+
+      const result = checkTwitchAccessControl({
+        message,
+        account,
+        botUsername: "testbot",
+      });
+      expect(result.allowed).toBe(true);
+      expect(result.matchSource).toBe("allowlist");
+    });
+  });
+});
+
+describe("extractMentions", () => {
+  it("extracts single mention", () => {
+    const mentions = extractMentions("hello @testbot");
+    expect(mentions).toEqual(["testbot"]);
+  });
+
+  it("extracts multiple mentions", () => {
+    const mentions = extractMentions("hello @testbot and @otheruser");
+    expect(mentions).toEqual(["testbot", "otheruser"]);
+  });
+
+  it("returns empty array when no mentions", () => {
+    const mentions = extractMentions("hello everyone");
+    expect(mentions).toEqual([]);
+  });
+
+  it("handles mentions at start of message", () => {
+    const mentions = extractMentions("@testbot hello");
+    expect(mentions).toEqual(["testbot"]);
+  });
+
+  it("handles mentions at end of message", () => {
+    const mentions = extractMentions("hello @testbot");
+    expect(mentions).toEqual(["testbot"]);
+  });
+
+  it("converts mentions to lowercase", () => {
+    const mentions = extractMentions("hello @TestBot");
+    expect(mentions).toEqual(["testbot"]);
+  });
+
+  it("extracts alphanumeric usernames", () => {
+    const mentions = extractMentions("hello @user123");
+    expect(mentions).toEqual(["user123"]);
+  });
+
+  it("handles underscores in usernames", () => {
+    const mentions = extractMentions("hello @test_user");
+    expect(mentions).toEqual(["test_user"]);
+  });
+
+  it("handles empty string", () => {
+    const mentions = extractMentions("");
+    expect(mentions).toEqual([]);
+  });
+});