> ## Documentation Index > Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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](/pt-BR/tools/plugin) 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](#auto-join) - convites novos só entram quando `autoJoin` os permite). ### Configuração interativa ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 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`](#encryption-and-verification). ### Configuração mínima Baseada em token: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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): ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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. Defina `autoJoin: "allowlist"` mais `autoJoinAllowlist` para restringir quais convites o bot aceita, ou `autoJoin: "always"` para aceitar todos os convites. `autoJoinAllowlist` aceita apenas destinos estáveis: `!roomId:server`, `#alias:server` ou `*`. Nomes simples de salas são rejeitados; entradas de alias são resolvidas contra o homeserver, não contra o estado declarado pela sala convidada. ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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..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-.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. | Conta padrão | Conta nomeada (`` é o ID de conta normalizado) | | --------------------- | -------------------------------------------------- | | `MATRIX_HOMESERVER` | `MATRIX__HOMESERVER` | | `MATRIX_ACCESS_TOKEN` | `MATRIX__ACCESS_TOKEN` | | `MATRIX_USER_ID` | `MATRIX__USER_ID` | | `MATRIX_PASSWORD` | `MATRIX__PASSWORD` | | `MATRIX_DEVICE_ID` | `MATRIX__DEVICE_ID` | | `MATRIX_DEVICE_NAME` | `MATRIX__DEVICE_NAME` | | `MATRIX_RECOVERY_KEY` | `MATRIX__RECOVERY_KEY` | 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](/pt-BR/gateway/security). ## Exemplo de configuração Uma linha de base prática com pareamento de DM, allowlist de salas e E2EE: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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. ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { matrix: { streaming: { mode: "partial", preview: { toolProgress: false, }, }, }, }, } ``` A forma completa de objeto aceita `{ mode, preview, progress }`: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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. | `streaming` | Comportamento | | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `"off"` (padrão) | Aguarda a resposta completa e envia uma vez. `true` ↔ `"partial"`, `false` ↔ `"off"`. | | `"partial"` | Edita uma mensagem de texto normal no local enquanto o modelo escreve o bloco atual. Clientes Matrix padrão podem notificar na primeira prévia, não na edição final. | | `"quiet"` | Igual a `"partial"`, mas a mensagem é um aviso sem notificação. Destinatários só recebem uma notificação quando uma regra de push por usuário corresponde à edição finalizada (veja abaixo). | | `"progress"` | Envia linhas individuais compactas de progresso usando um rascunho de progresso. | `blockStreaming` é independente de `streaming`: | `streaming` | `blockStreaming: true` | `blockStreaming: false` (padrão) | | ----------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------ | | `"partial"` / `"quiet"` | Rascunho ao vivo para o bloco atual, blocos concluídos mantidos como mensagens | Rascunho ao vivo para o bloco atual, finalizado no local | | `"off"` | Uma mensagem Matrix com notificação por bloco concluído | Uma mensagem Matrix com notificação para a resposta completa | 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](/pt-BR/tools/media-overview) 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](/pt-BR/channels/matrix-push-rules) 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: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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..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](/pt-BR/channels/bot-loop-protection) compartilhada. Configure `channels.defaults.botLoopProtection` e depois substitua com `channels.matrix.botLoopProtection` ou `channels.matrix.groups..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 ` (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 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 ` 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: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { matrix: { enabled: true, homeserver: "https://matrix.example.org", accessToken: "syt_xxx", encryption: true, dm: { policy: "pairing" }, }, }, } ``` ### Status e sinais de confiança ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw matrix verify status openclaw 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__RECOVERY_KEY` para uma conta nomeada): ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw matrix verify self ``` `verify self` aguarda `Cross-signing verified: yes` antes de sair com sucesso. Use `--timeout-ms ` para ajustar a espera. A forma de chave literal `openclaw matrix verify device ""` também é aceita, mas a chave acaba no histórico do seu shell. ### Inicializar ou reparar assinatura cruzada ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 ` * `--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 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 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): ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw matrix verify list ``` Lista solicitações de verificação pendentes para a conta selecionada. ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 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 `` (impressa por `verify list` e `verify request`): | Comando | Finalidade | | ------------------------------------------ | --------------------------------------------------------------------- | | `openclaw matrix verify accept ` | Aceitar uma solicitação recebida | | `openclaw matrix verify start ` | Iniciar o fluxo SAS | | `openclaw matrix verify sas ` | Imprimir o emoji ou os decimais SAS | | `openclaw matrix verify confirm-sas ` | Confirmar que o SAS corresponde ao que o outro cliente mostra | | `openclaw matrix verify mismatch-sas ` | Rejeitar o SAS quando o emoji ou os decimais não corresponderem | | `openclaw matrix verify cancel ` | Cancelar; aceita `--reason ` e `--code ` opcionais | `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 `, 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`. Com `encryption: true`, `startupVerification` assume `"if-unverified"` por padrão. Na inicialização, um dispositivo não verificado solicita autoverificação em outro cliente Matrix, evitando duplicatas e aplicando um cooldown (24 horas por padrão). Ajuste com `startupVerificationCooldownHours` ou desabilite com `startupVerification: "off"`. A inicialização também executa uma passagem conservadora de inicialização criptográfica que reutiliza o armazenamento secreto e a identidade de assinatura cruzada atuais. Se o estado de inicialização estiver quebrado, o OpenClaw tenta um reparo protegido mesmo sem `channels.matrix.password`; se o homeserver exigir UIA por senha, a inicialização registra um aviso e permanece não fatal. Dispositivos já assinados pelo proprietário são preservados. Consulte [Migração do Matrix](/pt-BR/channels/matrix-migration) para o fluxo completo de upgrade. O Matrix publica avisos de ciclo de vida de verificação na sala de verificação por DM estrita como mensagens `m.notice`: solicitação, pronto (com orientação "Verificar por emoji"), início/conclusão e detalhes de SAS (emoji/decimal) quando disponíveis. Solicitações recebidas de outro cliente Matrix são rastreadas e aceitas automaticamente. Para autoverificação, o OpenClaw inicia o fluxo SAS automaticamente e confirma seu próprio lado assim que a verificação por emoji está disponível - você ainda precisa comparar e confirmar "Eles correspondem" no seu cliente Matrix. Avisos do sistema de verificação não são encaminhados ao pipeline de chat do agente. Se `verify status` disser que o dispositivo atual não está mais listado no homeserver, crie um novo dispositivo Matrix do OpenClaw. Para login por senha: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw matrix account add \ --account assistant \ --homeserver https://matrix.example.org \ --user-id '@assistant:example.org' \ --password '' \ --device-name OpenClaw-Gateway ``` Para autenticação por token, crie um token de acesso novo no seu cliente Matrix ou na UI administrativa e então atualize o OpenClaw: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw matrix account add \ --account assistant \ --homeserver https://matrix.example.org \ --access-token '' ``` Substitua `assistant` pelo ID da conta do comando que falhou, ou omita `--account` para a conta padrão. Dispositivos antigos gerenciados pelo OpenClaw podem se acumular. Liste e remova os obsoletos: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw matrix devices list openclaw matrix devices prune-stale ``` A E2EE do Matrix usa o caminho oficial de criptografia Rust do `matrix-js-sdk` com `fake-indexeddb` como shim de IndexedDB. O estado criptográfico persiste em `crypto-idb-snapshot.json` (permissões de arquivo restritivas). O estado de runtime criptografado fica em `~/.openclaw/matrix/accounts//__//` e inclui o armazenamento de sincronização, o armazenamento de criptografia, a chave de recuperação, o snapshot do IDB, os vínculos de threads e o estado de verificação de inicialização. Quando o token muda, mas a identidade da conta permanece a mesma, o OpenClaw reutiliza a melhor raiz existente para que o estado anterior continue visível. Uma única raiz token-hash mais antiga pode ser um caminho normal de continuidade de rotação de token. Se o OpenClaw registrar `matrix: multiple populated token-hash storage roots detected`, inspecione o diretório da conta e arquive raízes irmãs obsoletas somente depois de confirmar que a raiz ativa selecionada está saudável. Prefira mover raízes obsoletas para um diretório `_archive/` em vez de excluí-las imediatamente. ## Gerenciamento de perfil Atualize o autoperfil Matrix da conta selecionada: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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): | Configuração | Ordem | | ----------------------- | -------------------------------------------------------------------------------------- | | `ackReaction` | por conta → canal → `messages.ackReaction` → fallback de emoji da identidade do agente | | `ackReactionScope` | por conta → canal → `messages.ackReactionScope` → padrão `"group-mentions"` | | `reactionNotifications` | por conta → canal → padrão `"own"` | `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 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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`: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { matrix: { dm: { enabled: false }, groupPolicy: "allowlist", groupAllowFrom: ["@admin:example.org"], }, }, } ``` Consulte [Grupos](/pt-BR/channels/groups) para o comportamento de controle por menção e allowlist. Exemplo de pareamento para DMs do Matrix: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw pairing list matrix openclaw pairing approve matrix ``` 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](/pt-BR/channels/pairing) 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: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw matrix direct inspect --user-id @alice:example.org ``` Repare-o: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw matrix direct repair --user-id @alice:example.org ``` Ambos os comandos aceitam `--account ` 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..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 allow-once`, `/approve allow-always`, `/approve 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](/pt-BR/tools/exec-approvals). ## 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 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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..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 `. * 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](/pt-BR/gateway/config-channels#multi-account-all-channels) 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: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { matrix: { homeserver: "http://matrix-synapse:8008", network: { dangerouslyAllowPrivateNetwork: true, }, accessToken: "syt_internal_xxx", }, }, } ``` Exemplo de configuração da CLI: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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`: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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..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..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](/pt-BR/gateway/secrets)). * `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..account`: restringe uma entrada de sala herdada a uma conta específica. * `groups..enabled`: alternância por sala. Quando `false`, a sala é ignorada como se não estivesse no mapa. * `groups..requireMention`: substituição por sala do requisito de menção no nível do canal. * `groups..allowBots`: substituição por sala da configuração no nível do canal (`true` ou `"mentions"`). * `groups..botLoopProtection`: substituição por sala do orçamento de proteção contra loops entre bots. * `groups..users`: lista de remetentes permitidos por sala. * `groups..tools`: substituições de permissão/bloqueio de ferramentas por sala. * `groups..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..skills`: filtro de skill por sala. * `groups..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](/pt-BR/channels) - todos os canais compatíveis * [Pareamento](/pt-BR/channels/pairing) - autenticação por DM e fluxo de pareamento * [Grupos](/pt-BR/channels/groups) - comportamento de chats em grupo e controle por menções * [Roteamento de canais](/pt-BR/channels/channel-routing) - roteamento de sessões para mensagens * [Segurança](/pt-BR/gateway/security) - modelo de acesso e fortalecimento