Microsoft Teams

​

Gebündeltes Plugin

openclaw plugins install @openclaw/msteams

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

​

Schnelleinrichtung

npm install -g @microsoft/teams.cli@preview
teams login
teams status   # Prüfen, ob Sie angemeldet sind, und Mandanteninformationen anzeigen

# Einmalige Einrichtung (dauerhafte URL über Sitzungen hinweg):
devtunnel create my-openclaw-bot --allow-anonymous
devtunnel port create my-openclaw-bot -p 3978 --protocol auto

# Für jede Entwicklungssitzung:
devtunnel host my-openclaw-bot
# Ihr Endpunkt: https://<tunnel-id>.devtunnels.ms/api/messages

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

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

teams app get <teamsAppId> --install-link

teams app doctor <teamsAppId>

​

Ziele

• Kommunizieren Sie über Teams-DMs, Gruppenchats oder Kanäle mit OpenClaw.
• Halten Sie das Routing deterministisch: Antworten gehen immer an den Kanal zurück, über den sie eingegangen sind.
• Verwenden Sie standardmäßig ein sicheres Kanalverhalten (Erwähnungen erforderlich, sofern nicht anders konfiguriert).

​

Konfigurationsänderungen

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

​

Zugriffskontrolle (DMs + Gruppen)

• Standard: channels.msteams.dmPolicy = "pairing". Unbekannte Absender werden ignoriert, bis sie genehmigt wurden.
• channels.msteams.allowFrom sollte stabile AAD-Objekt-IDs oder statische Absenderzugriffsgruppen wie accessGroup:core-team verwenden.
• Verlassen Sie sich bei Zulassungslisten nicht auf den Abgleich von UPNs/Anzeigenamen; diese können sich ändern. OpenClaw deaktiviert den direkten Namensabgleich standardmäßig; aktivieren Sie ihn mit channels.msteams.dangerouslyAllowNameMatching: true.
• Der Assistent kann Namen über Microsoft Graph in IDs auflösen, sofern die Anmeldedaten dies erlauben.

• Standard: channels.msteams.groupPolicy = "allowlist" (blockiert, sofern Sie nicht groupAllowFrom hinzufügen). channels.defaults.groupPolicy kann den gemeinsamen Standardwert überschreiben, wenn channels.msteams.groupPolicy nicht gesetzt ist.
• channels.msteams.groupAllowFrom steuert, welche Absender oder statischen Absenderzugriffsgruppen in Gruppenchats/Kanälen eine Aktion auslösen können (greift auf channels.msteams.allowFrom zurück).
• Setzen Sie groupPolicy: "open", um jedes Mitglied zuzulassen (standardmäßig ist weiterhin eine Erwähnung erforderlich).
• Um alle Kanäle zu blockieren, setzen Sie channels.msteams.groupPolicy: "disabled".

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

• Begrenzen Sie Gruppen-/Kanalantworten, indem Sie Teams und Kanäle unter channels.msteams.teams aufführen.
• Verwenden Sie stabile Teams-Unterhaltungs-IDs aus Teams-Links als Schlüssel, nicht veränderliche Anzeigenamen (siehe Team- und Kanal-IDs).
• Wenn groupPolicy="allowlist" und eine Teams-Zulassungsliste vorhanden sind, werden nur aufgeführte Teams/Kanäle akzeptiert (Erwähnung erforderlich).
• Der Konfigurationsassistent akzeptiert Team/Channel-Einträge und speichert sie für Sie.
• Beim Start löst OpenClaw die Namen in Team-/Kanal- und Benutzerzulassungslisten in IDs auf (sofern Graph-Berechtigungen dies erlauben) und protokolliert die Zuordnung. Nicht aufgelöste Namen bleiben wie eingegeben erhalten, werden beim Routing jedoch ignoriert, sofern channels.msteams.dangerouslyAllowNameMatching: true nicht gesetzt ist.

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

​

Föderierte Authentifizierung (Zertifikat plus verwaltete Identität)

​

Option A: Zertifikatbasierte Authentifizierung

1. Generieren oder beschaffen Sie ein Zertifikat (PEM-Format mit privatem Schlüssel).
2. Entra ID → App-Registrierung → Certificates & secrets → Certificates → laden Sie das öffentliche Zertifikat hoch.

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

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

​

Option B: Verwaltete Azure-Identität

1. Der Bot-Pod/die VM verfügt über eine verwaltete Identität (system- oder benutzerseitig zugewiesen).
2. Anmeldedaten für eine föderierte Identität verknüpfen die verwaltete Identität mit der Entra ID-App-Registrierung.
3. Zur Laufzeit verwendet OpenClaw @azure/identity, um Token vom Azure-IMDS-Endpunkt abzurufen.
4. Das Token wird zur Bot-Authentifizierung an das Teams SDK übergeben.

• Azure-Infrastruktur mit aktivierter verwalteter Identität (AKS-Workloadidentität, App Service, VM).
• Für die Entra-ID-App-Registrierung erstellte Anmeldeinformationen für die Verbundidentität.
• Netzwerkzugriff auf IMDS (169.254.169.254:80) vom Pod bzw. von der VM.

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

• MSTEAMS_AUTH_TYPE=federated
• MSTEAMS_USE_MANAGED_IDENTITY=true
• MSTEAMS_MANAGED_IDENTITY_CLIENT_ID=<client-id> (nur benutzerseitig zugewiesen)

​

Einrichtung der AKS-Workloadidentität

1. Aktivieren Sie die Workloadidentität für Ihren AKS-Cluster.
2. Erstellen Sie Anmeldeinformationen für die Verbundidentität in der Entra-ID-App-Registrierung:
   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. Versehen Sie das Kubernetes-Dienstkonto mit einer Annotation für die Client-ID der App:
   apiVersion: v1
   kind: ServiceAccount
   metadata:
     name: my-bot-sa
     annotations:
       azure.workload.identity/client-id: "<APP_CLIENT_ID>"
   
4. Versehen Sie den Pod mit einem Label für die Einbindung der Workloadidentität:
   metadata:
     labels:
       azure.workload.identity/use: "true"
   
5. Erlauben Sie den Netzwerkzugriff auf IMDS (169.254.169.254): Wenn Sie NetworkPolicy verwenden, fügen Sie für 169.254.169.254/32 an Port 80 eine ausgehende Regel hinzu.

​

Vergleich der Authentifizierungstypen

​

Lokale Entwicklung (Tunneling)

# Einmalige Einrichtung:
devtunnel create my-openclaw-bot --allow-anonymous
devtunnel port create my-openclaw-bot -p 3978 --protocol auto

# Bei jeder Entwicklungssitzung:
devtunnel host my-openclaw-bot

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

​

Bot testen

teams app doctor <teamsAppId>

1. Installieren Sie die Teams-App (Installationslink aus teams app get <id> --install-link).
2. Suchen Sie den Bot in Teams und senden Sie ihm eine Direktnachricht.
3. Prüfen Sie die Gateway-Protokolle auf eingehende Aktivitäten.

​

Umgebungsvariablen

​

Aktion für Mitgliedsinformationen

• ChannelSettings.Read.Group- und TeamMember.Read.Group-RSC-Berechtigungen (bereits im empfohlenen Manifest enthalten).

​

Verlaufskontext

• channels.msteams.historyLimit steuert, wie viele der letzten Kanal-/Gruppennachrichten in den Prompt eingebettet werden. Als Rückfallwert wird messages.groupChat.historyLimit verwendet, danach gilt standardmäßig 50. Legen Sie 0 fest, um die Funktion zu deaktivieren.
• Der abgerufene Threadverlauf wird anhand der Absender-Zulassungslisten (allowFrom / groupAllowFrom) gefiltert, sodass die anfängliche Befüllung des Threadkontexts nur Nachrichten von zulässigen Absendern enthält.
• Der Kontext zitierter Anhänge (aus dem HTML des Skype-Reply-Schemas in den eigenen Anhängen einer Antwort analysiert) wird ungefiltert weitergegeben; derzeit wendet nur die anfängliche Befüllung aus dem Threadverlauf den Filter der Absender-Zulassungsliste an.
• Der Verlauf von Direktnachrichten kann mit channels.msteams.dmHistoryLimit (Benutzerbeiträge) begrenzt werden. Benutzerspezifische Überschreibungen: channels.msteams.dms["<user_id>"].historyLimit.

​

Aktuelle Teams-RSC-Berechtigungen (Manifest)

• ChannelMessage.Read.Group (Application) – alle Kanalnachrichten ohne @Erwähnung empfangen
• 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) – alle Gruppenchatnachrichten ohne @Erwähnung empfangen

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

​

Beispiel für ein Teams-Manifest (geschwärzt)

{
  $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: "Ihre Organisation",
    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" },
      ],
    },
  },
}

​

Einschränkungen des Manifests (Pflichtfelder)

• bots[].botId muss mit der App-ID des Azure-Bots übereinstimmen.
• webApplicationInfo.id muss mit der App-ID des Azure-Bots übereinstimmen.
• bots[].scopes muss die Oberflächen enthalten, die Sie verwenden möchten (personal, team, groupChat).
• bots[].supportsFiles: true ist für die Dateiverarbeitung im persönlichen Bereich erforderlich.
• authorization.permissions.resourceSpecific muss Lese-/Sendeberechtigungen für Kanalverkehr enthalten.

​

Vorhandene App aktualisieren

# Manifest herunterladen, bearbeiten und erneut hochladen
teams app manifest download <teamsAppId> manifest.json
# manifest.json lokal bearbeiten ...
teams app manifest upload manifest.json <teamsAppId>
# Die Version wird automatisch erhöht, wenn sich der Inhalt geändert hat

​

Funktionen: nur RSC im Vergleich zu Graph

​

Mit nur Teams RSC (App installiert, keine Graph-API-Berechtigungen)

• Textinhalt von Kanalnachrichten lesen.
• Textinhalt von Kanalnachrichten senden.
• Dateianhänge in persönlichen Nachrichten (Direktnachrichten) empfangen.

• Bild- oder Dateiinhalte in Kanälen/Gruppen (die Nutzlast enthält nur einen HTML-Platzhalter).
• In SharePoint/OneDrive gespeicherte Anhänge herunterladen.
• Nachrichtenverlauf über das Live-Webhook-Ereignis hinaus lesen.

​

Mit Teams RSC + Microsoft-Graph-Anwendungsberechtigungen

• Gehostete Inhalte herunterladen (in Nachrichten eingefügte Bilder).
• In SharePoint/OneDrive gespeicherte Dateianhänge herunterladen.
• Kanal-/Chatnachrichtenverlauf über Graph lesen.

​

RSC im Vergleich zur Graph-API

​

Graph-gestützte Medien und Verlauf

1. Entra ID (Azure AD) App Registration → Graph-Anwendungsberechtigungen hinzufügen:
   • ChannelMessage.Read.All für Kanalanhänge und Kanalverlauf.
   • Chat.Read.All für Gruppenchat-Anhänge und Gruppenchat-Verlauf.
   • Files.Read.All, wenn Anhangsdaten aus dem SharePoint-/OneDrive-Speicher heruntergeladen werden müssen; reine Verlaufsinstallationen benötigen diese Berechtigung nicht.
2. Grant admin consent für den Mandanten.
3. Die Manifestversion der Teams-App erhöhen, erneut hochladen und die App in Teams neu installieren.
4. Teams vollständig beenden und neu starten, um zwischengespeicherte App-Metadaten zu löschen.

​

Wiederherstellung von Kanal-/Gruppendateien (graphMediaFallback)

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

​

Bekannte Einschränkungen

​

Webhook-Zeitüberschreitungen

​

Unterstützung für Teams-Clouds und Dienst-URLs

• channels.msteams.cloud wählt die Cloud-Voreinstellung des Teams SDK für Authentifizierung, JWT-Validierung, Token-Dienste und den Graph-Bereich aus.
• channels.msteams.serviceUrl wählt die Bot-Connector-Endpunktbegrenzung aus, mit der gespeicherte Unterhaltungsreferenzen vor proaktivem Senden, Bearbeiten, Löschen, Karten, Umfragen, Dateieinwilligungsnachrichten und in die Warteschlange gestellten lang laufenden Antworten validiert werden. Sie ist für die SDK-Clouds USGov und DoD erforderlich. Für China/21Vianet verwendet OpenClaw die SDK-Voreinstellung China und akzeptiert gespeicherte/konfigurierte Dienst-URLs nur auf Azure-China-Hosts des Bot-Framework-Kanals.

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

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

​

Formatierung

• Grundlegende Formatierung funktioniert: fett, kursiv, code, Links.
• Komplexes Markdown (Tabellen, verschachtelte Listen) wird möglicherweise nicht korrekt dargestellt.
• Adaptive Cards werden für Umfragen und semantische Präsentationssendungen unterstützt (siehe unten).

​

Konfiguration

• channels.msteams.enabled: den Kanal aktivieren/deaktivieren.
• channels.msteams.appId, channels.msteams.appPassword, channels.msteams.tenantId: Bot-Anmeldedaten.
• channels.msteams.cloud: Teams-SDK-Cloud-Umgebung (Public, USGov, USGovDoD oder China; Standardwert Public). Für USGov-/DoD-SDK-Clouds mit serviceUrl festlegen; China verwendet die SDK-Voreinstellung und gespeicherte Azure-China-Bot-Framework-Konversationsreferenzen, wobei Graph-basierte Hilfsfunktionen deaktiviert bleiben, bis Azure-China-Graph-Routing verfügbar ist.
• channels.msteams.serviceUrl: URL-Grenze des Bot-Connector-Dienstes für proaktive SDK-Vorgänge. Die öffentliche Cloud verwendet den SDK-Standardwert; für GCC (https://smba.infra.gcc.teams.microsoft.com/teams), GCC High oder DoD festlegen. China akzeptiert Azure-China-Bot-Framework-Kanalhosts, wenn die gespeicherte Konversationsreferenz aus dem von 21Vianet betriebenen Teams stammt.
• channels.msteams.webhook.port (Standardwert 3978).
• channels.msteams.webhook.path (Standardwert /api/messages).
• channels.msteams.dmPolicy: pairing | allowlist | open | disabled (Standardwert pairing).
• channels.msteams.allowFrom: Zulassungsliste für Direktnachrichten (AAD-Objekt-IDs empfohlen). Der Assistent löst Namen während der Einrichtung in IDs auf, wenn Graph-Zugriff verfügbar ist.
• channels.msteams.dangerouslyAllowNameMatching: Notfall-Umschalter, um den veränderlichen Abgleich von UPN/Anzeigenamen und das direkte Routing über Team-/Kanalnamen wieder zu aktivieren.
• channels.msteams.textChunkLimit: Größe ausgehender Textabschnitte in Zeichen (Standardwert 4000; unabhängig von einem höher konfigurierten Wert fest auf 4000 begrenzt).
• channels.msteams.streaming.chunkMode: length (Standardwert) oder newline, um vor der längenbasierten Aufteilung an Leerzeilen (Absatzgrenzen) zu trennen.
• channels.msteams.mediaAllowHosts: Zulassungsliste für Hosts eingehender Anhänge (standardmäßig Microsoft-/Teams-Domains: Graph, SharePoint/OneDrive, Teams CDN, Bot Framework, Azure Media Services).
• channels.msteams.mediaAuthAllowHosts: Zulassungsliste für das Anhängen von Authorization-Headern bei erneuten Medienabrufen (standardmäßig Graph- und Bot-Framework-Hosts).
• channels.msteams.graphMediaFallback: Graph-Nachrichtensuchen aktivieren, wenn Kanal-/Gruppen-HTML keine Dateimarkierungen enthält (Standardwert false; siehe Wiederherstellung von Kanal-/Gruppendateien).
• channels.msteams.mediaMaxMb: kanalspezifische Überschreibung der Mediengrößenbegrenzung in MB. Fällt auf agents.defaults.mediaMaxMb zurück, wenn nicht festgelegt.
• channels.msteams.requireMention: @Erwähnung in Kanälen/Gruppen verlangen (Standardwert true).
• channels.msteams.replyStyle: thread | top-level (siehe Antwortstil).
• channels.msteams.teams.<teamId>.replyStyle: teamspezifische Überschreibung.
• channels.msteams.teams.<teamId>.requireMention: teamspezifische Überschreibung.
• channels.msteams.teams.<teamId>.tools: standardmäßige teamspezifische Überschreibungen der Werkzeugrichtlinie (allow/deny/alsoAllow), die verwendet werden, wenn eine Kanalüberschreibung fehlt.
• channels.msteams.teams.<teamId>.toolsBySender: standardmäßige teamspezifische und absenderspezifische Überschreibungen der Werkzeugrichtlinie (Platzhalter "*" wird unterstützt).
• channels.msteams.teams.<teamId>.channels.<conversationId>.replyStyle: kanalspezifische Überschreibung.
• channels.msteams.teams.<teamId>.channels.<conversationId>.requireMention: kanalspezifische Überschreibung.
• channels.msteams.teams.<teamId>.channels.<conversationId>.tools: kanalspezifische Überschreibungen der Werkzeugrichtlinie (allow/deny/alsoAllow).
• channels.msteams.teams.<teamId>.channels.<conversationId>.toolsBySender: kanal- und absenderspezifische Überschreibungen der Werkzeugrichtlinie (Platzhalter "*" wird unterstützt).
• toolsBySender-Schlüssel sollten explizite Präfixe verwenden: channel:, id:, e164:, username:, name: (ältere Schlüssel ohne Präfix werden weiterhin nur id: zugeordnet).
• channels.msteams.authType: Authentifizierungstyp – "secret" (Standardwert) oder "federated".
• channels.msteams.certificatePath: Pfad zur PEM-Zertifikatsdatei (föderierte Authentifizierung und Zertifikatsauthentifizierung).
• channels.msteams.certificateThumbprint: Zertifikatfingerabdruck; wird akzeptiert, ist für die Authentifizierung jedoch nicht erforderlich.
• channels.msteams.useManagedIdentity: Authentifizierung mit verwalteter Identität aktivieren (föderierter Modus).
• channels.msteams.managedIdentityClientId: Client-ID für eine benutzerseitig zugewiesene verwaltete Identität.
• channels.msteams.sharePointSiteId: SharePoint-Website-ID für Datei-Uploads in Gruppenchats/Kanälen (siehe Dateien in Gruppenchats senden).
• channels.msteams.welcomeCard, channels.msteams.groupWelcomeCard, channels.msteams.promptStarters: Adaptive Card zur Begrüßung, die beim ersten Direktnachrichten-/Gruppenkontakt angezeigt wird, sowie deren Schaltflächen mit vorgeschlagenen Prompts.
• channels.msteams.responsePrefix: Text, der ausgehenden Antworten vorangestellt wird.
• channels.msteams.feedbackEnabled (Standardwert true), channels.msteams.feedbackReflection (Standardwert true), channels.msteams.feedbackReflectionCooldownMs: Feedback per Daumen hoch/runter zu Antworten und anschließende Reflexion bei negativem Feedback.
• channels.msteams.sso, channels.msteams.delegatedAuth: Bot-Framework-OAuth-Verbindung und delegierte Graph-Bereiche für SSO-basierte Abläufe; sso.enabled: true erfordert sso.connectionName.

​

Routing und Sitzungen

• Sitzungsschlüssel folgen dem standardmäßigen Agentenformat (siehe /concepts/session):
  • Direktnachrichten verwenden gemeinsam die Hauptsitzung (agent:<agentId>:<mainKey>).
  • Kanal-/Gruppennachrichten verwenden die Konversations-ID:
    • agent:<agentId>:msteams:channel:<conversationId>
    • agent:<agentId>:msteams:group:<conversationId>

​

Antwortstil: Threads oder Beiträge

• thread in einem Kanal mit Threads-Oberfläche → Antworten erscheinen unübersichtlich verschachtelt.
• top-level in einem Kanal mit Beitragsoberfläche → Antworten erscheinen als separate Beiträge auf oberster Ebene statt innerhalb des Threads.

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

​

Auflösungsreihenfolge

1. Pro Kanal – channels.msteams.teams.<teamId>.channels.<conversationId>.replyStyle
2. Pro Team – channels.msteams.teams.<teamId>.replyStyle
3. Global – channels.msteams.replyStyle
4. Impliziter Standardwert – abgeleitet aus requireMention:
   • requireMention: true → thread
   • requireMention: false → top-level

​

Beibehaltung des Thread-Kontexts

​

Anhänge und Bilder

• Direktnachrichten: Bilder und Dateianhänge funktionieren über die Teams-Bot-Datei-APIs.
• Kanäle/Gruppen: Anhänge befinden sich im M365-Speicher (SharePoint/OneDrive). Die Webhook-Nutzlast enthält nur ein HTML-Fragment, nicht die tatsächlichen Dateibytes. Zum Herunterladen von Kanalanhängen sind Graph-API-Berechtigungen erforderlich.
• Verwenden Sie für explizite dateiorientierte Sendevorgänge action=upload-file mit media / filePath / path; das optionale message wird zum begleitenden Text/Kommentar und filename (oder title) überschreibt den Namen der hochgeladenen Datei.

​

Dateien in Gruppenchats senden

​

Warum Gruppenchats SharePoint benötigen

​

Einrichtung

1. Fügen Sie Graph-API-Berechtigungen unter Entra ID (Azure AD) → App Registration hinzu:
   • Sites.ReadWrite.All (Application) – Dateien zu SharePoint hochladen.
   • ChatMember.Read.All (Application) – mandantenweite Berechtigung mit den geringsten Rechten für das Senden von Dateien in Gruppenchats. Chat.Read.All funktioniert ebenfalls und deckt dies bereits ab, wenn der Gruppenchatverlauf aktiviert ist. Verwenden Sie als chatbezogene Alternative die ressourcenspezifische Einwilligungsberechtigung ChatMember.Read.Chat.
2. Erteilen Sie die Administratoreinwilligung für den Mandanten.
3. Rufen Sie Ihre SharePoint-Website-ID ab:
   # Über Graph Explorer oder curl mit einem gültigen Token:
   curl -H "Authorization: Bearer $TOKEN" \
     "https://graph.microsoft.com/v1.0/sites/{hostname}:/{site-path}"
   
   # Beispiel: für eine Website unter "contoso.sharepoint.com/sites/BotFiles"
   curl -H "Authorization: Bearer $TOKEN" \
     "https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com:/sites/BotFiles"
   
   # Die Antwort enthält: "id": "contoso.sharepoint.com,guid1,guid2"
   
4. OpenClaw konfigurieren:
   {
     channels: {
       msteams: {
         // ... weitere Konfiguration ...
         sharePointSiteId: "contoso.sharepoint.com,guid1,guid2",
       },
     },
   }
   

​

Freigabeverhalten

​

Fallback-Verhalten

​

Speicherort der Dateien

​

Umfragen (Adaptive Cards)

• CLI: openclaw message poll --channel msteams --target conversation:<id> --poll-question "..." --poll-option "..." --poll-option "...".
• Stimmen werden vom Gateway im SQLite-Plugin-Status von OpenClaw unter state/openclaw.sqlite gespeichert.
• Vorhandene msteams-polls.json-Dateien werden durch openclaw doctor --fix importiert, nicht durch das laufende Plugin.
• Das Gateway muss online bleiben, um Stimmen zu erfassen.
• Umfragen veröffentlichen nicht automatisch Ergebniszusammenfassungen, und es gibt noch keine CLI für Umfrageergebnisse.

​

Präsentationskarten

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

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

​

Zielformate

# An einen Benutzer nach ID senden
openclaw message send --channel msteams --target "user:40a1a0ed-..." --message "Hallo"

# An einen Benutzer nach Anzeigename senden (löst eine Graph-API-Suche aus)
openclaw message send --channel msteams --target "user:John Smith" --message "Hallo"

# An einen Gruppenchat oder Kanal senden
openclaw message send --channel msteams --target "conversation:19:abc...@thread.tacv2" --message "Hallo"

# Eine Präsentationskarte an eine Unterhaltung senden
openclaw message send --channel msteams --target "conversation:19:abc...@thread.tacv2" \
  --presentation '{"title":"Hallo","blocks":[{"type":"text","text":"Hallo"}]}'

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

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

​

Proaktive Nachrichten

• Proaktive Nachrichten sind nur möglich, nachdem ein Benutzer interagiert hat, da OpenClaw zu diesem Zeitpunkt Unterhaltungsreferenzen speichert.
• Informationen zu dmPolicy und zur Zulassungslistensteuerung finden Sie unter /gateway/configuration.

​

Team- und Kanal-IDs (häufiger Stolperstein)

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

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

• Team-Schlüssel = Pfadsegment nach /team/ (URL-decodiert, z. B. 19:Bk4j...@thread.tacv2; ältere Mandanten zeigen möglicherweise @thread.skype, was ebenfalls gültig ist).
• Kanal-Schlüssel = Pfadsegment nach /channel/ (URL-decodiert).
• Ignorieren Sie den Abfrageparameter groupId für das OpenClaw-Routing. Dabei handelt es sich um die Microsoft-Entra-Gruppen-ID, nicht um die Bot-Framework-Unterhaltungs-ID, die in eingehenden Teams-Aktivitäten verwendet wird.

​

Private Kanäle

1. Verwenden Sie Standardkanäle für Bot-Interaktionen.
2. Verwenden Sie Direktnachrichten; Benutzer können dem Bot jederzeit direkt schreiben.
3. Verwenden Sie die Graph API für den historischen Zugriff (erfordert ChannelMessage.Read.All).

​

Fehlerbehebung

​

Häufige Probleme

• Bilder werden in Kanälen nicht angezeigt: Graph-Berechtigungen oder Administratoreinwilligung fehlen. Installieren Sie die Teams-App neu, beenden Sie Teams vollständig und öffnen Sie es erneut.
• Keine Antworten im Kanal: Erwähnungen sind standardmäßig erforderlich; legen Sie channels.msteams.requireMention=false fest oder konfigurieren Sie dies je Team/Kanal.
• Versionsabweichung (Teams zeigt weiterhin das alte Manifest): Entfernen Sie die App, fügen Sie sie erneut hinzu, beenden Sie Teams vollständig und öffnen Sie es zur Aktualisierung erneut.
• 401 Unauthorized vom Webhook: Wird beim manuellen Testen ohne Azure-JWT erwartet; dies bedeutet, dass der Endpunkt erreichbar ist, die Authentifizierung jedoch fehlgeschlagen ist. Verwenden Sie Azure Web Chat für einen ordnungsgemäßen Test.

​

Fehler beim Hochladen des Manifests

• “Icon file cannot be empty”: Das Manifest verweist auf Symboldateien mit einer Größe von 0 Byte. Erstellen Sie gültige PNG-Symbole (32x32 für outline.png, 192x192 für color.png).
• “webApplicationInfo.Id already in use”: Die App ist noch in einem anderen Team/Chat installiert. Suchen und deinstallieren Sie sie zuerst oder warten Sie 5-10 Minuten auf die Übernahme der Änderung.
• “Something went wrong” beim Hochladen: Laden Sie sie stattdessen über https://admin.teams.microsoft.com hoch, öffnen Sie die Browser-Entwicklertools (F12) → Registerkarte Network und prüfen Sie den Antworttext auf den tatsächlichen Fehler.
• Querladen schlägt fehl: Versuchen Sie “Upload an app to your org’s app catalog” anstelle von “Upload a custom app”; dadurch werden Einschränkungen für das Querladen häufig umgangen.

​

RSC-Berechtigungen funktionieren nicht

1. Überprüfen Sie, ob webApplicationInfo.id exakt mit der App-ID Ihres Bots übereinstimmt.
2. Laden Sie die App erneut hoch und installieren Sie sie im Team/Chat neu.
3. Prüfen Sie, ob der Administrator Ihrer Organisation RSC-Berechtigungen blockiert hat.
4. Vergewissern Sie sich, dass Sie den richtigen Bereich verwenden: ChannelMessage.Read.Group für Teams, ChatMessage.Read.Chat für Gruppenchats.

​

Referenzen

• Azure Bot erstellen - Einrichtungsanleitung für Azure Bot
• Teams Developer Portal - Teams-Apps erstellen/verwalten
• Schema des Teams-App-Manifests
• Kanalnachrichten mit RSC empfangen
• Referenz zu RSC-Berechtigungen
• Dateiverarbeitung für Teams-Bots (Kanal/Gruppe erfordert Graph)
• Proaktive Nachrichten
• @microsoft/teams.cli - Teams-CLI zur Bot-Verwaltung

​

Verwandte Themen

• Kanalübersicht - alle unterstützten Kanäle
• Kopplung - DM-Authentifizierung und Kopplungsablauf
• Gruppen - Verhalten von Gruppenchats und erwähnungsbasierte Freigabe
• Kanal-Routing - Sitzungs-Routing für Nachrichten
• Sicherheit - Zugriffsmodell und Absicherung