Summary

channels login QR code needs an image output option or HTTP endpoint — Unicode terminal rendering is unscannable on headless/SSH servers.

Problem to solve

On headless servers accessed via SSH, the WhatsApp QR code is impossible to scan:

1. QR renders as 59-column Unicode block characters (▄▀█) — wraps or truncates in narrow/SSH terminals
2. No --output qr.png flag to save as an image file
3. No HTTP endpoint to serve the QR (e.g. GET /channels/whatsapp/qr.png)
4. The UI's "Show QR" button doesn't work due to the credential reload bug (WhatsApp proactive send fails while inbound/auto-reply works (2026.3.12) #45576)
5. QR expires in ~20 seconds — too fast for SCP transfer

This completely blocks WhatsApp setup on any headless server without a wide local terminal.

Proposed solution

Any of the following:

• openclaw channels login --output /path/to/qr.png to save QR as an image file
• Serve QR via the existing gateway HTTP server (e.g. GET http://127.0.0.1:18789/channels/whatsapp/qr.png) with auto-refresh
• Support WhatsApp phone number pairing code as an alternative to QR scanning

Alternatives considered

• SCP the terminal output and parse offline — QR expires in ~20s, too slow
• Widen the SSH terminal — does not reliably fix rendering across all terminal emulators
• Custom Python script to parse Unicode QR → PNG and serve via HTTP — this is what I had to build as a workaround; took significant effort and shouldn't be necessary

Impact

• Affected users: Anyone running OpenClaw on a headless server (VPS, cloud VM, Raspberry Pi) accessed via SSH — a very common deployment
• Severity: Blocks workflow — cannot complete WhatsApp setup at all without a workaround
• Frequency: Every time WhatsApp needs to be linked or re-linked
• Consequence: Hours of debugging and custom scripting to work around a setup step that should take 30 seconds

Evidence/examples

Full debug report documenting the issue: https://gist.github.com/maxxie114/970c9a3407dfc0a3b83f0246663a3eaa

Workaround required: a Python script using Pillow to parse the Unicode QR from stdout, convert to PNG, and serve on a separate HTTP port through an SSH tunnel.

Additional information

• OpenClaw 2026.3.12
• DigitalOcean droplet, accessed only via SSH tunnel
• Gateway bound to loopback (127.0.0.1:18789)