openclaw - ✅(Solved) Fix docs: add WhatsApp 408 disconnect troubleshooting runbook [1 pull requests, 3 comments, 3 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
openclaw/openclaw#72262Fetched 2026-04-27 05:32:23
View on GitHub
Comments
3
Participants
3
Timeline
4
Reactions
0
Timeline (top)
commented ×3cross-referenced ×1

Error Message

WhatsApp default: enabled, configured, linked, running, disconnected, error:status=408 Request Time-out Connection was lost

Fix Action

Fixed

PR fix notes

PR #72489: docs(whatsapp): add 408 disconnect runbook (Fixes #72262)

Description (problem / solution / changelog)

Summary

Problem

WhatsApp troubleshooting did not explain the common status=408 Request Time-out disconnect loop.

Why it matters

Operators can see the exact 408 state in openclaw channels status --probe and logs, but the docs only had generic reconnect guidance.

What changed

  • Added a WhatsApp 408 troubleshooting accordion with the probe/log/doctor/gateway command ladder.
  • Documented wait-vs-relogin guidance, network/proxy checks, runtime-dependency checks, credential health, backup, logout, and login recovery.
  • Added a concise 408 row to the channel troubleshooting failure table.

What did NOT change

No runtime behavior or channel code changed.

Change Type

Documentation

Scope

Docs only:

  • docs/channels/whatsapp.md
  • docs/channels/troubleshooting.md

Linked Issue/PR

Closes #72262

User-visible / Behavior Changes

Users now have a direct runbook for WhatsApp status=408 Request Time-out disconnect loops.

Security Impact

No security-sensitive code changed. The runbook tells users to back up auth state before logout/relogin recovery.

Repro + Verification

Environment

  • macOS local checkout
  • Node v22.12.0
  • pnpm 10.33.0

Steps

  1. Read the WhatsApp troubleshooting docs.
  2. Check the channel troubleshooting WhatsApp failure table.
  3. Run docs lint.

Expected

The docs include concrete 408 guidance and pass Markdown lint.

Actual

The new 408 section and table row are present, and Markdown lint passes.

Evidence

  • pnpm lint:docs passed.
  • git diff --check passed.

pnpm format:docs:check could not run locally because oxfmt is not installed in this environment.

Human Verification

The diff was reviewed manually against the issue checklist.

Compatibility / Migration

No migration needed.

Failure Recovery

Docs-only change. Revert the commit if the runbook needs a different recovery path.

Risks and Mitigations

Risk: operators may apply logout/relogin too early. Mitigation: the docs first suggest waiting for transient reconnects and checking logs/network/runtime state before rebuilding auth.

Changed files

  • docs/channels/troubleshooting.md (modified, +6/-5)
  • docs/channels/whatsapp.md (modified, +49/-0)

Code Example

WhatsApp default: enabled, configured, linked, running, disconnected, error:status=408 Request Time-out Connection was lost

---

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

---

openclaw channels logout --channel whatsapp --account <id>
  openclaw channels login --channel whatsapp --account <id>
RAW_BUFFERClick to expand / collapse

Problem

The current WhatsApp/channel troubleshooting docs mention random disconnect/relogin loops, but the guidance is too shallow for the common Baileys/WhatsApp Web failure signature:

WhatsApp default: enabled, configured, linked, running, disconnected, error:status=408 Request Time-out Connection was lost

We hit repeated short disconnect/reconnect loops with status=408, and the docs did not explain how to distinguish network flakiness, stale Baileys auth state, runtime dependency issues, or service/runtime mismatches.

Suggested docs fix

Add a dedicated section to docs/channels/whatsapp.md and/or docs/channels/troubleshooting.md:

WhatsApp disconnected with status=408 Request Time-out

Include:

  • What 408 usually means for the WhatsApp Web/Baileys socket.
  • First checks:
    openclaw channels status --probe
    openclaw logs --follow
    openclaw doctor
    openclaw gateway status
  • How to decide between:
    • waiting for reconnect
    • re-login / rebuilding auth state
    • checking host DNS/proxy/connectivity
    • repairing bundled plugin runtime deps
  • What “verify credentials directory is healthy” means in concrete terms.
  • Safe recovery path:
    openclaw channels logout --channel whatsapp --account <id>
    openclaw channels login --channel whatsapp --account <id>
  • Warnings about preserving/backup of auth dirs where appropriate.

Why

channels status --probe already exposes the useful state, but the docs do not yet map that state to a deterministic operator runbook. This makes production WhatsApp support harder than it needs to be.

extent analysis

TL;DR

To address the WhatsApp disconnect/reconnect loops with status=408, update the troubleshooting documentation to include a dedicated section with step-by-step guidance on diagnosing and resolving the issue.

Guidance

  • Run the suggested commands to gather information: openclaw channels status --probe, openclaw logs --follow, openclaw doctor, and openclaw gateway status to understand the current state of the system.
  • Determine the cause of the disconnect by checking for network flakiness, stale Baileys auth state, runtime dependency issues, or service/runtime mismatches.
  • Consider the safe recovery path: openclaw channels logout --channel whatsapp --account <id> followed by openclaw channels login --channel whatsapp --account <id> to re-establish the connection.
  • Verify the credentials directory is healthy by checking its integrity and ensuring it is properly configured.

Example

No code snippet is provided as the issue focuses on documentation and command-line troubleshooting.

Notes

The provided solution assumes that the issue is related to the WhatsApp Web/Baileys socket and the status=408 error. However, the root cause may vary, and additional troubleshooting may be necessary.

Recommendation

Apply the suggested documentation fix to provide a clear and step-by-step guide for operators to diagnose and resolve the WhatsApp disconnect/reconnect loops with status=408, as it will improve the overall troubleshooting experience and reduce production support difficulties.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING