Discord

DM 및 길드 채널에서 공식 Discord Gateway를 통해 사용할 준비가 되었습니다.

빠른 설정

봇이 있는 새 애플리케이션을 만들고, 봇을 서버에 추가한 다음 OpenClaw에 페어링해야 합니다. 봇은 본인의 비공개 서버에 추가하는 것을 권장합니다. 아직 서버가 없다면 먼저 만드세요(Create My Own > For me and my friends 선택).

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" },},},}JSON5openclaw config patch --file ./discord.patch.json5 --dry-runopenclaw config patch --file ./discord.patch.json5openclaw 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 discordopenclaw pairing approve discord <CODE>

권장: 길드 작업 공간 설정

DM이 작동하면, 각 채널이 자체 컨텍스트를 가진 자체 에이전트 세션을 받는 전체 작업 공간으로 Discord 서버를 설정할 수 있습니다. 본인과 봇만 있는 비공개 서버에 권장됩니다.

{channels: {discord: {groupPolicy: "allowlist",guilds: {YOUR_SERVER_ID: {  requireMention: true,  users: ["YOUR_USER_ID"],},},},},}

{channels: {discord: {guilds: {YOUR_SERVER_ID: {  requireMention: false,},},},},}

이제 Discord 서버에 몇 개의 채널을 만들고 채팅을 시작하세요. 에이전트는 채널 이름을 볼 수 있고, 각 채널은 자체 격리된 세션을 받습니다. 따라서 워크플로에 맞게 #coding, #home, #research 등을 설정할 수 있습니다.

런타임 모델

• 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 알림은 최종적으로 어시스턴트에 표시되는 답변을 한 번 사용합니다. 미디어와 구조화된 컴포넌트 페이로드는 에이전트가 전달 가능한 페이로드를 여러 개 내보낼 때 여러 메시지로 유지됩니다.

포럼 채널

Discord 포럼 및 미디어 채널은 스레드 게시물만 허용합니다. OpenClaw는 이를 생성하는 두 가지 방법을 지원합니다.

• 포럼 부모(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"

포럼 부모는 Discord 컴포넌트를 허용하지 않습니다. 컴포넌트가 필요하면 스레드 자체(channel:<threadId>)로 보내세요.

인터랙티브 컴포넌트

OpenClaw는 에이전트 메시지에 대해 Discord 컴포넌트 v2 컨테이너를 지원합니다. components 페이로드와 함께 메시지 도구를 사용하세요. 상호작용 결과는 일반 인바운드 메시지처럼 에이전트로 다시 라우팅되며 기존 Discord replyToMode 설정을 따릅니다.

지원되는 블록:

• text, section, separator, actions, media-gallery, file
• 액션 행은 최대 5개의 버튼 또는 단일 선택 메뉴를 허용합니다.
• 선택 유형: string, user, role, mentionable, channel

기본적으로 컴포넌트는 일회용입니다. 버튼, 선택 항목, 양식을 만료될 때까지 여러 번 사용할 수 있게 하려면 components.reusable=true를 설정하세요.

버튼을 클릭할 수 있는 사용자를 제한하려면 해당 버튼에 allowedUsers를 설정하세요(Discord 사용자 ID, 태그 또는 *). 구성된 경우 일치하지 않는 사용자는 임시 거부 메시지를 받습니다.

컴포넌트 콜백은 기본적으로 30분 후 만료됩니다. 기본 Discord 계정의 콜백 레지스트리 수명을 변경하려면 channels.discord.agentComponents.ttlMs를 설정하거나, 다중 계정 설정에서 한 계정을 재정의하려면 channels.discord.accounts.<accountId>.agentComponents.ttlMs를 설정하세요. 값은 밀리초이며 양의 정수여야 하고 86400000(24시간)으로 제한됩니다. 더 긴 TTL은 버튼을 계속 사용할 수 있어야 하는 검토 또는 승인 워크플로에 유용하지만, 오래된 Discord 메시지가 여전히 액션을 트리거할 수 있는 기간도 늘립니다. 워크플로에 맞는 가장 짧은 TTL을 선호하고, 오래된 콜백이 예상 밖일 수 있다면 기본값을 유지하세요.

/model 및 /models 슬래시 명령은 제공자, 모델, 호환 런타임 드롭다운과 제출 단계가 있는 인터랙티브 모델 선택기를 엽니다. /models add는 더 이상 권장되지 않으며 이제 채팅에서 모델을 등록하는 대신 지원 중단 메시지를 반환합니다. 선택기 응답은 임시이며 호출한 사용자만 사용할 수 있습니다. Discord 선택 메뉴는 옵션이 25개로 제한되므로, openai 또는 vllm 같은 선택된 제공자에 대해서만 동적으로 발견된 모델을 선택기에 표시하려면 agents.defaults.models에 provider/* 항목을 추가하세요.

파일 첨부:

• 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[].match.roles를 사용해 Discord 길드 멤버를 역할 ID별로 다른 에이전트에 라우팅합니다. 역할 기반 바인딩은 역할 ID만 허용하며 피어 또는 부모 피어 바인딩 이후, 길드 전용 바인딩 이전에 평가됩니다. 바인딩이 다른 일치 필드도 설정하는 경우(예: peer + guildId + roles), 구성된 모든 필드가 일치해야 합니다.

{  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: {  suppressEmbeds: false,},},}

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

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

도구 및 작업 게이트

Discord 메시지 작업에는 메시징, 채널 관리, 조정, 상태 표시, 메타데이터 작업이 포함됩니다.

핵심 예시:

• 메시징: sendMessage, readMessages, editMessage, deleteMessage, threadReply
• 반응: react, reactions, emojiList
• 조정: timeout, kick, ban
• 상태 표시: setPresence

event-create 작업은 예약된 이벤트 커버 이미지를 설정하기 위해 선택적 image 매개변수(URL 또는 로컬 파일 경로)를 허용합니다.

작업 게이트는 channels.discord.actions.* 아래에 있습니다.

기본 게이트 동작:

Components v2 UI

OpenClaw는 exec 승인과 교차 컨텍스트 마커에 Discord components v2를 사용합니다. Discord 메시지 작업은 사용자 지정 UI를 위해 components도 허용할 수 있습니다(고급; discord 도구를 통해 컴포넌트 페이로드를 구성해야 함). 레거시 embeds는 계속 사용할 수 있지만 권장되지 않습니다.

• channels.discord.ui.components.accentColor는 Discord 컴포넌트 컨테이너에서 사용하는 강조 색상(16진수)을 설정합니다.
• 계정별로 channels.discord.accounts.<id>.ui.components.accentColor를 설정하세요.
• channels.discord.agentComponents.ttlMs는 보낸 Discord 컴포넌트 콜백이 등록 상태로 유지되는 시간을 제어합니다(기본값 1800000, 최대 86400000). 계정별로 channels.discord.accounts.<id>.agentComponents.ttlMs를 설정하세요.
• components v2가 있으면 embeds는 무시됩니다.
• 일반 URL 미리 보기는 기본적으로 억제됩니다. 단일 아웃바운드 링크를 펼쳐야 할 때는 메시지 작업에서 suppressEmbeds: false를 설정하세요.

예시:

{  channels: {    discord: {      ui: {        components: {          accentColor: "#5865F2",        },      },    },  },}

음성

Discord에는 실시간 음성 채널(연속 대화)과 음성 메시지 첨부 파일(파형 미리 보기 형식)이라는 두 가지 별개의 음성 표면이 있습니다. Gateway는 둘 다 지원합니다.

음성 채널

설정 체크리스트:

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|leave|status를 사용하세요. 이 명령은 계정 기본 에이전트를 사용하며 다른 Discord 명령과 동일한 허용 목록 및 그룹 정책 규칙을 따릅니다.

/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/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",          speakerVoice: "cedar",        },      },    },  },}

참고:

• voice.tts는 stt-tts 음성 재생에만 messages.tts를 재정의합니다. 실시간 모드는 voice.realtime.speakerVoice를 사용합니다.
• voice.mode는 대화 경로를 제어합니다. 기본값은 agent-proxy입니다. 실시간 음성 프런트엔드가 턴 타이밍, 중단, 재생을 처리하고, 실질적인 작업은 openclaw_agent_consult를 통해 라우팅된 OpenClaw 에이전트에 위임하며, 결과를 해당 화자가 입력한 Discord 프롬프트처럼 처리합니다. stt-tts는 기존 일괄 STT 및 TTS 흐름을 유지합니다. bidi는 OpenClaw 브레인을 위해 openclaw_agent_consult를 노출하면서 실시간 모델이 직접 대화할 수 있게 합니다.
• voice.agentSession은 어떤 OpenClaw 대화가 음성 턴을 받을지 제어합니다. 음성 채널 자체 세션을 사용하려면 설정하지 않은 상태로 두거나, 음성 채널이 #maintainers 같은 기존 Discord 텍스트 채널 세션의 마이크/스피커 확장처럼 동작하게 하려면 { mode: "target", target: "channel:<text-channel-id>" }로 설정합니다.
• voice.model은 Discord 음성 응답 및 실시간 consult에 사용할 OpenClaw 에이전트 브레인을 재정의합니다. 라우팅된 에이전트 모델을 상속하려면 설정하지 않은 상태로 둡니다. 이는 voice.realtime.model과 별개입니다.
• voice.followUsers를 사용하면 봇이 선택한 사용자와 함께 Discord 음성에 참가하고, 이동하고, 나갈 수 있습니다. 동작 규칙과 예시는 음성에서 사용자 따라가기를 참조하세요.
• agent-proxy는 음성을 discord-voice를 통해 라우팅합니다. 이 방식은 화자 및 대상 세션에 대한 일반적인 소유자/도구 권한 부여는 유지하지만, Discord 음성이 재생을 소유하므로 에이전트 tts 도구는 숨깁니다. 기본적으로 agent-proxy는 소유자 화자에게 consult가 소유자와 동등한 전체 도구 접근 권한을 갖게 하며(voice.realtime.toolPolicy: "owner"), 실질적인 답변 전에 OpenClaw 에이전트에 consult하는 것을 강하게 선호합니다(voice.realtime.consultPolicy: "always"). 기본 always 모드에서는 실시간 계층이 consult 답변 전에 자동으로 채움말을 말하지 않습니다. 음성을 캡처하고 전사한 다음, 라우팅된 OpenClaw 답변을 말합니다. Discord가 첫 번째 답변을 아직 재생 중인 동안 여러 강제 consult 답변이 완료되면, 이후의 정확한 음성 답변은 문장 중간에 음성을 바꾸지 않고 재생이 유휴 상태가 될 때까지 큐에 들어갑니다.
• stt-tts 모드에서 STT는 tools.media.audio를 사용하며, voice.model은 전사에 영향을 주지 않습니다.
• 실시간 모드에서 voice.realtime.provider, voice.realtime.model, voice.realtime.speakerVoice는 실시간 오디오 세션을 구성합니다. OpenAI Realtime 2와 Codex 브레인을 함께 사용하려면 voice.realtime.model: "gpt-realtime-2" 및 voice.model: "openai/gpt-5.5"를 사용합니다.
• 실시간 음성 모드는 기본적으로 작은 IDENTITY.md, USER.md, SOUL.md 프로필 파일을 실시간 provider 지침에 포함하여, 빠른 직접 턴도 라우팅된 OpenClaw 에이전트와 동일한 정체성, 사용자 기반 정보, 페르소나를 유지하게 합니다. 이를 사용자 지정하려면 voice.realtime.bootstrapContextFiles를 하위 집합으로 설정하거나, 비활성화하려면 []로 설정합니다. 지원되는 실시간 부트스트랩 파일은 해당 프로필 파일로 제한되며, AGENTS.md는 일반 에이전트 컨텍스트에 남습니다. 주입된 프로필 컨텍스트는 워크스페이스 작업, 현재 사실, 메모리 조회, 도구 기반 작업에서 openclaw_agent_consult를 대체하지 않습니다.
• OpenAI agent-proxy 실시간 모드에서 전사가 wake name으로 시작하거나 끝날 때까지 Discord 실시간 음성이 침묵하도록 하려면 voice.realtime.requireWakeName: true를 설정합니다. 구성된 wake name은 한 단어 또는 두 단어여야 합니다. voice.realtime.wakeNames가 설정되지 않은 경우 OpenClaw는 라우팅된 에이전트 name과 OpenClaw를 사용하며, 없으면 에이전트 id와 OpenClaw로 대체합니다. wake-name 게이팅은 실시간 provider 자동 응답을 비활성화하고, 허용된 턴을 OpenClaw 에이전트 consult 경로로 라우팅하며, 최종 전사가 도착하기 전에 부분 전사에서 선행 wake name이 인식되면 짧은 음성 확인을 제공합니다.
• OpenAI 실시간 provider는 현재 Realtime 2 이벤트 이름과 출력 오디오 및 전사 이벤트에 대한 레거시 Codex 호환 별칭을 허용하므로, 호환 provider 스냅샷이 달라져도 어시스턴트 오디오가 누락되지 않습니다.
• voice.realtime.bargeIn은 Discord 화자 시작 이벤트가 활성 실시간 재생을 중단할지 여부를 제어합니다. 설정하지 않으면 실시간 provider의 입력 오디오 중단 설정을 따릅니다.
• voice.realtime.minBargeInAudioEndMs는 OpenAI 실시간 barge-in이 오디오를 잘라내기 전 최소 어시스턴트 재생 시간을 제어합니다. 기본값: 250. 에코가 적은 방에서 즉시 중단하려면 0으로 설정하고, 에코가 많은 스피커 설정에서는 값을 높입니다.
• Discord 재생에 OpenAI 음성을 사용하려면 voice.tts.provider: "openai"를 설정하고 voice.tts.providers.openai.speakerVoice 아래에서 텍스트 음성 변환 음성을 선택합니다. cedar는 현재 OpenAI TTS 모델에서 남성적으로 들리는 좋은 선택입니다.
• 채널별 Discord systemPrompt 재정의는 해당 음성 채널의 음성 전사 턴에 적용됩니다.
• 음성 전사 턴은 소유자 게이트 명령 및 채널 작업에 대해 Discord allowFrom 또는 dm.allowFrom에서 소유자 상태를 파생합니다. 에이전트 도구 가시성은 라우팅된 세션에 구성된 도구 정책을 따릅니다.
• Discord 음성은 텍스트 전용 구성에서는 옵트인입니다. /vc 명령, 음성 런타임, GuildVoiceStates Gateway intent를 활성화하려면 channels.discord.voice.enabled=true를 설정하거나 기존 channels.discord.voice 블록을 유지합니다.
• channels.discord.intents.voiceStates는 음성 상태 intent 구독을 명시적으로 재정의할 수 있습니다. intent가 유효한 음성 활성화 상태를 따르게 하려면 설정하지 않은 상태로 둡니다.
• voice.autoJoin에 같은 길드에 대한 항목이 여러 개 있으면 OpenClaw는 해당 길드에 대해 마지막으로 구성된 채널에 참가합니다.
• voice.allowedChannels는 선택적 상주 허용 목록입니다. 승인된 Discord 음성 채널 어디든 /vc join으로 들어갈 수 있게 하려면 설정하지 않은 상태로 둡니다. 설정된 경우 /vc join, 시작 시 자동 참가, 봇 음성 상태 이동은 나열된 { guildId, channelId } 항목으로 제한됩니다. 모든 Discord 음성 참가를 거부하려면 빈 배열로 설정합니다. Discord가 봇을 허용 목록 밖으로 이동시키면 OpenClaw는 해당 채널을 떠나고 사용 가능한 경우 구성된 자동 참가 대상으로 다시 참가합니다.
• voice.daveEncryption 및 voice.decryptionFailureTolerance는 @discordjs/voice 참가 옵션으로 전달됩니다.
• 설정하지 않은 경우 @discordjs/voice 기본값은 daveEncryption=true 및 decryptionFailureTolerance=24입니다.
• OpenClaw는 Discord 음성 수신 및 실시간 원시 PCM 재생에 번들된 libopus-wasm 코덱을 사용합니다. 고정된 libopus WebAssembly 빌드를 제공하며 네이티브 opus 애드온이 필요하지 않습니다.
• voice.connectTimeoutMs는 /vc join 및 자동 참가 시도에 대한 초기 @discordjs/voice Ready 대기 시간을 제어합니다. 기본값: 30000.
• voice.reconnectGraceMs는 연결이 끊긴 음성 세션이 다시 연결을 시작하기까지 OpenClaw가 파기 전 기다리는 시간을 제어합니다. 기본값: 15000.
• stt-tts 모드에서는 다른 사용자가 말하기 시작했다는 이유만으로 음성 재생이 멈추지 않습니다. 피드백 루프를 피하기 위해 OpenClaw는 TTS가 재생 중일 때 새 음성 캡처를 무시합니다. 다음 턴은 재생이 끝난 뒤 말하세요. 실시간 모드는 화자 시작을 barge-in 신호로 실시간 provider에 전달합니다.
• 실시간 모드에서는 스피커의 에코가 열린 마이크로 들어가 barge-in처럼 보이고 재생을 중단할 수 있습니다. 에코가 많은 Discord 방에서는 입력 오디오에서 OpenAI가 자동 중단하지 않도록 voice.realtime.providers.openai.interruptResponseOnInputAudio: false를 설정합니다. 그래도 Discord 화자 시작 이벤트가 활성 재생을 중단하길 원하면 voice.realtime.bargeIn: true를 추가합니다. OpenAI 실시간 브리지는 voice.realtime.minBargeInAudioEndMs보다 짧은 재생 잘림을 에코/노이즈 가능성이 높은 것으로 보고, Discord 재생을 지우지 않고 건너뛴 것으로 기록합니다.
• voice.captureSilenceGraceMs는 Discord가 화자가 멈췄다고 보고한 뒤 STT를 위해 해당 오디오 세그먼트를 확정하기까지 OpenClaw가 기다리는 시간을 제어합니다. 기본값: 2000. Discord가 정상적인 멈춤을 끊어진 부분 전사로 나누는 경우 이 값을 높입니다.
• ElevenLabs가 선택된 TTS provider인 경우 Discord 음성 재생은 스트리밍 TTS를 사용하며 provider 응답 스트림에서 시작합니다. 스트리밍 지원이 없는 provider는 합성된 임시 파일 경로로 폴백합니다.
• OpenClaw는 수신 복호화 실패도 감시하며, 짧은 시간 안에 실패가 반복되면 음성 채널을 나갔다가 다시 참가하여 자동 복구합니다.
• 업데이트 후 수신 로그에 DecryptionFailed(UnencryptedWhenPassthroughDisabled)가 반복해서 표시되면 의존성 보고서와 로그를 수집하세요. 번들된 @discordjs/voice 라인에는 discord.js PR #11449의 업스트림 패딩 수정이 포함되어 있으며, 이 수정은 discord.js 이슈 #11419를 닫았습니다.
• The operation was aborted 수신 이벤트는 OpenClaw가 캡처된 화자 세그먼트를 확정할 때 예상되는 이벤트입니다. 이는 상세 진단 정보이며 경고가 아닙니다.
• 상세 Discord 음성 로그에는 허용된 각 화자 세그먼트에 대해 제한된 한 줄 STT 전사 미리보기가 포함되므로, 디버깅 시 무제한 전사 텍스트를 덤프하지 않고도 사용자 측과 에이전트 응답 측을 모두 볼 수 있습니다.
• agent-proxy 모드에서 강제 consult 폴백은 ...로 끝나는 텍스트나 and 같은 후행 연결어처럼 불완전해 보이는 전사 조각, 그리고 “be right back” 또는 “bye”처럼 명백히 실행 불가능한 마무리 말을 건너뜁니다. 이로 인해 오래된 큐 답변이 방지되면 로그에 forced agent consult skipped reason=...가 표시됩니다.

음성에서 사용자 따라가기

시작 시 고정 채널에 참가하거나 /vc join을 기다리는 대신 Discord 음성 봇이 하나 이상의 알려진 Discord 사용자와 함께 머무르게 하려면 voice.followUsers를 사용합니다.

{  channels: {    discord: {      voice: {        enabled: true,        followUsersEnabled: true,        followUsers: ["discord:123456789012345678"],        allowedChannels: [          {            guildId: "123456789012345678",            channelId: "234567890123456789",          },        ],      },    },  },}

동작:

• followUsers는 원시 Discord 사용자 ID와 discord:<id> 값을 허용합니다. OpenClaw는 음성 상태 이벤트를 매칭하기 전에 두 형식을 모두 정규화합니다.
• followUsersEnabled는 followUsers가 구성된 경우 기본값이 true입니다. 저장된 목록은 유지하되 자동 음성 따라가기를 중지하려면 false로 설정합니다.
• 따라가는 사용자가 허용된 음성 채널에 참가하면 OpenClaw도 해당 채널에 참가합니다. 사용자가 이동하면 OpenClaw도 함께 이동합니다. 활성 상태인 따라가는 사용자의 연결이 끊기면 OpenClaw는 나갑니다.
• 같은 길드에 따라가는 사용자가 여러 명 있고 활성 상태인 따라가는 사용자가 나가면, OpenClaw는 길드를 떠나기 전에 추적 중인 다른 따라가는 사용자의 채널로 이동합니다. 여러 따라가는 사용자가 동시에 이동하면 마지막으로 관찰된 음성 상태 이벤트가 우선합니다.
• allowedChannels는 계속 적용됩니다. 허용되지 않은 채널에 있는 따라가는 사용자는 무시되며, follow 소유 세션은 다른 따라가는 사용자에게 이동하거나 나갑니다.
• OpenClaw는 시작 시와 제한된 간격으로 누락된 음성 상태 이벤트를 조정합니다. 조정은 구성된 길드를 샘플링하고 실행당 REST 조회 수를 제한하므로, 매우 큰 followUsers 목록은 수렴하는 데 둘 이상의 간격이 걸릴 수 있습니다.
• 사용자를 따라가는 중 Discord 또는 관리자가 봇을 이동시키면, OpenClaw는 음성 세션을 다시 만들고 대상이 허용된 경우 follow 소유권을 유지합니다. 봇이 allowedChannels 밖으로 이동되면 OpenClaw는 나가고, 구성된 대상이 있으면 다시 참가합니다.
• DAVE 수신 복구는 복호화 실패가 반복된 후 같은 채널을 나갔다가 다시 참가할 수 있습니다. follow 소유 세션은 해당 복구 경로에서도 follow 소유권을 유지하므로, 이후 따라가는 사용자의 연결이 끊기면 여전히 채널을 떠납니다.

참가 모드 선택:

• 봇이 사용자가 음성에 있을 때 자동으로 음성에 있어야 하는 개인 또는 운영자 설정에는 followUsers를 사용합니다.
• 추적 중인 사용자가 음성에 없더라도 봇이 있어야 하는 고정 방 봇에는 autoJoin을 사용합니다.
• 일회성 참가나 자동 음성 상주가 예상 밖일 수 있는 방에는 /vc join을 사용합니다.

Discord 음성 코덱:

• 음성 수신 로그에는 discord voice: opus decoder: libopus-wasm가 표시됩니다.
• 실시간 재생은 패킷을 @discordjs/voice에 전달하기 전에 동일하게 번들된 libopus-wasm 패키지로 원시 48 kHz 스테레오 PCM을 Opus로 인코딩합니다.
• 파일 및 공급자 스트림 재생은 ffmpeg로 원시 48 kHz 스테레오 PCM으로 트랜스코딩한 다음, Discord로 전송되는 Opus 패킷 스트림에 libopus-wasm을 사용합니다.

STT와 TTS 파이프라인:

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

기본 agent-proxy 음성 채널 세션 예시:

{  channels: {    discord: {      voice: {        enabled: true,        model: "openai/gpt-5.5",        followUsersEnabled: true,        followUsers: ["123456789012345678"],        realtime: {          provider: "openai",          model: "gpt-realtime-2",          speakerVoice: "cedar",        },      },    },  },}

voice.agentSession 블록이 없으면 각 음성 채널은 자체적으로 라우팅된 OpenClaw 세션을 갖습니다. 예를 들어 /vc join channel:234567890123456789는 해당 Discord 음성 채널의 세션과 대화합니다. 실시간 모델은 음성 프런트엔드일 뿐이며, 실제 요청은 구성된 OpenClaw agent로 전달됩니다. 실시간 모델이 consult 도구를 호출하지 않고 최종 transcript를 생성하면, OpenClaw는 기본 동작이 agent와 대화하는 것처럼 유지되도록 fallback으로 consult를 강제합니다.

레거시 STT와 TTS 예시:

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

실시간 양방향 예시:

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

기존 Discord 채널 세션의 확장으로서의 음성:

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

agent-proxy 모드에서는 봇이 구성된 음성 채널에 참가하지만, OpenClaw agent 턴은 대상 채널의 일반 라우팅 세션과 agent를 사용합니다. 실시간 음성 세션은 반환된 결과를 음성 채널로 다시 말해 줍니다. supervisor agent는 도구 정책에 따라 일반 메시지 도구를 계속 사용할 수 있으며, 적절한 동작이라면 별도의 Discord 메시지를 보내는 것도 포함됩니다.

위임된 OpenClaw 실행이 활성 상태인 동안 새 Discord 음성 transcript는 다른 agent 턴을 시작하기 전에 라이브 실행 제어로 처리됩니다. "status", "cancel that", "use the smaller fix", "when you're done also check tests" 같은 구문은 활성 세션에 대한 상태, 취소, 조정 또는 후속 입력으로 분류됩니다. 상태, 취소, 수락된 조정, 후속 결과는 음성 채널로 다시 말해 주므로 호출자는 OpenClaw가 요청을 처리했는지 알 수 있습니다.

유용한 대상 형식:

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

에코가 심한 OpenAI Realtime 예시:

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

모델이 열린 마이크를 통해 자체 Discord 재생음을 듣지만, 사용자가 말해서 중단할 수 있기를 원할 때 이 설정을 사용하세요. OpenClaw는 OpenAI가 원시 입력 오디오에서 자동으로 중단하지 않도록 하며, bargeIn: true는 다음 캡처 턴이 OpenAI에 도달하기 전에 Discord 화자 시작 이벤트와 이미 활성화된 화자 오디오가 활성 실시간 응답을 취소할 수 있게 합니다. audioEndMs가 minBargeInAudioEndMs보다 낮은 매우 이른 끼어들기 신호는 에코/노이즈일 가능성이 높은 것으로 처리되어 무시되므로, 모델이 첫 재생 프레임에서 끊기지 않습니다.

예상 음성 로그:

• 참가 시: discord voice: joining ... voiceSession=... supervisorSession=... agentSessionMode=... voiceModel=... realtimeModel=...
• 실시간 시작 시: 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 ...
• 실시간 응답 완료 시: discord voice: realtime audio playback finishing reason=response.done ... audioMs=... chunks=...
• 재생 중지/재설정 시: discord voice: realtime audio playback stopped reason=... audioMs=... elapsedMs=... chunks=...
• 실시간 consult 시: discord voice: realtime consult requested ... voiceSession=... supervisorSession=... question=...
• agent 답변 시: 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=...
• 실시간 중단 시: 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가 assistant 오디오 재생을 시작했다는 뜻입니다. 브리지는 이 시점부터 assistant 출력 청크, Discord PCM 바이트, 공급자 실시간 바이트, 합성 오디오 길이를 계산하기 시작합니다.
2. realtime speaker turn opened는 Discord 화자가 활성화되었음을 표시합니다. 재생이 이미 활성 상태이고 bargeIn이 활성화되어 있으면, 뒤이어 barge-in detected source=speaker-start가 나타날 수 있습니다.
3. realtime input audio started는 해당 화자 턴에서 실제 첫 오디오 프레임을 수신했음을 표시합니다. 여기서 outputActive=true 또는 0이 아닌 outputAudioMs는 assistant 재생이 아직 활성 상태인 동안 마이크가 입력을 보내고 있음을 의미합니다.
4. barge-in detected source=active-speaker-audio는 assistant 재생이 활성 상태인 동안 OpenClaw가 라이브 화자 오디오를 감지했다는 뜻입니다. 이는 실제 중단과 유용한 오디오가 없는 Discord 화자 시작 이벤트를 구분하는 데 유용합니다.
5. barge-in requested reason=...는 OpenClaw가 실시간 공급자에게 활성 응답을 취소하거나 자르도록 요청했다는 뜻입니다. 여기에는 outputAudioMs, outputActive, playbackChunks가 포함되어 중단 전에 실제로 얼마나 많은 assistant 오디오가 재생되었는지 확인할 수 있습니다.
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는 화자 턴은 열렸지만 사용할 수 있는 오디오가 실시간 브리지에 도달하지 않았음을 의미합니다. interruptedPlayback=true는 해당 입력 턴이 assistant 출력과 겹쳐 끼어들기 로직을 트리거했음을 의미합니다.

유용한 필드:

• outputAudioMs: 로그 줄 이전에 실시간 공급자가 생성한 assistant 오디오 길이.
• audioMs: 재생이 중지되기 전에 OpenClaw가 계산한 assistant 오디오 길이.
• elapsedMs: 재생 스트림 또는 화자 턴을 열고 닫는 사이의 실제 경과 시간.
• discordBytes: Discord 음성으로 전송되거나 Discord 음성에서 수신된 48 kHz 스테레오 PCM 바이트.
• realtimeBytes: 실시간 공급자로 전송되거나 실시간 공급자에서 수신된 공급자 형식 PCM 바이트.
• playbackChunks: 활성 응답을 위해 Discord로 전달된 assistant 오디오 청크.
• 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)는 assistant 오디오가 활성 상태인 동안 OpenClaw가 의도적으로 입력을 버렸다는 뜻입니다. 발화로 재생을 중단하고 싶다면 voice.realtime.bargeIn을 활성화하세요.
• barge-in ignored ... outputActive=false는 Discord 또는 공급자 VAD가 발화를 보고했지만, OpenClaw에는 중단할 활성 재생이 없었다는 뜻입니다. 이 경우 오디오가 끊기면 안 됩니다.

자격 증명은 컴포넌트별로 확인됩니다: voice.model의 LLM 라우트 인증, tools.media.audio의 STT 인증, messages.tts/voice.tts의 TTS 인증, 그리고 voice.realtime.providers 또는 공급자의 일반 인증 설정에 대한 실시간 공급자 인증입니다.

음성 메시지

Discord 음성 메시지는 waveform 미리보기를 표시하며 OGG/Opus 오디오가 필요합니다. OpenClaw는 waveform을 자동으로 생성하지만, 검사 및 변환을 위해 Gateway 호스트에 ffmpeg와 ffprobe가 필요합니다.

• 로컬 파일 경로를 제공하세요(URL은 거부됩니다).
• 텍스트 콘텐츠는 생략하세요(Discord는 동일한 페이로드에 텍스트와 음성 메시지를 함께 넣는 것을 거부합니다).
• 모든 오디오 형식을 사용할 수 있습니다. OpenClaw는 필요에 따라 OGG/Opus로 변환합니다.

message(action="send", channel="discord", target="channel:123", path="/path/to/audio.mp3", asVoice=true)

문제 해결

openclaw doctoropenclaw channels status --probeopenclaw logs --follow

{channels: {discord: {  accounts: {    default: {      eventQueue: {        listenerTimeout: 120000,      },    },  },},},}

{channels: {defaults: {  botLoopProtection: {    maxEventsPerWindow: 20,    windowSeconds: 60,    cooldownSeconds: 60,  },},discord: {  // Optional Discord-wide override. Account blocks override individual  // fields and inherit omitted fields from here.  botLoopProtection: {    maxEventsPerWindow: 4,  },  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 a Mantis Discord mention with the configured user id.        Mantis: "MANTIS_DISCORD_USER_ID",      },      botLoopProtection: {        // Allow up to five messages per minute before suppressing the pair.        maxEventsPerWindow: 5,        windowSeconds: 60,        cooldownSeconds: 90,      },    },  },},},}

구성 참조

기본 참조: 구성 참조 - Discord.

안전 및 운영

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

관련 항목