---
name: whatsapp-bridge-setup
description: Configure OpenClaw WhatsApp bridge for Hermes with read-only group policy and error routing to ops DM.
category: opsman
---
# WhatsApp Bridge Setup for Hermes

## Context
WhatsApp bridge connects Hermes (the foreman/site assistant) to a WhatsApp group for site foremen to send tool check-in/check-out photos and messages. Bridged via OpenClaw runtime on the VPS.

## Known Issues (from Rocky's experience, 29 Apr 2026)
- Hermes was auto-replying to everything in the group → must set to READ-ONLY / @mention-only
- Error messages were being broadcast to the group → errors must route to ops DM only
- When Hermes was in the group, it was answering questions it shouldn't

## Setup Steps

### 1. Link WhatsApp (QR Scan)

From the VPS terminal:
```bash
openclaw channels login --channel whatsapp
```
A QR code will display. Scan it with the WhatsApp app (same process as WhatsApp Web).

This is a ONE-TIME setup per WhatsApp number. Once linked, the session persists.

### 2. Configure openclaw.json

After linking, edit `/root/.clawdbot-opsman/openclaw.json` to set:

```json
"channels": {
    "whatsapp": {
        "enabled": true,
        "dmPolicy": "allowlist",
        "allowFrom": [7377499346],
        "groupPolicy": "allowlist",
        "groups": {
            "LFCS Site Group": {
                "readOnly": true,
                "silent": true,
                "errorsToOps": true
            }
        }
    }
}
```

### Key Config Flags

| Flag | Value | Meaning |
|------|-------|---------|
| `dmPolicy` | `allowlist` | Only accept DMs from allowlisted numbers |
| `groupPolicy` | `allowlist` | Only respond in allowlisted groups |
| `readOnly` | `true` | Don't auto-reply in groups |
| `silent` | `true` | Suppress routine confirmations in group |
| `errorsToOps` | `true` | Send errors to ops DM, not group |

### 3. Restart the service

```bash
systemctl restart clawdbot-opsman.service
```

### 4. Test

- Send a DM from Rocky's WhatsApp → should respond
- Post in group without @mention → should stay silent
- @mention in group → should reply briefly
- Trigger an error → should come to ops DM, not group

## Troubleshooting

- If Hermes still replies in group: verify `silent: true` is set per group
- If errors still go to group: add `"errorBroadcast": false` to gateway config
- WhatsApp session expires: re-run `openclaw channels login --channel whatsapp`
- To check WhatsApp status: `openclaw channels status`

## Important Note
Hermes is the agent. OpenClaw is the runtime/gateway that connects Hermes to WhatsApp. When troubleshooting, you interact with OpenClaw CLI (`openclaw channels ...`) but Hermes is the intelligence that reads and writes messages.