Mattermost

• O padrão de native e nativeSkills é "auto", que resulta em desabilitado para o Mattermost. Defina-os explicitamente como true.
• O padrão de callbackPath é /api/channels/mattermost/command.
• Se callbackUrl for omitida, o OpenClaw deriva http://<gateway.customBindHost ou localhost>:<gateway.port, padrão 18789><callbackPath>. Hosts de associação curinga (0.0.0.0, ::) usam localhost como alternativa.
• 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 gatilho, criados por outras integrações, permanecem inalterados (o registro os ignora); os comandos criados pelo bot são atualizados ou recriados quando a URL de callback diverge.
• Os callbacks de comandos são validados com os tokens específicos de cada comando retornados pelo Mattermost quando o OpenClaw registra os comandos oc_*.
• O OpenClaw atualiza o registro atual de comandos do Mattermost antes de aceitar cada callback; assim, tokens obsoletos de comandos de barra excluídos ou gerados novamente deixam de ser aceitos sem reiniciar o Gateway.
• A validação do callback falha de modo seguro 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, consultas simultâneas são agrupadas e o início de novas consultas tem limite de frequência por comando para restringir a pressão de repetição.
• Os callbacks de barra falham de modo seguro quando o registro falha, a inicialização é 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 a partir do 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 use um proxy reverso para encaminhar /api/channels/mattermost/command ao 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, não 404.

Se o callback tiver como destino endereços privados/da 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évia que é editada à medida que a resposta cresce e, em seguida, finalizada com a resposta completa.
• block alterna a prévia entre blocos de texto concluído e 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 paralelas e consecutivas de ferramentas compartilham a publicação atual de atividade das ferramentas.
• progress exibe uma prévia de status durante a geração e publica a resposta final somente após a conclusão.
• off desativa a transmissão da prévia. Com blockStreaming: 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 não for possível finalizar a transmissão no próprio lugar (por exemplo, se a publicação for excluída durante a transmissão), 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 Transmissão para ver a matriz de mapeamento de canais.

• Os retornos de chamada dos botões usam verificação HMAC-SHA256 (automática, sem necessidade de configuração).
• 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 que contêm hífens ou sublinhados são higienizadas 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 ("Unknown action").

• 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 de botões (por exemplo, https://gateway.example.com). Use-a quando o Mattermost não puder acessar diretamente o Gateway pelo host ao qual ele está vinculado.
• 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 derivará a URL de retorno de chamada de gateway.customBindHost + gateway.port (padrão: 18789) e, em seguida, recorrerá 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 estar acessível a partir do servidor Mattermost. localhost funciona somente quando o Mattermost e o OpenClaw são executados no mesmo host/espaço de nomes de rede.
• channels.mattermost.interactions.allowedSourceIps: lista de IPs de origem permitidos para retornos de chamada de 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, ou 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 obtido dos cabeçalhos encaminhados.
• Se o destino do retorno de chamada for privado, da tailnet ou interno, adicione o host/domínio dele 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 do contexto (menos _token). O Gateway remove _token e depois assina tudo o que restar. Assinar apenas um subconjunto causa uma falha silenciosa de verificação.
• Use sort_keys=True — o Gateway ordena as chaves antes da assinatura, e o Mattermost pode reordenar os campos de contexto ao armazenar a carga.
• 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 Mattermost privados/da LAN 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 retorno de chamada. Causas comuns:
  • o registro do comando de barra falhou ou foi concluído apenas parcialmente na inicialização
  • o retorno de chamada está chegando ao gateway/à conta incorretos
  • o Mattermost ainda tem comandos antigos apontando para um destino de retorno de chamada anterior
  • o Gateway foi reiniciado sem reativar os comandos de barra
• Se os 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 retorno de chamada foi resolvido para uma URL de local loopback como http://localhost:18789/..., essa URL provavelmente só será acessível quando o Mattermost estiver em execução no mesmo host/espaço de nomes 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 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 está acessível pelo servidor Mattermost, se o IP do servidor Mattermost está incluído em channels.mattermost.interactions.allowedSourceIps (sem isso, somente local loopback é aceito) e se ServiceSettings.AllowedUntrustedInternalConnections inclui o host de retorno de chamada 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 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 Mattermost ou seu ponto de entrada à 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 são 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 a carga útil 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 Mattermost.