Mattermost

• Los valores predeterminados de native y nativeSkills son "auto", que para Mattermost se resuelve como deshabilitado. Establézcalos explícitamente en true.
• El valor predeterminado de callbackPath es /api/channels/mattermost/command.
• Si se omite callbackUrl, OpenClaw obtiene http://<gateway.customBindHost or localhost>:<gateway.port, default 18789><callbackPath>. Los hosts de enlace comodín (0.0.0.0, ::) recurren a localhost.
• En configuraciones con varias cuentas, commands puede establecerse en el nivel superior o en channels.mattermost.accounts.<id>.commands (los valores de la cuenta prevalecen sobre los campos del nivel superior).
• Los comandos de barra existentes con el mismo activador creados por otras integraciones no se modifican (se omiten durante el registro); los comandos creados por el bot se actualizan o se vuelven a crear cuando cambia la URL de devolución de llamada.
• Las devoluciones de llamada de los comandos se validan con los tokens específicos de cada comando que Mattermost devuelve cuando OpenClaw registra los comandos oc_*.
• OpenClaw actualiza el registro actual de comandos de Mattermost antes de aceptar cada devolución de llamada, por lo que los tokens obsoletos de comandos de barra eliminados o regenerados dejan de aceptarse sin necesidad de reiniciar el Gateway.
• La validación de la devolución de llamada falla de forma segura si la API de Mattermost no puede confirmar que el comando sigue vigente; las validaciones fallidas se almacenan brevemente en caché, las consultas simultáneas se agrupan y los inicios de consultas nuevas se limitan por comando para acotar la presión de reproducción.
• Las devoluciones de llamada de comandos de barra fallan de forma segura cuando el registro no se completó, el inicio fue parcial o el token de devolución de llamada no coincide con el token registrado del comando resuelto (un token válido para un comando no puede llegar a la validación ascendente de otro comando).
• Las devoluciones de llamada aceptadas se confirman con una respuesta efímera "Procesando..."; la respuesta real llega como un mensaje normal.

El servidor de Mattermost debe poder acceder al punto de conexión de devolución de llamada.

• No establezca callbackUrl en localhost, salvo que Mattermost se ejecute en el mismo host o espacio de nombres de red que OpenClaw.
• No establezca callbackUrl en la URL base de Mattermost, salvo que esa URL use un proxy inverso para dirigir /api/channels/mattermost/command a OpenClaw.
• Una comprobación rápida es curl https://<gateway-host>/api/channels/mattermost/command; una solicitud GET debe devolver 405 Method Not Allowed desde OpenClaw, no 404.

Si la devolución de llamada apunta a direcciones privadas, de tailnet o internas, configure ServiceSettings.AllowedUntrustedInternalConnections de Mattermost para incluir el host o dominio de devolución de llamada.

Use entradas de host o dominio, no URL completas.

• Correcto: gateway.tailnet-name.ts.net
• Incorrecto: https://gateway.tailnet-name.ts.net

• partial (predeterminado): una publicación de vista previa que se edita a medida que crece la respuesta y después se finaliza con la respuesta completa.
• block alterna la vista previa entre bloques de texto completado y de actividad de las herramientas, por lo que cada bloque permanece visible como una publicación independiente en lugar de sobrescribirse en el mismo lugar. Las actualizaciones paralelas y consecutivas de herramientas comparten la publicación actual de actividad de las herramientas.
• progress muestra una vista previa del estado durante la generación y solo publica la respuesta final al completarse.
• off desactiva la transmisión de vista previa. Con blockStreaming: true, los bloques completados del asistente siguen entregándose como respuestas normales en bloques (publicaciones separadas), en lugar de como una única publicación final combinada.

• Si la transmisión no puede finalizarse en el mismo lugar (por ejemplo, si la publicación se eliminó durante la transmisión), OpenClaw recurre al envío de una nueva publicación final para que la respuesta nunca se pierda.
• Las cargas que solo contienen razonamiento se omiten de las publicaciones del canal, incluido el texto que llega como una cita en bloque > Thinking. Configure /reasoning on para ver el razonamiento en otras superficies; la publicación final de Mattermost conserva únicamente la respuesta.
• Consulte Transmisión para ver la matriz de correspondencias de canales.

• Las devoluciones de llamada de los botones usan verificación HMAC-SHA256 (automática, sin necesidad de configuración).
• Al hacer clic se sustituye todo el bloque adjunto, por lo que todos los botones se eliminan conjuntamente; no es posible eliminarlos de forma parcial.
• Los identificadores de acción que contienen guiones o guiones bajos se depuran automáticamente (limitación del enrutamiento de Mattermost).
• Los clics cuyo action_id no coincide con ninguna acción de la publicación original se rechazan con 403 ("Acción desconocida").

• channels.mattermost.capabilities: matriz de cadenas de capacidades. Añada "inlineButtons" para activar la descripción de la herramienta de botones en el mensaje del sistema del agente.
• channels.mattermost.interactions.callbackBaseUrl: URL base externa opcional para las devoluciones de llamada de los botones (por ejemplo, https://gateway.example.com). Úsela cuando Mattermost no pueda acceder directamente al Gateway en su host de enlace.
• En configuraciones con varias cuentas, también puede establecer el mismo campo en channels.mattermost.accounts.<id>.interactions.callbackBaseUrl.
• Si se omite interactions.callbackBaseUrl, OpenClaw obtiene la URL de devolución de llamada a partir de gateway.customBindHost + gateway.port (valor predeterminado: 18789) y, si no es posible, recurre a http://localhost:<port>. La ruta de devolución de llamada es /mattermost/interactions/<accountId>.
• Regla de accesibilidad: el servidor de Mattermost debe poder acceder a la URL de devolución de llamada del botón. localhost solo funciona cuando Mattermost y OpenClaw se ejecutan en el mismo host o espacio de nombres de red.
• channels.mattermost.interactions.allowedSourceIps: lista de direcciones IP de origen permitidas para las devoluciones de llamada de los botones. Sin ella, solo se aceptan orígenes local loopback (127.0.0.1, ::1), por lo que un servidor remoto de Mattermost debe incluirse aquí en la lista de permitidos o sus clics se rechazarán con 403. Si se encuentra detrás de un proxy inverso, configure también gateway.trustedProxies para obtener la dirección IP real del cliente a partir de los encabezados reenviados.
• Si el destino de la devolución de llamada es privado, pertenece a una red de Tailscale o es interno, añada su host o dominio a ServiceSettings.AllowedUntrustedInternalConnections de Mattermost.

• json.dumps de Python añade espacios de forma predeterminada ({"key": "val"}). Use separators=(",", ":") para que coincida con la salida compacta de JavaScript ({"key":"val"}).
• Firme siempre todos los campos de contexto (excepto _token). El Gateway elimina _token y después firma todo lo restante. Firmar un subconjunto provoca un fallo de verificación silencioso.
• Use sort_keys=True: el Gateway ordena las claves antes de firmar, y Mattermost puede reordenar los campos de contexto al almacenar la carga.
• Obtenga el secreto a partir del token del bot (de forma determinista), no de bytes aleatorios. El secreto debe ser el mismo en el proceso que crea los botones y en el Gateway que realiza la verificación.

Asegúrate de que el bot esté en el canal y menciónalo (oncall), usa un prefijo de activación (onchar) o establece chatmode: "onmessage".

• Comprueba el token del bot, la URL base y si la cuenta está habilitada.
• Problemas con varias cuentas: las variables de entorno solo se aplican a la cuenta default.
• Los hosts privados o de LAN de Mattermost necesitan network.dangerouslyAllowPrivateNetwork: true (la protección contra SSRF bloquea las IP privadas de forma predeterminada).

• Unauthorized: invalid command token.: OpenClaw no aceptó el token de devolución de llamada. Causas habituales:
  • el registro del comando de barra falló o solo se completó parcialmente durante el inicio
  • la devolución de llamada llega al Gateway o a la cuenta incorrectos
  • Mattermost aún tiene comandos antiguos que apuntan a un destino de devolución de llamada anterior
  • el Gateway se reinició sin volver a activar los comandos de barra
• Si los comandos de barra nativos dejan de funcionar, busca en los registros mattermost: failed to register slash commands o mattermost: native slash commands enabled but no commands could be registered.
• Si se omite callbackUrl y los registros advierten que la devolución de llamada se resolvió en una URL de local loopback como http://localhost:18789/..., probablemente esa URL solo sea accesible cuando Mattermost se ejecuta en el mismo host o espacio de nombres de red que OpenClaw. En su lugar, establece un commands.callbackUrl explícito y accesible externamente.

• Los botones aparecen como cuadros blancos o no aparecen: los datos del botón tienen un formato incorrecto. Cada botón de presentación necesita un label y un value (se descartan los botones a los que les falte cualquiera de ellos).
• Los botones se muestran, pero los clics no hacen nada: comprueba que el Gateway sea accesible desde el servidor de Mattermost, que la IP del servidor de Mattermost esté incluida en channels.mattermost.interactions.allowedSourceIps (sin esta opción solo se acepta local loopback) y que ServiceSettings.AllowedUntrustedInternalConnections incluya el host de devolución de llamada para destinos privados.
• Los botones devuelven 404 al hacer clic: es probable que el id del botón contenga guiones o guiones bajos. El enrutador de acciones de Mattermost falla con identificadores no alfanuméricos. Usa únicamente [a-zA-Z0-9].
• El Gateway registra rejected callback source: el clic provino de una IP que no está en interactions.allowedSourceIps. Añade el servidor de Mattermost o tu punto de entrada a la lista de permitidos y configura gateway.trustedProxies si está detrás de un proxy inverso.
• El Gateway registra invalid _token: discrepancia de HMAC. Comprueba que firmas todos los campos de contexto (no solo un subconjunto), que usas claves ordenadas y JSON compacto (sin espacios). Consulta la sección sobre HMAC anterior.
• El Gateway registra missing _token in context: el campo _token no está en el contexto del botón. Asegúrate de incluirlo al crear la carga útil de integración.
• El Gateway rechaza el clic con Unknown action: context.action_id no coincide con ningún id de acción de la publicación. Establece ambos con el mismo valor saneado.
• El agente no ofrece botones: añade capabilities: ["inlineButtons"] a la configuración del canal de Mattermost.