Twitch (плагин)

Поддержка чата Twitch через IRC-соединение. OpenClaw подключается как пользователь Twitch (аккаунт бота) для приёма и отправки сообщений в каналах.

Требуется плагин

Twitch поставляется как плагин и не входит в базовую установку.

Установка через CLI (npm-реестр):

openclaw plugins install @openclaw/twitch

Из локальной копии (при работе из git-репозитория):

openclaw plugins install ./extensions/twitch

Подробнее: Плагины

Быстрая настройка (для начинающих)

  1. Создайте выделенный аккаунт Twitch для бота (или используйте существующий).
  2. Сгенерируйте учётные данные: Twitch Token Generator
    • Выберите Bot Token
    • Убедитесь, что выбраны права chat:read и chat:write
    • Скопируйте Client ID и Access Token
  3. Найдите ваш Twitch user ID: https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/
  4. Настройте токен:
    • Env: OPENCLAW_TWITCH_ACCESS_TOKEN=... (только аккаунт по умолчанию)
    • Или конфиг: channels.twitch.accessToken
    • При наличии обоих конфиг имеет приоритет (env fallback только для аккаунта по умолчанию).
  5. Запустите шлюз.

Предупреждение: Добавьте контроль доступа (allowFrom или allowedRoles), чтобы неавторизованные пользователи не могли активировать бота. requireMention по умолчанию true.

Минимальная конфигурация:

{
  channels: {
    twitch: {
      enabled: true,
      username: "openclaw", // Аккаунт бота в Twitch
      accessToken: "oauth:abc123...", // OAuth Access Token (или используйте OPENCLAW_TWITCH_ACCESS_TOKEN)
      clientId: "xyz789...", // Client ID из Token Generator
      channel: "vevisk", // Чат какого канала Twitch присоединиться (обязательно)
      allowFrom: ["123456789"], // (рекомендуется) Ваш Twitch user ID — получите на https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/
    },
  },
}

Что это

  • Канал Twitch, принадлежащий шлюзу.
  • Детерминированная маршрутизация: ответы всегда возвращаются в Twitch.
  • Каждый аккаунт привязан к изолированному ключу сессии agent:<agentId>:twitch:<accountName>.
  • username — аккаунт бота (кто аутентифицируется), channel — в какой чат присоединиться.

Настройка (подробная)

Генерация учётных данных

Используйте Twitch Token Generator:

  • Выберите Bot Token
  • Убедитесь, что выбраны права chat:read и chat:write
  • Скопируйте Client ID и Access Token

Ручная регистрация приложения не требуется. Токены истекают через несколько часов.

Настройка бота

Переменная окружения (только аккаунт по умолчанию):

OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123...

Или конфиг:

{
  channels: {
    twitch: {
      enabled: true,
      username: "openclaw",
      accessToken: "oauth:abc123...",
      clientId: "xyz789...",
      channel: "vevisk",
    },
  },
}

При наличии обоих конфиг имеет приоритет.

Контроль доступа (рекомендуется)

{
  channels: {
    twitch: {
      allowFrom: ["123456789"], // (рекомендуется) Ваш Twitch user ID
    },
  },
}

Предпочтительнее allowFrom для жёсткого списка доступа. Используйте allowedRoles для доступа по ролям.

Доступные роли: "moderator", "owner", "vip", "subscriber", "all".

Почему user ID? Имена пользователей могут меняться, допуская имитацию. User ID постоянны.

Найдите ваш Twitch user ID: https://www.streamweasels.com/tools/convert-twitch-username-%20to-user-id/

Обновление токена (опционально)

Токены из Twitch Token Generator не могут быть обновлены автоматически — перегенерируйте при истечении.

Для автоматического обновления создайте собственное приложение Twitch в Twitch Developer Console и добавьте в конфиг:

{
  channels: {
    twitch: {
      clientSecret: "your_client_secret",
      refreshToken: "your_refresh_token",
    },
  },
}

Бот автоматически обновляет токены перед истечением и логирует события обновления.

Мульти-аккаунт

Используйте channels.twitch.accounts с токенами для каждого аккаунта. Подробнее: gateway/configuration.

Пример (один бот-аккаунт в двух каналах):

{
  channels: {
    twitch: {
      accounts: {
        channel1: {
          username: "openclaw",
          accessToken: "oauth:abc123...",
          clientId: "xyz789...",
          channel: "vevisk",
        },
        channel2: {
          username: "openclaw",
          accessToken: "oauth:def456...",
          clientId: "uvw012...",
          channel: "secondchannel",
        },
      },
    },
  },
}

Примечание: Каждому аккаунту нужен свой токен (один токен на канал).

Контроль доступа

Ограничение по ролям

{
  channels: {
    twitch: {
      accounts: {
        default: {
          allowedRoles: ["moderator", "vip"],
        },
      },
    },
  },
}

Список доступа по User ID (наиболее безопасный)

{
  channels: {
    twitch: {
      accounts: {
        default: {
          allowFrom: ["123456789", "987654321"],
        },
      },
    },
  },
}

Доступ по ролям (альтернатива)

allowFrom — жёсткий список доступа. При наличии допускаются только указанные user ID. Если нужен доступ по ролям, оставьте allowFrom пустым и настройте allowedRoles:

{
  channels: {
    twitch: {
      accounts: {
        default: {
          allowedRoles: ["moderator"],
        },
      },
    },
  },
}

Отключение требования @mention

По умолчанию requireMention равно true. Для ответа на все сообщения:

{
  channels: {
    twitch: {
      accounts: {
        default: {
          requireMention: false,
        },
      },
    },
  },
}

Устранение неполадок

Сначала выполните диагностические команды:

openclaw doctor
openclaw channels status --probe

Бот не отвечает на сообщения

Проверьте контроль доступа: Убедитесь, что ваш user ID в allowFrom, или временно удалите allowFrom и задайте allowedRoles: ["all"] для теста.

Проверьте, что бот в канале: Бот должен присоединиться к каналу, указанному в channel.

Проблемы с токеном

«Failed to connect» или ошибки аутентификации:

  • Убедитесь, что accessToken — это значение OAuth access token (обычно начинается с oauth:)
  • Проверьте, что токен имеет права chat:read и chat:write
  • При использовании обновления токена проверьте, что заданы clientSecret и refreshToken

Обновление токена не работает

Проверьте логи на события обновления:

Using env token source for mybot
Access token refreshed for user 123456 (expires in 14400s)

Если видите «token refresh disabled (no refresh token)»:

  • Убедитесь, что задан clientSecret
  • Убедитесь, что задан refreshToken

Конфигурация

Конфигурация аккаунта:

  • username - Имя пользователя бота
  • accessToken - OAuth access token с chat:read и chat:write
  • clientId - Twitch Client ID (из Token Generator или вашего приложения)
  • channel - Канал для присоединения (обязательно)
  • enabled - Включить этот аккаунт (по умолчанию: true)
  • clientSecret - Необязательно: для автоматического обновления токена
  • refreshToken - Необязательно: для автоматического обновления токена
  • expiresIn - Срок действия токена в секундах
  • obtainmentTimestamp - Временная метка получения токена
  • allowFrom - Список доступа по user ID
  • allowedRoles - Контроль доступа по ролям ("moderator" | "owner" | "vip" | "subscriber" | "all")
  • requireMention - Требовать @mention (по умолчанию: true)

Опции провайдера:

  • channels.twitch.enabled - Включение/выключение запуска канала
  • channels.twitch.username - Имя пользователя бота (упрощённая конфигурация одного аккаунта)
  • channels.twitch.accessToken - OAuth access token (упрощённая конфигурация одного аккаунта)
  • channels.twitch.clientId - Twitch Client ID (упрощённая конфигурация одного аккаунта)
  • channels.twitch.channel - Канал для присоединения (упрощённая конфигурация одного аккаунта)
  • channels.twitch.accounts.<accountName> - Мульти-аккаунтная конфигурация (все поля аккаунта выше)

Полный пример:

{
  channels: {
    twitch: {
      enabled: true,
      username: "openclaw",
      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"],
        },
      },
    },
  },
}

Действия инструментов

Агент может вызывать twitch с действием:

  • send - Отправить сообщение в канал

Пример:

{
  action: "twitch",
  params: {
    message: "Hello Twitch!",
    to: "#mychannel",
  },
}

Безопасность и эксплуатация

  • Обращайтесь с токенами как с паролями — никогда не коммитьте токены в git
  • Используйте автоматическое обновление токена для долго работающих ботов
  • Используйте списки доступа по user ID вместо имён пользователей для контроля доступа
  • Отслеживайте логи на предмет событий обновления токенов и состояния подключения
  • Минимизируйте права токенов — запрашивайте только chat:read и chat:write
  • При зависании: перезапустите шлюз, убедившись, что другой процесс не владеет сессией

Ограничения

  • 500 символов на сообщение (автоматическая разбивка по границам слов)
  • Markdown удаляется перед разбивкой
  • Ограничение частоты отсутствует (используются встроенные лимиты Twitch)
arrow_back
Назад
Tlon
Далее
Whatsapp
arrow_forward