openclaw/docs/channels/msteams/configuration.md

Multi-channel AI gateway with extensible messaging integrations

---
summary: "Microsoft Teams configuration keys, environment variables, and history limits"
read_when:
  - Looking up a `channels.msteams` configuration key
  - Setting Teams credentials from environment variables
  - Tuning how much history reaches the prompt
title: "Microsoft Teams configuration"
sidebarTitle: "Configuration"
---

The `channels.msteams` settings, the environment variables that stand in for the auth keys, and the history context rules.

## Environment variables

These auth-related config keys can be set via environment variables instead of `openclaw.json` (other config keys, such as `groupPolicy` or `historyLimit`, are config-only):

| Env var                              | Config key                | Notes                               |
| ------------------------------------ | ------------------------- | ----------------------------------- |
| `MSTEAMS_APP_ID`                     | `appId`                   |                                     |
| `MSTEAMS_APP_PASSWORD`               | `appPassword`             |                                     |
| `MSTEAMS_TENANT_ID`                  | `tenantId`                |                                     |
| `MSTEAMS_AUTH_TYPE`                  | `authType`                | `"secret"` or `"federated"`         |
| `MSTEAMS_CERTIFICATE_PATH`           | `certificatePath`         | federated + certificate             |
| `MSTEAMS_CERTIFICATE_THUMBPRINT`     | `certificateThumbprint`   | accepted, not required for auth     |
| `MSTEAMS_USE_MANAGED_IDENTITY`       | `useManagedIdentity`      | federated + managed identity        |
| `MSTEAMS_MANAGED_IDENTITY_CLIENT_ID` | `managedIdentityClientId` | user-assigned managed identity only |

## History context

- `channels.msteams.historyLimit` controls how many recent channel/group messages are wrapped into the prompt. Falls back to `messages.groupChat.historyLimit`, then defaults to 50. Set `0` to disable.
- Graph thread context adds the parent and up to the oldest 50 replies alongside recent channel history. It excludes the triggering message and keeps history separate from the sender's command text, so commands quoted in history do not execute. Long fetched messages retain their beginning and end within the prompt's per-message limit.
- Thread and quoted attachment context follow `channels.msteams.contextVisibility`, falling back to `channels.defaults.contextVisibility`, then `all`. Use `allowlist` to filter both by sender allowlists (`allowFrom` / `groupAllowFrom`), or `allowlist_quote` to filter thread history while permitting quoted context.
- DM history can be limited with `channels.msteams.dmHistoryLimit` (user turns). Per-user overrides: `channels.msteams.dms["<user_id>"].historyLimit`.

## Configuration

Key settings (see [/gateway/configuration](/gateway/configuration) for shared channel patterns):

- `channels.msteams.enabled`: enable/disable the channel.
- `channels.msteams.appId`, `channels.msteams.appPassword`, `channels.msteams.tenantId`: bot credentials.
- `channels.msteams.cloud`: Teams SDK cloud environment (`Public`, `USGov`, `USGovDoD`, or `China`; default `Public`). Set with `serviceUrl` for USGov/DoD SDK clouds; China uses the SDK preset and stored Azure China Bot Framework conversation references, with Graph-backed helpers disabled until Azure China Graph routing ships.
- `channels.msteams.serviceUrl`: Bot Connector service URL boundary for SDK proactive operations. Public cloud uses the SDK default; set for GCC (`https://smba.infra.gcc.teams.microsoft.com/teams`), GCC High, or DoD. China accepts Azure China Bot Framework channel hosts when the stored conversation reference comes from Teams operated by 21Vianet.
- `channels.msteams.webhook.path`: Gateway HTTP route (omitted or empty uses `/api/messages`), served on `gateway.port` (default `18789`).
- `channels.msteams.legacyWebhook`: explicit compatibility listener. `{ port, host? }` selects an endpoint, preserving the previous wildcard bind when `host` is omitted. Omitted or `false` opens no separate listener.
- `channels.msteams.dmPolicy`: `pairing | allowlist | open | disabled` (default `pairing`).
- `channels.msteams.allowFrom`: DM allowlist (AAD object IDs recommended). Stable AAD object IDs also authorize approval actions. The wizard resolves names to IDs during setup when Graph access is available.
- `channels.msteams.defaultTo`: default outbound target; a stable AAD object ID can also authorize approval actions.
- `channels.msteams.dangerouslyAllowNameMatching`: break-glass toggle to re-enable mutable UPN/display-name matching and direct team/channel name routing.
- `channels.msteams.textChunkLimit`: outbound text chunk size in characters (default `4000`, and hard-capped at `4000` regardless of a higher configured value).
- `channels.msteams.streaming.chunkMode`: `length` (default) or `newline` to split on blank lines (paragraph boundaries) before length chunking.
- `channels.msteams.mediaAllowHosts`: allowlist for inbound attachment hosts (defaults to Microsoft/Teams domains: Graph, SharePoint/OneDrive, Teams CDN, Bot Framework, Azure Media Services).
- `channels.msteams.mediaAuthAllowHosts`: allowlist for attaching Authorization headers on media retries (defaults to Graph + Bot Framework hosts).
- `channels.msteams.graphMediaFallback`: opt into Graph message lookups when channel/group HTML omits file markers (default `false`; see [Channel/group file recovery](/channels/msteams/manifest-and-permissions#channel%2Fgroup-file-recovery-graphmediafallback)).
- `channels.msteams.mediaMaxMb`: per-channel media size limit override in MB. Falls back to `agents.defaults.mediaMaxMb` when unset.
- `channels.msteams.requireMention`: require @mention in channels/groups (default `true`).
- `channels.msteams.requireMentionInBotThreads`: override mention gating in channel threads rooted at this bot's tracked messages. Omitted preserves current behavior; see [Bot-created threads](/channels/msteams/access-control#mentions-in-bot-created-threads).
- `channels.msteams.replyStyle`: `thread | top-level` (see [Reply style](/channels/msteams/messaging#reply-style-threads-vs-posts)).
- `channels.msteams.teams.<teamId>.replyStyle`: per-team override.
- `channels.msteams.teams.<teamId>.requireMention`: per-team override.
- `channels.msteams.teams.<teamId>.requireMentionInBotThreads`: per-team bot-thread override.
- `channels.msteams.teams.<teamId>.tools`: default per-team tool policy overrides (`allow`/`deny`/`alsoAllow`) used when a channel override is missing.
- `channels.msteams.teams.<teamId>.toolsBySender`: default per-team per-sender tool policy overrides (`"*"` wildcard supported).
- `channels.msteams.teams.<teamId>.channels.<conversationId>.replyStyle`: per-channel override.
- `channels.msteams.teams.<teamId>.channels.<conversationId>.requireMention`: per-channel override.
- `channels.msteams.teams.<teamId>.channels.<conversationId>.requireMentionInBotThreads`: per-channel bot-thread override.
- `channels.msteams.teams.<teamId>.channels.<conversationId>.tools`: per-channel tool policy overrides (`allow`/`deny`/`alsoAllow`).
- `channels.msteams.teams.<teamId>.channels.<conversationId>.toolsBySender`: per-channel per-sender tool policy overrides (`"*"` wildcard supported).
- `toolsBySender` keys use explicit prefixes: `channel:`, `id:`, `e164:`, `username:`, `name:`. Run `openclaw doctor --fix` to migrate retired unprefixed keys to `id:` entries.
- `channels.msteams.authType`: authentication type - `"secret"` (default) or `"federated"`.
- `channels.msteams.certificatePath`: path to PEM certificate file (federated + certificate auth).
- `channels.msteams.certificateThumbprint`: certificate thumbprint; accepted, not required for auth.
- `channels.msteams.useManagedIdentity`: enable managed identity auth (federated mode).
- `channels.msteams.managedIdentityClientId`: client ID for user-assigned managed identity.
- `channels.msteams.sharePointSiteId`: SharePoint site ID for file uploads in group chats/channels (see [Sending files in group chats](/channels/msteams/messaging#sending-files-in-group-chats)).
- `channels.msteams.welcomeCard`, `channels.msteams.groupWelcomeCard`, `channels.msteams.promptStarters`: welcome Adaptive Card shown on first DM/group contact, and its suggested prompt buttons.
- `channels.msteams.responsePrefix`: text prefixed to outbound replies.
- `channels.msteams.feedbackEnabled` (default `true`), `channels.msteams.feedbackReflection` (default `true`), `channels.msteams.feedbackReflectionCooldownMs`: thumbs-up/down feedback on replies and the negative-feedback reflection follow-up.
- `channels.msteams.sso`, `channels.msteams.delegatedAuth`: Bot Framework OAuth connection and delegated Graph scopes for SSO-backed flows; `sso.enabled: true` requires `sso.connectionName`.

## Migrating an existing webhook endpoint

Teams webhooks now share the Gateway HTTP listener. The Teams SDK still verifies
Azure JWT signatures; callers do not supply a Gateway token. Keep the public
HTTPS messaging endpoint in Azure Bot and change its reverse-proxy upstream to
Gateway port `18789` (or your `gateway.port`), preserving `/api/messages` or your
configured `webhook.path`. If you expose a port directly, update Azure Bot's
messaging endpoint to the public HTTPS URL that reaches this Gateway route.

Doctor pins `legacyWebhook: { port: 3978 }` once for an enabled Teams channel on
an existing installation that relied on the implicit port. Evidence of prior
operation is required; fresh installations open no separate listener. An
explicitly configured `webhook.port` moves to `legacyWebhook.port` through
Doctor's normal config backup and write flow. Pinned compatibility listeners
forward into the same Gateway route and JWT validation.

The deprecated TypeScript `webhook.port` input remains source-compatible until
the next Plugin SDK major. Runtime config uses `legacyWebhook`; run
`openclaw doctor --fix` to migrate the old key.

After confirming a delivery through the Gateway port, remove the
`channels.msteams.legacyWebhook` pin and any old firewall or Compose port mapping.
Keep `meta.migrations.webhookListeners`, which Doctor saves with the pin, so later
runs do not recreate it. See [webhook migrations](/gateway/doctor/config-migrations#channel-webhook-listeners)
for included and read-only config sources.
Explicit `false` also disables the listener. Doctor and startup print the
Gateway route and the setting to remove.

For an existing installation that supplies Teams credentials only through
environment variables, Doctor preserves the endpoint without enabling Teams in
the source config. If those credentials are visible only to the Gateway service,
Doctor leaves the decision pending until Gateway startup. Continue using
`gateway run --ambient-channels` to activate it. A listener setting alone no
longer enables Teams; use `enabled: true` for a permanent opt-in. Doctor adds that
flag to authored listener settings that previously implied activation, including
an explicit `legacyWebhook: false`. It does not add the flag to a generated pin
whose migration completion is already recorded.

A custom path also accepts the older `/api/messages` alias with its existing
deprecation warning when that route is available. If another plugin owns the
alias, startup logs the conflict and keeps serving the configured path. Update
Azure Bot to the configured path.

The Gateway reserves `/health`, `/healthz`, `/ready`, `/readyz`, `/startup`, and
`/startupz` for probes, including URLs with query strings. If your former Teams
callback uses one of these paths, set `webhook.path` to `/api/messages` and update
Azure Bot or the proxy upstream to match. Doctor reports this conflict. The
compatibility listener keeps the old endpoint working; startup refuses the
unusable Gateway route when no explicit legacy listener is configured. Verify
the replacement before removing that listener's pin.

Paths under `/api/channels` require Gateway authentication on the main listener,
including encoded spellings. Teams callbacks authenticate with Azure JWTs, so
use `/api/messages` instead. Doctor and startup report the same callback-change
action; the compatibility listener continues serving the old path until that
cutover is complete.

Express parameter, wildcard, and brace patterns continue working on the legacy
port. Gateway route registration uses literal paths. Before disabling the legacy
listener for a pattern, change the existing `webhook.path` to `/api/messages` and
update Azure Bot or your proxy. Doctor and startup identify these patterns; without
an explicit legacy listener, startup reports the required change instead of silently
dropping callbacks.