Discord

Ready for DMs and guild channels via the official Discord gateway.

Quick setup

You will need to create a new application with a bot, add the bot to your server, and pair it to OmeniaClaw. We recommend adding your bot to your own private server. If you don't have one yet, create one first (choose 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" },},},}JSON5OmeniaClaw config patch --file ./discord.patch.json5 --dry-runOmeniaClaw config patch --file ./discord.patch.json5OmeniaClaw 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",},},},},}

OmeniaClaw pairing list discordOmeniaClaw pairing approve discord <CODE>

Recommended: Set up a guild workspace

Once DMs are working, you can set up your Discord server as a full workspace where each channel gets its own agent session with its own context. This is recommended for private servers where it's just you and your bot.

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

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

Now create some channels on your Discord server and start chatting. Your agent can see the channel name, and each channel gets its own isolated session — so you can set up #coding, #home, #research, or whatever fits your workflow.

Runtime model

• Gateway owns the Discord connection.
• Reply routing is deterministic: Discord inbound replies back to Discord.
• Discord guild/channel metadata is added to the model prompt as untrusted context, not as a user-visible reply prefix. If a model copies that envelope back, OmeniaClaw strips the copied metadata from outbound replies and from future replay context.
• By default (session.dmScope=main), direct chats share the agent main session (agent:main:main).
• Guild channels are isolated session keys (agent:<agentId>:discord:channel:<channelId>).
• Group DMs are ignored by default (channels.discord.dm.groupEnabled=false).
• Native slash commands run in isolated command sessions (agent:<agentId>:discord:slash:<userId>), while still carrying CommandTargetSessionKey to the routed conversation session.
• Text-only cron/heartbeat announce delivery to Discord uses the final assistant-visible answer once. Media and structured component payloads remain multi-message when the agent emits multiple deliverable payloads.

Forum channels

Discord forum and media channels only accept thread posts. OmeniaClaw supports two ways to create them:

• Send a message to the forum parent (channel:<forumId>) to auto-create a thread. The thread title uses the first non-empty line of your message.
• Use OmeniaClaw message thread create to create a thread directly. Do not pass --message-id for forum channels.

Example: send to forum parent to create a thread

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

Example: create a forum thread explicitly

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

Forum parents do not accept Discord components. If you need components, send to the thread itself (channel:<threadId>).

Interactive components

OmeniaClaw supports Discord components v2 containers for agent messages. Use the message tool with a components payload. Interaction results are routed back to the agent as normal inbound messages and follow the existing Discord replyToMode settings.

Supported blocks:

• text, section, separator, actions, media-gallery, file
• Action rows allow up to 5 buttons or a single select menu
• Select types: string, user, role, mentionable, channel

By default, components are single use. Set components.reusable=true to allow buttons, selects, and forms to be used multiple times until they expire.

To restrict who can click a button, set allowedUsers on that button (Discord user IDs, tags, or *). When configured, unmatched users receive an ephemeral denial.

Component callbacks expire after 30 minutes by default. Set channels.discord.agentComponents.ttlMs to change that callback registry lifetime for the default Discord account, or channels.discord.accounts.<accountId>.agentComponents.ttlMs to override one account in a multi-account setup. The value is milliseconds, must be a positive integer, and is capped at 86400000 (24 hours). Longer TTLs are useful for review or approval workflows that need buttons to remain usable, but they also extend the window where an old Discord message can still trigger an action. Prefer the shortest TTL that fits the workflow, and keep the default when stale callbacks would be surprising.

The /model and /models slash commands open an interactive model picker with provider, model, and compatible runtime dropdowns plus a Submit step. /models add is deprecated and now returns a deprecation message instead of registering models from chat. The picker reply is ephemeral and only the invoking user can use it. Discord select menus are limited to 25 options, so add provider/* entries to agents.defaults.models when you want the picker to show dynamically discovered models only for selected providers such as openai or vllm.

File attachments:

• file blocks must point to an attachment reference (attachment://<filename>)
• Provide the attachment via media/path/filePath (single file); use media-gallery for multiple files
• Use filename to override the upload name when it should match the attachment reference

Modal forms:

• Add components.modal with up to 5 fields
• Field types: text, checkbox, radio, select, role-select, user-select
• OmeniaClaw adds a trigger button automatically

Example:

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

Access control and routing

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

Role-based agent routing

Use bindings[].match.roles to route Discord guild members to different agents by role ID. Role-based bindings accept role IDs only and are evaluated after peer or parent-peer bindings and before guild-only bindings. If a binding also sets other match fields (for example peer + guildId + roles), all configured fields must match.

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

Native commands and command auth

• commands.native defaults to "auto" and is enabled for Discord.
• Per-channel override: channels.discord.commands.native.
• commands.native=false skips Discord slash-command registration and cleanup during startup. Previously registered commands may remain visible in Discord until you remove them from the Discord app.
• Native command auth uses the same Discord allowlists/policies as normal message handling.
• Commands may still be visible in Discord UI for users who are not authorized; execution still enforces OmeniaClaw auth and returns "not authorized".

See Slash commands for command catalog and behavior.

Default slash command settings:

• ephemeral: true

Feature details

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

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

Tools and action gates

Discord message actions include messaging, channel admin, moderation, presence, and metadata actions.

Core examples:

• messaging: sendMessage, readMessages, editMessage, deleteMessage, threadReply
• reactions: react, reactions, emojiList
• moderation: timeout, kick, ban
• presence: setPresence

The event-create action accepts an optional image parameter (URL or local file path) to set the scheduled event cover image.

Action gates live under channels.discord.actions.*.

Default gate behavior:

Components v2 UI

OmeniaClaw uses Discord components v2 for exec approvals and cross-context markers. Discord message actions can also accept components for custom UI (advanced; requires constructing a component payload via the discord tool), while legacy embeds remain available but are not recommended.

• channels.discord.ui.components.accentColor sets the accent color used by Discord component containers (hex).
• Set per account with channels.discord.accounts.<id>.ui.components.accentColor.
• channels.discord.agentComponents.ttlMs controls how long sent Discord component callbacks remain registered (default 1800000, maximum 86400000). Set per account with channels.discord.accounts.<id>.agentComponents.ttlMs.
• embeds are ignored when components v2 are present.
• Plain URL previews are suppressed by default. Set suppressEmbeds: false on a message action when a single outbound link should expand.

Example:

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

Voice

Discord has two distinct voice surfaces: realtime voice channels (continuous conversations) and voice message attachments (the waveform preview format). The gateway supports both.

Voice channels

Setup checklist:

1. Enable Message Content Intent in the Discord Developer Portal.
2. Enable Server Members Intent when role/user allowlists are used.
3. Invite the bot with bot and applications.commands scopes.
4. Grant Connect, Speak, Send Messages, and Read Message History in the target voice channel.
5. Enable native commands (commands.native or channels.discord.commands.native).
6. Configure channels.discord.voice.

Use /vc join|leave|status to control sessions. The command uses the account default agent and follows the same allowlist and group policy rules as other Discord commands.

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

To inspect the bot's effective permissions before joining, run:

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

Auto-join example:

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

Notes:

• voice.tts overrides messages.tts for stt-tts voice playback only. Realtime modes use voice.realtime.speakerVoice.
• voice.mode controls the conversation path. The default is agent-proxy: a realtime voice front end handles turn timing, interruption, and playback, delegates substantive work to the routed OmeniaClaw agent through OmeniaClaw_agent_consult, and treats the result like a typed Discord prompt from that speaker. stt-tts keeps the older batch STT plus TTS flow. bidi lets the realtime model converse directly while exposing OmeniaClaw_agent_consult for the OmeniaClaw brain.
• voice.agentSession controls which OmeniaClaw conversation receives voice turns. Leave it unset for the voice channel's own session, or set { mode: "target", target: "channel:<text-channel-id>" } to make the voice channel act as the microphone/speaker extension of an existing Discord text channel session such as #maintainers.
• voice.model overrides the OmeniaClaw agent brain for Discord voice responses and realtime consults. Leave it unset to inherit the routed agent model. It is separate from voice.realtime.model.
• voice.followUsers lets the bot join, move, and leave Discord voice with selected users. See Follow users in voice for behavior rules and examples.
• agent-proxy routes speech through discord-voice, which preserves normal owner/tool authorization for the speaker and target session but hides the agent tts tool because Discord voice owns playback. By default, agent-proxy gives the consult full owner-equivalent tool access for owner speakers (voice.realtime.toolPolicy: "owner") and strongly prefers consulting the OmeniaClaw agent before substantive answers (voice.realtime.consultPolicy: "always"). In that default always mode, the realtime layer does not auto-speak filler before the consult answer; it captures and transcribes speech, then speaks the routed OmeniaClaw answer. If multiple forced consult answers finish while Discord is still playing the first answer, later exact-speech answers are queued until playback idles instead of replacing speech mid-sentence.
• In stt-tts mode, STT uses tools.media.audio; voice.model does not affect transcription.
• In realtime modes, voice.realtime.provider, voice.realtime.model, and voice.realtime.speakerVoice configure the realtime audio session. For OpenAI Realtime 2 plus the Codex brain, use voice.realtime.model: "gpt-realtime-2" and voice.model: "openai/gpt-5.5".
• Realtime voice modes include small IDENTITY.md, USER.md, and SOUL.md profile files in the realtime provider instructions by default so fast direct turns keep the same identity, user grounding, and persona as the routed OmeniaClaw agent. Set voice.realtime.bootstrapContextFiles to a subset to customize this, or [] to disable it. The supported realtime bootstrap files are limited to those profile files; AGENTS.md stays in the normal agent context. The injected profile context does not replace OmeniaClaw_agent_consult for workspace work, current facts, memory lookup, or tool-backed actions.
• In OpenAI agent-proxy realtime mode, set voice.realtime.requireWakeName: true to keep Discord realtime voice silent until a transcript starts or ends with a wake name. Configured wake names must be one or two words. If voice.realtime.wakeNames is unset, OmeniaClaw uses the routed agent name plus OmeniaClaw, falling back to the agent id plus OmeniaClaw. Wake-name gating disables realtime provider auto-response, routes accepted turns through the OmeniaClaw agent consult path, and gives a short spoken acknowledgement when a leading wake name is recognized from partial transcription before the final transcript arrives.
• The OpenAI realtime provider accepts current Realtime 2 event names and legacy Codex-compatible aliases for output audio and transcript events, so compatible provider snapshots can drift without dropping assistant audio.
• voice.realtime.bargeIn controls whether Discord speaker-start events interrupt active realtime playback. If unset, it follows the realtime provider's input-audio interruption setting.
• voice.realtime.minBargeInAudioEndMs controls the minimum assistant playback duration before an OpenAI realtime barge-in truncates audio. Default: 250. Set 0 for immediate interruption in low-echo rooms, or raise it for echo-heavy speaker setups.
• For an OpenAI voice on Discord playback, set voice.tts.provider: "openai" and choose a Text-to-speech voice under voice.tts.providers.openai.speakerVoice. cedar is a good masculine-sounding choice on the current OpenAI TTS model.
• Per-channel Discord systemPrompt overrides apply to voice transcript turns for that voice channel.
• Voice transcript turns derive owner status from Discord allowFrom (or dm.allowFrom) for owner-gated commands and channel actions. Agent tool visibility follows the configured tool policy for the routed session.
• Discord voice is opt-in for text-only configs; set channels.discord.voice.enabled=true (or keep an existing channels.discord.voice block) to enable /vc commands, the voice runtime, and the GuildVoiceStates gateway intent.
• channels.discord.intents.voiceStates can explicitly override voice-state intent subscription. Leave it unset for the intent to follow effective voice enablement.
• If voice.autoJoin has multiple entries for the same guild, OmeniaClaw joins the last configured channel for that guild.
• voice.allowedChannels is an optional residency allowlist. Leave it unset to allow /vc join into any authorized Discord voice channel. When set, /vc join, startup auto-join, and bot voice-state moves are restricted to the listed { guildId, channelId } entries. Set it to an empty array to deny all Discord voice joins. If Discord moves the bot outside the allowlist, OmeniaClaw leaves that channel and rejoins the configured auto-join target when one is available.
• voice.daveEncryption and voice.decryptionFailureTolerance pass through to @discordjs/voice join options.
• @discordjs/voice defaults are daveEncryption=true and decryptionFailureTolerance=24 if unset.
• OmeniaClaw uses the bundled libopus-wasm codec for Discord voice receive and realtime raw PCM playback. It ships a pinned libopus WebAssembly build and does not require native opus addons.
• voice.connectTimeoutMs controls the initial @discordjs/voice Ready wait for /vc join and auto-join attempts. Default: 30000.
• voice.reconnectGraceMs controls how long OmeniaClaw waits for a disconnected voice session to begin reconnecting before destroying it. Default: 15000.
• In stt-tts mode, voice playback does not stop just because another user starts speaking. To avoid feedback loops, OmeniaClaw ignores new voice capture while TTS is playing; speak after playback finishes for the next turn. Realtime modes forward speaker starts as barge-in signals to the realtime provider.
• In realtime modes, echo from speakers into an open mic can look like barge-in and interrupt playback. For echo-heavy Discord rooms, set voice.realtime.providers.openai.interruptResponseOnInputAudio: false to keep OpenAI from auto-interrupting on input audio. Add voice.realtime.bargeIn: true if you still want Discord speaker-start events to interrupt active playback. The OpenAI realtime bridge ignores playback truncations shorter than voice.realtime.minBargeInAudioEndMs as likely echo/noise and logs them as skipped instead of clearing Discord playback.
• voice.captureSilenceGraceMs controls how long OmeniaClaw waits after Discord reports a speaker has stopped before finalizing that audio segment for STT. Default: 2000; raise this if Discord splits normal pauses into choppy partial transcripts.
• When ElevenLabs is the selected TTS provider, Discord voice playback uses streaming TTS and starts from the provider response stream. Providers without streaming support fall back to the synthesized temp-file path.
• OmeniaClaw also watches receive decrypt failures and auto-recovers by leaving/rejoining the voice channel after repeated failures in a short window.
• If receive logs repeatedly show DecryptionFailed(UnencryptedWhenPassthroughDisabled) after updating, collect a dependency report and logs. The bundled @discordjs/voice line includes the upstream padding fix from discord.js PR #11449, which closed discord.js issue #11419.
• The operation was aborted receive events are expected when OmeniaClaw finalizes a captured speaker segment; they are verbose diagnostics, not warnings.
• Verbose Discord voice logs include a bounded one-line STT transcript preview for each accepted speaker segment, so debugging shows both the user side and the agent reply side without dumping unbounded transcript text.
• In agent-proxy mode, forced consult fallback skips likely incomplete transcript fragments such as text ending in ... or a trailing connector like and, plus obvious non-actionable closings like “be right back” or “bye”. Logs show forced agent consult skipped reason=... when this prevents a stale queued answer.

Follow users in voice

Use voice.followUsers when you want the Discord voice bot to stay with one or more known Discord users instead of joining a fixed channel at startup or waiting for /vc join.

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

Behavior:

• followUsers accepts raw Discord user IDs and discord:<id> values. OmeniaClaw normalizes both forms before matching voice-state events.
• followUsersEnabled defaults to true when followUsers is configured. Set it to false to keep the saved list but stop automatic voice following.
• When a followed user joins an allowed voice channel, OmeniaClaw joins that channel. When the user moves, OmeniaClaw moves with them. When the active followed user disconnects, OmeniaClaw leaves.
• If multiple followed users are in the same guild and the active followed user leaves, OmeniaClaw moves to another tracked followed user's channel before leaving the guild. If several followed users move at once, the latest observed voice-state event wins.
• allowedChannels still applies. A followed user in a disallowed channel is ignored, and a follow-owned session moves to another followed user or leaves.
• OmeniaClaw reconciles missed voice-state events on startup and at a bounded interval. Reconciliation samples configured guilds and caps REST lookups per run, so very large followUsers lists may take more than one interval to converge.
• If Discord or an admin moves the bot while it is following a user, OmeniaClaw rebuilds the voice session and preserves follow ownership when the destination is allowed. If the bot is moved outside allowedChannels, OmeniaClaw leaves and rejoins the configured target when one exists.
• DAVE receive recovery may leave and rejoin the same channel after repeated decrypt failures. Follow-owned sessions keep their follow ownership through that recovery path, so a later followed-user disconnect still leaves the channel.

Choose between the join modes:

• Use followUsers for personal or operator setups where the bot should automatically be in voice when you are.
• Use autoJoin for fixed-room bots that should be present even when no tracked user is in voice.
• Use /vc join for one-off joins or rooms where automatic voice presence would be surprising.

Discord voice codec:

• Voice receive logs show discord voice: opus decoder: libopus-wasm.
• Realtime playback encodes raw 48 kHz stereo PCM to Opus with the same bundled libopus-wasm package before handing packets to @discordjs/voice.
• File and provider-stream playback transcodes to raw 48 kHz stereo PCM with ffmpeg, then uses libopus-wasm for the Opus packet stream sent to Discord.

STT plus TTS pipeline:

• Discord PCM capture is converted to a WAV temp file.
• tools.media.audio handles STT, for example openai/gpt-4o-mini-transcribe.
• The transcript is sent through Discord ingress and routing while the response LLM runs with a voice-output policy that hides the agent tts tool and asks for returned text, because Discord voice owns final TTS playback.
• voice.model, when set, overrides only the response LLM for this voice-channel turn.
• voice.tts is merged over messages.tts; streaming-capable providers feed the player directly, otherwise the resulting audio file is played in the joined channel.

Default agent-proxy voice-channel session example:

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

With no voice.agentSession block, each voice channel gets its own routed OmeniaClaw session. For example, /vc join channel:234567890123456789 talks to the session for that Discord voice channel. The realtime model is only the voice front end; substantive requests are handed to the configured OmeniaClaw agent. If the realtime model produces a final transcript without calling the consult tool, OmeniaClaw forces the consult as a fallback so the default still behaves like talking to the agent.

Legacy STT plus TTS example:

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

Realtime bidi example:

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

Voice as an extension of an existing Discord channel session:

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

In agent-proxy mode the bot joins the configured voice channel, but OmeniaClaw agent turns use the target channel's normal routed session and agent. The realtime voice session speaks the returned result back into the voice channel. The supervisor agent can still use normal message tools according to its tool policy, including sending a separate Discord message if that is the right action.

While a delegated OmeniaClaw run is active, new Discord voice transcripts are treated as live run control before starting another agent turn. Phrases such as "status", "cancel that", "use the smaller fix", or "when you're done also check tests" are classified as status, cancel, steering, or follow-up input for the active session. Status, cancel, accepted steering, and follow-up outcomes are spoken back into the voice channel so the caller knows whether OmeniaClaw handled the request.

Useful target forms:

• target: "channel:123456789012345678" routes through a Discord text channel session.
• target: "123456789012345678" is treated as a channel target.
• target: "dm:123456789012345678" or target: "user:123456789012345678" routes through that direct-message session.

Echo-heavy OpenAI Realtime example:

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

Use this when the model hears its own Discord playback through an open mic, but you still want to interrupt it by speaking. OmeniaClaw keeps OpenAI from auto-interrupting on raw input audio, while bargeIn: true lets Discord speaker-start events and already-active speaker audio cancel active realtime responses before the next captured turn reaches OpenAI. Very early barge-in signals with audioEndMs below minBargeInAudioEndMs are treated as likely echo/noise and ignored so the model does not cut off at the first playback frame.

Expected voice logs:

• On join: discord voice: joining ... voiceSession=... supervisorSession=... agentSessionMode=... voiceModel=... realtimeModel=...
• On realtime start: discord voice: realtime bridge starting ... autoRespond=false interruptResponse=false bargeIn=false minBargeInAudioEndMs=...
• On speaker audio: discord voice: realtime speaker turn opened ..., discord voice: realtime input audio started ... outputAudioMs=... outputActive=..., and discord voice: realtime speaker turn closed ... chunks=... discordBytes=... realtimeBytes=... interruptedPlayback=...
• On skipped stale speech: discord voice: realtime forced agent consult skipped reason=incomplete-transcript ... or reason=non-actionable-closing ...
• On realtime response completion: discord voice: realtime audio playback finishing reason=response.done ... audioMs=... chunks=...
• On playback stop/reset: discord voice: realtime audio playback stopped reason=... audioMs=... elapsedMs=... chunks=...
• On realtime consult: discord voice: realtime consult requested ... voiceSession=... supervisorSession=... question=...
• On agent answer: discord voice: agent turn answer ...
• On queued exact speech: discord voice: realtime exact speech queued ... queued=... outputAudioMs=... outputActive=..., followed by discord voice: realtime exact speech dequeued reason=player-idle ...
• On barge-in detection: discord voice: realtime barge-in detected source=speaker-start ... or discord voice: realtime barge-in detected source=active-speaker-audio ..., followed by discord voice: realtime barge-in requested reason=... outputAudioMs=... outputActive=...
• On realtime interruption: discord voice: realtime model interrupt requested client:response.cancel reason=barge-in, followed by either discord voice: realtime model audio truncated client:conversation.item.truncate reason=barge-in audioEndMs=... or discord voice: realtime model interrupt confirmed server:response.done status=cancelled ...
• On ignored echo/noise: discord voice: realtime model interrupt ignored client:conversation.item.truncate.skipped reason=barge-in audioEndMs=0 minAudioEndMs=250
• On disabled barge-in: discord voice: realtime capture ignored during playback (barge-in disabled) ...
• On idle playback: discord voice: realtime barge-in ignored reason=... outputActive=false ... playbackChunks=0

To debug cut-off audio, read the realtime voice logs as a timeline:

1. realtime audio playback started means Discord has begun playing assistant audio. The bridge starts counting assistant output chunks, Discord PCM bytes, provider realtime bytes, and synthesized audio duration from this point.
2. realtime speaker turn opened marks a Discord speaker becoming active. If playback is already active and bargeIn is enabled, this can be followed by barge-in detected source=speaker-start.
3. realtime input audio started marks the first actual audio frame received for that speaker turn. outputActive=true or a nonzero outputAudioMs here means the mic is sending input while assistant playback is still active.
4. barge-in detected source=active-speaker-audio means OmeniaClaw saw live speaker audio while assistant playback was active. This is useful for distinguishing a real interruption from a Discord speaker-start event with no useful audio.
5. barge-in requested reason=... means OmeniaClaw asked the realtime provider to cancel or truncate the active response. It includes outputAudioMs, outputActive, and playbackChunks so you can see how much assistant audio had actually played before the interruption.
6. realtime audio playback stopped reason=... is the local Discord playback reset point. The reason says who stopped playback: barge-in, player-idle, provider-clear-audio, forced-agent-consult, stream-close, or session-close.
7. realtime speaker turn closed summarizes the captured input turn. chunks=0 or hasAudio=false means the speaker turn opened but no usable audio reached the realtime bridge. interruptedPlayback=true means that input turn overlapped assistant output and triggered barge-in logic.

Useful fields:

• outputAudioMs: assistant audio duration generated by the realtime provider before the log line.
• audioMs: assistant audio duration that OmeniaClaw counted before playback stopped.
• elapsedMs: wall-clock time between opening and closing the playback stream or speaker turn.
• discordBytes: 48 kHz stereo PCM bytes sent to or received from Discord voice.
• realtimeBytes: provider-format PCM bytes sent to or received from the realtime provider.
• playbackChunks: assistant audio chunks forwarded to Discord for the active response.
• sinceLastAudioMs: gap between the last captured speaker audio frame and the speaker turn closing.

Common patterns:

• Immediate cut-off with source=active-speaker-audio, small outputAudioMs, and the same user nearby usually points to speaker echo entering the mic. Raise voice.realtime.minBargeInAudioEndMs, lower speaker volume, use headphones, or set voice.realtime.providers.openai.interruptResponseOnInputAudio: false.
• source=speaker-start followed by speaker turn closed ... hasAudio=false means Discord reported a speaker start but no audio reached OmeniaClaw. That can be a transient Discord voice event, noise gate behavior, or a client briefly keying the mic.
• audio playback stopped reason=stream-close without a nearby barge-in or provider-clear-audio means the local Discord playback stream ended unexpectedly. Check the preceding provider and Discord player logs.
• capture ignored during playback (barge-in disabled) means OmeniaClaw intentionally dropped input while assistant audio was active. Enable voice.realtime.bargeIn if you want speech to interrupt playback.
• barge-in ignored ... outputActive=false means Discord or provider VAD reported speech, but OmeniaClaw had no active playback to interrupt. This should not cut off audio.

Credentials are resolved per component: LLM route auth for voice.model, STT auth for tools.media.audio, TTS auth for messages.tts/voice.tts, and realtime provider auth for voice.realtime.providers or the provider's normal auth config.

Voice messages

Discord voice messages show a waveform preview and require OGG/Opus audio. OmeniaClaw generates the waveform automatically, but needs ffmpeg and ffprobe on the gateway host to inspect and convert.

• Provide a local file path (URLs are rejected).
• Omit text content (Discord rejects text + voice message in the same payload).
• Any audio format is accepted; OmeniaClaw converts to OGG/Opus as needed.

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

Troubleshooting

OmeniaClaw doctorOmeniaClaw channels status --probeOmeniaClaw 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,      },    },  },},},}

Configuration reference

Primary reference: Configuration reference - Discord.

Safety and operations

• Treat bot tokens as secrets (DISCORD_BOT_TOKEN preferred in supervised environments).
• Grant least-privilege Discord permissions.
• If command deploy/state is stale, restart gateway and re-check with OmeniaClaw channels status --probe.

Related