Mattermost

• native: "auto" usa desativado como padrão para Mattermost. Defina native: true para ativar.
• Se callbackUrl for omitido, o OpenClaw deriva uma a partir do host/porta do Gateway + callbackPath.
• Para configurações com várias contas, commands pode ser definido no nível superior ou em channels.mattermost.accounts.<id>.commands (valores da conta substituem campos do nível superior).
• Callbacks de comando são validados com os tokens por comando retornados pelo Mattermost quando o OpenClaw registra comandos oc_*.
• O OpenClaw atualiza o registro atual de comandos do Mattermost antes de aceitar cada callback, para que tokens obsoletos de comandos de barra excluídos ou regenerados deixem de ser aceitos sem reiniciar o Gateway.
• A validação do callback falha de forma fechada se a API do Mattermost não conseguir confirmar que o comando ainda é atual; validações com falha são armazenadas brevemente em cache, consultas simultâneas são agrupadas, e novos inícios de consulta são limitados por taxa por comando para limitar a pressão de replay.
• Callbacks de barra falham de forma fechada quando o registro falhou, a inicialização foi parcial ou o token de callback não corresponde ao token registrado do comando resolvido (um token válido para um comando não consegue alcançar a validação upstream de outro comando).

O endpoint de callback deve ser alcançável a partir do servidor Mattermost.

• Não defina callbackUrl como localhost a menos que o Mattermost seja executado no mesmo host/namespace de rede que o OpenClaw.
• Não defina callbackUrl como sua URL base do Mattermost a menos que essa URL faça proxy reverso de /api/channels/mattermost/command para o OpenClaw.
• Uma verificação rápida é curl https://<gateway-host>/api/channels/mattermost/command; um GET deve retornar 405 Method Not Allowed do OpenClaw, não 404.

Se o callback tiver como destino endereços privados/tailnet/internos, defina ServiceSettings.AllowedUntrustedInternalConnections do Mattermost para incluir o host/domínio do callback.

Use entradas de host/domínio, não URLs completas.

• Correto: gateway.tailnet-name.ts.net
• Incorreto: https://gateway.tailnet-name.ts.net

• partial é a escolha usual: uma postagem de prévia que é editada conforme a resposta cresce e, então, finalizada com a resposta completa.
• block usa partes de rascunho em estilo de acréscimo dentro da postagem de prévia.
• progress mostra uma prévia de status durante a geração e publica apenas a resposta final ao concluir.
• off desativa o streaming de prévia.

• Se o stream não puder ser finalizado no lugar (por exemplo, a postagem foi excluída no meio do stream), o OpenClaw recorre ao envio de uma nova postagem final para que a resposta nunca seja perdida.
• Payloads apenas de raciocínio são suprimidos das postagens no canal, incluindo texto que chega como uma citação em bloco > Thinking. Defina /reasoning on para ver o raciocínio em outras superfícies; a postagem final do Mattermost mantém apenas a resposta.
• Consulte Streaming para a matriz de mapeamento de canais.

• Callbacks de botão usam verificação HMAC-SHA256 (automática, nenhuma configuração necessária).
• O Mattermost remove dados de callback das respostas da API dele (recurso de segurança), portanto todos os botões são removidos no clique - remoção parcial não é possível.
• IDs de ação contendo hifens ou sublinhados são sanitizados automaticamente (limitação de roteamento do Mattermost).

• channels.mattermost.capabilities: matriz de strings de capacidade. Adicione "inlineButtons" para habilitar a descrição da ferramenta de botões no prompt do sistema do agente.
• channels.mattermost.interactions.callbackBaseUrl: URL base externa opcional para callbacks de botão (por exemplo, https://gateway.example.com). Use isto quando o Mattermost não conseguir alcançar o Gateway diretamente no host de bind dele.
• Em configurações com várias contas, você também pode definir o mesmo campo em channels.mattermost.accounts.<id>.interactions.callbackBaseUrl.
• Se interactions.callbackBaseUrl for omitido, o OpenClaw deriva a URL de callback de gateway.customBindHost + gateway.port e depois faz fallback para http://localhost:<port>.
• Regra de acessibilidade: a URL de callback do botão deve ser acessível a partir do servidor Mattermost. localhost só funciona quando Mattermost e OpenClaw rodam no mesmo host/namespace de rede.
• Se seu destino de callback for privado/tailnet/interno, adicione o host/domínio dele a ServiceSettings.AllowedUntrustedInternalConnections do Mattermost.

• json.dumps do Python adiciona espaços por padrão ({"key": "val"}). Use separators=(",", ":") para corresponder à saída compacta do JavaScript ({"key":"val"}).
• Sempre assine todos os campos de contexto (menos _token). O Gateway remove _token e então assina tudo o que resta. Assinar um subconjunto causa falha silenciosa de verificação.
• Use sort_keys=True - o Gateway ordena chaves antes de assinar, e o Mattermost pode reordenar campos de contexto ao armazenar o payload.
• Derive o segredo a partir do token do bot (determinístico), não de bytes aleatórios. O segredo deve ser o mesmo no processo que cria botões e no Gateway que verifica.

Garanta que o bot esteja no canal e mencione-o (oncall), use um prefixo de acionamento (onchar) ou defina chatmode: "onmessage".

• Verifique o token do bot, a URL base e se a conta está habilitada.
• Problemas com várias contas: vars de ambiente só se aplicam à conta default.

• Unauthorized: invalid command token.: o OpenClaw não aceitou o token de callback. Causas típicas:
  • o registro do comando de barra falhou ou foi concluído apenas parcialmente na inicialização
  • o callback está chegando ao Gateway/conta errado
  • o Mattermost ainda tem comandos antigos apontando para um destino de callback anterior
  • o Gateway reiniciou sem reativar os comandos de barra
• Se comandos de barra nativos pararem de funcionar, verifique os logs em busca de mattermost: failed to register slash commands ou mattermost: native slash commands enabled but no commands could be registered.
• Se callbackUrl for omitido e os logs avisarem que o callback foi resolvido para http://127.0.0.1:18789/..., essa URL provavelmente só é acessível quando o Mattermost roda no mesmo host/namespace de rede que o OpenClaw. Defina um commands.callbackUrl explicitamente acessível externamente em vez disso.

• Botões aparecem como caixas brancas: o agente pode estar enviando dados de botão malformados. Verifique se cada botão tem os campos text e callback_data.
• Botões são renderizados, mas cliques não fazem nada: verifique se AllowedUntrustedInternalConnections na configuração do servidor Mattermost inclui 127.0.0.1 localhost, e se EnablePostActionIntegration é true em ServiceSettings.
• Botões retornam 404 no clique: o id do botão provavelmente contém hifens ou sublinhados. O roteador de ações do Mattermost quebra com IDs não alfanuméricos. Use apenas [a-zA-Z0-9].
• Logs do Gateway mostram invalid _token: incompatibilidade de HMAC. Verifique se você assina todos os campos de contexto (não um subconjunto), usa chaves ordenadas e usa JSON compacto (sem espaços). Veja a seção de HMAC acima.
• Logs do Gateway mostram missing _token in context: o campo _token não está no contexto do botão. Garanta que ele seja incluído ao construir o payload de integração.
• A confirmação mostra ID bruto em vez do nome do botão: context.action_id não corresponde ao id do botão. Defina ambos com o mesmo valor sanitizado.
• O agente não sabe sobre botões: adicione capabilities: ["inlineButtons"] à configuração de canal do Mattermost.