Discord

OpenClaw подключается к Discord как бот через официальный gateway Discord. Поддерживаются личные сообщения и каналы серверов.

Быстрая настройка

Создайте приложение Discord с ботом, добавьте бота на свой сервер и выполните его сопряжение с OpenClaw. По возможности используйте частный сервер; при необходимости сначала создайте его (Create My Own > For me and my friends).

export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN"cat > discord.patch.json5 <<'JSON5'{channels: {discord: {  enabled: true,  token: { source: "env", provider: "default", id: "DISCORD_BOT_TOKEN" },},},}JSON5openclaw config patch --file ./discord.patch.json5 --dry-runopenclaw config patch --file ./discord.patch.json5openclaw gateway

{channels: {discord: {enabled: true,token: {source: "env",provider: "default",id: "DISCORD_BOT_TOKEN",},},},}

DISCORD_BOT_TOKEN=...

{channels: {discord: {enabled: true,accounts: {personal: {  token: { source: "env", provider: "default", id: "DISCORD_PERSONAL_TOKEN" },  applicationId: "111111111111111111",},work: {  token: { source: "env", provider: "default", id: "DISCORD_WORK_TOKEN" },  applicationId: "222222222222222222",},},},},}

openclaw pairing list discordopenclaw pairing approve discord <CODE>

Рекомендуется: настройте рабочее пространство сервера

Когда личные сообщения заработают, сервер можно превратить в полноценное рабочее пространство, где каждому каналу соответствует отдельный сеанс агента с собственным контекстом. Рекомендуется для частных серверов, где присутствуете только вы и ваш бот.

{channels: {discord: {groupPolicy: "allowlist",guilds: {YOUR_SERVER_ID: {  requireMention: true,  users: ["YOUR_USER_ID"],},},},},}

{channels: {discord: {guilds: {YOUR_SERVER_ID: {  requireMention: false,},},},},}

Теперь создайте каналы и начинайте общение. Агент видит название канала, а каждый канал представляет собой изолированный сеанс — настройте #coding, #home, #research или любые другие каналы, соответствующие вашему рабочему процессу.

Модель среды выполнения

• Gateway управляет подключением к Discord.
• Маршрутизация ответов детерминирована: ответы на входящие сообщения Discord возвращаются в Discord.
• Метаданные сервера и канала Discord добавляются в запрос модели как недоверенный контекст, а не как видимый пользователю префикс ответа. Если модель копирует эту оболочку в ответ, OpenClaw удаляет скопированные метаданные из исходящих ответов и будущего контекста воспроизведения.
• По умолчанию (session.dmScope=main) личные чаты используют общий основной сеанс агента (agent:main:main).
• Каналы сервера используют изолированные ключи сеансов (agent:<agentId>:discord:channel:<channelId>).
• Групповые личные сообщения по умолчанию игнорируются (channels.discord.dm.groupEnabled=false).
• Нативные слеш-команды выполняются в изолированных сеансах команд (agent:<agentId>:discord:slash:<userId>), при этом CommandTargetSessionKey по-прежнему передаётся в сеанс беседы, выбранный маршрутизацией.
• При доставке в Discord текстовых объявлений Cron/Heartbeat отправляется только один раз итоговый ответ, видимый от имени ассистента. Если агент создаёт несколько доставляемых полезных нагрузок с медиафайлами или структурированными компонентами, они по-прежнему отправляются несколькими сообщениями.

Каналы форумов

Discord-каналы форумов и медиа принимают только публикации в ветках. OpenClaw поддерживает два способа их создания:

• Отправьте сообщение в родительский канал форума (channel:<forumId>), чтобы автоматически создать ветку. Заголовком ветки станет первая непустая строка сообщения (обрезанная до установленного Discord ограничения имени ветки в 100 символов).
• Используйте openclaw message thread create, чтобы создать ветку напрямую. Не передавайте --message-id для каналов форумов.

Отправьте сообщение в родительский канал форума, чтобы создать ветку:

openclaw message send --channel discord --target channel:<forumId> \  --message "Заголовок темы\nТекст публикации"

Создайте ветку форума явно:

openclaw message thread create --channel discord --target channel:<forumId> \  --thread-name "Заголовок темы" --message "Текст публикации"

Родительские каналы форумов не принимают компоненты Discord. Если вам нужны компоненты, отправляйте сообщение в саму ветку (channel:<threadId>).

Интерактивные компоненты

OpenClaw поддерживает контейнеры компонентов Discord v2 для сообщений агента. Используйте инструмент сообщений с полезной нагрузкой components. Результаты взаимодействия направляются обратно агенту как обычные входящие сообщения и учитывают существующие настройки Discord replyToMode.

Поддерживаемые блоки:

• text, section, separator, actions, media-gallery, file
• Строки действий допускают до 5 кнопок или одно меню выбора
• Типы выбора: string, user, role, mentionable, channel

По умолчанию компоненты можно использовать только один раз. Установите components.reusable=true, чтобы кнопки, списки выбора и формы можно было использовать многократно до истечения срока их действия.

Чтобы ограничить круг пользователей, которые могут нажать кнопку, задайте для неё allowedUsers (идентификаторы пользователей Discord, теги или *). Пользователи, не соответствующие условию, получают временное сообщение с отказом.

По умолчанию срок действия обратных вызовов компонентов истекает через 30 минут. Установите channels.discord.agentComponents.ttlMs, чтобы изменить время жизни реестра обратных вызовов для учётной записи по умолчанию, или channels.discord.accounts.<accountId>.agentComponents.ttlMs для отдельной учётной записи. Значение задаётся в миллисекундах, должно быть положительным целым числом и ограничено величиной 86400000 (24 часа). Более длительные значения TTL подходят для процессов проверки и утверждения, в которых кнопки должны дольше оставаться доступными, но они увеличивают период, в течение которого старое сообщение Discord всё ещё может инициировать действие. Выбирайте минимальный подходящий TTL и сохраняйте значение по умолчанию, если срабатывание устаревших обратных вызовов будет неожиданным.

Слеш-команды /model и /models открывают интерактивное средство выбора модели с раскрывающимися списками поставщиков, моделей и совместимых сред выполнения, а также этапом Submit. Команда /models add устарела и вместо регистрации моделей из чата возвращает сообщение об устаревании. Ответ средства выбора является временным и доступен только вызвавшему его пользователю. Меню выбора Discord ограничены 25 вариантами, поэтому добавьте записи provider/* в agents.defaults.models, если хотите, чтобы средство выбора отображало динамически обнаруженные модели только для выбранных поставщиков, таких как openai или vllm.

Вложения файлов:

• Блоки file должны указывать на ссылку на вложение (attachment://<filename>)
• Передайте вложение через media/path/filePath (один файл); для нескольких файлов используйте media-gallery
• Используйте filename, чтобы переопределить имя загружаемого файла, когда оно должно совпадать со ссылкой на вложение

Модальные формы:

• Добавьте components.modal, содержащий до 5 полей
• Типы полей: text, checkbox, radio, select, role-select, user-select
• OpenClaw автоматически добавляет кнопку запуска

Пример:

{  channel: "discord",  action: "send",  to: "channel:123456789012345678",  message: "Необязательный резервный текст",  components: {    reusable: true,    text: "Выберите вариант",    blocks: [      {        type: "actions",        buttons: [          {            label: "Утвердить",            style: "success",            allowedUsers: ["123456789012345678"],          },          { label: "Отклонить", style: "danger" },        ],      },      {        type: "actions",        select: {          type: "string",          placeholder: "Выберите вариант",          options: [            { label: "Вариант A", value: "a" },            { label: "Вариант B", value: "b" },          ],        },      },    ],    modal: {      title: "Подробности",      triggerLabel: "Открыть форму",      fields: [        { type: "text", label: "Заявитель" },        {          type: "select",          label: "Приоритет",          options: [            { label: "Низкий", value: "low" },            { label: "Высокий", value: "high" },          ],        },      ],    },  },}

Управление доступом и маршрутизация

{accessGroups: {operators: {  type: "message.senders",  members: {    "*": ["global-owner-id"],    discord: ["discord:123456789012345678"],    telegram: ["987654321"],  },},},channels: {discord: {  dmPolicy: "allowlist",  allowFrom: ["accessGroup:operators"],},},}

{accessGroups: {maintainers: {  type: "discord.channelAudience",  guildId: "1456350064065904867",  channelId: "1456744319972282449",  membership: "canViewChannel",},},channels: {discord: {  dmPolicy: "allowlist",  allowFrom: ["accessGroup:maintainers"],},},}

{accessGroups: {maintainers: {  type: "discord.channelAudience",  guildId: "1456350064065904867",  channelId: "1456744319972282449",},},channels: {discord: {  dmPolicy: "allowlist",  allowFrom: ["accessGroup:maintainers", "discord:123456789012345678"],},},}

{channels: {discord: {  groupPolicy: "allowlist",  guilds: {    "123456789012345678": {      requireMention: true,      ignoreOtherMentions: true,      users: ["987654321098765432"],      roles: ["123456789012345678"],      channels: {        general: { enabled: true },        help: { enabled: true, requireMention: true },      },    },  },},},}

Маршрутизация агентов на основе ролей

Используйте bindings[].match.roles, чтобы направлять участников сервера Discord разным агентам по идентификатору роли. Привязки на основе ролей принимают только идентификаторы ролей и проверяются после привязок к собеседнику или родительскому собеседнику, но до привязок только к серверу. Если привязка также задаёт другие поля сопоставления (например, peer + guildId + roles), должны совпасть все настроенные поля.

{  bindings: [    {      agentId: "opus",      match: {        channel: "discord",        guildId: "123456789012345678",        roles: ["111111111111111111"],      },    },    {      agentId: "sonnet",      match: {        channel: "discord",        guildId: "123456789012345678",      },    },  ],}

Нативные команды и авторизация команд

• commands.native по умолчанию имеет значение "auto" и включён для Discord.
• Переопределение для отдельного канала: channels.discord.commands.native.
• commands.native=false пропускает регистрацию и очистку слеш-команд Discord при запуске. Ранее зарегистрированные команды могут оставаться видимыми в Discord, пока вы не удалите их из приложения Discord.
• Авторизация нативных команд использует те же списки разрешений и политики Discord, что и обычная обработка сообщений.
• Команды могут по-прежнему отображаться в интерфейсе Discord для неавторизованных пользователей; при выполнении OpenClaw проверяет авторизацию и отвечает «нет авторизации».
• Настройки слеш-команд по умолчанию: ephemeral: true (channels.discord.slashCommand.ephemeral).

Каталог команд и описание их поведения см. в разделе Слеш-команды.

Подробности функций

{channels: {discord: {  suppressEmbeds: false,},},}

{channels: {discord: {  streaming: {    mode: "progress",    progress: {      label: "auto",      maxLines: 8,      maxLineChars: 120,      toolProgress: true,      commentary: false,    },  },},},}

{  "channels": {    "discord": {      "streaming": {        "mode": "progress",        "progress": {          "toolProgress": true,          "commandText": "status"        }      }    }  }}

{session: {threadBindings: {  enabled: true,  idleHours: 24,  maxAgeHours: 0,},},channels: {discord: {  threadBindings: {    enabled: true,    idleHours: 24,    maxAgeHours: 0,    spawnSessions: true,    defaultSpawnContext: "fork",  },},},}

{agents: {list: [  {    id: "codex",    runtime: {      type: "acp",      acp: {        agent: "codex",        backend: "acpx",        mode: "persistent",        cwd: "/workspace/openclaw",      },    },  },],},bindings: [{  type: "acp",  agentId: "codex",  match: {    channel: "discord",    accountId: "default",    peer: { kind: "channel", id: "222222222222222222" },  },  acp: { label: "codex-main" },},],channels: {discord: {  guilds: {    "111111111111111111": {      channels: {        "222222222222222222": {          requireMention: false,        },      },    },  },},},}

{channels: {discord: {  configWrites: false,},},}

{channels: {discord: {  proxy: "http://proxy.example:8080",},},}

{channels: {discord: {  accounts: {    primary: {      proxy: "http://proxy.example:8080",    },  },},},}

{channels: {discord: {  pluralkit: {    enabled: true,    token: "pk_live_...", // optional; needed for private systems  },},},}

{channels: {discord: {  mentionAliases: {    SupportLead: "123456789012345678",  },  accounts: {    ops: {      mentionAliases: {        OpsLead: "234567890123456789",      },    },  },},},}

{channels: {discord: {  status: "idle",},},}

{channels: {discord: {  activity: "Focus time",  activityType: 4,},},}

{channels: {discord: {  activity: "Live coding",  activityType: 1,  activityUrl: "https://twitch.tv/openclaw",},},}

{channels: {discord: {  autoPresence: {    enabled: true,    intervalMs: 30000,    minUpdateIntervalMs: 15000,    exhaustedText: "token exhausted",  },},},}

Инструменты и ограничения действий

Действия с сообщениями Discord охватывают обмен сообщениями, администрирование каналов, модерацию, присутствие и метаданные.

Основные примеры:

• обмен сообщениями: sendMessage, readMessages, editMessage, deleteMessage, threadReply
• реакции: react, reactions, emojiList
• модерация: timeout, kick, ban
• присутствие: setPresence

Действие event-create принимает необязательный параметр image (URL или путь к локальному файлу), чтобы задать обложку запланированного события.

Ограничения действий находятся в channels.discord.actions.*.

Поведение ограничений по умолчанию:

Интерфейс компонентов v2

OpenClaw использует компоненты Discord v2 для подтверждений выполнения и маркеров между контекстами. Действия с сообщениями Discord также могут принимать components для пользовательского интерфейса (расширенная возможность; требуется сформировать полезную нагрузку компонента с помощью инструмента Discord), при этом устаревшие embeds по-прежнему доступны, но не рекомендуются.

• channels.discord.ui.components.accentColor задаёт акцентный цвет контейнеров компонентов Discord (шестнадцатеричный формат). Для отдельной учётной записи: channels.discord.accounts.<id>.ui.components.accentColor.
• channels.discord.agentComponents.ttlMs определяет, как долго отправленные обратные вызовы компонентов Discord остаются зарегистрированными (по умолчанию 1800000, максимум 86400000). Для отдельной учётной записи: channels.discord.accounts.<id>.agentComponents.ttlMs.
• embeds игнорируются при наличии компонентов v2.
• Предварительный просмотр обычных URL по умолчанию отключён. Задайте suppressEmbeds: false для действия с сообщением, если требуется развернуть одну исходящую ссылку.

Пример:

{  channels: {    discord: {      ui: {        components: {          accentColor: "#5865F2",        },      },    },  },}

Голосовая связь

В Discord есть два отдельных голосовых интерфейса: голосовые каналы в реальном времени (непрерывные разговоры) и вложения голосовых сообщений (формат предварительного просмотра с осциллограммой). Gateway поддерживает оба.

Голосовые каналы

Контрольный список настройки:

1. Включите Message Content Intent в Discord Developer Portal.
2. Включите Server Members Intent, если используются списки разрешённых ролей или пользователей.
3. Пригласите бота с областями доступа bot и applications.commands.
4. Предоставьте разрешения Connect, Speak, Send Messages и Read Message History в целевом голосовом канале.
5. Включите встроенные команды (commands.native или channels.discord.commands.native).
6. Настройте channels.discord.voice.

Используйте /vc join|leave|status для управления сеансами. Команда использует агента по умолчанию для учётной записи и подчиняется тем же правилам списка разрешённых значений и групповой политики, что и другие команды Discord.

/vc join channel:<voice-channel-id>/vc status/vc leave

Чтобы проверить фактические разрешения бота перед подключением:

openclaw channels capabilities --channel discord --target channel:<voice-channel-id>

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

{  channels: {    discord: {      voice: {        enabled: true,        model: "openai/gpt-5.6-sol",        autoJoin: [          {            guildId: "123456789012345678",            channelId: "234567890123456789",          },        ],        allowedChannels: [          {            guildId: "123456789012345678",            channelId: "234567890123456789",          },        ],        daveEncryption: true,        decryptionFailureTolerance: 24,        connectTimeoutMs: 30000,        reconnectGraceMs: 15000,        realtime: {          provider: "openai",          model: "gpt-realtime-2.1",          speakerVoice: "cedar",        },      },    },  },}

Примечания:

• Голосовой режим Discord включается явно для конфигураций, предназначенных только для текста; задайте channels.discord.voice.enabled=true (или сохраните существующий блок channels.discord.voice), чтобы включить команды /vc, голосовую среду выполнения и намерение Gateway GuildVoiceStates. Параметр channels.discord.intents.voiceStates может явно переопределить подписку на намерение; не задавайте его, чтобы она определялась фактическим состоянием голосового режима.
• voice.mode управляет сценарием разговора. По умолчанию используется agent-proxy: интерфейс голосового взаимодействия в реальном времени управляет моментами смены реплик, прерываниями и воспроизведением, делегирует содержательную работу выбранному агенту OpenClaw через openclaw_agent_consult и обрабатывает результат как текстовый запрос Discord от этого говорящего. Режим stt-tts сохраняет прежний пакетный процесс STT с последующим TTS. Режим bidi позволяет модели реального времени вести разговор напрямую, предоставляя openclaw_agent_consult для обращения к интеллектуальному ядру OpenClaw.
• voice.agentSession определяет, в какой разговор OpenClaw поступают голосовые реплики. Не задавайте этот параметр, чтобы использовать собственный сеанс голосового канала, либо задайте { mode: "target", target: "channel:<text-channel-id>" }, чтобы голосовой канал служил расширением микрофона и динамика для сеанса существующего текстового канала Discord, например #maintainers.
• voice.model переопределяет интеллектуальное ядро агента OpenClaw для голосовых ответов Discord и обращений в реальном времени. Не задавайте этот параметр, чтобы наследовать модель выбранного агента. Этот параметр не связан с voice.realtime.model.
• voice.followUsers позволяет боту подключаться к голосовому каналу Discord с выбранными пользователями, переходить вслед за ними и покидать канал. См. Следование за пользователями в голосовом канале.
• agent-proxy направляет речь через discord-voice, сохраняя обычную авторизацию владельца и инструментов для говорящего и целевого сеанса, но скрывает инструмент агента tts, поскольку воспроизведением управляет голосовой режим Discord. По умолчанию agent-proxy предоставляет обращению полный доступ к инструментам, эквивалентный доступу владельца, для говорящих-владельцев (voice.realtime.toolPolicy: "owner") и настоятельно рекомендует обращаться к агенту OpenClaw перед содержательными ответами (voice.realtime.consultPolicy: "always"). В этом режиме always, используемом по умолчанию, слой реального времени не произносит автоматически фразы-заполнители перед ответом на обращение: он захватывает и расшифровывает речь, а затем озвучивает ответ выбранного агента OpenClaw. Если несколько принудительно запрошенных ответов завершаются, пока Discord ещё воспроизводит первый ответ, последующие ответы с точной формулировкой речи помещаются в очередь до окончания воспроизведения, а не заменяют речь посреди предложения.
• В режиме stt-tts для STT используется tools.media.audio; параметр voice.model не влияет на распознавание речи.
• В режимах реального времени параметры voice.realtime.provider, voice.realtime.model и voice.realtime.speakerVoice настраивают аудиосеанс реального времени. Для OpenAI Realtime 2.1 с интеллектуальным ядром Codex используйте voice.realtime.model: "gpt-realtime-2.1" и voice.model: "openai/gpt-5.6-sol".
• По умолчанию голосовые режимы реального времени включают небольшие файлы профиля IDENTITY.md, USER.md и SOUL.md в инструкции поставщика реального времени, чтобы быстрые прямые реплики сохраняли ту же идентичность, привязку к пользователю и образ, что и выбранный агент OpenClaw. Задайте в voice.realtime.bootstrapContextFiles подмножество файлов, чтобы настроить это поведение, или [], чтобы отключить его. Поддерживаются только эти файлы профиля; AGENTS.md остаётся в обычном контексте агента. Внедрённый контекст профиля не заменяет openclaw_agent_consult для работы в рабочем пространстве, получения актуальных сведений, поиска в памяти или действий с использованием инструментов.
• В режиме реального времени OpenAI agent-proxy задайте voice.realtime.requireWakeName: true, чтобы голосовой режим Discord в реальном времени молчал, пока расшифровка не начнётся или не закончится именем активации. Настроенные имена активации должны состоять из одного или двух слов. Если voice.realtime.wakeNames не задан, OpenClaw использует name выбранного агента вместе с OpenClaw, а при их отсутствии — идентификатор агента вместе с OpenClaw. Фильтрация по имени активации отключает автоматический ответ поставщика реального времени, направляет принятые реплики через механизм обращения к агенту OpenClaw и выдаёт короткое голосовое подтверждение, если начальное имя активации распознано по частичной расшифровке до поступления окончательной расшифровки.
• Поставщик OpenAI для режима реального времени принимает текущие имена событий Realtime 2 и устаревшие псевдонимы, совместимые с Codex, для событий выходного аудио и расшифровки, поэтому совместимые снимки поставщика могут изменяться без потери звука ответов ассистента.
• voice.realtime.bargeIn определяет, прерывают ли события начала речи в Discord активное воспроизведение в реальном времени. Если параметр не задан, поведение определяется настройкой прерывания по входному аудио поставщика реального времени.
• voice.realtime.minBargeInAudioEndMs задаёт минимальную длительность воспроизведения ответа ассистента, после которой вмешательство в режиме реального времени OpenAI обрезает аудио. По умолчанию: 250. Задайте 0 для немедленного прерывания в помещениях с малым эхом или увеличьте значение для конфигураций динамиков с сильным эхом.
• voice.tts переопределяет messages.tts только для голосового воспроизведения stt-tts; вместо этого режимы реального времени используют voice.realtime.speakerVoice. Чтобы использовать голос OpenAI для воспроизведения в Discord, задайте voice.tts.provider: "openai" и выберите голос синтеза речи в voice.tts.providers.openai.speakerVoice. cedar — хороший вариант с мужским звучанием в текущей модели TTS OpenAI.
• Переопределения Discord systemPrompt для отдельных каналов применяются к репликам, полученным из расшифровки речи в соответствующем голосовом канале.
• Для реплик из расшифровки речи и команд /vc статус владельца Discord определяется по записям Discord в commands.ownerAllowFrom. Если владелец команд Discord не настроен, OpenClaw использует allowFrom выбранной учётной записи Discord (или устаревший dm.allowFrom). Доступность инструментов агента определяется настроенной политикой инструментов для выбранного сеанса.
• Если voice.autoJoin содержит несколько записей для одной и той же гильдии, OpenClaw подключается к последнему настроенному каналу этой гильдии.
• voice.allowedChannels — необязательный список разрешённых мест пребывания. Не задавайте его, чтобы разрешить /vc join подключение к любому авторизованному голосовому каналу Discord. Если параметр задан, /vc join, автоматическое подключение при запуске и перемещения голосового состояния бота ограничиваются перечисленными записями { guildId, channelId }. Задайте пустой массив, чтобы запретить все подключения к голосовым каналам Discord. Если Discord перемещает бота за пределы списка разрешённых каналов, OpenClaw покидает этот канал и повторно подключается к настроенному целевому каналу автоматического подключения, если он доступен.
• voice.daveEncryption и voice.decryptionFailureTolerance передаются в параметры подключения @discordjs/voice; значения по умолчанию в вышестоящем проекте — daveEncryption=true и decryptionFailureTolerance=24.
• OpenClaw использует встроенный кодек libopus-wasm для приёма голоса Discord и воспроизведения необработанного PCM в реальном времени. В поставку входит закреплённая версия сборки libopus для WebAssembly, поэтому нативные дополнения opus не требуются.
• voice.connectTimeoutMs задаёт время первоначального ожидания состояния @discordjs/voice Ready для /vc join и попыток автоматического подключения. По умолчанию: 30000.
• voice.reconnectGraceMs определяет, как долго OpenClaw ожидает начала повторного подключения отключённого голосового сеанса, прежде чем уничтожить его. По умолчанию: 15000.
• В режиме stt-tts воспроизведение голоса не останавливается только из-за того, что другой пользователь начал говорить. Чтобы избежать петель обратной связи, OpenClaw игнорирует новый захват голоса во время воспроизведения TTS; для следующей реплики говорите после окончания воспроизведения. Режимы реального времени передают начало речи как сигналы вмешательства поставщику реального времени.
• В режимах реального времени эхо от динамиков, попадающее в открытый микрофон, может быть воспринято как вмешательство и прервать воспроизведение. Для помещений Discord с сильным эхом задайте voice.realtime.providers.openai.interruptResponseOnInputAudio: false, чтобы OpenAI не выполнял автоматическое прерывание по входному аудио. Добавьте voice.realtime.bargeIn: true, если события начала речи в Discord всё же должны прерывать активное воспроизведение. Мост OpenAI для режима реального времени считает обрезания воспроизведения короче voice.realtime.minBargeInAudioEndMs вероятным эхом или шумом и регистрирует их как пропущенные вместо очистки воспроизведения Discord.
• voice.captureSilenceGraceMs определяет, как долго OpenClaw ждёт после сообщения Discord о прекращении речи пользователем, прежде чем завершить этот аудиосегмент для STT. По умолчанию: 2000; увеличьте значение, если Discord разбивает обычные паузы на прерывистые частичные расшифровки.
• Когда в качестве поставщика TTS выбран ElevenLabs, голосовое воспроизведение Discord использует потоковый TTS и начинается непосредственно из потока ответа поставщика. Для поставщиков без поддержки потоковой передачи используется резервный путь через синтезированный временный файл.
• OpenClaw отслеживает ошибки расшифрования при приёме и автоматически восстанавливается, покидая голосовой канал и подключаясь к нему снова после нескольких ошибок за короткий промежуток времени.
• Если после обновления в журналах приёма регулярно появляется DecryptionFailed(UnencryptedWhenPassthroughDisabled), соберите отчёт о зависимостях и журналы. Встроенная ветка @discordjs/voice содержит исправление заполнения из вышестоящего PR discord.js #11449, закрывшего проблему discord.js #11419.
• События приёма The operation was aborted ожидаемы, когда OpenClaw завершает захваченный сегмент речи пользователя; это подробная диагностика, а не предупреждения.
• Подробные журналы голосового режима Discord содержат ограниченный однострочный предварительный просмотр расшифровки STT для каждого принятого сегмента речи, поэтому при отладке видны и реплика пользователя, и ответ агента без вывода неограниченного объёма текста расшифровки.
• В режиме agent-proxy резервный механизм принудительного обращения пропускает предположительно незавершённые фрагменты расшифровки, например текст, заканчивающийся на ... или союзом вроде «и», а также очевидные не требующие действий завершающие фразы вроде «скоро вернусь» или «пока». Когда это предотвращает выдачу устаревшего ответа из очереди, в журналах отображается forced agent consult skipped reason=....

Следование за пользователями в голосовом канале

Используйте voice.followUsers, если голосовой бот Discord должен оставаться с одним или несколькими известными пользователями Discord, а не подключаться к фиксированному каналу при запуске или ожидать /vc join.

{  channels: {    discord: {      voice: {        enabled: true,        followUsersEnabled: true,        followUsers: ["discord:123456789012345678"],        allowedChannels: [          {            guildId: "123456789012345678",            channelId: "234567890123456789",          },        ],      },    },  },}

Поведение:

• followUsers принимает необработанные идентификаторы пользователей Discord и значения discord:<id>. OpenClaw нормализует обе формы перед сопоставлением событий состояния голосового канала.
• followUsersEnabled по умолчанию имеет значение true, когда настроен followUsers. Установите значение false, чтобы сохранить список, но отключить автоматическое следование в голосовых каналах.
• followUsers управляет только присутствием в голосовом канале. Он не предоставляет доступ к роли говорящего или полномочия владельца; настройте commands.ownerAllowFrom, а также пользователей и роли сервера или канала отдельно.
• Когда отслеживаемый пользователь подключается к разрешённому голосовому каналу, OpenClaw подключается к этому каналу. Когда пользователь переходит в другой канал, OpenClaw следует за ним. Когда активный отслеживаемый пользователь отключается, OpenClaw покидает канал.
• Если несколько отслеживаемых пользователей находятся на одном сервере и активный отслеживаемый пользователь уходит, OpenClaw переходит в канал другого отслеживаемого пользователя, прежде чем покинуть сервер. Если несколько отслеживаемых пользователей перемещаются одновременно, приоритет получает последнее замеченное событие состояния голосового канала.
• allowedChannels продолжает действовать. Отслеживаемый пользователь в запрещённом канале игнорируется, а сеанс, принадлежащий функции отслеживания, переходит к другому отслеживаемому пользователю или завершается.
• OpenClaw восстанавливает пропущенные события состояния голосового канала при запуске и через ограниченные интервалы. При сверке проверяются настроенные серверы, а количество REST-запросов за один проход ограничивается, поэтому для очень больших списков followUsers может потребоваться более одного интервала для достижения согласованного состояния.
• Если Discord или администратор перемещает бота во время отслеживания пользователя, OpenClaw пересоздаёт голосовой сеанс и сохраняет принадлежность функции отслеживания, если целевой канал разрешён. Если бот перемещён за пределы allowedChannels, OpenClaw покидает канал и повторно подключается к настроенному целевому каналу, если он существует.
• При восстановлении приёма DAVE бот может покинуть канал и повторно подключиться к нему после многократных ошибок расшифровки. Сеансы, принадлежащие функции отслеживания, сохраняют эту принадлежность в процессе восстановления, поэтому при последующем отключении отслеживаемого пользователя бот всё равно покинет канал.

Выберите режим подключения:

• Используйте followUsers для личных или операторских конфигураций, в которых бот должен автоматически присутствовать в голосовом канале вместе с вами.
• Используйте autoJoin для ботов, закреплённых за определённым каналом и присутствующих в нём, даже когда ни один отслеживаемый пользователь не подключён к голосовому каналу.
• Используйте /vc join для разовых подключений или каналов, где автоматическое присутствие в голосовом канале было бы неожиданным.

Голосовой кодек Discord:

• В журналах приёма голоса отображается discord voice: opus decoder: libopus-wasm.
• При воспроизведении в реальном времени необработанный стереофонический PCM с частотой 48 кГц кодируется в Opus тем же встроенным пакетом libopus-wasm, после чего пакеты передаются в @discordjs/voice.
• При воспроизведении файлов и потоков от провайдера данные перекодируются с помощью ffmpeg в необработанный стереофонический PCM с частотой 48 кГц, после чего libopus-wasm используется для формирования потока пакетов Opus, отправляемого в Discord.

Конвейер STT и TTS:

• Захваченные из Discord данные PCM преобразуются во временный WAV-файл.
• tools.media.audio выполняет STT, например openai/gpt-4o-mini-transcribe.
• Транскрипция проходит через входной поток и маршрутизацию Discord, а LLM ответа работает с политикой голосового вывода, которая скрывает от агента инструмент tts и запрашивает возвращаемый текст, поскольку окончательным воспроизведением TTS управляет голосовая подсистема Discord.
• voice.model, если задан, переопределяет только LLM ответа для этого обращения в голосовом канале.
• voice.tts объединяется поверх messages.tts; провайдеры с поддержкой потоковой передачи отправляют данные непосредственно проигрывателю, а в противном случае полученный аудиофайл воспроизводится в подключённом канале.

Пример стандартного сеанса голосового канала с проксированием через агента:

{  channels: {    discord: {      voice: {        enabled: true,        model: "openai/gpt-5.6-sol",        followUsersEnabled: true,        followUsers: ["123456789012345678"],        realtime: {          provider: "openai",          model: "gpt-realtime-2.1",          speakerVoice: "cedar",        },      },    },  },}

Если блок voice.agentSession отсутствует, каждый голосовой канал получает отдельный маршрутизируемый сеанс OpenClaw. Например, /vc join channel:234567890123456789 взаимодействует с сеансом соответствующего голосового канала Discord. Модель реального времени служит только голосовым интерфейсом; содержательные запросы передаются настроенному агенту OpenClaw. Если модель реального времени создаёт окончательную транскрипцию без вызова инструмента консультации, OpenClaw принудительно вызывает консультацию как резервный механизм, чтобы стандартное поведение по-прежнему соответствовало разговору с агентом.

Пример устаревшего режима STT и TTS:

{  channels: {    discord: {      voice: {        enabled: true,        mode: "stt-tts",        model: "openai/gpt-5.4-mini",        tts: {          provider: "openai",          providers: {            openai: {              model: "gpt-4o-mini-tts",              speakerVoice: "cedar",            },          },        },      },    },  },}

Пример двунаправленного режима реального времени:

{  channels: {    discord: {      voice: {        enabled: true,        mode: "bidi",        model: "openai/gpt-5.6-sol",        realtime: {          provider: "openai",          model: "gpt-realtime-2.1",          speakerVoice: "cedar",          toolPolicy: "safe-read-only",          consultPolicy: "always",        },      },    },  },}

Голосовой режим как расширение существующего сеанса канала Discord:

{  channels: {    discord: {      voice: {        enabled: true,        mode: "agent-proxy",        model: "openai/gpt-5.6-sol",        agentSession: {          mode: "target",          target: "channel:123456789012345678",        },        realtime: {          provider: "openai",          model: "gpt-realtime-2.1",          speakerVoice: "cedar",        },      },    },  },}

В режиме agent-proxy бот подключается к настроенному голосовому каналу, но обращения к агенту OpenClaw используют обычный маршрутизируемый сеанс и агента целевого канала. Голосовой сеанс реального времени озвучивает возвращённый результат в голосовом канале. Агент-супервизор по-прежнему может использовать обычные инструменты сообщений в соответствии со своей политикой инструментов, включая отправку отдельного сообщения в Discord, если это подходящее действие.

Пока выполняется делегированный запуск OpenClaw, новые голосовые транскрипции Discord рассматриваются как команды управления активным запуском, прежде чем будет начато очередное обращение к агенту. Фразы наподобие «статус», «отмени это», «используй более компактное исправление» или «когда закончишь, также проверь тесты» классифицируются как запрос состояния, отмена, корректирующее указание или последующее действие для активного сеанса. Результаты запроса состояния, отмены, принятого корректирующего указания и последующего действия озвучиваются в голосовом канале, чтобы вызывающий пользователь знал, обработал ли OpenClaw запрос.

Полезные формы целевых объектов:

• target: "channel:123456789012345678" направляет запрос через сеанс текстового канала Discord.
• target: "123456789012345678" рассматривается как целевой канал.
• target: "dm:123456789012345678" или target: "user:123456789012345678" направляет запрос через соответствующий сеанс личных сообщений.

Пример OpenAI Realtime для среды с сильным эхом:

{  channels: {    discord: {      voice: {        enabled: true,        mode: "bidi",        model: "openai/gpt-5.6-sol",        realtime: {          provider: "openai",          model: "gpt-realtime-2.1",          speakerVoice: "cedar",          bargeIn: true,          minBargeInAudioEndMs: 500,          consultPolicy: "always",          providers: {            openai: {              interruptResponseOnInputAudio: false,            },          },        },      },    },  },}

Используйте эту конфигурацию, когда модель слышит собственное воспроизведение Discord через открытый микрофон, но вы всё равно хотите иметь возможность прервать её голосом. OpenClaw запрещает OpenAI автоматически прерывать ответ при поступлении необработанного входного аудио, а bargeIn: true позволяет событиям начала речи в Discord и уже активному аудио говорящего отменять активные ответы реального времени до того, как следующий захваченный голосовой фрагмент поступит в OpenAI. Слишком ранние сигналы прерывания со значением audioEndMs ниже minBargeInAudioEndMs считаются вероятным эхом или шумом и игнорируются, чтобы модель не обрывала ответ на первом кадре воспроизведения.

Ожидаемые голосовые журналы:

• При подключении: discord voice: joining ... voiceSession=... supervisorSession=... agentSessionMode=... voiceModel=... realtimeModel=...
• При запуске режима реального времени: discord voice: realtime bridge starting ... autoRespond=false interruptResponse=false bargeIn=false minBargeInAudioEndMs=...
• При получении аудио говорящего: discord voice: realtime speaker turn opened ..., discord voice: realtime input audio started ... outputAudioMs=... outputActive=... и discord voice: realtime speaker turn closed ... chunks=... discordBytes=... realtimeBytes=... interruptedPlayback=...
• При пропуске устаревшей речи: discord voice: realtime forced agent consult skipped reason=incomplete-transcript ... или reason=non-actionable-closing ...
• При завершении ответа реального времени: discord voice: realtime audio playback finishing reason=response.done ... audioMs=... chunks=...
• При остановке или сбросе воспроизведения: discord voice: realtime audio playback stopped reason=... audioMs=... elapsedMs=... chunks=...
• При консультации в реальном времени: discord voice: realtime consult requested ... voiceSession=... supervisorSession=... question=...
• При ответе агента: discord voice: agent turn answer ...
• При постановке точной речи в очередь: discord voice: realtime exact speech queued ... queued=... outputAudioMs=... outputActive=..., затем discord voice: realtime exact speech dequeued reason=player-idle ...
• При обнаружении голосового прерывания: discord voice: realtime barge-in detected source=speaker-start ... или discord voice: realtime barge-in detected source=active-speaker-audio ..., затем discord voice: realtime barge-in requested reason=... outputAudioMs=... outputActive=...
• При прерывании ответа реального времени: discord voice: realtime model interrupt requested client:response.cancel reason=barge-in, затем discord voice: realtime model audio truncated client:conversation.item.truncate reason=barge-in audioEndMs=... или discord voice: realtime model interrupt confirmed server:response.done status=cancelled ...
• При игнорировании эха или шума: discord voice: realtime model interrupt ignored client:conversation.item.truncate.skipped reason=barge-in audioEndMs=0 minAudioEndMs=250
• При отключённом голосовом прерывании: discord voice: realtime capture ignored during playback (barge-in disabled) ...
• При бездействующем воспроизведении: discord voice: realtime barge-in ignored reason=... outputActive=false ... playbackChunks=0

Для диагностики обрыва аудио рассматривайте журналы голосового режима реального времени как временную шкалу:

1. realtime audio playback started означает, что Discord начал воспроизводить аудио ассистента. С этого момента мост начинает подсчитывать фрагменты вывода ассистента, байты PCM Discord, байты данных реального времени провайдера и длительность синтезированного аудио.
2. realtime speaker turn opened отмечает начало активности говорящего в Discord. Если воспроизведение уже активно и включён bargeIn, далее может следовать barge-in detected source=speaker-start.
3. realtime input audio started отмечает первый фактически полученный аудиокадр для этого фрагмента речи говорящего. outputActive=true или ненулевое значение outputAudioMs здесь означает, что микрофон отправляет входные данные, пока воспроизведение аудио ассистента ещё активно.
4. barge-in detected source=active-speaker-audio означает, что OpenClaw обнаружил поступающее аудио говорящего во время активного воспроизведения аудио ассистента. Это помогает отличить фактическое прерывание от события начала речи в Discord без полезного аудио.
5. barge-in requested reason=... означает, что OpenClaw запросил у провайдера реального времени отмену или усечение активного ответа. Запись содержит outputAudioMs, outputActive и playbackChunks, чтобы можно было увидеть, сколько аудио ассистента фактически было воспроизведено до прерывания.
6. realtime audio playback stopped reason=... — это точка локального сброса воспроизведения Discord. Причина указывает, кто остановил воспроизведение: barge-in, player-idle, provider-clear-audio, forced-agent-consult, stream-close или session-close.
7. realtime speaker turn closed содержит сводку по захваченному фрагменту входной речи. chunks=0 или hasAudio=false означает, что фрагмент речи говорящего начался, но пригодное для использования аудио не поступило в мост реального времени. interruptedPlayback=true означает, что этот фрагмент входной речи наложился на вывод ассистента и запустил логику голосового прерывания.

Полезные поля:

• outputAudioMs: длительность аудио ассистента, созданного провайдером реального времени до этой строки журнала.
• audioMs: длительность аудио ассистента, подсчитанная OpenClaw до остановки воспроизведения.
• elapsedMs: время по часам между открытием и закрытием потока воспроизведения или фрагмента речи говорящего.
• discordBytes: байты стереофонического PCM с частотой 48 кГц, отправленные в голосовой канал Discord или полученные из него.
• realtimeBytes: байты PCM в формате провайдера, отправленные провайдеру реального времени или полученные от него.
• playbackChunks: фрагменты аудио ассистента, переданные в Discord для активного ответа.
• sinceLastAudioMs: интервал между последним захваченным аудиокадром говорящего и завершением фрагмента речи говорящего.

Распространённые шаблоны:

• Немедленное прерывание при source=active-speaker-audio, небольшом outputAudioMs и нахождении того же пользователя рядом обычно указывает на то, что эхо динамика попадает в микрофон. Увеличьте voice.realtime.minBargeInAudioEndMs, уменьшите громкость динамика, используйте наушники или задайте voice.realtime.providers.openai.interruptResponseOnInputAudio: false.
• source=speaker-start, за которым следует speaker turn closed ... hasAudio=false, означает, что Discord сообщил о начале речи, но звук не достиг OpenClaw. Причиной может быть кратковременное голосовое событие Discord, работа шумового порога или кратковременное включение микрофона клиентом.
• audio playback stopped reason=stream-close без близкого по времени перебивания или provider-clear-audio означает, что локальный поток воспроизведения Discord неожиданно завершился. Проверьте предшествующие журналы провайдера и проигрывателя Discord.
• capture ignored during playback (barge-in disabled) означает, что OpenClaw намеренно отбросил входной звук во время воспроизведения звука ассистента. Включите voice.realtime.bargeIn, если хотите, чтобы речь прерывала воспроизведение.
• barge-in ignored ... outputActive=false означает, что VAD Discord или провайдера обнаружил речь, но в OpenClaw не было активного воспроизведения, которое можно было бы прервать. Это не должно прерывать звук.

Учетные данные разрешаются отдельно для каждого компонента: аутентификация маршрута LLM для voice.model, аутентификация STT для tools.media.audio, аутентификация TTS для messages.tts/voice.tts и аутентификация провайдера реального времени для voice.realtime.providers либо обычная конфигурация аутентификации провайдера.

Голосовые сообщения

Голосовые сообщения Discord показывают предварительный просмотр звуковой волны и требуют аудио OGG/Opus. OpenClaw автоматически создает звуковую волну, но для анализа и преобразования на хосте Gateway необходимы ffmpeg и ffprobe.

• Укажите путь к локальному файлу (URL-адреса отклоняются).
• Не указывайте текстовое содержимое (Discord отклоняет текст и голосовое сообщение в одной полезной нагрузке).
• Допускается любой аудиоформат; при необходимости OpenClaw преобразует его в OGG/Opus.

message(action="send", channel="discord", target="channel:123", path="/path/to/audio.mp3", asVoice=true)

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

openclaw doctoropenclaw channels status --probeopenclaw logs --follow

{channels: {discord: {  accounts: {    default: {      eventQueue: {        listenerTimeout: 120000,      },    },  },},},}

{channels: {defaults: {  botLoopProtection: {    maxEventsPerWindow: 20,    windowSeconds: 60,    cooldownSeconds: 60,  },},discord: {  // Необязательное переопределение для всего Discord. Блоки учетных записей переопределяют отдельные  // поля и наследуют отсюда пропущенные поля.  botLoopProtection: {    maxEventsPerWindow: 4,  },  accounts: {    alpha: {      // Alpha принимает сообщения других ботов, только когда они упоминают его.      allowBots: "mentions",    },    bravo: {      // Bravo принимает все сообщения Discord, созданные ботами.      allowBots: true,      mentionAliases: {        // Позволяет Bravo записать упоминание Alpha в Discord с настроенным идентификатором пользователя.        Alpha: "ALPHA_DISCORD_USER_ID",      },      botLoopProtection: {        // Разрешить до пяти сообщений в минуту перед блокировкой пары.        maxEventsPerWindow: 5,        windowSeconds: 60,        cooldownSeconds: 90,      },    },  },},},}

Справочник по конфигурации

Основной справочник: Справочник по конфигурации — Discord.

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

• Считайте токены ботов секретами (в контролируемых средах предпочтительно использовать DISCORD_BOT_TOKEN).
• Предоставляйте Discord минимально необходимые разрешения.
• Если развертывание или состояние команд устарело, перезапустите Gateway и повторно проверьте с помощью openclaw channels status --probe.

Связанные материалы