Discord

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

빠른 설정

export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN"
cat > discord.patch.json5 <<'JSON5'
{
  channels: {
    discord: {
      enabled: true,
      token: { source: "env", provider: "default", id: "DISCORD_BOT_TOKEN" },
    },
  },
}
JSON5
openclaw config patch --file ./discord.patch.json5 --dry-run
openclaw config patch --file ./discord.patch.json5
openclaw gateway

{
  channels: {
    discord: {
      enabled: true,
      token: {
        source: "env",
        provider: "default",
        id: "DISCORD_BOT_TOKEN",
      },
    },
  },
}

DISCORD_BOT_TOKEN=...

{
  channels: {
    discord: {
      enabled: true,
      accounts: {
        personal: {
          token: { source: "env", provider: "default", id: "DISCORD_PERSONAL_TOKEN" },
          applicationId: "111111111111111111",
        },
        work: {
          token: { source: "env", provider: "default", id: "DISCORD_WORK_TOKEN" },
          applicationId: "222222222222222222",
        },
      },
    },
  },
}

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로 다시 전달됩니다.
• Discord 길드/채널 메타데이터는 사용자에게 보이는 응답 접두사가 아니라 신뢰할 수 없는 컨텍스트로 모델 프롬프트에 추가됩니다. 모델이 그 봉투를 다시 복사하면 OpenClaw는 아웃바운드 응답과 향후 재생 컨텍스트에서 복사된 메타데이터를 제거합니다.
• 기본적으로 (session.dmScope=main) 직접 채팅은 에이전트 메인 세션(agent:main:main)을 공유합니다.
• 길드 채널은 격리된 세션 키입니다(agent:<agentId>:discord:channel:<channelId>).
• 그룹 DM은 기본적으로 무시됩니다(channels.discord.dm.groupEnabled=false).
• 네이티브 슬래시 명령은 격리된 명령 세션에서 실행되며(agent:<agentId>:discord:slash:<userId>), 라우팅된 대화 세션으로 CommandTargetSessionKey를 계속 전달합니다.
• Discord로 전달되는 텍스트 전용 cron/heartbeat 공지는 최종 어시스턴트 표시 답변을 한 번 사용합니다. 미디어 및 구조화된 컴포넌트 페이로드는 에이전트가 전달 가능한 페이로드를 여러 개 내보낼 때 여러 메시지로 유지됩니다.

​

포럼 채널

• 포럼 상위 대상(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: "Optional fallback text",
  components: {
    reusable: true,
    text: "Choose a path",
    blocks: [
      {
        type: "actions",
        buttons: [
          {
            label: "Approve",
            style: "success",
            allowedUsers: ["123456789012345678"],
          },
          { label: "Decline", style: "danger" },
        ],
      },
      {
        type: "actions",
        select: {
          type: "string",
          placeholder: "Pick an option",
          options: [
            { label: "Option A", value: "a" },
            { label: "Option B", value: "b" },
          ],
        },
      },
    ],
    modal: {
      title: "Details",
      triggerLabel: "Open form",
      fields: [
        { type: "text", label: "Requester" },
        {
          type: "select",
          label: "Priority",
          options: [
            { label: "Low", value: "low" },
            { label: "High", value: "high" },
          ],
        },
      ],
    },
  },
}

​

접근 제어 및 라우팅

{
  accessGroups: {
    operators: {
      type: "message.senders",
      members: {
        "*": ["global-owner-id"],
        discord: ["discord:123456789012345678"],
        telegram: ["987654321"],
      },
    },
  },
  channels: {
    discord: {
      dmPolicy: "allowlist",
      allowFrom: ["accessGroup:operators"],
    },
  },
}

{
  accessGroups: {
    maintainers: {
      type: "discord.channelAudience",
      guildId: "1456350064065904867",
      channelId: "1456744319972282449",
      membership: "canViewChannel",
    },
  },
  channels: {
    discord: {
      dmPolicy: "allowlist",
      allowFrom: ["accessGroup:maintainers"],
    },
  },
}

{
  accessGroups: {
    maintainers: {
      type: "discord.channelAudience",
      guildId: "1456350064065904867",
      channelId: "1456744319972282449",
    },
  },
  channels: {
    discord: {
      dmPolicy: "allowlist",
      allowFrom: ["accessGroup:maintainers", "discord:123456789012345678"],
    },
  },
}

{
  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",
      },
    },
  ],
}

​

네이티브 명령 및 명령 인증

• commands.native는 기본값이 "auto"이며 Discord에서 활성화됩니다.
• 채널별 재정의: channels.discord.commands.native.
• commands.native=false는 시작 중 Discord 슬래시 명령 등록 및 정리를 건너뜁니다. 이전에 등록된 명령은 Discord 앱에서 제거할 때까지 Discord에 계속 표시될 수 있습니다.
• 네이티브 명령 인증은 일반 메시지 처리와 동일한 Discord 허용 목록/정책을 사용합니다.
• 권한이 없는 사용자에게도 명령이 Discord UI에 계속 표시될 수 있습니다. 실행 시에는 여전히 OpenClaw 인증을 적용하며 “not authorized”를 반환합니다.

• ephemeral: true

​

기능 세부 정보

{
  channels: {
    discord: {
      streaming: {
        mode: "progress",
        progress: {
          label: "auto",
          maxLines: 8,
          toolProgress: true,
        },
      },
    },
  },
}

{
  "channels": {
    "discord": {
      "streaming": {
        "mode": "progress",
        "progress": {
          "toolProgress": true,
          "commandText": "status"
        }
      }
    }
  }
}

{
  session: {
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
  },
  channels: {
    discord: {
      threadBindings: {
        enabled: true,
        idleHours: 24,
        maxAgeHours: 0,
        spawnSessions: true,
        defaultSpawnContext: "fork",
      },
    },
  },
}

{
  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_...", // optional; needed for private systems
      },
    },
  },
}

{
  channels: {
    discord: {
      mentionAliases: {
        Vladislava: "123456789012345678",
      },
      accounts: {
        ops: {
          mentionAliases: {
            OpsLead: "234567890123456789",
          },
        },
      },
    },
  },
}

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

{
  channels: {
    discord: {
      activity: "Focus time",
      activityType: 4,
    },
  },
}

{
  channels: {
    discord: {
      activity: "Live coding",
      activityType: 1,
      activityUrl: "https://twitch.tv/openclaw",
    },
  },
}

{
  channels: {
    discord: {
      autoPresence: {
        enabled: true,
        intervalMs: 30000,
        minUpdateIntervalMs: 15000,
        exhaustedText: "token exhausted",
      },
    },
  },
}

​

도구 및 작업 게이트

• 메시징: sendMessage, readMessages, editMessage, deleteMessage, threadReply
• 반응: react, reactions, emojiList
• 모더레이션: timeout, kick, ban
• 프레즌스: 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",
        },
      },
    },
  },
}

​

음성

​

음성 채널

1. Discord Developer Portal에서 Message Content Intent를 활성화합니다.
2. 역할/사용자 허용 목록을 사용할 때 Server Members Intent를 활성화합니다.
3. bot 및 applications.commands 범위로 봇을 초대합니다.
4. 대상 음성 채널에서 Connect, Speak, Send Messages, Read Message History를 부여합니다.
5. 네이티브 명령(commands.native 또는 channels.discord.commands.native)을 활성화합니다.
6. channels.discord.voice를 구성합니다.

/vc join channel:<voice-channel-id>
/vc status
/vc leave

openclaw channels capabilities --channel discord --target channel:<voice-channel-id>

{
  channels: {
    discord: {
      voice: {
        enabled: true,
        model: "openai-codex/gpt-5.5",
        autoJoin: [
          {
            guildId: "123456789012345678",
            channelId: "234567890123456789",
          },
        ],
        allowedChannels: [
          {
            guildId: "123456789012345678",
            channelId: "234567890123456789",
          },
        ],
        daveEncryption: true,
        decryptionFailureTolerance: 24,
        connectTimeoutMs: 30000,
        reconnectGraceMs: 15000,
        realtime: {
          provider: "openai",
          model: "gpt-realtime-2",
          voice: "cedar",
        },
      },
    },
  },
}

• voice.tts는 stt-tts 음성 재생에만 messages.tts를 재정의합니다. Realtime 모드는 voice.realtime.voice를 사용합니다.
• voice.mode는 대화 경로를 제어합니다. 기본값은 agent-proxy입니다. Realtime 음성 프런트엔드가 턴 타이밍, 끼어들기, 재생을 처리하고, 실질적인 작업은 openclaw_agent_consult를 통해 라우팅된 OpenClaw 에이전트에 위임하며, 그 결과를 해당 화자의 입력된 Discord 프롬프트처럼 취급합니다. stt-tts는 기존의 배치 STT와 TTS 흐름을 유지합니다. bidi는 Realtime 모델이 직접 대화하도록 하면서 OpenClaw 두뇌를 위해 openclaw_agent_consult를 노출합니다.
• voice.agentSession은 어떤 OpenClaw 대화가 음성 턴을 받을지 제어합니다. 음성 채널 자체 세션을 사용하려면 설정하지 않은 상태로 두거나, 음성 채널이 #maintainers 같은 기존 Discord 텍스트 채널 세션의 마이크/스피커 확장으로 동작하게 하려면 { mode: "target", target: "channel:<text-channel-id>" }로 설정하세요.
• voice.model은 Discord 음성 응답과 Realtime 상담에 사용할 OpenClaw 에이전트 두뇌를 재정의합니다. 라우팅된 에이전트 모델을 상속하려면 설정하지 않은 상태로 두세요. 이는 voice.realtime.model과 별개입니다.
• agent-proxy는 음성을 discord-voice를 통해 라우팅합니다. 이 경로는 화자와 대상 세션에 대한 일반적인 소유자/도구 권한을 보존하지만, Discord 음성이 재생을 소유하므로 에이전트 tts 도구는 숨깁니다. 기본적으로 agent-proxy는 소유자 화자에게 상담에 대한 전체 소유자 동등 도구 접근 권한을 부여하고(voice.realtime.toolPolicy: "owner"), 실질적인 답변 전 OpenClaw 에이전트 상담을 강하게 선호합니다(voice.realtime.consultPolicy: "always"). 이 기본 always 모드에서는 Realtime 계층이 상담 답변 전에 자동으로 자리 채우기 발화를 하지 않습니다. 음성을 캡처하고 전사한 뒤, 라우팅된 OpenClaw 답변을 말합니다. Discord가 첫 답변을 아직 재생 중인 동안 여러 강제 상담 답변이 완료되면, 이후의 정확 발화 답변은 문장 중간에 음성을 교체하지 않고 재생이 유휴 상태가 될 때까지 대기열에 들어갑니다.
• stt-tts 모드에서 STT는 tools.media.audio를 사용하며, voice.model은 전사에 영향을 주지 않습니다.
• Realtime 모드에서는 voice.realtime.provider, voice.realtime.model, voice.realtime.voice가 Realtime 오디오 세션을 구성합니다. OpenAI Realtime 2와 Codex 두뇌를 함께 사용하려면 voice.realtime.model: "gpt-realtime-2" 및 voice.model: "openai-codex/gpt-5.5"를 사용하세요.
• OpenAI Realtime 제공자는 출력 오디오 및 전사 이벤트에 대해 현재 Realtime 2 이벤트 이름과 레거시 Codex 호환 별칭을 모두 허용하므로, 호환 제공자 스냅샷이 변하더라도 어시스턴트 오디오가 누락되지 않습니다.
• voice.realtime.bargeIn은 Discord 화자 시작 이벤트가 활성 Realtime 재생을 중단할지 제어합니다. 설정하지 않으면 Realtime 제공자의 입력 오디오 끼어들기 설정을 따릅니다.
• voice.realtime.minBargeInAudioEndMs는 OpenAI Realtime 끼어들기가 오디오를 자르기 전에 필요한 최소 어시스턴트 재생 시간을 제어합니다. 기본값: 250. 에코가 적은 방에서는 즉시 중단하려면 0으로 설정하고, 에코가 많은 스피커 설정에서는 값을 높이세요.
• Discord 재생에 OpenAI 음성을 사용하려면 voice.tts.provider: "openai"를 설정하고 voice.tts.openai.voice 또는 voice.tts.providers.openai.voice 아래에서 Text-to-speech 음성을 선택하세요. cedar는 현재 OpenAI TTS 모델에서 남성적인 느낌의 좋은 선택입니다.
• 채널별 Discord systemPrompt 재정의는 해당 음성 채널의 음성 전사 턴에 적용됩니다.
• 음성 전사 턴은 Discord allowFrom(또는 dm.allowFrom)에서 소유자 상태를 도출합니다. 비소유자 화자는 소유자 전용 도구(예: gateway, cron)에 접근할 수 없습니다.
• Discord 음성은 텍스트 전용 구성에서는 옵트인입니다. /vc 명령, 음성 런타임, GuildVoiceStates Gateway 인텐트를 활성화하려면 channels.discord.voice.enabled=true를 설정하거나 기존 channels.discord.voice 블록을 유지하세요.
• channels.discord.intents.voiceStates는 음성 상태 인텐트 구독을 명시적으로 재정의할 수 있습니다. 인텐트가 유효한 음성 활성화 상태를 따르게 하려면 설정하지 않은 상태로 두세요.
• voice.autoJoin에 같은 길드에 대한 항목이 여러 개 있으면 OpenClaw는 해당 길드에 대해 마지막으로 구성된 채널에 참여합니다.
• voice.allowedChannels는 선택적 상주 허용 목록입니다. /vc join을 인증된 모든 Discord 음성 채널로 허용하려면 설정하지 않은 상태로 두세요. 설정하면 /vc join, 시작 시 자동 참여, 봇 음성 상태 이동이 나열된 { guildId, channelId } 항목으로 제한됩니다. 모든 Discord 음성 참여를 거부하려면 빈 배열로 설정하세요. Discord가 봇을 허용 목록 밖으로 이동시키면 OpenClaw는 해당 채널을 떠나고, 사용할 수 있는 구성된 자동 참여 대상이 있으면 다시 참여합니다.
• voice.daveEncryption 및 voice.decryptionFailureTolerance는 @discordjs/voice 참여 옵션으로 전달됩니다.
• 설정하지 않으면 @discordjs/voice 기본값은 daveEncryption=true 및 decryptionFailureTolerance=24입니다.
• OpenClaw는 Discord 음성 수신에 기본적으로 순수 JS opusscript 디코더를 사용합니다. 선택적 네이티브 @discordjs/opus 패키지는 저장소 pnpm 설치 정책에서 무시되므로 일반 설치, Docker 레인, 관련 없는 테스트가 네이티브 애드온을 컴파일하지 않습니다. 전용 음성 성능 호스트는 네이티브 애드온을 설치한 뒤 OPENCLAW_DISCORD_OPUS_DECODER=native로 옵트인할 수 있습니다.
• voice.connectTimeoutMs는 /vc join 및 자동 참여 시도에 대한 초기 @discordjs/voice Ready 대기 시간을 제어합니다. 기본값: 30000.
• voice.reconnectGraceMs는 연결이 끊긴 음성 세션이 제거되기 전에 다시 연결되기 시작할 때까지 OpenClaw가 기다리는 시간을 제어합니다. 기본값: 15000.
• stt-tts 모드에서는 다른 사용자가 말하기 시작했다는 이유만으로 음성 재생이 멈추지 않습니다. 피드백 루프를 피하기 위해 OpenClaw는 TTS가 재생되는 동안 새 음성 캡처를 무시합니다. 다음 턴은 재생이 끝난 뒤 말하세요. Realtime 모드는 화자 시작을 Realtime 제공자에 끼어들기 신호로 전달합니다.
• Realtime 모드에서 스피커의 에코가 열린 마이크로 들어오면 끼어들기처럼 보이고 재생을 중단할 수 있습니다. 에코가 많은 Discord 방에서는 OpenAI가 입력 오디오에서 자동으로 중단하지 않도록 voice.realtime.providers.openai.interruptResponseOnInputAudio: false를 설정하세요. 그래도 Discord 화자 시작 이벤트가 활성 재생을 중단하길 원한다면 voice.realtime.bargeIn: true를 추가하세요. OpenAI Realtime 브리지는 voice.realtime.minBargeInAudioEndMs보다 짧은 재생 잘림을 에코/잡음 가능성이 높은 것으로 보고 무시하며, Discord 재생을 지우는 대신 건너뛴 것으로 로그에 남깁니다.
• voice.captureSilenceGraceMs는 Discord가 화자가 멈췄다고 보고한 뒤 OpenClaw가 해당 오디오 세그먼트를 STT용으로 확정하기까지 기다리는 시간을 제어합니다. 기본값: 2500; Discord가 일반적인 멈춤을 끊긴 부분 전사로 나눈다면 이 값을 높이세요.
• ElevenLabs가 선택된 TTS 제공자인 경우 Discord 음성 재생은 스트리밍 TTS를 사용하며 제공자 응답 스트림에서 시작합니다. 스트리밍을 지원하지 않는 제공자는 합성된 임시 파일 경로로 대체됩니다.
• OpenClaw는 수신 복호화 실패도 감시하며, 짧은 시간 안에 반복 실패가 발생하면 음성 채널을 떠났다가 다시 참여하여 자동으로 복구합니다.
• 업데이트 후 수신 로그에 DecryptionFailed(UnencryptedWhenPassthroughDisabled)가 반복해서 표시되면 의존성 보고서와 로그를 수집하세요. 번들된 @discordjs/voice 라인에는 discord.js PR #11449의 업스트림 패딩 수정이 포함되어 있으며, 이 수정은 discord.js 이슈 #11419를 닫았습니다.
• The operation was aborted 수신 이벤트는 OpenClaw가 캡처된 화자 세그먼트를 확정할 때 예상되는 이벤트입니다. 이는 경고가 아니라 자세한 진단 정보입니다.
• 자세한 Discord 음성 로그에는 허용된 각 화자 세그먼트에 대해 제한된 한 줄 STT 전사 미리보기가 포함되므로, 디버깅 시 무제한 전사 텍스트를 덤프하지 않고도 사용자 측과 에이전트 응답 측을 모두 볼 수 있습니다.
• agent-proxy 모드에서 강제 상담 폴백은 ...로 끝나는 텍스트나 and 같은 후행 연결어처럼 불완전할 가능성이 높은 전사 조각, 그리고 “곧 돌아올게요” 또는 “안녕” 같은 명백히 실행 불가능한 종료 발화를 건너뜁니다. 이로 인해 오래된 대기열 답변이 방지되면 로그에 forced agent consult skipped reason=...가 표시됩니다.

pnpm install
mise exec node@22 -- pnpm discord:opus:install

OPENCLAW_DISCORD_OPUS_DECODER=native pnpm gateway:watch

• Discord PCM 캡처는 WAV 임시 파일로 변환됩니다.
• tools.media.audio가 STT를 처리합니다. 예: openai/gpt-4o-mini-transcribe.
• 전사는 Discord 인그레스와 라우팅을 통해 전송되며, 응답 LLM은 에이전트 tts 도구를 숨기고 반환 텍스트를 요청하는 음성 출력 정책으로 실행됩니다. 최종 TTS 재생은 Discord 음성이 소유하기 때문입니다.
• voice.model이 설정된 경우 이 음성 채널 턴의 응답 LLM만 재정의합니다.
• voice.tts는 messages.tts 위에 병합됩니다. 스트리밍 가능한 제공자는 플레이어에 직접 공급하고, 그렇지 않으면 결과 오디오 파일이 참여한 채널에서 재생됩니다.

{
  channels: {
    discord: {
      voice: {
        enabled: true,
        model: "openai-codex/gpt-5.5",
        realtime: {
          provider: "openai",
          model: "gpt-realtime-2",
          voice: "cedar",
        },
      },
    },
  },
}

{
  channels: {
    discord: {
      voice: {
        enabled: true,
        mode: "stt-tts",
        model: "openai/gpt-5.4-mini",
        tts: {
          provider: "openai",
          openai: {
            model: "gpt-4o-mini-tts",
            voice: "cedar",
          },
        },
      },
    },
  },
}

{
  channels: {
    discord: {
      voice: {
        enabled: true,
        mode: "bidi",
        model: "openai-codex/gpt-5.5",
        realtime: {
          provider: "openai",
          model: "gpt-realtime-2",
          voice: "cedar",
          toolPolicy: "safe-read-only",
          consultPolicy: "always",
        },
      },
    },
  },
}

{
  channels: {
    discord: {
      voice: {
        enabled: true,
        mode: "agent-proxy",
        model: "openai-codex/gpt-5.5",
        agentSession: {
          mode: "target",
          target: "channel:123456789012345678",
        },
        realtime: {
          provider: "openai",
          model: "gpt-realtime-2",
          voice: "cedar",
        },
      },
    },
  },
}

• target: "channel:123456789012345678"는 Discord 텍스트 채널 세션을 통해 라우팅합니다.
• target: "123456789012345678"는 채널 대상으로 취급됩니다.
• target: "dm:123456789012345678" 또는 target: "user:123456789012345678"는 해당 다이렉트 메시지 세션을 통해 라우팅합니다.

{
  channels: {
    discord: {
      voice: {
        enabled: true,
        mode: "bidi",
        model: "openai-codex/gpt-5.5",
        realtime: {
          provider: "openai",
          model: "gpt-realtime-2",
          voice: "cedar",
          bargeIn: true,
          minBargeInAudioEndMs: 500,
          consultPolicy: "always",
          providers: {
            openai: {
              interruptResponseOnInputAudio: false,
            },
          },
        },
      },
    },
  },
}

• 참여 시: discord voice: joining ... voiceSession=... supervisorSession=... agentSessionMode=... voiceModel=... realtimeModel=...
• realtime 시작 시: discord voice: realtime bridge starting ... autoRespond=false interruptResponse=false bargeIn=false minBargeInAudioEndMs=...
• 화자 오디오 시: discord voice: realtime speaker turn opened ..., discord voice: realtime input audio started ... outputAudioMs=... outputActive=..., 및 discord voice: realtime speaker turn closed ... chunks=... discordBytes=... realtimeBytes=... interruptedPlayback=...
• 오래된 음성 건너뜀 시: discord voice: realtime forced agent consult skipped reason=incomplete-transcript ... 또는 reason=non-actionable-closing ...
• realtime 응답 완료 시: discord voice: realtime audio playback finishing reason=response.done ... audioMs=... chunks=...
• 재생 중지/재설정 시: discord voice: realtime audio playback stopped reason=... audioMs=... elapsedMs=... chunks=...
• realtime consult 시: discord voice: realtime consult requested ... voiceSession=... supervisorSession=... question=...
• 에이전트 답변 시: discord voice: agent turn answer ...
• 정확한 음성 대기열 추가 시: discord voice: realtime exact speech queued ... queued=... outputAudioMs=... outputActive=..., 이후 discord voice: realtime exact speech dequeued reason=player-idle ...
• 끼어들기 감지 시: discord voice: realtime barge-in detected source=speaker-start ... 또는 discord voice: realtime barge-in detected source=active-speaker-audio ..., 이후 discord voice: realtime barge-in requested reason=... outputAudioMs=... outputActive=...
• realtime 중단 시: discord voice: realtime model interrupt requested client:response.cancel reason=barge-in, 이후 discord voice: realtime model audio truncated client:conversation.item.truncate reason=barge-in audioEndMs=... 또는 discord voice: realtime model interrupt confirmed server:response.done status=cancelled ...
• 무시된 에코/노이즈 시: discord voice: realtime model interrupt ignored client:conversation.item.truncate.skipped reason=barge-in audioEndMs=0 minAudioEndMs=250
• 비활성화된 끼어들기 시: discord voice: realtime capture ignored during playback (barge-in disabled) ...
• 유휴 재생 시: discord voice: realtime barge-in ignored reason=... outputActive=false ... playbackChunks=0

1. realtime audio playback started는 Discord가 어시스턴트 오디오 재생을 시작했다는 뜻입니다. 브리지는 이 지점부터 어시스턴트 출력 청크, Discord PCM 바이트, 제공자 realtime 바이트, 합성된 오디오 길이를 세기 시작합니다.
2. realtime speaker turn opened는 Discord 화자가 활성 상태가 되었음을 표시합니다. 재생이 이미 활성 상태이고 bargeIn이 활성화되어 있으면, 뒤이어 barge-in detected source=speaker-start가 나타날 수 있습니다.
3. realtime input audio started는 해당 화자 턴에 대해 실제 첫 오디오 프레임이 수신되었음을 표시합니다. 여기서 outputActive=true 또는 0이 아닌 outputAudioMs는 어시스턴트 재생이 아직 활성 상태인 동안 마이크가 입력을 보내고 있음을 의미합니다.
4. barge-in detected source=active-speaker-audio는 OpenClaw가 어시스턴트 재생이 활성 상태인 동안 라이브 화자 오디오를 확인했다는 뜻입니다. 이는 유용한 오디오가 없는 Discord 화자 시작 이벤트와 실제 중단을 구분하는 데 유용합니다.
5. barge-in requested reason=...는 OpenClaw가 realtime 제공자에게 활성 응답을 취소하거나 잘라내도록 요청했다는 뜻입니다. 중단 전에 실제로 재생된 어시스턴트 오디오의 양을 확인할 수 있도록 outputAudioMs, outputActive, playbackChunks를 포함합니다.
6. realtime audio playback stopped reason=...는 로컬 Discord 재생 재설정 지점입니다. 이유는 재생을 누가 중지했는지 나타냅니다: barge-in, player-idle, provider-clear-audio, forced-agent-consult, stream-close, 또는 session-close.
7. realtime speaker turn closed는 캡처된 입력 턴을 요약합니다. chunks=0 또는 hasAudio=false는 화자 턴이 열렸지만 사용 가능한 오디오가 realtime 브리지에 도달하지 않았음을 의미합니다. interruptedPlayback=true는 해당 입력 턴이 어시스턴트 출력과 겹쳤고 끼어들기 로직을 트리거했음을 의미합니다.

• outputAudioMs: 로그 줄 이전에 realtime 제공자가 생성한 어시스턴트 오디오 길이입니다.
• audioMs: 재생이 중지되기 전에 OpenClaw가 계산한 어시스턴트 오디오 길이입니다.
• elapsedMs: 재생 스트림 또는 화자 턴을 열고 닫는 사이의 실제 경과 시간입니다.
• discordBytes: Discord 음성으로 보내거나 Discord 음성에서 받은 48 kHz 스테레오 PCM 바이트입니다.
• realtimeBytes: realtime 제공자에게 보내거나 제공자에서 받은 제공자 형식 PCM 바이트입니다.
• playbackChunks: 활성 응답에 대해 Discord로 전달된 어시스턴트 오디오 청크입니다.
• sinceLastAudioMs: 마지막으로 캡처된 화자 오디오 프레임과 화자 턴 종료 사이의 간격입니다.

• source=active-speaker-audio, 작은 outputAudioMs, 같은 사용자가 근처에 있는 즉시 끊김은 보통 스피커 에코가 마이크로 유입됨을 나타냅니다. voice.realtime.minBargeInAudioEndMs를 높이거나, 스피커 볼륨을 낮추거나, 헤드폰을 사용하거나, voice.realtime.providers.openai.interruptResponseOnInputAudio: false를 설정하세요.
• source=speaker-start 뒤에 speaker turn closed ... hasAudio=false가 나타나면 Discord가 화자 시작을 보고했지만 오디오가 OpenClaw에 도달하지 않았다는 뜻입니다. 이는 일시적인 Discord 음성 이벤트, 노이즈 게이트 동작, 또는 클라이언트가 잠시 마이크를 켜는 동작일 수 있습니다.
• 근처에 끼어들기 또는 provider-clear-audio 없이 audio playback stopped reason=stream-close가 나타나면 로컬 Discord 재생 스트림이 예기치 않게 종료되었다는 뜻입니다. 앞선 제공자 및 Discord 플레이어 로그를 확인하세요.
• capture ignored during playback (barge-in disabled)는 어시스턴트 오디오가 활성 상태인 동안 OpenClaw가 의도적으로 입력을 버렸다는 뜻입니다. 음성이 재생을 중단하게 하려면 voice.realtime.bargeIn을 활성화하세요.
• barge-in ignored ... outputActive=false는 Discord 또는 제공자 VAD가 음성을 보고했지만, OpenClaw에 중단할 활성 재생이 없었다는 뜻입니다. 이 경우 오디오가 끊기면 안 됩니다.

​

음성 메시지

• 로컬 파일 경로를 제공하세요(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,
          },
        },
      },
    },
  },
}

{
  channels: {
    discord: {
      accounts: {
        mantis: {
          // Mantis listens to other bots only when they mention her.
          allowBots: "mentions",
        },
        molty: {
          // Molty listens to all bot-authored Discord messages.
          allowBots: true,
          mentionAliases: {
            // Lets Molty write "@Mantis" and send a real Discord mention.
            Mantis: "MANTIS_DISCORD_USER_ID",
          },
        },
      },
    },
  },
}

​

구성 참고 자료

​

안전 및 운영

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

​

관련 항목