Sókrates Wiki

WhatsApp Channel Integration and OpenClaw Pairing Process

3 min read

WhatsApp Channel Integration and OpenClaw Pairing Process

Summary

The process of integrating WhatsApp into the Sokrates stack involves configuring the OpenClaw gateway (the underlying engine for the Hermes Agent), accessing its web-based dashboard via SSH tunneling, and performing a QR-code-based pairing. This workflow includes managing NixOS configuration files, handling WhatsApp-side rate limits, and resolving authentication token mismatches between system-generated and state-persistent configurations.

Details

Configuration and Environment

The WhatsApp integration is managed through the OpenClaw Gateway, which runs as a service on the Sokrates NixOS appliances (specifically the sokrates-dev GMKtec unit). The gateway’s state and configuration are split between two locations:

  • NixOS Managed Config: Located at /etc/openclaw/openclaw.json. This file is generated via the openclaw.nix module and takes precedence for channel definitions.
  • State Directory: Located at /var/lib/sokrates/periphery. This directory stores persistent session data, credentials, and the openclaw.json state file.

To enable WhatsApp, the channel must be explicitly defined in the NixOS configuration block. Failure to include the whatsapp channel in the NixOS-generated config results in a “web login provider is not available” error, even if the channel appears in the state directory.

Dashboard Access via SSH Tunneling

The OpenClaw dashboard is served directly by the gateway on port 3000. Because the gateway binds to the loopback interface (127.0.0.1) for security, remote access requires an SSH tunnel.

A common conflict occurs when a local instance of OpenClaw is running on the developer’s machine (often on port 18789 or 3000), which can intercept dashboard requests. To access the remote GMKtec dashboard, the local process must be terminated and a tunnel established:

ssh -L 3000:localhost:3000 hakon@192.168.1.238

The dashboard requires an authentication token found in the gateway logs or the configuration file. If the gateway restarts, it may generate a new token, leading to “Token Mismatch” errors in the browser UI.

Pairing Workflow

  1. Initialization: The channel is enabled via the CLI or NixOS config.
  2. Login Command: Running openclaw channels login --channel whatsapp triggers the pairing sequence.
  3. QR Code Generation: A QR code is generated and can be viewed either as ASCII art in the terminal or as a high-resolution image in the OpenClaw Dashboard under the “Channels” tab.
  4. Linking: The user scans the QR code using “Linked Devices” within the WhatsApp mobile application.
  5. Verification: Once scanned, the dashboard should update the status to Configured: Yes and Linked: Yes.

Troubleshooting and Constraints

  • Rate Limiting (401 Unauthorized): WhatsApp imposes strict rate limits on pairing attempts. If the QR code is scanned too many times or the gateway attempts to reconnect too frequently after a failure, WhatsApp returns a 401 Unauthorized “Connection Failure” error. In this state, the gateway must be stopped for 15-20 minutes to allow the cooldown to clear.
  • Session Revocation: If connection attempts continue to fail during a rate-limit period, WhatsApp may revoke the session entirely, necessitating a full logout (openclaw channels logout --channel whatsapp) and a fresh pairing.
  • DM Policy: The default dmPolicy is often set to "pairing", meaning the first account to scan the QR code becomes the linked identity for the gateway.

Graph View