OpenClaw WhatsApp QR Expired: The Documented Recovery Path

An expired QR code can look like a lost WhatsApp account. It may be a smaller failure: the current link attempt is no longer active.

In the upstream WhatsApp login implementation checked on September 13, 2026, an active login has a three-minute freshness window. When that window has passed, OpenClaw clears the active login and returns a message telling the operator to generate a new QR. The login source code shows that behavior. The official WhatsApp channel guide lists the QR-only login command for an account that is not linked.

That gives the ordinary expiry a narrow recovery path: start a new login on the Gateway host, scan the newest QR from WhatsApp's Linked Devices screen, then check live channel status. Clearing saved credentials is a later branch for a different symptom.

The short answer

1. Use an interactive terminal on the host that runs the OpenClaw Gateway. The CLI reference specifically says to run channels login from a terminal on the Gateway host.
2. Request a new QR:

openclaw channels login --channel whatsapp

For a named account, keep the account selector consistent:

openclaw channels login --channel whatsapp --account work

3. On the phone, open WhatsApp, choose Linked Devices, choose Link a device, and scan the QR currently shown by OpenClaw.
4. If OpenClaw reports that the QR was refreshed, scan the latest code instead of returning to an older screenshot or terminal capture.
5. Check the live state after the login completes:

openclaw channels status --channel whatsapp --probe
openclaw gateway status

The CLI documentation says that a successful login asks a reachable local Gateway to start the account. In remote mode, the saved authentication may be retained while the remote runtime is not restarted, so the status result still matters.

What you need before retrying

This flow is interactive. A non-interactive shell is not a good place to wait for the QR prompt, and the documented CLI path is tied to the Gateway host. If the Gateway is not already running, the WhatsApp guide shows:

openclaw gateway

Leave that process or service running, then use another terminal on the same host for channels login. If a service already owns the Gateway, use the service's normal terminal or management path rather than starting a second copy on the same port.

You also need the phone that owns the WhatsApp account, access to the account's Linked Devices screen, and the correct OpenClaw account id. The WhatsApp guide uses default for the default account and supports named accounts such as work. If you have more than one account, do not run a recovery command for one id and a status or logout command for another.

There is one separate pairing step to keep in mind. The WhatsApp login QR links the OpenClaw account to WhatsApp. It does not automatically authorize every person who sends a direct message. In the default pairing policy, the first sender can create a DM access request that must be approved in Settings or with:

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

The current channel documentation says those DM requests expire after one hour and are capped at three pending requests per account. That code is not a replacement for the WhatsApp device-link QR.

Why the fresh QR matters

The three-minute value belongs to OpenClaw's active login operation. It is not a promise about how every WhatsApp client displays a code. The source uses ACTIVE_LOGIN_TTL_MS = 3 * 60_000, checks whether the login is still fresh, and clears a stale active login before returning the expiry message.

The same source also tracks QR versions. A login can receive a newer QR while the operator is waiting, and the wait path can return a message that the QR was refreshed. In practical terms, a code that was valid when it first appeared may be the wrong code by the time it is scanned.

This matters most on a remote or headless host. The official guide warns that terminal-rendered QRs, screenshots, and chat attachments can expire in transit. A static image can therefore fail even when the Gateway is healthy. Keep the phone ready before starting the login, use a live view of the current QR where possible, and avoid transporting the code through another messaging system.

That is an operational reading of the documentation, not a hands-on timing result. The safe assumption is simply that the QR is temporary and the newest displayed code wins.

Confirm that the account really recovered

A QR scan is an important event, but it is not the final operational check. Run:

openclaw channels status --channel whatsapp --probe
openclaw gateway status

The --probe form is the live channel check. A plain configuration view can tell you that an account exists without proving that its runtime connection is healthy. If the account is linked and running, the probe should give you a more useful result than a stale configuration summary.

If the login command finishes but the account does not start, read the message it returns. The CLI documentation says that startup can be skipped when another lifecycle operation owns the account, and it reports the reason rather than silently claiming that the runtime is active.

When a new QR still fails

No usable QR appears

If login fails before displaying a usable QR, do not treat that as the same problem as an expired code. The WhatsApp troubleshooting guide calls out status=408 Request Time-out and TLS socket disconnects as a separate path. Start with the documented checks:

openclaw channels status --probe
openclaw doctor
openclaw logs --follow
openclaw gateway status

For a 408 or TLS failure behind a proxy, the guide says that WhatsApp Web login uses the Gateway host's standard proxy environment, including HTTPS_PROXY, HTTP_PROXY, and their lowercase variants. Check that the Gateway process inherits the expected environment and that NO_PROXY does not match mmg.whatsapp.net. Fixing transport is more useful than repeatedly scanning new codes.

If OpenClaw reports that the WhatsApp plugin is missing, the current guide says that channels login can offer the install flow. The manual package path is:

openclaw plugins install @openclaw/whatsapp

After an install or plugin repair, follow the normal Gateway restart and status checks for your installation. Plugin availability is a setup problem, not evidence that the QR itself has expired.

The phone accepts the QR but the Control UI remains stuck

A closed upstream issue opened on April 8, 2026 reports a specific Control UI failure: the phone accepted the QR, but the interface stayed on a logging-in or couldn't-link state while the backend wait call completed successfully. The report is useful evidence of a possible UI handoff problem, not a universal diagnosis. It is documented in upstream issue #63019.

If the same symptom appears in your installed version, use the terminal path on the Gateway host first. The issue report records this version-dependent workaround after the QR has been scanned:

openclaw gateway call web.login.wait --params '{"timeoutMs":120000}' --timeout 130000 --json

Treat that command as an observed issue workaround, not as the baseline documented recovery for every OpenClaw release. Check channel status afterward, and avoid starting several overlapping login attempts while the first one may still be active.

The account was linked, then became disconnected

This is a different branch from a QR that expired before linking. The WhatsApp guide recommends checking the Gateway, channel probe, doctor output, and logs when a linked account enters a reconnect loop:

openclaw channels status --probe
openclaw doctor
openclaw logs --follow
openclaw gateway status

For an account that only needs a runtime restart, the CLI reference documents a non-destructive stop and start path that keeps the pairing and credentials. Both Gateway RPCs require operator.admin:

openclaw gateway call channels.stop --params '{"channel":"whatsapp","accountId":"<accountId>"}'
openclaw gateway call channels.start --params '{"channel":"whatsapp","accountId":"<accountId>"}'
openclaw channels status --channel whatsapp --probe

Use the same account id in both calls. The CLI documentation warns that a successful start request does not by itself prove provider connectivity, so keep the status and logs check.

If the reconnect loop continues after host connectivity and timing have been checked, the WhatsApp guide gives a more invasive relink sequence. Back up the exact account directory first:

cp -a ~/.openclaw/credentials/whatsapp/<accountId> ~/.openclaw/credentials/whatsapp/<accountId>.bak
openclaw channels logout --channel whatsapp --account <accountId>
openclaw channels login --channel whatsapp --account <accountId>

The current setup documentation identifies the default WhatsApp credential file as ~/.openclaw/credentials/whatsapp/<accountId>/creds.json. The CLI documentation says that logout clears the account's WhatsApp authentication state and, when the Gateway is reachable, stops that account's live listener before clearing it. It does not claim that provider-side credentials are revoked.

For a plain expired QR, there is no documented reason to begin by deleting the credential directory. The official guide places backup, logout, and relink under the persistent disconnect branch. That ordering is an editorial inference from the documented decision tree, but it keeps a transient login timeout separate from a saved-session reset.

The link disappears after a restart

The setup guide says that channel and provider state lives below ~/.openclaw/credentials/, with WhatsApp credentials under the account-specific path above. The WhatsApp guide also supports a custom authentication directory with --auth-dir.

If a container, service, or remote host is expected to survive restarts, a sensible proposed check is whether that same credential location is still present and mounted when the Gateway starts again. This is an operational inference from the documented storage map, not a claim about your deployment. If you intentionally use a custom auth directory, back up and relink that directory rather than assuming the default path applies.

A proposed verification test

This is a test plan for the operator, not a result reported by this article:

1. Run openclaw channels status --channel whatsapp --probe and record the account id and runtime state.
2. Send a harmless message from an authorized test contact. If the account uses pairing mode, approve the pending DM request first.
3. Watch openclaw logs --follow while the message is handled, then confirm delivery in WhatsApp itself.
4. If persistence matters, restart the Gateway through its normal service path and repeat the status check.

The WhatsApp documentation makes an important distinction here: a transcript row shows what the agent generated, not necessarily what WhatsApp accepted. Delivery is checked separately, and OpenClaw treats an automatic reply as sent only after the provider returns an outbound message id. A green transcript alone is therefore not enough evidence that recovery is complete.

Bottom line

When OpenClaw says the WhatsApp login QR expired, generate a new QR with openclaw channels login --channel whatsapp on the Gateway host and scan the latest code from WhatsApp's Linked Devices screen. Check the live channel probe afterward.

If no QR appears, investigate Gateway, proxy, TLS, and plugin errors. If the phone accepts the code but the Control UI stalls, the terminal path and the dated upstream issue report provide a bounded fallback. If an already linked account keeps disconnecting, preserve its auth directory, run the documented diagnostics, and only then use logout plus relink.

Sources

1. WhatsApp - OpenClaw: https://docs.openclaw.ai/channels/whatsapp. Accessed 2026-09-13. Publication date: not stated.
2. Channels - OpenClaw: https://docs.openclaw.ai/cli/channels. Accessed 2026-09-13. Publication date: not stated.
3. OpenClaw upstream WhatsApp channel documentation: https://github.com/openclaw/openclaw/blob/main/docs/channels/whatsapp.md. Accessed 2026-09-13. Publication date: not stated.
4. OpenClaw upstream setup documentation: https://github.com/openclaw/openclaw/blob/main/docs/start/setup.md. Accessed 2026-09-13. Publication date: not stated.
5. OpenClaw upstream WhatsApp login source: https://github.com/openclaw/openclaw/blob/main/extensions/whatsapp/src/login-qr.ts. Accessed 2026-09-13. Publication date: not stated.
6. Upstream issue #63019, Control UI relink handoff: https://github.com/openclaw/openclaw/issues/63019. Accessed 2026-09-13. Publication date: 2026-04-08.