​

Matrix

​

Plugin incluído

openclaw plugins install @openclaw/matrix

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

​

Configuração inicial

1. Verifique se o plugin Matrix está disponível.
   • As versões empacotadas atuais do OpenClaw já o incluem.
   • Instalações antigas/personalizadas podem adicioná-lo manualmente com os comandos acima.
2. Crie uma conta Matrix no seu homeserver.
3. Configure channels.matrix com um destes formatos:
   • homeserver + accessToken, ou
   • homeserver + userId + password.
4. Reinicie o gateway.
5. Inicie uma DM com o bot ou convide-o para uma sala.
   • Convites novos do Matrix só funcionam quando channels.matrix.autoJoin os permite.

openclaw channels add
openclaw configure --section channels

• URL do homeserver
• método de autenticação: token de acesso ou senha
• ID do usuário (apenas autenticação por senha)
• nome do dispositivo opcional
• se deve ativar E2EE
• se deve configurar acesso à sala e entrada automática por convite

• Se as variáveis de ambiente de autenticação do Matrix já existirem e essa conta ainda não tiver autenticação salva na configuração, o assistente oferece um atalho de env para manter a autenticação nas variáveis de ambiente.
• Os nomes das contas são normalizados para o ID da conta. Por exemplo, Ops Bot vira ops-bot.
• Entradas de allowlist de DM aceitam @user:server diretamente; nomes de exibição só funcionam quando a busca ativa no diretório encontra uma correspondência exata.
• Entradas de allowlist de sala aceitam IDs e aliases de sala diretamente. Prefira !room:server ou #alias:server; nomes não resolvidos são ignorados em tempo de execução pela resolução da allowlist.
• No modo de allowlist de entrada automática por convite, use apenas destinos de convite estáveis: !roomId:server, #alias:server ou *. Nomes simples de salas são rejeitados.
• Para resolver nomes de salas antes de salvar, use openclaw channels resolve --channel matrix "Project Room".

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

{
  channels: {
    matrix: {
      autoJoin: "always",
    },
  },
}

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

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

• MATRIX_HOMESERVER
• MATRIX_ACCESS_TOKEN
• MATRIX_USER_ID
• MATRIX_PASSWORD
• MATRIX_DEVICE_ID
• MATRIX_DEVICE_NAME

• MATRIX_<ACCOUNT_ID>_HOMESERVER
• MATRIX_<ACCOUNT_ID>_ACCESS_TOKEN
• MATRIX_<ACCOUNT_ID>_USER_ID
• MATRIX_<ACCOUNT_ID>_PASSWORD
• MATRIX_<ACCOUNT_ID>_DEVICE_ID
• MATRIX_<ACCOUNT_ID>_DEVICE_NAME

• MATRIX_OPS_HOMESERVER
• MATRIX_OPS_ACCESS_TOKEN

• MATRIX_OPS_X2D_BOT_HOMESERVER
• MATRIX_OPS_X2D_BOT_ACCESS_TOKEN

​

Exemplo de configuração

{
  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 por streaming

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

• streaming: "off" é o padrão. O OpenClaw espera a resposta final e a envia uma vez.
• streaming: "partial" cria uma mensagem de prévia editável para o bloco atual do assistente usando mensagens de texto normais do Matrix. Isso preserva o comportamento legado do Matrix de notificar primeiro a prévia, então clientes padrão podem notificar com base no primeiro texto da prévia transmitida em vez do bloco finalizado.
• streaming: "quiet" cria uma prévia silenciosa e editável para o bloco atual do assistente. Use isso apenas quando também configurar regras de push do destinatário para edições finalizadas da prévia.
• blockStreaming: true ativa mensagens separadas de progresso no Matrix. Com streaming de prévia ativado, o Matrix mantém o rascunho ao vivo do bloco atual e preserva os blocos concluídos como mensagens separadas.
• Quando a prévia por streaming está ativada e blockStreaming está desativado, o Matrix edita o rascunho ao vivo no lugar e finaliza esse mesmo evento quando o bloco ou turno termina.
• Se a prévia não couber mais em um único evento do Matrix, o OpenClaw interrompe a prévia por streaming e volta para a entrega final normal.
• Respostas com mídia continuam enviando anexos normalmente. Se uma prévia antiga não puder mais ser reutilizada com segurança, o OpenClaw a remove antes de enviar a resposta final com mídia.
• Edições de prévia geram chamadas extras à API do Matrix. Deixe o streaming desativado se quiser o comportamento mais conservador em relação a limite de taxa.

• blockStreaming: true envia cada bloco concluído como uma mensagem normal notificável do Matrix.
• blockStreaming: false envia apenas a resposta final concluída como uma mensagem normal notificável do Matrix.

​

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

• usuário destinatário = a pessoa que deve receber a notificação
• usuário bot = a conta Matrix do OpenClaw que envia a resposta
• use o token de acesso do usuário destinatário nas chamadas de API abaixo
• faça a correspondência de sender na regra de push com o MXID completo do usuário bot

1. Configure o OpenClaw para usar prévias silenciosas:

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

2. Certifique-se de que a conta destinatária já receba notificações push normais do Matrix. Regras para prévias silenciosas só funcionam se esse usuário já tiver pushers/dispositivos funcionando.
3. Obtenha o token de acesso do usuário destinatário.
   • Use o token do usuário que recebe, não o token do bot.
   • Reaproveitar o token de uma sessão existente do cliente normalmente é o mais fácil.
   • Se precisar gerar um token novo, você pode fazer login pela API Client-Server padrão do Matrix:

curl -sS -X POST \
  "https://matrix.example.org/_matrix/client/v3/login" \
  -H "Content-Type: application/json" \
  --data '{
    "type": "m.login.password",
    "identifier": {
      "type": "m.id.user",
      "user": "@alice:example.org"
    },
    "password": "REDACTED"
  }'

4. Verifique se a conta destinatária já tem pushers:

curl -sS \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  "https://matrix.example.org/_matrix/client/v3/pushers"

{
  "com.openclaw.finalized_preview": true
}

5. Crie uma regra de push de override para cada conta destinatária que deve receber essas notificações:

curl -sS -X PUT \
  "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "conditions": [
      { "kind": "event_match", "key": "type", "pattern": "m.room.message" },
      {
        "kind": "event_property_is",
        "key": "content.m\\.relates_to.rel_type",
        "value": "m.replace"
      },
      {
        "kind": "event_property_is",
        "key": "content.com\\.openclaw\\.finalized_preview",
        "value": true
      },
      { "kind": "event_match", "key": "sender", "pattern": "@bot:example.org" }
    ],
    "actions": [
      "notify",
      { "set_tweak": "sound", "value": "default" },
      { "set_tweak": "highlight", "value": false }
    ]
  }'

• https://matrix.example.org: URL base do seu homeserver
• $USER_ACCESS_TOKEN: token de acesso do usuário que recebe
• openclaw-finalized-preview-botname: um ID de regra único para este bot para este usuário destinatário
• @bot:example.org: o MXID do seu bot Matrix do OpenClaw, não o MXID do usuário destinatário

• Regras de push são indexadas por ruleId. Executar PUT novamente contra o mesmo ID de regra atualiza essa regra.
• Se um usuário destinatário deve receber notificações de várias contas Matrix bot do OpenClaw, crie uma regra por bot com um ID de regra único para cada correspondência de remetente.
• Um padrão simples é openclaw-finalized-preview-<botname>, como openclaw-finalized-preview-ops ou openclaw-finalized-preview-support.

• autentique com o token do usuário destinatário
• faça a correspondência de sender com o MXID do bot do OpenClaw

6. Verifique se a regra existe:

curl -sS \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname"

7. Teste uma resposta por streaming. No modo silencioso, a sala deve mostrar uma prévia silenciosa em rascunho e a edição final no lugar deve notificar quando o bloco ou o turno terminar.

curl -sS -X DELETE \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname"

• Crie a regra com o token de acesso do usuário destinatário, não com o token do bot.
• Novas regras override definidas pelo usuário são inseridas antes das regras padrão de supressão, então nenhum parâmetro extra de ordenação é necessário.
• Isso afeta apenas edições de prévia somente de texto que o OpenClaw consegue finalizar com segurança no lugar. Fallbacks de mídia e fallbacks de prévia antiga continuam usando a entrega normal do Matrix.
• Se GET /_matrix/client/v3/pushers não mostrar pushers, o usuário ainda não tem entrega push do Matrix funcionando para essa conta/dispositivo.

​

Synapse

• Nenhuma alteração especial em homeserver.yaml é necessária para notificações de prévia finalizada do OpenClaw.
• Se sua implantação do Synapse já envia notificações push normais do Matrix, o token do usuário + a chamada pushrules acima são a principal etapa de configuração.
• Se você executa o Synapse atrás de um proxy reverso ou workers, certifique-se de que /_matrix/client/.../pushrules/ chegue corretamente ao Synapse.
• Se você executa workers do Synapse, certifique-se de que os pushers estejam saudáveis. A entrega de push é tratada pelo processo principal ou por synapse.app.pusher / workers de pusher configurados.

​

Tuwunel

• Nenhuma configuração específica do Tuwunel é necessária para o marcador de prévia finalizada em si.
• Se as notificações normais do Matrix já funcionam para esse usuário, o token do usuário + a chamada pushrules acima são a principal etapa de configuração.
• Se as notificações parecerem desaparecer enquanto o usuário está ativo em outro dispositivo, verifique se suppress_push_when_active está ativado. O Tuwunel adicionou essa opção no Tuwunel 1.4.2 em 12 de setembro de 2025, e ela pode suprimir intencionalmente envios push para outros dispositivos enquanto um dispositivo está ativo.

​

Salas bot para bot

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

• allowBots: true aceita mensagens de outras contas Matrix bot configuradas em salas e DMs permitidas.
• allowBots: "mentions" aceita essas mensagens apenas quando mencionam visivelmente este bot em salas. DMs continuam permitidas.
• groups.<room>.allowBots substitui a configuração em nível de conta para uma sala.
• O OpenClaw ainda ignora mensagens do mesmo ID de usuário Matrix para evitar loops de autorresposta.
• O Matrix não expõe aqui uma sinalização nativa de bot; o OpenClaw trata “de autoria de bot” como “enviado por outra conta Matrix configurada neste gateway OpenClaw”.

​

Criptografia e verificação

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

openclaw matrix verify status

openclaw matrix verify status --verbose

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

openclaw matrix verify bootstrap

openclaw matrix verify bootstrap --verbose

openclaw matrix verify bootstrap --force-reset-cross-signing

openclaw matrix verify device "<your-recovery-key>"

openclaw matrix verify device "<your-recovery-key>" --verbose

openclaw matrix verify backup status

openclaw matrix verify backup status --verbose

openclaw matrix verify backup restore

openclaw matrix verify backup restore --verbose

openclaw matrix verify backup reset --yes

openclaw matrix verify status --account assistant
openclaw matrix verify backup restore --account assistant
openclaw matrix devices list --account assistant

​

O que “verified” significa

• Locally trusted: este dispositivo é confiável apenas pelo cliente atual
• Cross-signing verified: o SDK relata o dispositivo como verificado via cross-signing
• Signed by owner: o dispositivo é assinado pela sua própria chave self-signing

​

O que o bootstrap faz

• inicializa o armazenamento secreto, reaproveitando uma chave de recuperação existente quando possível
• inicializa o cross-signing e faz upload das chaves públicas de cross-signing ausentes
• tenta marcar e assinar via cross-signing o dispositivo atual
• cria um novo backup de chaves de sala no servidor se ainda não existir

​

Nova base de backup

openclaw matrix verify backup reset --yes
openclaw matrix verify backup status --verbose
openclaw matrix verify status

​

Comportamento na inicialização

​

Avisos de verificação

• avisos de solicitação de verificação
• avisos de verificação pronta (com orientação explícita “Verifique por emoji”)
• avisos de início e conclusão da verificação
• detalhes de SAS (emoji e decimal) quando disponíveis

​

Higiene de dispositivos

openclaw matrix devices list

openclaw matrix devices prune-stale

​

Armazenamento de criptografia

​

Gerenciamento de perfil

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

​

Threads

• dm.sessionScope: "per-user" (padrão) mantém o roteamento de DM do Matrix com escopo por remetente, para que várias salas de DM possam compartilhar uma sessão quando forem resolvidas para o mesmo par.
• dm.sessionScope: "per-room" isola cada sala de DM do Matrix em sua própria chave de sessão, ainda usando autenticação normal de DM e verificações de allowlist.
• Bindings explícitos de conversa Matrix ainda têm precedência sobre dm.sessionScope, então salas e threads vinculadas mantêm a sessão de destino escolhida.
• threadReplies: "off" mantém respostas no nível superior e mantém mensagens recebidas em thread na sessão pai.
• threadReplies: "inbound" responde dentro de uma thread apenas quando a mensagem recebida já estava nessa thread.
• threadReplies: "always" mantém respostas de sala em uma thread enraizada na mensagem que acionou a resposta e encaminha essa conversa pela sessão com escopo de thread correspondente a partir da primeira mensagem acionadora.
• dm.threadReplies substitui a configuração de nível superior apenas para DMs. Por exemplo, você pode manter threads de sala isoladas enquanto mantém DMs planas.
• Mensagens recebidas em thread incluem a mensagem raiz da thread como contexto extra para o agente.
• Envios com ferramentas de mensagem herdam automaticamente a thread atual do Matrix quando o destino é a mesma sala, ou o mesmo alvo de usuário em DM, a menos que um threadId explícito seja fornecido.
• O reaproveitamento do mesmo alvo de usuário de DM na mesma sessão 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 para o roteamento normal com escopo por usuário.
• Quando o OpenClaw detecta que uma sala de DM do Matrix colide com outra sala de DM na mesma sessão de DM compartilhada do Matrix, ele publica um m.notice único nessa sala com a rota de escape /focus quando bindings de thread estão ativados e a dica dm.sessionScope.
• Bindings de thread em tempo de execução são suportados para Matrix. /focus, /unfocus, /agents, /session idle, /session max-age e /acp spawn vinculado a thread funcionam em salas e DMs do Matrix.
• /focus de sala/DM Matrix no nível superior cria uma nova thread Matrix e a vincula à sessão de destino quando threadBindings.spawnSubagentSessions=true.
• Executar /focus ou /acp spawn --thread here dentro de uma thread Matrix existente vincula essa thread atual.

​

Bindings de conversa ACP

• 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 no nível superior, a DM/sala atual permanece como superfície de chat e mensagens futuras são roteadas para a sessão ACP criada.
• Dentro de uma thread Matrix existente, --bind here vincula essa 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 binding.

• --bind here não cria uma thread Matrix filha.
• threadBindings.spawnAcpSessions só é necessário para /acp spawn --thread auto|here, quando o OpenClaw precisa criar ou vincular uma thread Matrix filha.

​

Configuração de binding de thread

• threadBindings.enabled
• threadBindings.idleHours
• threadBindings.maxAgeHours
• threadBindings.spawnSubagentSessions
• threadBindings.spawnAcpSessions

• Defina threadBindings.spawnSubagentSessions: true para permitir que /focus no nível superior crie e vincule novas threads Matrix.
• Defina threadBindings.spawnAcpSessions: true para permitir que /acp spawn --thread auto|here vincule sessões ACP a threads Matrix.

​

Reações

• O uso de reações de saída é controlado por channels["matrix"].actions.reactions.
• react adiciona uma reação a um evento Matrix específico.
• reactions lista o resumo atual de reações para um evento Matrix específico.
• emoji="" remove as reações da própria conta do bot nesse evento.
• remove: true remove apenas a reação do emoji especificado da conta do bot.

• channels["matrix"].accounts.<accountId>.ackReaction
• channels["matrix"].ackReaction
• messages.ackReaction
• fallback para o emoji de identidade do agente

• channels["matrix"].accounts.<accountId>.ackReactionScope
• channels["matrix"].ackReactionScope
• messages.ackReactionScope

• channels["matrix"].accounts.<accountId>.reactionNotifications
• channels["matrix"].reactionNotifications
• padrão: own

• reactionNotifications: "own" encaminha eventos m.reaction adicionados quando eles têm como alvo mensagens Matrix de autoria do bot.
• reactionNotifications: "off" desativa eventos de sistema de reação.
• Remoções de reação não são sintetizadas em eventos de sistema porque o Matrix as expõe como redações, não como remoções independentes de m.reaction.

​

Contexto de histórico

• channels.matrix.historyLimit controla quantas mensagens recentes da sala são incluídas como InboundHistory quando uma mensagem de sala no Matrix aciona o agente. Usa messages.groupChat.historyLimit como fallback; se ambos não estiverem definidos, o padrão efetivo é 0. Defina 0 para desativar.
• 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 acionaram resposta, depois tira um snapshot dessa janela quando chega uma menção ou outro gatilho.
• A mensagem atual que acionou a resposta não é incluída em InboundHistory; ela permanece no corpo principal de entrada para esse turno.
• Novas tentativas do mesmo evento Matrix reutilizam o snapshot de histórico original em vez de avançar para mensagens mais novas da sala.

​

Visibilidade de contexto

• 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.

​

Política de DM e sala

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

openclaw pairing list matrix
openclaw pairing approve matrix <CODE>

​

Reparo de sala direta

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

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

• prefere uma DM estrita 1:1 que já esteja mapeada em m.direct
• recorre a qualquer DM estrita 1:1 atualmente conectada com esse usuário
• cria uma nova sala direta e reescreve m.direct se não existir uma DM saudável

​

Aprovações de exec

• channels.matrix.execApprovals.enabled
• channels.matrix.execApprovals.approvers (opcional; usa channels.matrix.dm.allowFrom como fallback)
• channels.matrix.execApprovals.target (dm | channel | both, padrão: dm)
• channels.matrix.execApprovals.agentFilter
• channels.matrix.execApprovals.sessionFilter

• channels.matrix.execApprovals.* controla o modo nativo de distribuição em DM/canal para prompts de aprovação do Matrix.
• Aprovações de exec usam o conjunto de aprovadores de exec de execApprovals.approvers ou channels.matrix.dm.allowFrom.
• Aprovações de plugin usam a allowlist de DM do Matrix em channels.matrix.dm.allowFrom.
• Atalhos por reação e atualizações de mensagem do Matrix se aplicam tanto a aprovações de exec quanto a aprovações de plugin.

• target: "dm" envia prompts de aprovação para as DMs dos aprovadores
• target: "channel" envia o prompt de volta para a sala ou DM Matrix de origem
• target: "both" envia para as DMs dos aprovadores e para a sala ou DM Matrix de origem

• ✅ = permitir uma vez
• ❌ = negar
• ♾️ = permitir sempre quando essa decisão for permitida pela política efetiva de exec

• channels.matrix.accounts.<account>.execApprovals

​

Múltiplas 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",
          },
        },
      },
    },
  },
}

​

Homeservers privados/LAN

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

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

​

Uso de proxy para tráfego Matrix

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

​

Resolução de destino

• 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

• Buscas de usuário consultam o diretório de usuários do Matrix nesse homeserver.
• Buscas de sala aceitam diretamente IDs e aliases explícitos de sala, depois recorrem à busca por nomes de salas já conectadas para essa conta.
• A busca por nome de sala conectada é best-effort. Se o nome de uma sala não puder ser resolvido para um ID ou alias, ele será ignorado pela resolução de allowlist em tempo de execução.

​

Referência de configuração

• enabled: ativa ou desativa o canal.
• name: rótulo opcional da conta.
• defaultAccount: ID de conta preferido quando várias contas Matrix estão configuradas.
• homeserver: URL do homeserver, por exemplo https://matrix.example.org.
• network.dangerouslyAllowPrivateNetwork: permite que esta conta Matrix se conecte a homeservers privados/internos. Ative isso quando o homeserver resolver para localhost, um IP de LAN/Tailscale ou um host interno como matrix-synapse.
• proxy: URL opcional de proxy HTTP(S) para tráfego Matrix. Contas nomeadas podem substituir o padrão de nível superior com seu próprio proxy.
• userId: ID completo de usuário Matrix, por exemplo @bot:example.org.
• accessToken: token de acesso para autenticação baseada em token. Valores em texto simples e valores SecretRef são compatíveis com channels.matrix.accessToken e channels.matrix.accounts.<id>.accessToken em provedores env/file/exec. Veja Gerenciamento de segredos.
• password: senha para login baseado em senha. Valores em texto simples e valores SecretRef são compatíveis.
• deviceId: ID explícito do dispositivo Matrix.
• deviceName: nome de exibição do dispositivo para login por senha.
• avatarUrl: URL armazenada do próprio avatar para sincronização de perfil e atualizações de profile set.
• initialSyncLimit: número máximo de eventos buscados durante a sincronização na inicialização.
• encryption: ativa E2EE.
• allowlistOnly: quando true, promove a política de sala open para allowlist e força todas as políticas ativas de DM, exceto disabled (incluindo pairing e open), para allowlist. Não afeta políticas disabled.
• allowBots: permite mensagens de outras contas Matrix do OpenClaw configuradas (true ou "mentions").
• groupPolicy: open, allowlist ou disabled.
• contextVisibility: modo de visibilidade do contexto suplementar da sala (all, allowlist, allowlist_quote).
• groupAllowFrom: allowlist de IDs de usuário para tráfego de sala. As entradas devem ser IDs completos de usuário Matrix; nomes não resolvidos são ignorados em tempo de execução.
• historyLimit: máximo de mensagens da sala a incluir como contexto de histórico de grupo. Usa messages.groupChat.historyLimit como fallback; se ambos não estiverem definidos, o padrão efetivo é 0. Defina 0 para desativar.
• replyToMode: off, first, all ou batched.
• markdown: configuração opcional de renderização Markdown para texto Matrix de saída.
• streaming: off (padrão), "partial", "quiet", true ou false. "partial" e true ativam atualizações de rascunho com prévia primeiro usando mensagens de texto normais do Matrix. "quiet" usa avisos de prévia sem notificação para configurações auto-hospedadas com regras de push. false equivale a "off".
• blockStreaming: true ativa mensagens separadas de progresso para blocos concluídos do assistente enquanto o streaming de prévia em rascunho estiver ativo.
• threadReplies: off, inbound ou always.
• threadBindings: substituições por canal para roteamento e ciclo de vida de sessão vinculada a thread.
• startupVerification: modo automático de solicitação de autoverificação na inicialização (if-unverified, off).
• startupVerificationCooldownHours: cooldown antes de repetir solicitações automáticas de verificação na inicialização.
• textChunkLimit: tamanho do bloco de mensagem de saída em caracteres (aplica-se quando chunkMode é length).
• chunkMode: length divide mensagens por contagem de caracteres; newline divide em limites de linha.
• responsePrefix: string opcional prefixada a todas as respostas de saída deste canal.
• ackReaction: substituição opcional da reação de confirmação para este canal/conta.
• ackReactionScope: substituição opcional do escopo da reação de confirmação (group-mentions, group-all, direct, all, none, off).
• reactionNotifications: modo de notificação de reação recebida (own, off).
• mediaMaxMb: limite de tamanho de mídia em MB para envios de saída e processamento de mídia recebida.
• autoJoin: política de entrada automática por convite (always, allowlist, off). Padrão: off. Aplica-se a todos os convites do Matrix, incluindo convites no estilo DM.
• autoJoinAllowlist: salas/aliases permitidos quando autoJoin é allowlist. Entradas de alias são resolvidas para IDs de sala durante o tratamento do convite; o OpenClaw não confia no estado de alias declarado pela sala convidada.
• dm: bloco de política de DM (enabled, policy, allowFrom, sessionScope, threadReplies).
• dm.policy: controla o acesso à DM depois que o OpenClaw entrou na sala e a classificou como DM. Não altera se um convite é aceito automaticamente.
• dm.allowFrom: as entradas devem ser IDs completos de usuário Matrix, a menos que você já as tenha resolvido via busca ativa no diretório.
• dm.sessionScope: per-user (padrão) ou per-room. Use per-room quando quiser que cada sala de DM do Matrix mantenha contexto separado mesmo se o par for o mesmo.
• dm.threadReplies: substituição da política de thread apenas para DMs (off, inbound, always). Ela substitui a configuração de nível superior threadReplies tanto para posicionamento da resposta quanto para isolamento de sessão em DMs.
• execApprovals: entrega nativa de aprovação de exec no Matrix (enabled, approvers, target, agentFilter, sessionFilter).
• execApprovals.approvers: IDs de usuário Matrix autorizados a aprovar solicitações de exec. Opcional quando dm.allowFrom já identifica os aprovadores.
• execApprovals.target: dm | channel | both (padrão: dm).
• accounts: substituições nomeadas por conta. Valores de nível superior em channels.matrix atuam como padrões para essas entradas.
• groups: mapa de políticas por sala. Prefira IDs ou aliases de sala; nomes de salas não resolvidos são ignorados em tempo de execução. A identidade de sessão/grupo usa o ID estável da sala após a resolução.
• groups.<room>.account: restringe uma entrada de sala herdada a uma conta Matrix específica em configurações com múltiplas contas.
• groups.<room>.allowBots: substituição em nível de sala para remetentes bot configurados (true ou "mentions").
• groups.<room>.users: allowlist de remetentes por sala.
• groups.<room>.tools: substituições por sala de permitir/negar ferramentas.
• groups.<room>.autoReply: substituição em nível de sala para exigência de menção. true desativa exigências de menção para essa sala; false volta a forçá-las.
• groups.<room>.skills: filtro opcional de Skills por sala.
• groups.<room>.systemPrompt: trecho opcional de prompt de sistema por sala.
• rooms: alias legado para groups.
• actions: controle por ação do uso de ferramentas (messages, reactions, pins, profile, memberInfo, channelInfo, verification).

​

Relacionado

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