Connect OpenClaw to Microsoft Teams

📘 Channel guide: This page covers Microsoft Teams–only setup. New to OpenClaw? Start with the Quick Start Guide and installation, then return here to add Teams.

Overview

OpenClaw can run as a bot inside Microsoft Teams-in team channels, group chats, and direct conversations. Once connected, your self-hosted AI agent can read messages, reply in threads or DMs, run tasks 24/7, and automate workflows for your organization-all from your own infrastructure, with no data leaving your control. The Teams channel is ideal for business automation, internal Q&A, meeting follow-ups, and enterprise deployments where Teams is already the primary collaboration tool. Integration uses the Azure Bot Service (or Bot Framework) and the Teams channel; you register a bot in Azure, enable the Teams channel, and point it at your OpenClaw Gateway (or a relay that forwards to OpenClaw).

This guide covers:

  • Creating and configuring an Azure Bot (or Bot Framework bot) and enabling the Teams channel
  • Obtaining the Microsoft App ID and client secret (or password) for your bot
  • Configuring the messaging endpoint so Teams can deliver messages to OpenClaw
  • Adding the OpenClaw channel configuration to your OpenClaw instance
  • Installing or sideloading the bot into Teams (teams, chats, and DMs)
  • Verification, common Teams-specific issues, and best practices

Prerequisites

  • OpenClaw installed and running - Gateway and CLI working. See the Quick Start Guide or installation hub for your platform.
  • Microsoft 365 tenant and Azure subscription - You need an Azure account to create a Bot resource (or register an app in Azure AD). For production, a Microsoft 365 tenant where Teams is enabled is required so you can add the bot to teams and chats.
  • Publicly reachable endpoint (for cloud bot) - If your bot uses the standard Bot Framework / Teams channel, Microsoft’s servers must be able to send HTTP requests to your OpenClaw Gateway or a relay. That usually means a public URL (e.g. via tunnel like ngrok, or a deployed gateway). For development, a tunnel is common; for production, use a secure endpoint and follow security best practices.
  • Basic terminal/CLI - You will run openclaw config edit and optionally openclaw status.

Step 1: Create an Azure Bot and Enable Teams

  1. Sign in to the Azure Portal. Create or select a resource group, then create a resource: search for Azure Bot (or “Bot Services”) and create a new bot. Choose a name (e.g. “OpenClaw Agent”), pricing tier (F0 free tier is often sufficient for testing), and Microsoft App ID-either create a new Microsoft App ID (recommended) or use an existing one.
  2. After the bot is created, open the bot resource. Go to Channels (under Bot management). Click Microsoft Teams to add the Teams channel. Accept the terms if prompted. The Teams channel is now enabled; Microsoft will send activity to the messaging endpoint you configure in the next step.
  3. Under Configuration (or Settings), find the Microsoft App ID and create or copy a Client secret (under “Manage” for the app in Azure AD, or via the bot’s configuration). Store the App ID and secret securely-you will add them to OpenClaw’s config and must never commit them to version control. Prefer environment variables (e.g. TEAMS_APP_ID, TEAMS_APP_SECRET) and reference them in the config.

If you use the legacy Bot Framework portal instead of Azure, register your bot there, configure the messaging endpoint, and add the Teams channel; the same App ID and password are used in OpenClaw.

Step 2: Configure the Messaging Endpoint

Teams (and the Bot Framework) send incoming messages to a messaging endpoint (HTTPS URL). OpenClaw’s Teams channel adapter typically exposes or uses this endpoint so that when a user messages the bot in Teams, the request is forwarded to the OpenClaw Gateway. The exact behavior depends on your OpenClaw version: some setups run an HTTP server that receives Bot Framework activities and forwards them to the Gateway; others use a built-in Teams adapter that registers the endpoint for you.

  1. In the Azure Bot resource, open Configuration (or Settings) and set the Messaging endpoint to the URL where OpenClaw (or your relay) receives POST requests from the Bot Framework. Example: https://your-gateway-or-relay.example.com/api/teams. For local development, use an HTTPS tunnel (e.g. ngrok) and point the endpoint to that URL; update it when you move to production.
  2. Ensure the endpoint is HTTPS and returns appropriate status codes so Microsoft does not disable the channel. See the official OpenClaw Teams channel docs for the exact path and expected payload.

Step 3: Configure OpenClaw for Teams

Add the Teams channel to your OpenClaw configuration. The exact schema may vary by OpenClaw version; refer to the official OpenClaw Teams channel documentation for the current structure.

  1. Open your config (e.g. openclaw config edit or edit the config file directly).
  2. Add a channel entry for Teams. Typically you will set:
    • Channel type (e.g. teams or microsoft-teams)
    • App ID - Your Microsoft App ID (prefer env var, e.g. TEAMS_APP_ID)
    • App secret / password - Client secret from Azure (prefer env var, e.g. TEAMS_APP_SECRET)
    • Any messaging endpoint or port settings required by the adapter (if not auto-configured)
  3. Save the config and restart the Gateway (or let it reload if it supports hot reload). Ensure the Gateway (or the Teams adapter) is listening on the URL you set in Azure as the messaging endpoint.

Example (illustrative; check docs for your version):

# In your OpenClaw config, under channels (or equivalent):
# teams:
#   appId: ${TEAMS_APP_ID}
#   appSecret: ${TEAMS_APP_SECRET}

Set TEAMS_APP_ID and TEAMS_APP_SECRET in your environment before starting OpenClaw. For more options (e.g. tenant ID restrictions, allowed teams), see the advanced configuration guide and the official docs.

Step 4: Add the Bot to Teams

Users need to interact with the bot in Teams. You can:

  • Install via “Add to Teams” - In the Azure Bot resource, open the Teams channel and use the “Add to Teams” or “Open in Teams” link to install the app into your tenant. Then add the bot to a team or open a direct chat.
  • Sideload a Teams app - If you have an app manifest (and optionally an app package), upload it in Teams (Apps → Manage your apps → Upload an app) so the bot appears in your org. This is common when you customize the app name, icon, or capabilities.

Once installed, open a channel or a direct chat with the bot and send a message. Your OpenClaw agent should receive it and respond according to your agent and model setup.

Step 5: Verify the Connection

  1. Run openclaw status (or your CLI’s status command) and confirm the Teams channel is listed and connected (if your version reports channel status).
  2. In Teams, send a message in a channel where the bot is added, or in a direct chat with the bot. The OpenClaw agent should respond.
  3. If the bot does not respond, check Gateway logs and the messaging endpoint URL in Azure; see Common Issues below and the channel troubleshooting guide.

Common Teams Issues

Issue Solution
Bot doesn’t respond in Teams Confirm the messaging endpoint in Azure is correct and reachable (HTTPS). Check OpenClaw Gateway logs for incoming requests. Ensure the Teams channel is enabled on the Azure Bot and that OpenClaw config has the correct App ID and secret. Restart the Gateway after config changes.
401 Unauthorized / authentication errors Verify the Microsoft App ID and client secret in your config (or env vars) match the values in the Azure Bot / Azure AD app. Ensure no extra spaces or quotes. Rotate the secret in Azure if it was ever exposed and update OpenClaw.
Endpoint not reachable (development) Use an HTTPS tunnel (e.g. ngrok, cloudflared) and set that URL as the messaging endpoint in Azure. Keep the tunnel running while testing. For production, deploy the Gateway or relay behind a proper HTTPS endpoint and firewall.
Bot not visible or can’t add to team Use “Add to Teams” from the Azure Bot’s Teams channel page, or sideload the app in Teams (Apps → Manage your apps). Ensure your Microsoft 365 tenant allows custom apps if your org has restricted policies.
Tenant or permission restrictions Some organizations restrict which bots or apps can be installed. Check with your IT admin. For multi-tenant bots, ensure the Azure Bot is configured for the correct tenant(s) and that the app registration has the right API permissions if you use Graph or other Microsoft APIs.
Rate limits or throttling Microsoft enforces rate limits on the Bot Framework and Teams. Check OpenClaw logs for rate-limit or 429 responses; reduce message frequency or batch actions. Ensure outbound HTTPS to the Bot Framework / Teams endpoints is allowed.

For more fixes (gateway, config, other channels), see the full troubleshooting hub and channel issues page.

Best Practices

  • Keep App ID and secret secure. Use environment variables (e.g. TEAMS_APP_ID, TEAMS_APP_SECRET) and follow security best practices. Rotate the secret in Azure if it is ever exposed.
  • Use HTTPS and restrict access. The messaging endpoint must be HTTPS. Keep the Gateway bound to localhost when possible and expose it only via a secure tunnel or reverse proxy; see network isolation and credential management.
  • Test in a dev tenant first. Use a development or test Microsoft 365 tenant before rolling out to production teams.
  • Stay updated. Keep OpenClaw and the Teams adapter up to date for compatibility with Bot Framework and Teams API changes.
  • Monitor logs. Use openclaw logs (or your log path) to catch connection and authentication errors early.

Next Steps

Related Resources