OpenClaw

Canal Matrix do OpenClaw

Descentralizado
Médio

Conecte o OpenClaw ao Matrix — um protocolo de comunicação aberto e federado. Esta integração permite que seu assistente de IA participe de salas Matrix e mensagens diretas através de qualquer servidor doméstico (matrix.org, Element ou auto-hospedado). O OpenClaw se conecta através da API Matrix Client-Server com suporte opcional de criptografia de ponta a ponta (E2EE) através do SDK de criptografia Rust. O canal Matrix é fornecido como plugin e suporta federação, threads, reações e mídia rica.

Info rápida
DificuldadeMédio
CategoriaDescentralizado
Recursos suportados5 / 6

Matrix Recursos suportados

Mensagens de texto

Suportado

Mídia e arquivos

Suportado

Reações

Suportado

Threads

Suportado

Mensagens de voz

Não suportado

Chat em grupo

Suportado

Matrix Pré-requisitos

  • Uma conta Matrix ativa em qualquer servidor doméstico (matrix.org, Element ou auto-hospedado)
  • O plugin Matrix instalado: openclaw plugins install @openclaw/matrix
  • OpenClaw Gateway em execução e configurado
  • Node.js 18+ instalado no seu servidor

Matrix Configuração rápida

1

Instalar o plugin Matrix

O canal Matrix é fornecido como plugin separado. Instale-o através de 'openclaw plugins install @openclaw/matrix'. O plugin será baixado do registro npm e habilitado automaticamente.

2

Obter credenciais do Matrix

Você precisa de um token de acesso ou usuário/senha. Para tokens de acesso: use curl para chamar o endpoint de login do seu servidor doméstico e copie o token. Para usuário/senha: o Gateway fará login automaticamente e armazenará o token em ~/.openclaw/credentials/matrix/credentials.json.

3

Adicionar configuração do canal Matrix

Adicione a configuração do canal Matrix em ~/.openclaw/openclaw.json com a URL do seu servidor doméstico e credenciais. Você também pode usar variáveis de ambiente MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN, MATRIX_USER_ID e MATRIX_PASSWORD.

4

Iniciar Gateway e testar

Execute 'openclaw gateway' para iniciar o serviço. Envie uma mensagem direta para seu usuário bot Matrix de outra conta. Se estiver usando a política de emparelhamento padrão, aprove o remetente através de 'openclaw pairing approve matrix <code>' no seu terminal.

Matrix Exemplo de configuração

config.json
{
  "channels": {
    "matrix": {
      "enabled": true,
      "homeserver": "https://matrix.org",
      "accessToken": "your_access_token_here",
      "dmPolicy": "pairing"
    }
  }
}

Matrix Documentação Detalhada

Visão geral da arquitetura

O OpenClaw se conecta ao Matrix através da API Client-Server, agindo como um cliente Matrix padrão. A arquitetura é baseada em eventos: seu bot recebe eventos (mensagens, reações, mudanças de associação) através de solicitações de sincronização de polling longo, processa-os com sua IA e envia respostas de volta através da API. O Matrix é federado, o que significa que seu bot pode se comunicar com usuários em qualquer servidor doméstico na rede global Matrix — não apenas no servidor doméstico onde a conta do seu bot está registrada. Isso é fundamentalmente diferente de plataformas centralizadas como WhatsApp ou Telegram. O fluxo é: Usuário envia mensagem no Matrix → Servidor doméstico roteia para seu Gateway via sync → OpenClaw processa com IA → resposta enviada via API de envio de eventos → mensagem entregue através de federação.
Federação significa que seu bot no matrix.org pode conversar com usuários em qualquer servidor doméstico Matrix (por exemplo, element.io, servidor da Mozilla ou instâncias auto-hospedadas).
O plugin Matrix usa polling longo por padrão. Não há necessidade de webhooks ou URLs públicas — o Gateway se conecta de forma externa ao seu servidor doméstico.

Métodos de autenticação

O OpenClaw suporta duas abordagens de autenticação para Matrix: 1. **Token de acesso (recomendado)** — Obtenha um token chamando a API de login do seu servidor doméstico usando curl ou um cliente Matrix. Configure channels.matrix.accessToken na sua configuração. O sistema obtém automaticamente seu ID de usuário através do endpoint /whoami. 2. **Usuário/Senha** — Configure channels.matrix.userId e channels.matrix.password. O OpenClaw chama automaticamente o endpoint de login e armazena o token de acesso em ~/.openclaw/credentials/matrix/credentials.json. Variáveis de ambiente têm precedência sobre arquivos de configuração: MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN, MATRIX_USER_ID, MATRIX_PASSWORD.
openclaw.json
# Método com token de acesso
{
  "channels": {
    "matrix": {
      "homeserver": "https://matrix.example.org",
      "accessToken": "syt_xxx..."
    }
  }
}

# Método com usuário/senha
{
  "channels": {
    "matrix": {
      "homeserver": "https://matrix.example.org",
      "userId": "@bot:example.org",
      "password": "your_password"
    }
  }
}
Nunca faça commit de tokens de acesso ou senhas no controle de versão. Use variáveis de ambiente para implantações de produção. Se seu token estiver comprometido, faça logout de todos os dispositivos através do seu cliente Matrix para invalidar todos os tokens e então gere um novo.

Políticas de mensagens diretas

Políticas de mensagens diretas controlam quem pode interagir com seu assistente de IA. O OpenClaw suporta quatro políticas: • pairing (padrão) — Usuários desconhecidos recebem um código de emparelhamento no primeiro contato. Aprove através de 'openclaw pairing approve matrix <CODE>' para conceder acesso. Uma vez aprovado, o usuário pode conversar livremente. • allowlist — Apenas IDs de usuário Matrix listados explicitamente em channels.matrix.dm.allowFrom podem enviar mensagens ao bot. Todos os outros são silenciosamente ignorados. • open — Qualquer pessoa que enviar mensagem ao bot recebe uma resposta. Requer allowFrom: ["*"]. Use com cautela. • disabled — Manipulação de mensagens diretas está completamente desativada. Allowlists aceitam IDs de usuário Matrix completos no formato @user:server (por exemplo, @alice:matrix.org).
openclaw.json
{
  "channels": {
    "matrix": {
      "dmPolicy": "allowlist",
      "dm": {
        "allowFrom": ["@alice:matrix.org", "@bob:example.org"]
      }
    }
  }
}

Suporte para chat em grupo (salas)

Conversas em grupo do Matrix são chamadas de "salas". Por padrão, o OpenClaw usa uma política de allowlist para salas, exigindo ativação baseada em menção. Você pode configurar em quais salas o bot participa e como ele responde. Salas são identificadas por IDs de sala (!roomId:server) ou apelidos de sala (#alias:server). Você pode configurar definições específicas por sala como comportamento de entrada automática, requisitos de menção e allowlists de usuários por sala.
openclaw.json
{
  "channels": {
    "matrix": {
      "groupPolicy": "allowlist",
      "groups": {
        "!abc123:matrix.org": {
          "allow": true,
          "requireMention": false,
          "users": ["@alice:matrix.org"]
        },
        "#team-chat:example.org": {
          "allow": true
        }
      },
      "autoJoin": "allowlist"
    }
  }
}
Configure autoJoin para 'always' para aceitar automaticamente todos os convites de sala, 'allowlist' para entrar apenas em salas configuradas, ou 'off' para ignorar convites.
Use requireMention: false para habilitar respostas automáticas sem mencionar o bot. Tenha cautela em salas de alto tráfego.

Criptografia de ponta a ponta (E2EE)

O Matrix suporta criptografia de ponta a ponta (E2EE) através dos protocolos Olm e Megolm. O OpenClaw pode participar de salas criptografadas quando você habilita a criptografia através do SDK de criptografia Rust. Quando habilitado, o sistema descriptografa automaticamente mensagens criptografadas, criptografa mídias de saída em salas protegidas e armazena o estado criptográfico em ~/.openclaw/matrix/accounts/ (SQLite). Verificação de dispositivo é necessária na primeira conexão — aprove a solicitação de verificação no Element ou outro cliente Matrix para habilitar o compartilhamento de chaves. Se os módulos de criptografia falharem ao carregar, E2EE é desabilitado e salas criptografadas permanecem inacessíveis.
openclaw.json
{
  "channels": {
    "matrix": {
      "encryption": true
    }
  }
}
Alterar tokens de acesso requer re-verificação de dispositivo. Mantenha backups do seu diretório de estado criptográfico (~/.openclaw/matrix/accounts/) para prevenir perda de acesso ao histórico de mensagens criptografadas.

Federação e seleção de servidor doméstico

O Matrix é um protocolo federado — não há um único servidor central. Você pode escolher registrar seu bot em qualquer servidor doméstico: • **matrix.org** — O servidor doméstico principal mantido pela Fundação Matrix. Registro aberto, alta confiabilidade, mas pode ser mais lento devido ao alto tráfego. • **Element Matrix Services** — Servidores domésticos hospedados profissionalmente em element.io com recursos premium e suporte. • **Auto-hospedado** — Execute seu próprio servidor doméstico para máximo controle e privacidade. O Synapse é a opção mais madura e ativamente desenvolvida. Dendrite (Go) e Conduit (Rust) são alternativas mais leves adequadas para implantações menores, embora ambos estejam agora em modo de manutenção ou desenvolvimento limitado. Seu bot pode se comunicar com usuários em qualquer servidor doméstico independentemente de onde está registrado, graças à federação.
Para implantações de produção, considere usar um servidor doméstico auto-hospedado ou Element Matrix Services para melhor controle e desempenho.
A federação funciona de forma transparente — os usuários não precisam saber em qual servidor doméstico seu bot está.

Threads e modos de resposta

O Matrix suporta conversas em threads através do tipo de relação m.thread. O OpenClaw pode participar de threads e controlar como manipula respostas. A configuração threadReplies controla o comportamento de threads: 'off' desabilita o suporte a threads, 'inbound' apenas lê o contexto de threads, e 'always' lê e cria respostas em threads. A configuração replyToMode controla a anexação de metadados para relacionamentos de resposta.
openclaw.json
{
  "channels": {
    "matrix": {
      "threadReplies": "always",
      "replyToMode": "reference"
    }
  }
}

Manipulação de mídia e upload de arquivos

O Matrix suporta mídia rica incluindo imagens, vídeos, áudio e documentos. O OpenClaw manipula automaticamente uploads de mídia — arquivos são enviados para o repositório de mídia do seu servidor doméstico e referenciados em eventos de mensagem. Você pode configurar tamanhos máximos de arquivo através da configuração mediaMaxMb. O padrão é 50 MB para mídia de entrada, com otimização JPEG automática e redimensionamento para imagens muito grandes em envios de saída.
openclaw.json
{
  "channels": {
    "matrix": {
      "mediaMaxMb": 50
    }
  }
}
Uploads de mídia são armazenados no seu servidor doméstico. Se você estiver usando um servidor doméstico público como matrix.org, esteja atento aos limites de armazenamento e termos de serviço.

Reações e recursos ricos

O OpenClaw suporta reações Matrix (respostas emoji a mensagens), enquetes, compartilhamento de localização (formato geo URI) e outros recursos ricos. Reações podem ser enviadas e lidas através de ferramentas se habilitadas. Você pode restringir operações específicas através da configuração actions, limitando o que seu agente de IA pode fazer (reações, mensagens, pins, informações de membros/canal).
openclaw.json
{
  "channels": {
    "matrix": {
      "actions": {
        "reactions": true,
        "messages": true,
        "pins": false
      }
    }
  }
}

Por que Matrix para IA auto-hospedada?

O Matrix é uma excelente escolha para assistentes de IA auto-hospedados porque: • **Verdadeiramente aberto** — Especificação aberta, sem dependência de fornecedor, múltiplas implementações de cliente e servidor. • **Federado** — Sem ponto único de controle ou falha. Seu bot pode se comunicar através da rede global Matrix. • **Focado em privacidade** — Suporte E2EE, opções auto-hospedadas e sem coleta de dados centralizada. • **Recursos ricos** — Threads, reações, mídia, enquetes e tipos de eventos extensíveis. • **Não requer número de telefone** — Ao contrário de WhatsApp ou Signal, o Matrix não requer um número de telefone para registro. O compromisso é a complexidade: o modelo de federação do Matrix e a configuração E2EE podem ser mais complexos que plataformas centralizadas. Para usuários e equipes conscientes da privacidade, esse compromisso vale a pena.

Matrix Referência de Configuração

enabled
Type: booleanDefault: true

Habilitar ou desabilitar o canal Matrix

homeserver
Type: stringDefault: "https://matrix.org"

URL do servidor doméstico Matrix (por exemplo, https://matrix.org, https://element.io)

accessToken
Type: stringDefault: ""

Token de acesso Matrix para autenticação (método recomendado)

userId
Type: stringDefault: ""

ID de usuário Matrix (por exemplo, @bot:matrix.org) — usado com autenticação por senha

password
Type: stringDefault: ""

Senha da conta Matrix — usado com userId para login

encryption
Type: booleanDefault: false

Habilitar criptografia de ponta a ponta através do SDK de criptografia Rust

dmPolicy
Type: stringDefault: "pairing"

Política de acesso a mensagens diretas: pairing, allowlist, open ou disabled

dm.allowFrom
Type: arrayDefault: []

IDs de usuário Matrix permitidos para mensagens diretas (por exemplo, [@alice:matrix.org])

groupPolicy
Type: stringDefault: "allowlist"

Política de salas: allowlist ou disabled

groups
Type: objectDefault: {}

Configuração específica por sala (ID ou apelido de sala como chave)

groups.<roomId>.allow
Type: booleanDefault: false

Permitir ao bot participar desta sala

groups.<roomId>.requireMention
Type: booleanDefault: true

Exigir menção ao bot para acionar respostas nesta sala

groups.<roomId>.users
Type: arrayDefault: []

Allowlist de usuários específica por sala (IDs de usuário Matrix)

autoJoin
Type: stringDefault: "allowlist"

Entrar automaticamente em convites de sala: always, allowlist ou off

textChunkLimit
Type: numberDefault: 4096

Máximo de caracteres por mensagem de saída

chunkMode
Type: stringDefault: "length"

Como dividir respostas longas: length (limite rígido) ou newline (limites de parágrafo)

threadReplies
Type: stringDefault: "inbound"

Comportamento de threads: off, inbound (apenas leitura) ou always (ler + criar)

replyToMode
Type: stringDefault: "reference"

Modo de anexação de metadados de resposta

mediaMaxMb
Type: numberDefault: 50

Tamanho máximo de arquivo de mídia em megabytes

actions.reactions
Type: booleanDefault: true

Permitir ao agente enviar/ler reações

actions.messages
Type: booleanDefault: true

Permitir ao agente ler/enviar/editar/excluir mensagens

actions.pins
Type: booleanDefault: true

Permitir ao agente fixar/desafixar mensagens

actions.memberInfo
Type: booleanDefault: true

Permitir ao agente consultar informações de membros da sala

actions.channelInfo
Type: booleanDefault: true

Permitir ao agente obter informações de sala/canal

Matrix Perguntas Frequentes

Matrix Solução de Problemas

Bot não está recebendo mensagens

Política de mensagens diretas bloqueando mensagens, ou bot não está na sala

Verifique as configurações channels.matrix.dmPolicy e dm.allowFrom. Para salas, certifique-se de que a sala esteja na sua allowlist de groups e que o bot tenha sido convidado e entrado.
Salas criptografadas E2EE não mostram mensagens

Dispositivo não verificado ou módulos de criptografia falharam ao carregar

Verifique o dispositivo do seu bot no Element ou outro cliente Matrix. Verifique os logs para erros de carregamento de módulos de criptografia. Certifique-se de que channels.matrix.encryption está configurado para true.
Token de acesso inválido ou expirado

Token foi revogado ou invalidado no servidor doméstico

Gere um novo token de acesso fazendo login novamente. Se estiver usando usuário/senha, exclua ~/.openclaw/credentials/matrix/credentials.json e reinicie o Gateway.
Bot entra na sala mas não responde

Sala não está na allowlist ou requireMention está habilitado

Adicione a sala a channels.matrix.groups com allow: true. Se requireMention for true, usuários devem mencionar o bot para obter uma resposta.
Erros de federação com outros servidores domésticos

Problemas de conectividade ou federação do servidor doméstico

Verifique o status de federação do seu servidor doméstico em federationtester.matrix.org. Verifique registros DNS SRV e certificados SSL se for auto-hospedado.
Instalação do plugin falha

Acesso ao registro npm ou incompatibilidade de versão do Node.js

Certifique-se de que Node.js 18+ está instalado. Tente 'openclaw plugins install @openclaw/matrix --verbose' para logs de erro detalhados. Verifique a conectividade de rede ao registro npm.
Ver documentação completaVoltar para todos os canais

Canais relacionados

Nostr

Advanced

OpenClaw integração descentralizada NIP-04 DM

Guia de Configuracao

Tlon

Advanced

OpenClaw integração com mensageiro Urbit

Guia de Configuracao