Mattermost

​

Instalação

openclaw plugins install @openclaw/mattermost

openclaw plugins install ./path/to/local/mattermost-plugin

​

Configuração rápida

{
  channels: {
    mattermost: {
      enabled: true,
      botToken: "mm-token",
      baseUrl: "https://chat.example.com",
      dmPolicy: "pairing",
    },
  },
}

openclaw channels add --channel mattermost --bot-token <token> --http-url https://chat.example.com

​

Comandos de barra nativos

{
  channels: {
    mattermost: {
      commands: {
        native: true,
        nativeSkills: true,
        callbackPath: "/api/channels/mattermost/command",
        // Use quando o Mattermost não puder acessar o Gateway diretamente (proxy reverso/URL pública).
        callbackUrl: "https://gateway.example.com/api/channels/mattermost/command",
      },
    },
  },
}

​

Variáveis de ambiente (conta padrão)

• MATTERMOST_BOT_TOKEN=...
• MATTERMOST_URL=https://chat.example.com

​

Modos de chat

{
  channels: {
    mattermost: {
      chatmode: "onchar",
      oncharPrefixes: [">", "!"], // padrão
    },
  },
}

• onchar ainda responde a @menções explícitas.
• channels.mattermost.requireMention ainda é respeitado, mas chatmode é preferível. As configurações groups.<channelId>.requireMention por canal prevalecem sobre ambos.
• Depois que o bot envia uma resposta visível em uma thread de canal, as mensagens posteriores nessa mesma thread são respondidas sem uma nova @menção ou prefixo onchar, permitindo que as conversas de vários turnos na thread continuem fluindo. A participação é lembrada por 7 dias após a última resposta do bot nessa thread e persiste após reinicializações do Gateway. Threads que o bot apenas observou não são afetadas; inicie uma nova mensagem no nível superior para voltar a exigir uma menção explícita.

​

Threads e sessões

• off (padrão): responde em uma thread somente quando a publicação recebida já está em uma.
• first: para publicações de canal/grupo no nível superior, inicia uma thread sob essa publicação e encaminha a conversa para uma sessão com escopo de thread.
• all e batched: atualmente têm o mesmo comportamento que first no Mattermost, pois, depois que o Mattermost tem uma raiz de thread, os trechos e as mídias subsequentes continuam nessa mesma thread.
• As mensagens diretas usam off por padrão, mesmo quando replyToMode está definido.

• off (padrão): as mensagens diretas permanecem sem threads em uma única sessão contínua.
• first, all ou batched: cada mensagem direta no nível superior inicia uma thread do Mattermost respaldada por uma sessão nova e independente.

{
  channels: {
    mattermost: {
      replyToMode: "all",
      replyToModeByChatType: {
        direct: "first",
      },
    },
  },
}

• As sessões com escopo de thread usam o ID da publicação acionadora como raiz da thread.
• first e all são atualmente equivalentes porque, depois que o Mattermost tem uma raiz de thread, os trechos e as mídias subsequentes continuam nessa mesma thread.
• As substituições por tipo de conversa prevalecem sobre replyToMode. Sem uma substituição direct, as implantações existentes mantêm DMs lineares, sem threads.

​

Controle de acesso (DMs)

• Padrão: channels.mattermost.dmPolicy = "pairing" (remetentes desconhecidos recebem um código de pareamento). Outros valores: allowlist, open, disabled.
• Aprove por meio de:
  • openclaw pairing list mattermost
  • openclaw pairing approve mattermost <CODE>
• DMs públicas: channels.mattermost.dmPolicy="open" mais channels.mattermost.allowFrom=["*"] (o esquema de configuração exige o curinga).
• channels.mattermost.allowFrom aceita IDs de usuário (recomendado) e entradas accessGroup:<name>. Consulte Grupos de acesso.

​

Canais (grupos)

• Padrão: channels.mattermost.groupPolicy = "allowlist" (exige menção).
• Inclua remetentes na lista de permissões com channels.mattermost.groupAllowFrom (recomenda-se usar IDs de usuário).
• channels.mattermost.groupAllowFrom aceita entradas accessGroup:<name>. Consulte Grupos de acesso.
• As substituições de menção por canal ficam em channels.mattermost.groups.<channelId>.requireMention ou em channels.mattermost.groups["*"].requireMention para um padrão.
• A correspondência de @username é mutável e só é ativada quando channels.mattermost.dangerouslyAllowNameMatching: true.
• Canais abertos: channels.mattermost.groupPolicy="open" (exige menção).
• Ordem de resolução: channels.mattermost.groupPolicy, depois channels.defaults.groupPolicy e, por fim, "allowlist".
• Observação de runtime: se a seção channels.mattermost estiver completamente ausente, o runtime falhará de forma fechada usando groupPolicy="allowlist" nas verificações de grupo (mesmo que channels.defaults.groupPolicy esteja definido) e registrará um aviso uma única vez.

{
  channels: {
    mattermost: {
      groupPolicy: "open",
      groups: {
        "*": { requireMention: true },
        "team-channel-id": { requireMention: false },
      },
    },
  },
}

​

Destinos para entrega de saída

​

Nova tentativa do canal de DM

{
  channels: {
    mattermost: {
      dmChannelRetry: {
        maxRetries: 3,
        initialDelayMs: 1000,
        maxDelayMs: 10000,
        timeoutMs: 30000,
      },
    },
  },
}

• Isso se aplica somente à criação de canais de MD (/api/v4/channels/direct), não a todas as chamadas à API do Mattermost.
• As novas tentativas usam espera exponencial com jitter e se aplicam a falhas transitórias, como limites de taxa, respostas 5xx e erros de rede ou de tempo limite.
• Erros 4xx do cliente diferentes de 429 são tratados como permanentes e não são tentados novamente.

​

Streaming de pré-visualização

{
  channels: {
    mattermost: {
      streaming: { mode: "partial" }, // off | partial | block | progress
    },
  },
}

​

Reações (ferramenta de mensagens)

• Use message action=react com channel=mattermost.
• messageId é o ID da publicação do Mattermost.
• emoji aceita nomes como thumbsup ou :+1: (os dois-pontos são opcionais).
• Defina remove=true (booleano) para remover uma reação.
• Os eventos de adição/remoção de reações são encaminhados como eventos de sistema para a sessão roteada do agente, sujeitos às mesmas verificações de política de MD/grupo aplicadas às mensagens.

message action=react channel=mattermost target=channel:<channelId> messageId=<postId> emoji=thumbsup
message action=react channel=mattermost target=channel:<channelId> messageId=<postId> emoji=thumbsup remove=true

• channels.mattermost.actions.reactions: ativa/desativa ações de reação (padrão: true).
• Substituição por conta: channels.mattermost.accounts.<id>.actions.reactions.

​

Botões interativos (ferramenta de mensagens)

message action=send channel=mattermost target=channel:<channelId> presentation={"blocks":[{"type":"buttons","buttons":[{"label":"Yes","value":"yes"},{"label":"No","value":"no"}]}]}

{
  channels: {
    mattermost: {
      capabilities: ["inlineButtons"],
    },
  },
}

​

Integração direta com a API (scripts externos)

{
  channel_id: "<channelId>",
  message: "Escolha uma opção:",
  props: {
    attachments: [
      {
        actions: [
          {
            id: "mybutton01", // somente alfanumérico - veja abaixo
            type: "button", // obrigatório, caso contrário os cliques são ignorados silenciosamente
            name: "Aprovar", // rótulo de exibição
            style: "primary", // opcional: "default", "primary", "danger"
            integration: {
              url: "https://gateway.example.com/mattermost/interactions/default",
              context: {
                action_id: "mybutton01", // deve corresponder ao ID do botão
                action: "approve",
                // ... quaisquer campos personalizados ...
                _token: "<hmac>", // consulte a seção sobre HMAC abaixo
              },
            },
          },
        ],
      },
    ],
  },
}

import hmac, hashlib, json

secret = hmac.new(
    b"openclaw-mattermost-interactions",
    bot_token.encode(), hashlib.sha256
).hexdigest()

ctx = {"action_id": "mybutton01", "action": "approve"}
payload = json.dumps(ctx, sort_keys=True, separators=(",", ":"))
token = hmac.new(secret.encode(), payload.encode(), hashlib.sha256).hexdigest()

context = {**ctx, "_token": token}

​

Adaptador de diretório

​

Várias contas

{
  channels: {
    mattermost: {
      accounts: {
        default: { name: "Primary", botToken: "mm-token", baseUrl: "https://chat.example.com" },
        alerts: { name: "Alerts", botToken: "mm-token-2", baseUrl: "https://alerts.example.com" },
      },
    },
  },
}

​

Solução de problemas

​

Relacionados

• Roteamento de canais — roteamento de sessões para mensagens
• Visão geral dos canais — todos os canais compatíveis
• Grupos — comportamento de chats em grupo e controle por menção
• Emparelhamento — autenticação de mensagens diretas e fluxo de emparelhamento
• Segurança — modelo de acesso e reforço de segurança