Matrix (plugin)

Matrix é um protocolo de mensagens aberto e descentralizado. O OpenClaw se conecta como um usuário Matrix em qualquer homeserver, então você precisa de uma conta Matrix para o bot. Uma vez logado, você pode enviar DMs diretamente ao bot ou convidá-lo para salas (os “grupos” do Matrix). Beeper também é uma opção válida de cliente, mas requer E2EE habilitado.

Status: suportado via plugin (@vector-im/matrix-bot-sdk). Mensagens diretas, salas, threads, mídia, reações, enquetes (envio + poll-start como texto), localização e E2EE (com suporte a crypto).

Plugin necessário

O Matrix é distribuído como plugin e não vem incluído na instalação padrão.

Instalação via CLI (registro npm):

openclaw plugins install @openclaw/matrix

Checkout local (quando rodando a partir de um repositório git):

openclaw plugins install ./extensions/matrix

Se você escolher Matrix durante configure/onboarding e um checkout git for detectado, o OpenClaw oferecerá o caminho de instalação local automaticamente.

Detalhes: Plugins

Configuração

  1. Instale o plugin Matrix:

    • Do npm: openclaw plugins install @openclaw/matrix
    • De um checkout local: openclaw plugins install ./extensions/matrix

  2. Crie uma conta Matrix em um homeserver:

  3. Obtenha um access token para a conta do bot:

    • Use a API de login do Matrix com curl no seu homeserver:
    curl --request POST \
  --url https://matrix.example.org/_matrix/client/v3/login \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "m.login.password",
  "identifier": {
    "type": "m.id.user",
    "user": "seu-nome-de-usuario"
  },
  "password": "sua-senha"
}'
    • Substitua matrix.example.org pela URL do seu homeserver.
    • Ou defina channels.matrix.userId + channels.matrix.password: o OpenClaw chama o mesmo endpoint de login, armazena o access token em ~/.openclaw/credentials/matrix/credentials.json e o reutiliza na próxima inicialização.

  4. Configure as credenciais:

    • Env: MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN (ou MATRIX_USER_ID + MATRIX_PASSWORD)
    • Ou config: channels.matrix.*
    • Se ambos estiverem definidos, o config tem precedência.
    • Com access token: o user ID é obtido automaticamente via /whoami.
    • Quando definido, channels.matrix.userId deve ser o ID Matrix completo (exemplo: @bot:example.org).

  5. Reinicie o gateway (ou finalize o onboarding).

  6. Inicie uma DM com o bot ou convide-o para uma sala a partir de qualquer cliente Matrix (Element, Beeper, etc.; veja https://matrix.org/ecosystem/clients/). Beeper requer E2EE, então defina channels.matrix.encryption: true e verifique o dispositivo.

Configuração mínima (access token, user ID obtido automaticamente):

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_***",
      dm: { policy: "pairing" },
    },
  },
}

Configuração E2EE (criptografia ponta a ponta habilitada):

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_***",
      encryption: true,
      dm: { policy: "pairing" },
    },
  },
}

Criptografia (E2EE)

A criptografia ponta a ponta é suportada via Rust crypto SDK.

Habilite com channels.matrix.encryption: true:

  • Se o módulo crypto carregar, salas criptografadas são descriptografadas automaticamente.
  • Mídia de saída é criptografada ao enviar para salas criptografadas.
  • Na primeira conexão, o OpenClaw solicita verificação de dispositivo das suas outras sessões.
  • Verifique o dispositivo em outro cliente Matrix (Element, etc.) para habilitar compartilhamento de chaves.
  • Se o módulo crypto não puder ser carregado, E2EE é desabilitado e salas criptografadas não serão descriptografadas; o OpenClaw registra um aviso.
  • Se você vir erros de módulo crypto ausente (por exemplo, @matrix-org/matrix-sdk-crypto-nodejs-*), permita scripts de build para @matrix-org/matrix-sdk-crypto-nodejs e execute pnpm rebuild @matrix-org/matrix-sdk-crypto-nodejs ou baixe o binário com node node_modules/@matrix-org/matrix-sdk-crypto-nodejs/download-lib.js.

O estado crypto é armazenado por conta + access token em ~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/crypto/ (banco de dados SQLite). O estado de sync fica ao lado em bot-storage.json. Se o access token (dispositivo) mudar, um novo store é criado e o bot deve ser re-verificado para salas criptografadas.

Verificação de dispositivo: Quando E2EE está habilitado, o bot solicita verificação das suas outras sessões na inicialização. Abra o Element (ou outro cliente) e aprove a solicitação de verificação para estabelecer confiança. Uma vez verificado, o bot pode descriptografar mensagens em salas criptografadas.

Múltiplas contas

Suporte a múltiplas contas: use channels.matrix.accounts com credenciais por conta e name opcional. Veja gateway/configuration para o padrão compartilhado.

Cada conta roda como um usuário Matrix separado em qualquer homeserver. A configuração por conta herda das configurações de nível superior channels.matrix e pode sobrescrever qualquer opção (política de DM, grupos, criptografia, etc.).

{
  channels: {
    matrix: {
      enabled: true,
      dm: { policy: "pairing" },
      accounts: {
        assistant: {
          name: "Assistente principal",
          homeserver: "https://matrix.example.org",
          accessToken: "syt_assistant_***",
          encryption: true,
        },
        alerts: {
          name: "Bot de alertas",
          homeserver: "https://matrix.example.org",
          accessToken: "syt_alerts_***",
          dm: { policy: "allowlist", allowFrom: ["@admin:example.org"] },
        },
      },
    },
  },
}

Observações:

  • A inicialização de contas é serializada para evitar condições de corrida com importações concorrentes de módulos.
  • Variáveis de ambiente (MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN, etc.) se aplicam apenas à conta padrão.
  • Configurações base do canal (política de DM, política de grupo, gating de menção, etc.) se aplicam a todas as contas, a menos que sobrescritas por conta.
  • Use bindings[].match.accountId para rotear cada conta para um agente diferente.
  • O estado crypto é armazenado por conta + access token (key stores separados por conta).

Modelo de roteamento

  • Respostas sempre voltam para o Matrix.
  • DMs compartilham a sessão principal do agente; salas mapeiam para sessões de grupo.

Controle de acesso (DMs)

  • Padrão: channels.matrix.dm.policy = "pairing". Remetentes desconhecidos recebem um código de pareamento.
  • Aprove via:
    • openclaw pairing list matrix
    • openclaw pairing approve matrix <CODE>
  • DMs públicas: channels.matrix.dm.policy="open" mais channels.matrix.dm.allowFrom=["*"].
  • channels.matrix.dm.allowFrom aceita IDs Matrix completos (exemplo: @user:server). O wizard resolve nomes de exibição para IDs quando a busca no diretório encontra uma correspondência exata única.
  • Não use nomes de exibição ou localparts simples (exemplo: "Alice" ou "alice"). São ambíguos e ignorados para correspondência de allowlist. Use IDs completos @user:server.

Salas (grupos)

  • Padrão: channels.matrix.groupPolicy = "allowlist" (com gating de menção). Use channels.defaults.groupPolicy para sobrescrever o padrão quando não definido.
  • Nota de runtime: se channels.matrix está completamente ausente, o runtime faz fallback para groupPolicy="allowlist" para verificações de sala (mesmo se channels.defaults.groupPolicy estiver definido).
  • Permita salas com channels.matrix.groups (IDs de sala ou aliases; nomes são resolvidos para IDs quando a busca no diretório encontra uma correspondência exata única):
{
  channels: {
    matrix: {
      groupPolicy: "allowlist",
      groups: {
        "!roomId:example.org": { allow: true },
        "#alias:example.org": { allow: true },
      },
      groupAllowFrom: ["@owner:example.org"],
    },
  },
}
  • requireMention: false habilita resposta automática naquela sala.
  • groups."*" pode definir padrões de gating de menção entre salas.
  • groupAllowFrom restringe quais remetentes podem acionar o bot em salas (IDs Matrix completos).
  • Allowlists users por sala podem restringir ainda mais remetentes dentro de uma sala específica (use IDs Matrix completos).
  • O wizard de configuração solicita allowlists de sala (IDs de sala, aliases ou nomes) e resolve nomes apenas em correspondência exata e única.
  • Na inicialização, o OpenClaw resolve nomes de sala/usuário em allowlists para IDs e registra o mapeamento; entradas não resolvidas são ignoradas para correspondência de allowlist.
  • Convites são aceitos automaticamente por padrão; controle com channels.matrix.autoJoin e channels.matrix.autoJoinAllowlist.
  • Para não permitir nenhuma sala, defina channels.matrix.groupPolicy: "disabled" (ou mantenha uma allowlist vazia).
  • Chave legada: channels.matrix.rooms (mesmo formato que groups).

Threads

  • Threading de respostas é suportado.
  • channels.matrix.threadReplies controla se respostas ficam em threads:
    • off, inbound (padrão), always
  • channels.matrix.replyToMode controla metadados de reply-to quando não respondendo em thread:
    • off (padrão), first, all

Funcionalidades

FuncionalidadeStatus
Mensagens diretasSuportado
SalasSuportado
ThreadsSuportado
MídiaSuportado
E2EESuportado (módulo crypto necessário)
ReaçõesSuportado (envio/leitura via ferramentas)
EnquetesEnvio suportado; poll starts de entrada são convertidos em texto (respostas/fins ignorados)
LocalizaçãoSuportado (geo URI; altitude ignorada)
Comandos nativosSuportado

Resolução de problemas

Execute esta sequência primeiro:

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

Depois confirme o estado de pareamento de DM se necessário:

openclaw pairing list matrix

Falhas comuns:

  • Logado mas mensagens de sala ignoradas: sala bloqueada por groupPolicy ou allowlist de sala.
  • DMs ignoradas: remetente pendente de aprovação quando channels.matrix.dm.policy="pairing".
  • Salas criptografadas falham: suporte crypto ou configurações de criptografia incompatíveis.

Para fluxo de triagem: /channels/troubleshooting.

Referência de configuração (Matrix)

Configuração completa: Configuração

Opções do provedor:

  • channels.matrix.enabled: habilitar/desabilitar inicialização do canal.
  • channels.matrix.homeserver: URL do homeserver.
  • channels.matrix.userId: ID de usuário Matrix (opcional com access token).
  • channels.matrix.accessToken: access token.
  • channels.matrix.password: senha para login (token armazenado).
  • channels.matrix.deviceName: nome de exibição do dispositivo.
  • channels.matrix.encryption: habilitar E2EE (padrão: false).
  • channels.matrix.initialSyncLimit: limite de sync inicial.
  • channels.matrix.threadReplies: off | inbound | always (padrão: inbound).
  • channels.matrix.textChunkLimit: tamanho do chunk de texto de saída (caracteres).
  • channels.matrix.chunkMode: length (padrão) ou newline para dividir em linhas em branco (limites de parágrafo) antes da divisão por tamanho.
  • channels.matrix.dm.policy: pairing | allowlist | open | disabled (padrão: pairing).
  • channels.matrix.dm.allowFrom: allowlist de DM (IDs Matrix completos). open requer "*". O wizard resolve nomes para IDs quando possível.
  • channels.matrix.groupPolicy: allowlist | open | disabled (padrão: allowlist).
  • channels.matrix.groupAllowFrom: remetentes na allowlist para mensagens de grupo (IDs Matrix completos).
  • channels.matrix.allowlistOnly: forçar regras de allowlist para DMs + salas.
  • channels.matrix.groups: mapa de allowlist de grupo + configurações por sala.
  • channels.matrix.rooms: allowlist/configuração legada de grupo.
  • channels.matrix.replyToMode: modo reply-to para threads/tags.
  • channels.matrix.mediaMaxMb: limite de mídia de entrada/saída (MB).
  • channels.matrix.autoJoin: tratamento de convites (always | allowlist | off, padrão: always).
  • channels.matrix.autoJoinAllowlist: IDs/aliases de sala permitidos para auto-join.
  • channels.matrix.accounts: configuração multi-conta chaveada por ID de conta (cada conta herda configurações de nível superior).
  • channels.matrix.actions: gating de ferramenta por ação (reactions/messages/pins/memberInfo/channelInfo).
arrow_back
Anterior
Line
Próximo
Mattermost
arrow_forward