Summary

• Problem: Android now requires TLS for non-loopback gateway endpoints, but pairing setup code / QR generation could still emit remote plaintext ws:// URLs and Android surfaced vague follow-on errors.
• Why it matters: Tailscale and remote pairing flows looked supported, then failed late with generic QR or TLS-fingerprint errors instead of a usable setup path.
• What changed: pairing setup generation now fails closed on insecure remote ws://; Android setup/manual/QR validation shares one secure-endpoint rule and shows actionable remediation; TLS probe errors now explain whether no secure endpoint exists or the secure endpoint was unreachable; docs now point remote/mobile users to Tailscale Serve or wss://.
• What did NOT change (scope boundary): Android TLS hardening stays in place; no auth protocol or wire-format changes; localhost / emulator cleartext exceptions remain for local debugging only.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #
• Related #
• This PR fixes a bug or regression

Root Cause / Regression History (if applicable)

• Root cause: Android's non-loopback TLS requirement and the pairing/setup-code producer were out of sync. The producer still treated remote plaintext ws:// endpoints as valid mobile pairing targets.
• Missing detection / guardrail: no shared eligibility rule for mobile pairing endpoints, so setup-code generation, QR parsing, manual entry, and TLS probe failures each handled the same invalid state differently.
• Prior context (git blame, prior PR, issue, or refactor if known): Android remote TLS hardening landed separately from setup-code generation and docs, which still implied raw tailnet / remote ws:// could work.
• Why this regressed now: once Android enforced TLS for remote hosts, old QR/setup flows started producing setup codes that were structurally valid but operationally unusable.
• If unknown, what was ruled out: N/A.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/pairing/setup-code.test.ts, src/cli/qr-cli.test.ts, src/cli/qr-dashboard.integration.test.ts, apps/android/app/src/test/java/ai/openclaw/app/ui/GatewayConfigResolverTest.kt, apps/android/app/src/test/java/ai/openclaw/app/GatewayBootstrapAuthTest.kt
• Scenario the test should lock in: remote non-loopback plaintext ws:// must fail before mobile pairing; loopback / emulator cleartext still works; Android shows secure-endpoint guidance instead of generic parse/fingerprint errors.
• Why this is the smallest reliable guardrail: the bug lived at the seam between pairing payload generation and Android endpoint validation, so one side alone was not enough.
• Existing test that already covers this (if any): apps/android/app/src/test/java/ai/openclaw/app/node/ConnectionManagerTest.kt already covered the TLS-required policy for non-loopback endpoints.
• If no new test is added, why not: N/A.

User-visible / Behavior Changes

• openclaw qr now fails instead of emitting remote insecure mobile pairing setup codes.
• CLI and docs now describe the flow as mobile pairing, not iOS-only pairing.
• Android onboarding, connect-tab validation, and diagnostics now consistently say remote mobile nodes require wss:// or Tailscale Serve.
• Android first-time TLS probe failures now distinguish missing TLS from unreachable secure endpoint.

Diagram (if applicable)

Before:
[remote ws:// config] -> [QR/setup code generated] -> [Android scan/connect] -> [generic invalid QR or TLS fingerprint error]

After:
[remote ws:// config] -> [setup generation rejected with Tailscale Serve / wss:// fix]
[remote ws:// pasted/scanned on Android] -> [explicit insecure-remote guidance] -> [use secure endpoint]

Security Impact (required)

• New permissions/capabilities? (Yes/No) No
• Secrets/tokens handling changed? (Yes/No) No
• New/changed network calls? (Yes/No) No
• Command/tool execution surface changed? (Yes/No) Yes
• Data access scope changed? (Yes/No) No
• If any Yes, explain risk + mitigation: openclaw qr now rejects an insecure remote pairing target that used to encode. This narrows behavior in the secure direction and prevents generating broken mobile setup codes.

Repro + Verification

Environment

• OS: macOS
• Runtime/container: Node 22 + Bun/pnpm repo toolchain, Android Gradle unit tests
• Model/provider: N/A
• Integration/channel (if any): Android mobile pairing / gateway QR setup
• Relevant config (redacted): gateway.bind=custom|lan|tailnet, gateway.tailscale.mode=serve, optional gateway.remote.url / plugins.entries.device-pair.config.publicUrl

Steps

1. Configure a gateway that resolves to a remote non-loopback plaintext ws:// URL.
2. Run openclaw qr or scan/paste that setup target into Android.
3. Compare old generic failure vs new early rejection / explicit secure-endpoint guidance.

Expected

• Remote mobile pairing only proceeds with wss:// or Tailscale Serve.
• Plaintext remote ws:// is rejected early with actionable remediation.

Actual

• Verified: CLI rejects insecure remote mobile pairing URLs; Android parser/UX shows secure-endpoint guidance; valid secure / loopback flows still pass.

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

• Verified scenarios: targeted TS tests for setup-code + QR flows; Android unit tests for parser + bootstrap/TLS failure copy; full pnpm build; full pnpm check.
• Edge cases checked: localhost / 127.0.0.1 cleartext remains allowed; Android emulator alias remains allowed; secure remote wss:// remains allowed; Tailscale Serve path remains preferred.
• What you did not verify: full device/manual Android smoke on hardware; no end-to-end Tailscale Serve live run in this PR.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? (Yes/No) No
• Config/env changes? (Yes/No) No
• Migration needed? (Yes/No) Yes
• If yes, exact upgrade steps: if you were pairing Android/mobile against a raw remote ws:// endpoint, switch that flow to Tailscale Serve / Funnel or another wss:// gateway URL. Localhost and emulator cleartext flows do not change.

Risks and Mitigations

• Risk: operators using old raw tailnet/LAN mobile pairing flows now hit a hard CLI/app rejection.
  • Mitigation: the new errors point directly at gateway.tailscale.mode=serve, gateway.remote.url, or plugins.entries.device-pair.config.publicUrl with wss://, and the docs now match the runtime policy.