Microsoft Teams

Status: há suporte a texto + anexos em MDs; o envio de arquivos em canais/grupos requer sharePointSiteId + permissões do Graph (consulte Envio de arquivos em chats em grupo). As enquetes são enviadas por meio de Adaptive Cards. As ações de mensagem disponibilizam explicitamente upload-file para envios que começam por um arquivo.

Plugin incluído

O Microsoft Teams é fornecido como um plugin incluído nas versões atuais do OpenClaw; nenhuma instalação separada é necessária na compilação empacotada normal.

Em uma compilação mais antiga ou em uma instalação personalizada que exclua o Teams incluído, instale o pacote npm diretamente:

openclaw plugins install @openclaw/msteams

Use o pacote sem versão para acompanhar a tag da versão oficial atual. Fixe uma versão exata somente quando precisar de uma instalação reproduzível.

Checkout local (executando a partir de um repositório git):

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

Detalhes: Plugins

Configuração rápida

O @microsoft/teams.cli realiza o registro do bot, a criação do manifesto e a geração de credenciais em um único comando.

1. Instale e faça login

npm install -g @microsoft/teams.cli@previewteams loginteams status   # verifique se você fez login e veja as informações do seu locatário

2. Inicie um túnel (o Teams não consegue acessar localhost)

Instale e autentique a CLI devtunnel, se necessário (guia de introdução).

# Configuração única (URL persistente entre sessões):devtunnel create my-openclaw-bot --allow-anonymousdevtunnel port create my-openclaw-bot -p 3978 --protocol auto # Em cada sessão de desenvolvimento:devtunnel host my-openclaw-bot# Seu endpoint: https://<tunnel-id>.devtunnels.ms/api/messages

Alternativas: ngrok http 3978 ou tailscale funnel 3978 (as URLs podem mudar a cada sessão).

3. Crie o aplicativo

teams app create \  --name "OpenClaw" \  --endpoint "https://<your-tunnel-url>/api/messages"

Isso cria um aplicativo do Entra ID (Azure AD), gera um segredo do cliente, cria e carrega um manifesto de aplicativo do Teams (com ícones) e registra um bot gerenciado pelo Teams (nenhuma assinatura do Azure é necessária). A saída inclui CLIENT_ID, CLIENT_SECRET, TENANT_ID e uma ID de aplicativo do Teams; ela também oferece a opção de instalar o aplicativo diretamente no Teams.

4. Configure o OpenClaw usando as credenciais da saída:

{  channels: {    msteams: {      enabled: true,      appId: "<CLIENT_ID>",      appPassword: "<CLIENT_SECRET>",      tenantId: "<TENANT_ID>",      webhook: { port: 3978, path: "/api/messages" },    },  },}

Ou use as variáveis de ambiente diretamente: MSTEAMS_APP_ID, MSTEAMS_APP_PASSWORD, MSTEAMS_TENANT_ID.

5. Instale o aplicativo no Teams

teams app create solicita que você instale o aplicativo; selecione "Install in Teams". Para obter o link de instalação posteriormente:

teams app get <teamsAppId> --install-link

6. Verifique se tudo funciona

teams app doctor <teamsAppId>

Executa diagnósticos do registro do bot, da configuração do aplicativo AAD, da validade do manifesto e da configuração de SSO.

Para produção, considere a autenticação federada (certificado ou identidade gerenciada) em vez de segredos do cliente.

Objetivos

• Conversar com o OpenClaw por meio de MDs, chats em grupo ou canais do Teams.
• Manter o roteamento determinístico: as respostas sempre retornam ao canal pelo qual chegaram.
• Usar por padrão um comportamento seguro nos canais (menções obrigatórias, a menos que configurado de outra forma).

Gravações de configuração

Por padrão, o Microsoft Teams pode gravar atualizações de configuração acionadas por /config set|unset (requer commands.config: true).

Desative com:

{  channels: { msteams: { configWrites: false } },}

Controle de acesso (MDs + grupos)

Acesso por MD

• Padrão: channels.msteams.dmPolicy = "pairing". Remetentes desconhecidos são ignorados até serem aprovados.
• channels.msteams.allowFrom deve usar IDs de objeto AAD estáveis ou grupos estáticos de acesso de remetentes, como accessGroup:core-team.
• Não dependa da correspondência por UPN/nome de exibição para listas de permissões; eles podem mudar. O OpenClaw desativa a correspondência direta por nome por padrão; habilite-a com channels.msteams.dangerouslyAllowNameMatching: true.
• O assistente pode resolver nomes para IDs por meio do Microsoft Graph quando as credenciais permitirem.

Acesso de grupo

• Padrão: channels.msteams.groupPolicy = "allowlist" (bloqueado, a menos que você adicione groupAllowFrom). channels.defaults.groupPolicy pode substituir o padrão compartilhado quando channels.msteams.groupPolicy não estiver definido.
• channels.msteams.groupAllowFrom controla quais remetentes ou grupos estáticos de acesso de remetentes podem acionar ações em chats em grupo/canais (usa channels.msteams.allowFrom como alternativa).
• Defina groupPolicy: "open" para permitir qualquer membro (ainda com exigência de menção por padrão).
• Para bloquear todos os canais, defina channels.msteams.groupPolicy: "disabled".

Exemplo:

{  channels: {    msteams: {      groupPolicy: "allowlist",      groupAllowFrom: ["00000000-0000-0000-0000-000000000000", "accessGroup:core-team"],    },  },}

Lista de permissões de equipes + canais

• Restrinja as respostas de grupo/canal listando equipes e canais em channels.msteams.teams.
• Use IDs de conversa estáveis do Teams, obtidos em links do Teams, como chaves, e não nomes de exibição mutáveis (consulte IDs de equipe e canal).
• Quando groupPolicy="allowlist" e houver uma lista de permissões de equipes, somente as equipes/os canais listados serão aceitos (com exigência de menção).
• O assistente de configuração aceita entradas Team/Channel e as armazena para você.
• Na inicialização, o OpenClaw resolve nomes de equipe/canal e de usuários da lista de permissões para IDs (quando as permissões do Graph permitem) e registra o mapeamento. Os nomes não resolvidos são mantidos conforme digitados, mas ignorados para roteamento, a menos que channels.msteams.dangerouslyAllowNameMatching: true esteja definido.

Exemplo:

{  channels: {    msteams: {      groupPolicy: "allowlist",      teams: {        "My Team": {          channels: {            General: { requireMention: true },          },        },      },    },  },}

{  channels: {    msteams: {      enabled: true,      appId: "<APP_ID>",      appPassword: "<APP_PASSWORD>",      tenantId: "<TENANT_ID>",      webhook: { port: 3978, path: "/api/messages" },    },  },}

Autenticação federada (certificado mais identidade gerenciada)

Para produção, o OpenClaw oferece suporte à autenticação federada como alternativa aos segredos do cliente, por meio de channels.msteams.authType: "federated". Há dois métodos:

Opção A: Autenticação baseada em certificado

Use um certificado PEM registrado no registro do aplicativo do Entra ID.

Configuração:

1. Gere ou obtenha um certificado (formato PEM com chave privada).
2. Entra ID → App Registration → Certificates & secrets → Certificates → carregue o certificado público.

Configuração:

{  channels: {    msteams: {      enabled: true,      appId: "<APP_ID>",      tenantId: "<TENANT_ID>",      authType: "federated",      certificatePath: "/path/to/cert.pem",      webhook: { port: 3978, path: "/api/messages" },    },  },}

Variáveis de ambiente:

• MSTEAMS_AUTH_TYPE=federated
• MSTEAMS_CERTIFICATE_PATH=/path/to/cert.pem

Opção B: Identidade Gerenciada do Azure

Use a Identidade Gerenciada do Azure para autenticação sem senha na infraestrutura do Azure (AKS, App Service, VMs do Azure).

Como funciona:

1. O pod/a VM do bot tem uma identidade gerenciada (atribuída pelo sistema ou pelo usuário).
2. Uma credencial de identidade federada vincula a identidade gerenciada ao registro do aplicativo do Entra ID.
3. Durante a execução, o OpenClaw usa @azure/identity para adquirir tokens do endpoint IMDS do Azure.
4. O token é passado ao SDK do Teams para a autenticação do bot.

Pré-requisitos:

• Infraestrutura do Azure com identidade gerenciada ativada (identidade de carga de trabalho do AKS, App Service, VM).
• Credencial de identidade federada criada no registro do aplicativo do Entra ID.
• Acesso de rede ao IMDS (169.254.169.254:80) a partir do pod/da VM.

Configuração (identidade gerenciada atribuída pelo sistema):

{  channels: {    msteams: {      enabled: true,      appId: "<APP_ID>",      tenantId: "<TENANT_ID>",      authType: "federated",      useManagedIdentity: true,      webhook: { port: 3978, path: "/api/messages" },    },  },}

Configuração (identidade gerenciada atribuída pelo usuário): adicione managedIdentityClientId: "<MI_CLIENT_ID>" ao bloco acima.

Variáveis de ambiente:

• MSTEAMS_AUTH_TYPE=federated
• MSTEAMS_USE_MANAGED_IDENTITY=true
• MSTEAMS_MANAGED_IDENTITY_CLIENT_ID=<client-id> (somente atribuída pelo usuário)

Configuração da Identidade de Carga de Trabalho do AKS

Para implantações no AKS que usam identidade de carga de trabalho:

1. Habilite a identidade de carga de trabalho no cluster do AKS.

2. Crie uma credencial de identidade federada no registro de aplicativo do Entra ID:

   az ad app federated-credential create --id <APP_OBJECT_ID> --parameters '{  "name": "my-bot-workload-identity",  "issuer": "<AKS_OIDC_ISSUER_URL>",  "subject": "system:serviceaccount:<NAMESPACE>:<SERVICE_ACCOUNT>",  "audiences": ["api://AzureADTokenExchange"]}'

3. Anote a conta de serviço do Kubernetes com o ID de cliente do aplicativo:

   apiVersion: v1kind: ServiceAccountmetadata:  name: my-bot-sa  annotations:    azure.workload.identity/client-id: "<APP_CLIENT_ID>"

4. Adicione um rótulo ao pod para a injeção da identidade de carga de trabalho:

   metadata:  labels:    azure.workload.identity/use: "true"

5. Permita o acesso de rede ao IMDS (169.254.169.254): se estiver usando NetworkPolicy, adicione uma regra de saída para 169.254.169.254/32 na porta 80.

Comparação dos tipos de autenticação

certificateThumbprint pode ser definido junto com certificatePath, mas atualmente não é lido pelo caminho de autenticação; ele é aceito apenas para compatibilidade futura.

Padrão: quando authType não está definido, o OpenClaw usa autenticação por segredo do cliente (appPassword). As configurações existentes continuam funcionando sem alterações.

Desenvolvimento local (tunelamento)

O Teams não consegue acessar localhost. Use um túnel de desenvolvimento persistente para que a URL permaneça estável entre as sessões:

# Configuração única:devtunnel create my-openclaw-bot --allow-anonymousdevtunnel port create my-openclaw-bot -p 3978 --protocol auto # Em cada sessão de desenvolvimento:devtunnel host my-openclaw-bot

Alternativas: ngrok http 3978 ou tailscale funnel 3978 (as URLs podem mudar a cada sessão).

Se a URL do túnel mudar, atualize o endpoint:

teams app update <teamsAppId> --endpoint "https://<new-url>/api/messages"

Teste do bot

Execute os diagnósticos:

teams app doctor <teamsAppId>

Verifica o registro do bot, o aplicativo AAD, o manifesto e a configuração de SSO em uma única execução.

Envie uma mensagem de teste:

1. Instale o aplicativo do Teams (link de instalação obtido com teams app get <id> --install-link).
2. Encontre o bot no Teams e envie uma mensagem direta.
3. Verifique os logs do Gateway em busca de atividades recebidas.

Variáveis de ambiente

Estas chaves de configuração relacionadas à autenticação podem ser definidas por variáveis de ambiente em vez de openclaw.json (outras chaves de configuração, como groupPolicy ou historyLimit, só podem ser definidas na configuração):

Ação de informações do membro

O OpenClaw disponibiliza uma ação member-info baseada no Graph para o Microsoft Teams, permitindo que agentes e automações consultem detalhes verificados da lista de membros de uma conversa configurada.

Requisitos:

• Permissões RSC ChannelSettings.Read.Group e TeamMember.Read.Group (já incluídas no manifesto recomendado).

A ação fica disponível sempre que as credenciais do Graph estão configuradas; não há um controle separado channels.msteams.actions.memberInfo. As consultas em canais padrão retornam a identidade correspondente na lista de membros da equipe, o nome de exibição, o e-mail e as funções. Na mensagem direta ou no chat em grupo atual, a ação pode retornar o ID de usuário estável do remetente confiável. As consultas de membros de canais privados/compartilhados e de chats que não sejam o atual exigem permissões adicionais para a lista de membros e são rejeitadas pelo conjunto padrão de permissões.

Contexto do histórico

• channels.msteams.historyLimit controla quantas mensagens recentes do canal/grupo são incluídas no prompt. Usa messages.groupChat.historyLimit como alternativa e, depois, o padrão de 50. Defina como 0 para desabilitar.
• O histórico de threads obtido é filtrado pelas listas de remetentes permitidos (allowFrom / groupAllowFrom), portanto, a inclusão inicial do contexto da thread contém apenas mensagens de remetentes permitidos.
• O contexto de anexos citados (analisado a partir do HTML no esquema Skype Reply presente nos próprios anexos de uma resposta) é repassado sem filtragem; atualmente, somente a inclusão inicial do histórico da thread aplica o filtro da lista de remetentes permitidos.
• O histórico de mensagens diretas pode ser limitado com channels.msteams.dmHistoryLimit (turnos do usuário). Substituições por usuário: channels.msteams.dms["<user_id>"].historyLimit.

Permissões RSC atuais do Teams (manifesto)

Estas são as permissões resourceSpecific existentes no manifesto do nosso aplicativo do Teams. Elas se aplicam apenas dentro da equipe/do chat em que o aplicativo está instalado.

Para canais (escopo da equipe):

• ChannelMessage.Read.Group (Application) - receber todas as mensagens do canal sem @menção
• ChannelMessage.Send.Group (Application)
• Member.Read.Group (Application)
• Owner.Read.Group (Application)
• ChannelSettings.Read.Group (Application)
• TeamMember.Read.Group (Application)
• TeamSettings.Read.Group (Application)

Para chats em grupo:

• ChatMessage.Read.Chat (Application) - receber todas as mensagens do chat em grupo sem @menção

Adicione permissões RSC pela CLI do Teams:

teams app rsc add <teamsAppId> ChannelMessage.Read.Group --type Application

Exemplo de manifesto do Teams (com dados ocultados)

Exemplo mínimo e válido com os campos obrigatórios. Substitua os IDs e as URLs.

{  $schema: "https://developer.microsoft.com/en-us/json-schemas/teams/v1.23/MicrosoftTeams.schema.json",  manifestVersion: "1.23",  version: "1.0.0",  id: "00000000-0000-0000-0000-000000000000",  name: { short: "OpenClaw" },  developer: {    name: "Sua Organização",    websiteUrl: "https://example.com",    privacyUrl: "https://example.com/privacy",    termsOfUseUrl: "https://example.com/terms",  },  description: { short: "OpenClaw no Teams", full: "OpenClaw no Teams" },  icons: { outline: "outline.png", color: "color.png" },  accentColor: "#5B6DEF",  bots: [    {      botId: "11111111-1111-1111-1111-111111111111",      scopes: ["personal", "team", "groupChat"],      isNotificationOnly: false,      supportsCalling: false,      supportsVideo: false,      supportsFiles: true,    },  ],  webApplicationInfo: {    id: "11111111-1111-1111-1111-111111111111",  },  authorization: {    permissions: {      resourceSpecific: [        { name: "ChannelMessage.Read.Group", type: "Application" },        { name: "ChannelMessage.Send.Group", type: "Application" },        { name: "Member.Read.Group", type: "Application" },        { name: "Owner.Read.Group", type: "Application" },        { name: "ChannelSettings.Read.Group", type: "Application" },        { name: "TeamMember.Read.Group", type: "Application" },        { name: "TeamSettings.Read.Group", type: "Application" },        { name: "ChatMessage.Read.Chat", type: "Application" },      ],    },  },}

Ressalvas do manifesto (campos obrigatórios)

• bots[].botId deve corresponder ao ID do aplicativo do Azure Bot.
• webApplicationInfo.id deve corresponder ao ID do aplicativo do Azure Bot.
• bots[].scopes deve incluir as superfícies que você pretende usar (personal, team, groupChat).
• bots[].supportsFiles: true é obrigatório para o processamento de arquivos no escopo pessoal.
• authorization.permissions.resourceSpecific deve incluir permissões de leitura/envio de canal para o tráfego dos canais.

Atualização de um aplicativo existente

# Baixe, edite e reenvie o manifestoteams app manifest download <teamsAppId> manifest.json# Edite manifest.json localmente...teams app manifest upload manifest.json <teamsAppId># A versão é incrementada automaticamente se o conteúdo tiver sido alterado

Após a atualização, reinstale o aplicativo em cada equipe e encerre completamente e reinicie o Teams (não apenas feche a janela) para limpar os metadados em cache do aplicativo.

Recursos: somente RSC em comparação com Graph

Com somente RSC do Teams (aplicativo instalado, sem permissões da API do Graph)

Funciona:

• Ler o conteúdo de texto das mensagens do canal.
• Enviar conteúdo de texto às mensagens do canal.
• Receber anexos de arquivos pessoais (mensagens diretas).

NÃO funciona:

• Conteúdo de imagens ou arquivos de canais/grupos (o payload inclui apenas um trecho HTML).
• Baixar anexos armazenados no SharePoint/OneDrive.
• Ler o histórico de mensagens além do evento Webhook em tempo real.

Com RSC do Teams + permissões de aplicativo do Microsoft Graph

Adiciona:

• Download de conteúdo hospedado (imagens coladas nas mensagens).
• Download de anexos de arquivos armazenados no SharePoint/OneDrive.
• Leitura do histórico de mensagens de canais/chats pelo Graph.

RSC em comparação com a API do Graph

Em resumo: o RSC serve para monitoramento em tempo real; a API do Graph serve para acesso ao histórico. Para recuperar mensagens perdidas enquanto estava offline, você precisa da API do Graph com ChannelMessage.Read.All (exige consentimento do administrador).

Mídia + histórico habilitados pelo Graph

Habilite apenas as permissões de aplicativo do Microsoft Graph necessárias para os escopos e dados do Teams que você usa:

1. Entra ID (Azure AD) App Registration → adicione Application permissions do Graph:
   • ChannelMessage.Read.All para anexos e histórico de canais.
   • Chat.Read.All para anexos e histórico de chats em grupo.
   • Files.Read.All quando os bytes dos anexos precisarem ser baixados do armazenamento do SharePoint/OneDrive; configurações somente de histórico não precisam dessa permissão.
2. Grant admin consent para o locatário.
3. Incremente a versão do manifesto do aplicativo do Teams, reenvie-o e reinstale o aplicativo no Teams.
4. Encerre completamente e reinicie o Teams para limpar os metadados em cache do aplicativo.

Recuperação de arquivos de canais/grupos (graphMediaFallback)

O Teams pode remover marcadores de arquivo da atividade HTML enviada a um bot. Nesse caso, a atividade do Bot Framework não pode ser distinguida de uma mensagem HTML comum; a referência completa do anexo existe apenas na cópia da mensagem no Graph.

Ative o fallback após conceder as permissões acima:

{  channels: {    msteams: {      graphMediaFallback: true,    },  },}

Isso se aplica somente a canais e chats em grupo. Ele adiciona uma consulta de mensagem ao Graph sempre que uma atividade HTML não produz mídia diretamente baixável, inclusive em mensagens comuns ou que contêm apenas menções. O padrão é false, para que instalações existentes não passem a gerar tráfego adicional no Graph nem erros de permissão automaticamente.

Menções a usuários: as @menções funcionam sem configuração adicional para usuários que já estão na conversa. Para pesquisar e mencionar dinamicamente usuários que não estão na conversa atual, adicione a permissão User.Read.All (Application) e conceda o consentimento do administrador.

Limitações conhecidas

Tempos limite de Webhook

O Teams entrega mensagens por meio de um Webhook HTTP. O OpenClaw aplica tempos limite fixos do servidor HTTP ao listener desse Webhook: 30s de inatividade, 30s para a solicitação total e 15s para receber os cabeçalhos. O enriquecimento opcional de mídia recebida e contexto tem um orçamento compartilhado de 10 segundos, mas o SDK do Teams ainda aguarda o turno do agente antes de retornar a resposta do Webhook. Se o turno completo exceder a janela de repetição do Teams, você poderá observar:

• O Teams tentando entregar a mensagem novamente (causando duplicatas).
• Respostas descartadas.

As respostas são enviadas de forma proativa assim que o agente responde, mas execuções lentas do agente ainda podem resultar em novas tentativas ou duplicatas no Teams.

Suporte à nuvem do Teams e à URL de serviço

Este caminho do Teams baseado no SDK é validado em ambiente real para a nuvem pública do Microsoft Teams.

As respostas a mensagens recebidas usam o contexto do turno recebido do SDK do Teams. Operações proativas fora de contexto — envios, edições, exclusões, cartões, enquetes, mensagens de consentimento de arquivo e respostas enfileiradas de longa duração — usam o serviceUrl da referência de conversa armazenada. Por padrão, a nuvem pública usa o ambiente de nuvem pública do SDK do Teams e permite referências armazenadas no host público do Teams Connector: https://smba.trafficmanager.net/.

A nuvem pública é o padrão. Não é necessário definir channels.msteams.cloud nem channels.msteams.serviceUrl para bots comuns na nuvem pública.

Para nuvens não públicas do Teams, defina cloud e o limite proativo correspondente quando a Microsoft publicar um:

• channels.msteams.cloud seleciona a predefinição de nuvem do SDK do Teams para autenticação, validação de JWT, serviços de token e escopo do Graph.
• channels.msteams.serviceUrl seleciona o limite do endpoint do Bot Connector usado para validar referências de conversa armazenadas antes de envios, edições, exclusões, cartões, enquetes, mensagens de consentimento de arquivo e respostas enfileiradas de longa duração proativos. Ele é obrigatório para as nuvens USGov e DoD do SDK. Para China/21Vianet, o OpenClaw usa a predefinição China do SDK e aceita URLs de serviço armazenadas/configuradas somente em hosts de canal do Azure China Bot Framework.

A Microsoft publica os endpoints globais proativos do Bot Connector na seção Criar a conversa da documentação de mensagens proativas do Teams. Use o serviceUrl da atividade recebida quando estiver disponível; caso contrário, use a tabela da Microsoft abaixo.

Exemplo para GCC, em que a Microsoft documenta uma URL de serviço proativa separada, mas o SDK do Teams não disponibiliza uma predefinição de nuvem GCC separada:

{  "channels": {    "msteams": {      "serviceUrl": "https://smba.infra.gcc.teams.microsoft.com/teams"    }  }}

Exemplo para GCC High:

{  "channels": {    "msteams": {      "cloud": "USGov",      "serviceUrl": "https://smba.infra.gov.teams.microsoft.us/teams"    }  }}

channels.msteams.serviceUrl é restrita aos hosts compatíveis do Microsoft Teams Bot Connector. Quando uma URL de serviço é configurada, o OpenClaw verifica se a serviceUrl armazenada da conversa usa o mesmo host antes da execução de envios proativos, edições, exclusões, cartões, enquetes ou respostas de longa duração enfileiradas. Com a configuração padrão da nuvem pública, o OpenClaw interrompe a operação com segurança se uma conversa armazenada apontar para fora do host público do Teams Connector. Após alterar as configurações de nuvem/URL de serviço, receba uma nova mensagem da conversa para que a referência armazenada da conversa esteja atualizada.

China/21Vianet não tem uma URL smba proativa global separada na tabela de endpoints proativos do Teams da Microsoft. Configure cloud: "China" para que o SDK do Teams use os endpoints de autenticação, token e JWT do Azure China. Os envios proativos passam então a exigir uma referência de conversa armazenada proveniente de uma atividade recebida do Teams da China, ou uma URL de serviço configurada explicitamente, no limite do canal do Azure China Bot Framework (*.botframework.azure.cn). Os auxiliares do Teams baseados no Graph ficam desabilitados para cloud: "China" até que o OpenClaw encaminhe as solicitações do Graph pelo endpoint do Azure China Graph.

Formatação

O Markdown do Teams é mais limitado que o do Slack ou Discord:

• A formatação básica funciona: negrito, itálico, code, links.
• Markdown complexo (tabelas, listas aninhadas) pode não ser renderizado corretamente.
• Há suporte a Adaptive Cards para enquetes e envios de apresentação semântica (veja abaixo).

Configuração

Principais configurações (consulte /gateway/configuration para ver padrões compartilhados de canais):

• channels.msteams.enabled: habilita/desabilita o canal.
• channels.msteams.appId, channels.msteams.appPassword, channels.msteams.tenantId: credenciais do bot.
• channels.msteams.cloud: ambiente de nuvem do SDK do Teams (Public, USGov, USGovDoD ou China; padrão Public). Configure junto com serviceUrl para as nuvens do SDK USGov/DoD; a China usa a predefinição do SDK e referências de conversa armazenadas do Azure China Bot Framework, com auxiliares baseados no Graph desabilitados até que o roteamento do Graph para o Azure China seja disponibilizado.
• channels.msteams.serviceUrl: limite da URL de serviço do Bot Connector para operações proativas do SDK. A nuvem pública usa o padrão do SDK; configure para GCC (https://smba.infra.gcc.teams.microsoft.com/teams), GCC High ou DoD. A China aceita hosts de canal do Azure China Bot Framework quando a referência de conversa armazenada vem do Teams operado pela 21Vianet.
• channels.msteams.webhook.port (padrão 3978).
• channels.msteams.webhook.path (padrão /api/messages).
• channels.msteams.dmPolicy: pairing | allowlist | open | disabled (padrão pairing).
• channels.msteams.allowFrom: lista de permissões para mensagens diretas (recomendam-se IDs de objeto do AAD). O assistente resolve nomes em IDs durante a configuração quando o acesso ao Graph está disponível.
• channels.msteams.dangerouslyAllowNameMatching: opção emergencial para reabilitar a correspondência por UPN/nome de exibição mutável e o roteamento direto por nome de equipe/canal.
• channels.msteams.textChunkLimit: tamanho dos segmentos de texto de saída em caracteres (padrão 4000, com limite rígido de 4000, independentemente de um valor configurado mais alto).
• channels.msteams.streaming.chunkMode: length (padrão) ou newline para dividir em linhas em branco (limites de parágrafo) antes da segmentação por comprimento.
• channels.msteams.mediaAllowHosts: lista de permissões para hosts de anexos recebidos (o padrão são os domínios da Microsoft/Teams: Graph, SharePoint/OneDrive, CDN do Teams, Bot Framework e Azure Media Services).
• channels.msteams.mediaAuthAllowHosts: lista de permissões para anexar cabeçalhos Authorization em novas tentativas de mídia (o padrão são hosts do Graph + Bot Framework).
• channels.msteams.graphMediaFallback: permite consultas de mensagens no Graph quando o HTML do canal/grupo omite marcadores de arquivo (padrão false; consulte Recuperação de arquivos de canal/grupo).
• channels.msteams.mediaMaxMb: substituição do limite de tamanho de mídia por canal em MB. Usa agents.defaults.mediaMaxMb como alternativa quando não definido.
• channels.msteams.requireMention: exige @menção em canais/grupos (padrão true).
• channels.msteams.replyStyle: thread | top-level (consulte Estilo de resposta).
• channels.msteams.teams.<teamId>.replyStyle: substituição por equipe.
• channels.msteams.teams.<teamId>.requireMention: substituição por equipe.
• channels.msteams.teams.<teamId>.tools: substituições padrão da política de ferramentas por equipe (allow/deny/alsoAllow), usadas quando não há uma substituição de canal.
• channels.msteams.teams.<teamId>.toolsBySender: substituições padrão da política de ferramentas por remetente e por equipe (há suporte ao curinga "*").
• channels.msteams.teams.<teamId>.channels.<conversationId>.replyStyle: substituição por canal.
• channels.msteams.teams.<teamId>.channels.<conversationId>.requireMention: substituição por canal.
• channels.msteams.teams.<teamId>.channels.<conversationId>.tools: substituições da política de ferramentas por canal (allow/deny/alsoAllow).
• channels.msteams.teams.<teamId>.channels.<conversationId>.toolsBySender: substituições da política de ferramentas por remetente e por canal (há suporte ao curinga "*").
• As chaves de toolsBySender devem usar prefixos explícitos: channel:, id:, e164:, username:, name: (chaves legadas sem prefixo ainda são mapeadas apenas para id:).
• channels.msteams.authType: tipo de autenticação — "secret" (padrão) ou "federated".
• channels.msteams.certificatePath: caminho para o arquivo de certificado PEM (autenticação federada + certificado).
• channels.msteams.certificateThumbprint: impressão digital do certificado; aceita, mas não obrigatória para autenticação.
• channels.msteams.useManagedIdentity: habilita a autenticação com identidade gerenciada (modo federado).
• channels.msteams.managedIdentityClientId: ID do cliente para a identidade gerenciada atribuída pelo usuário.
• channels.msteams.sharePointSiteId: ID do site do SharePoint para uploads de arquivos em chats em grupo/canais (consulte Envio de arquivos em chats em grupo).
• channels.msteams.welcomeCard, channels.msteams.groupWelcomeCard, channels.msteams.promptStarters: Adaptive Card de boas-vindas exibido no primeiro contato por mensagem direta/grupo e seus botões de prompts sugeridos.
• channels.msteams.responsePrefix: texto prefixado às respostas de saída.
• channels.msteams.feedbackEnabled (padrão true), channels.msteams.feedbackReflection (padrão true), channels.msteams.feedbackReflectionCooldownMs: feedback de positivo/negativo nas respostas e acompanhamento de reflexão sobre feedback negativo.
• channels.msteams.sso, channels.msteams.delegatedAuth: conexão OAuth do Bot Framework e escopos delegados do Graph para fluxos baseados em SSO; sso.enabled: true exige sso.connectionName.

Roteamento e sessões

• As chaves de sessão seguem o formato padrão do agente (consulte /concepts/session):
  • As mensagens diretas compartilham a sessão principal (agent:<agentId>:<mainKey>).
  • As mensagens de canal/grupo usam o ID da conversa:
    • agent:<agentId>:msteams:channel:<conversationId>
    • agent:<agentId>:msteams:group:<conversationId>

Estilo de resposta: threads versus publicações

O Teams tem dois estilos de interface de canal sobre o mesmo modelo de dados subjacente:

O problema: a API do Teams não informa qual estilo de interface um canal usa. Se você usar o replyStyle incorreto:

• thread em um canal no estilo Threads → as respostas aparecem aninhadas de forma inadequada.
• top-level em um canal no estilo Publicações → as respostas aparecem como publicações separadas de nível superior, em vez de dentro do thread.

Solução: configure replyStyle por canal, com base em como o canal está configurado:

{  channels: {    msteams: {      replyStyle: "thread",      teams: {        "19:abc...@thread.tacv2": {          channels: {            "19:xyz...@thread.tacv2": {              replyStyle: "top-level",            },          },        },      },    },  },}

Precedência de resolução

Quando o bot envia uma resposta para um canal, replyStyle é resolvido da substituição mais específica até o padrão. O primeiro valor diferente de undefined prevalece:

1. Por canal - channels.msteams.teams.<teamId>.channels.<conversationId>.replyStyle
2. Por equipe - channels.msteams.teams.<teamId>.replyStyle
3. Global - channels.msteams.replyStyle
4. Padrão implícito - derivado de requireMention:
   • requireMention: true → thread
   • requireMention: false → top-level

Se você definir requireMention: false globalmente sem um replyStyle explícito, as menções em canais no estilo Publicações serão exibidas como publicações de nível superior, mesmo quando a mensagem recebida for uma resposta em um thread. Fixe replyStyle: "thread" no nível global, da equipe ou do canal para evitar surpresas.

Para envios proativos a uma conversa de canal armazenada (respostas enfileiradas de chamadas de ferramenta, agentes de longa duração), aplica-se a mesma resolução de equipe/canal; chats em grupo e conversas pessoais (DM) sempre são resolvidos como top-level para envios proativos, independentemente de replyStyle.

Preservação do contexto do thread

Quando replyStyle: "thread" está em vigor e o bot foi mencionado com @ dentro de um thread de canal, o OpenClaw reanexa a raiz original do thread à referência da conversa de saída (19:...@thread.tacv2;messageid=<root>) para que a resposta seja enviada dentro do mesmo thread. Isso vale tanto para envios ao vivo (durante o turno) quanto para envios proativos feitos após o contexto de turno do Bot Framework expirar (por exemplo, agentes de longa duração e respostas enfileiradas de chamadas de ferramenta via mcp__openclaw__message).

A raiz do thread é obtida do threadId armazenado na referência da conversa. Referências armazenadas mais antigas, anteriores ao threadId, recorrem ao activityId (a atividade recebida que inicializou a conversa mais recentemente), portanto as implantações existentes continuam funcionando sem uma nova inicialização.

Quando replyStyle: "top-level" está em vigor, mensagens recebidas em threads de canal são intencionalmente respondidas como novas publicações de nível superior; nenhum sufixo de thread é anexado. Isso é correto para canais no estilo Threads; publicações de nível superior quando você esperava respostas encadeadas significam que replyStyle está configurado incorretamente para esse canal.

Anexos e imagens

Limitações atuais:

• DMs: imagens e anexos de arquivos funcionam por meio das APIs de arquivos de bot do Teams.
• Canais/grupos: os anexos ficam no armazenamento do M365 (SharePoint/OneDrive). A carga do webhook inclui apenas um trecho HTML, não os bytes reais do arquivo. São necessárias permissões da API do Graph para baixar anexos de canais.
• Para envios explícitos que priorizam o arquivo, use action=upload-file com media / filePath / path; o message opcional se torna o texto/comentário acompanhante, e filename (ou title) substitui o nome do arquivo enviado.

Sem permissões do Graph, mensagens de canal com imagens chegam somente como texto (o conteúdo da imagem não fica acessível ao bot). Por padrão, o OpenClaw baixa mídia somente de nomes de host da Microsoft/Teams. Substitua isso com channels.msteams.mediaAllowHosts (use ["*"] para permitir qualquer host). Os cabeçalhos de autorização são anexados somente para hosts em channels.msteams.mediaAuthAllowHosts (o padrão inclui hosts do Graph e do Bot Framework). Mantenha essa lista restrita (evite sufixos multilocatário).

Envio de arquivos em chats em grupo

Os bots podem enviar arquivos em DMs usando o fluxo integrado do FileConsentCard. O envio de arquivos em chats em grupo/canais exige configuração adicional:

Por que chats em grupo precisam do SharePoint

Os bots usam uma identidade de aplicativo, enquanto o recurso /me do Microsoft Graph exige um usuário conectado. Para enviar arquivos em chats em grupo/canais, o bot faz o upload para um site do SharePoint e cria um link de compartilhamento.

Configuração

1. Adicione permissões da API do Graph em Entra ID (Azure AD) → App Registration:

   • Sites.ReadWrite.All (Application) - fazer upload de arquivos para o SharePoint.
   • Chat.Read.All (Application) - opcional, habilita links de compartilhamento por usuário.

2. Conceda consentimento do administrador para o locatário.

3. Obtenha o ID do seu site do SharePoint:

   # Pelo Graph Explorer ou curl com um token válido:curl -H "Authorization: Bearer $TOKEN" \  "https://graph.microsoft.com/v1.0/sites/{hostname}:/{site-path}" # Exemplo: para um site em "contoso.sharepoint.com/sites/BotFiles"curl -H "Authorization: Bearer $TOKEN" \  "https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com:/sites/BotFiles" # A resposta inclui: "id": "contoso.sharepoint.com,guid1,guid2"

4. Configure o OpenClaw:

   {  channels: {    msteams: {      // ... outras configurações ...      sharePointSiteId: "contoso.sharepoint.com,guid1,guid2",    },  },}

Comportamento de compartilhamento

O compartilhamento por usuário é mais seguro, pois somente os participantes do chat podem acessar o arquivo. Se Chat.Read.All estiver ausente, o bot recorre ao compartilhamento para toda a organização.

Comportamento alternativo

Local de armazenamento dos arquivos

Os arquivos enviados são armazenados em uma pasta /OpenClawShared/ na biblioteca de documentos padrão do site do SharePoint configurado.

Enquetes (Adaptive Cards)

O OpenClaw envia enquetes do Teams como Adaptive Cards (não existe uma API nativa de enquetes do Teams).

• CLI: openclaw message poll --channel msteams --target conversation:<id> --poll-question "..." --poll-option "..." --poll-option "...".
• Os votos são registrados pelo Gateway no SQLite de estado do Plugin do OpenClaw em state/openclaw.sqlite.
• Arquivos msteams-polls.json existentes são importados por openclaw doctor --fix, não pelo Plugin em execução.
• O Gateway deve permanecer online para registrar votos.
• As enquetes não publicam automaticamente resumos dos resultados, e ainda não existe uma CLI de resultados de enquetes.

Cartões de apresentação

Envie cargas semânticas de apresentação para usuários ou conversas do Teams usando a ferramenta message, a CLI ou a entrega normal de respostas. O OpenClaw as renderiza como Adaptive Cards do Teams a partir do contrato genérico de apresentação.

O parâmetro presentation aceita blocos semânticos. Quando presentation é fornecido, o texto da mensagem é opcional. Os botões são renderizados como ações de envio ou de URL do Adaptive Card. Os menus de seleção não são nativos no renderizador do Teams, portanto o OpenClaw os converte em texto legível antes da entrega.

Ferramenta do agente:

{  action: "send",  channel: "msteams",  target: "user:<id>",  presentation: {    title: "Hello",    blocks: [{ type: "text", text: "Hello!" }],  },}

CLI:

openclaw message send --channel msteams \  --target "conversation:19:abc...@thread.tacv2" \  --presentation '{"title":"Hello","blocks":[{"type":"text","text":"Hello!"}]}'

Para obter detalhes sobre o formato do destino, consulte Formatos de destino abaixo.

Formatos de destino

Os destinos do MSTeams usam prefixos para distinguir entre usuários e conversas:

Exemplos de CLI:

# Enviar para um usuário por IDopenclaw message send --channel msteams --target "user:40a1a0ed-..." --message "Hello" # Enviar para um usuário pelo nome de exibição (aciona uma consulta à API do Graph)openclaw message send --channel msteams --target "user:John Smith" --message "Hello" # Enviar para um chat em grupo ou canalopenclaw message send --channel msteams --target "conversation:19:abc...@thread.tacv2" --message "Hello" # Enviar um cartão de apresentação para uma conversaopenclaw message send --channel msteams --target "conversation:19:abc...@thread.tacv2" \  --presentation '{"title":"Hello","blocks":[{"type":"text","text":"Hello"}]}'

Exemplos da ferramenta do agente:

{  action: "send",  channel: "msteams",  target: "user:John Smith",  message: "Hello!",}

{  action: "send",  channel: "msteams",  target: "conversation:19:abc...@thread.tacv2",  presentation: {    title: "Hello",    blocks: [{ type: "text", text: "Hello" }],  },}

Mensagens proativas

• Mensagens proativas só são possíveis depois que um usuário interage, pois o OpenClaw armazena as referências da conversa nesse momento.
• Consulte /gateway/configuration para saber mais sobre dmPolicy e o controle por lista de permissões.

IDs de equipe e canal (problema comum)

O parâmetro de consulta groupId nas URLs do Teams NÃO é o ID da equipe usado na configuração. Em vez disso, extraia os IDs do caminho da URL:

URL da equipe:

https://teams.microsoft.com/l/team/19%3ABk4j...%40thread.tacv2/conversations?groupId=...                                    └────────────────────────────┘                                    ID da conversa da equipe (decodifique a URL)

URL do canal:

https://teams.microsoft.com/l/channel/19%3A15bc...%40thread.tacv2/ChannelName?groupId=...                                      └─────────────────────────┘                                      ID do canal (decodifique a URL)

Para a configuração:

• Chave da equipe = segmento do caminho após /team/ (com a URL decodificada, por exemplo, 19:Bk4j...@thread.tacv2; locatários mais antigos podem exibir @thread.skype, que também é válido).
• Chave do canal = segmento do caminho após /channel/ (com a URL decodificada).
• Ignore o parâmetro de consulta groupId para o roteamento do OpenClaw. Ele é o ID do grupo do Microsoft Entra, não o ID de conversa do Bot Framework usado nas atividades recebidas do Teams.

Canais privados

Os bots têm suporte limitado em canais privados:

Soluções alternativas caso os canais privados não funcionem:

1. Use canais padrão para interações com o bot.
2. Use mensagens diretas; os usuários sempre podem enviar mensagens diretamente ao bot.
3. Use a API Graph para acessar o histórico (requer ChannelMessage.Read.All).

Solução de problemas

Problemas comuns

• Imagens não aparecem nos canais: faltam permissões do Graph ou consentimento do administrador. Reinstale o aplicativo do Teams, encerre-o completamente e abra-o novamente.
• Sem respostas no canal: as menções são obrigatórias por padrão; defina channels.msteams.requireMention=false ou configure por equipe/canal.
• Incompatibilidade de versão (o Teams ainda exibe o manifesto antigo): remova e adicione novamente o aplicativo e encerre completamente o Teams para atualizar.
• 401 Não autorizado do Webhook: esperado ao testar manualmente sem um JWT do Azure; significa que o endpoint está acessível, mas a autenticação falhou. Use o Azure Web Chat para testar corretamente.

Erros de upload do manifesto

• "Icon file cannot be empty": o manifesto referencia arquivos de ícone com 0 bytes. Crie ícones PNG válidos (32x32 para outline.png, 192x192 para color.png).
• "webApplicationInfo.Id already in use": o aplicativo ainda está instalado em outra equipe/conversa. Localize-o e desinstale-o primeiro ou aguarde 5-10 minutos pela propagação.
• "Something went wrong" durante o upload: faça o upload por https://admin.teams.microsoft.com, abra o DevTools do navegador (F12) → guia Network e verifique o corpo da resposta para identificar o erro real.
• Falha no sideload: tente "Upload an app to your org's app catalog" em vez de "Upload a custom app"; isso frequentemente contorna as restrições de sideload.

Permissões RSC não funcionam

1. Verifique se webApplicationInfo.id corresponde exatamente ao ID do aplicativo do seu bot.
2. Faça novamente o upload do aplicativo e reinstale-o na equipe/conversa.
3. Verifique se o administrador da sua organização bloqueou as permissões RSC.
4. Confirme se você está usando o escopo correto: ChannelMessage.Read.Group para equipes, ChatMessage.Read.Chat para conversas em grupo.

Referências

• Criar um Azure Bot - guia de configuração do Azure Bot
• Portal do Desenvolvedor do Teams - criar/gerenciar aplicativos do Teams
• Esquema do manifesto de aplicativo do Teams
• Receber mensagens de canal com RSC
• Referência de permissões RSC
• Manipulação de arquivos por bots do Teams (canal/grupo requer o Graph)
• Mensagens proativas
• @microsoft/teams.cli - CLI do Teams para gerenciamento de bots

Relacionados

• Visão geral dos canais - todos os canais compatíveis
• Pareamento - autenticação por mensagem direta e fluxo de pareamento
• Grupos - comportamento de conversas em grupo e exigência de menções
• Roteamento de canais - roteamento de sessões para mensagens
• Segurança - modelo de acesso e proteção