​

Discord (Bot API)

​

빠른 설정

export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN"
openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN --dry-run
openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN
openclaw config set channels.discord.enabled true --strict-json
openclaw gateway

{
  channels: {
    discord: {
      enabled: true,
      token: {
        source: "env",
        provider: "default",
        id: "DISCORD_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,
        },
      },
    },
  },
}

​

런타임 모델

• Gateway가 Discord 연결을 소유합니다.
• 응답 라우팅은 결정적입니다. Discord 수신 응답은 다시 Discord로 돌아갑니다.
• 기본값(session.dmScope=main)에서는 직접 채팅이 에이전트 메인 세션(agent:main:main)을 공유합니다.
• 길드 채널은 격리된 세션 키(agent:<agentId>:discord:channel:<channelId>)를 사용합니다.
• 그룹 DM은 기본적으로 무시됩니다(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 "Topic title\nBody of the post"

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

​

인터랙티브 컴포넌트

• 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: "선택적 폴백 텍스트",
  components: {
    reusable: true,
    text: "경로를 선택하세요",
    blocks: [
      {
        type: "actions",
        buttons: [
          {
            label: "승인",
            style: "success",
            allowedUsers: ["123456789012345678"],
          },
          { label: "거절", style: "danger" },
        ],
      },
      {
        type: "actions",
        select: {
          type: "string",
          placeholder: "옵션을 선택하세요",
          options: [
            { label: "옵션 A", value: "a" },
            { label: "옵션 B", value: "b" },
          ],
        },
      },
    ],
    modal: {
      title: "세부 정보",
      triggerLabel: "폼 열기",
      fields: [
        { type: "text", label: "요청자" },
        {
          type: "select",
          label: "우선순위",
          options: [
            { label: "낮음", value: "low" },
            { label: "높음", value: "high" },
          ],
        },
      ],
    },
  },
}

​

액세스 제어 및 라우팅

{
  channels: {
    discord: {
      groupPolicy: "allowlist",
      guilds: {
        "123456789012345678": {
          requireMention: true,
          ignoreOtherMentions: true,
          users: ["987654321098765432"],
          roles: ["123456789012345678"],
          channels: {
            general: { allow: true },
            help: { allow: true, requireMention: true },
          },
        },
      },
    },
  },
}

​

역할 기반 에이전트 라우팅

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

​

Developer Portal 설정

​

네이티브 명령과 명령 인증

• commands.native의 기본값은 "auto"이며 Discord에서 활성화됩니다.
• 채널별 재정의: channels.discord.commands.native.
• commands.native=false는 이전에 등록된 Discord 네이티브 명령을 명시적으로 제거합니다.
• 네이티브 명령 인증은 일반 메시지 처리와 동일한 Discord allowlist/정책을 사용합니다.
• 권한이 없는 사용자에게도 명령이 Discord UI에 보일 수는 있지만, 실행 시에는 여전히 OpenClaw 인증이 적용되며 “not authorized”를 반환합니다.

• ephemeral: true

​

기능 세부 정보

{
  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, // 선택적 활성화
      },
    },
  },
}

{
  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_...", // 선택 사항; 비공개 시스템에 필요
      },
    },
  },
}

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

{
  channels: {
    discord: {
      activity: "집중 시간",
      activityType: 4,
    },
  },
}

{
  channels: {
    discord: {
      activity: "라이브 코딩",
      activityType: 1,
      activityUrl: "https://twitch.tv/openclaw",
    },
  },
}

{
  channels: {
    discord: {
      autoPresence: {
        enabled: true,
        intervalMs: 30000,
        minUpdateIntervalMs: 15000,
        exhaustedText: "토큰 소진",
      },
    },
  },
}

​

도구 및 작업 게이트

• 메시징: sendMessage, readMessages, editMessage, deleteMessage, threadReply
• 리액션: react, reactions, emojiList
• moderation: timeout, kick, ban
• presence: setPresence

​

Components v2 UI

• channels.discord.ui.components.accentColor는 Discord 컴포넌트 컨테이너에 사용되는 강조 색상을 설정합니다(hex).
• 계정별 설정: channels.discord.accounts.<id>.ui.components.accentColor.
• components v2가 있으면 embeds는 무시됩니다.

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

​

음성 채널

• 네이티브 명령을 활성화하세요(commands.native 또는 channels.discord.commands.native).
• channels.discord.voice를 구성하세요.
• 봇은 대상 음성 채널에서 Connect + Speak 권한이 필요합니다.

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

• voice.tts는 음성 재생에 대해서만 messages.tts를 재정의합니다.
• 음성 전사 턴은 Discord allowFrom(또는 dm.allowFrom)에서 소유자 상태를 파생합니다. 소유자가 아닌 화자는 소유자 전용 도구(예: gateway, cron)에 접근할 수 없습니다.
• 음성은 기본적으로 활성화되어 있습니다. 비활성화하려면 channels.discord.voice.enabled=false를 설정하세요.
• voice.daveEncryption 및 voice.decryptionFailureTolerance는 @discordjs/voice join 옵션에 그대로 전달됩니다.
• @discordjs/voice 기본값은 설정되지 않은 경우 daveEncryption=true 및 decryptionFailureTolerance=24입니다.
• OpenClaw는 수신 복호화 실패도 감시하며, 짧은 시간 안에 반복 실패가 발생하면 음성 채널에서 나갔다가 다시 참여하여 자동 복구합니다.
• 수신 로그에 DecryptionFailed(UnencryptedWhenPassthroughDisabled)가 반복해서 표시되면, 이는 discord.js #11419에 추적된 상위 @discordjs/voice 수신 버그일 수 있습니다.

​

음성 메시지

• 로컬 파일 경로를 제공해야 합니다(URL은 거부됨).
• 텍스트 콘텐츠는 생략해야 합니다(Discord는 동일한 페이로드에서 텍스트 + 음성 메시지를 허용하지 않음).
• 어떤 오디오 형식이든 허용되며, 필요하면 OpenClaw가 OGG/Opus로 변환합니다.

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

​

문제 해결

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

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

​

구성 참조 포인터

• Configuration reference - Discord

• 시작/인증: enabled, token, accounts.*, allowBots
• 정책: groupPolicy, dm.*, guilds.*, guilds.*.channels.*
• 명령: commands.native, commands.useAccessGroups, configWrites, slashCommand.*
• 이벤트 큐: eventQueue.listenerTimeout (리스너 예산), eventQueue.maxQueueSize, eventQueue.maxConcurrency
• 인바운드 워커: inboundWorker.runTimeoutMs
• 응답/기록: replyToMode, historyLimit, dmHistoryLimit, dms.*.historyLimit
• 전달: textChunkLimit, chunkMode, maxLinesPerMessage
• 스트리밍: streaming (레거시 별칭: streamMode), draftChunk, blockStreaming, blockStreamingCoalesce
• 미디어/재시도: mediaMaxMb, retry
  • mediaMaxMb는 Discord 아웃바운드 업로드 상한을 설정합니다(기본값: 8MB)
• 작업: actions.*
• 상태: activity, status, activityType, activityUrl
• UI: ui.components.accentColor
• 기능: threadBindings, 최상위 bindings[] (type: "acp"), pluralkit, execApprovals, intents, agentComponents, heartbeat, responsePrefix

​

안전 및 운영

• 봇 토큰은 비밀 정보로 취급하세요(관리되는 환경에서는 DISCORD_BOT_TOKEN 권장).
• 최소 권한의 Discord 권한만 부여하세요.
• 명령 배포/상태가 오래되었다면 gateway를 재시작하고 openclaw channels status --probe로 다시 확인하세요.

​

관련 문서

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