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 antes de configurar o canal:

openclaw plugins install @openclaw/matrix

A partir de um checkout local:

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

plugins install registra e habilita o Plugin, então nenhuma etapa separada openclaw plugins enable matrix é necessária. O Plugin ainda não faz nada até que você configure o canal abaixo. Consulte Plugins para ver o comportamento geral de Plugins e as 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 permite).

# Configuração interativa

openclaw channels add
openclaw 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 deve habilitar E2EE e se deve configurar acesso a salas e entrada automática.

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á habilitado, 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 como padrão. Com o padrão, o bot não aparecerá em novas salas ou DMs de convites recentes até que você entre manualmente.

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 DM - passam primeiro por autoJoin. dm.policy só se aplica depois, após o bot entrar e a sala ser 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 DM e sala são melhor preenchidas com IDs estáveis:

• DMs (dm.allowFrom, groupAllowFrom, groups.<room>.users): use @user:server. Nomes de exibição só são resolvidos quando o diretório do homeserver retorna exatamente uma correspondência.
• Salas (groups, autoJoinAllowlist): use !room:server ou #alias:server. Nomes são resolvidos com melhor esforço em relação às salas já ingressadas; entradas não resolvidas são ignoradas em tempo de execução.

# Normalização do ID da conta

O assistente converte um nome amigável em um ID de conta normalizado. Por exemplo, Ops Bot vira ops-bot. 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 é mapeado para MATRIX_OPS_X2D_PROD_*.

# Credenciais em cache

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, OpenClaw trata 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 do 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 da CLI cientes de recuperação (verify backup restore, verify device, verify bootstrap) quando você envia a chave via pipe usando --recovery-key-stdin.

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

# Exemplo de configuração

Uma 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é-visualizações de streaming

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

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

Para manter pré-visualizações de respostas ao vivo, mas ocultar linhas intermediárias de ferramentas/progresso, use a forma de objeto:

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

blockStreaming é independente de streaming:

Observações:

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

# 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. 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, OpenClaw divide o texto visível em partes e anexa com.openclaw.approval apenas à primeira parte. 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é-visualizações finalizadas silenciosas

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

# Salas bot-a-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 somente quando elas mencionam visivelmente este bot em salas. DMs ainda são permitidas.
• groups.<room>.allowBots substitui a configuração no nível da conta para uma sala.
• OpenClaw ainda ignora mensagens do mesmo ID de usuário Matrix para evitar loops de autorresposta.
• Matrix não expõe uma sinalização nativa de bot aqui; OpenClaw trata "autoria de bot" como "enviado por outra conta Matrix configurada neste Gateway OpenClaw".

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

# Criptografia e verificação

Em salas criptografadas (E2EE), eventos de imagem de saída usam thumbnail_file para que pré-visualizações de imagem sejam criptografadas junto com o anexo completo. Salas não criptografadas ainda usam thumbnail_url simples. Nenhuma configuração é necessária - o Plugin detecta automaticamente o estado de E2EE.

Todos os comandos openclaw matrix aceitam --verbose (diagnósticos completos), --json (saída legível por máquina) e --account <id> (configurações com várias contas). A saída é concisa por padrão, com registro interno silencioso 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 de segredos e a assinatura cruzada, cria um backup de chaves de sala se necessário e então 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 atual de assinatura cruzada 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 status
openclaw matrix verify status --include-recovery-key --json

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

• Locally trusted: confiável apenas por este cliente
• Cross-signing verified: o SDK relata 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 somente quando Cross-signing verified é yes. Confiança local ou uma assinatura do proprietário por si só não é suficiente.

--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 - envie-a por 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 relata três estados:

• Recovery key accepted: o Matrix aceitou a chave para armazenamento de segredos 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 a partir de 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 com chave literal openclaw matrix verify device "<recovery-key>" também é aceita, mas a chave acaba no histórico do seu shell.

# Inicializar ou reparar a assinatura cruzada

openclaw matrix verify bootstrap

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

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

Se o homeserver exigir UIA para enviar chaves de assinatura cruzada, o OpenClaw tenta primeiro sem autenticação, depois m.login.dummy e então 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 atual de assinatura cruzada (apenas intencionalmente)

# Backup de chaves de sala

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

backup status mostra se existe um backup no servidor e se este dispositivo consegue descriptografá-lo. backup restore importa as chaves de sala em backup para o armazenamento criptográfico local; se a chave de recuperação já estiver em 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 de segredos se o segredo do backup atual não puder ser carregado):

openclaw matrix verify backup reset --yes

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

# Listar, solicitar e responder a verificações

openclaw matrix verify list

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

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

Envia uma solicitação de verificação a partir 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 para 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 acompanhar 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.

# Observações sobre várias contas

Sem --account <id>, os 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 list
openclaw matrix devices prune-stale

# Gerenciamento de perfil

Atualize o autoperfil do Matrix para a conta selecionada:

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

Você pode passar ambas as opções em uma 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 por 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.

Associações explícitas de conversa sempre prevalecem sobre sessionScope, então salas e threads associadas mantêm a sessão de destino escolhida.

# Respostas em thread (threadReplies)

threadReplies decide onde o bot publica sua resposta:

• "off": as respostas são de nível superior. Mensagens de entrada em thread permanecem na sessão pai.
• "inbound": responde dentro de uma thread somente quando a mensagem de entrada já estava nessa thread.
• "always": responde dentro de uma thread enraizada na mensagem acionadora; essa conversa é roteada por uma sessão correspondente com escopo de thread a partir do primeiro acionamento.

dm.threadReplies substitui isto apenas para DMs - por exemplo, manter threads de sala isoladas enquanto mantém DMs sem threads.

# Herança de threads e comandos de barra

• As mensagens encadeadas de entrada incluem a mensagem raiz do thread como contexto extra do agente.
• Envios pela ferramenta de mensagens herdam automaticamente o thread Matrix atual ao mirar a mesma sala (ou o mesmo alvo de usuário por DM), a menos que um threadId explícito seja fornecido.
• A reutilização de alvo de usuário por 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 recorre ao roteamento normal com escopo por usuário.
• /focus, /unfocus, /agents, /session idle, /session max-age e /acp spawn vinculado a thread funcionam em salas e DMs do Matrix.
• /focus no nível superior cria um novo thread Matrix e o vincula à sessão de destino quando threadBindings.spawnSessions está habilitado.
• Executar /focus ou /acp spawn --thread here dentro de um thread Matrix existente vincula esse thread no lugar.

Quando o OpenClaw detecta uma sala de DM do Matrix em conflito 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 os vínculos de thread estão habilitados.

# Vínculos de conversa ACP

Salas, DMs e threads Matrix existentes podem ser transformados 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, sala ou thread existente do Matrix que você quer continuar usando.
• Em uma DM ou sala Matrix de nível superior, a DM/sala atual permanece como a superfície de chat e as mensagens futuras são roteadas para a sessão ACP gerada.
• Dentro de um thread Matrix existente, --bind here vincula o thread atual no lugar.
• /new e /reset redefinem a mesma sessão ACP vinculada no lugar.
• /acp close fecha a sessão ACP e remove o vínculo.

Observações:

• --bind here não cria um thread filho no Matrix.
• threadBindings.spawnSessions controla /acp spawn --thread auto|here, quando o OpenClaw precisa criar ou vincular um thread filho no 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

A geração de sessões vinculadas a threads do Matrix vem habilitada por padrão:

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

# Reações

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

A ferramenta de reações de saída é controlada por channels.matrix.actions.reactions:

• react adiciona uma reação a um evento Matrix.
• reactions lista o resumo atual de reações para um evento Matrix.
• emoji="" remove as próprias reações do bot naquele evento.
• remove: true remove apenas a reação do emoji especificado 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 do sistema de reações. Remoções de reações não são sintetizadas em eventos do sistema porque o Matrix as expõe como redações, não como remoções independentes de m.reaction.

# Contexto do histórico

• channels.matrix.historyLimit controla quantas mensagens recentes da sala são incluídas como InboundHistory quando uma mensagem em sala Matrix aciona o agente. Recorre a messages.groupChat.historyLimit; se ambos não estiverem definidos, o padrão efetivo é 0. Defina 0 para desabilitar.
• O histórico de salas Matrix é apenas da sala. DMs continuam usando o histórico normal da sessão.
• O histórico de salas Matrix é somente pendente: o OpenClaw armazena em buffer mensagens da sala que ainda não acionaram uma resposta e captura uma cópia dessa janela quando uma menção ou outro gatilho chega.
• A mensagem de gatilho atual não é incluída em InboundHistory; ela permanece no corpo principal de entrada daquele turno.
• Novas tentativas do mesmo evento Matrix reutilizam o instantâneo original do histórico em vez de avançar para mensagens mais novas da sala.

# Visibilidade de contexto

O Matrix oferece suporte ao controle compartilhado contextVisibility para contexto suplementar de sala, como texto de resposta buscado, raízes de threads 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 explicitamente citada.

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

# Política de DMs e salas

{
  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 mantendo as salas funcionando, defina dm.enabled: false:

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

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

Exemplo de pareamento para DMs do Matrix:

openclaw pairing list matrix
openclaw 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 período de espera, em vez de gerar um novo código.

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

# Reparo de sala direta

Se o estado de mensagens diretas ficar fora de sincronia, o OpenClaw pode acabar com mapeamentos m.direct obsoletos que apontam para salas individuais antigas em vez da DM ativa. Inspecione o mapeamento atual para um par:

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

Repare:

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
• recorre a qualquer DM 1:1 estrita atualmente ingressada com esse usuário
• cria uma nova sala direta e reescreve m.direct se não houver uma DM íntegra

Ele não exclui salas antigas automaticamente. Ele escolhe a DM íntegra e atualiza o mapeamento para que envios futuros pelo Matrix, avisos de verificação e outros fluxos de mensagens diretas mirem a sala correta.

# Aprovações de execução

O Matrix pode atuar como um cliente nativo de aprovação. 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 definido como "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 execução. Opcional - recorre a channels.matrix.dm.allowFrom.
• target: para onde os prompts vão. "dm" (padrão) envia para as DMs dos aprovadores; "channel" envia para a sala Matrix ou DM de origem; "both" envia para ambos.
• agentFilter / sessionFilter: allowlists opcionais para quais agentes/sessões acionam a entrega pelo Matrix.

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

• Aprovações de execução usam execApprovals.approvers, recorrendo a 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 principal de aprovação:

• ✅ permitir uma vez
• ❌ negar
• ♾️ permitir sempre (quando a política efetiva de execução permite)

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

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

Relacionado: Aprovações de execução.

# Comandos slash

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

As regras de autorização ainda se aplicam: os remetentes dos 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 de channels.matrix atuam como padrões para contas nomeadas, a menos que uma conta os substitua.
• Restrinja uma entrada de sala herdada a 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 preferida por roteamento implícito, sondagem e comandos da CLI.
• Se você tiver várias contas e uma delas se chamar literalmente default, o OpenClaw a usará implicitamente mesmo quando defaultAccount não estiver definido.
• Se você tiver várias contas nomeadas e nenhum padrão selecionado, 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 inicial, ele preserva a conta nomeada existente se houver uma ou se defaultAccount já apontar para uma. Apenas chaves de autenticação/bootstrap do Matrix são movidas para a conta promovida; chaves compartilhadas de política de entrega permanecem no nível superior.

Consulte a referência de configuração para ver 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, em um IP de LAN/Tailscale ou em um nome de host 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 pela CLI:

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

Esta 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 do tráfego Matrix

Se sua implantação do 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 o tráfego Matrix em tempo de execução e sondagens de status de conta.

# Resolução de destinos

O Matrix aceita estes formatos de destino em qualquer lugar em que o OpenClaw solicite 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
• Apelidos: #alias:server, channel:#alias:server ou matrix:channel:#alias:server

IDs de sala do 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 de Cron, vinculações ou listas de permissões. O OpenClaw mantém chaves internas de sessão canônicas para armazenamento, então essas chaves em minúsculas não são uma fonte confiável para IDs de entrega do Matrix.

A consulta ao diretório em tempo real usa a conta do Matrix conectada:

• Consultas de usuários consultam o diretório de usuários do Matrix nesse homeserver.
• Consultas de salas aceitam IDs de sala e apelidos explícitos diretamente e, em seguida, recorrem à busca nos nomes de salas ingressadas dessa conta.
• A consulta por nome de sala ingressada é de melhor esforço. Se um nome de sala não puder ser resolvido para um ID ou apelido, ele será ignorado pela resolução de lista de permissões em tempo de execução.

# Referência de configuração

Campos do tipo lista de permissões (groupAllowFrom, dm.allowFrom, groups.<room>.users) aceitam IDs completos de usuários do Matrix (mais seguro). Correspondências exatas de diretório são resolvidas na inicialização e sempre que a lista de permissões muda enquanto o monitor está em execução; entradas que não podem ser resolvidas são ignoradas em tempo de execução. Listas de permissões de salas preferem IDs de sala ou apelidos pelo mesmo motivo.

# 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. Os valores de nível superior de channels.matrix são herdados como padrões.
• homeserver: URL do servidor doméstico, por exemplo https://matrix.example.org.
• network.dangerouslyAllowPrivateNetwork: permite que esta conta se conecte a localhost, IPs de LAN/Tailscale ou nomes de host internos.
• proxy: URL opcional de proxy HTTP(S) para o tráfego Matrix. Há suporte a substituição por conta.
• userId: ID completo de usuário Matrix (@bot:example.org).
• accessToken: token de acesso para autenticação baseada em token. Há suporte a valores em texto simples e SecretRef entre provedores de env/file/exec (Gerenciamento de segredos).
• password: senha para login baseado em senha. Há suporte a valores em texto simples e SecretRef.
• deviceId: ID explícito do dispositivo Matrix.
• deviceName: nome de exibição do dispositivo usado no momento do login por senha.
• avatarUrl: URL do autoavatar armazenado 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 a autoverificação na inicialização quando este dispositivo não está verificado.
• startupVerificationCooldownHours: intervalo antes da próxima solicitação automática na inicialização. Padrão: 24.

# Acesso e política

• groupPolicy: "open", "allowlist" ou "disabled". Padrão: "allowlist".
• groupAllowFrom: lista de permissões de IDs de usuário para tráfego de 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 uma DM; não afeta o tratamento de convites.
• dm.allowFrom: lista de permissões de IDs de usuário para tráfego de DM.
• dm.sessionScope: "per-user" (padrão) ou "per-room".
• dm.threadReplies: substituição somente para 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".
• 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 em relação ao servidor doméstico, não em relação ao estado reivindicado pela sala convidada.
• contextVisibility: visibilidade de contexto suplementar (padrão "all", "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ões vinculadas a threads.
• streaming: "off" (padrão), "partial", "quiet" ou forma de objeto { mode, preview: { 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 de Markdown para texto de saída.
• responsePrefix: string opcional prefixada às 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 nos 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 da reação de confirmação para este canal/conta.
• ackReactionScope: substituição de escopo (padrão "group-mentions", "group-all", "direct", "all", "none", "off").
• reactionNotifications: modo de notificação de reação de entrada (padrão "own", "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íticas 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 herdada de sala a uma conta específica.
  • groups.<room>.allowBots: substituição por sala da configuração no nível do canal (true ou "mentions").
  • groups.<room>.users: lista de permissões de remetentes por sala.
  • groups.<room>.tools: substituições de permitir/negar ferramentas por sala.
  • groups.<room>.autoReply: substituição por sala do controle por menção. true desabilita os requisitos de menção para essa sala; false força sua reativação.
  • groups.<room>.skills: filtro de Skills 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 meio de prompts nativos do Matrix.
• execApprovals.approvers: IDs de usuário Matrix autorizados a aprovar. Recai para 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.

# Relacionados

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