Matriz

Matrix é um Plugin de canal baixável para OpenClaw. Ele usa o matrix-js-sdk oficial e oferece suporte a DMs, salas, threads, mídia, reações, enquetes, localização e E2EE.

Instalação

Instale o Matrix pelo ClawHub antes de configurar o canal:

openclaw plugins install @openclaw/matrix

Especificações de Plugin simples tentam o ClawHub primeiro e depois recorrem ao npm. Para forçar a origem do registro, use openclaw plugins install clawhub:@openclaw/matrix ou openclaw plugins install npm:@openclaw/matrix.

A partir de um checkout local:

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

plugins install registra e habilita o Plugin, portanto nenhuma etapa separada de openclaw plugins enable matrix é necessária. O Plugin ainda não faz nada até você configurar o canal abaixo. Consulte Plugins para o comportamento geral de Plugins e regras de instalação.

Configuração

1. Crie uma conta Matrix no seu homeserver.
2. Configure channels.matrix com homeserver + accessToken ou homeserver + userId + password.
3. Reinicie o Gateway.
4. Inicie uma DM com o bot ou convide-o para uma sala (consulte entrada automática - convites novos só entram quando autoJoin os permite).

Configuração interativa

openclaw channels addopenclaw configure --section channels

O assistente solicita: URL do homeserver, método de autenticação (token de acesso ou senha), ID de usuário (somente autenticação por senha), nome opcional do dispositivo, se E2EE deve ser habilitada e se o acesso a salas e a entrada automática devem ser configurados.

Se variáveis de ambiente MATRIX_* correspondentes já existirem e a conta selecionada não tiver autenticação salva, o assistente oferece um atalho por variável de ambiente. Para resolver nomes de salas antes de salvar uma allowlist, execute openclaw channels resolve --channel matrix "Project Room". Quando E2EE está habilitada, o assistente grava a configuração e executa o mesmo bootstrap de openclaw matrix encryption setup.

Configuração mínima

Baseada em token:

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

Baseada em senha (o token é armazenado em cache após o primeiro login):

{  channels: {    matrix: {      enabled: true,      homeserver: "https://matrix.example.org",      userId: "@bot:example.org",      password: "replace-me", // pragma: allowlist secret      deviceName: "OpenClaw Gateway",    },  },}

Entrada automática

channels.matrix.autoJoin usa off por padrão. Com o padrão, o bot não aparecerá em novas salas ou DMs de convites recentes até que você entre manualmente.

O OpenClaw não consegue saber, no momento do convite, se uma sala convidada é uma DM ou um grupo, então todos os convites - incluindo convites no estilo de DM - passam primeiro por autoJoin. dm.policy só se aplica depois, quando o bot já entrou e a sala foi classificada.

{  channels: {    matrix: {      autoJoin: "allowlist",      autoJoinAllowlist: ["!ops:example.org", "#support:example.org"],      groups: {        "!ops:example.org": { requireMention: true },      },    },  },}

Para aceitar todos os convites, use autoJoin: "always".

Formatos de destino da allowlist

Allowlists de DMs e salas são melhor preenchidas com IDs estáveis:

• DMs (dm.allowFrom, groupAllowFrom, groups.<room>.users): use @user:server. Nomes de exibição são ignorados por padrão porque são mutáveis; defina dangerouslyAllowNameMatching: true somente quando precisar explicitamente de compatibilidade com entradas de nome de exibição.
• Chaves de allowlist de salas (groups, legado rooms): use !room:server ou #alias:server. Nomes simples de salas são ignorados por padrão; defina dangerouslyAllowNameMatching: true somente quando precisar explicitamente de compatibilidade com busca por nome de sala já ingressada.
• Allowlists de convite (autoJoinAllowlist): use !room:server, #alias:server ou *. Nomes simples de salas são rejeitados.

Normalização de ID de conta

O assistente converte um nome amigável em um ID de conta normalizado. Por exemplo, Ops Bot vira ops-bot. A pontuação é escapada em nomes de variáveis de ambiente com escopo para que duas contas não possam colidir: - → _X2D_, então ops-prod mapeia para MATRIX_OPS_X2D_PROD_*.

Credenciais em cache

O Matrix armazena credenciais em cache em ~/.openclaw/credentials/matrix/:

• conta padrão: credentials.json
• contas nomeadas: credentials-<account>.json

Quando credenciais em cache existem ali, o OpenClaw trata o Matrix como configurado mesmo que o token de acesso não esteja no arquivo de configuração - isso cobre configuração, openclaw doctor e sondagens de status de canal.

Variáveis de ambiente

Usadas quando a chave de configuração equivalente não está definida. A conta padrão usa nomes sem prefixo; contas nomeadas usam o ID da conta inserido antes do sufixo.

Para a conta ops, os nomes se tornam MATRIX_OPS_HOMESERVER, MATRIX_OPS_ACCESS_TOKEN e assim por diante. As variáveis de ambiente de chave de recuperação são lidas por fluxos de CLI cientes de recuperação (verify backup restore, verify device, verify bootstrap) quando você passa a chave via pipe por --recovery-key-stdin.

MATRIX_HOMESERVER não pode ser definido a partir de um .env de workspace; consulte Arquivos .env de workspace.

Exemplo de configuração

Uma linha de base prática com pareamento de DM, allowlist de salas e E2EE:

{  channels: {    matrix: {      enabled: true,      homeserver: "https://matrix.example.org",      accessToken: "syt_xxx",      encryption: true,       dm: {        policy: "pairing",        sessionScope: "per-room",        threadReplies: "off",      },       groupPolicy: "allowlist",      groupAllowFrom: ["@admin:example.org"],      groups: {        "!roomid:example.org": { requireMention: true },      },       autoJoin: "allowlist",      autoJoinAllowlist: ["!roomid:example.org"],      threadReplies: "inbound",      replyToMode: "off",      streaming: "partial",    },  },}

Prévias de streaming

Streaming de respostas do Matrix é opcional. streaming controla como o OpenClaw entrega a resposta em andamento do assistente; blockStreaming controla se cada bloco concluído é preservado como sua própria mensagem Matrix.

{  channels: {    matrix: {      streaming: "partial",    },  },}

Para manter prévias ao vivo da resposta, mas ocultar linhas intermediárias de ferramenta/progresso, use a forma de objeto:

{  channels: {    matrix: {      streaming: {        mode: "partial",        preview: {          toolProgress: false,        },      },    },  },}

A forma completa de objeto aceita { mode, preview, progress }:

{  channels: {    matrix: {      streaming: {        mode: "progress",        progress: {          label: "auto", // escolha entre rótulos configurados ou integrados (false para ocultar)          labels: ["Thinking", "Writing", "Searching"], // candidatos para label: "auto"          maxLines: 8, // máximo de linhas de progresso contínuo (padrão: 8)          maxLineChars: 120, // máximo de caracteres por linha antes do truncamento (padrão: 120)          toolProgress: true, // mostrar atividade de ferramenta/progresso (padrão: true)        },      },    },  },}

• progress.label: um rótulo personalizado, "auto" ou indefinido para escolher entre rótulos configurados ou integrados, ou false para ocultar a linha de rótulo.
• progress.labels: rótulos candidatos usados somente quando label é "auto" ou indefinido. Deixe indefinido para usar os padrões integrados.
• progress.maxLines: número máximo de linhas de progresso contínuo mantidas no rascunho. Após esse limite, linhas mais antigas são aparadas.
• progress.maxLineChars: número máximo de caracteres por linha compacta de progresso antes do truncamento.
• progress.toolProgress: quando true (padrão), a atividade ao vivo de ferramenta/progresso aparece no rascunho.

blockStreaming é independente de streaming:

Observações:

• Se uma prévia ultrapassar o limite de tamanho por evento do Matrix, o OpenClaw interrompe o streaming de prévias e volta para entrega somente final.
• Respostas com mídia sempre enviam anexos normalmente. Se uma prévia obsoleta não puder mais ser reutilizada com segurança, o OpenClaw a redige antes de enviar a resposta final com mídia.
• Atualizações de prévia de progresso de ferramentas são habilitadas por padrão quando o streaming de prévias Matrix está ativo. Defina streaming.preview.toolProgress: false para manter edições de prévia para texto de resposta, mas deixar o progresso de ferramentas no caminho normal de entrega.
• Edições de prévia custam chamadas extras à API Matrix. Deixe streaming: "off" se quiser o perfil de limite de taxa mais conservador.

Mensagens de voz

Notas de voz recebidas no Matrix são transcritas antes da barreira de menção da sala. Isso permite que uma nota de voz que diga o nome do bot acione o agente em uma sala com requireMention: true, e fornece ao agente a transcrição em vez de apenas um placeholder de anexo de áudio.

O Matrix usa o provedor de mídia de áudio compartilhado configurado em tools.media.audio, como OpenAI gpt-4o-mini-transcribe. Consulte Visão geral de ferramentas de mídia para configuração e limites de provedores.

Detalhes de comportamento:

• Eventos m.audio e eventos m.file com um tipo MIME audio/* são elegíveis.
• Em salas criptografadas, o OpenClaw descriptografa o anexo pelo caminho de mídia Matrix existente antes da transcrição.
• A transcrição é marcada como gerada por máquina e não confiável no prompt do agente.
• O anexo é marcado como já transcrito para que ferramentas de mídia downstream não transcrevam a mesma nota de voz novamente.
• Defina tools.media.audio.enabled: false para desabilitar a transcrição de áudio globalmente.

Metadados de aprovação

Prompts de aprovação nativos do Matrix são eventos m.room.message normais com conteúdo de evento personalizado específico do OpenClaw em com.openclaw.approval. O Matrix permite chaves personalizadas de conteúdo de evento, então clientes padrão ainda renderizam o corpo do texto, enquanto clientes cientes do OpenClaw podem ler o id de aprovação estruturado, tipo, estado, decisões disponíveis e detalhes de execução/plugin.

Quando um prompt de aprovação é longo demais para um evento Matrix, o OpenClaw divide o texto visível em blocos e anexa com.openclaw.approval apenas ao primeiro bloco. Reações para decisões de permitir/negar são vinculadas a esse primeiro evento, então prompts longos mantêm o mesmo destino de aprovação que prompts de evento único.

Regras de push auto-hospedadas para prévias finalizadas silenciosas

streaming: "quiet" só notifica destinatários quando um bloco ou turno é finalizado - uma regra de push por usuário precisa corresponder ao marcador de prévia finalizada. Consulte Regras de push do Matrix para prévias silenciosas para a receita completa (token do destinatário, verificação do pusher, instalação da regra, notas por homeserver).

Salas bot-para-bot

Por padrão, mensagens Matrix de outras contas Matrix configuradas do OpenClaw são ignoradas.

Use allowBots quando você quiser intencionalmente tráfego Matrix entre agentes:

{  channels: {    matrix: {      allowBots: "mentions", // true | "mentions"      groups: {        "!roomid:example.org": {          requireMention: true,        },      },    },  },}

• allowBots: true aceita mensagens de outras contas de bot Matrix configuradas em salas e DMs permitidas.
• allowBots: "mentions" aceita essas mensagens apenas quando elas mencionam visivelmente este bot em salas. DMs continuam permitidas.
• groups.<room>.allowBots substitui a configuração no nível da conta para uma sala.
• Mensagens aceitas de bots configurados usam a proteção contra loop de bots compartilhada. Configure channels.defaults.botLoopProtection e depois substitua com channels.matrix.botLoopProtection ou channels.matrix.groups.<room>.botLoopProtection quando uma sala precisar de um orçamento diferente.
• O OpenClaw ainda ignora mensagens do mesmo ID de usuário Matrix para evitar loops de autorresposta.
• O Matrix não expõe uma flag nativa de bot aqui; o OpenClaw trata "autoria de bot" como "enviada por outra conta Matrix configurada neste gateway OpenClaw".

Use allowlists de sala rigorosas e requisitos de menção ao habilitar tráfego bot-para-bot em salas compartilhadas.

Criptografia e verificação

Em salas criptografadas (E2EE), eventos de imagem de saída usam thumbnail_file, então prévias de imagem são criptografadas junto com o anexo completo. Salas não criptografadas ainda usam thumbnail_url. Nenhuma configuração é necessária - o plugin detecta o estado E2EE automaticamente.

Todos os comandos openclaw matrix aceitam --verbose (diagnósticos completos), --json (saída legível por máquina) e --account <id> (configurações com múltiplas contas). A saída é concisa por padrão, com logs internos silenciosos do SDK. Os exemplos abaixo mostram a forma canônica; adicione as flags conforme necessário.

Habilitar criptografia

openclaw matrix encryption setup

Inicializa o armazenamento secreto e a assinatura cruzada, cria um backup de chaves de sala se necessário e depois imprime o status e os próximos passos. Flags úteis:

• --recovery-key <key> aplica uma chave de recuperação antes da inicialização (prefira a forma via stdin documentada abaixo)
• --force-reset-cross-signing descarta a identidade de assinatura cruzada atual e cria uma nova (use apenas intencionalmente)

Para uma nova conta, habilite E2EE no momento da criação:

openclaw matrix account add \  --homeserver https://matrix.example.org \  --access-token syt_xxx \  --enable-e2ee

--encryption é um alias para --enable-e2ee.

Equivalente de configuração manual:

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

Status e sinais de confiança

openclaw matrix verify statusopenclaw matrix verify status --include-recovery-key --json

verify status informa três sinais de confiança independentes (--verbose mostra todos eles):

• Locally trusted: confiável apenas por este cliente
• Cross-signing verified: o SDK informa verificação via assinatura cruzada
• Signed by owner: assinado pela sua própria chave de autoassinatura (apenas diagnóstico)

Verified by owner se torna yes apenas quando Cross-signing verified é yes. Confiança local ou uma assinatura do proprietário isoladamente não basta.

--allow-degraded-local-state retorna diagnósticos de melhor esforço sem preparar a conta Matrix primeiro; útil para sondagens offline ou parcialmente configuradas.

Verificar este dispositivo com uma chave de recuperação

A chave de recuperação é sensível - passe-a via stdin em vez de passá-la na linha de comando. Defina MATRIX_RECOVERY_KEY (ou MATRIX_<ID>_RECOVERY_KEY para uma conta nomeada):

printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin

O comando informa três estados:

• Recovery key accepted: o Matrix aceitou a chave para armazenamento secreto ou confiança do dispositivo.
• Backup usable: o backup de chaves de sala pode ser carregado com o material de recuperação confiável.
• Device verified by owner: este dispositivo tem confiança completa da identidade de assinatura cruzada do Matrix.

Ele sai com código diferente de zero quando a confiança completa da identidade está incompleta, mesmo que a chave de recuperação tenha desbloqueado o material de backup. Nesse caso, conclua a autoverificação em outro cliente Matrix:

openclaw matrix verify self

verify self aguarda Cross-signing verified: yes antes de sair com sucesso. Use --timeout-ms <ms> para ajustar a espera.

A forma de chave literal openclaw matrix verify device "<recovery-key>" também é aceita, mas a chave acaba no histórico do seu shell.

Inicializar ou reparar assinatura cruzada

openclaw matrix verify bootstrap

verify bootstrap é o comando de reparo e configuração para contas criptografadas. Em ordem, ele:

• inicializa o armazenamento secreto, reutilizando uma chave de recuperação existente quando possível
• inicializa a assinatura cruzada e envia chaves públicas ausentes
• marca e assina cruzadamente o dispositivo atual
• cria um backup de chaves de sala no lado do servidor se ainda não existir

Se o homeserver exigir UIA para enviar chaves de assinatura cruzada, o OpenClaw tenta primeiro sem autenticação, depois m.login.dummy, depois m.login.password (requer channels.matrix.password).

Flags úteis:

• --recovery-key-stdin (combine com printf '%s\n' "$MATRIX_RECOVERY_KEY" | …) ou --recovery-key <key>
• --force-reset-cross-signing para descartar a identidade de assinatura cruzada atual (apenas intencional; requer que a chave de recuperação ativa esteja armazenada ou seja fornecida com --recovery-key-stdin)

Backup de chaves de sala

openclaw matrix verify backup statusprintf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin

backup status mostra se existe um backup no lado do servidor e se este dispositivo consegue descriptografá-lo. backup restore importa chaves de sala salvas em backup para o armazenamento criptográfico local; se a chave de recuperação já estiver no disco, você pode omitir --recovery-key-stdin.

Para substituir um backup quebrado por uma linha de base nova (aceita perder histórico antigo irrecuperável; também pode recriar o armazenamento secreto se o segredo do backup atual não puder ser carregado):

openclaw matrix verify backup reset --yes

Adicione --rotate-recovery-key apenas quando você quiser intencionalmente que a chave de recuperação anterior pare de desbloquear a nova linha de base de backup.

Listagem, solicitação e resposta a verificações

openclaw matrix verify list

Lista solicitações de verificação pendentes para a conta selecionada.

openclaw matrix verify request --own-useropenclaw matrix verify request --user-id @ops:example.org --device-id ABCDEF

Envia uma solicitação de verificação desta conta OpenClaw. --own-user solicita autoverificação (você aceita o prompt em outro cliente Matrix do mesmo usuário); --user-id/--device-id/--room-id direcionam outra pessoa. --own-user não pode ser combinado com as outras flags de direcionamento.

Para tratamento de ciclo de vida de nível mais baixo - normalmente ao espelhar solicitações de entrada de outro cliente - estes comandos atuam em uma solicitação específica <id> (impressa por verify list e verify request):

accept, start, sas, confirm-sas, mismatch-sas e cancel aceitam --user-id e --room-id como dicas de acompanhamento por DM quando a verificação está ancorada a uma sala de mensagem direta específica.

Notas sobre múltiplas contas

Sem --account <id>, comandos da CLI do Matrix usam a conta padrão implícita. Se você tiver várias contas nomeadas e não tiver definido channels.matrix.defaultAccount, eles se recusarão a adivinhar e pedirão que você escolha. Quando E2EE está desabilitado ou indisponível para uma conta nomeada, os erros apontam para a chave de configuração dessa conta, por exemplo channels.matrix.accounts.assistant.encryption.

openclaw matrix account add \--account assistant \--homeserver https://matrix.example.org \--user-id '@assistant:example.org' \--password '<password>' \--device-name OpenClaw-Gateway

openclaw matrix account add \--account assistant \--homeserver https://matrix.example.org \--access-token '<token>'

openclaw matrix devices listopenclaw matrix devices prune-stale

Gerenciamento de perfil

Atualize o autoperfil Matrix da conta selecionada:

openclaw matrix profile set --name "OpenClaw Assistant"openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png

Você pode passar as duas opções em uma única chamada. O Matrix aceita URLs de avatar mxc:// diretamente; quando você passa http:// ou https://, o OpenClaw primeiro faz upload do arquivo e armazena a URL mxc:// resolvida em channels.matrix.avatarUrl (ou na substituição por conta).

Threads

O Matrix oferece suporte a threads nativas do Matrix tanto para respostas automáticas quanto para envios pela ferramenta de mensagem. Dois controles independentes definem o comportamento:

Roteamento de sessão (sessionScope)

dm.sessionScope decide como salas de DM do Matrix são mapeadas para sessões do OpenClaw:

• "per-user" (padrão): todas as salas de DM com o mesmo par roteado compartilham uma sessão.
• "per-room": cada sala de DM do Matrix recebe sua própria chave de sessão, mesmo quando o par é o mesmo.

Vínculos explícitos de conversa sempre prevalecem sobre sessionScope, então salas e threads vinculadas mantêm a sessão de destino escolhida.

Encadeamento de respostas (threadReplies)

threadReplies decide onde o bot publica sua resposta:

• "off": as respostas ficam no nível superior. Mensagens encadeadas recebidas permanecem na sessão pai.
• "inbound": responde dentro de uma thread somente quando a mensagem recebida já estava nessa thread.
• "always": responde dentro de uma thread enraizada na mensagem disparadora; essa conversa é roteada por uma sessão correspondente com escopo de thread desde o primeiro disparo em diante.

dm.threadReplies substitui isso apenas para DMs - por exemplo, mantenha threads de sala isoladas enquanto mantém DMs planas.

Herança de thread e comandos de barra

• Mensagens encadeadas recebidas incluem a mensagem raiz da thread como contexto extra do agente.
• Envios pela ferramenta de mensagem herdam automaticamente a thread atual do Matrix ao mirar a mesma sala (ou o mesmo destino de usuário de DM), a menos que um threadId explícito seja fornecido.
• A reutilização de destino de usuário de DM só entra em ação quando os metadados da sessão atual comprovam o mesmo par de DM na mesma conta Matrix; caso contrário, o OpenClaw volta ao roteamento normal com escopo de usuário.
• /focus, /unfocus, /agents, /session idle, /session max-age e /acp spawn vinculados a thread funcionam em salas e DMs do Matrix.
• /focus no nível superior cria uma nova thread do Matrix e a vincula à sessão de destino quando threadBindings.spawnSessions está habilitado.
• Executar /focus ou /acp spawn --thread here dentro de uma thread existente do Matrix vincula essa thread no próprio local.

Quando o OpenClaw detecta uma sala de DM do Matrix colidindo com outra sala de DM na mesma sessão compartilhada, ele publica um m.notice único nessa sala apontando para a saída de emergência /focus e sugerindo uma alteração em dm.sessionScope. O aviso só aparece quando vínculos de thread estão habilitados.

Vínculos de conversa ACP

Salas, DMs e threads existentes do Matrix podem ser transformadas em workspaces ACP duráveis sem alterar a superfície de chat.

Fluxo rápido do operador:

• Execute /acp spawn codex --bind here dentro da DM do Matrix, sala ou thread existente que você quer continuar usando.
• Em uma DM ou sala Matrix no nível superior, a DM/sala atual permanece a superfície de chat e mensagens futuras são roteadas para a sessão ACP gerada.
• Dentro de uma thread existente do Matrix, --bind here vincula essa thread no próprio local.
• /new e /reset redefinem a mesma sessão ACP vinculada no próprio local.
• /acp close fecha a sessão ACP e remove o vínculo.

Observações:

• --bind here não cria uma thread filha do Matrix.
• threadBindings.spawnSessions controla /acp spawn --thread auto|here, quando o OpenClaw precisa criar ou vincular uma thread filha do Matrix.

Configuração de vínculo de thread

O Matrix herda padrões globais de session.threadBindings e também oferece suporte a substituições por canal:

• threadBindings.enabled
• threadBindings.idleHours
• threadBindings.maxAgeHours
• threadBindings.spawnSessions
• threadBindings.defaultSpawnContext

Gerações de sessão vinculadas a thread do Matrix vêm habilitadas por padrão:

• Defina threadBindings.spawnSessions: false para impedir que /focus no nível superior e /acp spawn --thread auto|here criem/vinculem threads do Matrix.
• Defina threadBindings.defaultSpawnContext: "isolated" quando gerações de threads de subagente nativas não devem bifurcar a transcrição pai.

Reações

O Matrix oferece suporte a reações de saída, notificações de reação recebidas e reações de confirmação.

As ferramentas de reação de saída são controladas por channels.matrix.actions.reactions:

• react adiciona uma reação a um evento Matrix.
• reactions lista o resumo atual de reações de um evento Matrix.
• emoji="" remove as próprias reações do bot nesse evento.
• remove: true remove apenas a reação de emoji especificada do bot.

Ordem de resolução (o primeiro valor definido vence):

reactionNotifications: "own" encaminha eventos m.reaction adicionados quando eles miram mensagens Matrix criadas pelo bot; "off" desabilita eventos de sistema de reação. Remoções de reação não são sintetizadas em eventos de sistema porque o Matrix expõe isso como redações, não como remoções m.reaction autônomas.

Contexto de histórico

• channels.matrix.historyLimit controla quantas mensagens recentes da sala são incluídas como InboundHistory quando uma mensagem de sala Matrix dispara o agente. Recai para messages.groupChat.historyLimit; se ambos não estiverem definidos, o padrão efetivo é 0. Defina 0 para desabilitar.
• O histórico de sala do Matrix é apenas da sala. DMs continuam usando o histórico normal da sessão.
• O histórico de sala do Matrix é apenas pendente: o OpenClaw armazena em buffer mensagens da sala que ainda não dispararam uma resposta e então captura esse intervalo quando uma menção ou outro disparador chega.
• A mensagem disparadora atual não é incluída em InboundHistory; ela permanece no corpo recebido principal desse turno.
• Novas tentativas do mesmo evento Matrix reutilizam o snapshot de histórico original em vez de avançar para mensagens de sala mais novas.

Visibilidade de contexto

O Matrix oferece suporte ao controle compartilhado contextVisibility para contexto suplementar de sala, como texto de resposta buscado, raízes de thread e histórico pendente.

• contextVisibility: "all" é o padrão. O contexto suplementar é mantido como recebido.
• contextVisibility: "allowlist" filtra o contexto suplementar para remetentes permitidos pelas verificações ativas de allowlist de sala/usuário.
• contextVisibility: "allowlist_quote" se comporta como allowlist, mas ainda mantém uma resposta citada explícita.

Essa configuração afeta a visibilidade do contexto suplementar, não se a própria mensagem recebida pode disparar uma resposta. A autorização de disparo ainda vem de groupPolicy, groups, groupAllowFrom e das configurações de política de DM.

Política de DM e sala

{  channels: {    matrix: {      dm: {        policy: "allowlist",        allowFrom: ["@admin:example.org"],        threadReplies: "off",      },      groupPolicy: "allowlist",      groupAllowFrom: ["@admin:example.org"],      groups: {        "!roomid:example.org": { requireMention: true },      },    },  },}

Para silenciar DMs completamente enquanto mantém salas funcionando, defina dm.enabled: false:

{  channels: {    matrix: {      dm: { enabled: false },      groupPolicy: "allowlist",      groupAllowFrom: ["@admin:example.org"],    },  },}

Consulte Grupos para o comportamento de controle por menção e allowlist.

Exemplo de pareamento para DMs do Matrix:

openclaw pairing list matrixopenclaw pairing approve matrix <CODE>

Se um usuário Matrix não aprovado continuar enviando mensagens antes da aprovação, o OpenClaw reutiliza o mesmo código de pareamento pendente e pode enviar uma resposta de lembrete após um curto cooldown em vez de emitir um novo código.

Consulte Pareamento para o fluxo compartilhado de pareamento de DM e o layout de armazenamento.

Reparo de sala direta

Se o estado de mensagem direta sair de sincronia, o OpenClaw pode acabar com mapeamentos m.direct obsoletos que apontam para salas solo antigas em vez da DM ativa. Inspecione o mapeamento atual de um par:

openclaw matrix direct inspect --user-id @alice:example.org

Repare-o:

openclaw matrix direct repair --user-id @alice:example.org

Ambos os comandos aceitam --account <id> para configurações com várias contas. O fluxo de reparo:

• prefere uma DM 1:1 estrita que já esteja mapeada em m.direct
• recai para qualquer DM 1:1 estrita atualmente ingressada com esse usuário
• cria uma sala direta nova e reescreve m.direct se nenhuma DM saudável existir

Ele não exclui salas antigas automaticamente. Ele escolhe a DM saudável e atualiza o mapeamento para que futuros envios Matrix, avisos de verificação e outros fluxos de mensagem direta mirem a sala correta.

Aprovações de exec

O Matrix pode atuar como um cliente de aprovação nativo. Configure em channels.matrix.execApprovals (ou channels.matrix.accounts.<account>.execApprovals para uma substituição por conta):

• enabled: entrega aprovações por prompts nativos do Matrix. Quando não definido ou "auto", o Matrix habilita automaticamente assim que pelo menos um aprovador puder ser resolvido. Defina false para desabilitar explicitamente.
• approvers: IDs de usuário Matrix (@owner:example.org) autorizados a aprovar solicitações de exec. Opcional - recai para channels.matrix.dm.allowFrom.
• target: para onde os prompts vão. "dm" (padrão) envia para DMs dos aprovadores; "channel" envia para a sala ou DM Matrix de origem; "both" envia para ambos.
• agentFilter / sessionFilter: allowlists opcionais para quais agentes/sessões disparam a entrega pelo Matrix.

A autorização difere ligeiramente entre tipos de aprovação:

• Aprovações de exec usam execApprovals.approvers, recaindo para dm.allowFrom.
• Aprovações de Plugin autorizam apenas por dm.allowFrom.

Ambos os tipos compartilham atalhos de reação e atualizações de mensagem do Matrix. Aprovadores veem atalhos de reação na mensagem de aprovação principal:

• ✅ permitir uma vez
• ❌ negar
• ♾️ permitir sempre (quando a política efetiva de exec permite isso)

Comandos de barra de fallback: /approve <id> allow-once, /approve <id> allow-always, /approve <id> deny.

Somente aprovadores resolvidos podem aprovar ou negar. A entrega por canal para aprovações de exec inclui o texto do comando - habilite channel ou both somente em salas confiáveis.

Relacionado: Aprovações de exec.

Comandos de barra

Comandos de barra (/new, /reset, /model, /focus, /unfocus, /agents, /session, /acp, /approve, etc.) funcionam diretamente em DMs. Em salas, o OpenClaw também reconhece comandos prefixados com a própria menção Matrix do bot, então @bot:server /new aciona o caminho de comando sem uma regex de menção personalizada. Isso mantém o bot responsivo às publicações no estilo de sala @mention /command que Element e clientes semelhantes emitem quando um usuário usa preenchimento por tabulação para o bot antes de digitar o comando.

As regras de autorização ainda se aplicam: remetentes de comandos devem satisfazer as mesmas políticas de allowlist/proprietário de DM ou sala que mensagens comuns.

Várias contas

{  channels: {    matrix: {      enabled: true,      defaultAccount: "assistant",      dm: { policy: "pairing" },      accounts: {        assistant: {          homeserver: "https://matrix.example.org",          accessToken: "syt_assistant_xxx",          encryption: true,        },        alerts: {          homeserver: "https://matrix.example.org",          accessToken: "syt_alerts_xxx",          dm: {            policy: "allowlist",            allowFrom: ["@ops:example.org"],            threadReplies: "off",          },        },      },    },  },}

Herança:

• Valores de nível superior em channels.matrix atuam como padrões para contas nomeadas, a menos que uma conta os substitua.
• Escopo uma entrada de sala herdada para uma conta específica com groups.<room>.account. Entradas sem account são compartilhadas entre contas; account: "default" ainda funciona quando a conta padrão está configurada no nível superior.

Seleção da conta padrão:

• Defina defaultAccount para escolher a conta nomeada que roteamento implícito, sondagem e comandos da CLI preferem.
• Se você tiver várias contas e uma se chamar literalmente default, o OpenClaw a usará implicitamente mesmo quando defaultAccount não estiver definido.
• Se você tiver várias contas nomeadas e nenhuma padrão estiver selecionada, comandos da CLI se recusam a adivinhar - defina defaultAccount ou passe --account <id>.
• O bloco de nível superior channels.matrix.* só é tratado como a conta implícita default quando sua autenticação está completa (homeserver + accessToken, ou homeserver + userId + password). Contas nomeadas continuam descobríveis a partir de homeserver + userId quando credenciais em cache cobrem a autenticação.

Promoção:

• Quando o OpenClaw promove uma configuração de conta única para várias contas durante reparo ou configuração, ele preserva a conta nomeada existente se houver uma ou se defaultAccount já apontar para uma. Somente chaves de autenticação/bootstrap do Matrix são movidas para a conta promovida; chaves de política de entrega compartilhadas permanecem no nível superior.

Consulte Referência de configuração para o padrão compartilhado de várias contas.

Homeservers privados/LAN

Por padrão, o OpenClaw bloqueia homeservers Matrix privados/internos para proteção contra SSRF, a menos que você opte explicitamente por conta.

Se seu homeserver roda em localhost, um IP de LAN/Tailscale ou um hostname interno, habilite network.dangerouslyAllowPrivateNetwork para essa conta Matrix:

{  channels: {    matrix: {      homeserver: "http://matrix-synapse:8008",      network: {        dangerouslyAllowPrivateNetwork: true,      },      accessToken: "syt_internal_xxx",    },  },}

Exemplo de configuração da CLI:

openclaw matrix account add \  --account ops \  --homeserver http://matrix-synapse:8008 \  --allow-private-network \  --access-token syt_ops_xxx

Essa opção explícita permite apenas destinos privados/internos confiáveis. Homeservers públicos em texto claro, como http://matrix.example.org:8008, continuam bloqueados. Prefira https:// sempre que possível.

Proxy de tráfego Matrix

Se sua implantação Matrix precisar de um proxy HTTP(S) de saída explícito, defina channels.matrix.proxy:

{  channels: {    matrix: {      homeserver: "https://matrix.example.org",      accessToken: "syt_bot_xxx",      proxy: "http://127.0.0.1:7890",    },  },}

Contas nomeadas podem substituir o padrão de nível superior com channels.matrix.accounts.<id>.proxy. O OpenClaw usa a mesma configuração de proxy para tráfego Matrix em runtime e sondagens de status de conta.

Resolução de destino

Matrix aceita estas formas de destino em qualquer lugar em que o OpenClaw peça um destino de sala ou usuário:

• Usuários: @user:server, user:@user:server ou matrix:user:@user:server
• Salas: !room:server, room:!room:server ou matrix:room:!room:server
• Aliases: #alias:server, channel:#alias:server ou matrix:channel:#alias:server

IDs de salas Matrix diferenciam maiúsculas de minúsculas. Use a capitalização exata do ID da sala do Matrix ao configurar destinos de entrega explícitos, tarefas cron, associações ou allowlists. O OpenClaw mantém chaves de sessão internas canônicas para armazenamento, portanto essas chaves em minúsculas não são uma fonte confiável para IDs de entrega Matrix.

A pesquisa em diretório ao vivo usa a conta Matrix conectada:

• Pesquisas de usuário consultam o diretório de usuários Matrix nesse homeserver.
• Pesquisas de sala aceitam diretamente IDs de sala e aliases explícitos. A pesquisa de nome de salas ingressadas é de melhor esforço e só se aplica a allowlists de sala em runtime quando dangerouslyAllowNameMatching: true está definido.
• Se um nome de sala não puder ser resolvido para um ID ou alias, ele será ignorado pela resolução de allowlist em runtime.

Referência de configuração

Campos de usuário no estilo allowlist (groupAllowFrom, dm.allowFrom, groups.<room>.users) aceitam IDs de usuário Matrix completos (mais seguro). Entradas de usuário que não são IDs são ignoradas por padrão. Se você definir dangerouslyAllowNameMatching: true, correspondências exatas de nome de exibição no diretório Matrix serão resolvidas na inicialização e sempre que a allowlist mudar enquanto o monitor estiver em execução; entradas que não puderem ser resolvidas serão ignoradas em runtime.

Chaves de allowlist de sala (groups, legado rooms) devem ser IDs de sala ou aliases. Chaves de nome de sala simples são ignoradas por padrão; dangerouslyAllowNameMatching: true restaura a pesquisa de melhor esforço em nomes de salas ingressadas.

Conta e conexão

• enabled: habilita ou desabilita o canal.
• name: rótulo de exibição opcional para a conta.
• defaultAccount: ID da conta preferida quando várias contas Matrix estão configuradas.
• accounts: substituições nomeadas por conta. Valores de nível superior em channels.matrix são herdados como padrões.
• homeserver: URL do homeserver, por exemplo https://matrix.example.org.
• network.dangerouslyAllowPrivateNetwork: permite que esta conta se conecte a localhost, IPs de LAN/Tailscale ou hostnames internos.
• proxy: URL de proxy HTTP(S) opcional para tráfego Matrix. Há suporte a substituição por conta.
• userId: ID de usuário Matrix completo (@bot:example.org).
• accessToken: token de acesso para autenticação baseada em token. Há suporte a valores em texto claro e SecretRef entre provedores env/file/exec (Gerenciamento de segredos).
• password: senha para login baseado em senha. Há suporte a valores em texto claro e SecretRef.
• deviceId: ID de dispositivo Matrix explícito.
• deviceName: nome de exibição do dispositivo usado no momento do login por senha.
• avatarUrl: URL do avatar próprio armazenada para sincronização de perfil e atualizações de profile set.
• initialSyncLimit: número máximo de eventos buscados durante a sincronização de inicialização.

Criptografia

• encryption: habilita E2EE. Padrão: false.
• startupVerification: "if-unverified" (padrão quando E2EE está ativado) ou "off". Solicita automaticamente autoverificação na inicialização quando este dispositivo não está verificado.
• startupVerificationCooldownHours: intervalo antes da próxima solicitação automática de inicialização. Padrão: 24.

Acesso e política

• groupPolicy: "open", "allowlist" ou "disabled". Padrão: "allowlist".
• groupAllowFrom: allowlist de IDs de usuário para tráfego de sala.
• mentionPatterns: padrões regex com escopo para menções em salas. Objeto com { mode: "allow"|"deny", allowIn: [roomId, ...], denyIn: [roomId, ...] }. Controla se agents.list[].groupChat.mentionPatterns configurados se aplicam por sala.
• dm.enabled: quando false, ignora todas as DMs. Padrão: true.
• dm.policy: "pairing" (padrão), "allowlist", "open" ou "disabled". Aplica-se depois que o bot entrou e classificou a sala como DM; não afeta o tratamento de convites.
• dm.allowFrom: allowlist de IDs de usuário para tráfego de DM.
• dm.sessionScope: "per-user" (padrão) ou "per-room".
• dm.threadReplies: substituição exclusiva de DM para encadeamento de respostas ("off", "inbound", "always").
• allowBots: aceita mensagens de outras contas de bot Matrix configuradas (true ou "mentions").
• allowlistOnly: quando true, força todas as políticas de DM ativas (exceto "disabled") e políticas de grupo "open" para "allowlist". Não altera políticas "disabled".
• dangerouslyAllowNameMatching: quando true, permite pesquisa no diretório de nomes de exibição Matrix para entradas de allowlist de usuários e pesquisa por nome de salas ingressadas para chaves de allowlist de sala. Prefira IDs completos @user:server e IDs de sala ou aliases.
• autoJoin: "always", "allowlist" ou "off". Padrão: "off". Aplica-se a todo convite Matrix, incluindo convites no estilo DM.
• autoJoinAllowlist: salas/aliases permitidos quando autoJoin é "allowlist". Entradas de alias são resolvidas contra o homeserver, não contra o estado declarado pela sala convidada.
• contextVisibility: visibilidade de contexto suplementar ("all" padrão, "allowlist", "allowlist_quote").

Comportamento de resposta

• replyToMode: "off", "first", "all" ou "batched".
• threadReplies: "off", "inbound" ou "always".
• threadBindings: substituições por canal para roteamento e ciclo de vida de sessão vinculados a thread.
• streaming: "off" (padrão), "partial", "quiet", "progress" ou forma de objeto { mode, preview: { toolProgress }, progress: { label, labels, maxLines, maxLineChars, toolProgress } }. true ↔ "partial", false ↔ "off".
• blockStreaming: quando true, blocos concluídos do assistente são mantidos como mensagens de progresso separadas.
• markdown: configuração opcional de renderização Markdown para texto de saída.
• responsePrefix: string opcional anexada ao início das respostas de saída.
• textChunkLimit: tamanho do bloco de saída em caracteres quando chunkMode: "length". Padrão: 4000.
• chunkMode: "length" (padrão, divide por contagem de caracteres) ou "newline" (divide em limites de linha).
• historyLimit: número de mensagens recentes da sala incluídas como InboundHistory quando uma mensagem de sala aciona o agente. Recai para messages.groupChat.historyLimit; padrão efetivo 0 (desabilitado).
• mediaMaxMb: limite de tamanho de mídia em MB para envios de saída e processamento de entrada.

Configurações de reação

• ackReaction: substituição de reação de confirmação para este canal/conta.
• ackReactionScope: substituição de escopo ("group-mentions" padrão, "group-all", "direct", "all", "none", "off").
• reactionNotifications: modo de notificação de reação de entrada ("own" padrão, "off").

Ferramentas e substituições por sala

• actions: controle de ferramentas por ação (messages, reactions, pins, profile, memberInfo, channelInfo, verification).
• groups: mapa de política por sala. A identidade da sessão usa o ID estável da sala após a resolução. (rooms é um alias legado.)
  • groups.<room>.account: restringe uma entrada de sala herdada a uma conta específica.
  • groups.<room>.enabled: alternância por sala. Quando false, a sala é ignorada como se não estivesse no mapa.
  • groups.<room>.requireMention: substituição por sala do requisito de menção no nível do canal.
  • groups.<room>.allowBots: substituição por sala da configuração no nível do canal (true ou "mentions").
  • groups.<room>.botLoopProtection: substituição por sala do orçamento de proteção contra loops entre bots.
  • groups.<room>.users: lista de remetentes permitidos por sala.
  • groups.<room>.tools: substituições de permissão/bloqueio de ferramentas por sala.
  • groups.<room>.autoReply: substituição por sala do controle por menções. true desabilita os requisitos de menção para essa sala; false força a reativação deles.
  • groups.<room>.skills: filtro de skill por sala.
  • groups.<room>.systemPrompt: trecho de prompt de sistema por sala.

Configurações de aprovação de exec

• execApprovals.enabled: entrega aprovações de exec por prompts nativos do Matrix.
• execApprovals.approvers: IDs de usuário do Matrix autorizados a aprovar. Recorre a dm.allowFrom.
• execApprovals.target: "dm" (padrão), "channel" ou "both".
• execApprovals.agentFilter / execApprovals.sessionFilter: listas de permissões opcionais de agente/sessão para entrega.

Relacionado

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