OpenClaw

Canal Nextcloud Talk do OpenClaw

Empresarial
Médio

Conecte o OpenClaw ao Nextcloud Talk, a plataforma de comunicação empresarial focada em privacidade integrada ao ecossistema Nextcloud. A integração utiliza uma arquitetura de bot baseada em webhooks — o Nextcloud Talk envia eventos de mensagem ao seu Gateway via webhooks, e o bot responde por meio da API REST do Talk. Isso permite que seu assistente de IA participe de mensagens diretas, conversas em salas e reaja a mensagens com emoji, tudo dentro do seu ambiente Nextcloud auto-hospedado.

Info rápida
DificuldadeMédio
CategoriaEmpresarial
Recursos suportados4 / 6

Nextcloud Talk Recursos suportados

Mensagens de texto

Suportado

Mídia e arquivos

Suportado

Reações

Suportado

Threads

Não suportado

Mensagens de voz

Não suportado

Chat em grupo

Suportado

Nextcloud Talk Pré-requisitos

  • Um servidor Nextcloud (v27.1+) com acesso de administrador e o aplicativo Talk instalado
  • Um segredo compartilhado (40-128 caracteres) para validação de assinatura de webhook
  • O endpoint de webhook do Gateway acessível a partir do servidor Nextcloud (URL pública ou rede interna)
  • OpenClaw Gateway instalado e em execução
  • O plugin Nextcloud Talk instalado via 'openclaw plugins install @openclaw/nextcloud-talk'

Nextcloud Talk Configuração rápida

1

Instalar o plugin Nextcloud Talk

Execute 'openclaw plugins install @openclaw/nextcloud-talk' para adicionar suporte ao Nextcloud Talk no seu Gateway.

2

Registrar o bot no seu servidor Nextcloud

Acesse seu servidor Nextcloud via SSH e execute o comando OCC: ./occ talk:bot:install "OpenClaw" "<shared-secret>" "<webhook-url>" --feature reaction. Substitua <shared-secret> por um segredo forte de 40+ caracteres, e <webhook-url> pelo endpoint de webhook publicamente acessível do Gateway (ex.: https://gateway.example.com:8788/webhook).

3

Ativar o bot e configurar

No Nextcloud Talk, vá até as configurações da sala e ative o bot OpenClaw. Em seguida, adicione a configuração do canal em ~/.openclaw/openclaw.json com sua baseUrl e botSecret. Inicie o Gateway com 'openclaw start' e envie uma mensagem na sala para verificar a conexão.

Nextcloud Talk Exemplo de configuração

config.json
{
  "channels": {
    "nextcloud-talk": {
      "enabled": true,
      "baseUrl": "https://nextcloud.example.com",
      "botSecret": "your-shared-secret-min-40-chars",
      "dmPolicy": "pairing"
    }
  }
}

Nextcloud Talk Documentação Detalhada

Visão Geral da Arquitetura

O OpenClaw integra-se ao Nextcloud Talk por meio da Talk Bot API (disponível desde o Nextcloud 27.1). A arquitetura é baseada em webhooks: 1. O bot é registrado no servidor Nextcloud usando a ferramenta de linha de comando OCC com um segredo compartilhado e URL de webhook. 2. Quando uma mensagem é postada em uma sala onde o bot está ativado, o Nextcloud Talk envia um HTTP POST para a URL de webhook configurada com o payload da mensagem, assinado usando o segredo compartilhado. 3. O Gateway verifica a assinatura do webhook, processa a mensagem por meio do seu agente de IA e posta a resposta de volta na conversa usando a API REST do Talk. Este design significa que o Gateway deve expor um endpoint de webhook acessível ao servidor Nextcloud. O listener de webhook é executado na porta 8788 por padrão e pode ser personalizado por meio das opções de configuração webhookPort e webhookHost.
A URL do webhook deve ser acessível a partir do servidor Nextcloud. Para desenvolvimento local, use um serviço de túnel como o ngrok.
Cada instalação de bot gera um hash de URL único (bot-<hash>) usado como ID do ator para mensagens.

Registro do Bot via OCC

Os bots do Nextcloud Talk são registrados no servidor usando comandos OCC (Nextcloud Command Console). Esta é uma operação do lado do servidor que requer acesso SSH ou console. Para instalar o bot: ./occ talk:bot:install "OpenClaw" "<secret>" "<webhook-url>" --feature reaction Parâmetros: • name (obrigatório): Nome de exibição mostrado como autor da mensagem (1-64 caracteres) • secret (obrigatório): Segredo compartilhado para validação de assinatura do webhook (40-128 caracteres) • url (obrigatório): URL do endpoint de webhook do seu Gateway • --feature: Capacidades do bot — use 'reaction' para habilitar reações com emoji • --no-setup: Impede que moderadores alternem o bot por sala Outros comandos OCC úteis: • talk:bot:list — Listar todos os bots instalados • talk:bot:remove <bot-id> — Remover um bot de conversas específicas • talk:bot:setup <bot-id> <token> — Ativar um bot em uma conversa • talk:bot:state <bot-id> <state> — Alterar o estado do bot (0=desativado, 1=ativado, 2=no-setup) • talk:bot:uninstall <id> — Remover completamente um bot do servidor
Terminal
./occ talk:bot:install "OpenClaw" "a]72@Bz&V!LKMO*xhQib7p^E%yzGMG(8a7Bp*x6o" "https://gateway.example.com:8788/webhook" --feature reaction
Gere um segredo compartilhado forte usando: openssl rand -base64 48
A flag --feature reaction é recomendada para permitir que o bot reaja a mensagens com emoji.

Políticas de DM

As políticas de Mensagem Direta (DM) controlam como o bot lida com conversas privadas individuais. **pairing (padrão)** — Remetentes desconhecidos recebem um código de pareamento que deve ser verificado antes que o bot responda. Este é o modo mais seguro, exigindo autorização explícita do usuário. **open** — Qualquer usuário que enviar mensagem ao bot recebe uma resposta. Requer configurar allowFrom como ["*"]. **disabled** — O bot não responde a mensagens diretas. Observação: Bots do Nextcloud Talk não podem iniciar DMs — o usuário deve enviar mensagem ao bot primeiro. O campo allowFrom corresponde aos IDs de usuário do Nextcloud (não aos nomes de exibição).
openclaw.json
{
  "channels": {
    "nextcloud-talk": {
      "dmPolicy": "pairing",
      "allowFrom": ["user-id-1", "user-id-2"]
    }
  }
}
Bots não podem iniciar mensagens diretas no Nextcloud Talk. Os usuários devem entrar em contato com o bot primeiro para iniciar uma conversa.

Configuração de Salas

As políticas de salas (chat em grupo) controlam em quais conversas o bot participa e como ele é acionado. **allowlist (padrão)** — O bot só responde em salas onde foi explicitamente ativado por um moderador nas configurações da sala. A configuração por sala pode ser personalizada usando o objeto rooms. Cada sala é identificada pelo seu token de conversa e pode ter configurações independentes: • requireMention — Quando verdadeiro, o bot só responde quando é @mencionado (comportamento padrão em salas) • Salas não listadas na configuração usam as configurações padrão da sala Para encontrar o token de uma sala, veja a URL ao visualizar a sala no Nextcloud Talk (ex.: https://nextcloud.example.com/call/<token>).
openclaw.json
{
  "channels": {
    "nextcloud-talk": {
      "groupPolicy": "allowlist",
      "rooms": {
        "abc123token": {
          "requireMention": true
        },
        "def456token": {
          "requireMention": false
        }
      }
    }
  }
}
Um moderador da sala deve ativar o bot nas configurações da sala antes que ele possa receber mensagens.
Use requireMention: true para salas movimentadas a fim de evitar que o bot responda a todas as mensagens.

Credenciais de API para Detecção de Sala

Por padrão, o payload do webhook do Nextcloud Talk não diferencia mensagens diretas de mensagens de sala. Para habilitar a detecção precisa do tipo de sala, você pode fornecer credenciais de API. Quando apiUser e apiPassword estão configurados, o Gateway faz uma chamada de API adicional para determinar se uma mensagem recebida é de uma DM ou de uma conversa em sala. Isso permite que o bot aplique políticas diferentes (dmPolicy vs groupPolicy) corretamente. Sem credenciais de API, o bot trata todas as mensagens de acordo com uma política unificada, o que pode ser suficiente para implantações simples.
openclaw.json
{
  "channels": {
    "nextcloud-talk": {
      "apiUser": "bot-service-account",
      "apiPassword": "service-account-password",
      "apiPasswordFile": "/run/secrets/nc-api-password"
    }
  }
}
Crie uma conta de usuário dedicada no Nextcloud para as credenciais de API em vez de usar uma conta de administrador.
Use apiPasswordFile para carregar a senha de um arquivo (ex.: Docker secret) em vez de armazená-la na configuração.
Sem credenciais de API, o bot não consegue distinguir DMs de mensagens de sala. Isso pode fazer com que políticas exclusivas de DM não funcionem corretamente.

Configuração de Webhook

O Gateway inicia um servidor HTTP integrado para receber eventos de webhook do Nextcloud Talk. A configuração do listener de webhook controla como e onde o servidor escuta. **webhookPort** (padrão: 8788) — A porta do servidor HTTP de webhook. **webhookHost** (padrão: 0.0.0.0) — A interface para vincular. Use 0.0.0.0 para escutar em todas as interfaces ou 127.0.0.1 apenas para localhost. **webhookPath** — Caminho de URL personalizado para o endpoint de webhook. **webhookPublicUrl** — A URL pública completa que o Nextcloud deve usar para alcançar o webhook. Necessária quando atrás de um proxy reverso ou NAT. A URL de webhook fornecida durante a instalação do bot (comando OCC) deve corresponder à URL pública que resolve para este listener.
openclaw.json
{
  "channels": {
    "nextcloud-talk": {
      "webhookPort": 8788,
      "webhookHost": "0.0.0.0",
      "webhookPath": "/webhook",
      "webhookPublicUrl": "https://gateway.example.com:8788/webhook"
    }
  }
}
Se estiver executando atrás de um proxy reverso, defina webhookPublicUrl como a URL acessível externamente.
Certifique-se de que seu firewall permita conexões de entrada na porta de webhook a partir do servidor Nextcloud.

Tratamento de Mensagens e Streaming

O OpenClaw oferece controle refinado sobre como as mensagens são fragmentadas e entregues ao Nextcloud Talk. **textChunkLimit** — Contagem máxima de caracteres por fragmento de mensagem. O Nextcloud Talk suporta mensagens longas, mas a fragmentação pode melhorar a legibilidade para respostas longas de IA. **chunkMode** — Controla como o texto é dividido: 'length' divide no limite de caracteres, 'newline' divide nos limites de parágrafo para quebras mais naturais. **blockStreaming** — Quando ativado, o bot aguarda a resposta completa da IA antes de enviar, em vez de transmitir respostas parciais. **blockStreamingCoalesce** — Quando o block streaming está ativado, combina a resposta final em uma única mensagem em vez de múltiplos fragmentos. **mediaMaxMb** — Tamanho máximo de arquivo (em MB) para anexos de mídia. Observe que o Nextcloud Talk transmite mídia como URLs em vez de uploads diretos de arquivos.
openclaw.json
{
  "channels": {
    "nextcloud-talk": {
      "textChunkLimit": 4000,
      "chunkMode": "newline",
      "blockStreaming": true,
      "blockStreamingCoalesce": true,
      "mediaMaxMb": 10
    }
  }
}
Use blockStreaming: true para respostas mais limpas em salas onde múltiplos usuários estão ativos.
Mídia é compartilhada como URLs no Nextcloud Talk — o bot não pode fazer upload de arquivos diretamente.

Histórico de Conversas

Controle quantas mensagens anteriores são incluídas como contexto quando o agente de IA processa uma nova mensagem. **historyLimit** — Número máximo de mensagens anteriores a incluir para conversas em sala. **dmHistoryLimit** — Número máximo de mensagens anteriores a incluir para conversas em mensagens diretas. Pode ser definido independentemente do limite de histórico da sala. Substituições por DM também são suportadas, permitindo configurar diferentes limites de histórico para usuários específicos. Um limite de histórico mais alto fornece mais contexto para a IA, mas aumenta o uso de tokens e o tempo de processamento.
openclaw.json
{
  "channels": {
    "nextcloud-talk": {
      "historyLimit": 20,
      "dmHistoryLimit": 50
    }
  }
}

Suporte a Reações

O Nextcloud Talk suporta reações com emoji em mensagens, e o bot OpenClaw pode tanto ler quanto adicionar reações. Para habilitar o suporte a reações, o bot deve ser registrado com a flag --feature reaction durante a instalação via OCC. Uma vez habilitado, o agente de IA pode reagir a mensagens de usuários com emoji para fornecer confirmação ou feedback. Reações são uma forma leve do bot interagir sem postar respostas de texto completas — por exemplo, reagindo com um emoji de marca de verificação para confirmar uma tarefa concluída. A API de Reações do Nextcloud Talk (disponível desde a capacidade bots-v1) cuida da mecânica subjacente de adicionar e remover reações.
A flag --feature reaction deve ser definida durante a instalação do bot para que as reações funcionem.
Reações podem ser usadas como um mecanismo de confirmação não intrusivo em salas movimentadas.

Segurança e Assinatura de Webhook

Todos os payloads de webhook do Nextcloud Talk são assinados usando o segredo compartilhado configurado durante a instalação do bot. O Gateway verifica cada assinatura para garantir autenticidade e integridade. O mecanismo de assinatura usa HMAC-SHA256: 1. O Nextcloud calcula um hash HMAC-SHA256 do corpo do payload do webhook usando o segredo compartilhado. 2. A assinatura é incluída nos cabeçalhos HTTP da requisição de webhook. 3. O Gateway calcula independentemente o hash e o compara com a assinatura recebida. 4. Se as assinaturas não corresponderem, a requisição é rejeitada. Isso garante que apenas requisições legítimas do seu servidor Nextcloud sejam processadas. Mantenha o segredo compartilhado confidencial e faça a rotação periodicamente reinstalando o bot com um novo segredo.
Use um segredo criptograficamente forte: openssl rand -base64 48 gera um valor adequado.
Armazene o segredo usando botSecretFile para evitar registrá-lo no controle de versão.
Nunca exponha o segredo compartilhado em repositórios públicos ou logs. Use variáveis de ambiente ou arquivos de segredo para implantações em produção.

Nextcloud Talk Referência de Configuração

enabled
Type: booleanDefault: true

Ativar ou desativar o canal Nextcloud Talk

baseUrl
Type: stringDefault: ""

URL completa do seu servidor Nextcloud (ex.: https://nextcloud.example.com)

botSecret
Type: stringDefault: ""

Segredo compartilhado usado para validação de assinatura do webhook (deve corresponder ao segredo da instalação OCC)

botSecretFile
Type: stringDefault: ""

Caminho para um arquivo contendo o segredo compartilhado (alternativa ao botSecret inline)

apiUser
Type: stringDefault: ""

Nome de usuário Nextcloud para chamadas de API (usado para detecção do tipo de sala)

apiPassword
Type: stringDefault: ""

Senha da conta de usuário da API

apiPasswordFile
Type: stringDefault: ""

Caminho para um arquivo contendo a senha da API (alternativa ao apiPassword inline)

dmPolicy
Type: stringDefault: "pairing"

Política de acesso a DM: 'pairing' (código de verificação), 'open' (qualquer usuário) ou 'disabled' (sem DMs)

allowFrom
Type: string[]Default: []

IDs de usuário Nextcloud autorizados a enviar DM ao bot (use ["*"] para acesso aberto)

groupPolicy
Type: stringDefault: "allowlist"

Política de acesso a salas: 'allowlist' (somente salas ativadas por moderadores)

webhookPort
Type: numberDefault: 8788

Porta do servidor HTTP de webhook integrado

webhookHost
Type: stringDefault: "0.0.0.0"

Interface para vincular o servidor de webhook

webhookPath
Type: stringDefault: "/webhook"

Caminho da URL para o endpoint de webhook

webhookPublicUrl
Type: stringDefault: ""

URL pública completa para o endpoint de webhook (necessária atrás de proxy reverso)

historyLimit
Type: numberDefault: 20

Quantidade máxima de mensagens anteriores incluídas como contexto para conversas em sala

dmHistoryLimit
Type: numberDefault: 50

Quantidade máxima de mensagens anteriores incluídas como contexto para conversas em DM

textChunkLimit
Type: numberDefault: 4000

Quantidade máxima de caracteres por fragmento de mensagem

chunkMode
Type: stringDefault: "length"

Modo de divisão de texto: 'length' (limite de caracteres) ou 'newline' (limites de parágrafo)

blockStreaming
Type: booleanDefault: false

Aguardar a resposta completa da IA antes de enviar (sem streaming)

blockStreamingCoalesce
Type: booleanDefault: false

Combinar fragmentos de streaming em uma única mensagem final

mediaMaxMb
Type: numberDefault: 10

Tamanho máximo de arquivo em MB para referências de URL de mídia

Nextcloud Talk Perguntas Frequentes

Nextcloud Talk Solução de Problemas

O bot não responde às mensagens

A URL de webhook está inacessível, o bot não está ativado na sala, ou o segredo compartilhado não corresponde.

Verifique se a URL de webhook está acessível a partir do servidor Nextcloud (teste com curl). Verifique se o bot está ativado nas configurações da sala. Certifique-se de que o botSecret no openclaw.json corresponde ao segredo usado no comando de instalação OCC.
Falha na verificação de assinatura do webhook

O segredo compartilhado no openclaw.json não corresponde ao usado durante a instalação do bot.

Verifique se ambos os segredos correspondem exatamente. Em caso de dúvida, desinstale e reinstale o bot com um segredo conhecido. Verifique os logs do Gateway para erros de incompatibilidade de assinatura.
O bot responde em DMs, mas não em salas

O bot não foi ativado por um moderador na sala alvo, ou requireMention está definido como true e o bot não foi @mencionado.

Peça a um moderador da sala para ativar o bot nas configurações da sala. Se requireMention estiver configurado, certifique-se de que os usuários @mencionem o nome do bot. Verifique a configuração de rooms no openclaw.json.
Não é possível distinguir DMs de mensagens de sala

As credenciais de API (apiUser, apiPassword) não estão configuradas.

Adicione apiUser e apiPassword à configuração do canal nextcloud-talk. Crie uma conta de serviço dedicada no Nextcloud para esse propósito. O Gateway usa essas credenciais para consultar a API do Talk para detecção do tipo de conversa.
O Gateway falha ao iniciar o listener de webhook

A porta de webhook configurada já está em uso ou a vinculação de host é inválida.

Altere webhookPort para uma porta disponível (padrão: 8788). Se estiver vinculando a uma interface específica, verifique se o endereço IP do webhookHost está correto. Verifique conflitos de porta usando 'lsof -i :8788' ou 'netstat -tlnp'.
Ver documentação completaVoltar para todos os canais

Canais relacionados

Feishu / Lark

Medium

OpenClaw integração Feishu/Lark via WebSocket

Guia de Configuracao

Slack

Medium

OpenClaw integração de app workspace via Bolt SDK

Guia de Configuracao

Google Chat

Medium

OpenClaw app Google Chat API via endpoint HTTP

Guia de Configuracao