Microsoft Teams setup

Install the plugin, register the bot and Teams app, point Teams at a reachable endpoint, and verify the result.

Bundled plugin

Microsoft Teams ships as a bundled plugin in current OpenClaw releases; no separate install is required in the normal packaged build. On an older build or a custom install that excludes bundled Teams, install the npm package directly:

openclaw plugins install @openclaw/msteams

Use the bare package to follow the current official release tag. Pin an exact version only when you need a reproducible install. Local checkout (running from a git repo):

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

Details: Plugins

Quick setup

@microsoft/teams.cli handles bot registration, manifest creation, and credential generation in one command. 1. Install and log in

npm install -g @microsoft/teams.cli@preview
teams login
teams status   # verify you're logged in and see your tenant info

The Teams CLI is currently in preview. Commands and flags may change between releases.

2. Start a tunnel (Teams cannot reach localhost) Install and authenticate the devtunnel CLI if needed (getting started guide).

# One-time setup (persistent URL across sessions):
devtunnel create my-openclaw-bot --allow-anonymous
devtunnel port create my-openclaw-bot -p 3978 --protocol auto

# Each dev session:
devtunnel host my-openclaw-bot
# Your endpoint: https://<tunnel-id>.devtunnels.ms/api/messages

--allow-anonymous is required because Teams cannot authenticate with devtunnels. Each incoming bot request is still validated by the Teams SDK.

Alternatives: ngrok http 3978 or tailscale funnel 3978 (URLs may change each session). 3. Create the app

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

This creates an Entra ID (Azure AD) application, generates a client secret, builds and uploads a Teams app manifest (with icons), and registers a Teams-managed bot (no Azure subscription needed). The output includes CLIENT_ID, CLIENT_SECRET, TENANT_ID, and a Teams App ID; it also offers to install the app in Teams directly. 4. Configure OpenClaw using the credentials from the output:

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

Or use environment variables directly: MSTEAMS_APP_ID, MSTEAMS_APP_PASSWORD, MSTEAMS_TENANT_ID. 5. Install the app in Teams teams app create prompts you to install the app; select “Install in Teams”. To get the install link later:

teams app get <teamsAppId> --install-link

6. Verify everything works

teams app doctor <teamsAppId>

Runs diagnostics across bot registration, AAD app config, manifest validity, and SSO setup. For production, consider federated authentication (certificate or managed identity) instead of client secrets.

Group chats are blocked by default (channels.msteams.groupPolicy: "allowlist"). To allow group replies, set channels.msteams.groupAllowFrom, or use groupPolicy: "open" to allow any member (mention-gated).

Goals

Talk to OpenClaw via Teams DMs, group chats, or channels.
Keep routing deterministic: replies always go back to the channel they arrived on.
Default to safe channel behavior (mentions required unless configured otherwise).

Local development (tunneling)

Teams cannot reach localhost. Use a persistent dev tunnel so the URL stays stable across sessions:

# One-time setup:
devtunnel create my-openclaw-bot --allow-anonymous
devtunnel port create my-openclaw-bot -p 3978 --protocol auto

# Each dev session:
devtunnel host my-openclaw-bot

Alternatives: ngrok http 3978 or tailscale funnel 3978 (URLs may change each session). If the tunnel URL changes, update the endpoint:

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

Testing the bot

Run diagnostics:

teams app doctor <teamsAppId>

Checks bot registration, AAD app, manifest, and SSO configuration in one pass. Send a test message:

Install the Teams app (install link from teams app get <id> --install-link).
Find the bot in Teams and send a DM.
Check gateway logs for incoming activity.

Overview

Mainstream messaging

Developer and self-hosted

Regional platforms

Configuration

Microsoft Teams setup

Bundled plugin

Quick setup

Goals

Local development (tunneling)

Testing the bot

​Bundled plugin

​Quick setup

​Goals

​Local development (tunneling)

​Testing the bot

Bundled plugin

Quick setup

Goals

Local development (tunneling)

Testing the bot