OpenClaw Microsoft Teams: Deploy AI Agents Where Your Team Works

Most AI agent deployments live in the wrong place. Your team is in Microsoft Teams for six hours a day — and your AI agent is sitting in a separate tab nobody opens. Fix that in under 30 minutes.

The OpenClaw Teams integration handles the full message lifecycle: inbound from Teams, through your agent's reasoning pipeline, and back as a formatted response — whether that's plain text or a rich adaptive card. We've run this in production across several organizations and the setup is more straightforward than the Microsoft documentation makes it look.

Prerequisites

Before touching config files, make sure you have everything in place. Missing any one of these adds 20+ minutes of backtracking.

• OpenClaw v1.6.0 or later — Teams gateway received a full rewrite at v1.6
• An Azure account with an active subscription (free tier works for registration)
• Microsoft Teams admin access, or permission from your Teams admin to sideload apps
• A publicly reachable HTTPS endpoint for your OpenClaw instance (Teams requires this — no localhost)
• Node.js 18+ if you're building the app package locally with the Teams Toolkit CLI

Sound familiar? Most people hit the HTTPS requirement late. If you're running OpenClaw behind a home router or corporate firewall, set up a tunnel with ngrok or Cloudflare Tunnel first and get a stable HTTPS URL before continuing.

Azure Bot Registration

Microsoft Teams bots run through the Azure Bot Framework. You register your bot in Azure, get credentials, and then OpenClaw uses those credentials to authenticate with Teams on your behalf.

Configure OpenClaw for Teams

With Azure credentials in hand, add the Teams gateway block to your OpenClaw config. This tells OpenClaw where to listen, which credentials to use, and how to format responses.

Gateway Config Block

# config.yaml — Microsoft Teams gateway
gateways:
  teams:
    enabled: true
    app_id: "${TEAMS_APP_ID}"           # from Azure Bot Configuration page
    app_secret: "${TEAMS_APP_SECRET}"   # client secret you generated
    messaging_endpoint: "/openclaw/teams"
    scopes:
      - personal      # direct messages
      - team          # @mentions in channels
      - groupchat     # group conversations
    response_format: adaptive_card     # adaptive_card | text
    adaptive_card_version: "1.5"
    typing_indicator: true             # shows "..." while agent thinks
    max_message_length: 28000          # Teams limit
    thread_memory: true                # maintain context across a thread

Set TEAMS_APP_ID and TEAMS_APP_SECRET as environment variables — never hardcode them. Restart OpenClaw after updating config and check the logs for a successful Teams gateway startup message.

Build the Teams App Package

Teams requires you to package your bot as a Teams app before users can install it. The package is a ZIP file containing a manifest and two icon images.

Here's the minimum viable manifest. We'll get to the exact config in a moment — but first you need to understand what the validDomains array controls, because this breaks 80% of setups.

{
  "manifestVersion": "1.17",
  "version": "1.0.0",
  "id": "${TEAMS_APP_ID}",
  "packageName": "com.aiagentsguides.openclaw",
  "developer": {
    "name": "Your Organization",
    "websiteUrl": "https://aiagentsguides.com",
    "privacyUrl": "https://aiagentsguides.com/privacy",
    "termsOfUseUrl": "https://aiagentsguides.com/terms"
  },
  "name": { "short": "OpenClaw AI", "full": "OpenClaw AI Assistant" },
  "description": {
    "short": "AI agent powered by OpenClaw",
    "full": "An intelligent assistant that answers questions and automates workflows inside Microsoft Teams."
  },
  "icons": { "outline": "outline.png", "color": "color.png" },
  "accentColor": "#C8321E",
  "bots": [{
    "botId": "${TEAMS_APP_ID}",
    "scopes": ["personal", "team", "groupChat"],
    "supportsFiles": false,
    "isNotificationOnly": false
  }],
  "permissions": ["identity", "messageTeamMembers"],
  "validDomains": ["yourdomain.com"]
}

The validDomains entry must match your OpenClaw instance domain exactly. A mismatch here causes Teams to silently drop messages — the bot appears online but never responds. This catches more people than any other single config error.

Package the manifest: create a ZIP containing manifest.json, color.png (192×192px), and outline.png (32×32px, transparent background). Upload the ZIP in Teams Admin Center under Teams apps → Manage apps → Upload an app.

Deploy and Test

After uploading the app package, search for your app in Teams and start a chat with it. Send a simple message like "Hello" — you should get a response within 3 seconds on a properly configured setup.

Verify the full flow works by checking OpenClaw logs in parallel:

$ openclaw logs --tail 30 --gateway teams

[2025-02-10 09:14:02] INFO  Teams gateway: listening on /openclaw/teams
[2025-02-10 09:14:45] INFO  Teams: inbound message from user_id=29:abc123 scope=personal
[2025-02-10 09:14:46] INFO  Agent: processing message, model=gpt-4o
[2025-02-10 09:14:48] INFO  Teams: response sent (1.8s), format=adaptive_card

That 1.8-second round trip is typical. If you're seeing 8–10 second delays, the bottleneck is almost always the model endpoint, not the Teams gateway itself.

Advanced: Adaptive Cards for Richer Responses

Plain text works. Adaptive cards work better for business contexts. OpenClaw can automatically wrap structured agent outputs in adaptive card templates — your users get clickable buttons, formatted tables, and input forms directly in their Teams chat.

Enable adaptive card templates in config:

gateways:
  teams:
    response_format: adaptive_card
    card_templates:
      default: "templates/teams/default_card.json"
      list_response: "templates/teams/list_card.json"
      confirmation: "templates/teams/confirm_card.json"

The template engine reads your agent's structured output and selects the matching card template automatically. For unstructured text responses, OpenClaw falls back to a plain text message — you never break the conversation flow.

Common Mistakes

Here's where most Teams deployments go wrong. Each of these has cost someone several hours.

• Wrong messaging endpoint URL — must match exactly between Azure bot config and your OpenClaw messaging_endpoint value. Even a trailing slash difference causes failures.
• validDomains not set correctly — Teams silently drops messages if the request origin doesn't match a domain in this array. Most common failure mode.
• App package uploaded but not installed — uploading to Teams Admin Center makes the app available but doesn't install it. Users must search for and install it manually, or you push it via Teams policies.
• Expired client secret — bot goes offline silently. Add secret rotation to your infrastructure runbook on day one.
• Single tenant bot trying to serve multiple tenants — if your Teams org spans multiple Azure AD tenants, you need a multi-tenant bot registration. Single-tenant bots are invisible to other tenants by design.

Frequently Asked Questions

Does OpenClaw work with Microsoft Teams free accounts?

OpenClaw's Teams integration requires an Azure subscription for bot registration — this is a Microsoft requirement, not an OpenClaw limitation. The Azure free tier covers the bot service costs for low-volume deployments, so you won't pay anything until you scale beyond a few thousand messages per month.

Can OpenClaw respond in Teams channels as well as direct messages?

Yes. Set scopes: [team] in your manifest and OpenClaw responds in public channels when @mentioned. For DMs, personal handles one-on-one conversations. Most deployments enable both scopes simultaneously — configure each independently in your openclaw gateway block.

How do I keep my Azure bot credentials secure with OpenClaw?

Never hardcode credentials in config.yaml. Use environment variables — TEAMS_APP_ID and TEAMS_APP_SECRET — and load them with the ${} syntax OpenClaw supports. For production, store secrets in Azure Key Vault or your CI/CD secrets manager and inject them at deploy time.

What Teams message types can OpenClaw handle?

OpenClaw handles text messages, @mentions, adaptive card interactions, and file attachments as of v1.6. Voice and video calls are not supported. The most common deployment pattern is text-based chat in both channels and direct message threads, with adaptive card responses for structured outputs.

Why is my OpenClaw Teams bot showing as offline?

An offline status almost always means the bot framework endpoint isn't reachable. Verify your messaging_endpoint URL returns HTTP 200 on GET requests, check that your SSL certificate is valid, and confirm OpenClaw is running with openclaw status. If the URL is correct, regenerate your app secret in Azure and update config.

Can I deploy OpenClaw to multiple Teams workspaces?

Yes — publish the app to your organization's Teams app catalog and any workspace in your tenant can install it. For cross-tenant deployments, submit the app to the public Microsoft Teams store or use sideloading on each target tenant. Each tenant requires its own Azure bot registration.

How long does the full Teams setup take?

Plan for 25–35 minutes end-to-end: 10 minutes for Azure bot registration, 5 minutes for OpenClaw config, 10 minutes to build and upload the Teams app package, and 5–10 minutes for testing. The Azure portal steps are the slowest part — have your subscription ready before you start.