Discord

Готово для DM і каналів гільдії через офіційний Discord gateway.

Швидке налаштування

Вам потрібно створити новий застосунок із ботом, додати бота на свій сервер і сполучити його з 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>

Рекомендовано: налаштуйте робочий простір гільдії

Коли DM запрацюють, ви можете налаштувати свій сервер Discord як повноцінний робочий простір, де кожен канал отримує власну сесію агента з власним контекстом. Це рекомендовано для приватних серверів, де є лише ви та ваш бот.

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

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

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

Runtime-модель

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

Форумні канали

Форумні та медіаканали Discord приймають лише дописи в гілках. OpenClaw підтримує два способи їх створення:

• Надішліть повідомлення до батьківського форуму (channel:<forumId>), щоб автоматично створити гілку. Назва гілки використовує перший непорожній рядок вашого повідомлення.
• Використайте openclaw message thread create, щоб створити гілку напряму. Не передавайте --message-id для форумних каналів.

Приклад: надішліть до батьківського форуму, щоб створити гілку

openclaw message send --channel discord --target channel:<forumId> \  --message "Topic title\nBody of the post"

Приклад: явно створіть форумну гілку

openclaw message thread create --channel discord --target channel:<forumId> \  --thread-name "Topic title" --message "Body of the post"

Батьківські форуми не приймають компоненти Discord. Якщо вам потрібні компоненти, надсилайте до самої гілки (channel:<threadId>).

Інтерактивні компоненти

OpenClaw підтримує контейнери компонентів Discord v2 для повідомлень агента. Використовуйте інструмент повідомлень із payload components. Результати взаємодій маршрутизуються назад до агента як звичайні вхідні повідомлення й дотримуються наявних налаштувань Discord replyToMode.

Підтримувані блоки:

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

За замовчуванням компоненти одноразові. Установіть components.reusable=true, щоб дозволити використовувати кнопки, вибір і форми кілька разів, доки вони не завершать термін дії.

Щоб обмежити, хто може натиснути кнопку, задайте allowedUsers для цієї кнопки (ідентифікатори користувачів Discord, теги або *). Коли налаштовано, користувачі, які не збігаються, отримують ефемерну відмову.

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

Slash-команди /model і /models відкривають інтерактивний вибір моделі з випадаючими списками провайдера, моделі та сумісного runtime, а також кроком 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: "Optional fallback text",  components: {    reusable: true,    text: "Choose a path",    blocks: [      {        type: "actions",        buttons: [          {            label: "Approve",            style: "success",            allowedUsers: ["123456789012345678"],          },          { label: "Decline", style: "danger" },        ],      },      {        type: "actions",        select: {          type: "string",          placeholder: "Pick an option",          options: [            { label: "Option A", value: "a" },            { label: "Option B", value: "b" },          ],        },      },    ],    modal: {      title: "Details",      triggerLabel: "Open form",      fields: [        { type: "text", label: "Requester" },        {          type: "select",          label: "Priority",          options: [            { label: "Low", value: "low" },            { label: "High", 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: { allow: true },        help: { allow: true, requireMention: true },      },    },  },},},}

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

Використовуйте bindings[].match.roles, щоб маршрутизувати учасників Discord guild до різних агентів за ID ролі. Прив’язки на основі ролей приймають лише ID ролей і оцінюються після прив’язок peer або parent-peer та перед прив’язками лише для guild. Якщо прив’язка також задає інші поля match (наприклад, 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 пропускає реєстрацію та очищення slash-команд Discord під час запуску. Раніше зареєстровані команди можуть залишатися видимими в Discord, доки ви не видалите їх із застосунку Discord.
• Авторизація нативних команд використовує ті самі allowlist-и/політики Discord, що й звичайна обробка повідомлень.
• Команди все ще можуть бути видимими в інтерфейсі Discord для користувачів, які не авторизовані; виконання все одно застосовує авторизацію OpenClaw і повертає "не авторизовано".

Див. Slash-команди щодо каталогу команд і поведінки.

Типові налаштування slash-команд:

• ephemeral: true

Деталі функцій

{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: {    Vladislava: "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.*.

Поведінка шлюзу за замовчуванням:

UI Components v2

OpenClaw використовує компоненти Discord v2 для exec approvals і маркерів між контекстами. Дії повідомлень Discord також можуть приймати components для користувацького UI (розширено; потребує створення component payload через інструмент discord), тоді як застарілі embeds лишаються доступними, але не рекомендуються.

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

Приклад:

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

Голос

Discord має дві окремі голосові поверхні: realtime голосові канали (безперервні розмови) і вкладення голосових повідомлень (формат попереднього перегляду waveform). 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.5",        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",          speakerVoice: "cedar",        },      },    },  },}

Примітки:

• voice.tts перевизначає messages.tts лише для голосового відтворення stt-tts. Режими реального часу використовують voice.realtime.speakerVoice.
• 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 плюс мозку Codex використовуйте voice.realtime.model: "gpt-realtime-2" і voice.model: "openai/gpt-5.5".
• Голосові режими реального часу за замовчуванням включають невеликі профільні файли 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 для негайного переривання в кімнатах із низьким відлунням або збільште значення для конфігурацій динаміків із сильним відлунням.
• Для голосу OpenAI під час відтворення в Discord задайте voice.tts.provider: "openai" і виберіть голос Text-to-speech у voice.tts.providers.openai.speakerVoice. cedar — хороший варіант із маскулінним звучанням у поточній моделі OpenAI TTS.
• Перевизначення systemPrompt для окремих каналів Discord застосовуються до голосових транскрибованих реплік для цього голосового каналу.
• Голосові транскрибовані репліки визначають статус власника з Discord allowFrom (або dm.allowFrom) для команд і дій каналу, обмежених власником. Видимість інструментів агента відповідає налаштованій політиці інструментів для маршрутизованої сесії.
• Голос Discord є опціональним для конфігурацій лише з текстом; задайте channels.discord.voice.enabled=true (або збережіть наявний блок channels.discord.voice), щоб увімкнути команди /vc, голосове середовище виконання та Gateway intent GuildVoiceStates.
• channels.discord.intents.voiceStates може явно перевизначити підписку на intent стану голосу. Залиште це поле незаданим, щоб intent відповідав фактичному ввімкненню голосу.
• Якщо voice.autoJoin має кілька записів для тієї самої гільдії, OpenClaw приєднується до останнього налаштованого каналу для цієї гільдії.
• voice.allowedChannels — необов'язковий список дозволеного перебування. Залиште його незаданим, щоб дозволити /vc join у будь-який авторизований голосовий канал Discord. Коли задано, /vc join, автоматичне приєднання під час запуску та переміщення голосового стану бота обмежуються переліченими записами { guildId, channelId }. Задайте порожній масив, щоб заборонити всі голосові приєднання Discord. Якщо Discord перемістить бота за межі списку дозволених, OpenClaw вийде з цього каналу й повторно приєднається до налаштованої цілі автоматичного приєднання, коли вона доступна.
• voice.daveEncryption і voice.decryptionFailureTolerance передаються напряму до параметрів приєднання @discordjs/voice.
• Стандартні значення @discordjs/voice — daveEncryption=true і decryptionFailureTolerance=24, якщо не задано.
• OpenClaw використовує вбудований кодек libopus-wasm для приймання голосу Discord і відтворення необробленого PCM у реальному часі. Він постачається із зафіксованою збіркою libopus WebAssembly і не потребує нативних додатків opus.
• voice.connectTimeoutMs керує початковим очікуванням Ready @discordjs/voice для /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 містить виправлення заповнення з upstream із PR discord.js #11449, яке закрило issue discord.js #11419.
• Події приймання The operation was aborted очікувані, коли OpenClaw фіналізує захоплений сегмент мовця; це докладна діагностика, а не попередження.
• Докладні журнали голосу Discord включають обмежений однорядковий попередній перегляд STT-транскрипту для кожного прийнятого сегмента мовця, тож налагодження показує і сторону користувача, і сторону відповіді агента без вивантаження необмеженого тексту транскрипту.
• У режимі agent-proxy примусовий запасний шлях консультації пропускає ймовірно неповні фрагменти транскрипту, як-от текст, що закінчується на ... або кінцевий сполучник на кшталт and, а також очевидні неакційні завершення на кшталт “be right back” або “bye”. Журнали показують 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, щоб зберегти список, але зупинити автоматичне голосове стеження.
• Коли відстежуваний користувач приєднується до дозволеного голосового каналу, 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.
• Відтворення файлів і потоків провайдера транскодує аудіо в сирий стерео PCM 48 кГц за допомогою ffmpeg, а потім використовує libopus-wasm для потоку пакетів Opus, що надсилається до Discord.

Конвеєр STT плюс TTS:

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

Приклад сеансу голосового каналу agent-proxy за замовчуванням:

{  channels: {    discord: {      voice: {        enabled: true,        model: "openai/gpt-5.5",        followUsersEnabled: true,        followUsers: ["123456789012345678"],        realtime: {          provider: "openai",          model: "gpt-realtime-2",          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",            },          },        },      },    },  },}

Приклад двонапрямного Realtime:

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

Голос як розширення наявного сеансу каналу Discord:

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

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

Поки делегований запуск OpenClaw активний, нові голосові транскрипти Discord розглядаються як керування живим запуском перед початком іншого ходу агента. Фрази на кшталт "status", "cancel that", "use the smaller fix" або "when you're done also check tests" класифікуються як статус, скасування, спрямування або подальший ввід для активного сеансу. Результати статусу, скасування, прийнятого спрямування та подальших дій промовляються назад у голосовий канал, щоб абонент знав, чи 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.5",        realtime: {          provider: "openai",          model: "gpt-realtime-2",          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 почав відтворювати аудіо асистента. Із цього моменту міст починає рахувати вихідні фрагменти асистента, байти Discord PCM, байти реального часу провайдера та тривалість синтезованого аудіо.
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 генерує хвилю автоматично, але потребує ffmpeg і ffprobe на хості Gateway для перевірки та перетворення.

• Укажіть локальний шлях до файлу (URL відхиляються).
• Не додавайте текстовий вміст (Discord відхиляє текст + голосове повідомлення в одному payload).
• Приймається будь-який аудіоформат; 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: {  // Optional Discord-wide override. Account blocks override individual  // fields and inherit omitted fields from here.  botLoopProtection: {    maxEventsPerWindow: 4,  },  accounts: {    mantis: {      // Mantis listens to other bots only when they mention her.      allowBots: "mentions",    },    molty: {      // Molty listens to all bot-authored Discord messages.      allowBots: true,      mentionAliases: {        // Lets Molty write a Mantis Discord mention with the configured user id.        Mantis: "MANTIS_DISCORD_USER_ID",      },      botLoopProtection: {        // Allow up to five messages per minute before suppressing the pair.        maxEventsPerWindow: 5,        windowSeconds: 60,        cooldownSeconds: 90,      },    },  },},},}

Довідник конфігурації

Основний довідник: Довідник конфігурації - Discord.

Безпека й експлуатація

• Ставтеся до токенів ботів як до секретів (DISCORD_BOT_TOKEN бажано в керованих середовищах).
• Надавайте Discord дозволи з найменшими необхідними привілеями.
• Якщо deploy/state команд застаріли, перезапустіть gateway і повторно перевірте за допомогою openclaw channels status --probe.

Пов’язане