​

Discord (Bot API)

​

Quick setup

openclaw config set channels.discord.token '"YOUR_BOT_TOKEN"' --json
openclaw config set channels.discord.enabled true --json
openclaw gateway

{
  channels: {
    discord: {
      enabled: true,
      token: "YOUR_BOT_TOKEN",
    },
  },
}

DISCORD_BOT_TOKEN=...

openclaw pairing list discord
openclaw pairing approve discord <CODE>

​

Recommended: Set up a guild workspace

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

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

​

Runtime model

• gateway가 Discord connection을 소유합니다.
• reply routing은 결정적입니다. Discord로 들어온 요청은 Discord로 다시 응답합니다.
• 기본값(session.dmScope=main)에서는 direct chat이 agent의 main session(agent:main:main)을 공유합니다.
• guild channel은 격리된 session key(agent:<agentId>:discord:channel:<channelId>)를 사용합니다.
• group DM은 기본적으로 무시됩니다(channels.discord.dm.groupEnabled=false).
• native slash command는 격리된 command session(agent:<agentId>:discord:slash:<userId>)에서 실행되지만, 라우팅 대상 대화 session에는 CommandTargetSessionKey를 계속 전달합니다.

​

Forum channels

• forum parent(channel:<forumId>)에 메시지를 보내 thread를 자동 생성합니다. 제목은 메시지의 첫 번째 non-empty line을 사용합니다.
• openclaw message thread create로 thread를 직접 생성합니다. forum channel에서는 --message-id를 넘기지 마세요.

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

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

​

Interactive components

• text, section, separator, actions, media-gallery, file
• action row는 최대 5개의 button 또는 단일 select menu를 가질 수 있음
• select type: string, user, role, mentionable, channel

• file block은 attachment://<filename> 참조를 가리켜야 함
• 첨부 파일은 media/path/filePath(단일 파일)로 제공
• 여러 파일은 media-gallery 사용
• 업로드 이름이 attachment reference와 맞아야 할 때는 filename 지정

• components.modal에 최대 5개의 field를 추가
• field type: text, checkbox, radio, select, role-select, user-select
• OpenClaw가 trigger button을 자동으로 추가

{
  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

{
  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

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

​

Developer Portal setup

​

Native commands and command auth

• commands.native의 기본값은 "auto"이며 Discord에서 활성화됩니다.
• channel 단위 override는 channels.discord.commands.native를 사용합니다.
• commands.native=false는 이전에 등록된 Discord native command를 명시적으로 제거합니다.
• native command 인증은 일반 메시지 처리와 동일한 Discord allowlist/policy를 사용합니다.
• 권한이 없는 사용자에게도 Discord UI에서 command가 보일 수는 있지만, 실제 실행 시에는 OpenClaw auth가 적용되어 “not authorized”가 반환됩니다.

• ephemeral: true

​

Feature details

{
  channels: {
    discord: {
      streaming: "partial",
    },
  },
}

{
  channels: {
    discord: {
      streaming: "block",
      draftChunk: {
        minChars: 200,
        maxChars: 800,
        breakPreference: "paragraph",
      },
    },
  },
}

{
  session: {
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
  },
  channels: {
    discord: {
      threadBindings: {
        enabled: true,
        idleHours: 24,
        maxAgeHours: 0,
        spawnSubagentSessions: false, // opt-in
      },
    },
  },
}

{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "discord",
        accountId: "default",
        peer: { kind: "channel", id: "222222222222222222" },
      },
      acp: { label: "codex-main" },
    },
  ],
  channels: {
    discord: {
      guilds: {
        "111111111111111111": {
          channels: {
            "222222222222222222": {
              requireMention: false,
            },
          },
        },
      },
    },
  },
}

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

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

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

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

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

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

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

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

​

Tools and action gates

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

​

Components v2 UI

• channels.discord.ui.components.accentColor는 Discord component container의 accent color(hex)를 설정합니다.
• account별로는 channels.discord.accounts.<id>.ui.components.accentColor를 사용합니다.
• components v2가 존재하면 embeds는 무시됩니다.

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

​

Voice channels

• native command를 활성화해야 함(commands.native 또는 channels.discord.commands.native)
• channels.discord.voice를 설정해야 함
• target voice channel에서 bot에 Connect + Speak 권한이 있어야 함

{
  channels: {
    discord: {
      voice: {
        enabled: true,
        autoJoin: [
          {
            guildId: "123456789012345678",
            channelId: "234567890123456789",
          },
        ],
        daveEncryption: true,
        decryptionFailureTolerance: 24,
        tts: {
          provider: "openai",
          openai: { voice: "alloy" },
        },
      },
    },
  },
}

• voice.tts는 voice playback에 대해서만 messages.tts를 override함
• voice transcript turn은 Discord allowFrom(또는 dm.allowFrom) 기준으로 owner status를 파생하며, non-owner speaker는 owner-only tool(예: gateway, cron)에 접근할 수 없음
• voice는 기본 활성화 상태이며, 비활성화하려면 channels.discord.voice.enabled=false
• voice.daveEncryption과 voice.decryptionFailureTolerance는 @discordjs/voice join option으로 그대로 전달됨
• @discordjs/voice 기본값은 각각 daveEncryption=true, decryptionFailureTolerance=24
• OpenClaw는 receive decrypt failure를 감시하고, 짧은 시간 동안 반복 실패가 발생하면 voice channel을 leave/rejoin하여 자동 복구를 시도함
• receive log에 DecryptionFailed(UnencryptedWhenPassthroughDisabled)가 반복되면, upstream @discordjs/voice receive bug인 discord.js #11419와 비교해 보세요

​

Voice messages

• local file path를 제공해야 함(URL은 거부됨)
• text content는 생략해야 함(Discord는 같은 payload에서 text + voice message를 허용하지 않음)
• 어떤 audio format이든 입력 가능하며, 필요하면 OpenClaw가 OGG/Opus로 변환

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

​

Troubleshooting

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

{
  channels: {
    discord: {
      accounts: {
        default: {
          eventQueue: {
            listenerTimeout: 120000,
          },
          inboundWorker: {
            runTimeoutMs: 1800000,
          },
        },
      },
    },
  },
}

​

Configuration reference pointers

• Configuration reference - Discord

• startup/auth: enabled, token, accounts.*, allowBots
• policy: groupPolicy, dm.*, guilds.*, guilds.*.channels.*
• command: commands.native, commands.useAccessGroups, configWrites, slashCommand.*
• event queue: eventQueue.listenerTimeout(listener budget), eventQueue.maxQueueSize, eventQueue.maxConcurrency
• inbound worker: inboundWorker.runTimeoutMs
• reply/history: replyToMode, historyLimit, dmHistoryLimit, dms.*.historyLimit
• delivery: textChunkLimit, chunkMode, maxLinesPerMessage
• streaming: streaming(legacy alias: streamMode), draftChunk, blockStreaming, blockStreamingCoalesce
• media/retry: mediaMaxMb, retry
  • mediaMaxMb는 outbound Discord upload 상한(default: 8MB)
• actions: actions.*
• presence: activity, status, activityType, activityUrl
• UI: ui.components.accentColor
• features: threadBindings, top-level bindings[](type: "acp"), pluralkit, execApprovals, intents, agentComponents, heartbeat, responsePrefix

​

Safety and operations

• bot token은 secret으로 취급하세요. supervised environment에서는 DISCORD_BOT_TOKEN 사용을 권장합니다.
• Discord permission은 최소 권한 원칙으로 부여하세요.
• command 배포 상태가 stale해 보이면 gateway를 재시작하고 openclaw channels status --probe로 다시 확인하세요.

​

Related

• Pairing
• Channel routing
• Multi-agent routing
• Troubleshooting
• Slash commands