MS Teams Integration Migration Guide

In recent versions of GoClaw, the Microsoft Teams integration no longer uses the legacy AzureBot + Local File Server architecture, in which the agent's files were served from GoClaw's own HTTP server. Files the agent sends now go through Microsoft's File Consent flow, and every inbound request is checked as coming from Bot Framework.

If you configured MS Teams with the older instructions, check the steps below: a single-tenant bot needs tenant_id, or the Teams channel does not start.

1. What Has Changed?

• File Sharing: The legacy version hosted files generated by the agent on GoClaw's own HTTP server and sent a direct link. The new version replaces this entirely, using Microsoft's official File Consent Card to upload the file to the user's OneDrive once the user approves. Files a user sends to the agent need no card: GoClaw downloads them directly from Microsoft.
• Identity: The sender's name and ID come from the Teams activity itself. Each inbound request must carry a Bot Framework token signed by Microsoft whose audience is your bot's App ID; others are refused with 401. GoClaw does not call the Microsoft Graph API.
• Replies: GoClaw posts a placeholder message while the agent works and replaces it with the whole answer when the turn ends. An answer too long for one Teams message continues in further messages.

2. Migration Steps

You do not need to delete or recreate your existing Azure Bot or App Registration, and no Microsoft Graph API permissions are needed. Earlier versions of this guide asked for User.Read.All and Files.ReadWrite.All; GoClaw does not use them, so a tenant administrator can remove them.

Step 1: Verify Tenant ID in config.yaml

A single-tenant bot needs its Tenant ID. GoClaw requests its Bot Framework token from the tenant in tenant_id; with tenant_id empty it uses the multi-tenant botframework.com endpoint, which does not issue tokens for a single-tenant app, and the Teams channel does not start (Teams channel failed: in the gateway log). A multi-tenant bot can leave it empty.

Check if the tenant_id value is filled in the channels.msteams section of your GoClaw config.yaml file.

channels:
  msteams:
    enabled: true
    app_id: "YOUR_APP_ID"
    app_password: "YOUR_APP_PASSWORD"
    tenant_id: "YOUR_TENANT_ID" # ← required for a single-tenant bot
    bot_name: "MyGoClawBot"

Where to find the Tenant ID? Go to Azure Portal -> App Registrations -> Select your App -> Overview page, and copy the Directory (tenant) ID.

Step 2: Restart the Server

Once the configuration is complete, restart the GoClaw server.

# Installed with `goclaw service install` (a per-user service, the default):
systemctl --user restart goclaw

# Installed with `sudo goclaw service install --system`:
sudo systemctl restart goclaw

# Any installed service, including launchd on macOS:
goclaw service stop && goclaw service start

# Or if you are running it directly, stop and run it again:
goclaw

From now on, when the agent sends you a file (an Excel report, for example), a "File Consent Card" asking for permission appears in Teams. Clicking "Accept" uploads the file to your OneDrive; GoClaw posts no further message after the upload. A card left unanswered for 24 hours, or across a gateway restart, has expired: clicking "Accept" then gets a reply that the file is no longer available. Files you send to the agent need no card.

3. Known Limitations

• File Consent Cards do not work in group chats or channels. The Microsoft Bot Framework only renders consent cards inside 1:1 DMs. If a file is sent to a group, the card will appear but users will not be able to click it—hence, this feature is only supported in DMs.
• SSO token exchange is not implemented. GoClaw answers a signin/tokenExchange invoke with HTTP 200 and a body whose status is 412, so the Teams client falls back to interactive sign-in. Inbound Bot Framework requests are verified; what GoClaw does not validate is the user's SSO token, so Teams SSO cannot be used.