​

Microsoft Teams (плагин)

«Оставь надежду всяк сюда входящий».

​

Требуется плагин

openclaw plugins install @openclaw/msteams

openclaw plugins install ./extensions/msteams

​

Быстрая настройка (для начинающих)

1. Установите плагин Microsoft Teams.
2. Создайте Azure Bot (App ID + client secret + tenant ID).
3. Настройте OpenClaw с этими учетными данными.
4. Опубликуйте /api/messages (по умолчанию порт 3978) через публичный URL или туннель.
5. Установите пакет приложения Teams и запустите Gateway (шлюз).

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

​

Цели

• Общение с OpenClaw через личные сообщения Teams, групповые чаты или каналы.
• Детерминированная маршрутизация: ответы всегда возвращаются в тот же канал, откуда пришли.
• Безопасное поведение каналов по умолчанию (требуются упоминания, если не настроено иначе).

​

Запись конфига

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

​

Контроль доступа (личные сообщения + группы)

• По умолчанию: channels.msteams.dmPolicy = "pairing". Неизвестные отправители игнорируются до одобрения.
• channels.msteams.allowFrom принимает AAD object ID, UPN или отображаемые имена. Мастер настраивания разрешает имена в ID через Microsoft Graph при наличии учетных данных.

• По умолчанию: channels.msteams.groupPolicy = "allowlist" (заблокировано, пока вы не добавите groupAllowFrom). Используйте channels.defaults.groupPolicy для переопределения значения по умолчанию, если оно не задано.
• channels.msteams.groupAllowFrom управляет тем, какие отправители могут инициировать события в групповых чатах/каналах (с откатом к channels.msteams.allowFrom).
• Установите groupPolicy: "open", чтобы разрешить любого участника (по умолчанию все равно требуется упоминание).
• Чтобы запретить все каналы, установите channels.msteams.groupPolicy: "disabled".

{
  channels: {
    msteams: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["[email protected]"],
    },
  },
}

• Ограничивайте ответы в группах/каналах, перечисляя команды и каналы в channels.msteams.teams.
• Ключами могут быть ID или имена команд; ключами каналов — ID диалогов или имена.
• Когда включен groupPolicy="allowlist" и присутствует allowlist команд, принимаются только перечисленные команды/каналы (с обязательным упоминанием).
• Мастер конфигурации принимает записи Team/Channel и сохраняет их за вас.
• При запуске OpenClaw разрешает имена команд/каналов и пользователей из allowlist в ID (если позволяют разрешения Graph) и логирует сопоставление; неразрешённые записи сохраняются как введены.

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

​

Как это работает

1. Установите плагин Microsoft Teams.
2. Создайте Azure Bot (App ID + secret + tenant ID).
3. Соберите пакет приложения Teams, который ссылается на бота и включает разрешения RSC ниже.
4. Загрузите/установите приложение Teams в команду (или в личную область для личных сообщений).
5. Настройте msteams в ~/.openclaw/openclaw.json (или через переменные окружения) и запустите Gateway (шлюз).
6. Gateway (шлюз) по умолчанию принимает трафик вебхуков Bot Framework на /api/messages.

​

Настройка Azure Bot (Предварительные требования)

​

Шаг 1: Создание Azure Bot

1. Перейдите на Create Azure Bot
2. Заполните вкладку Basics:

   Поле	Значение
   Имя бота	Имя вашего бота, например openclaw-msteams (должно быть уникальным)
   Подписка	Выберите подписку Azure
   Группа ресурсов	Создайте новую или используйте существующую
   Ценовой уровень	Free для разработки/тестирования
   Тип приложения	Single Tenant (рекомендуется — см. примечание ниже)
   Тип создания	Create new Microsoft App ID

Уведомление об устаревании: Создание новых мультиарендных ботов было прекращено после 2025-07-31. Для новых ботов используйте Single Tenant.

3. Нажмите Review + create → Create (подождите ~1–2 минуты)

​

Шаг 2: Получение учетных данных

1. Перейдите в ресурс Azure Bot → Configuration
2. Скопируйте Microsoft App ID → это ваш appId
3. Нажмите Manage Password → перейдите в App Registration
4. В Certificates & secrets → New client secret → скопируйте Value → это ваш appPassword
5. Перейдите в Overview → скопируйте Directory (tenant) ID → это ваш tenantId

​

Шаг 3: Настройка конечной точки сообщений

1. В Azure Bot → Configuration
2. Установите Messaging endpoint на URL вашего вебхука:
   • Продакшн: https://your-domain.com/api/messages
   • Локальная разработка: используйте туннель (см. Локальная разработка ниже)

​

Шаг 4: Включение канала Teams

1. В Azure Bot → Channels
2. Нажмите Microsoft Teams → Configure → Save
3. Примите Условия использования

​

Локальная разработка (туннелирование)

ngrok http 3978
# Copy the https URL, e.g., https://abc123.ngrok.io
# Set messaging endpoint to: https://abc123.ngrok.io/api/messages

tailscale funnel 3978
# Use your Tailscale funnel URL as the messaging endpoint

​

Teams Developer Portal (альтернатива)

1. Нажмите + New app
2. Заполните базовую информацию (имя, описание, данные разработчика)
3. Перейдите в App features → Bot
4. Выберите Enter a bot ID manually и вставьте App ID вашего Azure Bot
5. Отметьте области: Personal, Team, Group Chat
6. Нажмите Distribute → Download app package
7. В Teams: Apps → Manage your apps → Upload a custom app → выберите ZIP

​

Тестирование бота

1. В Azure Portal → ресурс Azure Bot → Test in Web Chat
2. Отправьте сообщение — вы должны увидеть ответ
3. Это подтверждает, что конечная точка вебхука работает до настройки Teams

1. Установите приложение Teams (sideload или каталог организации)
2. Найдите бота в Teams и отправьте личное сообщение
3. Проверьте логи Gateway (шлюза) на входящую активность

​

Настройка (минимальная, только текст)

1. Установка плагина Microsoft Teams
   • Из npm: openclaw plugins install @openclaw/msteams
   • Из локального чекаута: openclaw plugins install ./extensions/msteams
2. Регистрация бота
   • Создайте Azure Bot (см. выше) и запишите:
     • App ID
     • Client secret (пароль приложения)
     • Tenant ID (single-tenant)
3. Манифест приложения Teams
   • Добавьте запись bot с botId = <App ID>.
   • Области: personal, team, groupChat.
   • supportsFiles: true (обязательно для обработки файлов в личной области).
   • Добавьте разрешения RSC (ниже).
   • Создайте иконки: outline.png (32x32) и color.png (192x192).
   • Упакуйте все три файла в ZIP: manifest.json, outline.png, color.png.
4. Настройка OpenClaw
   {
     "msteams": {
       "enabled": true,
       "appId": "<APP_ID>",
       "appPassword": "<APP_PASSWORD>",
       "tenantId": "<TENANT_ID>",
       "webhook": { "port": 3978, "path": "/api/messages" }
     }
   }
   
   Вы также можете использовать переменные окружения вместо ключей конфига:
   • MSTEAMS_APP_ID
   • MSTEAMS_APP_PASSWORD
   • MSTEAMS_TENANT_ID
5. Конечная точка бота
   • Установите Messaging Endpoint Azure Bot в:
     • https://<host>:3978/api/messages (или выбранный вами путь/порт).
6. Запуск Gateway (шлюза)
   • Канал Teams запускается автоматически, когда плагин установлен и существует конфиг msteams с учетными данными.

​

Контекст истории

• channels.msteams.historyLimit управляет тем, сколько последних сообщений канала/группы включается в prompt.
• С откатом к messages.groupChat.historyLimit. Установите 0, чтобы отключить (по умолчанию 50).
• История личных сообщений может быть ограничена с помощью channels.msteams.dmHistoryLimit (повороты пользователя). Переопределения для конкретных пользователей: channels.msteams.dms["<user_id>"].historyLimit.

​

Текущие разрешения Teams RSC (манифест)

• ChannelMessage.Read.Group (Application) — получение всех сообщений канала без @упоминания
• ChannelMessage.Send.Group (Application)
• Member.Read.Group (Application)
• Owner.Read.Group (Application)
• ChannelSettings.Read.Group (Application)
• TeamMember.Read.Group (Application)
• TeamSettings.Read.Group (Application)

• ChatMessage.Read.Chat (Application) — получение всех сообщений группового чата без @упоминания

​

Пример манифеста Teams (сокращённый)

{
  "$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": "Your Org",
    "websiteUrl": "https://example.com",
    "privacyUrl": "https://example.com/privacy",
    "termsOfUseUrl": "https://example.com/terms"
  },
  "description": { "short": "OpenClaw in Teams", "full": "OpenClaw in 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" }
      ]
    }
  }
}

​

Ограничения манифеста (обязательные поля)

• bots[].botId должен совпадать с Azure Bot App ID.
• webApplicationInfo.id должен совпадать с Azure Bot App ID.
• bots[].scopes должен включать поверхности, которые вы планируете использовать (personal, team, groupChat).
• bots[].supportsFiles: true требуется для обработки файлов в личной области.
• authorization.permissions.resourceSpecific должен включать чтение/отправку каналов, если вы хотите трафик каналов.

​

Обновление существующего приложения

1. Обновите ваш manifest.json с новыми настройками
2. Увеличьте поле version (например, 1.0.0 → 1.1.0)
3. Переупакуйте ZIP манифеста с иконками (manifest.json, outline.png, color.png)
4. Загрузите новый ZIP:
   • Вариант A (Teams Admin Center): Teams Admin Center → Teams apps → Manage apps → найдите приложение → Upload new version
   • Вариант B (Sideload): В Teams → Apps → Manage your apps → Upload a custom app
5. Для каналов команды: переустановите приложение в каждой команде, чтобы новые разрешения вступили в силу
6. Полностью закройте и перезапустите Teams (не просто закройте окно), чтобы очистить кэш метаданных приложения

​

Возможности: только RSC vs Graph

​

С только Teams RSC (приложение установлено, без разрешений Graph API)

• Чтение текста сообщений каналов.
• Отправка текста сообщений каналов.
• Получение вложений файлов в личных сообщениях.

• Изображения или файлы в каналах/группах (в полезной нагрузке только HTML-заглушка).
• Загрузка вложений, хранящихся в SharePoint/OneDrive.
• Чтение истории сообщений (кроме события живого вебхука).

​

С Teams RSC + разрешениями Microsoft Graph (Application)

• Загрузка размещённого контента (изображения, вставленные в сообщения).
• Загрузка файловых вложений из SharePoint/OneDrive.
• Чтение истории сообщений каналов/чатов через Graph.

​

RSC vs Graph API

​

Медиа и история с Graph (требуется для каналов)

1. В Entra ID (Azure AD) → App Registration добавьте разрешения Microsoft Graph Application:
   • ChannelMessage.Read.All (вложения каналов + история)
   • Chat.Read.All или ChatMessage.Read.All (групповые чаты)
2. Выдайте согласие администратора для арендатора.
3. Увеличьте версию манифеста приложения Teams, повторно загрузите и переустановите приложение в Teams.
4. Полностью закройте и перезапустите Teams, чтобы очистить кэш метаданных приложения.

​

Известные ограничения

​

Тайм-ауты вебхука

• Тайм-ауты Gateway (шлюза)
• Повторные попытки Teams (вызывающие дубликаты)
• Потерянные ответы

​

Форматирование

• Базовое форматирование работает: жирный, курсив, code, ссылки
• Сложный markdown (таблицы, вложенные списки) может отображаться некорректно
• Adaptive Cards поддерживаются для опросов и произвольных карточек (см. ниже)

​

Конфигурация

• channels.msteams.enabled: включить/выключить канал.
• channels.msteams.appId, channels.msteams.appPassword, channels.msteams.tenantId: учетные данные бота.
• channels.msteams.webhook.port (по умолчанию 3978)
• channels.msteams.webhook.path (по умолчанию /api/messages)
• channels.msteams.dmPolicy: pairing | allowlist | open | disabled (по умолчанию: pairing)
• channels.msteams.allowFrom: список разрешённых для личных сообщений (AAD object ID, UPN или отображаемые имена). Мастер разрешает имена в ID во время настройки при наличии доступа Graph.
• channels.msteams.textChunkLimit: размер чанка исходящего текста.
• channels.msteams.chunkMode: length (по умолчанию) или newline для разделения по пустым строкам (границы абзацев) перед разбиением по длине.
• channels.msteams.mediaAllowHosts: список разрешённых хостов для входящих вложений (по умолчанию домены Microsoft/Teams).
• channels.msteams.mediaAuthAllowHosts: список разрешённых хостов для добавления заголовков Authorization при повторах загрузки медиа (по умолчанию хосты Graph + Bot Framework).
• channels.msteams.requireMention: требовать @упоминание в каналах/группах (по умолчанию true).
• channels.msteams.replyStyle: thread | top-level (см. Стиль ответа).
• channels.msteams.teams.<teamId>.replyStyle: переопределение для команды.
• channels.msteams.teams.<teamId>.requireMention: переопределение для команды.
• channels.msteams.teams.<teamId>.tools: значения по умолчанию переопределений политик инструментов для команды (allow/deny/alsoAllow), используемые, когда отсутствует переопределение канала.
• channels.msteams.teams.<teamId>.toolsBySender: значения по умолчанию переопределений политик инструментов для команды и отправителя ("*" поддерживает wildcard).
• channels.msteams.teams.<teamId>.channels.<conversationId>.replyStyle: переопределение для канала.
• channels.msteams.teams.<teamId>.channels.<conversationId>.requireMention: переопределение для канала.
• channels.msteams.teams.<teamId>.channels.<conversationId>.tools: переопределения политик инструментов для канала (allow/deny/alsoAllow).
• channels.msteams.teams.<teamId>.channels.<conversationId>.toolsBySender: переопределения политик инструментов для канала и отправителя ("*" поддерживает wildcard).
• channels.msteams.sharePointSiteId: ID сайта SharePoint для загрузки файлов в групповых чатах/каналах (см. Отправка файлов в групповых чатах).

​

Маршрутизация и сессии

• Ключи сессий следуют стандартному формату агента (см. /concepts/session):
  • Личные сообщения используют основную сессию (agent:<agentId>:<mainKey>).
  • Сообщения каналов/групп используют ID диалога:
    • agent:<agentId>:msteams:channel:<conversationId>
    • agent:<agentId>:msteams:group:<conversationId>

​

Стиль ответа: Threads vs Posts

• thread в канале со стилем Threads → ответы выглядят неудачно вложенными
• top-level в канале со стилем Posts → ответы появляются как отдельные верхнеуровневые посты, а не в треде

{
  "msteams": {
    "replyStyle": "thread",
    "teams": {
      "19:[email protected]": {
        "channels": {
          "19:[email protected]": {
            "replyStyle": "top-level"
          }
        }
      }
    }
  }
}

​

Вложения и изображения

• Личные сообщения: изображения и файловые вложения работают через API файлов бота Teams.
• Каналы/группы: вложения хранятся в M365 (SharePoint/OneDrive). Полезная нагрузка вебхука содержит только HTML-заглушку, а не байты файла. Для загрузки вложений каналов требуются разрешения Graph API.

​

Отправка файлов в групповых чатах

​

Почему группам нужен SharePoint

​

Настройка

1. Добавьте разрешения Graph API в Entra ID (Azure AD) → App Registration:
   • Sites.ReadWrite.All (Application) — загрузка файлов в SharePoint
   • Chat.Read.All (Application) — необязательно, включает ссылки общего доступа для каждого пользователя
2. Выдайте согласие администратора для арендатора.
3. Получите ID сайта SharePoint:
   # Via Graph Explorer or curl with a valid token:
   curl -H "Authorization: Bearer $TOKEN" \
     "https://graph.microsoft.com/v1.0/sites/{hostname}:/{site-path}"
   
   # Example: for a site at "contoso.sharepoint.com/sites/BotFiles"
   curl -H "Authorization: Bearer $TOKEN" \
     "https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com:/sites/BotFiles"
   
   # Response includes: "id": "contoso.sharepoint.com,guid1,guid2"
   
4. Настройте OpenClaw:
   {
     channels: {
       msteams: {
         // ... other config ...
         sharePointSiteId: "contoso.sharepoint.com,guid1,guid2",
       },
     },
   }
   

​

Поделиться поведением

​

Резервное поведение

​

Место хранения файлов

​

Опросы (Adaptive Cards)

• CLI: openclaw message poll --channel msteams --target conversation:<id> ...
• Голоса записываются Gateway (шлюзом) в ~/.openclaw/msteams-polls.json.
• Gateway (шлюз) должен оставаться онлайн для записи голосов.
• Автоматическая публикация итогов опросов пока не реализована (при необходимости проверяйте файл хранилища).

​

Adaptive Cards (произвольные)

{
  "action": "send",
  "channel": "msteams",
  "target": "user:<id>",
  "card": {
    "type": "AdaptiveCard",
    "version": "1.5",
    "body": [{ "type": "TextBlock", "text": "Hello!" }]
  }
}

openclaw message send --channel msteams \
  --target "conversation:19:[email protected]" \
  --card '{"type":"AdaptiveCard","version":"1.5","body":[{"type":"TextBlock","text":"Hello!"}]}'

​

Целевые форматы

# Send to a user by ID
openclaw message send --channel msteams --target "user:40a1a0ed-..." --message "Hello"

# Send to a user by display name (triggers Graph API lookup)
openclaw message send --channel msteams --target "user:John Smith" --message "Hello"

# Send to a group chat or channel
openclaw message send --channel msteams --target "conversation:19:[email protected]" --message "Hello"

# Send an Adaptive Card to a conversation
openclaw message send --channel msteams --target "conversation:19:[email protected]" \
  --card '{"type":"AdaptiveCard","version":"1.5","body":[{"type":"TextBlock","text":"Hello"}]}'

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

{
  "action": "send",
  "channel": "msteams",
  "target": "conversation:19:[email protected]",
  "card": {
    "type": "AdaptiveCard",
    "version": "1.5",
    "body": [{ "type": "TextBlock", "text": "Hello" }]
  }
}

​

Проактивные сообщения

• Проактивные сообщения возможны только после того, как пользователь взаимодействовал, так как мы сохраняем ссылки диалогов в этот момент.
• См. /gateway/configuration для dmPolicy и ограничений allowlist.

​

ID команд и каналов (частая ошибка)

https://teams.microsoft.com/l/team/19%3ABk4j...%40thread.tacv2/conversations?groupId=...
                                    └────────────────────────────┘
                                    Team ID (URL-decode this)

https://teams.microsoft.com/l/channel/19%3A15bc...%40thread.tacv2/ChannelName?groupId=...
                                      └─────────────────────────┘
                                      Channel ID (URL-decode this)

• ID команды = сегмент пути после /team/ (URL-decoded, например 19:[email protected])
• ID канала = сегмент пути после /channel/ (URL-decoded)
• Игнорируйте параметр запроса groupId

​

Приватные каналы

1. Используйте стандартные каналы для взаимодействия с ботом
2. Используйте личные сообщения — пользователи всегда могут написать боту напрямую
3. Используйте Graph API для доступа к истории (требуется ChannelMessage.Read.All)

​

Распространённые проблемы

​

Распространённые проблемы

• Изображения не отображаются в каналах: отсутствуют разрешения Graph или согласие администратора. Переустановите приложение Teams и полностью закройте/откройте Teams.
• Нет ответов в канале: по умолчанию требуются упоминания; установите channels.msteams.requireMention=false или настройте для команды/канала.
• Несоответствие версий (Teams показывает старый манифест): удалите и снова добавьте приложение и полностью перезапустите Teams для обновления.
• 401 Unauthorized от вебхука: ожидаемо при ручном тестировании без JWT Azure — означает, что конечная точка доступна, но аутентификация не прошла. Используйте Azure Web Chat для корректного теста.

​

Ошибки загрузки манифеста

• «Icon file cannot be empty»: манифест ссылается на иконки нулевого размера. Создайте корректные PNG-иконки (32x32 для outline.png, 192x192 для color.png).
• «webApplicationInfo.Id already in use»: приложение всё ещё установлено в другой команде/чате. Найдите и удалите его или подождите 5–10 минут для распространения.
• «Something went wrong» при загрузке: загрузите через https://admin.teams.microsoft.com, откройте DevTools браузера (F12) → вкладка Network и проверьте тело ответа с фактической ошибкой.
• Сбой sideload: попробуйте «Upload an app to your org’s app catalog» вместо «Upload a custom app» — это часто обходит ограничения sideload.

​

Разрешения RSC не работают

1. Проверьте, что webApplicationInfo.id точно совпадает с App ID вашего бота
2. Повторно загрузите приложение и переустановите его в команде/чате
3. Убедитесь, что администратор организации не заблокировал разрешения RSC
4. Подтвердите, что используется правильная область: ChannelMessage.Read.Group для команд, ChatMessage.Read.Chat для групповых чатов

​

Ссылки

• Create Azure Bot — руководство по настройке Azure Bot
• Teams Developer Portal — создание и управление приложениями Teams
• Teams app manifest schema
• Receive channel messages with RSC
• RSC permissions reference
• Teams bot file handling (для каналов/групп требуется Graph)
• Proactive messaging