​

Matrix (plugin)

​

Plugin necessário

openclaw plugins install @openclaw/matrix

openclaw plugins install ./extensions/matrix

​

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:
   • Veja opções de hospedagem em https://matrix.org/ecosystem/hosting/
   • Ou hospede você mesmo.
3. Obtenha um token de acesso 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": "your-user-name"
     },
     "password": "your-password"
   }'
   
   • 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 token de acesso 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, a configuração tem precedência.
   • Com token de acesso: o ID do usuário é obtido automaticamente via /whoami.
   • Quando definido, channels.matrix.userId deve ser o ID Matrix completo (exemplo: @bot:example.org).
5. Reinicie o gateway (ou conclua a integração inicial).
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/). O Beeper requer E2EE, então defina channels.matrix.encryption: true e verifique o dispositivo.

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

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

​

Criptografia (E2EE)

• Se o módulo de 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 do dispositivo a partir de suas outras sessões.
• Verifique o dispositivo em outro cliente Matrix (Element, etc.) para habilitar o compartilhamento de chaves.
• Se o módulo de crypto não puder ser carregado, o E2EE é desativado e salas criptografadas não serão descriptografadas; o OpenClaw registra um aviso.
• Se você vir erros de módulo de 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 obtenha o binário com node node_modules/@matrix-org/matrix-sdk-crypto-nodejs/download-lib.js.

​

Múltiplas contas

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

• A inicialização das contas é serializada para evitar condições de corrida com importações simultâneas de módulos.
• Variáveis de ambiente (MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN, etc.) aplicam-se apenas à conta padrão.
• Configurações base do canal (política de DM, política de grupo, controle de menções etc.) aplicam-se a todas as contas, a menos que sejam substituídas por conta.
• Use bindings[].match.accountId para direcionar cada conta a um agente diferente.
• O estado de criptografia é armazenado por conta + access token (repositórios de chaves separados por conta).

​

Modelo de roteamento

• As respostas sempre retornam 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.
• Aprovar 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 de usuário Matrix completos (exemplo: @user:server). O assistente resolve nomes de exibição para IDs quando a busca no diretório encontra uma única correspondência exata.
• Não use nomes de exibição ou localparts simples (exemplo: "Alice" ou "alice"). Eles são ambíguos e são ignorados na correspondência da lista de permissões. Use IDs completos no formato @user:server.

​

Salas (grupos)

• Padrão: channels.matrix.groupPolicy = "allowlist" (com menção obrigatória). Use channels.defaults.groupPolicy para sobrescrever o padrão quando não definido.
• Coloque salas na lista de permissões com channels.matrix.groups (IDs ou aliases de sala; nomes são resolvidos para IDs quando a busca no diretório encontra uma única correspondência exata):

{
  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 nessa sala.
• groups."*" pode definir padrões para exigência de menção entre salas.
• groupAllowFrom restringe quais remetentes podem acionar o bot em salas (IDs Matrix completos).
• Listas de permissões por sala users podem restringir ainda mais remetentes dentro de uma sala específica (use IDs Matrix completos).
• O assistente de configuração solicita listas de permissões de salas (IDs, aliases ou nomes) e resolve nomes apenas em uma correspondência exata e única.
• Na inicialização, o OpenClaw resolve nomes de sala/usuário nas listas de permissões para IDs e registra o mapeamento; entradas não resolvidas são ignoradas na correspondência de listas de permissões.
• Convites são aceitos automaticamente por padrão; controle com channels.matrix.autoJoin e channels.matrix.autoJoinAllowlist.
• Para permitir nenhuma sala, defina channels.matrix.groupPolicy: "disabled" (ou mantenha a lista de permissões vazia).
• Chave legada: channels.matrix.rooms (mesma estrutura que groups).

​

Threads

• Encadeamento de respostas é suportado.
• channels.matrix.threadReplies controla se as respostas permanecem em threads:
  • off, inbound (padrão), always
• channels.matrix.replyToMode controla os metadados de resposta quando não responde em uma thread:
  • off (padrão), first, all

​

Capacidades

​

Solução de problemas

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

openclaw pairing list matrix

• Logado, mas mensagens de salas ignoradas: sala bloqueada por groupPolicy ou lista de permissões de salas.
• DMs ignoradas: remetente aguardando aprovação quando channels.matrix.dm.policy="pairing".
• Falha em salas criptografadas: suporte a crypto ou incompatibilidade nas configurações de criptografia.

​

Referência de configuração (Matrix)

• channels.matrix.enabled: habilitar/desabilitar a inicialização do canal.
• channels.matrix.homeserver: URL do homeserver.
• channels.matrix.userId: ID do usuário Matrix (opcional com token de acesso).
• channels.matrix.accessToken: token de acesso.
• 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 inicial de sincronização.
• channels.matrix.threadReplies: off | inbound | always (padrão: inbound).
• channels.matrix.textChunkLimit: tamanho do bloco de texto de saída (caracteres).
• channels.matrix.chunkMode: length (padrão) ou newline para dividir por linhas em branco (limites de parágrafo) antes do fracionamento por comprimento.
• channels.matrix.dm.policy: pairing | allowlist | open | disabled (padrão: pareamento).
• channels.matrix.dm.allowFrom: lista de permissões de DM (IDs Matrix completos). open requer "*". O assistente resolve nomes para IDs quando possível.
• channels.matrix.groupPolicy: allowlist | open | disabled (padrão: lista de permissões).
• channels.matrix.groupAllowFrom: remetentes permitidos para mensagens em grupo (IDs Matrix completos).
• channels.matrix.allowlistOnly: forçar regras de lista de permissões para DMs + salas.
• channels.matrix.groups: lista de permissões de grupo + mapa de configurações por sala.
• channels.matrix.rooms: lista/configuração legada de grupos.
• channels.matrix.replyToMode: modo de resposta 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: sempre).
• channels.matrix.autoJoinAllowlist: IDs/aliases de salas permitidos para auto-join.
• channels.matrix.accounts: configuração de múltiplas contas indexada por ID da conta (cada conta herda as configurações de nível superior).
• channels.matrix.actions: controle de ferramentas por ação (reações/mensagens/pins/memberInfo/channelInfo).