fix(messaging): let the operator choose the Hermes WhatsApp mode

[hunglp6d]

Summary

The WhatsApp channel manifest rendered WHATSAPP_MODE=bot as a constant, so neither Hermes mode was reachable and a freshly onboarded sandbox could not deliver a message. channels add whatsapp now asks the operator which senders the sandbox answers, and derives WHATSAPP_DM_POLICY from that answer and the allowlist. A blank answer keeps self-chat, so a paired sandbox works with nothing else configured. Answering bot without an allowlist renders pairing, so an unknown sender receives a pairing code the operator approves rather than being rejected outright. OpenClaw is unchanged.

Related Issue

Addresses part of #8312

Changes

• src/lib/messaging/channels/whatsapp/manifest.ts — add a mode input (envKey: WHATSAPP_MODE, statePath: whatsappConfig.mode, validValues: ["self-chat", "bot"], defaultValue: "self-chat") with an operator prompt; wire the shared common.configPrompt enroll hook limited to agents: ["hermes"]; render WHATSAPP_MODE={{whatsappConfig.mode}} and WHATSAPP_DM_POLICY={{whatsappConfig.dmPolicy}} instead of the constant.
• src/lib/messaging/channels/whatsapp/template-resolver.ts — resolve whatsappConfig.mode, following the telegramConfig.groupPolicy precedent, and add whatsappConfig.dmPolicy, which reads the mode as well as the allowlist. Remove the unreferenced allowedIds.whatsapp.dmPolicy case it replaces.
• src/lib/messaging/channels/whatsapp/rendered-config-parser.ts — list the mode beside the allowlist so channels status shows both. The mode decides whether an empty allowlist matters, and the existing WHATSAPP_ALLOWED_IDS: not set line carried no such context.
• docs/manage-sandboxes/set-up-whatsapp.mdx — rewrite the Hermes-only "Reply to Other Senders" section around the prompt, document approval and revocation, and qualify the existing allowlist sentence, which was written when bot was the only mode.
• Tests: resolver cases for every mode and allowlist combination, prompt behavior against the real manifest hook, a compiler-level assertion that an OpenClaw plan never reaches the prompt, rendered .env assertions in generate-hermes-config.test.ts, and the live E2E probe now requires the derived policy.

Why the DM policy is rendered rather than left unset

The two halves of the Hermes WhatsApp adapter disagree on this key's default: the Node bridge reads process.env.WHATSAPP_DM_POLICY || 'open' while the Python adapter reads os.getenv("WHATSAPP_DM_POLICY", "pairing"). Leaving the key unset therefore left the bridge enforcing an empty allowlist and rejecting every sender, while bot mode also stops replies to the paired account's own self-chat — a sandbox nobody could reach. Rendering the value is what makes bot usable without an allowlist. This compensates for an upstream default divergence on the pinned runtime; a Hermes-side report is planned separately.

The derivation is:

mode	allowlist	rendered WHATSAPP_DM_POLICY
self-chat	anything	line dropped — the bridge rejects non-self messages before it reads a policy
bot	populated	allowlist
bot	empty	pairing
unusable stored value	anything	line dropped — the mode fallback decides, so a stale registry entry cannot open the gateway

Scope

The prompt is limited to Hermes through the hook's agents list. WHATSAPP_MODE and WHATSAPP_DM_POLICY are rendered into the Hermes env, and the OpenClaw fragment carries no sender policy, so an OpenClaw operator would answer a question nothing consumes. WhatsApp and WeChat are the only two channels whose OpenClaw fragment omits allowFrom and dmPolicy, and git log -S"allowFrom" on this manifest is empty, so that omission is longstanding rather than lost here.

Two behavior changes worth calling out:

1. A sandbox already running bot renders self-chat after its next rebuild. Its persisted plan has no mode input, so the manifest default applies. A migration rule keyed on "allowlist present implies bot" was considered and rejected: the documented way to select WhatsApp non-interactively is to export WHATSAPP_ALLOWED_IDS, so that rule would silently place new sandboxes into the mode this issue is about. Affected operators re-run channels add whatsapp and answer bot.
2. Exporting WHATSAPP_MODE still selects the channel non-interactively for either agent, including OpenClaw, where the mode is not rendered. WHATSAPP_ALLOWED_IDS already behaves this way; inputs cannot be scoped per agent today (agents: exists on hooks, not on ChannelInputBaseSpec). An operator who exports the variable also skips the prompt, which keeps the previously documented non-interactive path working.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Quality Gates

• Tests added or updated for changed behavior
• Existing tests cover changed behavior — justification:
• Tests not applicable — justification:
• Docs updated for user-facing behavior changes
• Docs not applicable — justification:
• Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging)
• Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification: the recorded review at fix(messaging): let the operator choose the Hermes WhatsApp mode #8423 (comment) covered the revision that declared no prompt and rendered no DM policy. This revision adds an operator prompt and renders WHATSAPP_DM_POLICY, so re-review is requested.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Documentation Writer Review

• Documentation writer subagent reviewed the completed changes
• Result: docs-updated
• Evidence: docs/manage-sandboxes/set-up-whatsapp.mdx. The review returned no blocking findings and ten non-blocking suggestions; seven writing suggestions were applied, the wildcard-accuracy question was resolved by running the bridge's own parseAllowedUsers/matchesAllowedUser against * on a live sandbox, and the companion-page suggestion was left out because the reviewer scoped it outside this PR. npm run docs passed with 0 errors and 2 repository warnings. Two later corrections came from manual testing and are included: self-chat also issues a pairing code for the operator's own first message, and answering the in-sandbox hermes whatsapp allowlist prompt writes .env outside the sealed configuration.
• Agent: Claude Code

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit:
• Station profile/scenario:
• Result:
• Supporting evidence:

Verification

• PR description includes a Signed-off-by: line and every commit appears as Verified in GitHub
• Normal pre-commit, commit-msg, and pre-push hooks passed, or npm run validate:pr passed after refreshing origin/main when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — command/result or justification: npx vitest run --project cli src/lib/messaging/channels/whatsapp/template-resolver.test.ts src/lib/messaging/hooks/common/config-prompt.test.ts src/lib/messaging/compiler/manifest-compiler.test.ts — 50 passed; npx vitest run --project integration test/generate-hermes-config.test.ts — 55 passed; npx vitest run --project cli src/lib/onboard/messaging-channel-setup.test.ts src/lib/actions/sandbox/policy-channel-remove-flow.test.ts — 47 passed. Adding an enroll hook to this manifest broke four assertions in those last two files, which were updated: one pinned the previous "onboarding asks nothing" contract, and three built a planner without a hook registry.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result: not applicable; this change is scoped to one channel manifest, the shared config-prompt hook's manifest wiring, and their tests. npm run checks:repository passed. npx vitest run --project cli after npm run catalog:compile reports 1158 of 1161 files passing; the three failures need Python 3.11 for tomllib and are unrelated. npx vitest run --project integration after npm run build:cli reports 720 of 734 files passing; the eight failures need Python 3.11 for typing.NotRequired, a locally absent qrcode package, or an external terminology tool, and none reference this change.
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, or credentials committed
• npm run docs builds without warnings (doc changes only) — Found 0 errors and 2 warnings. Fern does not enumerate the two warnings in the build output; they are not attributable to this page from the build alone.
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

Live verification

Built from this branch on a CPU host (Hermes v0.19.0, OpenShell 0.0.99, docker driver) and exercised through the normal commands. Both modes were onboarded interactively so the prompt was answered rather than exported.

The prompt, and the default answer:

  self-chat replies only to messages the paired account sends to itself. bot replies to other
  senders and stops replying to that self-chat: an unknown sender receives a pairing code you
  approve with `hermes pairing approve whatsapp <code>`, unless you set WHATSAPP_ALLOWED_IDS to
  a fixed sender list before this command.
  WhatsApp reply mode [self-chat/bot; default: self-chat]:
  ✓ whatsapp WhatsApp reply mode saved

Pressing Enter, on sandbox wa-self:

$ nemoclaw wa-self exec -- grep -E '^WHATSAPP' /sandbox/.hermes/.env
WHATSAPP_ENABLED=true
WHATSAPP_MODE=self-chat

The policy line is absent, which is the intended result for self-chat. Hermes read the mode back as Mode: personal number (self-chat), QR pairing completed, and after gateway restart the bridge ran with --mode self-chat and the agent replied to a message the paired account sent to itself.

Answering bot, on sandbox wa-bot:

$ nemoclaw wa-bot exec -- grep -E '^WHATSAPP' /sandbox/.hermes/.env
WHATSAPP_ENABLED=true
WHATSAPP_MODE=bot
WHATSAPP_DM_POLICY=pairing

Hermes read that mode back as Mode: separate bot number. On the same sandbox, the in-sandbox hermes whatsapp wizard was then used to write an allowlist, which appended WHATSAPP_ALLOWED_USERS=* outside the configuration NemoClaw seals; the next gateway restart refused to relaunch on the integrity guard. rebuild --yes restored the rendered configuration and dropped the hand-written line, leaving exactly the three lines above. That confirms the rendered value is authoritative over an out-of-band edit, and the documented warning about that wizard prompt comes from this run.

An inbound message was not exchanged in bot mode on this host: the bridge did not spawn after that rebuild. The same code spawns the bridge in self-chat on the same branch, so the failure is downstream of the rendered value this change decides. Two known rebuild-time defects and the session-path behavior in #8229 are candidates; the diagnosis is separate from this PR.

---

Signed-off-by: Hung Le hple@nvidia.com

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Hermes WhatsApp mode is configurable through WHATSAPP_MODE. The default is self-chat; bot mode remains supported with allowlisted senders. Rendering, state merging, tests, onboarding, runtime checks, and documentation reflect the new behavior.

Changes

Hermes WhatsApp mode configuration

Layer / File(s)	Summary
Define WhatsApp mode configuration src/lib/messaging/channels/whatsapp/manifest.ts, src/lib/messaging/channels/whatsapp/rendered-config-parser.ts, src/lib/messaging/channels/*/metadata.test.ts, src/lib/messaging-channel-config.test.ts	The manifest defines self-chat and bot modes with a self-chat default. Hermes configuration visibility and key tests include WHATSAPP_MODE.
Render and merge configured mode src/lib/messaging/channels/whatsapp/template-resolver.ts, src/lib/messaging/channels/whatsapp/manifest.ts, src/lib/messaging/applier/host-state-applier.test.ts, test/messaging-plan-test-helper.ts	Template resolution accepts supported persisted modes and falls back to self-chat. Hermes renders the configured mode. Configuration merging replaces the stored WhatsApp mode. Test helpers propagate the mode to Hermes environment output.
Validate setup and document behavior src/lib/messaging/channels/whatsapp/template-resolver.test.ts, test/generate-hermes-config.test.ts, src/lib/onboard/messaging-channel-setup.test.ts, test/e2e/live/channels-stop-start-helpers.ts, docs/manage-sandboxes/set-up-whatsapp.mdx	Tests cover default, explicit, invalid, and persisted modes. Onboarding and runtime checks expect self-chat. Documentation describes bot-mode allowlists, sender IDs, wildcard usage, rebuilds, and gateway restarts.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Onboarding
  participant WhatsAppManifest
  participant HostState
  participant HermesConfig
  Onboarding->>WhatsAppManifest: seed mode self-chat
  Onboarding->>HostState: store mode and allowlist
  HostState->>HermesConfig: render WhatsApp settings
  HermesConfig-->>HermesConfig: use self-chat or bot mode

Loading

Possibly related PRs

• NVIDIA/NemoClaw#7718: Updates messaging onboarding plan handling and plan-derived configuration behavior.

Suggested labels: bug-fix, area: messaging, integration: whatsapp, integration: hermes

Suggested reviewers: senthilr-nv

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	The PR adds configurable Hermes mode and self-chat defaults but omits several #8312 requirements, including onboarding prompts, allowlist clearing, health diagnostics, and OpenClaw wiring.	Implement the remaining #8312 requirements or split them into linked follow-up changes with explicit scope.
Docstring Coverage	⚠️ Warning	Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Out of Scope Changes check	✅ Passed	The documentation, implementation, configuration tests, integration tests, and regression tests directly support the WhatsApp mode objective.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: allowing operators to choose the Hermes WhatsApp mode.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/whatsapp-mode-input

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-8423.docs.buildwithfern.com/nemoclaw

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in commit fdb182e in the fix/whatsapp-mode-in... branch remains at 96%, unchanged from commit 69f67a2 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit fdb182e in the fix/whatsapp-mode-in... branch remains at 82%, unchanged from commit fa2b577 in the main branch.

Show a code coverage summary of the most impacted files.

File	main fa2b577	fix/whatsapp-mode-in... fdb182e	+/-
src/lib/onboard...der/snapshot.ts	83%	75%	-8%
src/lib/agent/dashboard-ui.ts	98%	91%	-7%
src/lib/messagi...annel-config.ts	99%	95%	-4%
src/lib/onboard...press-resume.ts	81%	78%	-3%
src/lib/state/registry.ts	89%	87%	-2%
src/lib/onboard...-diagnostics.ts	96%	94%	-2%
src/lib/onboard...rtup/profile.ts	93%	93%	0%
src/lib/onboard...der/registry.ts	95%	96%	+1%
src/lib/state/o...d-checkpoint.ts	85%	88%	+3%
src/lib/agent/defs.ts	92%	95%	+3%

---

_{Updated August 10, 2026 07:52 UTC}

[github-actions]

PR Review Advisor — No blocking findings reported

Advisor assessment: No blocking advisor findings reported
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions

Model lanes

• GPT-5.6 Terra (primary): Completed · medium confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 2 warnings · 5 suggestions
• Model comparison: normalized findings differ; normalized terminology decisions differ; normalized E2E selections differ; Nemotron reported the same number of blockers, 2 more warnings, 5 more suggestions.

6 terminology differences from the second opinion

Advisory only. These are normalized differences from the primary terminology receipt.

• sender allowlist at docs/manage-sandboxes/set-up-whatsapp.mdx:73: selected only by the second-opinion lane as established.
• dmPolicy at src/lib/messaging/channels/whatsapp/template-resolver.ts:26: selected only by the second-opinion lane as justified.
• self-chat at src/lib/messaging/channels/whatsapp/manifest.ts:27: selected only by the second-opinion lane as define.
• bot at src/lib/messaging/channels/whatsapp/manifest.ts:27: selected only by the second-opinion lane as conflict.
• WHATSAPP_DM_POLICY at src/lib/messaging/channels/whatsapp/manifest.ts:89: selected only by the second-opinion lane as define.
• WhatsApp reply mode at src/lib/messaging/channels/whatsapp/manifest.ts:33: selected only by the second-opinion lane as define.

1 additional E2E selection from the second opinion

Advisory only. The primary lane did not select these E2E jobs or targets.

• whatsapp-qr-compact: The completed second-opinion lane identified E2E coverage that the primary lane omitted.

Second-opinion terminology and E2E selections are advisory. Live E2E does not run automatically for pull requests.

3 semantic terminology decisions

Terminology decisions are advisory. They affect the assessment only when a separate finding identifies concrete semantic impact.

• justified — self-chat at docs/manage-sandboxes/set-up-whatsapp.mdx:86: Keep `self-chat` as the literal mode name and define it with its bot-mode contrast.
• established — reply mode at src/lib/messaging/channels/whatsapp/manifest.ts:33: Keep `reply mode`; the prompt names the two supported values.
• established — pairing code at docs/manage-sandboxes/set-up-whatsapp.mdx:90: Keep `pairing code`; the approval command and sender flow define its use.

E2E guidance

Advisory only. A maintainer can dispatch the default E2E suite against this exact revision.

Recommended E2E: cloud-inference, cloud-onboard, managed-image-multiarch-startup, security-posture, channels-add-remove, channels-stop-start

Workflow run details

This automated review informs maintainers. Warnings and suggestions do not require a response. A maintainer decides whether to merge.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/manage-sandboxes/set-up-whatsapp.mdx`:
- Line 90: In the WhatsApp adapter sentence, replace the American-English
spelling “afterwards” with “afterward,” preserving the rest of the wording and
meaning.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 57bf1b12-3439-465a-9313-127f69b703af

📥 Commits

Reviewing files that changed from the base of the PR and between 2f29784 and 0c57526.

📒 Files selected for processing (12)

• docs/manage-sandboxes/set-up-whatsapp.mdx
• src/lib/messaging-channel-config.test.ts
• src/lib/messaging/applier/host-state-applier.test.ts
• src/lib/messaging/channels/metadata.test.ts
• src/lib/messaging/channels/whatsapp/manifest.ts
• src/lib/messaging/channels/whatsapp/rendered-config-parser.ts
• src/lib/messaging/channels/whatsapp/template-resolver.test.ts
• src/lib/messaging/channels/whatsapp/template-resolver.ts
• src/lib/onboard/messaging-channel-setup.test.ts
• test/e2e/live/channels-stop-start-helpers.ts
• test/generate-hermes-config.test.ts
• test/messaging-plan-test-helper.ts

[coderabbitai]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

[apurvvkumaria]

Maintainer security and gate audit completed for revision b0f04cde7.

Review area	Result	Evidence
Secrets and credentials	Pass	No secret material or credential handling changed. The new mode is ordinary non-secret configuration.
Input validation	Pass	The manifest accepts only self-chat or bot; the renderer independently falls back to self-chat for missing, empty, or invalid persisted values.
Authentication and authorization	Pass	The change does not widen sender access. Bot mode still relies on the existing sender allowlist, and an empty allowlist denies other senders.
Dependencies and supply chain	Pass	No dependencies, installers, workflows, or package metadata changed.
Error handling and observability	Pass with scope note	Channel status now reports the mode and allowlist. A richer warning for bot mode with no allowed senders remains part of the broader issue.
Cryptography	Not applicable	No cryptographic behavior changed.
Configuration and migration	Human decision required	Existing persisted WhatsApp plans have no mode, so a sandbox previously using bot behavior will render self-chat after rebuild. The PR documents this but intentionally does not migrate legacy state.
Tests	Pass	170 focused CLI tests and 54 Hermes config integration tests pass; CLI typecheck and the documentation build also pass.
Holistic review	Human decision required	#8312 also describes interactive prompting, clearing a stored allowlist, OpenClaw wiring, and stronger diagnostics. This PR intentionally implements a narrower Hermes configuration path.

No actionable security defect was found. Before approval, a maintainer should explicitly accept both the legacy-mode behavior and the narrower issue scope. I am changing the PR description from auto-closing #8312 to describing this as a partial implementation, so the remaining work is not closed accidentally.

GitHub Actions jobs are currently queued or cancelled during the reported service degradation. I have not rerun them.

[apurvvkumaria]

Documentation follow-up completed in revision ea42af0e9:

• documented that older persisted WhatsApp plans fall back to self-chat after rebuild and how to restore bot mode;
• added the channels status verification and acceptance criterion;
• added an explicit warning that the wildcard allowlist permits every sender.

npm run docs passes with 0 errors and the same 2 repository warnings. The documentation writer re-review now reports docs-updated, and the refreshed receipt validates successfully. The remaining maintainer decisions about legacy behavior and the narrower #8312 scope are unchanged.

[cv]

Cover explicit Hermes bot mode through the complete channel lifecycle. Seed WHATSAPP_MODE=bot with a nonempty sender allowlist, then assert the persisted input and rendered WHATSAPP_MODE=bot before stop, after rebuild, and after start. This mode changes sender authorization, so complete the nine-category security review for the final head. Refresh onto current main and rerun the managed-runtime activation and required checks after adding the lifecycle evidence.

[apurvvkumaria]

Addressed the requested Hermes bot lifecycle coverage in the current branch revision:

• The live lifecycle fixture seeds WHATSAPP_MODE=bot with a nonempty sender allowlist.
• Persisted mode and allowlist are asserted before stop, after stop/rebuild, after start, and after start/rebuild.
• Rendered Hermes configuration is checked before stop and after reactivation; Hermes is rebuilt after channel start before that assertion.
• The independent nine-category security review passed with no findings. The documentation-writer review also passed; the receipt now reflects this revision.
• Focused messaging, Hermes configuration, workflow-boundary, semantic-phase, type, title, source-shape, and documentation validation all passed.

Fresh CI hit an unrelated 5-second timeout in the untouched host-local-vllm-selection test. That file passes locally (3/3 in 1.59 seconds), and the failed-job rerun is underway.

The two product choices already called out in the description remain unchanged for maintainer direction: legacy plans without stored mode fall back to self-chat after rebuild, and this PR remains a narrower partial implementation of #8312.

[apurvvkumaria]

The rerun of CLI shard 6 passed. The prior host-local vLLM timeout is confirmed transient: the isolated test passed locally (3/3), the same CI shard passed on rerun, and every required check is now green. The remaining blockers are the two current human change requests concerning the legacy-plan fallback and the intended scope relative to #8312; those require product direction rather than another test or CI change.