OpenClaw를 설치한 뒤 가장 많이 막히는 단계가 Discord 봇 연결입니다. 봇은 생성했는데 응답하지 않거나 서버에서는 동작하는데 DM이 되지 않는 경우도 자주 발생합니다. 이 글에서는 Discord Developer Portal에서 봇을 만드는 과정부터 OpenClaw와 정상적으로 연결하는 방법, 자주 발생하는 오류 해결 방법까지 순서대로 정리했습니다.
OpenClaw Discord 연결은 봇 생성 → 토큰 발급 → Intents 활성화 → 서버 초대 → openclaw.json 설정 → DM 페어링 순서로 진행됩니다.
Message Content Intent와 DM 페어링만 제대로 설정해도 대부분의 문제를 해결할 수 있습니다.
1. Discord Developer Portal에서 봇 생성
OpenClaw는 Discord 공식 Gateway를 사용하기 때문에 먼저 Discord Developer Portal에서 애플리케이션을 생성해야 합니다.
- Discord Developer Portal에 접속합니다.
- New Application을 클릭합니다.
- 애플리케이션 이름을 입력합니다.
- Create를 클릭합니다.
- 왼쪽 메뉴에서 Bot을 선택합니다.
- 봇 이름(Username)을 원하는 이름으로 변경합니다.
실무에서 보면 프로젝트마다 봇을 하나씩 생성하는 것이 관리하기 가장 편합니다. 하나의 봇을 여러 프로젝트에서 공유하면 권한 관리가 복잡해지는 경우가 많습니다.
2. 봇 토큰 복사 및 Privileged Intents 활성화
봇 토큰 발급
Bot 메뉴에서 Reset Token을 클릭하면 토큰을 발급받을 수 있습니다.
중요
봇 토큰은 비밀번호와 같습니다. 외부에 공개하거나 GitHub 저장소에 업로드하면 안 됩니다.
반드시 활성화해야 하는 Intents
| 설정 | 권장 여부 | 설명 |
|---|---|---|
| Message Content Intent | 필수 | 메시지 내용을 읽기 위한 설정 |
| Server Members Intent | 권장 | 역할(Role) 기반 허용 목록 사용 |
| Presence Intent | 선택 | 온라인 상태 조회 시 사용 |
많이들 여기서 막히더라고요. Message Content Intent를 켜지 않으면 봇은 서버에 정상적으로 접속해 있어도 메시지를 읽지 못하기 때문에 아무런 응답을 하지 않습니다.
이 부분이 핵심입니다. Intents를 변경했다면 반드시 Gateway를 다시 시작해야 변경 사항이 적용됩니다.
3. OAuth2 URL 생성 및 서버 초대
OAuth2 → URL Generator에서 아래 항목을 선택합니다.
| Scope | 선택 |
|---|---|
| bot | 필수 |
| applications.commands | 필수 |
Bot Permissions에서는 다음 권한을 선택하는 것이 일반적입니다.
- View Channels
- Send Messages
- Read Message History
- Embed Links
- Attach Files
- Use Slash Commands
- Add Reactions(선택)
Administrator 권한은 특별한 이유가 없다면 부여하지 않는 것이 좋습니다. 최소 권한 원칙을 적용하는 것이 보안 측면에서도 안전합니다.
개발자 모드 활성화
Discord 설정 → Advanced → Developer Mode를 활성화합니다.
이후 아래 ID를 복사해 둡니다.
- Guild(Server) ID
- Channel ID
- Role ID
- User ID
이건 직접 겪어보면 체감되는데 서버 ID와 채널 ID를 혼동해서 입력하는 경우가 정말 많습니다. 숫자가 비슷하게 보여도 서로 다른 값이므로 반드시 다시 확인하는 것이 좋습니다.
4. openclaw.json 설정
OpenClaw는 Discord 설정을 openclaw.json에서 관리합니다.
대표적인 설정 항목은 다음과 같습니다.
| 옵션 | 기본값 | 설명 |
|---|---|---|
| token | 필수 | Discord Bot Token |
| dmPolicy | pairing | DM 접근 정책 |
| groupPolicy | allowlist | 서버 접근 정책 |
| requireMention | true | 멘션 시에만 응답 |
| users | [] | 허용 사용자 목록 |
| roles | [] | 허용 역할 목록 |
| channels | {} | 채널별 허용 및 차단 |
| ignoreOtherMentions | false | 다른 멘션 포함 시 무시 여부 |
| streaming | progress | 스트리밍 응답 방식 |
설정이 끝났다면 아래 명령으로 Gateway를 시작합니다.
openclaw gateway
정상적으로 연결되면 Discord Connected 메시지가 출력됩니다.
많은 분들이 헷갈리시는게, openclaw gateway 명령어를 openclaw한테 질의 하는게 아니라 cmd 창에서 진행해 주셔야 합니다.
5. DM 페어링 완료
Gateway 실행 후 Discord에서 봇에게 DM을 보내면 페어링 요청이 생성됩니다.
아래 명령으로 요청을 확인할 수 있습니다.
- openclaw pairing list discord
- openclaw pairing approve discord 코드
페어링 코드는 1시간 후 만료됩니다.
실무에서 보면 Gateway는 실행했지만 페어링 승인 명령을 하지 않아 DM이 동작하지 않는 경우도 적지 않습니다.
6. dmPolicy 설정 비교
| 값 | 설명 | 권장 상황 |
|---|---|---|
| pairing | 페어링 사용자만 허용 | 일반 사용자 |
| allowlist | 허용 목록만 접근 | 기업 환경 |
| open | 모든 사용자 허용 | 공개 봇 |
| disabled | DM 비활성화 | 서버 전용 |
초보자는 대부분 pairing을 사용하는 것이 가장 안전합니다. 실무자는 운영 환경에 따라 allowlist를 활용해 접근 범위를 제한하는 경우가 많습니다.
왜 이 방법이 실제로 더 잘 먹히는지 생각해 보면 운영 중인 서버에서는 권한 관리가 무엇보다 중요하기 때문입니다.
7. 트러블슈팅
봇이 메시지에 응답하지 않습니다.
- Message Content Intent 확인
- Gateway 재시작
- 토큰 확인
Missing Permissions 오류
- OAuth2 권한 재설정
- 봇 역할 권한 확인
- 채널 권한 확인
서버에서는 동작하지만 DM이 안 됩니다.
- DM 허용 여부 확인
- pairing 승인 확인
- dmPolicy 확인
서버에 봇이 보이지 않습니다.
- bot Scope 선택 여부 확인
- OAuth2 URL 재생성
실무 팁
문제가 발생하면 openclaw doctor, openclaw channels status –probe, openclaw logs –follow 순서대로 확인하면 원인을 빠르게 찾을 수 있습니다.
8. 설정 확인 체크리스트
- 애플리케이션 생성 완료
- Discord Bot 생성 완료
- Bot Token 안전하게 보관
- Message Content Intent 활성화
- Server Members Intent 활성화(권장)
- OAuth2 URL 생성
- Discord 서버 초대 완료
- Developer Mode 활성화
- Guild / Channel / Role ID 수집
- openclaw.json 설정 완료
- Gateway 실행 완료
- DM 페어링 승인 완료
- 테스트 메시지 응답 확인
Discord 연결은 설정해야 하는 항목이 많아 보이지만 실제로는 순서만 지키면 어렵지 않습니다. 특히 Message Content Intent, Guild ID 설정, DM 페어링 세 가지만 정확하게 확인해도 대부분의 연결 문제를 예방할 수 있습니다.
댓글로 공유해 주세요.
- 어떤 단계에서 가장 많이 막히셨나요?
- DM 연결과 서버 연결 중 어느 부분에서 오류가 발생했나요?
다음 글 추천
- OpenClaw Slack 연결 및 Bot Token 설정 방법
- OpenClaw Telegram Bot 연결 가이드
본 포스팅은 정보 전달 목적이며, 실제 적용 시 발생하는 책임은 사용자에게 있습니다.