Manage Messaging Channels

Use host-side channel commands to change a configured messaging channel.

Rotate Credentials

A successful channels add for a channel that is already configured updates the stored tokens and bridge provider. Provider replacement requires complete credentials and is refused when the provider is attached to another sandbox. If re-add fails after changing the provider, follow the channel-add recovery guidance for residual gateway-provider state. Rebuild the sandbox after a successful update so the image reflects the current channel set.

For WeChat, the cached-token shortcut applies. Remove WeChat first when you intend to acquire a fresh account through a new QR scan.

For Google Chat, re-add the channel and paste the replacement service-account JSON. On success, NemoClaw updates the gateway-side refresh material. The sandbox keeps only the OpenShell credential placeholder. OpenShell keeps refreshed access tokens at the gateway and substitutes them at approved egress boundaries.

Re-adding Google Chat prompts again for the project ID, complete Pub/Sub subscription name, and email sender allowlist. It does not create a public webhook endpoint.

For detailed token rotation procedures, refer to Credential Rotation.

Remove a Channel

Remove the channel and clear its stored credentials:

nemohermes my-assistant channels remove telegram
nemohermes my-assistant channels remove wechat
nemohermes my-assistant channels remove teams

channels remove wechat clears the bot token, deletes the <sandbox>-wechat-bridge provider, and removes wechat from the enabled-channel set. The next rebuild omits WeChat configuration and per-account state files.

channels remove googlechat disables the channel, removes its agent configuration and matching policy preset, and then detaches and deletes the <sandbox>-googlechat-bridge provider. If deletion fails after detachment, NemoClaw attempts to restore the provider attachment. If restoration also fails, the command names the provider and sandbox and warns that delivery may remain interrupted. The credentials remain, but the channel stays disabled with provider cleanup pending and its policy already removed. Resolve the gateway error, then rerun nemohermes <name> channels remove googlechat.

Hermes Google Chat has no dedicated host-side endpoint to stop. The next rebuild omits its Pub/Sub project, subscription, sender allowlist, and runtime adapter configuration.

For in-sandbox QR-paired channels such as WhatsApp, channels remove destructively clears the session directory before rebuild so stale auth files do not reconnect the channel.

The cleanup targets /sandbox/.hermes/platforms/<channel>/.

NemoClaw runs cleanup in running sandboxes through openshell sandbox exec. A failed, cancelled, or inconclusive native command does not retry through the local runtime provider or SSH. Cleanup succeeds only when the command exits successfully and returns its completion sentinel.

If the messaging plan or current OpenShell policy still records the channel and NemoClaw cannot confirm cleanup, the command exits nonzero with recovery guidance. It leaves the bridge provider, credentials, registry, and current OpenShell policy unchanged so you can fix the reported condition and retry removal.

channels remove whatsapp clears the client-side Baileys session but cannot deregister the linked device with WhatsApp’s servers after the local connection is gone. The phone continues to list the sandbox as a Linked Device until you remove it manually or WhatsApp’s 14-day inactivity timeout expires.

Remove the phone entry before pairing the same account with another sandbox.

Pause and Resume a Channel

Use channels stop when you want to pause a bridge without deleting credentials:

nemohermes my-assistant channels stop telegram
nemohermes my-assistant channels start telegram
nemohermes my-assistant channels stop wechat
nemohermes my-assistant channels start wechat

For WeChat, channels stop wechat followed by rebuild keeps the per-account state under /sandbox/.hermes/ even though the bridge is no longer wired into Hermes config. A later channels start wechat plus rebuild revives the bridge against the same iLink account without a fresh QR scan. The bot token remains in the OpenShell provider across the stop and start cycle.

Google Chat stop and start cycles also preserve the bridge provider and its gateway-side refresh material.

They preserve the project ID, Pub/Sub subscription name, and email sender allowlist. The next rebuild reuses the bridge provider without requiring the service-account JSON again. Hermes Google Chat does not use the dedicated webhook endpoint or nemohermes tunnel commands.

When channels start re-enables a channel, NemoClaw records the channel as enabled in the messaging plan. The rebuild attaches the existing bridge provider before applying its matching built-in policy preset to the replacement sandbox. While a channel remains stopped, the rebuild omits its runtime configuration, token upsert, and channel startup effects. Generic providers and refresh bridges remain detached.

The rebuild also omits the stopped channel’s inactive built-in messaging preset from the command-time plan. The messaging plan does not persist policy references; rebuild starts from the current OpenShell policy and derives any requested channel change from current manifests. For stopped Hermes Discord, a preserved custom credential-bound policy requires the exact validated static provider, so the rebuild retains and attaches only that provider without starting Discord or recreating its credentials. A missing or incompatible required provider stops the rebuild before the replacement can use the policy. If the command queues the change without rebuilding, the running sandbox keeps its existing bridge and network policy until you rebuild it.

Avoid Cross-Sandbox Conflicts

Use distinct credentials and resources for each active messaging sandbox. Follow these channel-specific rules:

• Use a distinct iLink accountId for each WeChat sandbox.
• Run only one active Slack sandbox on each OpenShell gateway.
• Use distinct bot and Socket Mode app tokens across OpenShell gateways.
• Use a local webhook port that no unrelated process or active Microsoft Teams sandbox uses.

When you onboard, rebuild, or add a channel, the command aborts on a conflict or an incomplete required check within the selected OpenShell gateway’s sandbox registry. Legacy entries without credential hashes count as incomplete. An unreadable messaging registry also causes onboarding and rebuild to abort. Onboarding and rebuild have no conflict override.

For channels add only, --force overrides conflict and incomplete-check aborts. Use it only when you accept the duplicate-consumer or shared-resource risk. Rerun channels add <channel> with the intended token to refresh stored non-secret identity metadata.

For Microsoft Teams, an unrelated host listener causes channels add to abort before it changes the channel unless you use --force. A direct OpenShell forward can keep the selected port only when NemoClaw verifies its listener belongs to the current sandbox and gateway. A stale forward record alone is not accepted. A port probe that cannot verify availability also aborts. Free an unrelated listener, or set MSTEAMS_PORT or TEAMS_PORT to a free port.

Before a rebuild, NemoClaw checks the messaging plan before backup and checks it again after MCP preparation, before deletion. A registry or Microsoft Teams host-port conflict stops rebuild before sandbox deletion. NemoClaw attempts to restore MCP changes made during preparation. Resolve the conflict and any reported MCP recovery failure, then rerun the operation. nemohermes status reports cross-sandbox overlaps within the selected OpenShell gateway’s sandbox registry.

After recreation, NemoClaw verifies the replacement’s required webhook forward. If verification fails, rebuild exits nonzero without deleting the replacement sandbox. NemoClaw retains existing backup and recovery files. Correct the reported forwarding error, then run nemohermes <sandbox> rebuild --yes to retry recovery.

If an older registry entry lacks lifecycle identity, channel provider operations restore missing fields only from a matching completed onboarding receipt. The receipt must identify the same live sandbox on the recorded gateway. Missing proof or conflicting identity stops the operation; --force does not override this check. When no matching receipt exists, run nemohermes <sandbox> rebuild --yes to record its lifecycle identity, then rerun the channel command.

Stop All Delivery

Use channels stop for an individual bridge or stop the sandbox when you need to stop the complete supervised runtime.

nemohermes tunnel stop stops the dashboard tunnel services that nemohermes tunnel start created without stopping the supervisor-owned Hermes gateway, agent-owned host forwards, or managed OpenShell gateway port. The deprecated full nemohermes stop command attempts to stop host forwards and safely release an unshared OpenShell gateway port 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.

Related Topics

• Add Channels After Onboarding to configure another channel.
• Run Sandboxes for tunnel and sandbox stop or start behavior.
• Troubleshooting for channel delivery failures.
• Commands for channel command flags.