Discord

O Discord oferece suporte a tags de resposta na saída do agente:

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

Controlado por channels.discord.replyToMode:

• off (padrão)
• first
• all
• batched

Observação: off desabilita o encadeamento implícito de respostas. Tags explícitas [[reply_to_*]] ainda são respeitadas. first sempre anexa a referência implícita de resposta nativa à primeira mensagem de saída do Discord no turno. batched só anexa a referência implícita de resposta nativa do Discord quando o turno de entrada foi um lote com debounce de várias mensagens. Isso é útil quando você quer respostas nativas principalmente para conversas ambíguas e com rajadas de mensagens, não para cada turno de mensagem única.

IDs de mensagem são expostos no contexto/histórico para que agentes possam direcionar mensagens específicas.

O OpenClaw pode transmitir rascunhos de respostas enviando uma mensagem temporária e editando-a conforme o texto chega. channels.discord.streaming aceita off | partial | block | progress (padrão). progress mantém um rascunho de status editável e o atualiza com o progresso das ferramentas até a entrega final; streamMode é um alias legado de runtime. Execute openclaw doctor --fix para reescrever a configuração persistida para a chave canônica.

Defina channels.discord.streaming.mode como off para desabilitar edições de prévia no Discord. Se a transmissão em bloco do Discord estiver explicitamente habilitada, o OpenClaw ignora o fluxo de prévia para evitar transmissão duplicada.

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

• partial edita uma única mensagem de prévia conforme os tokens chegam.
• block emite partes do tamanho de rascunho (use draftChunk para ajustar tamanho e pontos de quebra, limitado a textChunkLimit).
• Finais com mídia, erro e resposta explícita cancelam edições de prévia pendentes.
• streaming.preview.toolProgress (padrão true) controla se atualizações de ferramenta/progresso reutilizam a mensagem de prévia.
• streaming.preview.commandText / streaming.progress.commandText controla detalhes de comando/execução em linhas de progresso compactas: raw (padrão) ou status (somente o rótulo da ferramenta).

Oculte texto bruto de comando/execução mantendo linhas de progresso compactas:

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

A transmissão de prévia é somente texto; respostas com mídia voltam para a entrega normal. Quando a transmissão block está explicitamente habilitada, o OpenClaw ignora o fluxo de prévia para evitar transmissão duplicada.

Contexto de histórico de guilda:

• padrão de channels.discord.historyLimit: 20
• fallback: messages.groupChat.historyLimit
• 0 desabilita

Controles de histórico de DM:

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

Comportamento de thread:

• Threads do Discord são roteadas como sessões de canal e herdam a configuração do canal pai, a menos que sejam substituídas.
• Sessões de thread herdam a seleção /model em nível de sessão do canal pai como fallback somente de modelo; seleções /model locais da thread ainda têm precedência, e o histórico da transcrição do pai não é copiado a menos que a herança de transcrição esteja habilitada.
• channels.discord.thread.inheritParent (padrão false) faz novas auto-threads começarem com dados da transcrição pai. Substituições por conta ficam em channels.discord.accounts.<id>.thread.inheritParent.
• Reações da ferramenta de mensagens podem resolver destinos de DM user:<id>.
• guilds.<guild>.channels.<channel>.requireMention: false é preservado durante o fallback de ativação na etapa de resposta.

Tópicos de canal são injetados como contexto não confiável. Listas de permissões controlam quem pode acionar o agente, não são um limite completo de redação de contexto suplementar.

O Discord pode vincular uma thread a um destino de sessão para que mensagens subsequentes nessa thread continuem sendo roteadas para a mesma sessão (incluindo sessões de subagente).

Comandos:

• /focus <target> vincula a thread atual/nova a um destino de subagente/sessão
• /unfocus remove o vínculo da thread atual
• /agents mostra execuções ativas e o estado de vínculo
• /session idle <duration|off> inspeciona/atualiza o auto-unfocus por inatividade para vínculos em foco
• /session max-age <duration|off> inspeciona/atualiza a idade máxima rígida para vínculos em foco

Configuração:

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

Observações:

• session.threadBindings.* define padrões globais.
• channels.discord.threadBindings.* substitui o comportamento do Discord.
• spawnSessions controla a criação/vinculação automática de threads para sessions_spawn({ thread: true }) e criações de thread ACP. Padrão: true.
• defaultSpawnContext controla o contexto nativo de subagente para criações vinculadas a threads. Padrão: "fork".
• Chaves obsoletas spawnSubagentSessions/spawnAcpSessions são migradas por openclaw doctor --fix.
• Se vínculos de thread estiverem desabilitados para uma conta, /focus e operações relacionadas de vínculo de thread ficam indisponíveis.

Consulte Subagentes, Agentes ACP e Referência de configuração.

Para workspaces ACP estáveis e "sempre ativos", configure vínculos ACP tipados de nível superior direcionados a conversas do Discord.

Caminho de configuração:

• bindings[] com type: "acp" e match.channel: "discord"

Exemplo:

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

Observações:

• /acp spawn codex --bind here vincula o canal ou a thread atual no local e mantém mensagens futuras na mesma sessão ACP. Mensagens de thread herdam o vínculo do canal pai.
• Em um canal ou thread vinculado, /new e /reset redefinem a mesma sessão ACP no local. Vínculos temporários de thread podem substituir a resolução de destino enquanto ativos.
• spawnSessions controla a criação/vinculação de threads filhas por --thread auto|here.

Consulte Agentes ACP para detalhes do comportamento de vínculo.

Modo de notificação de reação por guilda:

• off
• own (padrão)
• all
• allowlist (usa guilds.<id>.users)

Eventos de reação são transformados em eventos do sistema e anexados à sessão roteada do Discord.

ackReaction envia um emoji de confirmação enquanto o OpenClaw processa uma mensagem de entrada.

Ordem de resolução:

• channels.discord.accounts.<accountId>.ackReaction
• channels.discord.ackReaction
• messages.ackReaction
• fallback para emoji da identidade do agente (agents.list[].identity.emoji; caso contrário, "👀")

Observações:

• O Discord aceita emoji unicode ou nomes de emoji personalizados.
• Use "" para desabilitar a reação para um canal ou conta.

Gravações de configuração iniciadas pelo canal são habilitadas por padrão.

Isso afeta fluxos /config set|unset (quando recursos de comando estão habilitados).

Desabilitar:

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

Roteie o tráfego WebSocket do Gateway do Discord e consultas REST de inicialização (ID do aplicativo + resolução de lista de permissões) por um proxy HTTP(S) com channels.discord.proxy.

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

Substituição por conta:

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

Habilite a resolução do PluralKit para mapear mensagens com proxy para a identidade de membro do sistema:

{
channels: {
discord: {
  pluralkit: {
    enabled: true,
    token: "pk_live_...", // opcional; necessário para sistemas privados
  },
},
},
}

Observações:

• listas de permissões podem usar pk:<memberId>
• nomes de exibição de membros são correspondidos por nome/slug somente quando channels.discord.dangerouslyAllowNameMatching: true
• consultas usam o ID da mensagem original e são restritas por janela de tempo
• se a consulta falhar, mensagens com proxy são tratadas como mensagens de bot e descartadas, a menos que allowBots=true

Use mentionAliases quando agentes precisam de menções de saída determinísticas para usuários conhecidos do Discord. As chaves são identificadores sem o @ inicial; os valores são IDs de usuário do Discord. Identificadores desconhecidos, @everyone, @here e menções dentro de spans de código Markdown são deixados inalterados.

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

Atualizações de presença são aplicadas quando você define um campo de status ou atividade, ou quando habilita presença automática.

Exemplo somente com status:

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

Exemplo de atividade (status personalizado é o tipo de atividade padrão):

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

Exemplo de streaming:

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

Mapa de tipos de atividade:

• 0: Jogando
• 1: Streaming (requer activityUrl)
• 2: Ouvindo
• 3: Assistindo
• 4: Personalizado (usa o texto da atividade como estado de status; emoji é opcional)
• 5: Competindo

Exemplo de presença automática (sinal de integridade em runtime):

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

A presença automática mapeia a disponibilidade em tempo de execução para o status do Discord: íntegro => online, degradado ou desconhecido => inativo, esgotado ou indisponível => dnd. Substituições opcionais de texto:

• autoPresence.healthyText
• autoPresence.degradedText
• autoPresence.exhaustedText (compatível com o placeholder {reason})

O Discord oferece suporte ao tratamento de aprovações por botões em DMs e pode, opcionalmente, publicar solicitações de aprovação no canal de origem.

Caminho de configuração:

• channels.discord.execApprovals.enabled
• channels.discord.execApprovals.approvers (opcional; recorre a commands.ownerAllowFrom quando possível)
• channels.discord.execApprovals.target (dm | channel | both, padrão: dm)
• agentFilter, sessionFilter, cleanupAfterResolve

O Discord ativa automaticamente aprovações nativas de execução quando enabled não está definido ou é "auto" e pelo menos um aprovador pode ser resolvido, seja de execApprovals.approvers ou de commands.ownerAllowFrom. O Discord não infere aprovadores de execução a partir de allowFrom do canal, dm.allowFrom legado ou defaultTo de mensagem direta. Defina enabled: false para desativar explicitamente o Discord como cliente de aprovação nativo.

Para comandos de grupo confidenciais e restritos ao proprietário, como /diagnostics e /export-trajectory, o OpenClaw envia solicitações de aprovação e resultados finais de forma privada. Ele tenta primeiro uma DM do Discord quando o proprietário que invocou o comando tem uma rota de proprietário do Discord; se isso não estiver disponível, recorre à primeira rota de proprietário disponível em commands.ownerAllowFrom, como Telegram.

Quando target é channel ou both, a solicitação de aprovação fica visível no canal. Somente aprovadores resolvidos podem usar os botões; outros usuários recebem uma negação efêmera. As solicitações de aprovação incluem o texto do comando, portanto só habilite a entrega no canal em canais confiáveis. Se o ID do canal não puder ser derivado da chave da sessão, o OpenClaw recorre à entrega por DM.

O Discord também renderiza os botões de aprovação compartilhados usados por outros canais de chat. O adaptador nativo do Discord principalmente adiciona roteamento de DM para aprovadores e distribuição para canais. Quando esses botões estão presentes, eles são a principal UX de aprovação; o OpenClaw só deve incluir um comando manual /approve quando o resultado da ferramenta disser que aprovações por chat estão indisponíveis ou que a aprovação manual é o único caminho. Se o runtime de aprovação nativo do Discord não estiver ativo, o OpenClaw mantém visível a solicitação determinística local /approve <id> <decision>. Se o runtime estiver ativo, mas um cartão nativo não puder ser entregue a nenhum destino, o OpenClaw envia um aviso de fallback no mesmo chat com o comando /approve exato da aprovação pendente.

A autenticação do Gateway e a resolução de aprovação seguem o contrato compartilhado do cliente Gateway (IDs plugin: são resolvidos por plugin.approval.resolve; outros IDs por exec.approval.resolve). As aprovações expiram após 30 minutos por padrão.

Consulte Aprovações de execução.

• habilite Message Content Intent
• habilite Server Members Intent quando você depende da resolução de usuário/membro
• reinicie o gateway após alterar intents

• verifique groupPolicy
• verifique a lista de permissão de guild em channels.discord.guilds
• se o mapa channels da guild existir, somente os canais listados serão permitidos
• verifique o comportamento de requireMention e os padrões de menção

Verificações úteis:

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

Causas comuns:

• groupPolicy="allowlist" sem uma allowlist de guild/canal correspondente
• requireMention configurado no lugar errado (deve ficar em channels.discord.guilds ou na entrada do canal)
• remetente bloqueado pela allowlist de users da guild/canal

Logs típicos:

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

Ajustes da fila do gateway do Discord:

• conta única: channels.discord.eventQueue.listenerTimeout
• várias contas: channels.discord.accounts.<accountId>.eventQueue.listenerTimeout
• isso controla apenas o trabalho do listener do gateway do Discord, não a duração do turno do agente

O Discord não aplica um timeout próprio do canal a turnos de agente enfileirados. Listeners de mensagens fazem o repasse imediatamente, e execuções do Discord enfileiradas preservam a ordem por sessão até que o ciclo de vida da sessão/ferramenta/runtime conclua ou aborte o trabalho.

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

O OpenClaw busca os metadados /gateway/bot do Discord antes de conectar. Falhas transitórias usam a URL padrão do gateway do Discord como fallback e têm limitação de frequência nos logs.

Ajustes de timeout de metadados:

• conta única: channels.discord.gatewayInfoTimeoutMs
• várias contas: channels.discord.accounts.<accountId>.gatewayInfoTimeoutMs
• fallback de env quando a configuração não está definida: OPENCLAW_DISCORD_GATEWAY_INFO_TIMEOUT_MS
• padrão: 30000 (30 segundos), máximo: 120000

O OpenClaw aguarda o evento READY do gateway do Discord durante a inicialização e depois de reconexões do runtime. Configurações com várias contas e escalonamento de inicialização podem precisar de uma janela READY de inicialização mais longa que o padrão.

Ajustes de timeout de READY:

• inicialização com conta única: channels.discord.gatewayReadyTimeoutMs
• inicialização com várias contas: channels.discord.accounts.<accountId>.gatewayReadyTimeoutMs
• fallback de env de inicialização quando a configuração não está definida: OPENCLAW_DISCORD_READY_TIMEOUT_MS
• padrão de inicialização: 15000 (15 segundos), máximo: 120000
• runtime com conta única: channels.discord.gatewayRuntimeReadyTimeoutMs
• runtime com várias contas: channels.discord.accounts.<accountId>.gatewayRuntimeReadyTimeoutMs
• fallback de env de runtime quando a configuração não está definida: OPENCLAW_DISCORD_RUNTIME_READY_TIMEOUT_MS
• padrão de runtime: 30000 (30 segundos), máximo: 120000

As verificações de permissão de channels status --probe funcionam apenas para IDs numéricos de canal.

Se você usar chaves de slug, a correspondência em runtime ainda pode funcionar, mas a probe não consegue verificar totalmente as permissões.

• DM desativada: channels.discord.dm.enabled=false
• política de DM desativada: channels.discord.dmPolicy="disabled" (legado: channels.discord.dm.policy)
• aguardando aprovação de pareamento no modo pairing

Por padrão, mensagens criadas por bots são ignoradas.

Se você definir channels.discord.allowBots=true, use regras estritas de menção e allowlist para evitar comportamento de loop. Prefira channels.discord.allowBots="mentions" para aceitar apenas mensagens de bots que mencionem o bot.

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

• mantenha o OpenClaw atualizado (openclaw update) para que a lógica de recuperação de recebimento de voz do Discord esteja presente
• confirme channels.discord.voice.daveEncryption=true (padrão)
• comece com channels.discord.voice.decryptionFailureTolerance=24 (padrão upstream) e ajuste apenas se necessário
• observe os logs para:
  • discord voice: DAVE decrypt failures detected
  • discord voice: repeated decrypt failures; attempting rejoin
• se as falhas continuarem após a reentrada automática, colete logs e compare com o histórico upstream de recebimento do DAVE em discord.js #11419 e discord.js #11449