> ## Documentation Index > Fetch the complete documentation index at: https://openclaw.veiseule.ai/llms.txt > Use this file to discover all available pages before exploring further. # Matrix # Matrix (plugin) Matrix é um protocolo de mensagens aberto e descentralizado. O OpenClaw se conecta como um **usuário** Matrix em qualquer homeserver, portanto você precisa de uma conta Matrix para o bot. Depois de fazer login, você pode enviar DM diretamente para o bot ou convidá-lo para salas (Matrix “grupos”). O Beeper também é uma opção válida de cliente, mas requer que o E2EE esteja habilitado. Status: suportado via plugin (@vector-im/matrix-bot-sdk). Mensagens diretas, salas, threads, mídia, reações, enquetes (envio + início de enquete como texto), localização e E2EE (com suporte a crypto). ## Plugin necessário Matrix é distribuído como um plugin e não vem incluído na instalação principal. Instale via CLI (registro npm): ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw plugins install @openclaw/matrix ``` Checkout local (ao executar a partir de um repositório git): ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw plugins install ./extensions/matrix ``` Se você escolher Matrix durante a configuração/integração inicial e um checkout git for detectado, o OpenClaw oferecerá automaticamente o caminho de instalação local. Detalhes: [Plugins](/tools/plugin) ## 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/](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: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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/](https://matrix.org/ecosystem/clients/)). O Beeper requer E2EE, então defina `channels.matrix.encryption: true` e verifique o dispositivo. Configuração mínima (token de acesso, ID do usuário obtido automaticamente): ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { matrix: { enabled: true, homeserver: "https://matrix.example.org", accessToken: "syt_***", dm: { policy: "pairing" }, }, }, } ``` Configuração E2EE (criptografia de ponta a ponta habilitada): ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { matrix: { enabled: true, homeserver: "https://matrix.example.org", accessToken: "syt_***", encryption: true, dm: { policy: "pairing" }, }, }, } ``` ## Criptografia (E2EE) A criptografia de ponta a ponta é **suportada** via o SDK de crypto em Rust. Habilite com `channels.matrix.encryption: true`: * 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`. O estado de crypto é armazenado por conta + token de acesso em `~/.openclaw/matrix/accounts//__//crypto/` (banco de dados SQLite). O estado de sincronização fica ao lado em `bot-storage.json`. Se o token de acesso (dispositivo) mudar, um novo armazenamento é criado e o bot deve ser reverificado para salas criptografadas. **Verificação de dispositivo:** Quando o 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. Depois de 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. Consulte [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts) para o padrão compartilhado. Cada conta é executada como um usuário Matrix separado em qualquer homeserver. Configuração por conta herda das configurações de nível superior de `channels.matrix` e pode substituir qualquer opção (política de DM, grupos, criptografia etc.). ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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"] }, }, }, }, }, } ``` Observações: * 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 ` * 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): ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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 | Funcionalidade | Status | | ----------------- | ----------------------------------------------------------------------------------------------------------- | | Mensagens diretas | ✅ Suportado | | Ambientes | ✅ Suportado | | Threads | ✅ Suportado | | Mídia | ✅ Suportado | | E2EE | ✅ Suportado (módulo de crypto necessário) | | Reações | ✅ Suportado (enviar/ler via ferramentas) | | Enquetes | ✅ Envio suportado; inícios de enquete recebidos são convertidos em texto (respostas/finalizações ignoradas) | | Localização | ✅ Suportado (URI geo; altitude ignorada) | | Comandos nativos | ✅ Suportado | ## Solução de problemas Execute esta sequência primeiro: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw status openclaw gateway status openclaw logs --follow openclaw doctor openclaw channels status --probe ``` Depois confirme o estado de pareamento de DMs, se necessário: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw pairing list matrix ``` Falhas comuns: * 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. Para fluxo de triagem: [/channels/troubleshooting](/channels/troubleshooting). ## Referência de configuração (Matrix) Configuração completa: [Configuração](/gateway/configuration) Opções do provedor: * `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).