Конфигурация и использование канала Discord

Чему вы научитесь

После завершения этого руководства вы сможете:

Создать Discord Bot и получить Bot Token
Настроить интеграцию Clawdbot с Discord Bot
Использовать AI-помощника в Discord DM (личных сообщениях) и серверных каналах
Настроить контроль доступа (спаривание DM, белый список каналов)
Позволить AI вызывать инструменты Discord (отправка сообщений, создание каналов, управление ролями и т.д.)

Ваши текущие трудности

Вы уже используете Discord для общения с друзьями или командой, и хотите взаимодействовать с AI-помощником прямо в Discord без переключения приложений. Вы можете столкнуться со следующими проблемами:

Не знаете, как создать Discord Bot
Неясно, какие права доступа необходимы для нормальной работы бота
Хотите контролировать, кто может взаимодействовать с ботом (чтобы избежать злоупотребления со стороны незнакомцев)
Хотите настроить разное поведение в разных серверных каналах

Это руководство пошагово научит вас решать эти проблемы.

Когда использовать этот метод

Канал Discord подходит для следующих сценариев:

✅ Вы активный пользователь Discord и большая часть вашего общения происходит в Discord
✅ Вы хотите добавить функции AI на сервер Discord (например, умный помощник в канале #help)
✅ Вы хотите взаимодействовать с AI через Discord DM (удобнее, чем открывать WebChat)
✅ Вам нужно, чтобы AI выполнял административные операции в Discord (создание каналов, отправка сообщений и т.д.)

Канал Discord основан на discord.js и поддерживает полный функционал Bot API.

🎒 Подготовка перед началом

Требования:

Завершили руководство Быстрый старт, Gateway может запускаться
Node.js ≥ 22
Аккаунт Discord (может создавать приложения)

Необходимая информация:

Discord Bot Token (покажем, как получить позже)
ID сервера (опционально, для настройки определенных каналов)
ID канала (опционально, для детального контроля)

Основная концепция

Как работает канал Discord

Канал Discord взаимодействует с Discord через официальный Bot API:

Пользователь Discord
     ↓
  Сервер Discord
     ↓
  Discord Bot Gateway
     ↓ (WebSocket)
  Clawdbot Gateway
     ↓
  AI Agent (Claude/GPT и т.д.)
     ↓
  Discord Bot API (отправка ответа)
     ↓
Сервер Discord
     ↓
Пользователь Discord (видит ответ)

Ключевые моменты:

Bot принимает сообщения через WebSocket (Gateway → Bot)
Clawdbot пересылает сообщения в AI Agent для обработки
AI может вызывать инструменты discord для выполнения операций, специфичных для Discord
Все ответы отправляются обратно в Discord через Bot API

Различия между DM и серверными каналами

Тип	Изоляция сессий	Поведение по умолчанию	Подходящие сценарии
Личные сообщения (DM)	Все DM используют общую сессию `agent:main:main`	Требуется спаривание (pairing)	Личный разговор, сохранение контекста
Серверный канал	Каждый канал имеет независимую сессию `agent:<agentId>:discord:channel:<channelId>`	Требуется @упоминание для ответа	Серверный умный помощник, параллельные многоканальные сессии

TIP

Сессии серверных каналов полностью изолированы и не мешают друг другу. Разговоры в канале #help не появятся в #general.

Механизм защиты по умолчанию

Канал Discord по умолчанию включает защиту спаривания DM:

Неизвестный пользователь → отправляет DM → Clawdbot
                              ↓
                      Отказ от обработки, возврат кода спаривания
                              ↓
                Пользователь должен выполнить `clawdbot pairing approve discord <code>`
                              ↓
                            Спаривание успешно, можно общаться

Это предотвращает прямое взаимодействие незнакомых пользователей с вашим AI-помощником.

Следуйте за нами

Шаг 1: Создание приложения Discord и Bot

Зачем Discord Bot нужен «идентификатор», чтобы подключиться к серверу Discord. Этот идентификатор — Bot Token.

1.1 Создание приложения Discord

Откройте Discord Developer Portal
Нажмите New Application (Новое приложение)
Введите название приложения (например, Clawdbot AI)
Нажмите Create (Создать)

1.2 Добавление пользователя Bot

В левой навигации нажмите Bot (Бот)
Нажмите Add Bot → Reset Token → Reset Token (Сбросить токен)
Важно: Сразу скопируйте Bot Token (отображается только один раз!)

Формат Bot Token: MTAwOTk1MDk5NjQ5NTExNjUy.Gm9...
(Изменяется при каждом сбросе, храните надежно!)

1.3 Включение необходимых Gateway Intents

Discord по умолчанию не позволяет Bot читать содержимое сообщений, нужно включить вручную.

В Bot → Privileged Gateway Intents (Привилегированные намерения шлюза) включите:

Intent	Обязателен	Описание
Message Content Intent	✅ Обязателен	Чтение текстового содержимого сообщения (без него Bot не видит сообщения)
Server Members Intent	⚠️ Рекомендуется	Для поиска участников и разрешения имен пользователей

Не делайте

Не включайте Presence Intent (Намерение присутствия), если вам действительно не нужен онлайн-статус пользователей.

Что вы должны увидеть: оба переключателя стали зелеными (ON).

Шаг 2: Генерация URL приглашения и добавление на сервер

Зачем Bot нужны права доступа для чтения и отправки сообщений на сервере.

В левой навигации нажмите OAuth2 → URL Generator
В Scopes (Область) выберите:
- ✅ bot
- ✅ applications.commands (для нативных команд)
В Bot Permissions (Права бота) выберите минимум:

Право	Описание
View Channels	Просмотр каналов
Send Messages	Отправка сообщений
Read Message History	Чтение истории сообщений
Embed Links	Встраивание ссылок
Attach Files	Загрузка файлов

Опциональные права (добавьте по необходимости):

Add Reactions (Добавление реакции)
Use External Emojis (Использование кастомных эмодзи)

Совет по безопасности

Избегайте предоставления прав Administrator (Администратор), если только вы не отлаживаете и полностью доверяете боту.

Скопируйте сгенерированный URL
Откройте URL в браузере
Выберите свой сервер, нажмите Authorize (Авторизовать)

Что вы должны увидеть: Bot успешно добавлен на сервер, отображается зеленым онлайн-статусом.

Шаг 3: Получение необходимых ID (сервер, канал, пользователь)

Зачем Конфигурация Clawdbot предпочитает использовать ID (числа), потому что ID не меняются.

3.1 Включение режима разработчика Discord

Discord Desktop/Web → User Settings (Настройки пользователя)
Advanced (Дополнительно) → включите Developer Mode (Режим разработчика)

3.2 Копирование ID

Тип	Действие
ID сервера	Правый клик по названию сервера → Copy Server ID
ID канала	Правый клик по каналу (например, `#general`) → Copy Channel ID
ID пользователя	Правый клик по аватару пользователя → Copy User ID

ID против имени

При настройке используйте ID в приоритете. Имя может измениться, но ID никогда не изменится.

Что вы должны увидеть: ID скопирован в буфер обмена (формат: 123456789012345678).

Шаг 4: Настройка подключения Clawdbot к Discord

Зачем Сказать Clawdbot, как подключиться к вашему Discord Bot.

Метод 1: Через переменные окружения (рекомендуется, для серверов)

bash

export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN"

clawdbot gateway --port 18789

Метод 2: Через конфигурационный файл

Отредактируйте ~/.clawdbot/clawdbot.json:

json5

{
  channels: {
    discord: {
      enabled: true,
      token: "YOUR_BOT_TOKEN"  // Token, скопированный на шаге 1
    }
  }
}

Приоритет переменных окружения

Если установлены переменные окружения и конфигурационный файл, конфигурационный файл имеет приоритет.

Что вы должны увидеть: После запуска Gateway, Discord Bot отображается в онлайн-статусе.

Шаг 5: Проверка подключения и тестирование

Зачем Убедиться, что конфигурация правильная, Bot может нормально принимать и отправлять сообщения.

Запустите Gateway (если еще не запущен):

bash

clawdbot gateway --port 18789 --verbose

Проверьте статус Discord Bot:
- Bot должен отображаться зеленым онлайн в списке участников сервера
- Если он серый офлайн, проверьте правильность Token
Отправьте тестовое сообщение:

В Discord:

Личные сообщения (DM): Отправьте сообщение напрямую боту (получите код спаривания, см. следующий раздел)
Серверный канал: @упомяните бота, например @ClawdbotAI hello

Что вы должны увидеть: Bot отвечает сообщением (содержимое зависит от вашей AI-модели).

Тест не удался?

Если Bot не отвечает, проверьте раздел Устранение неполадок.

Контрольная точка ✅

Перед продолжением подтвердите следующее:

[ ] Bot Token правильно настроен
[ ] Bot успешно добавлен на сервер
[ ] Message Content Intent включен
[ ] Gateway работает
[ ] Bot отображается онлайн в Discord
[ ] @упоминание Bot получает ответ

Расширенная настройка

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

Стратегия по умолчанию — pairing (режим спаривания), подходит для личного использования. Вы можете настроить по необходимости:

Стратегия	Описание	Пример конфигурации
pairing (по умолчанию)	Незнакомцы получают код спаривания, требуют ручного одобрения	`"dm": { "policy": "pairing" }`
allowlist	Разрешить только пользователей из списка	`"dm": { "policy": "allowlist", "allowFrom": ["123456", "alice"] }`
open	Разрешить всем (требуется `allowFrom` содержит `"*"`)	`"dm": { "policy": "open", "allowFrom": ["*"] }`
disabled	Отключить все DM	`"dm": { "enabled": false }`

Пример конфигурации: разрешение определенных пользователей

json5

{
  channels: {
    discord: {
      dm: {
        enabled: true,
        policy: "allowlist",
        allowFrom: [
          "123456789012345678",  // ID пользователя
          "@alice",                   // Имя пользователя (будет разрешено как ID)
          "alice#1234"              // Полное имя пользователя
        ]
      }
    }
  }
}

Одобрение запроса спаривания

Когда незнакомый пользователь впервые отправляет DM, он получает код спаривания. Способ одобрения:

bash

clawdbot pairing approve discord <код спаривания>

Настройка серверных каналов

Базовая настройка: разрешить только определенные каналы

json5

{
  channels: {
    discord: {
      groupPolicy: "allowlist",  // Режим белого списка (по умолчанию)
      guilds: {
        "123456789012345678": {
          requireMention: true,  // Требуется @упоминание для ответа
          channels: {
            help: { allow: true },    // Разрешить #help
            general: { allow: true } // Разрешить #general
          }
        }
      }
    }
  }
}

TIP

requireMention: true — рекомендуемая настройка, избегает «самодеятельности» бота в публичных каналах.

Расширенная настройка: уникальное поведение канала

json5

{
  channels: {
    discord: {
      guilds: {
        "123456789012345678": {
          slug: "my-server",              // Отображаемое имя (опционально)
          reactionNotifications: "own",      // Только реакции к сообщениям бота триггерят события
          channels: {
            help: {
              allow: true,
              requireMention: true,
              users: ["987654321098765432"], // Только определенные пользователи могут триггерить
              skills: ["search", "docs"],    // Ограничить доступные навыки
              systemPrompt: "Keep answers under 50 words."  // Дополнительный системный промпт
            }
          }
        }
      }
    }
  }
}

Операции с инструментами Discord

AI Agent может вызывать инструменты discord для выполнения операций, специфичных для Discord. Управляйте правами через channels.discord.actions:

Категория операции	Статус по умолчанию	Описание
reactions	✅ Включен	Добавление/чтение реакций
messages	✅ Включен	Чтение/отправка/редактирование/удаление сообщений
threads	✅ Включен	Создание/ответ в темах
channels	✅ Включен	Создание/редактирование/удаление каналов
pins	✅ Включен	Закрепление/открепление сообщений
search	✅ Включен	Поиск сообщений
memberInfo	✅ Включен	Запрос информации об участнике
roleInfo	✅ Включен	Запрос списка ролей
roles	❌ Отключен	Добавление/удаление ролей
moderation	❌ Отключен	Бан/выкидывание/тайм-аут

Отключение определенных операций

json5

{
  channels: {
    discord: {
      actions: {
        channels: false,      // Отключить управление каналами
        moderation: false,   // Отключить операции модерации
        roles: false         // Отключить управление ролями
      }
    }
  }
}

Предупреждение безопасности

При включении операций moderation и roles убедитесь, что AI имеет строгие промпты и контроль доступа, чтобы избежать случайного бана пользователей.

Другие параметры конфигурации

Параметр	Описание	По умолчанию
`historyLimit`	Количество исторических сообщений в контексте серверного канала	20
`dmHistoryLimit`	Количество исторических сообщений в сессии DM	Не ограничено
`textChunkLimit`	Максимальное количество символов в одном сообщении	2000
`maxLinesPerMessage`	Максимальное количество строк в одном сообщении	17
`mediaMaxMb`	Максимальный размер загружаемого медиафайла (МБ)	8
`chunkMode`	Режим разбиения сообщений (`length`/`newline`)	`length`

Предупреждение об ошибках

❌ Ошибка "Used disallowed intents"

Причина: Не включен Message Content Intent.

Решение:

Вернитесь в Discord Developer Portal
Bot → Privileged Gateway Intents
Включите Message Content Intent
Перезапустите Gateway

❌ Bot подключен, но не отвечает

Возможные причины:

Отсутствует Message Content Intent
Bot нет прав доступа к каналу
Конфигурация требует @упоминания, но вы не упомянули
Канал не в белом списке

Шаги решения:

bash

# Запуск инструмента диагностики
clawdbot doctor

# Проверка статуса канала и прав доступа
clawdbot channels status --probe

❌ Код спаривания DM истек

Причина: Срок действия кода спаривания — 1 час.

Решение: Попросите пользователя снова отправить DM, получить новый код спаривания, затем одобрить.

❌ Групповые DM игнорируются

Причина: По умолчанию dm.groupEnabled: false.

Решение:

json5

{
  channels: {
    discord: {
      dm: {
        groupEnabled: true,
        groupChannels: ["clawd-dm"]  // Опционально: разрешить только определенные групповые DM
      }
    }
  }
}

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

Диагностика распространенных проблем

bash

# 1. Проверка работы Gateway
clawdbot gateway status

# 2. Проверка статуса подключения канала
clawdbot channels status

# 3. Запуск полной диагностики (рекомендуется!)
clawdbot doctor

Отладка через логи

Запустите Gateway с --verbose для просмотра подробных логов:

bash

clawdbot gateway --port 18789 --verbose

Обратите внимание на эти логи:

Discord channel connected: ... → Успешное подключение
Message received from ... → Получено сообщение
ERROR: ... → Информация об ошибке

Резюме урока

Канал Discord подключается через discord.js, поддерживает DM и серверные каналы
Создание Bot требует 4 шага: приложение, пользователь Bot, Gateway Intents, URL приглашения
Message Content Intent обязателен, без него Bot не может читать сообщения
По умолчанию включена защита спаривания DM, незнакомцы должны спариться, чтобы общаться
Серверные каналы можно настроить через guilds.<id>.channels (белый список и поведение)
AI может вызывать инструменты Discord для выполнения административных операций (можно контролировать через actions)

Предварительный просмотр следующего урока

На следующем уроке мы изучим Канал Google Chat.
Вы узнаете:
Как настроить аутентификацию Google Chat OAuth
Маршрутизацию сообщений в Google Chat Space
Ограничения использования Google Chat API

Приложение: ссылка на исходный код

Нажмите, чтобы развернуть местоположение исходного кода

Время обновления: 2026-01-27

Функция	Путь к файлу	Номер строки
Schema конфигурации Discord Bot	`src/config/zod-schema.providers-core.ts`	320-427
Мастер настройки Discord Onboarding	`src/channels/plugins/onboarding/discord.ts`	1-485
Операции с инструментами Discord	`src/agents/tools/discord-actions.ts`	1-72
Операции с сообщениями Discord	`src/agents/tools/discord-actions-messaging.ts`	-
Операции с сервером Discord	`src/agents/tools/discord-actions-guild.ts`	-
Официальная документация Discord	`docs/channels/discord.md`	1-400

Ключевые поля Schema:

DiscordAccountSchema: конфигурация аккаунта Discord (token, guilds, dm, actions и т.д.)
DiscordDmSchema: конфигурация DM (enabled, policy, allowFrom, groupEnabled)
DiscordGuildSchema: конфигурация сервера (slug, requireMention, reactionNotifications, channels)
DiscordGuildChannelSchema: конфигурация канала (allow, requireMention, skills, systemPrompt)

Ключевые функции:

handleDiscordAction(): точка входа для обработки операций с инструментами Discord
discordOnboardingAdapter.configure(): мастер конфигурации в пошаговом режиме

Конфигурация и использование канала Discord ​

Чему вы научитесь ​

Ваши текущие трудности ​

Когда использовать этот метод ​

🎒 Подготовка перед началом ​

Основная концепция ​

Как работает канал Discord ​

Различия между DM и серверными каналами ​

Механизм защиты по умолчанию ​

Следуйте за нами ​

Шаг 1: Создание приложения Discord и Bot ​

1.1 Создание приложения Discord ​

1.2 Добавление пользователя Bot ​

1.3 Включение необходимых Gateway Intents ​

Шаг 2: Генерация URL приглашения и добавление на сервер ​

Шаг 3: Получение необходимых ID (сервер, канал, пользователь) ​

3.1 Включение режима разработчика Discord ​

3.2 Копирование ID ​

Шаг 4: Настройка подключения Clawdbot к Discord ​

Метод 1: Через переменные окружения (рекомендуется, для серверов) ​

Метод 2: Через конфигурационный файл ​

Шаг 5: Проверка подключения и тестирование ​

Контрольная точка ✅ ​

Расширенная настройка ​

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

Пример конфигурации: разрешение определенных пользователей ​

Одобрение запроса спаривания ​

Настройка серверных каналов ​

Базовая настройка: разрешить только определенные каналы ​

Расширенная настройка: уникальное поведение канала ​

Операции с инструментами Discord ​

Отключение определенных операций ​

Другие параметры конфигурации ​

Предупреждение об ошибках ​

❌ Ошибка "Used disallowed intents" ​

❌ Bot подключен, но не отвечает ​

❌ Код спаривания DM истек ​

❌ Групповые DM игнорируются ​

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

Диагностика распространенных проблем ​

Отладка через логи ​

Резюме урока ​

Предварительный просмотр следующего урока ​

Приложение: ссылка на исходный код ​

Конфигурация и использование канала Discord

Чему вы научитесь

Ваши текущие трудности

Когда использовать этот метод

🎒 Подготовка перед началом

Основная концепция

Как работает канал Discord

Различия между DM и серверными каналами

Механизм защиты по умолчанию

Следуйте за нами

Шаг 1: Создание приложения Discord и Bot

1.1 Создание приложения Discord

1.2 Добавление пользователя Bot

1.3 Включение необходимых Gateway Intents

Шаг 2: Генерация URL приглашения и добавление на сервер

Шаг 3: Получение необходимых ID (сервер, канал, пользователь)

3.1 Включение режима разработчика Discord

3.2 Копирование ID

Шаг 4: Настройка подключения Clawdbot к Discord

Метод 1: Через переменные окружения (рекомендуется, для серверов)

Метод 2: Через конфигурационный файл

Шаг 5: Проверка подключения и тестирование

Контрольная точка ✅

Расширенная настройка

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

Пример конфигурации: разрешение определенных пользователей

Одобрение запроса спаривания

Настройка серверных каналов

Базовая настройка: разрешить только определенные каналы

Расширенная настройка: уникальное поведение канала

Операции с инструментами Discord

Отключение определенных операций

Другие параметры конфигурации

Предупреждение об ошибках

❌ Ошибка "Used disallowed intents"

❌ Bot подключен, но не отвечает

❌ Код спаривания DM истек

❌ Групповые DM игнорируются

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

Диагностика распространенных проблем

Отладка через логи

Резюме урока

Предварительный просмотр следующего урока

Приложение: ссылка на исходный код