---
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/.openclaw/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
            }
        }
    }
}
```

**Config file locations (two separate OpenClaw configs on this box):**
- `/root/.openclaw/openclaw.json` — Hermes's own CLI config (this is where the WhatsApp channel config lives)
- `/root/.clawdbot-opsman/openclaw.json` — the `clawdbot-opsman` systemd service config (separate from the CLI config)

When enabling WhatsApp, set it in `/root/.openclaw/openclaw.json`. The service config at `/root/.clawdbot-opsman/openclaw.json` does not need to be changed for WhatsApp to work — they are independent.

**Restart the service:**
```bash
sudo systemctl restart clawdbot-opsman.service
```
Wait ~10s for the gateway to reconnect before testing.

### 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
sudo systemctl restart clawdbot-opsman.service
```
Wait ~10s for the gateway to reconnect before testing.

### 4. Airtable PAT — secure storage

If Hermes needs an Airtable PAT for write access to `appE43UvTyARe5oJs`:
- **Do NOT** put it in `/etc/environment` (world-readable, 644)
- **Do NOT** paste it into any chat, note, or vault file
- **Correct approach:** add it as a systemd override or environment file owned by root, chmod 600:

```bash
# Option A: systemctl edit (recommended)
sudo systemctl edit clawdbot-opsman.service
# Add under [Service]: Environment="AIRTABLE_API_KEY=patXXXXXXXXXXXX"

# Option B: environment file
sudo tee /etc/systemd/system/clawdbot-opsman.service.d/env <<'EOF'
[Service]
Environment="AIRTABLE_API_KEY=patXXXXXXXXXXXX"
EOF
sudo chmod 600 /etc/systemd/system/clawdbot-opsman.service.d/env
sudo systemctl daemon-reload
sudo systemctl restart clawdbot-opsman.service
```

- Scope the PAT to base `appE43UvTyARe5oJs` only, data + schema write
- Revoke and regenerate if it ever leaks

### 5. Gateway not responding — on-box diagnosis

If `openclaw channels status` shows "Gateway not reachable":
1. Check service is up: `systemctl status clawdbot-opsman.service`
2. Check WhatsApp session dir: `ls ~/.openclaw/credentials/` (should contain WhatsApp session files after QR link)
3. The gateway must be restarted **after** enabling WhatsApp in the config — a config change without restart has no effect
4. `openclaw doctor` can diagnose config file location mismatches and missing session stores

### 6. 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`
- "Gateway not reachable" = service is running but gateway process is down — check service logs: `journalctl -u clawdbot-opsman.service -n 50`

## 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.