Discord

OpenClaw terhubung ke Discord sebagai bot melalui gateway resmi Discord. DM dan kanal guild didukung.

Penyiapan cepat

Buat aplikasi Discord dengan bot, tambahkan bot tersebut ke server Anda, lalu pasangkan dengan OpenClaw. Gunakan server privat jika memungkinkan; buat terlebih dahulu (Create My Own > For me and my friends) jika diperlukan.

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 mengubah server menjadi ruang kerja lengkap tempat setiap kanal mendapatkan sesi agennya sendiri dengan konteks tersendiri. 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 kanal dan mulai mengobrol. Agen melihat nama kanal, dan setiap kanal merupakan sesi terisolasi—siapkan #coding, #home, #research, atau apa pun yang sesuai dengan alur kerja Anda.

Model runtime

• Gateway mengelola koneksi Discord.
• Perutean balasan bersifat deterministik: balasan untuk pesan masuk Discord dikirim kembali ke Discord.
• Metadata guild/kanal Discord ditambahkan ke prompt model sebagai konteks tidak tepercaya, bukan sebagai prefiks balasan yang terlihat oleh pengguna. Jika model menyalin kembali selubung tersebut, OpenClaw menghapus metadata yang disalin dari balasan keluar dan konteks pemutaran ulang mendatang.
• Secara default (session.dmScope=main), obrolan langsung berbagi sesi utama agen (agent:main:main).
• Kanal guild menggunakan kunci sesi terisolasi (agent:<agentId>:discord:channel:<channelId>).
• DM grup secara default diabaikan (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 diringkas menjadi jawaban akhir yang terlihat oleh asisten dan dikirim satu kali. Payload media dan komponen terstruktur tetap terdiri dari beberapa pesan ketika agen menghasilkan beberapa payload yang dapat dikirimkan.

Kanal forum

Kanal forum dan media Discord hanya menerima postingan utas. OpenClaw mendukung dua cara untuk membuatnya:

• Kirim pesan ke induk forum (channel:<forumId>) untuk membuat utas secara otomatis. Judul utas adalah baris pertama pesan yang tidak kosong (dipotong sesuai batas nama utas Discord sebanyak 100 karakter).
• Gunakan openclaw message thread create untuk membuat utas secara langsung. Jangan teruskan --message-id untuk kanal forum.

Kirim ke induk forum untuk membuat utas:

openclaw message send --channel discord --target channel:<forumId> \  --message "Judul topik\nIsi postingan"

Buat utas forum secara eksplisit:

openclaw message thread create --channel discord --target channel:<forumId> \  --thread-name "Judul topik" --message "Isi postingan"

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

Komponen interaktif

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

Blok yang didukung:

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

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

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

Callback komponen kedaluwarsa setelah 30 menit secara default. Atur channels.discord.agentComponents.ttlMs untuk mengubah masa aktif registri callback bagi akun default, atau channels.discord.accounts.<accountId>.agentComponents.ttlMs per akun. Nilainya dalam milidetik, harus berupa bilangan bulat positif, dan dibatasi hingga 86400000 (24 jam). TTL yang lebih panjang cocok untuk alur kerja peninjauan/persetujuan yang memerlukan tombol tetap dapat digunakan, tetapi memperpanjang rentang waktu ketika pesan Discord lama masih dapat memicu tindakan. Pilih TTL tersingkat yang sesuai, dan pertahankan nilai default jika callback usang akan menimbulkan perilaku yang tidak terduga.

Perintah garis miring /model dan /models membuka pemilih model interaktif dengan menu tarik-turun penyedia, model, dan runtime yang kompatibel, serta langkah Submit. /models add tidak digunakan lagi dan mengembalikan pesan penghentian dukungan alih-alih mendaftarkan model dari obrolan. Balasan pemilih bersifat efemeral dan hanya dapat digunakan oleh pengguna yang memanggilnya. Menu pilihan Discord dibatasi hingga 25 opsi, jadi tambahkan entri provider/* ke agents.defaults.modelPolicy.allow jika Anda ingin pemilih menampilkan model yang ditemukan secara dinamis hanya untuk penyedia tertentu seperti openai atau vllm.

Lampiran berkas:

• Blok file harus menunjuk ke referensi lampiran (attachment://<filename>)
• Sediakan lampiran melalui media/path/filePath (satu berkas); gunakan media-gallery untuk beberapa berkas
• Gunakan filename untuk mengganti nama unggahan jika harus sesuai 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: "Teks alternatif opsional",  components: {    reusable: true,    text: "Pilih jalur",    blocks: [      {        type: "actions",        buttons: [          {            label: "Setujui",            style: "success",            allowedUsers: ["123456789012345678"],          },          { label: "Tolak", style: "danger" },        ],      },      {        type: "actions",        select: {          type: "string",          placeholder: "Pilih opsi",          options: [            { label: "Opsi A", value: "a" },            { label: "Opsi B", value: "b" },          ],        },      },    ],    modal: {      title: "Detail",      triggerLabel: "Buka formulir",      fields: [        { type: "text", label: "Pemohon" },        {          type: "select",          label: "Prioritas",          options: [            { label: "Rendah", value: "low" },            { label: "Tinggi", 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: { enabled: true },        help: { enabled: true, requireMention: true },      },    },  },},},}

Perutean agen berbasis peran

Gunakan bindings[].match.roles untuk merutekan anggota guild Discord ke agen yang berbeda berdasarkan ID peran. Pengikatan berbasis peran hanya menerima ID peran dan dievaluasi setelah pengikatan rekan atau rekan-induk serta sebelum pengikatan khusus guild. Jika sebuah pengikatan juga menetapkan bidang pencocokan lain (misalnya peer + guildId + roles), semua bidang 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 secara default bernilai "auto" dan diaktifkan untuk Discord.
• Penimpaan per kanal: channels.discord.commands.native.
• commands.native=false melewati pendaftaran dan pembersihan perintah garis miring Discord selama proses mulai. Perintah yang sebelumnya didaftarkan mungkin tetap terlihat di Discord sampai Anda menghapusnya dari aplikasi Discord.
• Autentikasi perintah native menggunakan daftar izin/kebijakan Discord yang sama dengan penanganan pesan biasa.
• Perintah mungkin tetap terlihat di UI Discord bagi pengguna yang tidak berwenang; eksekusi memberlakukan autentikasi OpenClaw dan membalas "tidak berwenang".
• Pengaturan perintah garis miring default: ephemeral: true (channels.discord.slashCommand.ephemeral).

Lihat Perintah garis miring untuk katalog dan perilaku perintah.

Detail fitur

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

{channels: {discord: {  streaming: {    mode: "progress",    progress: {      maxLines: 8,      maxLineChars: 120,      toolProgress: false,      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",  },},},}

{channels: {discord: {  subagentProgress: true,},},}

{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: {      intents: { presence: true },      guilds: {        "111111111111111111": {          presenceEvents: {            channelId: "222222222222222222",            users: ["333333333333333333"], // opsional; persempit lagi pengguna yang dapat melihat kanal            reconnectSuppressSeconds: 300, // opsional; periode senyap sesi baru (0 menonaktifkan)            burstLimit: 8, // opsional; jumlah maksimum peristiwa per jendela lonjakan            burstWindowSeconds: 60, // opsional; jendela bergulir untuk deteksi lonjakan          },        },      },    },  },}

{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_...", // opsional; diperlukan untuk sistem privat  },},},}

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

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

{channels: {discord: {  activity: "Waktu fokus",  activityType: 4,},},}

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

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

Alat dan gerbang tindakan

Tindakan pesan Discord mencakup perpesanan, administrasi kanal, moderasi, kehadiran, dan metadata.

Contoh inti:

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

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

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

Perilaku gerbang bawaan:

UI komponen v2

OpenClaw menggunakan komponen v2 Discord untuk persetujuan eksekusi dan penanda lintas konteks. Tindakan pesan Discord juga dapat menerima components untuk UI kustom (tingkat lanjut; memerlukan pembuatan payload komponen melalui alat discord), sedangkan embeds lama tetap tersedia tetapi tidak disarankan.

• channels.discord.ui.components.accentColor menetapkan warna aksen yang digunakan oleh kontainer komponen Discord (heksadesimal). Per akun: 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). Per akun: channels.discord.accounts.<id>.agentComponents.ttlMs.
• embeds diabaikan saat komponen v2 tersedia.
• Pratinjau URL biasa disembunyikan secara default. Tetapkan suppressEmbeds: false pada tindakan pesan saat satu tautan keluar perlu diperluas.

Contoh:

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

Suara

Discord memiliki dua antarmuka suara yang berbeda: saluran suara waktu nyata (percakapan berkelanjutan) dan lampiran pesan suara (format pratinjau bentuk gelombang). Gateway mendukung keduanya.

Saluran suara

Daftar periksa penyiapan:

1. Aktifkan Message Content Intent di Discord Developer Portal.
2. Aktifkan Server Members Intent saat 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 tujuan.
5. Aktifkan perintah native (commands.native atau channels.discord.commands.native).
6. Konfigurasikan 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:

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

Contoh bergabung otomatis:

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

Catatan:

• Suara Discord bersifat opsional untuk konfigurasi khusus teks; tetapkan 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 mengganti langganan intent; biarkan tidak ditetapkan agar mengikuti pengaktifan suara yang berlaku.
• voice.mode mengontrol jalur percakapan. Nilai defaultnya adalah agent-proxy: front end suara waktu nyata menangani pengaturan waktu giliran, interupsi, dan pemutaran, mendelegasikan pekerjaan substantif kepada agen OpenClaw yang dirutekan melalui openclaw_agent_consult, dan memperlakukan hasilnya seperti prompt Discord yang diketik oleh pembicara tersebut. stt-tts mempertahankan alur STT batch lama ditambah TTS. bidi memungkinkan model waktu nyata bercakap-cakap secara langsung sambil menyediakan openclaw_agent_consult untuk otak OpenClaw.
• voice.agentSession mengontrol percakapan OpenClaw mana yang menerima giliran suara. Biarkan tidak ditetapkan untuk menggunakan sesi milik kanal suara itu sendiri, atau tetapkan { mode: "target", target: "channel:<text-channel-id>" } agar kanal suara berfungsi sebagai ekstensi mikrofon/pengeras suara dari sesi kanal teks Discord yang sudah ada, seperti #maintainers.
• voice.model mengganti otak agen OpenClaw untuk respons suara Discord dan konsultasi waktu nyata. Biarkan tidak ditetapkan 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 Mengikuti pengguna dalam suara.
• agent-proxy merutekan ucapan melalui discord-voice, yang mempertahankan otorisasi pemilik/alat normal untuk pembicara dan sesi target, tetapi menyembunyikan alat agen tts karena suara Discord menangani pemutaran. Secara default, agent-proxy memberikan konsultasi akses alat penuh yang setara dengan pemilik untuk pembicara pemilik (voice.realtime.toolPolicy: "owner") dan sangat mengutamakan konsultasi dengan agen OpenClaw sebelum memberikan jawaban substantif (voice.realtime.consultPolicy: "always"). Dalam mode always default tersebut, lapisan waktu nyata tidak secara otomatis mengucapkan kata pengisi sebelum jawaban konsultasi; lapisan ini merekam dan mentranskripsikan ucapan, lalu mengucapkan jawaban OpenClaw yang dirutekan. Jika beberapa jawaban konsultasi paksa selesai saat Discord masih memutar jawaban pertama, jawaban ucapan persis berikutnya akan dimasukkan ke antrean hingga pemutaran tidak aktif, alih-alih mengganti ucapan di tengah kalimat.
• Dalam mode stt-tts, STT menggunakan tools.media.audio; voice.model tidak memengaruhi transkripsi.
• Dalam mode waktu nyata, voice.realtime.provider, voice.realtime.model, dan voice.realtime.speakerVoice mengonfigurasi sesi audio waktu nyata. Untuk OpenAI Realtime 2.1 beserta otak Codex, gunakan voice.realtime.model: "gpt-realtime-2.1" dan voice.model: "openai/gpt-5.6-sol".
• Mode suara waktu nyata secara default menyertakan file profil kecil IDENTITY.md, USER.md, dan SOUL.md dalam instruksi penyedia waktu nyata agar giliran langsung yang cepat mempertahankan identitas, landasan pengguna, dan persona yang sama dengan agen OpenClaw yang dirutekan. Tetapkan voice.realtime.bootstrapContextFiles ke suatu subset untuk menyesuaikannya, atau [] untuk menonaktifkannya. Hanya file profil tersebut yang didukung; AGENTS.md tetap berada dalam konteks agen normal. Konteks profil yang diinjeksi tidak menggantikan openclaw_agent_consult untuk pekerjaan ruang kerja, fakta terkini, pencarian memori, atau tindakan berbasis alat.
• Dalam mode waktu nyata OpenAI agent-proxy, pembatasan nama pemicu secara default beradaptasi dengan ruangan: satu orang dapat berbicara secara alami tanpa nama pemicu, sedangkan dua orang atau lebih harus memulai atau mengakhiri giliran dengan nama pemicu. Bot lain tidak dihitung sebagai orang. Tetapkan voice.realtime.requireWakeName: true untuk selalu mewajibkan nama pemicu atau false agar tidak pernah mewajibkannya. Nama pemicu yang dikonfigurasi harus terdiri atas satu atau dua kata. Jika voice.realtime.wakeNames tidak ditetapkan, OpenClaw menggunakan name agen yang dirutekan ditambah OpenClaw, dengan fallback ke ID agen ditambah OpenClaw. Pembatas nama pemicu yang aktif menonaktifkan respons otomatis penyedia waktu nyata, merutekan giliran yang diterima melalui jalur konsultasi agen OpenClaw, dan memberikan pengakuan lisan singkat ketika nama pemicu di awal dikenali dari transkripsi parsial sebelum transkrip final tiba. Kebijakan mengikuti aktivitas bergabung dan keluar secara langsung tanpa menyambungkan ulang suara.
• Penyedia waktu nyata 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 berubah tanpa menghilangkan audio asisten.
• voice.realtime.bargeIn mengontrol apakah peristiwa mulai-berbicara Discord menginterupsi pemutaran waktu nyata yang aktif. Jika tidak ditetapkan, nilainya mengikuti pengaturan interupsi audio masukan dari penyedia waktu nyata.
• voice.realtime.minBargeInAudioEndMs mengontrol durasi minimum pemutaran asisten sebelum interupsi OpenAI waktu nyata memotong audio. Default: 250. Tetapkan 0 untuk interupsi langsung di ruangan dengan gema rendah, atau naikkan nilainya untuk penyiapan pengeras suara dengan gema tinggi.
• voice.tts mengganti messages.tts hanya untuk pemutaran suara stt-tts; mode waktu nyata menggunakan voice.realtime.speakerVoice sebagai gantinya. Untuk suara OpenAI pada pemutaran Discord, tetapkan voice.tts.provider: "openai" dan pilih suara Text-to-speech di bawah voice.tts.providers.openai.speakerVoice. cedar adalah pilihan yang bagus dengan karakter suara maskulin pada model TTS OpenAI saat ini.
• Penggantian systemPrompt Discord per kanal berlaku untuk giliran transkrip suara pada kanal suara tersebut.
• Saat OpenClaw bergabung dengan kanal suara, sesi agen yang dirutekan menerima peristiwa sistem senyap berisi daftar peserta saat ini. Peserta yang kemudian bergabung dan keluar akan memperbarui sesi tersebut tanpa memicu balasan lisan yang tidak diminta; nama tampilan Discord diperlakukan sebagai label yang tidak tepercaya. Giliran suara yang diotorisasi juga menerima snapshot daftar peserta terbaru.
• Giliran transkrip suara dan perintah /vc menggunakan entri Discord dalam commands.ownerAllowFrom untuk menentukan status pemilik. Jika tidak ada pemilik perintah Discord yang dikonfigurasi, allowFrom milik akun Discord yang dipilih (atau dm.allowFrom lama) masih dapat mengotorisasi akses suara tanpa memberikan status pemilik. Visibilitas alat agen mengikuti kebijakan alat yang dikonfigurasi untuk sesi yang dirutekan.
• Jika voice.autoJoin memiliki beberapa entri untuk guild yang sama, OpenClaw bergabung dengan kanal terakhir yang dikonfigurasi untuk guild tersebut.
• voice.allowedChannels adalah daftar izin residensi opsional. Biarkan tidak ditetapkan untuk mengizinkan /vc join masuk ke kanal suara Discord mana pun yang diotorisasi. Jika ditetapkan, /vc join, bergabung otomatis saat startup, dan perpindahan status suara bot dibatasi ke entri { guildId, channelId } yang tercantum. Tetapkan ke array kosong untuk menolak semua upaya bergabung ke suara Discord. Jika Discord memindahkan bot ke luar daftar izin, OpenClaw akan keluar dari kanal tersebut dan bergabung kembali ke target bergabung otomatis yang dikonfigurasi jika tersedia.
• voice.daveEncryption dan voice.decryptionFailureTolerance diteruskan ke opsi bergabung @discordjs/voice; nilai default upstream adalah daveEncryption=true dan decryptionFailureTolerance=24.
• OpenClaw menggunakan codec libopus-wasm bawaan untuk penerimaan suara Discord dan pemutaran PCM mentah waktu nyata. Codec ini menyertakan build WebAssembly libopus yang versinya dipatok dan tidak memerlukan addon opus native.
• voice.connectTimeoutMs mengontrol waktu tunggu Ready @discordjs/voice awal untuk upaya /vc join dan bergabung otomatis. Default: 30000.
• voice.reconnectGraceMs mengontrol berapa lama OpenClaw menunggu sesi suara yang terputus untuk 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 perekaman suara baru selama TTS diputar; berbicaralah setelah pemutaran selesai untuk giliran berikutnya. Mode waktu nyata meneruskan mulainya ucapan pembicara sebagai sinyal interupsi kepada penyedia waktu nyata.
• Dalam mode waktu nyata, gema dari pengeras suara yang masuk ke mikrofon terbuka dapat terlihat seperti interupsi dan menghentikan pemutaran. Untuk ruangan Discord dengan gema tinggi, tetapkan voice.realtime.providers.openai.interruptResponseOnInputAudio: false agar OpenAI tidak melakukan interupsi otomatis saat ada audio masukan. Tambahkan voice.realtime.bargeIn: true jika Anda masih ingin peristiwa mulai-berbicara Discord menginterupsi pemutaran aktif. Jembatan waktu nyata OpenAI mengabaikan pemotongan pemutaran yang lebih singkat dari voice.realtime.minBargeInAudioEndMs karena dianggap sebagai kemungkinan gema/derau dan mencatatnya sebagai dilewati alih-alih menghapus pemutaran Discord.
• voice.captureSilenceGraceMs mengontrol berapa lama OpenClaw menunggu setelah Discord melaporkan bahwa pembicara telah berhenti sebelum memfinalkan segmen audio tersebut untuk STT. Default: 2000; naikkan nilainya jika Discord memecah jeda normal menjadi transkrip parsial yang terputus-putus.
• Saat ElevenLabs menjadi penyedia TTS yang dipilih, pemutaran suara Discord menggunakan TTS streaming dan dimulai dari aliran respons penyedia. Penyedia tanpa dukungan streaming menggunakan fallback ke jalur file sementara hasil sintesis.
• OpenClaw memantau kegagalan dekripsi penerimaan dan memulihkan diri secara otomatis dengan keluar dari lalu bergabung kembali ke kanal suara setelah kegagalan berulang dalam jangka waktu singkat.
• Jika log penerimaan berulang kali menampilkan DecryptionFailed(UnencryptedWhenPassthroughDisabled) setelah pembaruan, kumpulkan laporan dependensi dan log. Baris @discordjs/voice bawaan menyertakan perbaikan padding upstream dari PR discord.js #11449, yang menutup isu discord.js #11419.
• Peristiwa penerimaan The operation was aborted memang diharapkan saat OpenClaw memfinalkan segmen pembicara yang direkam; ini adalah diagnostik terperinci, bukan peringatan.
• Log suara Discord terperinci menyertakan pratinjau transkrip STT satu baris dengan panjang terbatas untuk setiap segmen pembicara yang diterima, sehingga proses debugging menampilkan sisi pengguna dan sisi balasan agen tanpa membuang teks transkrip tanpa batas.
• Dalam mode agent-proxy, fallback konsultasi paksa melewati fragmen transkrip yang kemungkinan tidak lengkap, seperti teks yang diakhiri dengan ... atau kata penghubung di akhir seperti "dan", serta penutup yang jelas tidak memerlukan tindakan seperti "segera kembali" atau "sampai jumpa". Log menampilkan forced agent consult skipped reason=... saat hal ini mencegah jawaban lama dalam antrean.

Mengikuti pengguna dalam suara

Gunakan voice.followUsers jika Anda ingin bot suara Discord tetap bersama satu atau beberapa pengguna Discord yang dikenal, alih-alih bergabung dengan 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 status suara.
• followUsersEnabled secara default bernilai true ketika followUsers dikonfigurasi. Atur ke false untuk mempertahankan daftar yang disimpan tetapi menghentikan mengikuti suara secara otomatis.
• followUsers hanya mengontrol keberadaan di suara. Ini tidak memberikan akses pembicara atau wewenang pemilik; konfigurasikan commands.ownerAllowFrom serta pengguna dan peran guild atau kanal secara terpisah.
• Ketika pengguna yang diikuti bergabung ke kanal suara yang diizinkan, OpenClaw bergabung ke kanal tersebut. Ketika pengguna berpindah, OpenClaw ikut berpindah bersama mereka. Ketika pengguna aktif yang diikuti terputus, OpenClaw keluar.
• Jika beberapa pengguna yang diikuti berada di guild yang sama dan pengguna aktif yang diikuti keluar, OpenClaw berpindah ke kanal pengguna lain yang diikuti dan dilacak sebelum keluar dari guild. Jika beberapa pengguna yang diikuti berpindah secara bersamaan, peristiwa status suara yang diamati paling akhir yang berlaku.
• allowedChannels tetap berlaku. Pengguna yang diikuti di kanal yang tidak diizinkan akan diabaikan, dan sesi yang dimiliki mekanisme mengikuti akan berpindah ke pengguna lain yang diikuti atau keluar.
• OpenClaw merekonsiliasi peristiwa status suara yang terlewat saat dimulai dan pada interval terbatas. Rekonsiliasi mengambil sampel guild yang dikonfigurasi dan membatasi pencarian REST per proses, sehingga daftar followUsers yang sangat besar mungkin memerlukan lebih dari satu interval untuk mencapai keadaan yang selaras.
• Jika Discord atau admin memindahkan bot saat bot sedang mengikuti pengguna, OpenClaw membangun ulang sesi suara dan mempertahankan kepemilikan mengikuti ketika tujuan diizinkan. Jika bot dipindahkan ke luar allowedChannels, OpenClaw keluar dan bergabung kembali ke target yang dikonfigurasi jika ada.
• Pemulihan penerimaan DAVE mungkin keluar dan bergabung kembali ke kanal yang sama setelah kegagalan dekripsi berulang. Sesi yang dimiliki mekanisme mengikuti mempertahankan kepemilikan tersebut sepanjang jalur pemulihan, sehingga terputusnya pengguna yang diikuti setelahnya tetap menyebabkan bot keluar dari kanal.

Pilih di antara mode bergabung:

• Gunakan followUsers untuk penyiapan pribadi atau operator ketika bot harus otomatis berada di kanal suara saat Anda berada di sana.
• Gunakan autoJoin untuk bot ruang tetap yang harus tetap hadir meskipun tidak ada pengguna terlacak di kanal suara.
• Gunakan /vc join untuk bergabung satu kali atau ruang tempat keberadaan suara otomatis akan terasa tidak semestinya.

Kodek suara Discord:

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

Pipeline STT dan TTS:

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

Contoh sesi kanal suara proksi agen default:

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

Tanpa blok voice.agentSession, setiap kanal suara mendapatkan sesi OpenClaw terute sendiri. Misalnya, /vc join channel:234567890123456789 berkomunikasi dengan sesi untuk kanal suara Discord tersebut. Model waktu nyata hanya merupakan antarmuka suara; permintaan substantif diteruskan kepada agen OpenClaw yang dikonfigurasi. Jika model waktu nyata menghasilkan transkrip akhir tanpa memanggil alat konsultasi, OpenClaw memaksakan konsultasi sebagai mekanisme cadangan agar perilaku default tetap seperti berbicara dengan agen.

Contoh STT dan 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 dua arah waktu nyata:

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

Suara sebagai ekstensi sesi kanal Discord yang sudah ada:

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

Dalam mode agent-proxy, bot bergabung ke kanal suara yang dikonfigurasi, tetapi giliran agen OpenClaw menggunakan sesi terute dan agen normal milik kanal target. Sesi suara waktu nyata mengucapkan kembali hasil yang dikembalikan ke kanal suara. Agen pengawas tetap dapat menggunakan alat pesan normal sesuai kebijakan alatnya, termasuk mengirim pesan Discord terpisah jika itu merupakan tindakan yang tepat.

Saat proses OpenClaw yang didelegasikan aktif, transkrip suara Discord baru diperlakukan sebagai kontrol proses langsung sebelum memulai giliran agen lain. Frasa seperti "status", "batalkan itu", "gunakan perbaikan yang lebih kecil", atau "setelah selesai, periksa juga pengujian" diklasifikasikan sebagai masukan status, pembatalan, pengarahan, atau tindak lanjut untuk sesi aktif. Hasil status, pembatalan, pengarahan yang diterima, dan tindak lanjut diucapkan kembali ke kanal suara agar penelepon mengetahui apakah OpenClaw menangani permintaan tersebut.

Bentuk target yang berguna:

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

Contoh OpenAI Realtime dengan gema tinggi:

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

Gunakan ini ketika model mendengar pemutaran Discord-nya sendiri melalui mikrofon terbuka, tetapi Anda tetap ingin menyelanya dengan berbicara. OpenClaw mencegah OpenAI menyela otomatis berdasarkan audio masukan mentah, sementara bargeIn: true memungkinkan peristiwa mulai bicara Discord dan audio pembicara yang sudah aktif membatalkan respons waktu nyata aktif sebelum giliran tangkapan berikutnya mencapai OpenAI. Sinyal penyelaan yang sangat awal dengan audioEndMs di bawah minBargeInAudioEndMs dianggap kemungkinan gema/gangguan 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 waktu nyata dimulai: discord voice: realtime bridge starting ... autoRespond=false interruptResponse=false bargeIn=false minBargeInAudioEndMs=...
• Saat audio pembicara: 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=...
• Saat ucapan kedaluwarsa dilewati: discord voice: realtime forced agent consult skipped reason=incomplete-transcript ... atau reason=non-actionable-closing ...
• Saat respons waktu nyata selesai: discord voice: realtime audio playback finishing reason=response.done ... audioMs=... chunks=...
• Saat pemutaran dihentikan/direset: discord voice: realtime audio playback stopped reason=... audioMs=... elapsedMs=... chunks=...
• Saat konsultasi waktu nyata: discord voice: realtime consult requested ... voiceSession=... supervisorSession=... question=...
• Saat jawaban agen: discord voice: agent turn answer ...
• Saat ucapan persis dimasukkan ke antrean: discord voice: realtime exact speech queued ... queued=... outputAudioMs=... outputActive=..., diikuti oleh discord voice: realtime exact speech dequeued reason=player-idle ...
• Saat penyelaan terdeteksi: 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=...
• Saat interupsi waktu nyata: 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 ...
• Saat gema/gangguan diabaikan: discord voice: realtime model interrupt ignored client:conversation.item.truncate.skipped reason=barge-in audioEndMs=0 minAudioEndMs=250
• Saat penyelaan dinonaktifkan: discord voice: realtime capture ignored during playback (barge-in disabled) ...
• Saat pemutaran tidak aktif: discord voice: realtime barge-in ignored reason=... outputActive=false ... playbackChunks=0

Untuk men-debug audio yang terpotong, baca log suara waktu nyata sebagai garis waktu:

1. realtime audio playback started berarti Discord telah mulai memutar audio asisten. Bridge mulai menghitung potongan keluaran asisten, byte PCM Discord, byte waktu nyata penyedia, dan durasi audio yang disintesis sejak titik ini.
2. realtime speaker turn opened menandai pembicara Discord mulai 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 pembicara tersebut. outputActive=true atau outputAudioMs yang bukan nol di sini berarti mikrofon mengirimkan masukan saat pemutaran asisten masih aktif.
4. barge-in detected source=active-speaker-audio berarti OpenClaw mendeteksi audio pembicara langsung saat pemutaran asisten aktif. Ini berguna untuk membedakan interupsi nyata dari peristiwa mulai bicara Discord tanpa audio yang dapat digunakan.
5. barge-in requested reason=... berarti OpenClaw meminta penyedia waktu nyata untuk membatalkan atau memotong respons aktif. Ini menyertakan outputAudioMs, outputActive, dan playbackChunks agar Anda dapat melihat seberapa banyak audio asisten yang benar-benar telah diputar sebelum interupsi.
6. realtime audio playback stopped reason=... adalah titik reset pemutaran Discord lokal. Alasannya menunjukkan pihak 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 masukan yang ditangkap. chunks=0 atau hasAudio=false berarti giliran pembicara dibuka tetapi tidak ada audio yang dapat digunakan mencapai bridge waktu nyata. interruptedPlayback=true berarti giliran masukan tersebut bertumpang tindih dengan keluaran asisten dan memicu logika penyelaan.

Bidang yang berguna:

• outputAudioMs: durasi audio asisten yang dihasilkan oleh penyedia waktu nyata sebelum baris log.
• audioMs: durasi audio asisten yang dihitung OpenClaw sebelum pemutaran berhenti.
• elapsedMs: waktu jam nyata antara membuka dan menutup stream pemutaran atau giliran pembicara.
• discordBytes: byte PCM stereo 48 kHz yang dikirim ke atau diterima dari suara Discord.
• realtimeBytes: byte PCM berformat penyedia yang dikirim ke atau diterima dari penyedia waktu nyata.
• playbackChunks: potongan audio asisten yang diteruskan ke Discord untuk respons aktif.
• sinceLastAudioMs: selang antara frame audio pembicara terakhir yang ditangkap dan penutupan giliran pembicara.

Pola umum:

• Pemutusan langsung dengan source=active-speaker-audio, outputAudioMs yang kecil, dan pengguna yang sama berada di dekatnya biasanya menunjukkan gema speaker masuk ke mikrofon. Naikkan voice.realtime.minBargeInAudioEndMs, turunkan volume speaker, gunakan headphone, atau atur voice.realtime.providers.openai.interruptResponseOnInputAudio: false.
• source=speaker-start yang diikuti oleh speaker turn closed ... hasAudio=false berarti Discord melaporkan bahwa pengguna mulai berbicara, tetapi tidak ada audio yang mencapai OpenClaw. Hal ini dapat disebabkan oleh peristiwa suara Discord sementara, perilaku gerbang derau, atau klien yang mengaktifkan mikrofon sesaat.
• audio playback stopped reason=stream-close tanpa interupsi 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 mengabaikan input saat audio asisten aktif. Aktifkan voice.realtime.bargeIn jika Anda ingin ucapan menginterupsi pemutaran.
• barge-in ignored ... outputActive=false berarti VAD Discord atau penyedia mendeteksi ucapan, tetapi OpenClaw tidak memiliki pemutaran aktif untuk diinterupsi. Hal ini seharusnya tidak memutus audio.

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

Pesan suara

Pesan suara Discord menampilkan pratinjau bentuk gelombang dan memerlukan audio OGG/Opus. OpenClaw menghasilkan bentuk gelombang secara otomatis, tetapi memerlukan ffmpeg dan ffprobe pada host gateway untuk memeriksa dan mengonversinya.

• Berikan jalur file lokal (URL ditolak).
• Hilangkan konten teks (Discord menolak teks + pesan suara dalam payload yang sama).
• Format audio apa pun diterima; OpenClaw mengonversinya menjadi 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: {defaults: {  botLoopProtection: {    maxEventsPerWindow: 20,    windowSeconds: 60,    cooldownSeconds: 60,  },},discord: {  // Penggantian opsional untuk seluruh Discord. Blok akun menggantikan setiap  // bidang dan mewarisi bidang yang dihilangkan dari sini.  botLoopProtection: {    maxEventsPerWindow: 4,  },  accounts: {    alpha: {      // Alpha hanya mendengarkan bot lain saat mereka menyebutnya.      allowBots: "mentions",    },    bravo: {      // Bravo mendengarkan semua pesan Discord yang dibuat oleh bot.      allowBots: true,      mentionAliases: {        // Memungkinkan Bravo menulis penyebutan Discord untuk Alpha dengan ID pengguna yang dikonfigurasi.        Alpha: "ALPHA_DISCORD_USER_ID",      },      botLoopProtection: {        // Izinkan hingga lima pesan per menit sebelum membatasi pasangan.        maxEventsPerWindow: 5,        windowSeconds: 60,        cooldownSeconds: 90,      },    },  },},},}

Referensi konfigurasi

Referensi utama: Referensi konfigurasi - Discord.

Aktivitas Discord

Atur channels.discord.activities agar agen dapat memposting widget HTML mandiri yang terbuka di dalam Discord. Blok ini bersifat opsional; jika tidak ada, OpenClaw tidak mendaftarkan rute Activity, alat, atau pemroses interaksi. Lihat Aktivitas Discord untuk penyiapan Developer Portal, tunnel, keamanan, dan pemecahan masalah.

• activities.clientSecret: rahasia klien OAuth2 untuk aplikasi Discord; beralih ke DISCORD_CLIENT_SECRET jika tidak tersedia
• activities.applicationId: ID aplikasi Activity opsional; secara default menggunakan ID aplikasi bot yang diperoleh saat gateway dimulai

Keamanan dan operasi

• Perlakukan token bot sebagai rahasia (DISCORD_BOT_TOKEN lebih disarankan dalam lingkungan yang diawasi).
• Berikan izin Discord dengan hak akses minimum.
• Jika penerapan/status perintah sudah usang, mulai ulang gateway dan periksa kembali dengan openclaw channels status --probe.

Terkait