Mattermost

• native: "auto" está deshabilitado de forma predeterminada para Mattermost. Define native: true para habilitarlo.
• Si se omite callbackUrl, OpenClaw deriva una a partir del host/puerto del Gateway + callbackPath.
• Para configuraciones con varias cuentas, commands se puede definir en el nivel superior o bajo channels.mattermost.accounts.<id>.commands (los valores de cuenta reemplazan los campos de nivel superior).
• Los callbacks de comandos se validan con los tokens por comando devueltos por Mattermost cuando OpenClaw registra comandos oc_*.
• OpenClaw actualiza el registro actual de comandos de Mattermost antes de aceptar cada callback para que los tokens obsoletos de comandos slash eliminados o regenerados dejen de aceptarse sin reiniciar el Gateway.
• La validación de callbacks falla de forma cerrada si la API de Mattermost no puede confirmar que el comando sigue siendo actual; las validaciones fallidas se almacenan brevemente en caché, las búsquedas concurrentes se fusionan y los inicios de búsquedas nuevas se limitan por frecuencia por comando para acotar la presión de reproducción.
• Los callbacks slash fallan de forma cerrada cuando el registro falló, el inicio fue parcial o el token del callback no coincide con el token registrado del comando resuelto (un token válido para un comando no puede llegar a la validación upstream de un comando diferente).

El endpoint de callback debe ser accesible desde el servidor de Mattermost.

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

Si tu callback apunta a direcciones privadas/tailnet/internas, configura ServiceSettings.AllowedUntrustedInternalConnections de Mattermost para incluir el host/dominio del callback.

Usa entradas de host/dominio, no URL completas.

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

• partial es la opción habitual: una publicación de vista previa que se edita a medida que crece la respuesta y luego se finaliza con la respuesta completa.
• block usa fragmentos de borrador de estilo anexado dentro de la publicación de vista previa.
• progress muestra una vista previa de estado mientras se genera y solo publica la respuesta final al completarse.
• off deshabilita el streaming de vista previa.

• Si el stream no se puede finalizar en el mismo lugar (por ejemplo, la publicación se eliminó a mitad del stream), OpenClaw recurre a enviar una nueva publicación final para que la respuesta nunca se pierda.
• Las cargas útiles solo de razonamiento se suprimen de las publicaciones de canal, incluido el texto que llega como una cita en bloque > Thinking. Define /reasoning on para ver el razonamiento en otras superficies; la publicación final de Mattermost conserva solo la respuesta.
• Consulta Streaming para ver la matriz de mapeo de canales.

• Las devoluciones de llamada de los botones usan verificación HMAC-SHA256 (automática, sin configuración necesaria).
• Mattermost elimina los datos de devolución de llamada de sus respuestas de API (función de seguridad), por lo que todos los botones se eliminan al hacer clic; la eliminación parcial no es posible.
• Los ID de acción que contienen guiones o guiones bajos se saneean automáticamente (limitación de enrutamiento de Mattermost).

• channels.mattermost.capabilities: arreglo de cadenas de capacidades. Agrega "inlineButtons" para habilitar la descripción de la herramienta de botones en el prompt del sistema del agente.
• channels.mattermost.interactions.callbackBaseUrl: URL base externa opcional para devoluciones de llamada de botones (por ejemplo, https://gateway.example.com). Úsala cuando Mattermost no pueda alcanzar el Gateway directamente en su host de enlace.
• En configuraciones multicuenta, también puedes establecer el mismo campo en channels.mattermost.accounts.<id>.interactions.callbackBaseUrl.
• Si se omite interactions.callbackBaseUrl, OpenClaw deriva la URL de devolución de llamada de gateway.customBindHost + gateway.port y luego recurre a http://localhost:<port>.
• Regla de alcanzabilidad: la URL de devolución de llamada del botón debe ser alcanzable desde el servidor de Mattermost. localhost solo funciona cuando Mattermost y OpenClaw se ejecutan en el mismo host/espacio de nombres de red.
• Si tu destino de devolución de llamada es privado/tailnet/interno, agrega su host/dominio a ServiceSettings.AllowedUntrustedInternalConnections de Mattermost.

• json.dumps de Python agrega espacios de forma predeterminada ({"key": "val"}). Usa separators=(",", ":") para coincidir con la salida compacta de JavaScript ({"key":"val"}).
• Firma siempre todos los campos de contexto (menos _token). El Gateway elimina _token y luego firma todo lo restante. Firmar un subconjunto causa un fallo de verificación silencioso.
• Usa sort_keys=True; el Gateway ordena las claves antes de firmar, y Mattermost puede reordenar los campos de contexto al almacenar la carga.
• Deriva el secreto del token del bot (determinista), no de bytes aleatorios. El secreto debe ser el mismo en el proceso que crea los botones y en el Gateway que los verifica.

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

• Revisa el token del bot, la URL base y si la cuenta está habilitada.
• Problemas multicuenta: las variables de entorno solo se aplican a la cuenta default.

• Unauthorized: invalid command token.: OpenClaw no aceptó el token de devolución de llamada. Causas típicas:
  • el registro del comando slash falló o solo se completó parcialmente al inicio
  • la devolución de llamada está llegando al Gateway/cuenta incorrectos
  • Mattermost aún tiene comandos antiguos que apuntan a un destino de devolución de llamada anterior
  • el Gateway se reinició sin reactivar los comandos slash
• Si los comandos slash nativos dejan de funcionar, revisa los logs para mattermost: failed to register slash commands o mattermost: native slash commands enabled but no commands could be registered.
• Si se omite callbackUrl y los logs advierten que la devolución de llamada se resolvió como http://127.0.0.1:18789/..., esa URL probablemente solo sea alcanzable cuando Mattermost se ejecuta en el mismo host/espacio de nombres de red que OpenClaw. En su lugar, establece un commands.callbackUrl explícito y alcanzable externamente.

• Los botones aparecen como cuadros blancos: el agente puede estar enviando datos de botón mal formados. Comprueba que cada botón tenga los campos text y callback_data.
• Los botones se renderizan, pero los clics no hacen nada: verifica que AllowedUntrustedInternalConnections en la configuración del servidor Mattermost incluya 127.0.0.1 localhost y que EnablePostActionIntegration sea true en ServiceSettings.
• Los botones devuelven 404 al hacer clic: probablemente el id del botón contiene guiones o guiones bajos. El enrutador de acciones de Mattermost falla con ID no alfanuméricos. Usa solo [a-zA-Z0-9].
• Los logs del Gateway muestran invalid _token: discrepancia HMAC. Comprueba que firmas todos los campos de contexto (no un subconjunto), usas claves ordenadas y usas JSON compacto (sin espacios). Consulta la sección HMAC anterior.
• Los logs del Gateway muestran missing _token in context: el campo _token no está en el contexto del botón. Asegúrate de incluirlo al construir la carga de integración.
• La confirmación muestra un ID sin procesar en lugar del nombre del botón: context.action_id no coincide con el id del botón. Establece ambos con el mismo valor saneado.
• El agente no sabe sobre los botones: agrega capabilities: ["inlineButtons"] a la configuración del canal Mattermost.