nodmix 2026.5.25

package/docs/channels/twitch.md

@@ -0,0 +1,431 @@
+---
+summary: "Twitch chat bot configuration and setup"
+read_when:
+  - Setting up Twitch chat integration for Nodmix
+title: "Twitch"
+sidebarTitle: "Twitch"
+---
+
+Twitch chat support via IRC connection. Nodmix connects as a Twitch user (bot account) to receive and send messages in channels.
+
+## Bundled plugin
+
+<Note>
+Twitch ships as a bundled plugin in current Nodmix releases, so normal packaged builds do not need a separate install.
+</Note>
+
+If you are on an older build or a custom install that excludes Twitch, install the npm package directly:
+
+<Tabs>
+  <Tab title="npm registry">
+    ```bash
+    nodmix plugins install @nodmix/twitch
+    ```
+  </Tab>
+  <Tab title="Local checkout">
+    ```bash
+    nodmix plugins install ./path/to/local/twitch-plugin
+    ```
+  </Tab>
+</Tabs>
+
+Use the bare package to follow the current official release tag. Pin an exact
+version only when you need a reproducible install.
+
+Details: [Plugins](/tools/plugin)
+
+## Quick setup (beginner)
+
+<Steps>
+  <Step title="Ensure plugin is available">
+    Current packaged Nodmix releases already bundle it. Older/custom installs can add it manually with the commands above.
+  </Step>
+  <Step title="Create a Twitch bot account">
+    Create a dedicated Twitch account for the bot (or use an existing account).
+  </Step>
+  <Step title="Generate credentials">
+    Use [Twitch Token Generator](https://twitchtokengenerator.com/):
+
+    - Select **Bot Token**
+    - Verify scopes `chat:read` and `chat:write` are selected
+    - Copy the **Client ID** and **Access Token**
+
+  </Step>
+  <Step title="Find your Twitch user ID">
+    Use [https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/](https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/) to convert a username to a Twitch user ID.
+  </Step>
+  <Step title="Configure the token">
+    - Env: `NODMIX_TWITCH_ACCESS_TOKEN=...` (default account only)
+    - Or config: `channels.twitch.accessToken`
+
+    If both are set, config takes precedence (env fallback is default-account only).
+
+  </Step>
+  <Step title="Start the gateway">
+    Start the gateway with the configured channel.
+  </Step>
+</Steps>
+
+<Warning>
+Add access control (`allowFrom` or `allowedRoles`) to prevent unauthorized users from triggering the bot. `requireMention` defaults to `true`.
+</Warning>
+
+Minimal config:
+
+```json5
+{
+  channels: {
+    twitch: {
+      enabled: true,
+      username: "nodmix", // Bot's Twitch account
+      accessToken: "oauth:abc123...", // OAuth Access Token (or use NODMIX_TWITCH_ACCESS_TOKEN env var)
+      clientId: "xyz789...", // Client ID from Token Generator
+      channel: "vevisk", // Which Twitch channel's chat to join (required)
+      allowFrom: ["123456789"], // (recommended) Your Twitch user ID only - get it from https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/
+    },
+  },
+}
+```
+
+## What it is
+
+- A Twitch channel owned by the Gateway.
+- Deterministic routing: replies always go back to Twitch.
+- Each account maps to an isolated session key `agent:<agentId>:twitch:<accountName>`.
+- `username` is the bot's account (who authenticates), `channel` is which chat room to join.
+
+## Setup (detailed)
+
+### Generate credentials
+
+Use [Twitch Token Generator](https://twitchtokengenerator.com/):
+
+- Select **Bot Token**
+- Verify scopes `chat:read` and `chat:write` are selected
+- Copy the **Client ID** and **Access Token**
+
+<Note>
+No manual app registration needed. Tokens expire after several hours.
+</Note>
+
+### Configure the bot
+
+<Tabs>
+  <Tab title="Env var (default account only)">
+    ```bash
+    NODMIX_TWITCH_ACCESS_TOKEN=oauth:abc123...
+    ```
+  </Tab>
+  <Tab title="Config">
+    ```json5
+    {
+      channels: {
+        twitch: {
+          enabled: true,
+          username: "nodmix",
+          accessToken: "oauth:abc123...",
+          clientId: "xyz789...",
+          channel: "vevisk",
+        },
+      },
+    }
+    ```
+  </Tab>
+</Tabs>
+
+If both env and config are set, config takes precedence.
+
+### Access control (recommended)
+
+```json5
+{
+  channels: {
+    twitch: {
+      allowFrom: ["123456789"], // (recommended) Your Twitch user ID only
+    },
+  },
+}
+```
+
+Prefer `allowFrom` for a hard allowlist. Use `allowedRoles` instead if you want role-based access.
+
+**Available roles:** `"moderator"`, `"owner"`, `"vip"`, `"subscriber"`, `"all"`.
+
+<Note>
+**Why user IDs?** Usernames can change, allowing impersonation. User IDs are permanent.
+
+Find your Twitch user ID: [https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/](https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/) (Convert your Twitch username to ID)
+</Note>
+
+## Token refresh (optional)
+
+Tokens from [Twitch Token Generator](https://twitchtokengenerator.com/) cannot be automatically refreshed - regenerate when expired.
+
+For automatic token refresh, create your own Twitch application at [Twitch Developer Console](https://dev.twitch.tv/console) and add to config:
+
+```json5
+{
+  channels: {
+    twitch: {
+      clientSecret: "your_client_secret",
+      refreshToken: "your_refresh_token",
+    },
+  },
+}
+```
+
+The bot automatically refreshes tokens before expiration and logs refresh events.
+
+## Multi-account support
+
+Use `channels.twitch.accounts` with per-account tokens. See [Configuration](/gateway/configuration) for the shared pattern.
+
+Example (one bot account in two channels):
+
+```json5
+{
+  channels: {
+    twitch: {
+      accounts: {
+        channel1: {
+          username: "nodmix",
+          accessToken: "oauth:abc123...",
+          clientId: "xyz789...",
+          channel: "vevisk",
+        },
+        channel2: {
+          username: "nodmix",
+          accessToken: "oauth:def456...",
+          clientId: "uvw012...",
+          channel: "secondchannel",
+        },
+      },
+    },
+  },
+}
+```
+
+<Note>
+Each account needs its own token (one token per channel).
+</Note>
+
+## Access control
+
+<Tabs>
+  <Tab title="User ID allowlist (most secure)">
+    ```json5
+    {
+      channels: {
+        twitch: {
+          accounts: {
+            default: {
+              allowFrom: ["123456789", "987654321"],
+            },
+          },
+        },
+      },
+    }
+    ```
+  </Tab>
+  <Tab title="Role-based">
+    ```json5
+    {
+      channels: {
+        twitch: {
+          accounts: {
+            default: {
+              allowedRoles: ["moderator", "vip"],
+            },
+          },
+        },
+      },
+    }
+    ```
+
+    `allowFrom` is a hard allowlist. When set, only those user IDs are allowed. If you want role-based access, leave `allowFrom` unset and configure `allowedRoles` instead.
+
+  </Tab>
+  <Tab title="Disable @mention requirement">
+    By default, `requireMention` is `true`. To disable and respond to all messages:
+
+    ```json5
+    {
+      channels: {
+        twitch: {
+          accounts: {
+            default: {
+              requireMention: false,
+            },
+          },
+        },
+      },
+    }
+    ```
+
+  </Tab>
+</Tabs>
+
+## Troubleshooting
+
+First, run diagnostic commands:
+
+```bash
+nodmix doctor
+nodmix channels status --probe
+```
+
+<AccordionGroup>
+  <Accordion title="Bot does not respond to messages">
+    - **Check access control:** Ensure your user ID is in `allowFrom`, or temporarily remove `allowFrom` and set `allowedRoles: ["all"]` to test.
+    - **Check the bot is in the channel:** The bot must join the channel specified in `channel`.
+
+  </Accordion>
+  <Accordion title="Token issues">
+    "Failed to connect" or authentication errors:
+
+    - Verify `accessToken` is the OAuth access token value (typically starts with `oauth:` prefix)
+    - Check token has `chat:read` and `chat:write` scopes
+    - If using token refresh, verify `clientSecret` and `refreshToken` are set
+
+  </Accordion>
+  <Accordion title="Token refresh not working">
+    Check logs for refresh events:
+
+    ```
+    Using env token source for mybot
+    Access token refreshed for user 123456 (expires in 14400s)
+    ```
+
+    If you see "token refresh disabled (no refresh token)":
+
+    - Ensure `clientSecret` is provided
+    - Ensure `refreshToken` is provided
+
+  </Accordion>
+</AccordionGroup>
+
+## Config
+
+### Account config
+
+<ParamField path="username" type="string">
+  Bot username.
+</ParamField>
+<ParamField path="accessToken" type="string">
+  OAuth access token with `chat:read` and `chat:write`.
+</ParamField>
+<ParamField path="clientId" type="string">
+  Twitch Client ID (from Token Generator or your app).
+</ParamField>
+<ParamField path="channel" type="string" required>
+  Channel to join.
+</ParamField>
+<ParamField path="enabled" type="boolean" default="true">
+  Enable this account.
+</ParamField>
+<ParamField path="clientSecret" type="string">
+  Optional: for automatic token refresh.
+</ParamField>
+<ParamField path="refreshToken" type="string">
+  Optional: for automatic token refresh.
+</ParamField>
+<ParamField path="expiresIn" type="number">
+  Token expiry in seconds.
+</ParamField>
+<ParamField path="obtainmentTimestamp" type="number">
+  Token obtained timestamp.
+</ParamField>
+<ParamField path="allowFrom" type="string[]">
+  User ID allowlist.
+</ParamField>
+<ParamField path="allowedRoles" type='Array<"moderator" | "owner" | "vip" | "subscriber" | "all">'>
+  Role-based access control.
+</ParamField>
+<ParamField path="requireMention" type="boolean" default="true">
+  Require @mention.
+</ParamField>
+
+### Provider options
+
+- `channels.twitch.enabled` - Enable/disable channel startup
+- `channels.twitch.username` - Bot username (simplified single-account config)
+- `channels.twitch.accessToken` - OAuth access token (simplified single-account config)
+- `channels.twitch.clientId` - Twitch Client ID (simplified single-account config)
+- `channels.twitch.channel` - Channel to join (simplified single-account config)
+- `channels.twitch.accounts.<accountName>` - Multi-account config (all account fields above)
+
+Full example:
+
+```json5
+{
+  channels: {
+    twitch: {
+      enabled: true,
+      username: "nodmix",
+      accessToken: "oauth:abc123...",
+      clientId: "xyz789...",
+      channel: "vevisk",
+      clientSecret: "secret123...",
+      refreshToken: "refresh456...",
+      allowFrom: ["123456789"],
+      allowedRoles: ["moderator", "vip"],
+      accounts: {
+        default: {
+          username: "mybot",
+          accessToken: "oauth:abc123...",
+          clientId: "xyz789...",
+          channel: "your_channel",
+          enabled: true,
+          clientSecret: "secret123...",
+          refreshToken: "refresh456...",
+          expiresIn: 14400,
+          obtainmentTimestamp: 1706092800000,
+          allowFrom: ["123456789", "987654321"],
+          allowedRoles: ["moderator"],
+        },
+      },
+    },
+  },
+}
+```
+
+## Tool actions
+
+The agent can call `twitch` with action:
+
+- `send` - Send a message to a channel
+
+Example:
+
+```json5
+{
+  action: "twitch",
+  params: {
+    message: "Hello Twitch!",
+    to: "#mychannel",
+  },
+}
+```
+
+## Safety and ops
+
+- **Treat tokens like passwords** — Never commit tokens to git.
+- **Use automatic token refresh** for long-running bots.
+- **Use user ID allowlists** instead of usernames for access control.
+- **Monitor logs** for token refresh events and connection status.
+- **Scope tokens minimally** — Only request `chat:read` and `chat:write`.
+- **If stuck**: Restart the gateway after confirming no other process owns the session.
+
+## Limits
+
+- **500 characters** per message (auto-chunked at word boundaries).
+- Markdown is stripped before chunking.
+- No rate limiting (uses Twitch's built-in rate limits).
+
+## Related
+
+- [Channel Routing](/channels/channel-routing) — session routing for messages
+- [Channels Overview](/channels) — all supported channels
+- [Groups](/channels/groups) — group chat behavior and mention gating
+- [Pairing](/channels/pairing) — DM authentication and pairing flow
+- [Security](/gateway/security) — access model and hardening

package/docs/channels/wechat.md

@@ -0,0 +1,171 @@
+---
+summary: "WeChat channel setup through the external nodmix-weixin plugin"
+read_when:
+  - You want to connect Nodmix to WeChat or Weixin
+  - You are installing or troubleshooting the nodmix-weixin channel plugin
+  - You need to understand how external channel plugins run beside the Gateway
+title: "WeChat"
+---
+
+Nodmix connects to WeChat through Tencent's external
+`@tencent-weixin/nodmix-weixin` channel plugin.
+
+Status: external plugin. Direct chats and media are supported. Group chats are not
+advertised by the current plugin capability metadata.
+
+## Naming
+
+- **WeChat** is the user-facing name in these docs.
+- **Weixin** is the name used by Tencent's package and by the plugin id.
+- `nodmix-weixin` is the Nodmix channel id.
+- `@tencent-weixin/nodmix-weixin` is the npm package.
+
+Use `nodmix-weixin` in CLI commands and config paths.
+
+## How it works
+
+The WeChat code does not live in the Nodmix core repo. Nodmix provides the
+generic channel plugin contract, and the external plugin provides the
+WeChat-specific runtime:
+
+1. `nodmix plugins install` installs `@tencent-weixin/nodmix-weixin`.
+2. The Gateway discovers the plugin manifest and loads the plugin entrypoint.
+3. The plugin registers channel id `nodmix-weixin`.
+4. `nodmix channels login --channel nodmix-weixin` starts QR login.
+5. The plugin stores account credentials under the Nodmix state directory.
+6. When the Gateway starts, the plugin starts its Weixin monitor for each
+   configured account.
+7. Inbound WeChat messages are normalized through the channel contract, routed to
+   the selected Nodmix agent, and sent back through the plugin outbound path.
+
+That separation matters: Nodmix core should stay channel-agnostic. WeChat login,
+Tencent iLink API calls, media upload/download, context tokens, and account
+monitoring are owned by the external plugin.
+
+## Install
+
+Quick install:
+
+```bash
+npx -y @tencent-weixin/nodmix-weixin-cli install
+```
+
+Manual install:
+
+```bash
+nodmix plugins install "@tencent-weixin/nodmix-weixin"
+nodmix config set plugins.entries.nodmix-weixin.enabled true
+```
+
+Restart the Gateway after install:
+
+```bash
+nodmix gateway restart
+```
+
+## Login
+
+Run QR login on the same machine that runs the Gateway:
+
+```bash
+nodmix channels login --channel nodmix-weixin
+```
+
+Scan the QR code with WeChat on your phone and confirm the login. The plugin saves
+the account token locally after a successful scan.
+
+To add another WeChat account, run the same login command again. For multiple
+accounts, isolate direct-message sessions by account, channel, and sender:
+
+```bash
+nodmix config set session.dmScope per-account-channel-peer
+```
+
+## Access control
+
+Direct messages use the normal Nodmix pairing and allowlist model for channel
+plugins.
+
+Approve new senders:
+
+```bash
+nodmix pairing list nodmix-weixin
+nodmix pairing approve nodmix-weixin <CODE>
+```
+
+For the full access-control model, see [Pairing](/channels/pairing).
+
+## Compatibility
+
+The plugin checks the host Nodmix version at startup.
+
+| Plugin line | Nodmix version        | npm tag  |
+| ----------- | ----------------------- | -------- |
+| `2.x`       | `>=2026.3.22`           | `latest` |
+| `1.x`       | `>=2026.1.0 <2026.3.22` | `legacy` |
+
+If the plugin reports that your Nodmix version is too old, either update
+Nodmix or install the legacy plugin line:
+
+```bash
+nodmix plugins install @tencent-weixin/nodmix-weixin@legacy
+```
+
+## Sidecar process
+
+The WeChat plugin can run helper work beside the Gateway while it monitors the
+Tencent iLink API. In issue #68451, that helper path exposed a bug in Nodmix's
+generic stale-Gateway cleanup: a child process could try to clean up the parent
+Gateway process, causing restart loops under process managers such as systemd.
+
+Current Nodmix startup cleanup excludes the current process and its ancestors,
+so a channel helper must not kill the Gateway that launched it. This fix is
+generic; it is not a WeChat-specific path in core.
+
+## Troubleshooting
+
+Check install and status:
+
+```bash
+nodmix plugins list
+nodmix channels status --probe
+nodmix --version
+```
+
+If the channel shows as installed but does not connect, confirm that the plugin is
+enabled and restart:
+
+```bash
+nodmix config set plugins.entries.nodmix-weixin.enabled true
+nodmix gateway restart
+```
+
+If the Gateway restarts repeatedly after enabling WeChat, update both Nodmix and
+the plugin:
+
+```bash
+npm view @tencent-weixin/nodmix-weixin version
+nodmix plugins install "@tencent-weixin/nodmix-weixin" --force
+nodmix gateway restart
+```
+
+If startup reports that the installed plugin package `requires compiled runtime
+output for TypeScript entry`, the npm package was published without the compiled
+JavaScript runtime files Nodmix needs. Update/reinstall after the plugin
+publisher ships a fixed package, or temporarily disable/uninstall the plugin.
+
+Temporary disable:
+
+```bash
+nodmix config set plugins.entries.nodmix-weixin.enabled false
+nodmix gateway restart
+```
+
+## Related docs
+
+- Channel overview: [Chat Channels](/channels)
+- Pairing: [Pairing](/channels/pairing)
+- Channel routing: [Channel Routing](/channels/channel-routing)
+- Plugin architecture: [Plugin Architecture](/plugins/architecture)
+- Channel plugin SDK: [Channel Plugin SDK](/plugins/sdk-channel-plugins)
+- External package: [@tencent-weixin/nodmix-weixin](https://www.npmjs.com/package/@tencent-weixin/nodmix-weixin)