Summary

The Android app can show authentication needed during gateway setup/reconnect, but that message does not tell the user which recovery path applies: fresh QR scan, pending node approval, stale stored credential, or app storage reset.

What happened

During Android gateway setup/reconnection, the app reached the gateway but displayed an authentication-needed state. From the gateway side, different underlying states were observed during the same troubleshooting session:

• expired/stale bootstrap token
• node approval/reapproval pending
• app credential missing or stale
• Android camera permission denied, preventing QR scan

The app did not make those states distinguishable to the user.

Expected behavior

The setup/authentication screen should show the specific cause and next action, such as:

• Setup code expired. Scan a fresh setup QR.
• Gateway approval pending. On the gateway, run: openclaw nodes approve <id>
• Saved authentication is invalid. Re-authenticate or reset this gateway connection.
• Camera permission is required to scan setup codes.

If the app can see a gateway-provided pending approval ID or reason code, it should render that directly.

Actual behavior

The app exposed a generic authentication-needed state. The user had to rely on gateway CLI probing to determine whether the problem was QR/bootstrap expiry, node approval, stale app credential, or local Android permission state.

Why this matters

All of these failures look similar to a user but require different fixes. A generic authentication-needed state makes normal recovery difficult and leads users to try unrelated actions.

Environment

• OpenClaw gateway: 2026.6.10
• Android app/node: Samsung Galaxy S25
• Gateway bind: lan, setup URL advertised as ws://192.168.0.180:18789

Related

Adjacent to #98038, but this report is for the Android app's user-facing recovery messaging rather than iOS token persistence.