OpenClaw Discord 봇 연결 완전 가이드

서문

Discord는 세계에서 가장 인기 있는 커뮤니티 소통 플랫폼 중 하나입니다. OpenClaw를 Discord에 연결하면 서버에 지능형 AI 어시스턴트를 배포하여 커뮤니티 멤버에게 즉각적인 도움을 제공할 수 있습니다. 이 글에서는 Discord Bot 생성부터 OpenClaw 연결까지의 전체 과정을 처음부터 완전하게 설명합니다.

사전 조건

시작하기 전에 다음을 확인해 주십시오:

OpenClaw가 설치되어 정상적으로 실행 중 (openclaw up)
Discord 계정을 보유하고 있음
대상 Discord 서버의 관리 권한을 보유하고 있음

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

1.1 개발자 포털 진입

Discord Developer Portal에 접속하여 Discord 계정으로 로그인합니다.

1.2 새 애플리케이션 생성

우측 상단의 New Application 버튼을 클릭합니다
애플리케이션 이름을 입력합니다 (예: "OpenClaw Assistant")
개발자 서비스 약관에 동의합니다
Create를 클릭합니다

1.3 Bot 생성

좌측 메뉴에서 Bot을 클릭합니다
Add Bot을 클릭하고 생성을 확인합니다
Bot 설정 페이지에서:
- Bot 아바타와 사용자 이름을 설정합니다
- Reset Token을 클릭하여 Bot Token을 획득합니다
- Token을 안전하게 보관합니다 (이후 설정에 필요)

주의: Bot Token은 민감한 정보입니다. 절대 유출하거나 공개 저장소에 커밋하지 마십시오.
실수로 유출된 경우 개발자 포털에서 즉시 Token을 재설정하십시오.

1.4 Privileged Intents 설정

Bot 설정 페이지 하단에서 다음 Privileged Gateway Intents를 활성화해야 합니다:

Intent	설명	필수 여부
Presence Intent	멤버 온라인 상태 감지	선택
Server Members Intent	멤버 목록 조회	선택
Message Content Intent	메시지 내용 읽기	필수

Message Content Intent는 반드시 활성화해야 합니다. 그렇지 않으면 Bot이 사용자가 보낸 메시지 내용을 읽을 수 없습니다.

2단계: Bot을 서버에 초대

2.1 초대 링크 생성

좌측 메뉴에서 OAuth2 → URL Generator를 클릭합니다:

Scopes에서 bot과 applications.commands를 선택합니다
Bot Permissions에서 다음 권한을 선택합니다:

필요한 권한 목록:
├── Send Messages        - 메시지 전송
├── Send Messages in Threads - 스레드에서 메시지 전송
├── Embed Links          - 링크 임베드
├── Attach Files         - 파일 첨부
├── Read Message History - 메시지 기록 읽기
├── Use Slash Commands   - 슬래시 명령 사용
├── Add Reactions        - 반응 추가
└── Manage Messages      - 메시지 관리 (선택, 자신의 메시지 삭제용)

생성된 URL을 복사합니다

2.2 서버에 초대

브라우저에서 이전 단계에서 복사한 URL을 엽니다
Bot을 추가할 서버를 선택합니다
권한을 확인하고 Authorize를 클릭합니다
사람 인증을 완료합니다

초대가 성공하면 Bot이 서버의 멤버 목록에 나타납니다 (아직 OpenClaw에 연결되지 않았으므로 오프라인 상태로 표시됩니다).

3단계: OpenClaw 설정

3.1 설정 파일을 통한 설정

~/.config/openclaw/openclaw.json5를 편집합니다:

{
  channels: {
    discord: {
      enabled: true,
      // 개발자 포털에서 획득한 Bot Token
      botToken: "MTIzNDU2Nzg5MDEyMzQ1Njc4OQ.XXXXXX.XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      // 개발자 포털의 OAuth2 페이지에서 획득
      clientId: "123456789012345678",

      // 트리거 방식 설정
      trigger: {
        // @Bot 멘션이 필요한지 여부 (false이면 모든 메시지에 응답)
        mentionRequired: true,
        // 사용자 정의 트리거 접두사 (선택)
        prefix: "!ask",
        // DM에 응답할지 여부
        dmEnabled: true
      },

      // 응답 설정
      reply: {
        // Embed 형식으로 응답할지 여부
        useEmbed: true,
        // Embed 색상 (16진수)
        embedColor: "#5865F2",
        // 스레드에서 자동으로 따라 응답할지 여부
        threadReply: true,
        // 긴 메시지 자동 분할 글자 수
        maxLength: 2000
      }
    }
  }
}

3.2 환경 변수를 통한 설정

export DISCORD_BOT_TOKEN="MTIzNDU2Nzg5MDEyMzQ1Njc4OQ.XXXXXX.XXXX"
export DISCORD_CLIENT_ID="123456789012345678"

3.3 서비스 재시작

설정 완료 후 OpenClaw를 재시작합니다:

openclaw restart

로그를 확인하여 연결 상태를 확인합니다:

openclaw logs -f --component channel:discord

연결에 성공하면 로그에 다음과 같이 표시됩니다:

[INFO] [channel:discord] Bot이 OpenClaw Assistant#1234로 로그인했습니다
[INFO] [channel:discord] 3개 서버에 연결되었습니다
[INFO] [channel:discord] 슬래시 명령이 등록되었습니다

4단계: 슬래시 명령 설정

OpenClaw는 Discord 슬래시 명령(Slash Commands) 등록을 지원하여 사용자가 /로 특정 기능을 실행할 수 있습니다.

기본 슬래시 명령

연결에 성공하면 OpenClaw는 자동으로 다음 슬래시 명령을 등록합니다:

명령	설명
`/ask <질문>`	AI에게 질문하기
`/model <모델명>`	현재 사용하는 AI 모델 전환
`/reset`	대화 컨텍스트 초기화
`/help`	도움말 정보 표시

사용자 정의 슬래시 명령

설정 파일에서 사용자 정의 명령을 추가할 수 있습니다:

{
  channels: {
    discord: {
      // ...기타 설정
      slashCommands: [
        {
          name: "translate",
          description: "텍스트 번역",
          options: [
            {
              name: "text",
              description: "번역할 텍스트",
              type: "STRING",
              required: true
            },
            {
              name: "language",
              description: "대상 언어",
              type: "STRING",
              required: false,
              choices: [
                { name: "中文", value: "zh" },
                { name: "English", value: "en" },
                { name: "日本語", value: "ja" }
              ]
            }
          ],
          // 연결된 스킬 또는 시스템 프롬프트
          skill: "translate"
        }
      ]
    }
  }
}

다중 서버 설정

Bot이 여러 Discord 서버에 초대된 경우 서버별로 다른 동작을 설정할 수 있습니다:

{
  channels: {
    discord: {
      enabled: true,
      botToken: "your-bot-token",
      clientId: "your-client-id",

      // 서버 레벨 설정
      guilds: {
        // 서버 ID: 설정
        "111111111111111111": {
          model: "claude",
          systemPrompt: "당신은 기술 지원 어시스턴트입니다",
          allowedChannels: ["general", "bot-chat"],
          trigger: { mentionRequired: false }
        },
        "222222222222222222": {
          model: "gpt-4o",
          systemPrompt: "당신은 친근한 대화 파트너입니다",
          allowedChannels: ["ai-chat"],
          trigger: { mentionRequired: true }
        }
      },

      // guilds에 설정되지 않은 서버는 기본 설정 사용
      defaultGuild: {
        model: "claude",
        trigger: { mentionRequired: true }
      }
    }
  }
}

서버 ID 가져오기: Discord에서 개발자 모드를 활성화한 후 (설정 → 고급 → 개발자 모드), 서버 아이콘을 우클릭 → 서버 ID 복사를 선택합니다.

Embed 서식

OpenClaw는 응답을 Discord Embed로 서식화하여 메시지를 더 보기 좋게 만들 수 있습니다:

{
  channels: {
    discord: {
      reply: {
        useEmbed: true,
        embedColor: "#5865F2",
        embedFooter: "Powered by OpenClaw",
        // 코드 블록 자동 구문 강조
        codeHighlight: true,
        // 긴 응답을 자동으로 여러 Embed로 분할
        splitEmbed: true
      }
    }
  }
}

Embed 효과에는 다음이 포함됩니다:

색상 사이드바로 AI 응답 표시
코드 블록 구문 강조 지원
푸터에 모델 이름과 토큰 소비 정보 표시
긴 콘텐츠 자동 페이지 분할 표시

문제 해결

Bot이 오프라인으로 표시

# Token이 올바른지 확인
openclaw config get channels.discord.botToken

# 로그에서 오류 메시지 확인
openclaw logs --level error --component channel:discord

일반적인 원인: Token이 올바르지 않음, Token이 만료됨, 네트워크 연결 불가.

Bot이 메시지에 응답하지 않음

# Message Content Intent가 활성화되어 있는지 확인
# 개발자 포털 → Bot → Privileged Gateway Intents에서 확인

권한 부족 오류

Bot이 대상 채널에서 메시지를 보낼 수 있는 권한이 있는지 확인합니다. Discord 서버 설정에서 Bot 역할의 권한 설정을 확인할 수 있습니다.

요약

Discord 연동은 OpenClaw에서 가장 많이 사용되는 채널 중 하나입니다. 핵심 단계를 되짚어 보겠습니다:

Discord 개발자 포털에서 애플리케이션과 Bot 생성
Message Content Intent 활성화
초대 링크를 생성하여 서버에 초대
OpenClaw 설정 파일에 Token 입력
서비스를 재시작하고 연결 확인

배포가 완료되면 여러분의 Discord 커뮤니티에 강력한 AI 어시스턴트가 갖춰집니다.