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

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 18789 --protocol auto

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

Alternatives: ngrok http 18789 or tailscale funnel 18789 (URLs may change each session). Use your configured Gateway port if it differs. When configuring a reverse proxy, expose only the required webhook path.

New installations use only the Gateway port. Doctor preserves port 3978 on existing installations with a one-shot channels.msteams.legacyWebhook pin. After moving the callback and verifying delivery through the Gateway port, remove that pin to close the old port.

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:

{
  bindings: [{ agentId: "main", match: { channel: "msteams", accountId: "default" } }],
  channels: {
    msteams: {
      enabled: true,
      tenantId: "<TENANT_ID>",
      webhook: { path: "/api/messages" },
      accounts: {
        default: {
          appId: "<CLIENT_ID>",
          appPassword: "<CLIENT_SECRET>",
        },
      },
    },
  },
}

This account-based shape works for one bot or many. Environment variables (MSTEAMS_APP_ID, MSTEAMS_APP_PASSWORD, MSTEAMS_TENANT_ID) apply only to the default account. Each named account has its own bot credentials and webhook path on the same Gateway port. See Multiple bot accounts for endpoint examples.

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.

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).

{
  bindings: [{ agentId: "main", match: { channel: "msteams", accountId: "default" } }],
  channels: {
    msteams: {
      enabled: true,
      tenantId: "<TENANT_ID>",
      webhook: { path: "/api/messages" },
      accounts: {
        default: {
          appId: "<APP_ID>",
          appPassword: "<APP_PASSWORD>",
        },
      },
    },
  },
}

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 18789 --protocol auto

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

Alternatives: ngrok http 18789 or tailscale funnel 18789 (URLs may change each session). Use your configured Gateway port if it differs. When configuring a reverse proxy, expose only the required webhook path.

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:

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