Que version de Nextcloud se requiere?

Se requiere Nextcloud 27.1 o posterior, ya que la API de Bot (capacidad bots-v1) se introdujo en esta version. Las versiones anteriores no soportan el framework de bots basado en webhooks.

Puede el bot iniciar conversaciones con los usuarios?

No. Los bots de Nextcloud Talk no pueden iniciar mensajes directos. Los usuarios deben escribir al bot primero. Para las salas, un moderador debe habilitar el bot en la configuracion de la sala, y entonces el bot puede responder a los mensajes.

El bot soporta archivos adjuntos?

Los archivos multimedia se manejan como URLs en lugar de subidas directas de archivos. Cuando los usuarios comparten archivos, el bot recibe la URL del archivo. El bot puede incluir URLs en sus respuestas, pero no puede subir archivos directamente a Nextcloud Talk.

Puedo ejecutar el bot sin una URL de webhook accesible publicamente?

La URL del webhook debe ser accesible desde el servidor Nextcloud. Si ambos servicios estan en la misma red, una URL interna es suficiente. Para desarrollo, usa un servicio de tunel como ngrok para exponer tu Gateway local.

El bot soporta conversaciones con hilos?

No. El soporte de hilos de Nextcloud Talk no esta disponible actualmente en la integracion del bot. Todos los mensajes se tratan como parte del flujo principal de la conversacion.

Como actualizo el secreto compartido del bot?

Desinstala el bot existente usando './occ talk:bot:uninstall ' y reinstalalo con un nuevo secreto usando './occ talk:bot:install'. Actualiza el botSecret en tu openclaw.json de acuerdo.

OpenClaw GuideOpenClaw

Comenzar

Canal Nextcloud Talk de OpenClaw

Empresarial

Medio

Conecta OpenClaw a Nextcloud Talk, la plataforma de comunicacion empresarial centrada en la privacidad integrada en el ecosistema Nextcloud. La integracion utiliza una arquitectura de bot basada en webhooks: Nextcloud Talk envia eventos de mensajes a tu Gateway mediante webhooks, y el bot responde a traves de la API REST de Talk. Esto permite que tu asistente de IA participe en mensajes directos, conversaciones en salas y reaccione a mensajes con emojis, todo dentro de tu entorno Nextcloud autoalojado.

Info rápida

DificultadMedio

CategoríaEmpresarial

Funciones compatibles4 / 6

Nextcloud Talk Funciones compatibles

Mensajes de texto

Compatible

Medios y archivos

Compatible

Reacciones

Compatible

Hilos

No compatible

Mensajes de voz

No compatible

Chat grupal

Compatible

Nextcloud Talk Requisitos previos

Un servidor Nextcloud (v27.1+) con acceso de administrador y la aplicacion Talk instalada
Un secreto compartido (40-128 caracteres) para la validacion de firma del webhook
El endpoint de webhook del Gateway accesible desde el servidor Nextcloud (URL publica o red interna)
OpenClaw Gateway instalado y en funcionamiento
El plugin de Nextcloud Talk instalado mediante 'openclaw plugins install @openclaw/nextcloud-talk'

Nextcloud Talk Configuración rápida

Instalar el plugin de Nextcloud Talk

Ejecuta 'openclaw plugins install @openclaw/nextcloud-talk' para agregar soporte de Nextcloud Talk a tu Gateway.

Registrar el bot en tu servidor Nextcloud

Accede por SSH a tu servidor Nextcloud y ejecuta el comando OCC: ./occ talk:bot:install "OpenClaw" "<shared-secret>" "<webhook-url>" --feature reaction. Reemplaza <shared-secret> con un secreto seguro de al menos 40 caracteres, y <webhook-url> con el endpoint de webhook del Gateway accesible publicamente (por ejemplo, https://gateway.example.com:8788/webhook).

Habilitar el bot y configurar

En Nextcloud Talk, ve a la configuracion de la sala y habilita el bot OpenClaw. Luego agrega la configuracion del canal en ~/.openclaw/openclaw.json con tu baseUrl y botSecret. Inicia el Gateway con 'openclaw start' y envia un mensaje en la sala para verificar la conexion.

Nextcloud Talk Ejemplo de configuración

config.json

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

Nextcloud Talk Documentación Detallada

Descripcion general de la arquitectura

OpenClaw se integra con Nextcloud Talk a traves de la API de Bot de Talk (disponible desde Nextcloud 27.1). La arquitectura esta basada en webhooks: 1. El bot se registra en el servidor Nextcloud usando la herramienta de linea de comandos OCC con un secreto compartido y una URL de webhook. 2. Cuando se publica un mensaje en una sala donde el bot esta habilitado, Nextcloud Talk envia un HTTP POST a la URL de webhook configurada con el contenido del mensaje, firmado usando el secreto compartido. 3. El Gateway verifica la firma del webhook, procesa el mensaje a traves de tu agente de IA y publica la respuesta de vuelta en la conversacion usando la API REST de Talk. Este diseno significa que el Gateway debe exponer un endpoint de webhook accesible desde el servidor Nextcloud. El listener de webhook se ejecuta en el puerto 8788 por defecto y puede personalizarse mediante las opciones de configuracion webhookPort y webhookHost.

La URL del webhook debe ser accesible desde el servidor Nextcloud. Para desarrollo local, usa un servicio de tunel como ngrok.

Cada instalacion de bot genera un hash de URL unico (bot-<hash>) que se utiliza como ID de actor para los mensajes.

Registro del bot via OCC

Los bots de Nextcloud Talk se registran en el servidor usando comandos OCC (Nextcloud Command Console). Esta es una operacion del lado del servidor que requiere acceso por SSH o consola. Para instalar el bot: ./occ talk:bot:install "OpenClaw" "<secret>" "<webhook-url>" --feature reaction Parametros: • name (obligatorio): Nombre visible mostrado como autor del mensaje (1-64 caracteres) • secret (obligatorio): Secreto compartido para la validacion de firma del webhook (40-128 caracteres) • url (obligatorio): URL del endpoint de webhook de tu Gateway • --feature: Capacidades del bot — usa 'reaction' para habilitar reacciones con emoji • --no-setup: Evita que los moderadores activen o desactiven el bot por sala Otros comandos OCC utiles: • talk:bot:list — Listar todos los bots instalados • talk:bot:remove <bot-id> — Eliminar un bot de conversaciones especificas • talk:bot:setup <bot-id> <token> — Habilitar un bot en una conversacion • talk:bot:state <bot-id> <state> — Cambiar el estado del bot (0=deshabilitado, 1=habilitado, 2=sin-configuracion) • talk:bot:uninstall <id> — Eliminar completamente un bot del 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

Genera un secreto compartido seguro usando: openssl rand -base64 48

Se recomienda el flag --feature reaction para permitir que el bot reaccione a mensajes con emoji.

Politicas de mensajes directos

Las politicas de mensajes directos (DM) controlan como el bot gestiona las conversaciones privadas uno a uno. **pairing (por defecto)** — Los remitentes desconocidos reciben un codigo de emparejamiento que debe verificarse antes de que el bot responda. Este es el modo mas seguro, ya que requiere autorizacion explicita del usuario. **open** — Cualquier usuario que envie un mensaje al bot recibe una respuesta. Requiere establecer allowFrom en ["*"]. **disabled** — El bot no responde a mensajes directos en absoluto. Nota: Los bots de Nextcloud Talk no pueden iniciar mensajes directos — el usuario debe escribir al bot primero. El campo allowFrom coincide con los IDs de usuario de Nextcloud (no con los nombres para mostrar).

openclaw.json

{
  "channels": {
    "nextcloud-talk": {
      "dmPolicy": "pairing",
      "allowFrom": ["user-id-1", "user-id-2"]
    }
  }
}

Los bots no pueden iniciar mensajes directos en Nextcloud Talk. Los usuarios deben contactar al bot primero para iniciar una conversacion.

Configuracion de salas

Las politicas de sala (chat grupal) controlan en que conversaciones participa el bot y como se activa. **allowlist (por defecto)** — El bot solo responde en salas donde ha sido habilitado explicitamente por un moderador a traves de la configuracion de la sala. La configuracion por sala puede personalizarse usando el objeto rooms. Cada sala se identifica por su token de conversacion y puede tener ajustes independientes: • requireMention — Cuando es true, el bot solo responde cuando se le menciona con @ (comportamiento por defecto en salas) • Las salas no listadas en la configuracion usan los ajustes de sala predeterminados Para encontrar el token de una sala, observa la URL al visualizar la sala en Nextcloud Talk (por ejemplo, https://nextcloud.example.com/call/<token>).

openclaw.json

{
  "channels": {
    "nextcloud-talk": {
      "groupPolicy": "allowlist",
      "rooms": {
        "abc123token": {
          "requireMention": true
        },
        "def456token": {
          "requireMention": false
        }
      }
    }
  }
}

Un moderador de la sala debe habilitar el bot en la configuracion de la sala antes de que pueda recibir mensajes.

Usa requireMention: true para salas con mucha actividad para evitar que el bot responda a cada mensaje.

Credenciales de API para deteccion de salas

Por defecto, el payload del webhook de Nextcloud Talk no distingue entre mensajes directos y mensajes de sala. Para habilitar la deteccion precisa del tipo de sala, puedes proporcionar credenciales de API. Cuando apiUser y apiPassword estan configurados, el Gateway realiza una llamada API adicional para determinar si un mensaje entrante proviene de un DM o de una conversacion en sala. Esto permite que el bot aplique correctamente las diferentes politicas (dmPolicy vs groupPolicy). Sin credenciales de API, el bot trata todos los mensajes segun una politica unificada, lo cual puede ser suficiente para despliegues sencillos.

openclaw.json

{
  "channels": {
    "nextcloud-talk": {
      "apiUser": "bot-service-account",
      "apiPassword": "service-account-password",
      "apiPasswordFile": "/run/secrets/nc-api-password"
    }
  }
}

Crea una cuenta de usuario dedicada en Nextcloud para las credenciales de API en lugar de usar una cuenta de administrador.

Usa apiPasswordFile para cargar la contrasena desde un archivo (por ejemplo, un secreto de Docker) en lugar de almacenarla en la configuracion.

Sin credenciales de API, el bot no puede distinguir los DMs de los mensajes de sala. Esto puede causar que las politicas exclusivas de DM no funcionen correctamente.

Configuracion del webhook

El Gateway inicia un servidor HTTP integrado para recibir eventos de webhook de Nextcloud Talk. La configuracion del listener de webhook controla como y donde escucha el servidor. **webhookPort** (por defecto: 8788) — El puerto para el servidor HTTP de webhook. **webhookHost** (por defecto: 0.0.0.0) — La interfaz a la que enlazar. Usa 0.0.0.0 para escuchar en todas las interfaces o 127.0.0.1 solo para localhost. **webhookPath** — Ruta URL personalizada para el endpoint del webhook. **webhookPublicUrl** — La URL publica completa que Nextcloud debe usar para alcanzar el webhook. Requerida cuando se esta detras de un proxy inverso o NAT. La URL del webhook proporcionada durante la instalacion del bot (comando OCC) debe coincidir con la URL publica que resuelve a este listener.

openclaw.json

{
  "channels": {
    "nextcloud-talk": {
      "webhookPort": 8788,
      "webhookHost": "0.0.0.0",
      "webhookPath": "/webhook",
      "webhookPublicUrl": "https://gateway.example.com:8788/webhook"
    }
  }
}

Si ejecutas detras de un proxy inverso, establece webhookPublicUrl con la URL accesible externamente.

Asegurate de que tu firewall permita conexiones entrantes en el puerto del webhook desde el servidor Nextcloud.

Manejo de mensajes y streaming

OpenClaw proporciona un control detallado sobre como se fragmentan y entregan los mensajes a Nextcloud Talk. **textChunkLimit** — Numero maximo de caracteres por fragmento de mensaje. Nextcloud Talk soporta mensajes largos, pero la fragmentacion puede mejorar la legibilidad para respuestas extensas de IA. **chunkMode** — Controla como se divide el texto: 'length' divide en el limite de caracteres, 'newline' divide en los limites de parrafo para cortes mas naturales. **blockStreaming** — Cuando esta habilitado, el bot espera la respuesta completa de la IA antes de enviar, en lugar de transmitir respuestas parciales. **blockStreamingCoalesce** — Cuando el block streaming esta habilitado, esto combina la respuesta final en un unico mensaje en lugar de multiples fragmentos. **mediaMaxMb** — Tamano maximo de archivo (en MB) para adjuntos multimedia. Ten en cuenta que Nextcloud Talk transmite multimedia como URLs en lugar de subidas directas de archivos.

openclaw.json

{
  "channels": {
    "nextcloud-talk": {
      "textChunkLimit": 4000,
      "chunkMode": "newline",
      "blockStreaming": true,
      "blockStreamingCoalesce": true,
      "mediaMaxMb": 10
    }
  }
}

Usa blockStreaming: true para respuestas mas limpias en salas donde varios usuarios estan activos.

Los archivos multimedia se comparten como URLs en Nextcloud Talk — el bot no puede subir archivos directamente.

Historial de conversaciones

Controla cuantos mensajes anteriores se incluyen como contexto cuando el agente de IA procesa un nuevo mensaje. **historyLimit** — Numero maximo de mensajes anteriores a incluir para conversaciones en salas. **dmHistoryLimit** — Numero maximo de mensajes anteriores a incluir para conversaciones de mensajes directos. Puede configurarse independientemente del limite de historial de sala. Tambien se admiten ajustes por DM individual, lo que permite configurar diferentes limites de historial para usuarios especificos. Un limite de historial mas alto proporciona mas contexto para la IA, pero aumenta el uso de tokens y el tiempo de procesamiento.

openclaw.json

{
  "channels": {
    "nextcloud-talk": {
      "historyLimit": 20,
      "dmHistoryLimit": 50
    }
  }
}

Soporte de reacciones

Nextcloud Talk soporta reacciones con emoji en los mensajes, y el bot de OpenClaw puede tanto leer como agregar reacciones. Para habilitar el soporte de reacciones, el bot debe registrarse con el flag --feature reaction durante la instalacion via OCC. Una vez habilitado, el agente de IA puede reaccionar a los mensajes de los usuarios con emoji para proporcionar confirmacion o retroalimentacion. Las reacciones son una forma ligera de que el bot interactue sin publicar respuestas de texto completas — por ejemplo, reaccionando con un emoji de marca de verificacion para confirmar una tarea completada. La API de reacciones de Nextcloud Talk (disponible desde la capacidad bots-v1) gestiona los mecanismos subyacentes para agregar y eliminar reacciones.

El flag --feature reaction debe establecerse durante la instalacion del bot para que las reacciones funcionen.

Las reacciones pueden usarse como un mecanismo de confirmacion no intrusivo en salas con mucha actividad.

Seguridad y firma de webhooks

Todos los payloads de webhook de Nextcloud Talk se firman usando el secreto compartido configurado durante la instalacion del bot. El Gateway verifica cada firma para garantizar la autenticidad e integridad. El mecanismo de firma utiliza HMAC-SHA256: 1. Nextcloud calcula un hash HMAC-SHA256 del cuerpo del payload del webhook usando el secreto compartido. 2. La firma se incluye en los encabezados HTTP de la solicitud del webhook. 3. El Gateway calcula independientemente el hash y lo compara con la firma recibida. 4. Si las firmas no coinciden, la solicitud se rechaza. Esto garantiza que solo se procesen solicitudes legitimas de tu servidor Nextcloud. Manten el secreto compartido confidencial y rotalo periodicamente reinstalando el bot con un nuevo secreto.

Usa un secreto criptograficamente fuerte: openssl rand -base64 48 genera un valor adecuado.

Almacena el secreto usando botSecretFile para evitar incluirlo en el control de versiones.

Nunca expongas el secreto compartido en repositorios publicos ni en logs. Usa variables de entorno o archivos de secretos para despliegues en produccion.

Nextcloud Talk Referencia de Configuración

Key	Type	Default	Description
enabled	boolean	true	Habilitar o deshabilitar el canal de Nextcloud Talk
baseUrl	string	""	URL completa de tu servidor Nextcloud (por ejemplo, https://nextcloud.example.com)
botSecret	string	""	Secreto compartido utilizado para la validacion de firma del webhook (debe coincidir con el secreto de instalacion OCC)
botSecretFile	string	""	Ruta a un archivo que contiene el secreto compartido (alternativa al botSecret en linea)
apiUser	string	""	Nombre de usuario de Nextcloud para llamadas a la API (utilizado para la deteccion del tipo de sala)
apiPassword	string	""	Contrasena para la cuenta de usuario de la API
apiPasswordFile	string	""	Ruta a un archivo que contiene la contrasena de la API (alternativa a apiPassword en linea)
dmPolicy	string	"pairing"	Politica de acceso a DM: 'pairing' (codigo de verificacion), 'open' (cualquier usuario) o 'disabled' (sin DMs)
allowFrom	string[]	[]	IDs de usuario de Nextcloud permitidos para enviar DM al bot (usa ["*"] para acceso abierto)
groupPolicy	string	"allowlist"	Politica de acceso a salas: 'allowlist' (solo salas habilitadas por moderadores)
webhookPort	number	8788	Puerto para el servidor HTTP de webhook integrado
webhookHost	string	"0.0.0.0"	Interfaz a la que enlazar el servidor de webhook
webhookPath	string	"/webhook"	Ruta URL para el endpoint del webhook
webhookPublicUrl	string	""	URL publica completa para el endpoint del webhook (requerida detras de un proxy inverso)
historyLimit	number	20	Numero maximo de mensajes anteriores incluidos como contexto para conversaciones en salas
dmHistoryLimit	number	50	Numero maximo de mensajes anteriores incluidos como contexto para conversaciones por DM
textChunkLimit	number	4000	Numero maximo de caracteres por fragmento de mensaje
chunkMode	string	"length"	Modo de division de texto: 'length' (limite de caracteres) o 'newline' (limites de parrafo)
blockStreaming	boolean	false	Esperar la respuesta completa de la IA antes de enviar (sin streaming)
blockStreamingCoalesce	boolean	false	Combinar los fragmentos de streaming en un unico mensaje final
mediaMaxMb	number	10	Tamano maximo de archivo en MB para referencias de URLs multimedia

enabled

Type: booleanDefault: true

Habilitar o deshabilitar el canal de Nextcloud Talk

baseUrl

Type: stringDefault: ""

URL completa de tu servidor Nextcloud (por ejemplo, https://nextcloud.example.com)

botSecret

Type: stringDefault: ""

Secreto compartido utilizado para la validacion de firma del webhook (debe coincidir con el secreto de instalacion OCC)

botSecretFile

Type: stringDefault: ""

Ruta a un archivo que contiene el secreto compartido (alternativa al botSecret en linea)

apiUser

Type: stringDefault: ""

Nombre de usuario de Nextcloud para llamadas a la API (utilizado para la deteccion del tipo de sala)

apiPassword

Type: stringDefault: ""

Contrasena para la cuenta de usuario de la API

apiPasswordFile

Type: stringDefault: ""

Ruta a un archivo que contiene la contrasena de la API (alternativa a apiPassword en linea)

dmPolicy

Type: stringDefault: "pairing"

Politica de acceso a DM: 'pairing' (codigo de verificacion), 'open' (cualquier usuario) o 'disabled' (sin DMs)

allowFrom

Type: string[]Default: []

IDs de usuario de Nextcloud permitidos para enviar DM al bot (usa ["*"] para acceso abierto)

groupPolicy

Type: stringDefault: "allowlist"

Politica de acceso a salas: 'allowlist' (solo salas habilitadas por moderadores)

webhookPort

Type: numberDefault: 8788

Puerto para el servidor HTTP de webhook integrado

webhookHost

Type: stringDefault: "0.0.0.0"

Interfaz a la que enlazar el servidor de webhook

webhookPath

Type: stringDefault: "/webhook"

Ruta URL para el endpoint del webhook

webhookPublicUrl

Type: stringDefault: ""

URL publica completa para el endpoint del webhook (requerida detras de un proxy inverso)

historyLimit

Type: numberDefault: 20

Numero maximo de mensajes anteriores incluidos como contexto para conversaciones en salas

dmHistoryLimit

Type: numberDefault: 50

Numero maximo de mensajes anteriores incluidos como contexto para conversaciones por DM

textChunkLimit

Type: numberDefault: 4000

Numero maximo de caracteres por fragmento de mensaje

chunkMode

Type: stringDefault: "length"

Modo de division de texto: 'length' (limite de caracteres) o 'newline' (limites de parrafo)

blockStreaming

Type: booleanDefault: false

Esperar la respuesta completa de la IA antes de enviar (sin streaming)

blockStreamingCoalesce

Type: booleanDefault: false

Combinar los fragmentos de streaming en un unico mensaje final

mediaMaxMb

Type: numberDefault: 10

Tamano maximo de archivo en MB para referencias de URLs multimedia

Nextcloud Talk Preguntas Frecuentes

Nextcloud Talk Solución de Problemas

El bot no responde a los mensajes

La URL del webhook es inaccesible, el bot no esta habilitado en la sala o el secreto compartido no coincide.

Verifica que la URL del webhook sea accesible desde el servidor Nextcloud (prueba con curl). Comprueba que el bot este habilitado en la configuracion de la sala. Asegurate de que el botSecret en openclaw.json coincida con el secreto usado en el comando OCC de instalacion.

La verificacion de firma del webhook falla

El secreto compartido en openclaw.json no coincide con el utilizado durante la instalacion del bot.

Verifica que ambos secretos coincidan exactamente. Si no estas seguro, desinstala y reinstala el bot con un secreto conocido. Revisa los logs del Gateway en busca de errores de discrepancia de firma.

El bot responde en DMs pero no en salas

El bot no ha sido habilitado por un moderador en la sala de destino, o requireMention esta en true y el bot no fue mencionado con @.

Pide a un moderador de la sala que habilite el bot en la configuracion de la sala. Si requireMention esta configurado, asegurate de que los usuarios mencionen al bot con @. Revisa la configuracion de rooms en openclaw.json.

No se puede distinguir entre DMs y mensajes de sala

Las credenciales de API (apiUser, apiPassword) no estan configuradas.

Agrega apiUser y apiPassword a la configuracion del canal nextcloud-talk. Crea una cuenta de servicio dedicada en Nextcloud para este proposito. El Gateway usa estas credenciales para consultar la API de Talk y detectar el tipo de conversacion.

El Gateway no puede iniciar el listener de webhook

El puerto de webhook configurado ya esta en uso o el enlace del host es invalido.

Cambia webhookPort a un puerto disponible (por defecto: 8788). Si enlazas a una interfaz especifica, verifica que la direccion IP de webhookHost sea correcta. Busca conflictos de puertos usando 'lsof -i :8788' o 'netstat -tlnp'.

Ver documentación completa Volver a todos los canales

Canales relacionados

Feishu / Lark

Medium

OpenClaw integración de Feishu/Lark vía WebSocket

Guía de configuración

Slack

Medium

OpenClaw integración de app de workspace vía Bolt SDK

Guía de configuración

Google Chat

Medium

OpenClaw app de Google Chat API via endpoint HTTP

Guía de configuración