Discord Bot API 연결 및 설정 가이드

새로운 플랫폼에 봇을 연결하려고 하면 설정 과정이 복잡해서 막막할 때가 많죠. 특히 메시지 권한이나 세션 관리 같은 세세한 부분을 맞추다 보면 금방 지치기도 합니다.

복잡한 과정 없이 Discord와 연동을 시작하고 싶으신 분들을 위해 준비했습니다. 공식 Discord Gateway를 통해 DM과 서버 채널에 봇을 연결하는 방법을 바로 알아볼게요.

필요한 것

시작하기 전에 다음 항목들이 준비되었는지 확인해 주세요.

• Discord Developer Portal에서 생성한 애플리케이션과 봇 토큰
• 봇의 Message Content Intent 및 Server Members Intent 활성화

빠른 시작

5분 안에 봇을 실행할 수 있는 최소 경로입니다. 다음 단계를 차례대로 따라해 보세요.

1. Discord 봇 생성 및 Intent 활성화

Discord Developer Portal에서 애플리케이션을 만들고 봇을 추가한 뒤, 아래 두 가지 Intent를 반드시 켜주세요.

• Message Content Intent
• Server Members Intent (이름으로 ID를 찾거나 allowlist를 확인할 때 필요합니다)

2. 토큰 설정

설정 파일에 봇 토큰을 입력하세요.

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

기본 계정의 경우 환경 변수로도 설정할 수 있습니다.

DISCORD_BOT_TOKEN=...

참고

설정 파일의 토큰 값이 환경 변수보다 우선순위가 높습니다. DISCORD_BOT_TOKEN은 기본 계정에서만 사용됩니다.

3. 봇 초대 및 Gateway 시작

메시지 권한을 부여하여 봇을 서버에 초대하고 Gateway를 실행합니다.

openclaw gateway

4. 첫 번째 DM 페어링 승인

아래 명령어를 입력해 페어링을 승인하세요.

openclaw pairing list discord
openclaw pairing approve discord <CODE>

페어링 코드는 1시간 후에 만료되니 주의해 주세요.

Runtime model

작동 방식에 대해 알아두면 좋은 내용입니다.

• Gateway가 Discord 연결을 관리하며, 응답은 받은 곳으로 다시 전달됩니다.
• 기본적으로 (session.dmScope=main) 개인 DM은 에이전트 메인 세션을 공유합니다.
• 서버 채널은 독립된 세션 키(agent:<agentId>:discord:channel:<channelId>)를 가집니다.
• 그룹 DM은 기본적으로 무시됩니다 (channels.discord.dm.groupEnabled=false).

문제 해결

문제가 발생하면 다음 내용을 확인해 보세요.

• 페어링 코드 만료: 페어링 코드는 발급 후 1시간 동안만 유효합니다. 시간이 지났다면 다시 리스트를 확인해 보세요.
• 채널 연결 문제: 채널 진단이나 복구 흐름이 필요하다면 Channel troubleshooting 가이드를 참고해 주세요.

설정 중에 궁금한 점이 생기면 AI Setup Assistant에게 물어보세요!

다음 단계

• Pairing 가이드
• Slash commands 설정

Discord 봇을 배포할 때 가장 신경 쓰이는 부분은 역시 보안이죠. 아무나 내 봇에 메시지를 보내서 리소스를 낭비하게 하거나, 보안 설정이 제대로 되지 않아 원치 않는 서버에서 봇이 동작하는 상황은 피하고 싶을 거예요.

권한 관리는 복잡해 보일 수 있지만, 정책을 명확히 정의하면 봇을 안전하게 보호하면서 필요한 사용자에게만 기능을 제공할 수 있어요. OpenClaw에서 Discord 액세스 제어와 라우팅을 설정하는 방법을 알아볼게요.

필요한 것

• Discord Developer Portal 계정
• 봇 토큰 (DISCORD_BOT_TOKEN)
• 대상 서버 ID, 채널 ID, 사용자 ID (Discord Developer Mode 활성화 필요)

빠른 시작

Discord 봇의 접근 권한을 설정하는 가장 빠른 방법은 channels.discord 설정을 구성하는 거예요.

1. DM 및 서버 정책 설정

channels.discord.dm.policy를 통해 DM 접근을 제어하세요:

• pairing: (기본값) 페어링 모드로 동작합니다.
• allowlist: 허용된 사용자만 DM을 보낼 수 있습니다.
• open: 모든 사용자에게 열려 있습니다. (channels.discord.dm.allowFrom에 "*" 포함 필요)
• disabled: DM 기능을 비활성화합니다.

서버(Guild) 관리는 channels.discord.groupPolicy를 사용합니다:

• allowlist: 지정된 서버와 채널에서만 동작합니다.
• open: 모든 서버에서 동작합니다.
• disabled: 서버 기능을 비활성화합니다.

2. 설정 예시

아래는 특정 서버와 채널만 허용하는 allowlist 설정 예시예요.

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

Developer Portal setup

봇이 정상적으로 동작하려면 Discord Developer Portal에서 몇 가지 설정이 필요해요.

1. 앱 및 봇 생성: Applications -> New Application에서 앱을 만들고, Bot 메뉴에서 Add Bot을 클릭해 토큰을 복사하세요.
2. Privileged Intents 활성화: Bot -> Privileged Gateway Intents에서 다음 항목을 켜주세요.
   • Message Content Intent
   • Server Members Intent (권장)
3. OAuth 스코프 및 권한: OAuth URL generator에서 bot과 applications.commands 스코프를 선택하세요. 기본 권한으로는 View Channels, Send Messages, Read Message History, Embed Links, Attach Files 정도가 적당합니다. Administrator 권한은 꼭 필요한 경우가 아니면 피하는 것이 좋아요.
4. ID 복사: Discord 앱의 설정에서 Developer Mode를 켜고 서버 ID, 채널 ID, 사용자 ID를 복사해 두세요. OpenClaw 설정에서는 이름보다 숫자 ID를 사용하는 것이 더 정확합니다.

Native commands and command auth

OpenClaw는 Discord의 Slash Commands와 같은 네이티브 커맨드를 지원해요.

• commands.native는 기본값이 "auto"이며 Discord에서 활성화됩니다.
• 특정 채널에서만 끄고 싶다면 channels.discord.commands.native에서 오버라이드할 수 있어요.
• commands.native=false로 설정하면 이전에 등록된 네이티브 커맨드들이 명시적으로 삭제됩니다.
• 네이티브 커맨드 인증은 일반 메시지 처리와 동일한 allowlist 및 정책을 따릅니다. 권한이 없는 사용자에게 커맨드가 보일 수는 있지만, 실행 시 OpenClaw가 인증을 체크하여 “not authorized”를 반환합니다.

문제 해결

설정 중에 문제가 발생한다면 다음 내용을 확인해 보세요.

• ID 형식 오류: 단순히 숫자만 입력된 ID는 모호해서 거부될 수 있어요. DM 전달 시에는 user:<id> 또는 <@id> 형식을 명시적으로 사용해야 합니다.
• 로그 경고: channels.discord 블록을 생성하지 않고 DISCORD_BOT_TOKEN만 설정하면, 런타임에서 groupPolicy="open"으로 자동 전환되며 로그에 경고가 표시됩니다.
• DM 차단: DM 정책이 open이 아닌 경우, 알 수 없는 사용자의 메시지는 차단되거나 pairing 모드에서 페어링 요청을 받게 됩니다.
• 그룹 DM: 기본적으로 그룹 DM은 무시됩니다 (dm.groupEnabled=false). 사용하려면 dm.groupChannels에 ID나 슬러그를 추가해 주세요.

더 자세한 설정 방법이 궁금하거나 도움이 필요하다면 AI Setup Assistant에게 물어보세요!

다음 단계

• Slash commands: 커맨드 카탈로그 및 동작 방식 확인하기
• Message patterns: 멘션 감지 및 그룹 채팅 설정 알아보기

Discord 봇을 운영하다 보면 메시지 흐름을 추적하거나 스레드 문맥을 유지하는 게 쉽지 않죠. 특히 사용자가 여러 번 답장을 보낼 때 Agent가 어떤 메시지에 반응해야 할지 결정하는 로직을 짜는 건 꽤 번거로운 작업이에요.

이런 고민을 해결하기 위해 Discord 연동에서 지원하는 상세 기능들을 정리했어요. 설정을 통해 더 자연스러운 대화 흐름을 만들어 보세요.

필요한 것

• 활성화된 Discord 채널 세션
• channels.discord 설정 접근 권한

빠른 시작

5분 안에 가장 기본적인 답장 기능과 히스토리 제한을 설정해 보세요.

1. channels.discord.replyToMode를 first로 설정하여 첫 메시지에 답장하도록 만듭니다.
2. channels.discord.historyLimit을 설정해 Agent가 참고할 과거 대화 양을 조절하세요.

{
  channels: {
    discord: {
      replyToMode: "first",
      historyLimit: 20
    }
  }
}

상세 기능 안내

답장 태그 및 네이티브 답장

Discord Agent는 출력 결과에 답장 태그를 지원해요. 이 기능을 사용하면 특정 메시지를 명확하게 지칭할 수 있습니다.

• [[reply_to_current]]: 현재 메시지에 답장
• [[reply_to:<id>]]: 특정 ID를 가진 메시지에 답장

이 동작은 channels.discord.replyToMode 옵션으로 제어합니다.

• off (기본값)
• first
• all

메시지 ID는 컨텍스트와 히스토리에 노출되므로, Agent가 이를 보고 특정 메시지를 타겟팅할 수 있어요.

히스토리, 컨텍스트 및 스레드 동작

길드(서버) 내의 히스토리 컨텍스트 설정은 다음과 같아요.

• channels.discord.historyLimit: 기본값은 20입니다.
• 설정이 없으면 messages.groupChat.historyLimit 값을 따라갑니다.
• 0으로 설정하면 기능을 비활성화합니다.

DM 히스토리는 다음 경로에서 별도로 제어할 수 있습니다.

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

스레드(Thread)는 채널 세션으로 라우팅됩니다. 부모 스레드의 메타데이터를 사용해 부모 세션과 연결할 수 있고, 스레드 전용 설정이 없다면 부모 채널의 설정을 그대로 상속받아요. 채널 주제(Topic)는 시스템 프롬프트가 아닌 신뢰할 수 없는(untrusted) 컨텍스트로 주입됩니다.

반응(Reaction) 알림

길드별로 반응 알림 모드를 설정할 수 있어요. 반응 이벤트는 시스템 이벤트로 변환되어 라우팅된 Discord 세션에 연결됩니다.

• off
• own (기본값)
• all
• allowlist (guilds.<id>.users 사용)

설정 쓰기 (Config Writes)

채널에서 시작된 설정 쓰기 기능은 기본적으로 활성화되어 있습니다. 커맨드 기능이 켜져 있을 때 /config set 또는 /config unset 흐름에 영향을 줍니다. 만약 이 기능을 끄고 싶다면 아래와 같이 설정하세요.

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

PluralKit 지원

프록시된 메시지를 시스템 멤버 ID로 매핑하려면 PluralKit 연동을 활성화하세요.

{
  channels: {
    discord: {
      pluralkit: {
        enabled: true,
        token: "pk_live_...", // 선택 사항 (비공개 시스템인 경우 필요)
      },
    },
  },
}

참고 사항:

• allowlist에서 pk:<memberId> 형식을 사용할 수 있습니다.
• 멤버의 표시 이름은 이름이나 슬러그(slug)로 매치합니다.
• 조회 시 원본 메시지 ID를 사용하며 시간 범위 제한이 있습니다.
• 조회가 실패하면 프록시 메시지는 봇 메시지로 취급되어 드랍됩니다. (단, allowBots=true인 경우는 제외)

Discord 실행 승인 (Exec Approvals)

Discord DM에서 버튼 기반의 실행 승인 기능을 사용할 수 있습니다.

설정 경로:

• channels.discord.execApprovals.enabled
• channels.discord.execApprovals.approvers
• 기타 옵션: agentFilter, sessionFilter, cleanupAfterResolve

관련 문서: Exec approvals

문제 해결

• 승인이 실패하고 알 수 없는 승인 ID(unknown approval IDs)가 뜨나요?
  • 승인자(approver) 리스트에 본인이 포함되어 있는지 확인하세요.
  • 해당 기능이 enabled: true로 설정되어 있는지 다시 한번 체크해 보세요.

설정 중에 어려운 부분이 있다면 AI Setup Assistant에게 물어보세요.

다음 단계

• Discord 연동 시작하기
• 메시지 핸들러 설정 가이드

Discord 연동 기능을 개발하다 보면 어떤 기능은 허용하고 어떤 기능은 제한해야 할지 고민될 때가 많아요. 모든 권한을 다 열어두자니 보안이 걱정되고, 하나하나 설정하자니 복잡하게 느껴지곤 하죠. 이럴 때 Action gates 설정을 이해하면 봇의 권한을 훨씬 명확하게 관리할 수 있어요.

What You’ll Need

• Discord API 연동 환경
• channels.discord.actions 설정 접근 권한

Quick Start

Discord에서 사용할 수 있는 액션은 메시지 전송, 채널 관리, Moderation, Presence 등 다양합니다. 주요 예시는 다음과 같아요.

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

이러한 액션들을 제어하는 설정인 Action gates는 channels.discord.actions.* 경로 아래에 위치합니다.

기본 설정 (Default Gate Behavior)

모든 액션이 처음부터 활성화되어 있는 것은 아니에요. 아래 표를 보고 어떤 그룹이 기본으로 켜져 있는지, 혹은 꺼져 있는지 확인해 보세요.

Action group	Default
reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissions	enabled
roles	disabled
moderation	disabled
presence	disabled

Troubleshooting

• 특정 액션이 실행되지 않아요: roles, moderation, presence 관련 액션은 기본값이 disabled입니다. 이 기능들을 사용하려면 설정에서 명시적으로 활성화해야 합니다.

더 자세한 설정 방법이 궁금하다면 AI Setup Assistant에게 질문해 보세요.

What’s Next

• Discord API Reference
• Configuring Action Gates

봇을 열심히 개발하고 실행했는데, 아무런 반응이 없어서 당황하신 적 있으시죠? 분명 코드는 완벽한 것 같은데 메시지가 전달되지 않거나 권한 문제로 막히면 정말 답답해요. 설정 하나 때문에 몇 시간씩 헤매는 개발자분들을 위해 자주 발생하는 문제와 해결 방법을 정리했습니다.

설정 파일의 오타 하나나 체크박스 하나가 원인일 때가 많으니, 차근차근 함께 살펴봐요.

필요한 것

• Discord Bot Token 및 설정 권한
• OpenClaw CLI 도구
• Gateway 설정 파일 (channels.discord 관련 섹션)

빠른 시작

문제를 진단하는 가장 빠른 방법은 CLI 도구를 활용하는 거예요. 5분 안에 상태를 점검해 보세요.

1. 상태 진단 실행: 현재 설정에 문제가 없는지 확인합니다.

   openclaw doctor

2. 채널 프로브: 특정 채널의 권한과 연결 상태를 직접 테스트합니다.

   openclaw channels status --probe

3. 실시간 로그 확인: Gateway에서 발생하는 이벤트를 실시간으로 모니터링하세요.

   openclaw logs --follow

문제 해결

허용되지 않은 Intent를 사용하거나 메시지가 보이지 않나요?

• Message Content Intent를 활성화했는지 확인하세요.
• 사용자나 멤버 정보를 가져와야 한다면 Server Members Intent도 켜야 합니다.
• Discord 개발자 포털에서 Intent 설정을 변경했다면, 반드시 Gateway를 재시작해야 적용됩니다.

서버 메시지가 예상치 못하게 차단되나요?

• groupPolicy 설정을 다시 확인해 보세요.
• channels.discord.guilds 아래에 해당 서버가 allowlist에 포함되어 있는지 확인하세요.
• 만약 channels 맵이 존재한다면, 그 목록에 명시된 채널만 허용됩니다.
• requireMention 설정이 어떻게 되어 있는지, 그리고 멘션 패턴이 맞는지 체크해 보세요.

requireMention이 false인데도 메시지가 차단되나요?

다음 원인 중 하나일 가능성이 높아요.

• groupPolicy="allowlist"로 설정되어 있지만, 일치하는 서버나 채널 allowlist가 없는 경우입니다.
• requireMention 설정 위치가 잘못되었습니다. 이 설정은 channels.discord.guilds 아래나 개별 채널 엔트리에 있어야 합니다.
• 메시지 전송자가 서버나 채널의 users allowlist에 의해 차단되었는지 확인하세요.

권한 감사(Permissions audit) 결과가 일치하지 않나요?

channels status --probe를 통한 권한 체크는 숫자로 된 채널 ID를 사용할 때만 정확하게 작동해요. 만약 slug key를 사용 중이라면 런타임 매칭은 정상적으로 작동할 수 있지만, probe 명령어가 권한을 완벽하게 검증하지 못할 수 있다는 점을 참고해 주세요.

DM 및 페어링 관련 문제

• DM이 비활성화되어 있는지 확인하세요: channels.discord.dm.enabled=false
• DM 정책이 비활성 상태인지 확인하세요: channels.discord.dm.policy="disabled"
• pairing 모드를 사용 중이라면 승인 대기 상태는 아닌지 체크해 보세요.

봇끼리 메시지를 주고받는 루프 현상

기본적으로 봇이 작성한 메시지는 무시됩니다. 만약 channels.discord.allowBots=true를 설정했다면, 루프 현상을 방지하기 위해 엄격한 멘션 규칙과 allowlist 규칙을 함께 사용해야 합니다.

Configuration reference pointers

설정 시 참고해야 할 주요 항목들입니다.

기본 참조:

• Configuration reference - Discord

주요 Discord 필드:

• startup/auth: enabled, token, accounts.*, allowBots
• policy: groupPolicy, dm.*, guilds.*, guilds.*.channels.*
• command: commands.native, commands.useAccessGroups, configWrites
• reply/history: replyToMode, historyLimit, dmHistoryLimit, dms.*.historyLimit
• delivery: textChunkLimit, chunkMode, maxLinesPerMessage
• media/retry: mediaMaxMb, retry
• actions: actions.*
• features: pluralkit, execApprovals, intents, agentComponents, heartbeat, responsePrefix

Safety and operations

• Bot Token은 항상 비밀로 유지하세요. 관리형 환경에서는 DISCORD_BOT_TOKEN 환경변수 사용을 권장합니다.
• Discord 권한은 항상 최소 권한 원칙에 따라 부여하세요.
• 커맨드 배포 상태가 최신이 아니거나 이상하다면, Gateway를 재시작한 뒤 openclaw channels status --probe로 다시 확인해 보세요.

설정 과정에서 막히는 부분이 있다면 언제든 도움을 받을 수 있습니다. AI Setup Assistant에게 질문해 보세요!

다음 단계

• Pairing
• Channel routing
• Troubleshooting
• Slash commands