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 dashboard pairing and the gateway share /sandbox/.hermes/platforms/whatsapp/session.
After scanning a dashboard QR code, run nemohermes <sandbox> channels status --channel whatsapp to confirm that the shared session is available to the gateway.
If channels status reports credentials only under the legacy profiles/dashboard-home path, the sandbox has credentials from an image that wrote dashboard sessions to that path.
Rebuilding and pairing again writes new credentials to the shared path, but it leaves the legacy credentials in durable state, and sandbox startup treats that copy as migration input.
Clear every WhatsApp session path first with the supported removal command, then re-add the channel:
channels remove clears /sandbox/.hermes/platforms/whatsapp, the dashboard profile session at /sandbox/.hermes/profiles/dashboard-home/platforms/whatsapp/session, and the legacy migration source at /sandbox/.hermes/dashboard-home/platforms/whatsapp/session.
The sandbox must be running for that cleanup to succeed; channels remove refuses to proceed when it cannot reach the sandbox.
Pair again from the dashboard so the credentials are written to /sandbox/.hermes/platforms/whatsapp/session.
Rerun nemohermes <sandbox> channels status --channel whatsapp and confirm that the gateway session path holds the credentials and that the report no longer lists a profiles/dashboard-home session.
Protect Paired Session State
The sandbox stores mutable session credentials in durable platforms/whatsapp state for both dashboard pairing and the gateway.
The credentials survive rebuilds without re-pairing.
A sandbox that also holds legacy profiles/dashboard-home or dashboard-home credentials keeps both copies across a rebuild, because both paths are part of the durable state that a rebuild restores.
Run nemohermes <sandbox> channels remove whatsapp to clear every WhatsApp session path, then re-add the channel and pair again.
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 uses these values as its WhatsApp sender allowlist only when WHATSAPP_MODE=bot.
Refer to Reply to Other Senders.
Reply to Other Senders
channels add whatsapp asks which senders the sandbox answers:
Press Enter to keep self-chat, where the sandbox replies only to messages the paired account sends to itself and reads no allowlist.
Answer bot to reply to other senders; the sandbox then stops replying to that self-chat.
Pick bot when the sandbox has its own WhatsApp number and you write to it from a different phone, and keep self-chat when the sandbox shares your account and you write to yourself.
Complete the rebuild that channels add queues before the selected mode takes effect.
Hermes authorizes senders through its own pairing store in either mode, so the first message the sandbox receives is answered with a pairing code instead of a reply.
That applies to your own first message in self-chat too.
Approve it once inside the sandbox and the sender is recognized from then on:
The bot mode without an allowlist lets any sender start that pairing request.
In self-chat the bridge drops other senders before they reach the gateway, so only your own account can pair.
The Hermes bridge sends the code to the sender rather than to you.
Read it from that WhatsApp conversation on your paired phone, or have the sender share it with you.
hermes pairing list shows each waiting request by number and display name.
It shortens the code to a hash prefix, so use the list to judge whether a request is genuine rather than to read the code.
Approval runs inside the sandbox, so holding a code does not grant a sender access.
Supply an allowlist instead when the sandbox should answer a fixed set of senders without approving each one:
For individual sender IDs, use digits only, such as 15551234567, without a leading +.
The in-sandbox hermes whatsapp wizard also asks who may message the bot.
Answering it writes the allowlist outside the configuration NemoClaw seals, so the next gateway restart refuses to relaunch and directs you to rebuild.
Leave that question blank and set the allowlist through channels add instead.
Returning to self-chat stops replies to other senders, but it does not revoke a sender you already approved.
Revoke that sender when you no longer want them to reach the sandbox:
Sandboxes onboarded before NemoClaw stored the WhatsApp mode use self-chat after their next rebuild.
If such a sandbox must continue replying to other senders, run channels add whatsapp again and answer bot.
Verify the applied mode and allowlist:
Confirm that the output reports the intended mode and allowlist without a rendered-config mismatch.
Set WHATSAPP_ALLOWED_IDS='*' to let any sender reach the paired account without approving each one.
Continue with Enable Channels During Onboarding or Add Channels After Onboarding.