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 до сеансу розмови, визначеного маршрутизацією.
• Доставка текстових оголошень Cron/Heartbeat у Discord зводиться до остаточної видимої відповіді асистента, яка надсилається один раз. Медіадані та структуровані корисні навантаження компонентів залишаються багатоповідомленнєвими, коли агент створює кілька корисних навантажень для доставки.

Канали форумів

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

• Надішліть повідомлення до батьківського форуму (channel:<forumId>) для автоматичного створення гілки. Назвою гілки стане перший непорожній рядок повідомлення (обрізаний відповідно до обмеження Discord у 100 символів для назви гілки).
• Використовуйте 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 для повідомлень агента. Використовуйте інструмент повідомлень із корисним навантаженням 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 години). Довший термін дії підходить для процесів перевірки та схвалення, у яких кнопки мають залишатися доступними, але він подовжує період, протягом якого старе повідомлення Discord усе ще може ініціювати дію. Вибирайте найкоротший придатний термін дії та зберігайте значення за замовчуванням, якщо застарілі зворотні виклики можуть спричинити неочікувану поведінку.

Команди з косою рискою /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: "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: { 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_...", // необов’язково; потрібно для приватних систем  },},},}

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

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

{channels: {discord: {  activity: "Час зосередженої роботи",  activityType: 4,},},}

{channels: {discord: {  activity: "Програмування наживо",  activityType: 1,  activityUrl: "https://twitch.tv/openclaw",},},}

{channels: {discord: {  autoPresence: {    enabled: true,    intervalMs: 30000,    minUpdateIntervalMs: 15000,    exhaustedText: "токен вичерпано",  },},},}

Інструменти та обмеження дій

Дії з повідомленнями 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.
• Перевизначення systemPrompt для окремих каналів Discord застосовуються до реплік із голосових транскриптів відповідного голосового каналу.
• Для команд і дій каналу, доступних лише власнику, статус власника для реплік із голосових транскриптів визначається за allowFrom (або dm.allowFrom) у Discord. Видимість інструментів агента відповідає налаштованій політиці інструментів спрямованого сеансу.
• Якщо 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 визначає час початкового очікування стану 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 містить виправлення доповнення з 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, щоб зберегти список, але припинити автоматичне слідування в голосових каналах.
• Коли відстежуваний користувач приєднується до дозволеного голосового каналу, 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 і запитує повернення тексту, оскільки остаточним відтворенням 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 означає, що Discord або VAD провайдера виявив мовлення, але 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: {  // Optional Discord-wide override. Account blocks override individual  // fields and inherit omitted fields from here.  botLoopProtection: {    maxEventsPerWindow: 4,  },  accounts: {    alpha: {      // Alpha listens to other bots only when they mention it.      allowBots: "mentions",    },    bravo: {      // Bravo listens to all bot-authored Discord messages.      allowBots: true,      mentionAliases: {        // Lets Bravo write an Alpha Discord mention with the configured user id.        Alpha: "ALPHA_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 дозволи за принципом найменших привілеїв.
• Якщо розгортання або стан команд застаріли, перезапустіть Gateway і повторно перевірте за допомогою openclaw channels status --probe.

Пов’язані матеріали