Discord

Siap untuk DM dan kanal guild melalui Gateway Discord resmi.

Penyiapan cepat

Anda perlu membuat aplikasi baru dengan bot, menambahkan bot ke server Anda, dan memasangkannya ke OpenClaw. Kami menyarankan untuk menambahkan bot Anda ke server privat milik Anda sendiri. Jika Anda belum memilikinya, buat terlebih dahulu (pilih 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>

Disarankan: Siapkan ruang kerja guild

Setelah DM berfungsi, Anda dapat menyiapkan server Discord Anda sebagai ruang kerja penuh tempat setiap kanal mendapatkan sesi agennya sendiri dengan konteksnya sendiri. Ini disarankan untuk server privat yang hanya berisi Anda dan bot Anda.

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

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

Sekarang buat beberapa kanal di server Discord Anda dan mulai chat. Agen Anda dapat melihat nama kanal, dan setiap kanal mendapatkan sesinya sendiri yang terisolasi — sehingga Anda dapat menyiapkan #coding, #home, #research, atau apa pun yang cocok dengan alur kerja Anda.

Model runtime

• Gateway memiliki koneksi Discord.
• Perutean balasan bersifat deterministik: balasan masuk Discord kembali ke Discord.
• Metadata guild/saluran Discord ditambahkan ke prompt model sebagai konteks yang tidak tepercaya, bukan sebagai prefiks balasan yang terlihat pengguna. Jika model menyalin envelope itu kembali, OpenClaw menghapus metadata yang disalin dari balasan keluar dan dari konteks replay berikutnya.
• Secara default (session.dmScope=main), chat langsung berbagi sesi utama agen (agent:main:main).
• Saluran guild menggunakan kunci sesi terisolasi (agent:<agentId>:discord:channel:<channelId>).
• DM grup diabaikan secara default (channels.discord.dm.groupEnabled=false).
• Perintah slash native berjalan dalam sesi perintah terisolasi (agent:<agentId>:discord:slash:<userId>), sambil tetap membawa CommandTargetSessionKey ke sesi percakapan yang dirutekan.
• Pengiriman pengumuman cron/heartbeat khusus teks ke Discord menggunakan jawaban akhir yang terlihat asisten satu kali. Payload media dan komponen terstruktur tetap berupa beberapa pesan ketika agen mengeluarkan beberapa payload yang dapat dikirim.

Saluran forum

Saluran forum dan media Discord hanya menerima postingan thread. OpenClaw mendukung dua cara untuk membuatnya:

• Kirim pesan ke induk forum (channel:<forumId>) untuk membuat thread otomatis. Judul thread menggunakan baris pertama yang tidak kosong dari pesan Anda.
• Gunakan openclaw message thread create untuk membuat thread secara langsung. Jangan berikan --message-id untuk saluran forum.

Contoh: kirim ke induk forum untuk membuat thread

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

Contoh: buat thread forum secara eksplisit

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

Induk forum tidak menerima komponen Discord. Jika Anda membutuhkan komponen, kirim ke thread itu sendiri (channel:<threadId>).

Komponen interaktif

OpenClaw mendukung kontainer komponen Discord v2 untuk pesan agen. Gunakan alat pesan dengan payload components. Hasil interaksi dirutekan kembali ke agen sebagai pesan masuk normal dan mengikuti pengaturan Discord replyToMode yang ada.

Blok yang didukung:

• text, section, separator, actions, media-gallery, file
• Baris tindakan mengizinkan hingga 5 tombol atau satu menu pilihan
• Jenis pilihan: string, user, role, mentionable, channel

Secara default, komponen hanya sekali pakai. Atur components.reusable=true untuk mengizinkan tombol, pilihan, dan formulir digunakan beberapa kali hingga kedaluwarsa.

Untuk membatasi siapa yang dapat mengeklik tombol, atur allowedUsers pada tombol tersebut (ID pengguna Discord, tag, atau *). Saat dikonfigurasi, pengguna yang tidak cocok menerima penolakan ephemeral.

Callback komponen kedaluwarsa setelah 30 menit secara default. Atur channels.discord.agentComponents.ttlMs untuk mengubah masa pakai registri callback tersebut untuk akun Discord default, atau channels.discord.accounts.<accountId>.agentComponents.ttlMs untuk menimpa satu akun dalam setup multi-akun. Nilainya dalam milidetik, harus berupa bilangan bulat positif, dan dibatasi pada 86400000 (24 jam). TTL yang lebih panjang berguna untuk alur kerja review atau persetujuan yang membutuhkan tombol tetap dapat digunakan, tetapi juga memperpanjang jendela ketika pesan Discord lama masih dapat memicu tindakan. Pilih TTL tersingkat yang sesuai dengan alur kerja, dan pertahankan default ketika callback basi akan mengejutkan.

Perintah slash /model dan /models membuka pemilih model interaktif dengan dropdown provider, model, dan runtime kompatibel, ditambah langkah Submit. /models add sudah deprecated dan sekarang mengembalikan pesan deprecation alih-alih mendaftarkan model dari chat. Balasan pemilih bersifat ephemeral dan hanya pengguna yang memanggilnya yang dapat menggunakannya. Menu pilihan Discord dibatasi hingga 25 opsi, jadi tambahkan entri provider/* ke agents.defaults.models saat Anda ingin pemilih menampilkan model yang ditemukan secara dinamis hanya untuk provider yang dipilih seperti openai atau vllm.

Lampiran file:

• Blok file harus menunjuk ke referensi lampiran (attachment://<filename>)
• Sediakan lampiran melalui media/path/filePath (satu file); gunakan media-gallery untuk beberapa file
• Gunakan filename untuk menimpa nama unggahan ketika harus cocok dengan referensi lampiran

Formulir modal:

• Tambahkan components.modal dengan hingga 5 bidang
• Jenis bidang: text, checkbox, radio, select, role-select, user-select
• OpenClaw menambahkan tombol pemicu secara otomatis

Contoh:

{  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" },          ],        },      ],    },  },}

Kontrol akses dan perutean

{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 },      },    },  },},},}

Perutean agen berbasis role

Gunakan bindings[].match.roles untuk merutekan anggota guild Discord ke agent berbeda berdasarkan ID peran. Binding berbasis peran hanya menerima ID peran dan dievaluasi setelah binding peer atau parent-peer dan sebelum binding khusus guild. Jika sebuah binding juga menetapkan kolom match lain (misalnya peer + guildId + roles), semua kolom yang dikonfigurasi harus cocok.

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

Perintah native dan autentikasi perintah

• commands.native default-nya "auto" dan diaktifkan untuk Discord.
• Override per channel: channels.discord.commands.native.
• commands.native=false melewati pendaftaran dan pembersihan perintah slash Discord saat startup. Perintah yang sebelumnya terdaftar mungkin tetap terlihat di Discord sampai Anda menghapusnya dari aplikasi Discord.
• Autentikasi perintah native menggunakan allowlist/kebijakan Discord yang sama seperti penanganan pesan normal.
• Perintah mungkin tetap terlihat di UI Discord bagi pengguna yang tidak diotorisasi; eksekusi tetap menerapkan autentikasi OpenClaw dan mengembalikan "tidak diotorisasi".

Lihat Perintah slash untuk katalog dan perilaku perintah.

Pengaturan perintah slash default:

• ephemeral: true

Detail fitur

{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",  },},},}

Alat dan gerbang tindakan

Tindakan pesan Discord mencakup tindakan perpesanan, admin saluran, moderasi, presence, dan metadata.

Contoh inti:

• perpesanan: sendMessage, readMessages, editMessage, deleteMessage, threadReply
• reaksi: react, reactions, emojiList
• moderasi: timeout, kick, ban
• presence: setPresence

Tindakan event-create menerima parameter image opsional (URL atau jalur file lokal) untuk menetapkan gambar sampul acara terjadwal.

Gerbang tindakan berada di bawah channels.discord.actions.*.

Perilaku gerbang default:

UI komponen v2

OpenClaw menggunakan komponen Discord v2 untuk persetujuan exec dan penanda lintas konteks. Tindakan pesan Discord juga dapat menerima components untuk UI kustom (lanjutan; memerlukan pembuatan payload komponen melalui alat discord), sementara embeds legacy tetap tersedia tetapi tidak direkomendasikan.

• channels.discord.ui.components.accentColor menetapkan warna aksen yang digunakan oleh kontainer komponen Discord (hex).
• Tetapkan per akun dengan channels.discord.accounts.<id>.ui.components.accentColor.
• channels.discord.agentComponents.ttlMs mengontrol berapa lama callback komponen Discord yang dikirim tetap terdaftar (default 1800000, maksimum 86400000). Tetapkan per akun dengan channels.discord.accounts.<id>.agentComponents.ttlMs.
• embeds diabaikan ketika komponen v2 tersedia.
• Pratinjau URL polos ditekan secara default. Tetapkan suppressEmbeds: false pada tindakan pesan ketika satu tautan keluar harus diperluas.

Contoh:

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

Suara

Discord memiliki dua permukaan suara yang berbeda: saluran suara realtime (percakapan berkelanjutan) dan lampiran pesan suara (format pratinjau gelombang). Gateway mendukung keduanya.

Saluran suara

Checklist penyiapan:

1. Aktifkan Message Content Intent di Discord Developer Portal.
2. Aktifkan Server Members Intent ketika daftar izin peran/pengguna digunakan.
3. Undang bot dengan cakupan bot dan applications.commands.
4. Berikan Connect, Speak, Send Messages, dan Read Message History di saluran suara target.
5. Aktifkan perintah native (commands.native atau channels.discord.commands.native).
6. Konfigurasi channels.discord.voice.

Gunakan /vc join|leave|status untuk mengontrol sesi. Perintah ini menggunakan agen default akun dan mengikuti aturan daftar izin serta kebijakan grup yang sama seperti perintah Discord lainnya.

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

Untuk memeriksa izin efektif bot sebelum bergabung, jalankan:

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

Contoh auto-join:

{  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",        },      },    },  },}

Catatan:

• voice.tts menimpa messages.tts hanya untuk pemutaran suara stt-tts. Mode realtime menggunakan voice.realtime.speakerVoice.
• voice.mode mengontrol jalur percakapan. Defaultnya adalah agent-proxy: antarmuka depan suara realtime menangani waktu giliran, interupsi, dan pemutaran, mendelegasikan pekerjaan substantif ke agen OpenClaw yang dirutekan melalui openclaw_agent_consult, dan memperlakukan hasilnya seperti prompt Discord yang diketik dari pembicara tersebut. stt-tts mempertahankan alur lama STT batch plus TTS. bidi memungkinkan model realtime bercakap langsung sambil mengekspos openclaw_agent_consult untuk otak OpenClaw.
• voice.agentSession mengontrol percakapan OpenClaw mana yang menerima giliran suara. Biarkan tidak disetel untuk sesi milik kanal suara, atau setel { mode: "target", target: "channel:<text-channel-id>" } agar kanal suara bertindak sebagai ekstensi mikrofon/speaker dari sesi kanal teks Discord yang sudah ada seperti #maintainers.
• voice.model menimpa otak agen OpenClaw untuk respons suara Discord dan konsultasi realtime. Biarkan tidak disetel untuk mewarisi model agen yang dirutekan. Ini terpisah dari voice.realtime.model.
• voice.followUsers memungkinkan bot bergabung, berpindah, dan keluar dari suara Discord bersama pengguna yang dipilih. Lihat Ikuti pengguna dalam suara untuk aturan perilaku dan contoh.
• agent-proxy merutekan ucapan melalui discord-voice, yang mempertahankan otorisasi owner/tool normal untuk pembicara dan sesi target tetapi menyembunyikan tool tts agen karena suara Discord memiliki pemutaran. Secara default, agent-proxy memberi konsultasi akses tool penuh yang setara owner untuk pembicara owner (voice.realtime.toolPolicy: "owner") dan sangat memprioritaskan konsultasi dengan agen OpenClaw sebelum jawaban substantif (voice.realtime.consultPolicy: "always"). Dalam mode default always itu, lapisan realtime tidak otomatis mengucapkan pengisi sebelum jawaban konsultasi; lapisan ini menangkap dan mentranskripsi ucapan, lalu mengucapkan jawaban OpenClaw yang dirutekan. Jika beberapa jawaban konsultasi paksa selesai saat Discord masih memutar jawaban pertama, jawaban ucapan persis berikutnya diantrekan sampai pemutaran idle, alih-alih mengganti ucapan di tengah kalimat.
• Dalam mode stt-tts, STT menggunakan tools.media.audio; voice.model tidak memengaruhi transkripsi.
• Dalam mode realtime, voice.realtime.provider, voice.realtime.model, dan voice.realtime.speakerVoice mengonfigurasi sesi audio realtime. Untuk OpenAI Realtime 2 plus otak Codex, gunakan voice.realtime.model: "gpt-realtime-2" dan voice.model: "openai/gpt-5.5".
• Mode suara realtime menyertakan file profil kecil IDENTITY.md, USER.md, dan SOUL.md dalam instruksi penyedia realtime secara default sehingga giliran langsung yang cepat mempertahankan identitas, landasan pengguna, dan persona yang sama seperti agen OpenClaw yang dirutekan. Setel voice.realtime.bootstrapContextFiles ke subset untuk menyesuaikannya, atau [] untuk menonaktifkannya. File bootstrap realtime yang didukung terbatas pada file profil tersebut; AGENTS.md tetap berada dalam konteks agen normal. Konteks profil yang disisipkan tidak menggantikan openclaw_agent_consult untuk pekerjaan workspace, fakta terkini, pencarian memori, atau tindakan berbasis tool.
• Dalam mode realtime OpenAI agent-proxy, setel voice.realtime.requireWakeName: true agar suara realtime Discord tetap diam sampai transkrip dimulai atau diakhiri dengan nama bangun. Nama bangun yang dikonfigurasi harus satu atau dua kata. Jika voice.realtime.wakeNames tidak disetel, OpenClaw menggunakan name agen yang dirutekan plus OpenClaw, dengan fallback ke id agen plus OpenClaw. Pembatasan nama bangun menonaktifkan respons otomatis penyedia realtime, merutekan giliran yang diterima melalui jalur konsultasi agen OpenClaw, dan memberikan pengakuan lisan singkat ketika nama bangun di awal dikenali dari transkripsi parsial sebelum transkrip final tiba.
• Penyedia realtime OpenAI menerima nama peristiwa Realtime 2 saat ini dan alias lama yang kompatibel dengan Codex untuk peristiwa audio keluaran dan transkrip, sehingga snapshot penyedia yang kompatibel dapat bergeser tanpa menjatuhkan audio asisten.
• voice.realtime.bargeIn mengontrol apakah peristiwa mulai-berbicara Discord menginterupsi pemutaran realtime aktif. Jika tidak disetel, ini mengikuti pengaturan interupsi input-audio penyedia realtime.
• voice.realtime.minBargeInAudioEndMs mengontrol durasi minimum pemutaran asisten sebelum barge-in realtime OpenAI memotong audio. Default: 250. Setel 0 untuk interupsi langsung di ruangan dengan gema rendah, atau naikkan untuk pengaturan speaker dengan gema berat.
• Untuk suara OpenAI pada pemutaran Discord, setel voice.tts.provider: "openai" dan pilih suara Text-to-speech di bawah voice.tts.providers.openai.speakerVoice. cedar adalah pilihan yang terdengar maskulin dan baik pada model TTS OpenAI saat ini.
• Penimpaan systemPrompt Discord per kanal berlaku untuk giliran transkrip suara pada kanal suara tersebut.
• Giliran transkrip suara menurunkan status owner dari allowFrom Discord (atau dm.allowFrom) untuk perintah berpagar owner dan tindakan kanal. Visibilitas tool agen mengikuti kebijakan tool yang dikonfigurasi untuk sesi yang dirutekan.
• Suara Discord bersifat opt-in untuk konfigurasi hanya teks; setel channels.discord.voice.enabled=true (atau pertahankan blok channels.discord.voice yang sudah ada) untuk mengaktifkan perintah /vc, runtime suara, dan intent gateway GuildVoiceStates.
• channels.discord.intents.voiceStates dapat secara eksplisit menimpa langganan intent voice-state. Biarkan tidak disetel agar intent mengikuti pengaktifan suara efektif.
• Jika voice.autoJoin memiliki beberapa entri untuk guild yang sama, OpenClaw bergabung ke kanal terakhir yang dikonfigurasi untuk guild tersebut.
• voice.allowedChannels adalah allowlist residensi opsional. Biarkan tidak disetel untuk mengizinkan /vc join ke kanal suara Discord resmi mana pun. Jika disetel, /vc join, auto-join saat startup, dan perpindahan voice-state bot dibatasi ke entri { guildId, channelId } yang tercantum. Setel ke array kosong untuk menolak semua join suara Discord. Jika Discord memindahkan bot ke luar allowlist, OpenClaw meninggalkan kanal tersebut dan bergabung kembali ke target auto-join yang dikonfigurasi saat tersedia.
• voice.daveEncryption dan voice.decryptionFailureTolerance diteruskan ke opsi join @discordjs/voice.
• Default @discordjs/voice adalah daveEncryption=true dan decryptionFailureTolerance=24 jika tidak disetel.
• OpenClaw menggunakan codec libopus-wasm bawaan untuk penerimaan suara Discord dan pemutaran PCM mentah realtime. Ini mengirimkan build WebAssembly libopus yang dipin dan tidak memerlukan addon opus native.
• voice.connectTimeoutMs mengontrol penantian Ready awal @discordjs/voice untuk /vc join dan percobaan auto-join. Default: 30000.
• voice.reconnectGraceMs mengontrol berapa lama OpenClaw menunggu sesi suara yang terputus mulai menyambung kembali sebelum menghancurkannya. Default: 15000.
• Dalam mode stt-tts, pemutaran suara tidak berhenti hanya karena pengguna lain mulai berbicara. Untuk menghindari loop umpan balik, OpenClaw mengabaikan tangkapan suara baru saat TTS sedang diputar; berbicaralah setelah pemutaran selesai untuk giliran berikutnya. Mode realtime meneruskan mulai-berbicara sebagai sinyal barge-in ke penyedia realtime.
• Dalam mode realtime, gema dari speaker ke mikrofon terbuka dapat terlihat seperti barge-in dan menginterupsi pemutaran. Untuk ruangan Discord dengan gema berat, setel voice.realtime.providers.openai.interruptResponseOnInputAudio: false agar OpenAI tidak otomatis menginterupsi pada audio input. Tambahkan voice.realtime.bargeIn: true jika Anda tetap ingin peristiwa mulai-berbicara Discord menginterupsi pemutaran aktif. Bridge realtime OpenAI mengabaikan pemotongan pemutaran yang lebih pendek dari voice.realtime.minBargeInAudioEndMs sebagai kemungkinan gema/noise dan mencatatnya sebagai dilewati alih-alih menghapus pemutaran Discord.
• voice.captureSilenceGraceMs mengontrol berapa lama OpenClaw menunggu setelah Discord melaporkan pembicara telah berhenti sebelum memfinalisasi segmen audio tersebut untuk STT. Default: 2000; naikkan ini jika Discord memecah jeda normal menjadi transkrip parsial yang tersendat.
• Saat ElevenLabs adalah penyedia TTS yang dipilih, pemutaran suara Discord menggunakan TTS streaming dan dimulai dari stream respons penyedia. Penyedia tanpa dukungan streaming kembali ke jalur temp-file yang disintesis.
• OpenClaw juga mengawasi kegagalan dekripsi penerimaan dan memulihkan otomatis dengan keluar/bergabung kembali ke kanal suara setelah kegagalan berulang dalam jendela singkat.
• Jika log penerimaan berulang kali menampilkan DecryptionFailed(UnencryptedWhenPassthroughDisabled) setelah pembaruan, kumpulkan laporan dependensi dan log. Baris @discordjs/voice bawaan mencakup perbaikan padding upstream dari PR discord.js #11449, yang menutup issue discord.js #11419.
• Peristiwa penerimaan The operation was aborted diharapkan saat OpenClaw memfinalisasi segmen pembicara yang ditangkap; itu adalah diagnostik verbose, bukan peringatan.
• Log suara Discord verbose menyertakan pratinjau transkrip STT satu baris yang dibatasi untuk setiap segmen pembicara yang diterima, sehingga debugging menunjukkan sisi pengguna dan sisi balasan agen tanpa membuang teks transkrip tanpa batas.
• Dalam mode agent-proxy, fallback konsultasi paksa melewati fragmen transkrip yang kemungkinan belum lengkap seperti teks yang berakhir dengan ... atau konektor akhir seperti and, plus penutup yang jelas tidak dapat ditindaklanjuti seperti “be right back” atau “bye”. Log menampilkan forced agent consult skipped reason=... saat ini mencegah jawaban antrean yang usang.

Ikuti pengguna dalam suara

Gunakan voice.followUsers saat Anda ingin bot suara Discord tetap bersama satu atau beberapa pengguna Discord yang dikenal alih-alih bergabung ke kanal tetap saat startup atau menunggu /vc join.

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

Perilaku:

• followUsers menerima ID pengguna Discord mentah dan nilai discord:<id>. OpenClaw menormalkan kedua bentuk sebelum mencocokkan peristiwa voice-state.
• followUsersEnabled default ke true saat followUsers dikonfigurasi. Setel ke false untuk mempertahankan daftar tersimpan tetapi menghentikan mengikuti suara otomatis.
• Saat pengguna yang diikuti bergabung ke kanal suara yang diizinkan, OpenClaw bergabung ke kanal tersebut. Saat pengguna berpindah, OpenClaw berpindah bersama mereka. Saat pengguna yang diikuti aktif terputus, OpenClaw keluar.
• Jika beberapa pengguna yang diikuti berada di guild yang sama dan pengguna yang diikuti aktif keluar, OpenClaw berpindah ke kanal pengguna lain yang diikuti dan dilacak sebelum meninggalkan guild. Jika beberapa pengguna yang diikuti berpindah sekaligus, peristiwa voice-state terbaru yang diamati menang.
• allowedChannels tetap berlaku. Pengguna yang diikuti di kanal yang tidak diizinkan diabaikan, dan sesi milik follow berpindah ke pengguna lain yang diikuti atau keluar.
• OpenClaw merekonsiliasi peristiwa voice-state yang terlewat saat startup dan pada interval terbatas. Rekonsiliasi mengambil sampel guild yang dikonfigurasi dan membatasi pencarian REST per proses, sehingga daftar followUsers yang sangat besar mungkin membutuhkan lebih dari satu interval untuk konvergen.
• Jika Discord atau admin memindahkan bot saat sedang mengikuti pengguna, OpenClaw membangun ulang sesi suara dan mempertahankan kepemilikan follow saat tujuan diizinkan. Jika bot dipindahkan ke luar allowedChannels, OpenClaw keluar dan bergabung kembali ke target yang dikonfigurasi saat ada.
• Pemulihan penerimaan DAVE dapat keluar dan bergabung kembali ke kanal yang sama setelah kegagalan dekripsi berulang. Sesi milik follow mempertahankan kepemilikan follow melalui jalur pemulihan tersebut, sehingga pemutusan pengguna yang diikuti berikutnya tetap meninggalkan kanal.

Pilih antara mode join:

• Gunakan followUsers untuk pengaturan personal atau operator ketika bot harus otomatis berada di suara saat Anda ada.
• Gunakan autoJoin untuk bot ruang tetap yang harus hadir bahkan saat tidak ada pengguna terlacak dalam suara.
• Gunakan /vc join untuk join sekali pakai atau ruangan ketika kehadiran suara otomatis akan mengejutkan.

Codec suara Discord:

• Log penerimaan suara menampilkan discord voice: opus decoder: libopus-wasm.
• Pemutaran realtime mengodekan PCM stereo mentah 48 kHz ke Opus dengan paket libopus-wasm bawaan yang sama sebelum menyerahkan paket ke @discordjs/voice.
• Pemutaran file dan stream penyedia mentranskode ke PCM stereo mentah 48 kHz dengan ffmpeg, lalu menggunakan libopus-wasm untuk stream paket Opus yang dikirim ke Discord.

Pipeline STT plus TTS:

• Tangkapan PCM Discord dikonversi menjadi file sementara WAV.
• tools.media.audio menangani STT, misalnya openai/gpt-4o-mini-transcribe.
• Transkrip dikirim melalui ingress dan perutean Discord sementara LLM respons berjalan dengan kebijakan keluaran suara yang menyembunyikan tool agen tts dan meminta teks yang dikembalikan, karena suara Discord memiliki pemutaran TTS akhir.
• voice.model, jika disetel, hanya menimpa LLM respons untuk giliran channel suara ini.
• voice.tts digabungkan di atas messages.tts; penyedia yang mendukung streaming langsung memasok pemutar, jika tidak, file audio yang dihasilkan diputar di channel yang telah dimasuki.

Contoh sesi channel suara agent-proxy bawaan:

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

Tanpa blok voice.agentSession, setiap channel suara mendapatkan sesi OpenClaw terute sendiri. Misalnya, /vc join channel:234567890123456789 berbicara dengan sesi untuk channel suara Discord tersebut. Model realtime hanya menjadi front end suara; permintaan substantif diserahkan ke agen OpenClaw yang dikonfigurasi. Jika model realtime menghasilkan transkrip akhir tanpa memanggil tool konsultasi, OpenClaw memaksa konsultasi sebagai fallback agar bawaan tetap berperilaku seperti berbicara dengan agen.

Contoh STT plus TTS lama:

{  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",            },          },        },      },    },  },}

Contoh bidi 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",        },      },    },  },}

Suara sebagai ekstensi dari sesi channel Discord yang sudah ada:

{  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",        },      },    },  },}

Dalam mode agent-proxy, bot bergabung ke channel suara yang dikonfigurasi, tetapi giliran agen OpenClaw menggunakan sesi terute normal dan agen milik channel target. Sesi suara realtime mengucapkan kembali hasil yang dikembalikan ke channel suara. Agen supervisor masih dapat menggunakan tool pesan normal sesuai kebijakan tool-nya, termasuk mengirim pesan Discord terpisah jika itu tindakan yang tepat.

Saat run OpenClaw yang didelegasikan aktif, transkrip suara Discord baru diperlakukan sebagai kontrol run langsung sebelum memulai giliran agen lain. Frasa seperti "status", "cancel that", "use the smaller fix", atau "when you're done also check tests" diklasifikasikan sebagai status, pembatalan, pengarahan, atau masukan tindak lanjut untuk sesi aktif. Hasil status, pembatalan, pengarahan yang diterima, dan tindak lanjut diucapkan kembali ke channel suara agar pemanggil tahu apakah OpenClaw menangani permintaan tersebut.

Bentuk target yang berguna:

• target: "channel:123456789012345678" merutekan melalui sesi channel teks Discord.
• target: "123456789012345678" diperlakukan sebagai target channel.
• target: "dm:123456789012345678" atau target: "user:123456789012345678" merutekan melalui sesi pesan langsung tersebut.

Contoh OpenAI Realtime dengan echo berat:

{  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,            },          },        },      },    },  },}

Gunakan ini saat model mendengar pemutaran Discord-nya sendiri melalui mikrofon terbuka, tetapi Anda tetap ingin menyelanya dengan berbicara. OpenClaw mencegah OpenAI melakukan interupsi otomatis pada audio input mentah, sementara bargeIn: true memungkinkan peristiwa speaker-start Discord dan audio speaker yang sudah aktif membatalkan respons realtime aktif sebelum giliran tangkapan berikutnya mencapai OpenAI. Sinyal barge-in yang sangat awal dengan audioEndMs di bawah minBargeInAudioEndMs diperlakukan sebagai kemungkinan echo/noise dan diabaikan agar model tidak terpotong pada frame pemutaran pertama.

Log suara yang diharapkan:

• Saat bergabung: discord voice: joining ... voiceSession=... supervisorSession=... agentSessionMode=... voiceModel=... realtimeModel=...
• Saat realtime dimulai: discord voice: realtime bridge starting ... autoRespond=false interruptResponse=false bargeIn=false minBargeInAudioEndMs=...
• Pada audio speaker: discord voice: realtime speaker turn opened ..., discord voice: realtime input audio started ... outputAudioMs=... outputActive=..., dan discord voice: realtime speaker turn closed ... chunks=... discordBytes=... realtimeBytes=... interruptedPlayback=...
• Pada ucapan usang yang dilewati: discord voice: realtime forced agent consult skipped reason=incomplete-transcript ... atau reason=non-actionable-closing ...
• Pada penyelesaian respons realtime: discord voice: realtime audio playback finishing reason=response.done ... audioMs=... chunks=...
• Pada penghentian/reset pemutaran: discord voice: realtime audio playback stopped reason=... audioMs=... elapsedMs=... chunks=...
• Pada konsultasi realtime: discord voice: realtime consult requested ... voiceSession=... supervisorSession=... question=...
• Pada jawaban agen: discord voice: agent turn answer ...
• Pada ucapan persis yang diantrekan: discord voice: realtime exact speech queued ... queued=... outputAudioMs=... outputActive=..., diikuti oleh discord voice: realtime exact speech dequeued reason=player-idle ...
• Pada deteksi barge-in: discord voice: realtime barge-in detected source=speaker-start ... atau discord voice: realtime barge-in detected source=active-speaker-audio ..., diikuti oleh discord voice: realtime barge-in requested reason=... outputAudioMs=... outputActive=...
• Pada interupsi realtime: discord voice: realtime model interrupt requested client:response.cancel reason=barge-in, diikuti oleh discord voice: realtime model audio truncated client:conversation.item.truncate reason=barge-in audioEndMs=... atau discord voice: realtime model interrupt confirmed server:response.done status=cancelled ...
• Pada echo/noise yang diabaikan: discord voice: realtime model interrupt ignored client:conversation.item.truncate.skipped reason=barge-in audioEndMs=0 minAudioEndMs=250
• Pada barge-in yang dinonaktifkan: discord voice: realtime capture ignored during playback (barge-in disabled) ...
• Pada pemutaran idle: discord voice: realtime barge-in ignored reason=... outputActive=false ... playbackChunks=0

Untuk men-debug audio yang terpotong, baca log suara realtime sebagai timeline:

1. realtime audio playback started berarti Discord telah mulai memutar audio asisten. Bridge mulai menghitung chunk keluaran asisten, byte PCM Discord, byte realtime penyedia, dan durasi audio tersintesis dari titik ini.
2. realtime speaker turn opened menandai speaker Discord menjadi aktif. Jika pemutaran sudah aktif dan bargeIn diaktifkan, ini dapat diikuti oleh barge-in detected source=speaker-start.
3. realtime input audio started menandai frame audio aktual pertama yang diterima untuk giliran speaker tersebut. outputActive=true atau outputAudioMs bukan nol di sini berarti mikrofon mengirim input saat pemutaran asisten masih aktif.
4. barge-in detected source=active-speaker-audio berarti OpenClaw melihat audio speaker langsung saat pemutaran asisten aktif. Ini berguna untuk membedakan interupsi nyata dari peristiwa speaker-start Discord tanpa audio yang berguna.
5. barge-in requested reason=... berarti OpenClaw meminta penyedia realtime untuk membatalkan atau memotong respons aktif. Ini menyertakan outputAudioMs, outputActive, dan playbackChunks sehingga Anda dapat melihat berapa banyak audio asisten yang benar-benar sudah diputar sebelum interupsi.
6. realtime audio playback stopped reason=... adalah titik reset pemutaran Discord lokal. Alasannya menyatakan siapa yang menghentikan pemutaran: barge-in, player-idle, provider-clear-audio, forced-agent-consult, stream-close, atau session-close.
7. realtime speaker turn closed merangkum giliran input yang ditangkap. chunks=0 atau hasAudio=false berarti giliran speaker terbuka tetapi tidak ada audio yang dapat digunakan mencapai bridge realtime. interruptedPlayback=true berarti giliran input tersebut tumpang tindih dengan keluaran asisten dan memicu logika barge-in.

Bidang yang berguna:

• outputAudioMs: durasi audio asisten yang dihasilkan oleh penyedia realtime sebelum baris log.
• audioMs: durasi audio asisten yang dihitung OpenClaw sebelum pemutaran berhenti.
• elapsedMs: waktu wall-clock antara pembukaan dan penutupan stream pemutaran atau giliran speaker.
• discordBytes: byte PCM stereo 48 kHz yang dikirim ke atau diterima dari suara Discord.
• realtimeBytes: byte PCM format penyedia yang dikirim ke atau diterima dari penyedia realtime.
• playbackChunks: chunk audio asisten yang diteruskan ke Discord untuk respons aktif.
• sinceLastAudioMs: jeda antara frame audio speaker terakhir yang ditangkap dan penutupan giliran speaker.

Pola umum:

• Pemotongan langsung dengan source=active-speaker-audio, outputAudioMs kecil, dan pengguna yang sama di dekatnya biasanya menunjukkan echo speaker masuk ke mikrofon. Naikkan voice.realtime.minBargeInAudioEndMs, kecilkan volume speaker, gunakan headphone, atau setel voice.realtime.providers.openai.interruptResponseOnInputAudio: false.
• source=speaker-start diikuti oleh speaker turn closed ... hasAudio=false berarti Discord melaporkan speaker mulai tetapi tidak ada audio yang mencapai OpenClaw. Itu bisa berupa peristiwa suara Discord sementara, perilaku noise gate, atau klien yang sebentar mengaktifkan mikrofon.
• audio playback stopped reason=stream-close tanpa barge-in terdekat atau provider-clear-audio berarti stream pemutaran Discord lokal berakhir secara tidak terduga. Periksa log penyedia dan pemutar Discord sebelumnya.
• capture ignored during playback (barge-in disabled) berarti OpenClaw sengaja membuang input saat audio asisten aktif. Aktifkan voice.realtime.bargeIn jika Anda ingin ucapan menyela pemutaran.
• barge-in ignored ... outputActive=false berarti Discord atau VAD penyedia melaporkan ucapan, tetapi OpenClaw tidak memiliki pemutaran aktif untuk disela. Ini seharusnya tidak memotong audio.

Kredensial diselesaikan per komponen: autentikasi rute LLM untuk voice.model, autentikasi STT untuk tools.media.audio, autentikasi TTS untuk messages.tts/voice.tts, dan autentikasi penyedia realtime untuk voice.realtime.providers atau konfigurasi autentikasi normal penyedia.

Pesan suara

Pesan suara Discord menampilkan pratinjau waveform dan memerlukan audio OGG/Opus. OpenClaw menghasilkan waveform secara otomatis, tetapi membutuhkan ffmpeg dan ffprobe di host gateway untuk memeriksa dan mengonversi.

• Berikan jalur berkas lokal (URL ditolak).
• Hilangkan konten teks (Discord menolak teks + pesan suara dalam payload yang sama).
• Format audio apa pun diterima; OpenClaw mengonversi ke OGG/Opus sesuai kebutuhan.

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

Pemecahan masalah

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,      },    },  },},},}

Referensi konfigurasi

Referensi utama: Referensi konfigurasi - Discord.

Keamanan dan operasi

• Perlakukan token bot sebagai rahasia (DISCORD_BOT_TOKEN lebih disarankan di lingkungan yang diawasi).
• Berikan izin Discord dengan hak paling rendah.
• Jika deployment/status perintah sudah usang, mulai ulang Gateway dan periksa ulang dengan openclaw channels status --probe.

Terkait