Discord

Discord supports reply tags in agent output:

• [[reply_to_current]]
• [[reply_to:<id>]]

Controlled by channels.discord.replyToMode:

• off (default)
• first
• all
• batched

Note: off disables implicit reply threading. Explicit [[reply_to_*]] tags are still honored. first always attaches the implicit native reply reference to the first outbound Discord message for the turn. batched only attaches Discord's implicit native reply reference when the inbound turn was a debounced batch of multiple messages. This is useful when you want native replies mainly for ambiguous bursty chats, not every single-message turn.

Message IDs are surfaced in context/history so agents can target specific messages.

OpenClaw can stream draft replies by sending a temporary message and editing it as text arrives. channels.discord.streaming takes off | partial | block | progress (default). progress keeps one editable status draft and updates it with tool progress until final delivery; streamMode is a legacy runtime alias. Run openclaw doctor --fix to rewrite persisted config to the canonical key.

Set channels.discord.streaming.mode to off to disable Discord preview edits. If Discord block streaming is explicitly enabled, OpenClaw skips the preview stream to avoid double-streaming.

{
channels: {
discord: {
  streaming: {
    mode: "progress",
    progress: {
      label: "auto",
      maxLines: 8,
      toolProgress: true,
    },
  },
},
},
}

• partial edits a single preview message as tokens arrive.
• block emits draft-sized chunks (use draftChunk to tune size and breakpoints, clamped to textChunkLimit).
• Media, error, and explicit-reply finals cancel pending preview edits.
• streaming.preview.toolProgress (default true) controls whether tool/progress updates reuse the preview message.
• streaming.preview.commandText / streaming.progress.commandText controls command/exec detail in compact progress lines: raw (default) or status (tool label only).

Hide raw command/exec text while keeping compact progress lines:

{
  "channels": {
    "discord": {
      "streaming": {
        "mode": "progress",
        "progress": {
          "toolProgress": true,
          "commandText": "status"
        }
      }
    }
  }
}

Preview streaming is text-only; media replies fall back to normal delivery. When block streaming is explicitly enabled, OpenClaw skips the preview stream to avoid double-streaming.

Guild history context:

• channels.discord.historyLimit default 20
• fallback: messages.groupChat.historyLimit
• 0 disables

DM history controls:

• channels.discord.dmHistoryLimit
• channels.discord.dms["<user_id>"].historyLimit

Thread behavior:

• Discord threads route as channel sessions and inherit parent channel config unless overridden.
• Thread sessions inherit the parent channel's session-level /model selection as a model-only fallback; thread-local /model selections still take precedence and parent transcript history is not copied unless transcript inheritance is enabled.
• channels.discord.thread.inheritParent (default false) opts new auto-threads into seeding from the parent transcript. Per-account overrides live under channels.discord.accounts.<id>.thread.inheritParent.
• Message-tool reactions can resolve user:<id> DM targets.
• guilds.<guild>.channels.<channel>.requireMention: false is preserved during reply-stage activation fallback.

Channel topics are injected as untrusted context. Allowlists gate who can trigger the agent, not a full supplemental-context redaction boundary.

Discord can bind a thread to a session target so follow-up messages in that thread keep routing to the same session (including subagent sessions).

Commands:

• /focus <target> bind current/new thread to a subagent/session target
• /unfocus remove current thread binding
• /agents show active runs and binding state
• /session idle <duration|off> inspect/update inactivity auto-unfocus for focused bindings
• /session max-age <duration|off> inspect/update hard max age for focused bindings

Config:

{
session: {
threadBindings: {
  enabled: true,
  idleHours: 24,
  maxAgeHours: 0,
},
},
channels: {
discord: {
  threadBindings: {
    enabled: true,
    idleHours: 24,
    maxAgeHours: 0,
    spawnSessions: true,
    defaultSpawnContext: "fork",
  },
},
},
}

Notes:

• session.threadBindings.* sets global defaults.
• channels.discord.threadBindings.* overrides Discord behavior.
• spawnSessions controls auto-create/bind threads for sessions_spawn({ thread: true }) and ACP thread spawns. Default: true.
• defaultSpawnContext controls native subagent context for thread-bound spawns. Default: "fork".
• Deprecated spawnSubagentSessions/spawnAcpSessions keys are migrated by openclaw doctor --fix.
• If thread bindings are disabled for an account, /focus and related thread binding operations are unavailable.

See Sub-agents, ACP Agents, and Configuration Reference.

For stable "always-on" ACP workspaces, configure top-level typed ACP bindings targeting Discord conversations.

Config path:

• bindings[] with type: "acp" and match.channel: "discord"

Example:

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

Notes:

• /acp spawn codex --bind here binds the current channel or thread in place and keeps future messages on the same ACP session. Thread messages inherit the parent channel binding.
• In a bound channel or thread, /new and /reset reset the same ACP session in place. Temporary thread bindings can override target resolution while active.
• spawnSessions gates child thread creation/binding via --thread auto|here.

See ACP Agents for binding behavior details.

Per-guild reaction notification mode:

• off
• own (default)
• all
• allowlist (uses guilds.<id>.users)

Reaction events are turned into system events and attached to the routed Discord session.

ackReaction sends an acknowledgement emoji while OpenClaw is processing an inbound message.

Resolution order:

• channels.discord.accounts.<accountId>.ackReaction
• channels.discord.ackReaction
• messages.ackReaction
• agent identity emoji fallback (agents.list[].identity.emoji, else "👀")

Notes:

• Discord accepts unicode emoji or custom emoji names.
• Use "" to disable the reaction for a channel or account.

Channel-initiated config writes are enabled by default.

This affects /config set|unset flows (when command features are enabled).

Disable:

{
channels: {
discord: {
  configWrites: false,
},
},
}

Route Discord gateway WebSocket traffic and startup REST lookups (application ID + allowlist resolution) through an HTTP(S) proxy with channels.discord.proxy.

{
channels: {
discord: {
  proxy: "http://proxy.example:8080",
},
},
}

Per-account override:

{
channels: {
discord: {
  accounts: {
    primary: {
      proxy: "http://proxy.example:8080",
    },
  },
},
},
}

Enable PluralKit resolution to map proxied messages to system member identity:

{
channels: {
discord: {
  pluralkit: {
    enabled: true,
    token: "pk_live_...", // optional; needed for private systems
  },
},
},
}

Notes:

• allowlists can use pk:<memberId>
• member display names are matched by name/slug only when channels.discord.dangerouslyAllowNameMatching: true
• lookups use original message ID and are time-window constrained
• if lookup fails, proxied messages are treated as bot messages and dropped unless allowBots=true

Use mentionAliases when agents need deterministic outbound mentions for known Discord users. Keys are handles without the leading @; values are Discord user IDs. Unknown handles, @everyone, @here, and mentions inside Markdown code spans are left unchanged.

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

Presence updates are applied when you set a status or activity field, or when you enable auto presence.

Status only example:

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

Activity example (custom status is the default activity type):

{
channels: {
discord: {
  activity: "Focus time",
  activityType: 4,
},
},
}

Streaming example:

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

Activity type map:

• 0: Playing
• 1: Streaming (requires activityUrl)
• 2: Listening
• 3: Watching
• 4: Custom (uses the activity text as the status state; emoji is optional)
• 5: Competing

Auto presence example (runtime health signal):

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

Auto presence maps runtime availability to Discord status: healthy => online, degraded or unknown => idle, exhausted or unavailable => dnd. Optional text overrides:

• autoPresence.healthyText
• autoPresence.degradedText
• autoPresence.exhaustedText (supports {reason} placeholder)

Discord supports button-based approval handling in DMs and can optionally post approval prompts in the originating channel.

Config path:

• channels.discord.execApprovals.enabled
• channels.discord.execApprovals.approvers (optional; falls back to commands.ownerAllowFrom when possible)
• channels.discord.execApprovals.target (dm | channel | both, default: dm)
• agentFilter, sessionFilter, cleanupAfterResolve

Discord auto-enables native exec approvals when enabled is unset or "auto" and at least one approver can be resolved, either from execApprovals.approvers or from commands.ownerAllowFrom. Discord does not infer exec approvers from channel allowFrom, legacy dm.allowFrom, or direct-message defaultTo. Set enabled: false to disable Discord as a native approval client explicitly.

For sensitive owner-only group commands such as /diagnostics and /export-trajectory, OpenClaw sends approval prompts and final results privately. It tries Discord DM first when the invoking owner has a Discord owner route; if that is not available, it falls back to the first available owner route from commands.ownerAllowFrom, such as Telegram.

When target is channel or both, the approval prompt is visible in the channel. Only resolved approvers can use the buttons; other users receive an ephemeral denial. Approval prompts include the command text, so only enable channel delivery in trusted channels. If the channel ID cannot be derived from the session key, OpenClaw falls back to DM delivery.

Discord also renders the shared approval buttons used by other chat channels. The native Discord adapter mainly adds approver DM routing and channel fanout. When those buttons are present, they are the primary approval UX; OpenClaw should only include a manual /approve command when the tool result says chat approvals are unavailable or manual approval is the only path. If the Discord native approval runtime is not active, OpenClaw keeps the local deterministic /approve <id> <decision> prompt visible. If the runtime is active but a native card cannot be delivered to any target, OpenClaw sends a same-chat fallback notice with the exact /approve command from the pending approval.

Gateway auth and approval resolution follow the shared Gateway client contract (plugin: IDs resolve through plugin.approval.resolve; other IDs through exec.approval.resolve). Approvals expire after 30 minutes by default.

See Exec approvals.

• enable Message Content Intent
• enable Server Members Intent when you depend on user/member resolution
• restart gateway after changing intents

• verify groupPolicy
• verify guild allowlist under channels.discord.guilds
• if guild channels map exists, only listed channels are allowed
• verify requireMention behavior and mention patterns

Useful checks:

openclaw doctor
openclaw channels status --probe
openclaw logs --follow

Common causes:

• groupPolicy="allowlist" without matching guild/channel allowlist
• requireMention configured in the wrong place (must be under channels.discord.guilds or channel entry)
• sender blocked by guild/channel users allowlist

Typical logs:

• Slow listener detected ...
• stuck session: sessionKey=agent:...:discord:... state=processing ...

Discord gateway queue knobs:

• single-account: channels.discord.eventQueue.listenerTimeout
• multi-account: channels.discord.accounts.<accountId>.eventQueue.listenerTimeout
• this only controls Discord gateway listener work, not agent turn lifetime

Discord does not apply a channel-owned timeout to queued agent turns. Message listeners hand off immediately, and queued Discord runs preserve per-session ordering until the session/tool/runtime lifecycle completes or aborts the work.

{
channels: {
discord: {
  accounts: {
    default: {
      eventQueue: {
        listenerTimeout: 120000,
      },
    },
  },
},
},
}

OpenClaw fetches Discord /gateway/bot metadata before connecting. Transient failures fall back to Discord's default gateway URL and are rate-limited in logs.

Metadata timeout knobs:

• single-account: channels.discord.gatewayInfoTimeoutMs
• multi-account: channels.discord.accounts.<accountId>.gatewayInfoTimeoutMs
• env fallback when config is unset: OPENCLAW_DISCORD_GATEWAY_INFO_TIMEOUT_MS
• default: 30000 (30 seconds), max: 120000

OpenClaw waits for Discord's gateway READY event during startup and after runtime reconnects. Multi-account setups with startup staggering can need a longer startup READY window than the default.

READY timeout knobs:

• startup single-account: channels.discord.gatewayReadyTimeoutMs
• startup multi-account: channels.discord.accounts.<accountId>.gatewayReadyTimeoutMs
• startup env fallback when config is unset: OPENCLAW_DISCORD_READY_TIMEOUT_MS
• startup default: 15000 (15 seconds), max: 120000
• runtime single-account: channels.discord.gatewayRuntimeReadyTimeoutMs
• runtime multi-account: channels.discord.accounts.<accountId>.gatewayRuntimeReadyTimeoutMs
• runtime env fallback when config is unset: OPENCLAW_DISCORD_RUNTIME_READY_TIMEOUT_MS
• runtime default: 30000 (30 seconds), max: 120000

channels status --probe permission checks only work for numeric channel IDs.

If you use slug keys, runtime matching can still work, but probe cannot fully verify permissions.

• DM disabled: channels.discord.dm.enabled=false
• DM policy disabled: channels.discord.dmPolicy="disabled" (legacy: channels.discord.dm.policy)
• awaiting pairing approval in pairing mode

By default bot-authored messages are ignored.

If you set channels.discord.allowBots=true, use strict mention and allowlist rules to avoid loop behavior. Prefer channels.discord.allowBots="mentions" to only accept bot messages that mention the bot.

{
channels: {
discord: {
  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 "@Mantis" and send a real Discord mention.
        Mantis: "MANTIS_DISCORD_USER_ID",
      },
    },
  },
},
},
}

• keep OpenClaw current (openclaw update) so the Discord voice receive recovery logic is present
• confirm channels.discord.voice.daveEncryption=true (default)
• start from channels.discord.voice.decryptionFailureTolerance=24 (upstream default) and tune only if needed
• watch logs for:
  • discord voice: DAVE decrypt failures detected
  • discord voice: repeated decrypt failures; attempting rejoin
• if failures continue after automatic rejoin, collect logs and compare against the upstream DAVE receive history in discord.js #11419 and discord.js #11449