Mattermost

Status: Plugin baixável (token de bot + eventos WebSocket). Canais, grupos e DMs são compatíveis. Mattermost é uma plataforma auto-hospedável de mensagens para equipes; consulte o site oficial em mattermost.com para detalhes do produto e downloads.

# Instalar

Instale o Mattermost antes de configurar o canal:

openclaw plugins install @openclaw/mattermost

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

Detalhes: Plugins

# Configuração rápida

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

# Comandos slash nativos

Comandos slash nativos são opcionais. Quando ativados, o OpenClaw registra comandos slash oc_* por meio da API do Mattermost e recebe POSTs de callback no servidor HTTP do Gateway.

{
  channels: {
    mattermost: {
      commands: {
        native: true,
        nativeSkills: true,
        callbackPath: "/api/channels/mattermost/command",
        // Use when Mattermost cannot reach the gateway directly (reverse proxy/public URL).
        callbackUrl: "https://gateway.example.com/api/channels/mattermost/command",
      },
    },
  },
}

# Variáveis de ambiente (conta padrão)

Defina estas no host do Gateway se preferir variáveis de ambiente:

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

# Modos de chat

Mattermost responde a DMs automaticamente. O comportamento em canais é controlado por chatmode:

Exemplo de configuração:

{
  channels: {
    mattermost: {
      chatmode: "onchar",
      oncharPrefixes: [">", "!"],
    },
  },
}

Notas:

• onchar ainda responde a @menções explícitas.
• channels.mattermost.requireMention é respeitado para configurações legadas, mas chatmode é preferível.

# Threads e sessões

Use channels.mattermost.replyToMode para controlar se respostas em canais e grupos permanecem no canal principal ou iniciam uma thread sob a postagem acionadora.

• off (padrão): responde em uma thread somente quando a postagem de entrada já estiver em uma.
• first: para postagens de canal/grupo no nível superior, inicia uma thread sob essa postagem e encaminha a conversa para uma sessão com escopo de thread.
• all: mesmo comportamento que first para Mattermost atualmente.
• Mensagens diretas ignoram esta configuração e permanecem sem thread.

Exemplo de configuração:

{
  channels: {
    mattermost: {
      replyToMode: "all",
    },
  },
}

Notas:

• Sessões com escopo de thread usam o id da postagem acionadora como raiz da thread.
• first e all são atualmente equivalentes porque, quando o Mattermost tem uma raiz de thread, chunks de acompanhamento e mídia continuam nessa mesma thread.

# Controle de acesso (DMs)

• Padrão: channels.mattermost.dmPolicy = "pairing" (remetentes desconhecidos recebem um código de pareamento).
• Aprove via:
  • openclaw pairing list mattermost
  • openclaw pairing approve mattermost <CODE>
• DMs públicas: channels.mattermost.dmPolicy="open" mais channels.mattermost.allowFrom=["*"].

# Canais (grupos)

• Padrão: channels.mattermost.groupPolicy = "allowlist" (controlado por menção).
• Permita remetentes com channels.mattermost.groupAllowFrom (IDs de usuário recomendados).
• Substituições de menção por canal ficam em channels.mattermost.groups.<channelId>.requireMention ou 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" (controlado por menção).
• Nota de runtime: se channels.mattermost estiver completamente ausente, o runtime volta para groupPolicy="allowlist" em verificações de grupo (mesmo que channels.defaults.groupPolicy esteja definido).

Exemplo:

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

# Destinos para entrega de saída

Use estes formatos de destino com openclaw message send ou cron/webhooks:

• channel:<id> para um canal
• user:<id> para uma DM
• @username para uma DM (resolvido pela API do Mattermost)

# Nova tentativa de canal de DM

Quando o OpenClaw envia para um destino de DM do Mattermost e precisa resolver o canal direto primeiro, ele tenta novamente falhas transitórias de criação de canal direto por padrão.

Use channels.mattermost.dmChannelRetry para ajustar esse comportamento globalmente para o Plugin Mattermost, ou channels.mattermost.accounts.<id>.dmChannelRetry para uma conta.

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

Notas:

• Isso se aplica apenas à criação de canal de DM (/api/v4/channels/direct), não a todas as chamadas da API do Mattermost.
• Novas tentativas se aplicam a falhas transitórias, como limites de taxa, respostas 5xx e erros de rede ou timeout.
• Erros de cliente 4xx diferentes de 429 são tratados como permanentes e não são tentados novamente.

# Streaming de pré-visualização

Mattermost transmite raciocínio, atividade de ferramentas e texto parcial de resposta para uma única postagem de pré-visualização de rascunho, que é finalizada no lugar quando a resposta final é segura para enviar. A pré-visualização é atualizada no mesmo id de postagem em vez de encher o canal com mensagens por chunk. Finais de mídia/erro cancelam edições de pré-visualização pendentes e usam entrega normal em vez de descarregar uma postagem de pré-visualização descartável.

Ative via channels.mattermost.streaming:

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

# Reações (ferramenta de mensagem)

• Use message action=react com channel=mattermost.
• messageId é o id da postagem do Mattermost.
• emoji aceita nomes como thumbsup ou :+1: (dois-pontos são opcionais).
• Defina remove=true (booleano) para remover uma reação.
• Eventos de adição/remoção de reação são encaminhados como eventos de sistema para a sessão do agente roteada.

Exemplos:

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

Configuração:

• 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 mensagem)

Envie mensagens com botões clicáveis. Quando um usuário clica em um botão, o agente recebe a seleção e pode responder.

Ative botões adicionando inlineButtons às capacidades do canal:

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

Use message action=send com um parâmetro buttons. Botões são um array 2D (linhas de botões):

message action=send channel=mattermost target=channel:<channelId> buttons=[[{"text":"Yes","callback_data":"yes"},{"text":"No","callback_data":"no"}]]

Campos de botão:

Quando um usuário clica em um botão:

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

Scripts externos e webhooks podem publicar botões diretamente pela API REST do Mattermost em vez de passar pela ferramenta message do agente. Use buildButtonAttachments() do Plugin quando possível; se publicar JSON bruto, siga estas regras:

Estrutura do payload:

{
  channel_id: "<channelId>",
  message: "Choose an option:",
  props: {
    attachments: [
      {
        actions: [
          {
            id: "mybutton01", // alphanumeric only - see below
            type: "button", // required, or clicks are silently ignored
            name: "Approve", // display label
            style: "primary", // optional: "default", "primary", "danger"
            integration: {
              url: "https://gateway.example.com/mattermost/interactions/default",
              context: {
                action_id: "mybutton01", // must match button id (for name lookup)
                action: "approve",
                // ... any custom fields ...
                _token: "<hmac>", // see HMAC section below
              },
            },
          },
        ],
      },
    ],
  },
}

Geração de token HMAC

O Gateway verifica cliques em botões com HMAC-SHA256. Scripts externos devem gerar tokens que correspondam à lógica de verificação do Gateway:

Exemplo em Python:

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

O Plugin do Mattermost inclui um adaptador de diretório que resolve nomes de canais e usuários pela API do Mattermost. Isso habilita destinos #channel-name e @username em openclaw message send e entregas de cron/webhook.

Nenhuma configuração é necessária - o adaptador usa o token do bot da configuração da conta.

# Várias contas

O Mattermost oferece suporte a várias contas em channels.mattermost.accounts:

{
  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

# Relacionado

• Roteamento de canais - roteamento de sessões para mensagens
• Visão geral dos canais - todos os canais compatíveis
• Grupos - comportamento de chat em grupo e bloqueio por menção
• Pareamento - autenticação de DM e fluxo de pareamento
• Segurança - modelo de acesso e hardening