통합12 분 소요

OpenClaw Discord 통합: 봇 설정 및 Gateway Intents 설명

OpenClaw용 Discord 봇 생성, Gateway Intents 이해, DM 보안 정책 구성, 길드 채널 접근 제어 설정에 대한 완전한 가이드입니다.

OpenClaw Guides

Tutorial Authors

2025-02-04

개요

Discord 통합을 사용하면 Discord 봇을 통해 OpenClaw와 채팅할 수 있으며, DM(다이렉트 메시지)과 길드 텍스트 채널 통신을 모두 지원합니다. 이 가이드는 봇 생성, Gateway Intents 이해, DM 보안 정책 구성, 길드 채널 접근 제어 설정을 다룹니다. 모든 내용은 공식 OpenClaw 문서를 기반으로 합니다.

사전 요구 사항

OpenClaw 설치 및 실행 중
Discord 계정
관리자 권한이 있는 Discord 서버 (테스트용)

동작 방식

본격적으로 시작하기 전에 OpenClaw가 Discord 메시지를 어떻게 라우팅하는지 이해하면 도움이 됩니다:

DM 대화는 기본적으로 페어링 기반 보안을 사용하여 공유 세션(agent:main:main)으로 통합됩니다.
길드 채널 대화는 채널별로 격리되며, agent:<agentId>:discord:channel:<channelId> 패턴을 사용합니다.
그룹 DM은 기본적으로 무시되지만 channels.discord.dm.groupEnabled를 통해 활성화할 수 있습니다.

유효한 토큰이 존재하고 enabled가 false가 아니면 게이트웨이가 자동으로 시작됩니다.

1단계: Discord 애플리케이션 생성

Discord Developer Portal로 이동

Discord Developer Portal 방문
New Application 클릭
이름 입력 (예: "OpenClaw Assistant")
Create 클릭

봇 설정

애플리케이션에서 Bot 탭으로 이동
Add Bot → Yes, do it! 클릭
Token에서 Copy를 클릭하여 봇 토큰 복사

중요: 봇 토큰은 비밀번호처럼 취급하세요. 절대 공개적으로 공유하지 마세요. 노출된 경우 즉시 재생성하세요.

2단계: 권한 있는 Gateway Intents 활성화

Gateway Intents는 봇이 Discord에서 수신하는 이벤트를 제어합니다. OpenClaw가 정상적으로 작동하려면 특정 권한 있는 인텐트가 필요합니다.

필수 Intents

| Intent | 목적 | 필수 여부 | |--------|------|----------| | Message Content Intent | 길드 채널에서 메시지 텍스트 읽기 | 필수 — 이 인텐트 없이는 봇이 "Used disallowed intents" 오류를 표시하거나 연결은 되지만 응답하지 못함 | | Server Members Intent | 멤버 조회 및 허용 목록 매칭 | 권장 — 허용 목록 기반 접근 제어에 필요 |

Developer Portal에서 Intents 활성화

Developer Portal에서 Bot 탭으로 이동
Privileged Gateway Intents로 스크롤
MESSAGE CONTENT INTENT 활성화 (필수)
SERVER MEMBERS INTENT 활성화 (권장)
Save Changes 클릭

참고: 100개 이상의 서버에 있는 봇은 권한 있는 인텐트를 사용하기 위해 Discord 인증이 필요합니다.

3단계: 봇 초대 URL 생성

OAuth2 구성

OAuth2 → URL Generator로 이동
스코프 선택:
- bot
- applications.commands (네이티브 슬래시 명령에 필요)
봇 권한 선택:
- View Channels
- Send Messages
- Read Message History
- Embed Links
- Attach Files
- Add Reactions (선택 사항이지만 권장)
- Use External Emojis (선택 사항)

주의: 디버깅 중이 아니라면 Administrator 권한 부여를 피하세요. 필요한 권한만 부여하세요.

생성된 URL 복사

봇 초대

브라우저에서 URL 열기
테스트 서버 선택
Authorize 클릭

숫자 ID 얻기

Discord에서 개발자 모드를 활성화하세요 (사용자 설정 → 앱 설정 → 고급 → 개발자 모드). 이렇게 하면 우클릭으로 길드, 채널, 사용자 ID를 복사할 수 있습니다. 이 ID들은 구성에 필요합니다.

4단계: OpenClaw 구성

옵션 A: 환경 변수

토큰을 환경 변수로 설정합니다:

bash

export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN"

옵션 B: 구성 파일

구성 파일에 토큰을 직접 입력하여 OpenClaw를 설정합니다:

json5

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

참고: 환경 변수와 구성 파일 토큰이 모두 존재하는 경우, 구성 파일이 우선합니다.

옵션 C: 멀티 계정 지원

여러 봇 계정을 실행하는 경우:

json5

{
  channels: {
    discord: {
      accounts: [
        { token: "BOT_TOKEN_1", name: "assistant-1" },
        { token: "BOT_TOKEN_2", name: "assistant-2" }
      ]
    }
  }
}

5단계: 시작 및 테스트

OpenClaw 게이트웨이를 시작하거나 재시작합니다:

bash

openclaw gateway restart

채널 상태를 확인합니다:

bash

openclaw channels status --probe

문제가 있어 보이면 진단을 실행합니다:

bash

openclaw doctor

초기 DM 연락 시, 봇은 기본적으로 페어링 시스템을 사용합니다. 발신자는 시간 제한이 있는 코드(1시간 후 만료)를 받으며, 대화가 시작되기 전에 승인이 필요합니다.

DM 보안 정책

OpenClaw는 세 가지 DM 접근 제어 정책을 제공합니다:

페어링 (기본값)

알 수 없는 발신자는 1시간 후 만료되는 시간 제한 페어링 코드를 받습니다. 대화를 진행하려면 코드가 승인되어야 합니다.

json5

{
  channels: {
    discord: {
      dm: {
        enabled: true,
        policy: "pairing"
      }
    }
  }
}

허용 목록

구성된 사용자 ID 또는 사용자명만 DM을 보낼 수 있습니다:

json5

{
  channels: {
    discord: {
      dm: {
        enabled: true,
        policy: "allowlist",
        allowFrom: ["123456789012345678", "username#1234"]
      }
    }
  }
}

개방

누구나 DM을 보낼 수 있습니다 (주의해서 사용하세요):

json5

{
  channels: {
    discord: {
      dm: {
        enabled: true,
        policy: "open",
        allowFrom: ["*"]
      }
    }
  }
}

길드 채널 구성

기본 길드 접근 제어

멘션 요구 사항과 함께 봇을 특정 길드 및 채널로 제한합니다:

json5

{
  channels: {
    discord: {
      guilds: {
        "GUILD_ID": {
          requireMention: true,
          channels: {
            "CHANNEL_ID": {
              enabled: true
            }
          }
        }
      }
    }
  }
}

중요: requireMention은 길드 또는 채널 수준에서 구성해야 하며, 최상위 Discord 구성에서는 설정할 수 없습니다.

채널별 설정

채널별로 허용 목록과 스킬 제한을 구성할 수 있습니다:

json5

{
  channels: {
    discord: {
      guilds: {
        "GUILD_ID": {
          channels: {
            "CHANNEL_ID_1": {
              enabled: true,
              requireMention: true
            },
            "CHANNEL_ID_2": {
              enabled: true,
              requireMention: false
            }
          }
        }
      }
    }
  }
}

구성 매개변수

메시지 설정

| 매개변수 | 기본값 | 설명 | |----------|--------|------| | textChunkLimit | 2000 | 발신 메시지 청크당 최대 문자 수 | | chunkMode | — | 길이 제한 적용 전에 빈 줄(문단 경계)에서 분할하도록 설정 | | maxLinesPerMessage | 17 | 메시지당 최대 줄 수 | | mediaMaxMb | 8 | 최대 미디어 파일 크기(MB) |

컨텍스트 이력

json5

{
  channels: {
    discord: {
      historyLimit: 20  // 컨텍스트로 포함되는 최근 메시지 수 (기본값: 20, 비활성화하려면 0으로 설정)
    }
  }
}

답장 스레딩

네이티브 답장 스레딩은 기본적으로 비활성화되어 있습니다. 다음과 같이 활성화합니다:

json5

{
  channels: {
    discord: {
      replyToMode: "on"  // 네이티브 답장 스레딩 활성화
    }
  }
}

에이전트 응답에서 답장 태그를 사용하여 스레딩 동작을 제어합니다:

[[reply_to_current]] — 현재 처리 중인 메시지에 답장
[[reply_to:<message_id>]] — 특정 메시지에 답장

리액션 알림

길드별로 리액션 이벤트 알림을 구성합니다:

json5

{
  channels: {
    discord: {
      guilds: {
        "GUILD_ID": {
          reactionNotifications: "own"  // 옵션: "off", "own", "all", "allowlist"
        }
      }
    }
  }
}

도구 액션

에이전트는 Discord 내에서 작업을 수행하기 위해 discord 도구를 호출할 수 있습니다. 대부분의 액션은 기본적으로 활성화되어 있지만, 역할과 중재는 기본적으로 비활성화되어 있습니다.

사용 가능한 액션

| 카테고리 | 액션 | |----------|------| | 리액션 | react, sticker, poll | | 메시지 | readMessages, sendMessage, editMessage, deleteMessage, searchMessages | | 스레드 | threadCreate, threadList, threadReply | | 고정 | pinMessage, unpinMessage, listPins | | 채널 | channelInfo, channelList | | 멤버 | memberInfo, roleInfo, permissions | | 역할 | roleAdd, roleRemove (기본적으로 비활성화) | | 중재 | timeout, kick, ban (기본적으로 비활성화) | | 기타 | emojiList, voiceStatus, eventList, eventCreate, setPresence |

고급 기능

PluralKit 지원

활성화하면 OpenClaw가 프록시된 메시지를 기본 시스템 멤버로 변환하여, 실수로 Discord 핑이 발생하는 것을 방지하기 위해 발신자를 "Member (PK:System)"으로 표시합니다.

Exec 승인 버튼 UI

DM 대화에서 OpenClaw는 도구 액션의 대화형 확인을 위한 실행 승인 버튼을 표시할 수 있습니다.

재시도 구성

발신 API 호출은 Discord의 retry_after 헤더를 사용하여 속도 제한 시 지수 백오프로 자동 재시도합니다. channels.discord.retry 매개변수를 통해 재시도 동작을 구성하세요.

문제 해결

봇이 온라인이지만 응답하지 않음

Message Content Intent 확인: 이 인텐트 없이는 봇이 연결은 되지만 메시지 텍스트를 읽을 수 없습니다. Developer Portal → Bot → Privileged Gateway Intents로 이동하여 MESSAGE CONTENT INTENT가 활성화되어 있는지 확인하세요.
채널 권한 확인: 봇이 대상 채널에서 View Channels 및 Send Messages 권한을 가지고 있는지 확인하세요.
멘션 요구 사항 확인: 길드 또는 채널에서 requireMention이 활성화되어 있다면 봇을 @멘션해야 합니다.
길드/채널 허용 목록 확인: 채널이 허용 목록 구성에 의해 차단되지 않았는지 확인하세요.

"Used Disallowed Intents" 오류

필수 인텐트가 Developer Portal에서 활성화되지 않았음을 의미합니다:

Developer Portal → Bot → Privileged Gateway Intents로 이동
MESSAGE CONTENT INTENT 활성화
저장 후 OpenClaw 게이트웨이 재시작

DM이 작동하지 않음

dm.enabled가 false로 설정되어 있지 않은지 확인
DM 정책 확인 — "allowlist"로 설정된 경우 사용자 ID가 포함되어 있는지 확인
"pairing" 정책을 사용하는 경우 페어링 코드가 만료되지 않았는지 확인 (1시간 제한)

진단 명령

내장된 진단 도구를 사용하여 문제를 식별하세요:

bash

# 전체 진단 실행
openclaw doctor

# 연결 프로브를 포함한 채널 상태 확인
openclaw channels status --probe

모범 사례

봇 토큰을 비밀번호처럼 취급하세요 — 관리되는 호스트에서는 환경 변수를 사용하고, 토큰을 소스 컨트롤에 커밋하지 마세요.
필요한 권한만 부여하세요 — 디버깅 중이 아니라면 Administrator 권한을 피하세요.
페어링 또는 허용 목록 DM 정책을 사용하세요 — "open" 정책은 적절한 속도 제한이 적용된 공개용 봇에만 사용해야 합니다.
허용 목록 기반 접근 제어를 사용하는 경우 Server Members Intent를 활성화하세요 — 더 안정적인 멤버 매칭이 가능합니다.
활발한 길드에서는 requireMention을 사용하세요 — 봇이 모든 메시지에 응답하는 것을 방지합니다.
게이트웨이가 멈추면 --force 옵션으로 재시작하세요: openclaw gateway restart --force.

개요

사전 요구 사항

동작 방식

1단계: Discord 애플리케이션 생성

Discord Developer Portal로 이동

봇 설정

2단계: 권한 있는 Gateway Intents 활성화

필수 Intents

Developer Portal에서 Intents 활성화

3단계: 봇 초대 URL 생성

OAuth2 구성

봇 초대

숫자 ID 얻기

4단계: OpenClaw 구성

옵션 A: 환경 변수

옵션 B: 구성 파일

옵션 C: 멀티 계정 지원

5단계: 시작 및 테스트

DM 보안 정책

페어링 (기본값)

허용 목록

개방

길드 채널 구성

기본 길드 접근 제어

채널별 설정

구성 매개변수

메시지 설정

컨텍스트 이력

답장 스레딩

리액션 알림

도구 액션

사용 가능한 액션

고급 기능

PluralKit 지원

Exec 승인 버튼 UI

재시도 구성

문제 해결

봇이 온라인이지만 응답하지 않음

"Used Disallowed Intents" 오류

DM이 작동하지 않음

진단 명령

모범 사례

다음 단계