Mattermost

• native: "auto" usa desabilitado por padrão para Mattermost. Defina native: true para habilitar.
• 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 de comandos atual 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 de callback falha de modo fechado se a API do Mattermost não puder confirmar que o comando ainda é atual; validações com falha são armazenadas brevemente em cache, consultas simultâneas são coalescidas, e inícios de novas consultas têm limite de taxa por comando para conter pressão de repetição.
• Callbacks de barra falham de modo fechado 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 pode chegar à 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 rode 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 seu 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.

• Bom: gateway.tailnet-name.ts.net
• Ruim: https://gateway.tailnet-name.ts.net

• partial é a escolha usual: uma publicação de pré-visualização que é editada conforme a resposta cresce e depois finalizada com a resposta completa.
• block usa blocos de rascunho em estilo de anexação dentro da publicação de pré-visualização.
• progress mostra uma pré-visualização de status durante a geração e só publica a resposta final na conclusão.
• off desabilita o streaming de pré-visualização.

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

• Os callbacks de botão usam verificação HMAC-SHA256 (automática, sem necessidade de configuração).
• O Mattermost remove dados de callback das respostas da API dele (recurso de segurança), então todos os botões são removidos no clique - a remoção parcial não é possível.
• IDs de ação que contêm hífens ou sublinhados são higienizados automaticamente (limitação de roteamento do Mattermost).

• channels.mattermost.capabilities: array de strings de capacidade. Adicione "inlineButtons" para habilitar a descrição da ferramenta de botões no prompt de sistema do agente.
• channels.mattermost.interactions.callbackBaseUrl: URL base externa opcional para callbacks de botão (por exemplo https://gateway.example.com). Use isso quando o Mattermost não conseguir alcançar o Gateway diretamente no host de vinculação 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 recorre a http://localhost:<port>.
• Regra de acessibilidade: a URL de callback do botão precisa estar acessível a partir do servidor Mattermost. localhost só funciona quando Mattermost e OpenClaw são executados no mesmo host/namespace de rede.
• Se o destino do seu callback for privado/tailnet/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 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 as chaves antes de assinar, e o Mattermost pode reordenar campos de contexto ao armazenar o payload.
• Derive o segredo do token do bot (determinístico), não de bytes aleatórios. O segredo deve ser o mesmo entre o processo que cria os botões e o Gateway que verifica.

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

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

• Unauthorized: invalid command token.: o OpenClaw não aceitou o token de callback. Causas típicas:
  • o registro de comando de barra falhou ou foi concluído apenas parcialmente na inicialização
  • o callback está atingindo o Gateway/conta errado
  • o Mattermost ainda tem comandos antigos apontando para um destino de callback anterior
  • o Gateway reiniciou sem reativar comandos de barra
• Se os comandos de barra nativos pararem de funcionar, verifique os logs para 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ó será acessível quando o Mattermost for executado no mesmo host/namespace de rede que o OpenClaw. Defina uma commands.callbackUrl explícita e acessível externamente em vez disso.

• Os 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.
• Os botões são renderizados, mas os 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.
• Os botões retornam 404 no clique: o id do botão provavelmente contém hífens ou sublinhados. O roteador de ações do Mattermost quebra em IDs não alfanuméricos. Use somente [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). Consulte a seção HMAC acima.
• Logs do Gateway mostram missing _token in context: o campo _token não está no contexto do botão. Garanta que ele esteja incluído ao montar 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 para o mesmo valor higienizado.
• O agente não sabe sobre botões: adicione capabilities: ["inlineButtons"] à configuração do canal Mattermost.