Hermes configuration

Two sources are supported: config.yaml takes precedence, .env is the fallback. The recommended pattern keeps secrets in .env and references them from config.yaml with ${VAR} (the loader expands them), so config lives in one declarative file. Most config.yaml keys have a matching MSTEAMS_BRIDGE_* env var (e.g. realtime.azure_endpoint ↔ MSTEAMS_BRIDGE_AZURE_ENDPOINT, secret ↔ MSTEAMS_BRIDGE_SECRET); config.yaml wins where both are set. Exceptions: path is config-only, and the SharePoint site id uses TEAMS_SHAREPOINT_SITE_ID (shared with the chat plane).

config.yaml

%LOCALAPPDATA%\hermes\config.yaml (Windows) / ~/.hermes/config.yaml:

plugins:
  enabled:
    - msteams_bridge
  entries:
    msteams_bridge:
      config:
        # ONE secret covers BOTH lanes - calling and messages. StandIn issues it per connection
        # and you paste it once. (Per-lane overrides exist; see "Two lanes" below.)
        secret: ${MSTEAMS_BRIDGE_SECRET} # must equal the secret StandIn shows you
        host: 0.0.0.0                    # 127.0.0.1 only works behind a tunnel on the same machine
        calling_port: 9442               # the media WebSocket -> /msteams/calling
        # Teams chat does NOT ride this plugin: it is the gateway's Teams platform on
        # 127.0.0.1:3978 at /api/messages. messages_port below is the MANAGED-BOT chat
        # relay only, and most installs never set it. See /expose.
        messages_port: 9444              # managed-bot chat relay -> /msteams/messages
        # Post meeting minutes to the chat with the .docx as a native file
        # card - no SharePoint needed; it rides the Bot Framework attachment
        # contract using the chat plane's bot credentials.
        meeting_recap: true
        realtime:
          backend: azure
          azure_endpoint: https://<your-azure-resource>.cognitiveservices.azure.com
          azure_deployment: gpt-realtime
          azure_api_version: 2025-04-01-preview
          voice: cedar
          api_key: ${AZURE_FOUNDRY_API_KEY}           # secret stays in .env
          vad_threshold: 0.5
          prefix_padding_ms: 300
          silence_duration_ms: 500

.env

%LOCALAPPDATA%\hermes\.env / ~/.hermes/.env - the secret store (used directly, or referenced above). A fully env-only setup works too:

MSTEAMS_BRIDGE_SECRET=...            # the ONE connection secret - covers calling AND messages
AZURE_FOUNDRY_API_KEY=...            # realtime key (also used by the gateway)
# fully env-only is fine too:
MSTEAMS_BRIDGE_HOST=0.0.0.0
MSTEAMS_BRIDGE_PORT=9442
MSTEAMS_BRIDGE_REALTIME_BACKEND=azure
MSTEAMS_BRIDGE_AZURE_ENDPOINT=https://<your-azure-resource>.cognitiveservices.azure.com
MSTEAMS_BRIDGE_AZURE_DEPLOYMENT=gpt-realtime
MSTEAMS_BRIDGE_AZURE_API_VERSION=2025-04-01-preview
MSTEAMS_BRIDGE_REALTIME_VOICE=cedar

backend: openai uses public OpenAI instead of Azure - set the OpenAI key in place of the Azure endpoint/deployment fields.

For the hosted StandIn bridge to connect, bind a reachable address: set host: 0.0.0.0 (or keep 127.0.0.1 behind a tunnel that forwards to it) - the default loopback bind is only reachable from the same machine. allow_remote_worker has no effect on inbound connections; it only governs where outbound “call me back” requests may be sent (see the key reference below).

Key reference

Hermes implements the same feature set as the OpenClaw plugin; keys are snake_case and each has a matching MSTEAMS_BRIDGE_* env var.

Key	Meaning
`secret`	The connection secret. One value covers BOTH lanes; StandIn issues it per connection and you paste it once. Env: `MSTEAMS_BRIDGE_SECRET`. Keep it in `.env`
`calling_secret` / `messages_secret`	Per-lane OVERRIDES, for deployments that insist on separate keys. When set they win over `secret`. Env: `MSTEAMS_BRIDGE_CALLING_SECRET` / `MSTEAMS_BRIDGE_MESSAGES_SECRET`. Most installs need neither
`host`	address BOTH lanes bind (default `0.0.0.0`; `127.0.0.1` is reachable only from the same machine, so it works only behind a tunnel that forwards to it)
`calling_port` / `path`	the media WebSocket StandIn dials (default `9442`, `/msteams/calling`, the same calling port as every other StandIn plugin). `port` is still accepted as the old name for `calling_port`. StandIn dials `/msteams/calling/{call_id}`; the bare path has no route and 404s by design
`messages_port` / `messages_path`	the managed-bot chat relay (default `9444`, `/msteams/messages`), used only when your identity runs on the StandIn Managed Bot. Ordinary Teams chat does not come here: it goes to the gateway’s Teams platform on `127.0.0.1:3978` at `/api/messages`. See Expose your agent
`gateway_reply_endpoint`	where the plugin posts chat replies back (default `https://teams.standin.komaa.com/api/chat/reply`) - override only for a self-hosted StandIn
`allow_remote_worker`	SSRF guard for outbound “call me back”: permit dialing a non-loopback `worker_base_url` (default `false` = loopback only). Does not affect inbound bridge connections
`require_recording_status`	only engage once Teams reports recording active (default `true`)
`allowlist` / `allowlist_allow_names` / `allow_all`	inbound caller policy (see below): allowlisted caller AAD ids; empty = deny all inbound callers unless `allow_all: true` (`MSTEAMS_BRIDGE_ALLOW_ALL`) explicitly opens it. `allowlist_allow_names` additionally matches display names (weaker; spoofable). When empty, `allowlist` inherits the chat plane’s `TEAMS_ALLOWED_USERS`, so voice + chat can share one AAD allowlist
`wake_phrases`	group-call “speak only when addressed” wake words (default `assistant`, `hermes`)
`watch_browser_tasks`	opt-in “watch it work” (default `false`): while a background task runs, the tile shows live frames of the agent’s own browser session instead of the plain progress panel. Off by default because each capture can invoke the auxiliary vision model (`MSTEAMS_BRIDGE_WATCH_BROWSER_TASKS`)
`max_vision_per_minute`	vision spend cap (default `30`, `0` = unlimited)
`session_scope`	`per-call` \| `per-thread` \| `per-aad` agent-memory scope
`meeting_recap`	post end-of-meeting minutes (default `false`)
`show_file_root`	root directory `show_file` may display from (workspace containment; default `<hermes home>/workspace/msteams_bridge_show`)
`languages`	(realtime block) list like `[en, fr, de, ar]` - reply in the caller’s language when configured; empty = auto-detect and mirror. `bilingual` remains a deprecated alias for `[ar, en]`
`share_point_site_id`	optional; reserved for a future large-file SharePoint path. The minutes `.docx` file card itself needs no SharePoint - it rides the Bot Framework attachment contract using the chat plane’s `TEAMS_CLIENT_ID`/`SECRET`/`TENANT_ID`
`worker_base_url` / `tenant_id`	outbound “call me back” - StandIn’s outbound endpoint + your tenant
`realtime.{backend,azure_endpoint,azure_deployment,voice,api_key,vad_threshold,…}`	realtime backend (`azure` \| `openai`); key stays in `.env`
`hmac_window_ms` / `max_connections` / `max_connections_per_ip`	handshake window + connection caps

Inbound policy (voice): Hermes vs OpenClaw

Hermes has no inboundPolicy key and no pairing mode for calls - the allowlist is the inbound policy:

allowlist set → only those AAD object ids may call (add allowlist_allow_names: true to also match display names, which is weaker).
allowlist empty → all inbound callers are denied, unless you explicitly opt out with allow_all: true (env: MSTEAMS_BRIDGE_ALLOW_ALL). An unset allowlist never means “open to all”.
When allowlist is empty, it inherits TEAMS_ALLOWED_USERS (the chat plane’s allowlist), so one AAD list can cover both voice and chat.

The openclaw pairing approve msteams <CODE> steps you will see in the Quickstart and Teams app pages are OpenClaw-only. The Hermes equivalents are: edit allowlist for voice callers, and for Teams chat DMs (handled by the Hermes gateway’s Teams platform, not msteams_bridge) either approve the pairing code the bot sends an unknown sender (hermes pairing approve teams <CODE>) or set TEAMS_ALLOWED_USERS - see the bot ignores Teams chat.

Run

Show config + readiness:

hermes msteams-bridge status

Serve the bridge (use --handler streaming for streaming mode, which needs ffmpeg):

hermes msteams-bridge serve --handler realtime

Or run it standalone:

python -m hermes_msteams_bridge.bridge_server

Field in StandIn	Public path	Local target
Agent calling URL	`wss://<your-public-host>/msteams/calling`	`127.0.0.1:9442`, path `/msteams/calling` (`msteams-bridge serve`)
Agent chat URL	`https://<your-public-host>/api/messages`	`127.0.0.1:3978`, path `/api/messages` (the gateway’s Teams platform)

StandIn dials the public addresses, so both have to be reachable from the internet. There is no port in either public URL when you mount by path, which is the documented way to expose them - see Expose your agent for the two commands and the probe recipes.

Microsoft Graph permissions

The bot’s Azure AD app needs admin-consented application permissions - see the canonical Graph permissions table on the Create the Azure bot page.

The secret must byte-match the value StandIn shows you, or the HMAC handshake fails: calls connect and immediately hang up, and chat relays are rejected.

Gateway-managed mode (two layers)

To have hermes gateway run host the voice bridge itself (one process, no separate serve), enable both the plugin and the platform:

plugins:
  enabled:
    - msteams_bridge        # layer 1: the plugin
  entries:
    msteams_bridge:
      config:
        secret: ${MSTEAMS_BRIDGE_SECRET}
platforms:
  msteams_bridge:
    enabled: true         # layer 2: the gateway platform

In this mode scheduled jobs can deliver by voice: a cron job with deliver=msteams_bridge places a call and speaks the result. Set MSTEAMS_BRIDGE_HOME_AAD to the AAD object id the gateway should call for those deliveries (the callee must also be on the allowlist). Run gateway mode or standalone serve, never both - the second owner fails loudly on the port bind.

Voice & language tuning lives in Hermes

STT and TTS provider selection, voices, and language hints are host configuration, not plugin keys: set Hermes’s own stt: and tts: blocks in ~/.hermes/config.yaml (see the Hermes TTS and voice-mode feature docs). The plugin inherits them - streaming mode dispatches the host’s text_to_speech tool and transcription chain, so all Hermes STT/TTS providers apply unchanged. The call also answers with the host’s SOUL.md identity and knows the host’s installed skills (chat/call parity).

Getting Started

Teams setup

Concepts

OpenClaw plugin

Hermes plugin

ElevenLabs bridge

LiveKit bridge

config.yaml

.env

Key reference

Inbound policy (voice): Hermes vs OpenClaw

Run

Microsoft Graph permissions

Gateway-managed mode (two layers)

Voice & language tuning lives in Hermes

​config.yaml

​.env

​Key reference

​Inbound policy (voice): Hermes vs OpenClaw

​Run

​Microsoft Graph permissions

​Gateway-managed mode (two layers)

​Voice & language tuning lives in Hermes

config.yaml

.env

Key reference

Inbound policy (voice): Hermes vs OpenClaw

Run

Microsoft Graph permissions

Gateway-managed mode (two layers)

Voice & language tuning lives in Hermes