Guide to Connecting OpenClaw with Microsoft Teams

Introduction

Microsoft Teams is one of the leading enterprise collaboration platforms, widely used across organizations and companies. Connecting OpenClaw to Teams provides your organization with a secure, controllable AI assistant. This article covers the entire process from Azure AD app registration to Teams app deployment.

Prerequisites

• OpenClaw is installed and running
• You have a Microsoft 365 organizational account (personal accounts have limited functionality)
• You have an Azure subscription (the free tier is sufficient)
• You have Teams admin permissions (or can contact an admin to approve the app)
• The OpenClaw service is accessible via a public HTTPS URL

Architecture Overview

The message flow for a Teams Bot is as follows:

User sends a message in Teams
         ↓
Microsoft Bot Framework Service
         ↓
Sends to OpenClaw via HTTPS Webhook
         ↓
OpenClaw processes the message and calls the AI model
         ↓
Sends reply via the Bot Framework API
         ↓
User receives the reply in Teams

Step 1: Azure AD App Registration

1.1 Create an App Registration

1. Log in to the Azure Portal
2. Search for and navigate to Azure Active Directory > App registrations
3. Click New registration
4. Fill in the following information:

5. Click Register

1.2 Record Key Information

After registration, note the following from the Overview page:

Application (client) ID: 12345678-abcd-efgh-ijkl-123456789012
Directory (tenant) ID: 87654321-dcba-hgfe-lkji-210987654321

1.3 Create a Client Secret

1. Click Certificates & secrets in the left sidebar
2. Click New client secret
3. Enter a description (e.g., "OpenClaw Bot Secret")
4. Select an expiration period (24 months recommended)
5. Click Add
6. Copy the secret value immediately (it will not be visible after you leave the page)

Client secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Note: Save this secret immediately — it cannot be viewed again after the page is refreshed!

Step 2: Create a Bot Resource

2.1 Create an Azure Bot

1. In the Azure Portal, search for Azure Bot
2. Click Create
3. Fill in the following information:

4. Click Review + create > Create

2.2 Configure the Messaging Endpoint

After the Bot resource is created:

1. Navigate to the Bot resource page
2. Click Configuration in the left sidebar
3. Enter the following in the Messaging endpoint field:

https://your-domain.com/webhook/teams/messages

4. Click Apply

2.3 Enable the Teams Channel

1. Click Channels in the Bot resource's left sidebar
2. Click Microsoft Teams from the available channels list
3. Agree to the terms of service
4. Click Apply

After enabling the Teams channel, the status should show Running.

Step 3: Configure OpenClaw

3.1 Via Configuration File

Edit ~/.config/openclaw/openclaw.json5:

{
  channels: {
    teams: {
      enabled: true,
      // Azure AD Application (client) ID
      appId: "12345678-abcd-efgh-ijkl-123456789012",
      // Azure AD Client secret
      appPassword: "your-client-secret-value",
      // Tenant ID (can be left empty for multitenant mode)
      tenantId: "",

      // Webhook path
      webhookPath: "/webhook/teams/messages",

      // Message handling configuration
      message: {
        // Whether @Bot is required in team channels
        mentionRequired: true,
        // Auto-reply in one-on-one chats
        personalChatEnabled: true,
        // Whether to enable in group chats
        groupChatEnabled: true
      },

      // Reply configuration
      reply: {
        // Whether to use Adaptive Card format (more visually appealing)
        useAdaptiveCard: true,
        // Show "typing" indicator
        showTyping: true,
        // Long message split threshold
        maxLength: 28000
      }
    }
  }
}

3.2 Via Environment Variables

export TEAMS_APP_ID="12345678-abcd-efgh-ijkl-123456789012"
export TEAMS_APP_PASSWORD="your-client-secret-value"

3.3 Restart and Verify

openclaw restart

# View Teams channel logs
openclaw logs -f --component channel:teams

Successful logs:

[INFO] [channel:teams] Teams Bot service started
[INFO] [channel:teams] App ID: 12345678-abcd-****-****-************
[INFO] [channel:teams] Webhook path: /webhook/teams/messages
[INFO] [channel:teams] Waiting for incoming messages...

Step 4: Create the Teams App Package

To find and use the Bot in the Teams client, you need to create a Teams app package.

4.1 Create the App Manifest

Create a manifest.json file:

{
  "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.16/MicrosoftTeams.schema.json",
  "manifestVersion": "1.16",
  "version": "1.0.0",
  "id": "12345678-abcd-efgh-ijkl-123456789012",
  "developer": {
    "name": "Your Organization",
    "websiteUrl": "https://your-domain.com",
    "privacyUrl": "https://your-domain.com/privacy",
    "termsOfUseUrl": "https://your-domain.com/terms"
  },
  "name": {
    "short": "OpenClaw AI",
    "full": "OpenClaw AI Assistant for Teams"
  },
  "description": {
    "short": "AI Smart Assistant",
    "full": "An AI smart assistant powered by OpenClaw, supporting multiple large language models to provide instant intelligent Q&A for your team."
  },
  "icons": {
    "outline": "outline.png",
    "color": "color.png"
  },
  "accentColor": "#5B5FC7",
  "bots": [
    {
      "botId": "12345678-abcd-efgh-ijkl-123456789012",
      "scopes": ["personal", "team", "groupChat"],
      "supportsFiles": false,
      "isNotificationOnly": false,
      "commandLists": [
        {
          "scopes": ["personal", "team", "groupChat"],
          "commands": [
            {
              "title": "ask",
              "description": "Ask the AI a question"
            },
            {
              "title": "model",
              "description": "Switch the AI model"
            },
            {
              "title": "reset",
              "description": "Reset the conversation context"
            },
            {
              "title": "help",
              "description": "Display help information"
            }
          ]
        }
      ]
    }
  ],
  "permissions": ["identity", "messageTeamMembers"],
  "validDomains": ["your-domain.com"]
}

4.2 Prepare the Icons

Prepare two icon files:

4.3 Package the App

Bundle manifest.json, color.png, and outline.png into a ZIP file:

zip teams-app.zip manifest.json color.png outline.png

4.4 Upload to Teams

Developer upload (personal use):

1. Open the Teams client
2. Click Apps on the left > Manage your apps
3. Click Upload an app > Upload a custom app
4. Select the teams-app.zip file

Organization-wide deployment (admin action):

1. Log in to the Teams Admin Center
2. Navigate to Teams apps > Manage apps
3. Click Upload new app
4. Select the teams-app.zip file
5. Review and publish to the organization app store

Usage

One-on-One Chat

1. Find the OpenClaw AI app in Teams
2. Click to start chatting
3. Type your question to receive an AI reply

Using in Team Channels

1. @mention OpenClaw AI in the target team channel
2. Enter your question

@OpenClaw AI Please write a weekly report template for my project

Using in Group Chats

1. Add OpenClaw AI to a group chat
2. @mention the Bot and enter your question

Adaptive Card Format

With Adaptive Card enabled, the Bot's replies will be more visually appealing and structured:

{
  channels: {
    teams: {
      reply: {
        useAdaptiveCard: true,
        adaptiveCard: {
          // Use monospace font for code blocks
          codeStyle: true,
          // Show model information
          showModelInfo: true,
          // Show processing latency
          showLatency: true,
          // Add "Ask follow-up" buttons
          actionButtons: true
        }
      }
    }
  }
}

Adaptive Card formats the reply as a styled card, including:

• A header area displaying the Bot name and model
• A body area with Markdown rendering support
• Code blocks with syntax highlighting and a copy button
• A footer showing token consumption and processing time

Enterprise Deployment Considerations

Compliance and Data Security

User Permission Controls

{
  channels: {
    teams: {
      security: {
        // Allowed user email list
        allowedUsers: [
          "*@your-company.com"  // Allow all users under the company domain
        ],
        // Admin users
        adminUsers: [
          "[email protected]"
        ],
        // Allowed team IDs
        allowedTeams: [],
        // Daily message limit per user
        dailyLimit: 100
      }
    }
  }
}

High Availability Deployment

For enterprise-grade deployments, the following is recommended:

{
  channels: {
    teams: {
      // Request timeout (milliseconds)
      timeout: 60000,
      // Retry configuration
      retry: {
        maxAttempts: 3,
        backoffMs: 1000
      },
      // Concurrency limits
      concurrency: {
        maxConcurrent: 50,
        queueSize: 200
      }
    }
  }
}

Webhook vs. Connector Comparison

In addition to the Bot Framework approach, Teams also supports integration via Incoming Webhook or Connector:

Bot Framework is the only method that supports receiving user messages and sending replies, making it the recommended approach for OpenClaw. Webhooks and Connectors are only suitable for one-way notification scenarios.

Troubleshooting

Bot Not Responding

# Check OpenClaw logs
openclaw logs --level error --component channel:teams

# Common causes:
# 1. Messaging endpoint URL is unreachable
# 2. App ID or Password is incorrect
# 3. Teams channel is not enabled on the Bot

403 Forbidden Error

# Usually caused by an expired or incorrect App Password
# Regenerate a new password in Azure AD → App registrations → Certificates & secrets
# Update the OpenClaw configuration and restart
openclaw config set channels.teams.appPassword "new-password"
openclaw restart

App Cannot Be Uploaded to Teams

Check the following:

1. The Teams Admin Center allows custom app uploads
2. The id in manifest.json matches the Azure AD application ID
3. Icon files have the correct size and format
4. The ZIP package structure is correct (files are at the root level, not inside a subfolder)

Reply Timeout

The Teams Bot Framework requires a reply within 15 seconds. If the AI model response is slow:

{
  channels: {
    teams: {
      reply: {
        // Enable "typing" indicator to provide user feedback
        showTyping: true,
        // Send a "processing" message first
        thinkingMessage: "Thinking...",
        // Update the original message when done (instead of sending a new one)
        updateMessage: true
      }
    }
  }
}

Summary

Connecting OpenClaw to Microsoft Teams involves several steps, but it provides a secure and controllable AI assistant for your organization. The core workflow:

1. Register an application in Azure AD and obtain credentials
2. Create an Azure Bot resource and enable the Teams channel
3. Configure the App ID and Password in OpenClaw
4. Package and deploy the Teams app
5. Configure security policies and access controls

For enterprise scenarios, be sure to address data security, compliance requirements, and access control. It is recommended to validate everything in a test team first before rolling out to the entire organization.