Discord

Discord는 에이전트 출력의 답장 태그를 지원합니다.

• [[reply_to_current]]
• [[reply_to:<id>]]

channels.discord.replyToMode로 제어됩니다.

• off(기본값)
• first
• all
• batched

참고: off는 암시적 답장 스레딩을 비활성화합니다. 명시적 [[reply_to_*]] 태그는 여전히 적용됩니다. first는 항상 해당 턴의 첫 번째 발신 Discord 메시지에 암시적 네이티브 답장 참조를 연결합니다. batched는 수신 턴이 여러 메시지의 디바운스된 배치였을 때만 Discord의 암시적 네이티브 답장 참조를 연결합니다. 이는 모든 단일 메시지 턴이 아니라, 주로 모호하고 짧은 시간에 몰려오는 채팅에 네이티브 답장을 사용하려는 경우 유용합니다.

메시지 ID는 컨텍스트/기록에 노출되므로 에이전트가 특정 메시지를 대상으로 지정할 수 있습니다.

OpenClaw는 임시 메시지를 보내고 텍스트가 도착하는 대로 편집하여 초안 답장을 스트리밍할 수 있습니다. channels.discord.streaming은 off | partial | block | progress(기본값)를 받습니다. progress는 편집 가능한 상태 초안 하나를 유지하고 최종 전달 전까지 도구 진행 상황으로 업데이트합니다. streamMode는 레거시 런타임 별칭입니다. 지속된 설정을 표준 키로 다시 쓰려면 openclaw doctor --fix를 실행하세요.

Discord 미리보기 편집을 비활성화하려면 channels.discord.streaming.mode를 off로 설정하세요. Discord 블록 스트리밍이 명시적으로 활성화된 경우, OpenClaw는 이중 스트리밍을 피하기 위해 미리보기 스트림을 건너뜁니다.

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

• partial은 토큰이 도착하는 대로 단일 미리보기 메시지를 편집합니다.
• block은 초안 크기의 청크를 내보냅니다(draftChunk를 사용해 크기와 분기점을 조정하며, textChunkLimit까지로 제한됨).
• 미디어, 오류, 명시적 답장 최종 메시지는 대기 중인 미리보기 편집을 취소합니다.
• streaming.preview.toolProgress(기본값 true)는 도구/진행 업데이트가 미리보기 메시지를 재사용할지 제어합니다.
• streaming.preview.commandText / streaming.progress.commandText는 압축 진행 줄의 명령/실행 세부 정보를 제어합니다: raw(기본값) 또는 status(도구 레이블만).

압축 진행 줄은 유지하면서 원시 명령/실행 텍스트를 숨기기:

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

미리보기 스트리밍은 텍스트 전용입니다. 미디어 답장은 일반 전달로 대체됩니다. block 스트리밍이 명시적으로 활성화된 경우, OpenClaw는 이중 스트리밍을 피하기 위해 미리보기 스트림을 건너뜁니다.

길드 기록 컨텍스트:

• channels.discord.historyLimit 기본값 20
• 대체값: messages.groupChat.historyLimit
• 0은 비활성화

DM 기록 제어:

• channels.discord.dmHistoryLimit
• channels.discord.dms["<user_id>"].historyLimit

스레드 동작:

• Discord 스레드는 채널 세션으로 라우팅되며, 재정의하지 않는 한 부모 채널 설정을 상속합니다.
• 스레드 세션은 부모 채널의 세션 수준 /model 선택을 모델 전용 대체값으로 상속합니다. 스레드 로컬 /model 선택은 여전히 우선하며, 전사 기록 상속이 활성화되지 않은 한 부모 전사 기록은 복사되지 않습니다.
• channels.discord.thread.inheritParent(기본값 false)는 새 자동 스레드가 부모 전사에서 시드되도록 선택합니다. 계정별 재정의는 channels.discord.accounts.<id>.thread.inheritParent 아래에 있습니다.
• 메시지 도구 반응은 user:<id> DM 대상을 확인할 수 있습니다.
• guilds.<guild>.channels.<channel>.requireMention: false는 답장 단계 활성화 대체 중에도 보존됩니다.

채널 주제는 신뢰할 수 없는 컨텍스트로 주입됩니다. 허용 목록은 누가 에이전트를 트리거할 수 있는지만 제한하며, 전체 보조 컨텍스트 삭제 경계가 아닙니다.

Discord는 스레드를 세션 대상에 바인딩하여 해당 스레드의 후속 메시지가 동일한 세션(하위 에이전트 세션 포함)으로 계속 라우팅되게 할 수 있습니다.

명령:

• /focus <target> 현재/새 스레드를 하위 에이전트/세션 대상에 바인딩
• /unfocus 현재 스레드 바인딩 제거
• /agents 활성 실행 및 바인딩 상태 표시
• /session idle <duration|off> 포커스된 바인딩의 비활성 자동 언포커스 검사/업데이트
• /session max-age <duration|off> 포커스된 바인딩의 엄격한 최대 수명 검사/업데이트

설정:

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

참고:

• session.threadBindings.*는 전역 기본값을 설정합니다.
• channels.discord.threadBindings.*는 Discord 동작을 재정의합니다.
• spawnSessions는 sessions_spawn({ thread: true }) 및 ACP 스레드 생성에 대한 자동 생성/바인딩 스레드를 제어합니다. 기본값: true.
• defaultSpawnContext는 스레드 바인딩 생성의 네이티브 하위 에이전트 컨텍스트를 제어합니다. 기본값: "fork".
• 사용 중단된 spawnSubagentSessions/spawnAcpSessions 키는 openclaw doctor --fix로 마이그레이션됩니다.
• 계정에 대해 스레드 바인딩이 비활성화된 경우, /focus 및 관련 스레드 바인딩 작업을 사용할 수 없습니다.

하위 에이전트, ACP 에이전트, 설정 참조를 참조하세요.

안정적인 "상시 실행" ACP 작업 공간의 경우 Discord 대화를 대상으로 하는 최상위 타입 지정 ACP 바인딩을 설정하세요.

설정 경로:

• type: "acp" 및 match.channel: "discord"가 있는 bindings[]

예:

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

참고:

• /acp spawn codex --bind here는 현재 채널 또는 스레드를 그 자리에서 바인딩하고 향후 메시지를 동일한 ACP 세션에 유지합니다. 스레드 메시지는 부모 채널 바인딩을 상속합니다.
• 바인딩된 채널 또는 스레드에서 /new 및 /reset은 동일한 ACP 세션을 그 자리에서 재설정합니다. 임시 스레드 바인딩은 활성 상태일 때 대상 확인을 재정의할 수 있습니다.
• spawnSessions는 --thread auto|here를 통한 자식 스레드 생성/바인딩을 제한합니다.

바인딩 동작 세부 정보는 ACP 에이전트를 참조하세요.

길드별 반응 알림 모드:

• off
• own(기본값)
• all
• allowlist(guilds.<id>.users 사용)

반응 이벤트는 시스템 이벤트로 변환되어 라우팅된 Discord 세션에 첨부됩니다.

ackReaction은 OpenClaw가 수신 메시지를 처리하는 동안 확인 이모지를 보냅니다.

확인 순서:

• channels.discord.accounts.<accountId>.ackReaction
• channels.discord.ackReaction
• messages.ackReaction
• 에이전트 아이덴티티 이모지 대체값(agents.list[].identity.emoji, 없으면 "👀")

참고:

• Discord는 유니코드 이모지 또는 사용자 지정 이모지 이름을 허용합니다.
• 채널 또는 계정의 반응을 비활성화하려면 ""를 사용하세요.

채널에서 시작된 설정 쓰기는 기본적으로 활성화됩니다.

이는 /config set|unset 흐름에 영향을 줍니다(명령 기능이 활성화된 경우).

비활성화:

{
channels: {
discord: {
  configWrites: false,
},
},
}

channels.discord.proxy를 사용해 Discord Gateway WebSocket 트래픽과 시작 REST 조회(애플리케이션 ID + 허용 목록 확인)를 HTTP(S) 프록시를 통해 라우팅합니다.

{
channels: {
discord: {
  proxy: "http://proxy.example:8080",
},
},
}

계정별 재정의:

{
channels: {
discord: {
  accounts: {
    primary: {
      proxy: "http://proxy.example:8080",
    },
  },
},
},
}

프록시된 메시지를 시스템 멤버 아이덴티티에 매핑하려면 PluralKit 확인을 활성화하세요.

{
channels: {
discord: {
  pluralkit: {
    enabled: true,
    token: "pk_live_...", // optional; needed for private systems
  },
},
},
}

참고:

• 허용 목록은 pk:<memberId>를 사용할 수 있습니다.
• 멤버 표시 이름은 channels.discord.dangerouslyAllowNameMatching: true일 때만 이름/슬러그로 매칭됩니다.
• 조회는 원본 메시지 ID를 사용하며 시간 창으로 제한됩니다.
• 조회에 실패하면 프록시된 메시지는 봇 메시지로 처리되어 allowBots=true가 아닌 한 삭제됩니다.

에이전트가 알려진 Discord 사용자에 대해 결정적 발신 멘션이 필요할 때 mentionAliases를 사용하세요. 키는 앞의 @가 없는 핸들이며, 값은 Discord 사용자 ID입니다. 알 수 없는 핸들, @everyone, @here, Markdown 코드 스팬 안의 멘션은 변경되지 않습니다.

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

상태 또는 활동 필드를 설정하거나 자동 Presence를 활성화하면 Presence 업데이트가 적용됩니다.

상태만 있는 예:

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

활동 예(사용자 지정 상태가 기본 활동 유형):

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

스트리밍 예:

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

활동 유형 맵:

• 0: 플레이 중
• 1: 스트리밍 중(activityUrl 필요)
• 2: 듣는 중
• 3: 시청 중
• 4: 사용자 지정(활동 텍스트를 상태 상태값으로 사용하며, 이모지는 선택 사항)
• 5: 경쟁 중

자동 Presence 예(런타임 상태 신호):

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

자동 상태 표시 기능은 런타임 가용성을 Discord 상태에 매핑합니다. healthy => online, degraded 또는 unknown => idle, exhausted 또는 unavailable => dnd. 선택적 텍스트 재정의:

• autoPresence.healthyText
• autoPresence.degradedText
• autoPresence.exhaustedText ({reason} 플레이스홀더 지원)

Discord는 DM에서 버튼 기반 승인 처리를 지원하며, 선택적으로 원래 채널에 승인 프롬프트를 게시할 수 있습니다.

설정 경로:

• channels.discord.execApprovals.enabled
• channels.discord.execApprovals.approvers (선택 사항. 가능하면 commands.ownerAllowFrom으로 대체)
• channels.discord.execApprovals.target (dm | channel | both, 기본값: dm)
• agentFilter, sessionFilter, cleanupAfterResolve

Discord는 enabled가 설정되지 않았거나 "auto"이고 승인자를 하나 이상 확인할 수 있을 때 기본 exec 승인을 자동으로 활성화합니다. 승인자는 execApprovals.approvers 또는 commands.ownerAllowFrom에서 확인됩니다. Discord는 채널 allowFrom, 레거시 dm.allowFrom, 또는 직접 메시지 defaultTo에서 exec 승인자를 추론하지 않습니다. Discord를 기본 승인 클라이언트로 명시적으로 비활성화하려면 enabled: false를 설정하세요.

/diagnostics 및 /export-trajectory 같은 민감한 소유자 전용 그룹 명령의 경우 OpenClaw는 승인 프롬프트와 최종 결과를 비공개로 보냅니다. 호출한 소유자에게 Discord 소유자 경로가 있으면 먼저 Discord DM을 시도합니다. 사용할 수 없으면 Telegram 같은 commands.ownerAllowFrom의 첫 번째 사용 가능한 소유자 경로로 대체합니다.

target이 channel 또는 both이면 승인 프롬프트가 채널에 표시됩니다. 확인된 승인자만 버튼을 사용할 수 있으며, 다른 사용자는 임시 거부 메시지를 받습니다. 승인 프롬프트에는 명령 텍스트가 포함되므로 신뢰할 수 있는 채널에서만 채널 전송을 활성화하세요. 세션 키에서 채널 ID를 파생할 수 없으면 OpenClaw는 DM 전송으로 대체합니다.

Discord는 다른 채팅 채널에서 사용하는 공유 승인 버튼도 렌더링합니다. 기본 Discord 어댑터는 주로 승인자 DM 라우팅과 채널 팬아웃을 추가합니다. 이러한 버튼이 있으면 기본 승인 UX입니다. OpenClaw는 도구 결과가 채팅 승인을 사용할 수 없다고 하거나 수동 승인이 유일한 경로라고 말할 때만 수동 /approve 명령을 포함해야 합니다. Discord 기본 승인 런타임이 활성 상태가 아니면 OpenClaw는 로컬 결정적 /approve <id> <decision> 프롬프트를 계속 표시합니다. 런타임이 활성 상태이지만 기본 카드를 어떤 대상에도 전달할 수 없으면 OpenClaw는 보류 중인 승인에서 정확한 /approve 명령이 포함된 동일 채팅 대체 알림을 보냅니다.

Gateway 인증 및 승인 확인은 공유 Gateway 클라이언트 계약을 따릅니다(plugin: ID는 plugin.approval.resolve를 통해 확인되고, 다른 ID는 exec.approval.resolve를 통해 확인됨). 승인은 기본적으로 30분 후 만료됩니다.

Exec 승인을 참고하세요.

• Message Content Intent 활성화
• 사용자/멤버 확인에 의존하는 경우 Server Members Intent 활성화
• intents를 변경한 후 gateway 재시작

• groupPolicy 확인
• channels.discord.guilds 아래의 guild 허용 목록 확인
• guild channels 맵이 있으면 나열된 채널만 허용됨
• requireMention 동작과 멘션 패턴 확인

유용한 확인:

openclaw doctor
openclaw channels status --probe
openclaw logs --follow

일반적인 원인:

• 일치하는 guild/channel 허용 목록 없이 groupPolicy="allowlist" 사용
• requireMention이 잘못된 위치에 설정됨(channels.discord.guilds 또는 채널 항목 아래에 있어야 함)
• 발신자가 guild/channel users 허용 목록에 의해 차단됨

일반적인 로그:

• Slow listener detected ...
• stuck session: sessionKey=agent:...:discord:... state=processing ...

Discord gateway 큐 조정값:

• 단일 계정: channels.discord.eventQueue.listenerTimeout
• 다중 계정: channels.discord.accounts.<accountId>.eventQueue.listenerTimeout
• 이것은 에이전트 턴 수명이 아니라 Discord gateway listener 작업만 제어합니다.

Discord는 큐에 들어간 에이전트 턴에 채널 소유 timeout을 적용하지 않습니다. 메시지 listener는 즉시 넘겨주며, 큐에 들어간 Discord 실행은 session/tool/runtime lifecycle이 완료되거나 작업이 중단될 때까지 세션별 순서를 보존합니다.

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

OpenClaw는 연결하기 전에 Discord /gateway/bot 메타데이터를 가져옵니다. 일시적인 실패는 Discord의 기본 Gateway URL로 폴백하며 로그에서 비율 제한됩니다.

메타데이터 시간 초과 조정값:

• 단일 계정: channels.discord.gatewayInfoTimeoutMs
• 다중 계정: channels.discord.accounts.<accountId>.gatewayInfoTimeoutMs
• 구성이 설정되지 않았을 때의 env 폴백: OPENCLAW_DISCORD_GATEWAY_INFO_TIMEOUT_MS
• 기본값: 30000(30초), 최대: 120000

OpenClaw는 시작 중과 런타임 재연결 후 Discord의 Gateway READY 이벤트를 기다립니다. 시작 시차 적용을 사용하는 다중 계정 설정은 기본값보다 더 긴 시작 READY 대기 시간이 필요할 수 있습니다.

READY 시간 초과 조정값:

• 시작 단일 계정: channels.discord.gatewayReadyTimeoutMs
• 시작 다중 계정: channels.discord.accounts.<accountId>.gatewayReadyTimeoutMs
• 구성이 설정되지 않았을 때의 시작 env 폴백: OPENCLAW_DISCORD_READY_TIMEOUT_MS
• 시작 기본값: 15000(15초), 최대: 120000
• 런타임 단일 계정: channels.discord.gatewayRuntimeReadyTimeoutMs
• 런타임 다중 계정: channels.discord.accounts.<accountId>.gatewayRuntimeReadyTimeoutMs
• 구성이 설정되지 않았을 때의 런타임 env 폴백: OPENCLAW_DISCORD_RUNTIME_READY_TIMEOUT_MS
• 런타임 기본값: 30000(30초), 최대: 120000

channels status --probe 권한 검사는 숫자 채널 ID에서만 작동합니다.

slug 키를 사용하는 경우에도 런타임 매칭은 계속 작동할 수 있지만, probe가 권한을 완전히 검증할 수는 없습니다.

• DM 비활성화됨: channels.discord.dm.enabled=false
• DM 정책 비활성화됨: channels.discord.dmPolicy="disabled"(레거시: channels.discord.dm.policy)
• pairing 모드에서 페어링 승인을 기다리는 중

기본적으로 bot이 작성한 메시지는 무시됩니다.

channels.discord.allowBots=true를 설정한 경우, 루프 동작을 피하려면 엄격한 멘션 및 허용 목록 규칙을 사용하세요. bot을 멘션하는 bot 메시지만 허용하려면 channels.discord.allowBots="mentions"를 선호하세요.

{
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 음성 수신 복구 로직이 포함되도록 OpenClaw를 최신 상태로 유지하세요(openclaw update)
• channels.discord.voice.daveEncryption=true(기본값)인지 확인하세요
• channels.discord.voice.decryptionFailureTolerance=24(업스트림 기본값)에서 시작하고 필요한 경우에만 조정하세요
• 다음 로그를 확인하세요:
  • discord voice: DAVE decrypt failures detected
  • discord voice: repeated decrypt failures; attempting rejoin
• 자동 재참가 후에도 실패가 계속되면 로그를 수집하고 discord.js #11419 및 discord.js #11449의 업스트림 DAVE 수신 기록과 비교하세요