Messaging Channels
Telegram, Discord, Slack, WeChat, WhatsApp, and Microsoft Teams reach your OpenClaw or Hermes agent through OpenShell-managed processes and gateway resources. For token-based channels, NemoClaw registers credentials with OpenShell providers. WeChat uses a host-side QR scan during onboarding to capture a token. WhatsApp pairs inside the sandbox through a QR scan and intentionally stores mutable session state there. Microsoft Teams uses Bot Framework credentials plus a public HTTPS webhook that forwards to the sandbox. NemoClaw writes the selected channel configuration into the sandbox image and keeps runtime delivery under OpenShell control.
Experimental Channels
WeChat, WhatsApp, and Microsoft Teams are experimental. WeChat and WhatsApp rely on QR-based pairing flows that are more fragile than token-based bots. Microsoft Teams requires an externally reachable webhook path that depends on your host networking setup. Interfaces, defaults, and supported features can change, and NVIDIA does not recommend these channels for production use.
You can enable channels during nemohermes onboard or add them later with host-side nemohermes <sandbox> channels commands.
Do not mutate messaging configuration directly inside the sandbox because NemoClaw generates /sandbox/.hermes/.env and Hermes config at image build time, and changes inside the running container do not persist across rebuilds.
nemohermes tunnel start does not start Telegram, Discord, Slack, or other chat bridges.
It only starts optional host services such as the cloudflared tunnel when that binary is present.
Refer to Commands for details.
Prerequisites
- A machine where you can run
nemohermes onboard(local or remote host that runs the gateway and sandbox). - A token or app credential set for each credential-based messaging platform you want to enable.
- A personal WeChat account on your phone for the host-side QR scan during onboarding, or a phone you can use to scan the QR code for WhatsApp pairing.
- A network policy preset for each enabled channel, or equivalent custom egress rules.
Channel Requirements
Telegram uses a bot token from BotFather.
Open Telegram, send /newbot to @BotFather, follow the prompts, and copy the token.
For Telegram group chats, disable privacy mode before testing group replies: in @BotFather, run /setprivacy, choose the bot, then choose Disable.
After changing privacy mode, remove the bot from each Telegram group and add it back so Telegram applies the new delivery setting to that group.
TELEGRAM_ALLOWED_IDS is a comma-separated list of Telegram user or private-chat IDs for DM access.
For compatibility with older QA scripts, NemoClaw also accepts TELEGRAM_AUTHORIZED_CHAT_IDS and TELEGRAM_CHAT_ID as aliases, but new automation should use TELEGRAM_ALLOWED_IDS.
Keep these aliases until QA automation and public repro templates have stopped exporting them for at least one full release.
Group chats stay open by default so rebuilt sandboxes do not silently drop Telegram group messages because of an empty group allowlist.
NemoClaw defaults TELEGRAM_GROUP_POLICY to open for OpenClaw.
Set TELEGRAM_GROUP_POLICY=allowlist to block OpenClaw group chats until explicit group entries are configured, or TELEGRAM_GROUP_POLICY=disabled to disable OpenClaw Telegram group access.
Hermes does not have an equivalent disable-groups policy; TELEGRAM_ALLOWED_IDS maps to Hermes TELEGRAM_ALLOWED_USERS, which authorizes those users across DMs, groups, and forums.
NemoClaw defaults TELEGRAM_REQUIRE_MENTION to 1, so the bot replies in Telegram groups only when users mention it.
Set TELEGRAM_REQUIRE_MENTION=0 when you want the bot to reply to all group messages.
Pairing and TELEGRAM_ALLOWED_IDS still govern direct messages.
Discord uses a bot token from the Discord Developer Portal.
For server channels, enable Developer Mode in Discord, right-click the server, and copy the Server ID into DISCORD_SERVER_ID.
By default, NemoClaw configures the bot to reply only when mentioned.
If DISCORD_SERVER_ID is set and DISCORD_REQUIRE_MENTION is unset, NemoClaw defaults DISCORD_REQUIRE_MENTION to 1.
Set DISCORD_REQUIRE_MENTION=0 if you want it to reply to all messages in the configured server.
Set DISCORD_USER_ID to restrict access to one user; otherwise, any member of the configured server can message the bot.
NemoClaw routes Discord REST and gateway traffic through the top-level managed proxy and does not write a per-account Discord proxy, because OpenClaw accepts only loopback values for that field.
Slack uses Socket Mode and requires two tokens.
Use SLACK_BOT_TOKEN for the bot user OAuth token (xoxb-...) and SLACK_APP_TOKEN for the app-level Socket Mode token (xapp-...).
NemoClaw validates both tokens before it saves Slack credentials or enables the channel.
This validation calls the live Slack APIs auth.test and apps.connections.open, so the tokens must belong to a real Slack app.
If Slack rejects the tokens (for example, invalid_auth for placeholder or fake values), NemoClaw skips the Slack channel.
NemoClaw applies the slack network policy preset only for channels that are actually enabled.
When Slack is skipped, NemoClaw does not apply the slack preset, so it does not appear as applied (●) in nemohermes <name> policy-list.
To exercise Slack channel setup and the slack policy preset with placeholder tokens in a restricted network or hermetic test environment, set NEMOCLAW_SKIP_SLACK_AUTH_VALIDATION=1 to skip the live credential probes; Slack token format checks still apply.
Set SLACK_ALLOWED_USERS to comma-separated Slack member IDs to authorize those users for DMs and for channel @mention events in channels where the Slack app is present.
Set SLACK_ALLOWED_CHANNELS to comma-separated Slack channel IDs to restrict channel @mention handling to those channels.
When both Slack allowlists are set, NemoClaw requires the mention to come from one of the allowed channels and one of the allowed members.
Channel messages still require an explicit bot mention.
When a Slack channel @mention is denied by these allowlists, NemoClaw sends a denial notice back to the sender instead of dropping the message silently.
During sandbox startup, NemoClaw normalizes OpenShell credential placeholders into the environment shape expected by the Slack runtime, so post-rebuild Slack starts use the gateway-managed tokens instead of literal placeholder strings.
NemoClaw enables rich Slack rendering for Hermes.
Final responses can use Slack Block Kit, including native table blocks for Markdown tables.
This uses the existing Slack credentials and does not require additional scopes or reinstalling the Slack app.
Slack Socket Mode allows one active connection per app-level token.
If another sandbox on the same gateway already uses the same Slack app token, onboarding and channels add slack warn before continuing in interactive mode and abort in non-interactive mode.
Use --force only when you intentionally want to move the Slack Socket Mode session to the new sandbox.
Microsoft Teams (experimental) uses the Bot Framework webhook path.
Create or configure a Teams app whose messaging endpoint is a public HTTPS URL ending in /api/messages, and point that URL at the host port NemoClaw forwards for the sandbox.
The default local webhook port is 3978; set MSTEAMS_PORT or TEAMS_PORT before onboarding or channels add teams when you need another port.
No two active Teams sandboxes can share the same local webhook port, so NemoClaw blocks the second enablement and asks you to choose a different MSTEAMS_PORT or stop the other sandbox.
Teams requires an app ID, client secret, and tenant ID.
Set MSTEAMS_APP_ID, MSTEAMS_APP_PASSWORD, and MSTEAMS_TENANT_ID, or use the aliases TEAMS_CLIENT_ID, TEAMS_CLIENT_SECRET, and TEAMS_TENANT_ID.
The client secret is stored as the <sandbox>-teams-bridge OpenShell provider and reaches the sandbox as an OpenShell placeholder, not as a raw value baked into the image.
Use TEAMS_ALLOWED_USERS or MSTEAMS_ALLOWED_USERS to list comma-separated Microsoft Entra ID object IDs that may direct-message the bot.
This direct-message allowlist does not restrict OpenClaw group or channel senders.
OpenClaw group and channel messages stay open by default, subject to mention mode.
Operators who need group or channel sender allowlisting can configure OpenClaw directly with channels.msteams.groupPolicy="allowlist" and channels.msteams.groupAllowFrom.
If groupPolicy="allowlist" is set without an effective group allowlist, OpenClaw denies group messages instead of treating the group as open.
For OpenClaw group and channel messages, TEAMS_REQUIRE_MENTION defaults to 1, so the bot replies only when mentioned.
Direct messages are unaffected by mention mode.
NemoClaw configures OpenClaw Teams with channels.msteams.streaming.mode: "off" so the channel uses final-message delivery while the upstream Teams streaming path can duplicate or collapse preview and final messages.
WeChat (experimental) delivers messages over Tencent’s iLink gateway through the upstream @tencent-weixin/openclaw-weixin plugin installed into WeChat-enabled OpenClaw sandbox images and the built-in Hermes iLink WeChat adapter.
The supported mode in this release is personal WeChat (bot_type=3).
WeChat Official Account and WeCom/Enterprise WeChat are not wired up.
Because the bot token only exists after a successful iLink QR handshake, NemoClaw runs the QR login on the host during nemohermes onboard.
You scan the QR with WeChat on your phone (Discover → Scan), confirm the login, and NemoClaw captures the token, accountId, baseUrl, and userId from the iLink response.
NemoClaw registers the token as the <sandbox>-wechat-bridge OpenShell provider and substitutes the openshell:resolve:env:WECHAT_BOT_TOKEN placeholder for it inside the sandbox, so the token never lands in the image or on disk inside the running container.
NemoClaw bakes the non-secret per-account metadata (WECHAT_ACCOUNT_ID, WECHAT_BASE_URL, WECHAT_USER_ID) into the sandbox image so the in-sandbox bridge can pre-seed the per-account context tokens without re-running the QR handshake.
WeChat is DM-only (allowIdsMode: "dm").
NemoClaw adds the operator who scanned the QR to WECHAT_ALLOWED_IDS automatically, and you can append more comma-separated WeChat user IDs through the same env var.
You can silence the host-side [wechat] diagnostic lines (poll status, IDC redirects, swallowed gateway errors) by exporting NEMOCLAW_WECHAT_QUIET=1 after the flow is stable in your environment.
Tencent’s iLink gateway is a third-party service. Review your organization’s terms-of-service, compliance, and data-residency constraints before enabling WeChat.
WhatsApp (experimental) Web does not use a host-side token or OpenShell credential provider. NemoClaw advertises WhatsApp for both OpenClaw and Hermes sandboxes, and each agent completes pairing with its own in-sandbox command. Pairing happens inside the sandbox after the rebuild completes and creates mutable session credentials there. Connect to the sandbox and then use the agent-specific pairing command to render the QR code in the terminal:
The sandbox generates and stores session credentials inside durable agent state (whatsapp for OpenClaw, platforms/whatsapp for Hermes), so they survive rebuilds without re-pairing.
This is the runtime tradeoff of enabling WhatsApp without a host bridge: a paired sandbox can use that WhatsApp account until you unpair it or clear the durable state.
NemoClaw cannot detect cross-sandbox WhatsApp conflicts the way it does for token-based channels.
Pair only one sandbox per WhatsApp account at a time.
Enable Channels During Onboarding
When the wizard reaches Messaging channels, it lists Telegram, Discord, Slack, WeChat, WhatsApp, and Microsoft Teams when the selected agent supports them. Press a channel number to toggle it on or off, then press Enter when done. If you select no channels, pressing Enter skips messaging setup. If a token-based channel token is not already in the environment or credential store, the wizard prompts for it and saves it.
If you enable WeChat (experimental), the wizard does not prompt for a paste token.
Instead, it renders a QR code in your terminal, polls Tencent’s iLink gateway, and captures the bot token after you scan the QR with WeChat on your phone.
The login has an eight-minute deadline, refreshes the QR up to three times on expiry, and follows iLink’s IDC redirects automatically.
Keep the terminal in the foreground until you see ✓ WeChat login confirmed.
WhatsApp (experimental) uses QR pairing instead of a host-side token, so the wizard does not prompt.
It prints pairing instructions and you complete the pairing inside the sandbox after rebuild.
NemoClaw also selects the matching network policy preset during policy setup so the channel can reach its provider API.
For non-interactive onboarding, set WHATSAPP_ALLOWED_IDS to a nonempty comma-separated sender list to select WhatsApp for either agent.
Hermes also uses these values as its WhatsApp sender allowlist.
For scripted setup, export the credentials and optional settings for the channels you want to enable before you run onboarding:
The placeholder values are quoted because angle brackets are shell metacharacters; the quotes keep the export from triggering a redirection or syntax error when you paste a real token in place.
Before you run onboarding or channel commands, make sure Docker is running and that your user can access the Docker socket, either through the docker group or by using the documented sudo workflow for your host.
This release does not support non-interactive WeChat configuration because the iLink QR handshake requires a human to scan the QR on a paired phone.
Run nemohermes onboard interactively when you want to enable WeChat.
Then run onboarding:
Complete the rest of the wizard so the blueprint can create OpenShell providers where needed, such as <sandbox>-telegram-bridge, <sandbox>-teams-bridge, or <sandbox>-wechat-bridge.
The wizard also writes channel configuration into the image through NEMOCLAW_MESSAGING_CHANNELS_B64 and starts the sandbox.
Add Channels After Onboarding
Run channel commands from the host, not from inside the sandbox.
Use channels list to see the supported channel names:
Add the channel you want:
channels add collects the inputs each channel needs.
It prompts for Telegram, Discord, Slack, and Microsoft Teams tokens and configuration, runs an interactive host-side QR scan for WeChat, and collects nothing for WhatsApp because pairing happens in-sandbox after rebuild.
It registers bridge providers with the OpenShell gateway when it captures tokens, records the channel in the sandbox registry, and asks whether to rebuild immediately.
The command accepts mixed-case input such as Telegram, then stores and prints the canonical lowercase channel name.
channels add requires the matching built-in network policy preset YAML to be present.
A missing or malformed preset YAML (no network_policies: section) aborts the command before any token prompt, registry write, or rebuild prompt, so the sandbox never advertises a channel without a matching network policy.
With the preset file in place, channels add applies it to the sandbox before the rebuild so the bridge has egress to its upstream API.
When the apply step fails after the registry write on a fresh add, NemoClaw attempts to roll back the bridge providers, the messagingChannels entry, and any staged environment credentials.
It then exits without prompting for a rebuild.
If any gateway-side step, such as provider detach or delete, fails, the rollback continues and prints a Rollback could not fully clean <surfaces> warning so you can clean up manually.
When the same failure happens on a re-add of an already-enabled channel, NemoClaw restores the prior messagingChannels entry, restores staged environment credentials when available, restores registry credential hashes, and attempts to re-upsert the prior bridge providers.
It flags gateway-providers as residual because the in-flight upsert can leave the gateway with the new token.
Verify the gateway bridge before relying on the channel.
Restore the preset YAML and re-run nemohermes <sandbox> channels add <channel>.
Choose the rebuild so the running sandbox image picks up the new channel.
For Telegram, Discord, Slack, and Microsoft Teams, channels add also checks the rebuilt runtime for the selected bridge and reports startup, credential, or missing-plugin warnings before returning.
If you need optional channel settings such as TELEGRAM_ALLOWED_IDS, TELEGRAM_REQUIRE_MENTION, TELEGRAM_GROUP_POLICY, DISCORD_SERVER_ID, DISCORD_USER_ID, DISCORD_REQUIRE_MENTION, SLACK_ALLOWED_USERS, SLACK_ALLOWED_CHANNELS, TEAMS_ALLOWED_USERS, MSTEAMS_PORT, or TEAMS_REQUIRE_MENTION, export them before the rebuild starts.
You can omit TELEGRAM_REQUIRE_MENTION and DISCORD_REQUIRE_MENTION when you want the default mention-only mode.
You can omit TELEGRAM_GROUP_POLICY when you want OpenClaw Telegram group access to stay open.
Telegram Bot API sendMessage calls prove outbound delivery from the bot; to test inbound agent replies, send a message from the Telegram client as an allowed user and inspect the gateway log for the inbound agent turn and outbound reply.
For a repeatable installed-runtime outbound check, run NEMOCLAW_RUN_LIVE_E2E=1 npx vitest run --project e2e-live test/e2e/live/messaging-providers.test.ts --silent=false --reporter=default with NVIDIA_INFERENCE_API_KEY set.
The lane imports the installed OpenClaw Telegram runtime-api.js, calls sendMessageTelegram through the OpenShell credential rewrite path against a host-side fake Telegram API, and verifies the captured send has no unresolved placeholder.
Set TELEGRAM_BOT_TOKEN_REAL and TELEGRAM_CHAT_ID_E2E only when you also want the optional real outbound send; this lane does not automate an interactive inbound reply.
If you defer the rebuild, apply the change later:
In non-interactive mode, set the required environment variables before running channels add.
Optional mention-mode settings that declare defaults are still written when unset.
Telegram mention mode defaults to 1; Discord mention mode defaults to 1 when DISCORD_SERVER_ID is set.
Missing credentials fail fast, and the command queues the change for a manual rebuild:
For Discord server access after onboarding, include the server settings when you add the channel and rebuild:
For Microsoft Teams, create the Teams app and public HTTPS endpoint first, then provide the app credentials and local webhook port when you add the channel:
After the rebuild starts the Teams webhook forward, route your public HTTPS endpoint to http://127.0.0.1:3978/api/messages or the port you selected with MSTEAMS_PORT.
If channels add teams reports that another sandbox already uses the same Teams webhook port, choose another MSTEAMS_PORT for one sandbox or stop and remove the conflicting sandbox.
channels add wechat
channels add wechat (experimental) follows the same shape as the other channels with two differences driven by the iLink QR handshake.
First, the command does not prompt for a paste token.
Instead, it renders a QR code in your terminal, polls Tencent’s iLink gateway, and captures both the bot token and the per-account metadata (accountId, baseUrl, userId) after you scan the QR with WeChat on your phone (Discover > Scan).
The login has an eight-minute deadline and refreshes the QR up to three times on expiry.
Keep the terminal in the foreground until you see ✓ WeChat login confirmed.
Second, the command requires an interactive terminal.
Non-interactive mode (NEMOCLAW_NON_INTERACTIVE=1) fails fast with a clear error because the QR handshake needs a paired phone.
If WECHAT_BOT_TOKEN is already cached for this sandbox (the operator onboarded with WeChat earlier), channels add wechat reuses the cached token and skips the QR scan to keep the upstream plugin’s existing iLink session intact.
Re-running QR would invalidate that session.
Use channels remove wechat first if you intend to acquire a fresh account.
Rotate or Remove Credentials
Running channels add for a channel that is already configured overwrites the stored tokens and registers the updated bridge provider.
For WeChat the cached-token short-circuit applies.
Refer to channels add wechat for how to acquire a fresh account.
Rebuild the sandbox after the update so the image reflects the current channel set.
To remove a channel and clear its stored credentials, run:
channels remove wechat clears the bot token, deletes the <sandbox>-wechat-bridge OpenShell provider, and drops wechat from the sandbox’s enabled-channel set.
The next rebuild produces an image without the WeChat channel block in openclaw.json and without the per-account state files under /sandbox/.openclaw/openclaw-weixin/.
For in-sandbox QR-paired channels (today: WhatsApp), channels remove destructively clears the in-sandbox session directory before the rebuild so the next rebuild does not restore stale auth files and reconnect the channel.
The cleanup targets /sandbox/.openclaw/<channel>/ for OpenClaw and /sandbox/.hermes/platforms/<channel>/ for Hermes.
The cleanup tries openshell sandbox exec and falls back to SSH if that does not produce the success sentinel.
If neither transport can reach a running sandbox for a QR-paired channel, the command exits non-zero and asks you to start the sandbox and re-run.
NemoClaw deliberately leaves the registry, policy preset, and session.policyPresets unchanged on that failure path, so a follow-up re-run completes the removal cleanly.
channels remove whatsapp clears the client-side Baileys session inside the sandbox.
It cannot deregister the linked device with WhatsApp’s servers because that requires an active Baileys connection to issue the logout RPC, and the command no longer has that connection after it removes the session files.
The phone account will continue to list the sandbox as a Linked Device until you remove it manually from your phone (Settings → Linked Devices → tap the entry → Log out) or until WhatsApp’s 14-day inactivity timeout expires.
Remove the entry from the phone if you plan to re-pair the same phone with a different sandbox.
Use channels stop when you want to pause a bridge without deleting credentials:
For WeChat specifically, channels stop wechat followed by a rebuild keeps the per-account state files under /sandbox/.hermes/ intact even though the bridge is no longer wired up in Hermes config.
A subsequent channels start wechat plus rebuild revives the bridge against the same iLink account without a fresh QR scan.
The bot token is held by the OpenShell provider across the stop/start cycle.
When channels start re-enables a channel, NemoClaw also reapplies the matching built-in network policy preset before rebuild.
If policy restoration fails, the command keeps the channel disabled and exits without rebuilding into a partially active state.
Telegram, Discord, Slack, and WeChat each allow only one active consumer per channel credential.
Multiple sandboxes can use the same channel type at the same time when each sandbox uses a distinct bot/app token (or a distinct WeChat iLink bot account).
For example, two Telegram sandboxes can DM the same TELEGRAM_ALLOWED_IDS account as long as they use different TELEGRAM_BOT_TOKEN values.
For WeChat, each sandbox must own a distinct iLink accountId (bot identity).
Running two sandboxes against the same WeChat account causes one of them to lose messages.
If you enable a messaging channel and another sandbox already uses the same token, onboarding prompts you to confirm before continuing in interactive mode and exits non-zero in non-interactive mode.
For Slack, NemoClaw checks both the bot token and the Socket Mode app token so duplicate Socket Mode sessions do not compete silently.
For Microsoft Teams, NemoClaw also checks the local webhook port because active Teams sandboxes cannot share the same forwarded port.
If NemoClaw only has legacy channel metadata and cannot compare credential hashes, it keeps the conservative warning.
Re-run channels add <channel> with the intended token to refresh the stored non-secret hash.
Before any rebuild, including one started by channels add or channels start, NemoClaw rechecks the staged messaging plan against other registered sandboxes.
A credential or channel-resource conflict aborts before backup or deletion and leaves the original sandbox registered and intact.
Resolve the conflict, then rerun the operation.
nemohermes status reports cross-sandbox overlaps so you can resolve duplicates before messages start dropping.
Stop Messaging Delivery
Use channels stop when you want to pause one bridge and keep the sandbox running.
Use nemohermes tunnel stop to stop host auxiliary services without stopping the supervisor-owned Hermes gateway, its agent-owned host forwards, or the managed OpenShell gateway port.
The deprecated full nemohermes stop command attempts to stop the host forwards and safely release an unshared OpenShell gateway port whose ownership NemoClaw can verify, while the Hermes gateway remains under sandbox supervision.
Full stop preserves a shared gateway and fails closed without releasing its port when ownership is ambiguous.
Use channels stop for an individual channel or stop the sandbox when you need to stop the supervisor-owned runtime.
Confirm Delivery
After the sandbox is running, send a message to the configured bot or app.
If delivery fails, use openshell term on the host, check gateway logs, and verify network policy allows the channel API.
Use the matching policy preset (telegram, discord, slack, wechat, whatsapp, or teams) or review Common Integration Policy Examples.
Tunnel Command
When the host has cloudflared, nemohermes tunnel start starts a cloudflared tunnel that can expose the forwarded Hermes endpoint with a public URL.
Set CLOUDFLARE_TUNNEL_TOKEN before running the command when you want to use a Cloudflare named tunnel instead of a generated quick-tunnel URL.
nemohermes tunnel stop stops the tunnel but leaves the supervisor-owned in-sandbox gateway and agent-owned host forwards running for the selected or default sandbox.
Related Topics
- Architecture for how providers, the gateway, and the sandbox fit together.
- Commands for
channels add,channels remove,channels start,channels stop,tunnel start,tunnel stop, andstatus.