Mattermost

• native e nativeSkills usam "auto" por padrão, que resulta em desativado para o Mattermost. Defina-os explicitamente como true.
• callbackPath usa /api/channels/mattermost/command por padrão.
• Se callbackUrl for omitido, o OpenClaw deriva http://<gateway.customBindHost or localhost>:<gateway.port, default 18789><callbackPath>. Hosts de vinculação curinga (0.0.0.0, ::) recorrem a localhost.
• Em configurações com várias contas, commands pode ser definido no nível superior ou em channels.mattermost.accounts.<id>.commands (os valores da conta substituem os campos do nível superior).
• Comandos de barra existentes com o mesmo acionador, criados por outras integrações, permanecem intactos (o registro os ignora); os comandos criados pelo bot são atualizados ou recriados quando a URL de callback diverge.
• Os callbacks de comando são validados com os tokens específicos de cada comando retornados pelo Mattermost quando o OpenClaw registra comandos oc_*.
• O OpenClaw atualiza o registro atual dos comandos do Mattermost antes de aceitar cada callback; assim, tokens obsoletos de comandos de barra excluídos ou regenerados deixam de ser aceitos sem que seja necessário reiniciar o Gateway.
• A validação do callback falha de forma fechada se a API do Mattermost não puder confirmar que o comando ainda é atual; as validações com falha são armazenadas brevemente em cache, as consultas simultâneas são consolidadas e o início de novas consultas tem limitação de frequência por comando para restringir a pressão de repetição.
• Os callbacks de barra falham de forma fechada quando o registro falhou, a inicialização foi parcial ou o token do callback não corresponde ao token registrado do comando resolvido (um token válido para um comando não pode alcançar a validação upstream de outro comando).
• Os callbacks aceitos são confirmados com uma resposta efêmera "Processando..."; a resposta real chega como uma mensagem normal.

O endpoint de callback deve estar acessível pelo servidor do 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 a 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; uma solicitação GET deve retornar 405 Method Not Allowed do OpenClaw, e não 404.

Se o callback apontar para 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 (padrão): uma publicação de pré-visualização que é editada à medida que a resposta aumenta e, em seguida, finalizada com a resposta completa.
• block alterna a pré-visualização entre o texto concluído e os blocos de atividade das ferramentas, de modo que cada bloco permaneça visível como uma publicação própria, em vez de ser sobrescrito no mesmo lugar. Atualizações de ferramentas paralelas e consecutivas compartilham a publicação atual de atividade das ferramentas.
• progress mostra uma pré-visualização de status durante a geração e publica a resposta final somente após a conclusão.
• off desativa o streaming de pré-visualização. Com streaming.block.enabled: true, os blocos concluídos do assistente ainda são entregues como respostas normais em blocos (publicações separadas), em vez de uma única publicação final consolidada.

• Se o stream não puder ser finalizado no mesmo lugar (por exemplo, se a publicação for excluída durante o stream), o OpenClaw recorre ao envio de uma nova publicação final para que a resposta nunca seja perdida.
• Cargas contendo somente raciocínio são suprimidas das publicações do 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 publicação final do Mattermost mantém somente a resposta.
• Consulte Streaming para ver a matriz de mapeamento dos canais.

• Os retornos de chamada dos botões usam verificação HMAC-SHA256 (automática, nenhuma configuração necessária).
• Todo o bloco de anexo é substituído ao clicar, portanto todos os botões são removidos juntos — não é possível removê-los parcialmente.
• IDs de ação contendo hifens ou sublinhados são higienizados automaticamente (limitação de roteamento do Mattermost).
• Cliques cujo action_id não corresponde a uma ação na publicação original são rejeitados com 403 ("Ação desconhecida").

• channels.mattermost.capabilities: matriz de strings de recursos. Adicione "inlineButtons" para ativar a descrição da ferramenta de botões no prompt de sistema do agente.
• channels.mattermost.interactions.callbackBaseUrl: URL base externa opcional para retornos de chamada dos botões (por exemplo, https://gateway.example.com). Use-a quando o Mattermost não puder acessar o Gateway diretamente no host de associação.
• Em configurações com várias contas, também é possível definir o mesmo campo em channels.mattermost.accounts.<id>.interactions.callbackBaseUrl.
• Se interactions.callbackBaseUrl for omitido, o OpenClaw deriva a URL de retorno de chamada de gateway.customBindHost + gateway.port (padrão: 18789) e, em seguida, recorre a http://localhost:<port>. O caminho do retorno de chamada é /mattermost/interactions/<accountId>.
• Regra de acessibilidade: a URL de retorno de chamada do botão deve ser acessível pelo servidor Mattermost. localhost funciona somente quando o Mattermost e o OpenClaw são executados no mesmo host/namespace de rede.
• channels.mattermost.interactions.allowedSourceIps: lista de permissões de IPs de origem para retornos de chamada dos botões. Sem ela, somente origens de loopback (127.0.0.1, ::1) são aceitas; portanto, um servidor Mattermost remoto deve ser incluído nessa lista, caso contrário seus cliques serão rejeitados com 403. Atrás de um proxy reverso, defina também gateway.trustedProxies para que o IP real do cliente seja derivado dos cabeçalhos encaminhados.
• Se o destino do retorno de chamada for privado/da tailnet/interno, adicione seu host/domínio a ServiceSettings.AllowedUntrustedInternalConnections do Mattermost.

• O 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 (exceto _token). O Gateway remove _token e, em seguida, assina tudo o que resta. Assinar apenas um subconjunto causa uma falha silenciosa na verificação.
• Use sort_keys=True — o Gateway ordena as chaves antes de assinar, e o Mattermost pode reordenar os campos de contexto ao armazenar o payload.
• Derive o segredo do token do bot (de forma determinística), não de bytes aleatórios. O segredo deve ser o mesmo no processo que cria os botões e no Gateway que faz a verificação.

Verifique se o bot está 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: as variáveis de ambiente se aplicam somente à conta default.
• Hosts privados/LAN do Mattermost precisam de network.dangerouslyAllowPrivateNetwork: true (a proteção contra SSRF bloqueia IPs privados por padrão).

• Unauthorized: invalid command token.: o OpenClaw não aceitou o token de callback. Causas comuns:
  • o registro do comando de barra falhou ou foi concluído apenas parcialmente na inicialização
  • o callback está chegando ao Gateway ou à conta incorreta
  • o Mattermost ainda tem comandos antigos apontando para um destino de callback anterior
  • o Gateway foi reiniciado sem reativar os comandos de barra
• Se os comandos de barra nativos pararem de funcionar, verifique nos logs a presença 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 uma URL de loopback como http://localhost:18789/..., essa URL provavelmente só poderá ser acessada quando o Mattermost estiver em execução no mesmo host/namespace de rede que o OpenClaw. Em vez disso, defina explicitamente um commands.callbackUrl acessível externamente.

• Os botões aparecem como caixas brancas ou não aparecem: os dados do botão estão malformados. Cada botão de apresentação precisa de um label e de um value (botões sem um deles são descartados).
• Os botões são renderizados, mas os cliques não fazem nada: verifique se o Gateway pode ser acessado pelo servidor do Mattermost, se o IP do servidor do Mattermost está incluído em channels.mattermost.interactions.allowedSourceIps (sem essa configuração, apenas loopback é aceito) e se ServiceSettings.AllowedUntrustedInternalConnections inclui o host do callback para destinos privados.
• Os botões retornam 404 ao serem clicados: o id do botão provavelmente contém hifens ou sublinhados. O roteador de ações do Mattermost falha com IDs que contêm caracteres não alfanuméricos. Use somente [a-zA-Z0-9].
• O Gateway registra rejected callback source: o clique veio de um IP fora de interactions.allowedSourceIps. Adicione o servidor do Mattermost ou seu ingresso à lista de permissões e defina gateway.trustedProxies quando estiver atrás de um proxy reverso.
• O Gateway registra invalid _token: incompatibilidade de HMAC. Verifique se todos os campos de contexto estão sendo assinados (não apenas um subconjunto), use chaves ordenadas e JSON compacto (sem espaços). Consulte a seção sobre HMAC acima.
• O Gateway registra missing _token in context: o campo _token não está no contexto do botão. Certifique-se de incluí-lo ao criar o payload da integração.
• O Gateway rejeita o clique com Unknown action: context.action_id não corresponde a nenhum id de ação na publicação. Defina ambos com o mesmo valor sanitizado.
• O agente não oferece botões: adicione capabilities: ["inlineButtons"] à configuração do canal do Mattermost.