​

Discord (Bot API)

​

빠른 설정

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>

​

권장: 길드 워크스페이스 설정

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

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

​

Runtime model

• 게이트웨이는 Discord 연결을 소유합니다.
• 응답 라우팅은 결정론적입니다: Discord로부터 받은 응답은 다시 Discord로 돌아갑니다.
• 기본적으로 (session.dmScope=main), 직접 채팅은 에이전트의 메인 세션을 공유합니다 (agent:main:main).
• 길드 채널은 격리된 세션 키입니다 (agent:<agentId>:discord:channel:<channelId>).
• 그룹 다이렉트 메시지는 기본적으로 무시됩니다 (channels.discord.dm.groupEnabled=false).
• 네이티브 슬래시 명령어는 격리된 명령어 세션 (agent:<agentId>:discord:slash:<userId>)에서 실행되며, CommandTargetSessionKey를 경로화된 대화 세션에 유지합니다.

​

포럼 채널

• 포럼 상위 채널(channel:<forumId>)로 메시지를 보내면 자동으로 스레드가 생성됩니다. 스레드 제목은 메시지의 첫 번째 비어있지 않은 줄을 사용합니다.
• openclaw message thread create를 사용하여 직접 스레드를 생성합니다. 포럼 채널에는 --message-id를 전달하지 마세요.

openclaw message send --channel discord --target channel:<forumId> \
  --message "토픽 제목\n게시물 본문"

openclaw message thread create --channel discord --target channel:<forumId> \
  --thread-name "토픽 제목" --message "게시물 본문"

​

Interactive components

• text, section, separator, actions, media-gallery, file
• 액션 행은 최대 5개의 버튼 또는 단일 선택 메뉴를 허용합니다
• 선택 유형: string, user, role, mentionable, channel

• file 블록은 첨부 파일 참조 (attachment://<filename>)를 가리켜야 합니다
• media/path/filePath를 통해 첨부 파일을 제공하세요 (단일 파일); 여러 파일의 경우 media-gallery를 사용하세요
• 첨부 파일 참조와 일치해야 하는 경우 업로드 이름을 덮어쓰려면 filename을 사용하세요

• 최대 5개의 필드로 components.modal을 추가하세요
• 필드 유형: text, checkbox, radio, select, role-select, user-select
• OpenClaw는 자동으로 트리거 버튼을 추가합니다

{
  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,
          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에서 활성화됩니다.
• 채널별 오버라이드: channels.discord.commands.native.
• commands.native=false는 이전에 등록된 Discord 네이티브 명령어를 명시적으로 지웁니다.
• 네이티브 명령어 인증은 일반 메시지 처리와 동일하게 Discord 허용 목록/정책을 사용합니다.
• 명령어는 Discord UI에 명단이 없는 사용자를 위해 표시될 수 있지만, 실행은 여전히 OpenClaw 인증을 강제하고 “승인되지 않았습니다”라는 응답을 반환합니다.

• ephemeral: true

​

Feature details

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

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

{
  session: {
    threadBindings: {
      enabled: true,
      ttlHours: 24,
    },
  },
  channels: {
    discord: {
      threadBindings: {
        enabled: true,
        ttlHours: 24,
        spawnSubagentSessions: false, // 명시적 활성화 필요
      },
    },
  },
}

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

{
  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: {
      proxy: "http://proxy.example:8080",
    },
  },
}

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

{
  channels: {
    discord: {
      pluralkit: {
        enabled: true,
        token: "pk_live_...", // 선택적; 비공개 시스템에 필요
      },
    },
  },
}

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

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

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

​

Tools and action gates

• 메시징: sendMessage, readMessages, editMessage, deleteMessage, threadReply
• 반응: react, reactions, emojiList
• 모더레이션: timeout, kick, ban
• 존재: setPresence

​

Components v2 UI

• channels.discord.ui.components.accentColor는 Discord 컴포넌트 컨테이너에 사용되는 강조 색깔을 설정합니다 (16진수).
• 계정별로 channels.discord.accounts.<id>.ui.components.accentColor에 설정합니다.
• embeds는 components v2가 있는 경우 무시됩니다.

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

​

음성 채널

• 네이티브 명령어 활성화 (commands.native 또는 channels.discord.commands.native).
• channels.discord.voice 설정.
• 봇은 대상 음성 채널에서 연결 + 발언 권한이 필요합니다.

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

• voice.tts는 음성 재생에만 messages.tts를 오버라이드합니다.
• 음성은 기본적으로 활성화됩니다; channels.discord.voice.enabled=false로 비활성화하세요.
• voice.daveEncryption 및 voice.decryptionFailureTolerance는 @discordjs/voice 참여 옵션으로 전달됩니다.
• @discordjs/voice의 기본값은 미설정 시 daveEncryption=true, decryptionFailureTolerance=24입니다.
• OpenClaw는 수신 복호화 실패를 감시하고, 짧은 시간 내 반복 실패 시 음성 채널을 나갔다가 재참여하여 자동 복구합니다.
• 수신 로그에 DecryptionFailed(UnencryptedWhenPassthroughDisabled)가 반복 표시되면 업스트림 @discordjs/voice의 discord.js #11419 버그일 수 있습니다.

​

Voice messages

• 로컬 파일 경로를 제공해야 합니다 (URL은 거부됨).
• 텍스트 콘텐츠를 생략하세요 (Discord는 동일한 페이로드에서 텍스트 + 음성 메시지를 허용하지 않습니다).
• 모든 오디오 형식이 허용됩니다; 요구 사항에 맞춰 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

​

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.*
• reply/history: replyToMode, historyLimit, dmHistoryLimit, dms.*.historyLimit
• delivery: textChunkLimit, chunkMode, maxLinesPerMessage
• streaming: streaming (레거시 별칭: streamMode), draftChunk, blockStreaming, blockStreamingCoalesce
• media/retry: mediaMaxMb, retry
• actions: actions.*
• presence: activity, status, activityType, activityUrl
• UI: ui.components.accentColor
• features: threadBindings, 최상위 bindings[] (type: "acp"), pluralkit, execApprovals, intents, agentComponents, heartbeat, responsePrefix

​

Safety and operations

• 봇 토큰을 비밀로 취급하세요 (DISCORD_BOT_TOKEN을 감시되는 환경에서 선호).
• 최소 권한의 Discord 권한을 부여하세요.
• 명령어 배포/상이 정체되면 게이트웨이를 재시작하고 openclaw channels status --probe로 다시 점검하세요.

​

Related

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