Set Up WhatsApp

WhatsApp support is experimental and pairs inside the sandbox rather than through a host-side token or OpenShell credential provider.

Pair the Sandbox

Enable the channel during onboarding or with channels add whatsapp, rebuild the sandbox, then connect to it. Run the agent-specific pairing command to render the QR code:

$
hermes whatsapp

Hermes can pair from the Dashboard profile while the gateway reads the default platforms/whatsapp/session path. After scanning a dashboard QR code, run nemohermes <sandbox> channels status --channel whatsapp. If the report says dashboard-home has WhatsApp credentials, but the Hermes gateway session path is empty, point the gateway at the dashboard session with the supported config command:

$
nemohermes <sandbox> shields down --reason "repair Hermes WhatsApp session path"
$
nemohermes <sandbox> config set --key platforms.whatsapp.extra.session_path --value /sandbox/.hermes/profiles/dashboard-home/platforms/whatsapp/session --restart --config-accept-new-path
$
nemohermes <sandbox> shields up

Keep Shields down until config set finishes, then restore the restrictive posture with shields up. The --config-accept-new-path flag lets the command write the platforms.whatsapp.extra.session_path configuration key when the generated config does not already contain it. Dashboard pairing writes session credentials under profiles/dashboard-home; this bounded compatibility repair redirects the gateway to that session path while it still reads the default path otherwise. The repair stays documented until Hermes dashboard pairing state and gateway startup converge on one shared session path; NemoClaw can redirect the configured path but does not rewrite Hermes pairing state. Before removing the override, run nemohermes <sandbox> channels status --channel whatsapp after dashboard pairing and gateway startup and confirm the report no longer shows a dashboard-home session with an empty gateway session path. Remove the override only after Hermes uses one shared WhatsApp session path for dashboard pairing and gateway startup. Do not edit /sandbox/.hermes/.env or /sandbox/.hermes/config.yaml by hand. Manual edits can cause the Hermes config-integrity guard to reject restart with hash-mismatch. Supervisor quarantine happens after repeated relaunch failures or other integrity failures.

Protect Paired Session State

The sandbox stores mutable session credentials in durable platforms/whatsapp state for the gateway and profiles/dashboard-home/platforms/whatsapp state for Dashboard pairing. The credentials 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.

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. Use digits only, such as 15551234567. Do not include a leading +.

Continue with Enable Channels During Onboarding or Add Channels After Onboarding.