fix(ios): harden gateway pairing setup

Harden iOS gateway setup-code pairing by rejecting non-loopback plaintext ws:// setup URLs before bootstrap token issuance, consolidating iOS setup parsing, and adding QR scan support from Settings. Verification: - pnpm test extensions/device-pair/index.test.ts - swift test --package-path apps/shared/OpenClawKit --filter DeepLinksSecurityTests - XcodeBuildMCP OpenClawLogicTests/DeepLinkParserTests - targeted SwiftLint for touched iOS/OpenClawKit files - pnpm exec oxfmt --check --threads=1 extensions/device-pair/index.ts extensions/device-pair/index.test.ts - git diff --check origin/main...HEAD - GitHub PR checks green on 58e5e60a5c
2026-05-06 15:18:58 +00:00 · 2026-05-04 02:11:47 -05:00
parent 5fe8cde28f
commit b2efd19648
15 changed files with 556 additions and 188 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -66,6 +66,7 @@ Docs: https://docs.openclaw.ai
 - Release/beta smoke: resolve the dispatched Telegram beta E2E run from `gh run list` when `gh workflow run` returns no run URL, so the maintainer helper does not fail immediately after dispatch. Thanks @vincentkoc.
 - Media/images: keep HEIC/HEIF attachments fail-closed when optional Sharp conversion is unavailable instead of sending originals that still need conversion. Thanks @vincentkoc.
 - Google Meet: fork the caller's current agent transcript into agent-mode meeting consultant sessions, so Meet replies inherit the context from the tool call that joined the meeting.
+- iOS/mobile pairing: reject non-loopback `ws://` setup URLs before QR/setup-code issuance and let the iOS Gateway settings screen scan QR codes or paste full setup-code messages. Thanks @BunsDev.
 - Telegram/streaming: sanitize tool-progress draft preview backticks before shared compaction, so long backtick-heavy progress text still renders inside the safe code-formatted preview instead of collapsing to an ellipsis.
 - UI/chat: remove the unsupported `line-clamp` declaration from the chat queue text rule to eliminate Firefox console noise without changing visible truncation behavior. Thanks @ZanderH-code.
 - Agents/Pi: suppress persistence for synthetic mid-turn overflow continuation prompts, so transcript-retry recovery does not write the "continue from transcript" prompt as a new user turn. Thanks @vincentkoc.
--- a/apps/ios/CHANGELOG.md
+++ b/apps/ios/CHANGELOG.md
@@ -1,5 +1,11 @@
 # OpenClaw iOS Changelog

+## 2026.5.4 - 2026-05-04
+
+Maintenance update for the current OpenClaw development release.
+
+- Gateway pairing now supports scanning QR codes from Settings and accepts full copied setup-code messages while keeping non-loopback `ws://` setup links blocked.
+
 ## 2026.5.3 - 2026-05-03

 Maintenance update for the current OpenClaw development release.
--- a/apps/ios/README.md
+++ b/apps/ios/README.md
@@ -241,7 +241,7 @@ gateway can only send pushes for iOS devices that paired with that gateway.

 ## What Works Now (Concrete)

- Pairing via setup code flow (`/pair` then `/pair approve` in Telegram).
+- Pairing via QR or setup code flow (`/pair qr` or `/pair`, then `/pair approve` in Telegram).
 - Gateway connection via discovery or manual host/port with TLS fingerprint trust prompt.
 - Chat + Talk surfaces through the operator gateway session.
 - iPhone node commands in foreground: camera snap/clip, canvas present/navigate/eval/snapshot, screen record, location, contacts, calendar, reminders, photos, motion, local notifications.
--- a/apps/ios/Sources/Gateway/GatewaySetupCode.swift
+++ b/apps/ios/Sources/Gateway/GatewaySetupCode.swift
@@ -1,42 +0,0 @@
-import Foundation
-
-struct GatewaySetupPayload: Codable {
-    var url: String?
-    var host: String?
-    var port: Int?
-    var tls: Bool?
-    var bootstrapToken: String?
-    var token: String?
-    var password: String?
-}
-
-enum GatewaySetupCode {
-    static func decode(raw: String) -> GatewaySetupPayload? {
-        if let payload = decodeFromJSON(raw) {
-            return payload
-        }
-        if let decoded = decodeBase64Payload(raw),
-           let payload = decodeFromJSON(decoded)
-        {
-            return payload
-        }
-        return nil
-    }
-
-    private static func decodeFromJSON(_ json: String) -> GatewaySetupPayload? {
-        guard let data = json.data(using: .utf8) else { return nil }
-        return try? JSONDecoder().decode(GatewaySetupPayload.self, from: data)
-    }
-
-    private static func decodeBase64Payload(_ raw: String) -> String? {
-        let trimmed = raw.trimmingCharacters(in: .whitespacesAndNewlines)
-        guard !trimmed.isEmpty else { return nil }
-        let normalized = trimmed
-            .replacingOccurrences(of: "-", with: "+")
-            .replacingOccurrences(of: "_", with: "/")
-        let padding = normalized.count % 4
-        let padded = padding == 0 ? normalized : normalized + String(repeating: "=", count: 4 - padding)
-        guard let data = Data(base64Encoded: padded) else { return nil }
-        return String(data: data, encoding: .utf8)
-    }
-}
--- a/apps/ios/Sources/Onboarding/GatewayOnboardingView.swift
+++ b/apps/ios/Sources/Onboarding/GatewayOnboardingView.swift
@@ -248,38 +248,23 @@ private struct ManualEntryStep: View {
            return
        }

-        guard let payload = GatewaySetupCode.decode(raw: raw) else {
-            self.setupStatusText = "Setup code not recognized."
+        guard let link = GatewayConnectDeepLink.fromSetupInput(raw) else {
+            self.setupStatusText = "Setup code not recognized or uses an insecure ws:// gateway URL."
            return
        }

-        if let urlString = payload.url, let url = URL(string: urlString) {
-            self.applyURL(url)
-        } else if let host = payload.host, !host.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
-            self.manualHost = host.trimmingCharacters(in: .whitespacesAndNewlines)
-            if let port = payload.port {
-                self.manualPortText = String(port)
-            } else {
-                self.manualPortText = ""
-            }
-            if let tls = payload.tls {
-                self.manualUseTLS = tls
-            }
-        } else if let url = URL(string: raw), url.scheme != nil {
-            self.applyURL(url)
-        } else {
-            self.setupStatusText = "Setup code missing URL or host."
-            return
-        }
+        self.manualHost = link.host
+        self.manualPortText = String(link.port)
+        self.manualUseTLS = link.tls

-        if let token = payload.token, !token.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+        if let token = link.token, !token.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
            self.manualToken = token.trimmingCharacters(in: .whitespacesAndNewlines)
-        } else if payload.bootstrapToken?.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty == false {
+        } else if link.bootstrapToken?.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty == false {
            self.manualToken = ""
        }
-        if let password = payload.password, !password.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+        if let password = link.password, !password.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
            self.manualPassword = password.trimmingCharacters(in: .whitespacesAndNewlines)
-        } else if payload.bootstrapToken?.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty == false {
+        } else if link.bootstrapToken?.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty == false {
            self.manualPassword = ""
        }

@@ -287,30 +272,12 @@ private struct ManualEntryStep: View {
            .trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
        if !trimmedInstanceId.isEmpty {
            let trimmedBootstrapToken =
-                payload.bootstrapToken?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+                link.bootstrapToken?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
            GatewaySettingsStore.saveGatewayBootstrapToken(trimmedBootstrapToken, instanceId: trimmedInstanceId)
        }

        self.setupStatusText = "Setup code applied."
    }
-
-    private func applyURL(_ url: URL) {
-        guard let host = url.host, !host.isEmpty else { return }
-        self.manualHost = host
-        if let port = url.port {
-            self.manualPortText = String(port)
-        } else {
-            self.manualPortText = ""
-        }
-        let scheme = (url.scheme ?? "").lowercased()
-        if scheme == "wss" || scheme == "https" {
-            self.manualUseTLS = true
-        } else if scheme == "ws" || scheme == "http" {
-            self.manualUseTLS = false
-        }
-    }
-
-    // (GatewaySetupCode) decode raw setup codes.
 }

@MainActor
--- a/apps/ios/Sources/Onboarding/OnboardingWizardView.swift
+++ b/apps/ios/Sources/Onboarding/OnboardingWizardView.swift
@@ -203,14 +203,7 @@ struct OnboardingWizardView: View {
                            return
                        }
                        if let message = self.detectQRCode(from: data) {
-                            if let link = GatewayConnectDeepLink.fromSetupCode(message) {
-                                self.handleScannedLink(link)
-                                return
-                            }
-                            if let url = URL(string: message),
-                               let route = DeepLinkParser.parse(url),
-                               case let .gateway(link) = route
-                            {
+                            if let link = GatewayConnectDeepLink.fromSetupInput(message) {
                                self.handleScannedLink(link)
                                return
                            }
--- a/apps/ios/Sources/Onboarding/QRScannerView.swift
+++ b/apps/ios/Sources/Onboarding/QRScannerView.swift
@@ -65,20 +65,11 @@ struct QRScannerView: UIViewControllerRepresentable {
                      let payload = barcode.payloadStringValue
                else { continue }

-                // Try setup code format first (base64url JSON from /pair qr).
-                if let link = GatewayConnectDeepLink.fromSetupCode(payload) {
+                if let link = GatewayConnectDeepLink.fromSetupInput(payload) {
                    self.handled = true
-                    self.parent.onGatewayLink(link)
-                    return
-                }
-
-                // Fall back to deep link URL format (openclaw://gateway?...).
-                if let url = URL(string: payload),
-                   let route = DeepLinkParser.parse(url),
-                   case let .gateway(link) = route
-                {
-                    self.handled = true
-                    self.parent.onGatewayLink(link)
+                    Task { @MainActor in
+                        self.parent.onGatewayLink(link)
+                    }
                    return
                }
            }
--- a/apps/ios/Sources/Settings/SettingsTab.swift
+++ b/apps/ios/Sources/Settings/SettingsTab.swift
@@ -49,6 +49,8 @@ struct SettingsTab: View {
    @State private var defaultShareInstruction: String = ""
    @AppStorage("gateway.setupCode") private var setupCode: String = ""
    @State private var setupStatusText: String?
+    @State private var showQRScanner: Bool = false
+    @State private var scannerError: String?
    @State private var manualGatewayPortText: String = ""
    @State private var gatewayExpanded: Bool = true
    @State private var selectedAgentPickerId: String = ""
@@ -98,6 +100,13 @@ struct SettingsTab: View {
                                .textInputAutocapitalization(.never)
                                .autocorrectionDisabled()

+                            Button {
+                                self.openGatewayQRScanner()
+                            } label: {
+                                Label("Scan QR Code", systemImage: "qrcode.viewfinder")
+                            }
+                            .disabled(self.connectingGatewayID != nil)
+
                            Button {
                                Task { await self.applySetupCodeAndConnect() }
                            } label: {
@@ -430,6 +439,30 @@ struct SettingsTab: View {
                        })
                }
            }
+            .sheet(isPresented: self.$showQRScanner) {
+                NavigationStack {
+                    QRScannerView(
+                        onGatewayLink: { link in
+                            self.handleScannedGatewayLink(link)
+                        },
+                        onError: { error in
+                            self.showQRScanner = false
+                            self.setupStatusText = "Scanner error: \(error)"
+                            self.scannerError = error
+                        },
+                        onDismiss: {
+                            self.showQRScanner = false
+                        })
+                        .ignoresSafeArea()
+                        .navigationTitle("Scan QR Code")
+                        .navigationBarTitleDisplayMode(.inline)
+                        .toolbar {
+                            ToolbarItem(placement: .topBarLeading) {
+                                Button("Cancel") { self.showQRScanner = false }
+                            }
+                        }
+                }
+            }
            .alert("Reset Onboarding?", isPresented: self.$showResetOnboardingAlert) {
                Button("Reset", role: .destructive) {
                    self.resetOnboarding()
@@ -446,6 +479,14 @@ struct SettingsTab: View {
                    message: Text(help.message),
                    dismissButton: .default(Text("OK")))
            }
+            .alert("QR Scanner Unavailable", isPresented: Binding(
+                get: { self.scannerError != nil },
+                set: { if !$0 { self.scannerError = nil } }))
+            {
+                Button("OK", role: .cancel) {}
+            } message: {
+                Text(self.scannerError ?? "")
+            }
            .onAppear {
                self.lastLocationModeRaw = self.locationEnabledModeRaw
                self.syncManualPortText()
@@ -769,39 +810,28 @@ struct SettingsTab: View {
            return false
        }

-        guard let payload = GatewaySetupCode.decode(raw: raw) else {
-            self.setupStatusText = "Setup code not recognized."
+        guard let link = GatewayConnectDeepLink.fromSetupInput(raw) else {
+            self.setupStatusText = "Setup code not recognized or uses an insecure ws:// gateway URL."
            return false
        }

-        if let urlString = payload.url, let url = URL(string: urlString) {
-            self.applySetupURL(url)
-        } else if let host = payload.host, !host.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
-            self.manualGatewayHost = host.trimmingCharacters(in: .whitespacesAndNewlines)
-            if let port = payload.port {
-                self.manualGatewayPort = port
-                self.manualGatewayPortText = String(port)
-            } else {
-                self.manualGatewayPort = 0
-                self.manualGatewayPortText = ""
-            }
-            if let tls = payload.tls {
-                self.manualGatewayTLS = tls
-            }
-        } else if let url = URL(string: raw), url.scheme != nil {
-            self.applySetupURL(url)
-        } else {
-            self.setupStatusText = "Setup code missing URL or host."
-            return false
-        }
+        self.applyGatewayLink(link)
+        return true
+    }
+
+    private func applyGatewayLink(_ link: GatewayConnectDeepLink) {
+        self.manualGatewayHost = link.host
+        self.manualGatewayPort = link.port
+        self.manualGatewayPortText = String(link.port)
+        self.manualGatewayTLS = link.tls

        let trimmedInstanceId = self.instanceId.trimmingCharacters(in: .whitespacesAndNewlines)
        let trimmedBootstrapToken =
-            payload.bootstrapToken?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+            link.bootstrapToken?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
        if !trimmedInstanceId.isEmpty {
            GatewaySettingsStore.saveGatewayBootstrapToken(trimmedBootstrapToken, instanceId: trimmedInstanceId)
        }
-        if let token = payload.token, !token.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+        if let token = link.token, !token.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
            let trimmedToken = token.trimmingCharacters(in: .whitespacesAndNewlines)
            self.gatewayToken = trimmedToken
            if !trimmedInstanceId.isEmpty {
@@ -813,7 +843,7 @@ struct SettingsTab: View {
                GatewaySettingsStore.saveGatewayToken("", instanceId: trimmedInstanceId)
            }
        }
-        if let password = payload.password, !password.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+        if let password = link.password, !password.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
            let trimmedPassword = password.trimmingCharacters(in: .whitespacesAndNewlines)
            self.gatewayPassword = trimmedPassword
            if !trimmedInstanceId.isEmpty {
@@ -825,26 +855,33 @@ struct SettingsTab: View {
                GatewaySettingsStore.saveGatewayPassword("", instanceId: trimmedInstanceId)
            }
        }
-
-        return true
    }

-    private func applySetupURL(_ url: URL) {
-        guard let host = url.host, !host.isEmpty else { return }
-        self.manualGatewayHost = host
-        if let port = url.port {
-            self.manualGatewayPort = port
-            self.manualGatewayPortText = String(port)
-        } else {
-            self.manualGatewayPort = 0
-            self.manualGatewayPortText = ""
-        }
-        let scheme = (url.scheme ?? "").lowercased()
-        if scheme == "wss" || scheme == "https" {
-            self.manualGatewayTLS = true
-        } else if scheme == "ws" || scheme == "http" {
-            self.manualGatewayTLS = false
+    private func openGatewayQRScanner() {
+        self.appModel.disconnectGateway()
+        self.connectingGatewayID = nil
+        self.setupStatusText = "Opening QR scanner…"
+        self.showQRScanner = true
+    }
+
+    private func handleScannedGatewayLink(_ link: GatewayConnectDeepLink) {
+        self.showQRScanner = false
+        self.setupCode = ""
+        self.applyGatewayLink(link)
+        self.setupStatusText = "QR loaded. Connecting to \(link.host):\(link.port)…"
+        Task { await self.connectAfterScannedGatewayLink() }
+    }
+
+    private func connectAfterScannedGatewayLink() async {
+        let host = self.manualGatewayHost.trimmingCharacters(in: .whitespacesAndNewlines)
+        let resolvedPort = self.resolvedManualPort(host: host)
+        guard let port = resolvedPort else {
+            self.setupStatusText = "Failed: invalid port"
+            return
        }
+        let ok = await self.preflightGateway(host: host, port: port, useTLS: self.manualGatewayTLS)
+        guard ok else { return }
+        await self.connectManual()
    }

    private func resolvedManualPort(host: String) -> Int? {
@@ -892,8 +929,6 @@ struct SettingsTab: View {
            queueLabel: "gateway.preflight")
    }

-    // (GatewaySetupCode) decode raw setup codes.
-
    private func connectManual() async {
        let host = self.manualGatewayHost.trimmingCharacters(in: .whitespacesAndNewlines)
        guard !host.isEmpty else {
--- a/apps/ios/SwiftSources.input.xcfilelist
+++ b/apps/ios/SwiftSources.input.xcfilelist
@@ -21,7 +21,6 @@ Sources/Gateway/GatewayProblemView.swift
 Sources/Gateway/GatewayQuickSetupSheet.swift
 Sources/Gateway/GatewayServiceResolver.swift
 Sources/Gateway/GatewaySettingsStore.swift
-Sources/Gateway/GatewaySetupCode.swift
 Sources/Gateway/GatewayTrustPromptAlert.swift
 Sources/Gateway/KeychainStore.swift
 Sources/Gateway/TCPProbe.swift
--- a/apps/ios/Tests/DeepLinkParserTests.swift
+++ b/apps/ios/Tests/DeepLinkParserTests.swift
@@ -161,4 +161,34 @@ private func agentAction(
            token: nil,
            password: nil))
    }
+
+    @Test func parseGatewaySetupInputParsesFullCopiedSetupMessage() {
+        let payload = #"{"url":"wss://gateway.example.com","bootstrapToken":"tok"}"#
+        let link = GatewayConnectDeepLink.fromSetupInput("""
+        Pairing setup code generated.
+
+        Setup code:
+        \(setupCode(from: payload))
+        """)
+
+        #expect(link == .init(
+            host: "gateway.example.com",
+            port: 443,
+            tls: true,
+            bootstrapToken: "tok",
+            token: nil,
+            password: nil))
+    }
+
+    @Test func parseGatewaySetupInputParsesRawGatewayURL() {
+        let link = GatewayConnectDeepLink.fromSetupInput("wss://gateway.example.com:444")
+
+        #expect(link == .init(
+            host: "gateway.example.com",
+            port: 444,
+            tls: true,
+            bootstrapToken: nil,
+            token: nil,
+            password: nil))
+    }
 }
--- a/apps/shared/OpenClawKit/Sources/OpenClawKit/DeepLinks.swift
+++ b/apps/shared/OpenClawKit/Sources/OpenClawKit/DeepLinks.swift
@@ -6,6 +6,16 @@ public enum DeepLinkRoute: Sendable, Equatable {
 }

 public struct GatewayConnectDeepLink: Codable, Sendable, Equatable {
+    private struct SetupPayload: Decodable {
+        let url: String?
+        let host: String?
+        let port: Int?
+        let tls: Bool?
+        let bootstrapToken: String?
+        let token: String?
+        let password: String?
+    }
+
    public let host: String
    public let port: Int
    public let tls: Bool
@@ -27,28 +37,118 @@ public struct GatewayConnectDeepLink: Codable, Sendable, Equatable {
        return URL(string: "\(scheme)://\(self.host):\(self.port)")
    }

-    /// Parse a device-pair setup code (base64url-encoded JSON: `{url, bootstrapToken?, token?, password?}`).
+    /// Parse a gateway setup input from the QR/scanner/manual entry surfaces.
+    ///
+    /// Accepted inputs are:
+    /// - device-pair setup code (base64url-encoded JSON)
+    /// - raw setup JSON
+    /// - a copied message containing a `Setup code:` line
+    /// - an `openclaw://gateway?...` deep link
+    /// - a raw `ws://` or `wss://` gateway URL
+    public static func fromSetupInput(_ input: String) -> GatewayConnectDeepLink? {
+        let trimmed = input.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return nil }
+        if let link = fromSetupCode(trimmed) {
+            return link
+        }
+        if let url = URL(string: trimmed),
+           let route = DeepLinkParser.parse(url),
+           case let .gateway(link) = route
+        {
+            return link
+        }
+        return fromGatewayURLString(
+            trimmed,
+            bootstrapToken: nil,
+            token: nil,
+            password: nil)
+    }
+
+    /// Parse a gateway setup payload from a device-pair setup code or copied setup text.
+    ///
+    /// Accepted inputs are:
+    /// - base64url-encoded setup JSON
+    /// - raw setup JSON
+    /// - copied text/message content containing one or more extractable setup-code candidates
+    ///
+    /// Accepted payload shapes are:
+    /// - `{url, bootstrapToken?, token?, password?}`
+    /// - `{host, port?, tls?, bootstrapToken?, token?, password?}`
+    ///
+    /// URL-based payloads provide the gateway WebSocket URL via `url`. Host-based payloads
+    /// provide `host` plus optional `port` and `tls`. In both cases, the optional
+    /// `bootstrapToken`, `token`, and `password` fields are also supported.
    public static func fromSetupCode(_ code: String) -> GatewayConnectDeepLink? {
-        guard let data = decodeBase64Url(code) else { return nil }
-        guard let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any] else { return nil }
-        guard let urlString = json["url"] as? String,
-              let parsed = URLComponents(string: urlString),
+        let trimmed = code.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return nil }
+        if let link = decodeSetupPayload(from: Data(trimmed.utf8)) {
+            return link
+        }
+        if let data = decodeBase64Url(trimmed),
+           let link = decodeSetupPayload(from: data)
+        {
+            return link
+        }
+        for candidate in setupCodeCandidates(in: trimmed) where candidate != trimmed {
+            if let data = decodeBase64Url(candidate),
+               let link = decodeSetupPayload(from: data)
+            {
+                return link
+            }
+        }
+        return nil
+    }
+
+    private static func decodeSetupPayload(from data: Data) -> GatewayConnectDeepLink? {
+        guard let payload = try? JSONDecoder().decode(SetupPayload.self, from: data) else { return nil }
+        if let urlString = payload.url?.trimmingCharacters(in: .whitespacesAndNewlines),
+           !urlString.isEmpty
+        {
+            return fromGatewayURLString(
+                urlString,
+                bootstrapToken: payload.bootstrapToken,
+                token: payload.token,
+                password: payload.password)
+        }
+        guard let host = payload.host?.trimmingCharacters(in: .whitespacesAndNewlines),
+              !host.isEmpty
+        else {
+            return nil
+        }
+        let tls = payload.tls ?? true
+        if !tls, !LoopbackHost.isLoopbackHost(host) {
+            return nil
+        }
+        return GatewayConnectDeepLink(
+            host: host,
+            port: payload.port ?? (tls ? 443 : 18789),
+            tls: tls,
+            bootstrapToken: payload.bootstrapToken,
+            token: payload.token,
+            password: payload.password)
+    }
+
+    private static func fromGatewayURLString(
+        _ urlString: String,
+        bootstrapToken: String?,
+        token: String?,
+        password: String?) -> GatewayConnectDeepLink?
+    {
+        guard let parsed = URLComponents(string: urlString),
              let hostname = parsed.host, !hostname.isEmpty
        else { return nil }

        let scheme = (parsed.scheme ?? "ws").lowercased()
-        guard scheme == "ws" || scheme == "wss" else { return nil }
-        let tls = scheme == "wss"
+        guard scheme == "ws" || scheme == "wss" || scheme == "http" || scheme == "https" else {
+            return nil
+        }
+        let tls = scheme == "wss" || scheme == "https"
        if !tls, !LoopbackHost.isLoopbackHost(hostname) {
            return nil
        }
-        let port = parsed.port ?? (tls ? 443 : 18789)
-        let bootstrapToken = json["bootstrapToken"] as? String
-        let token = json["token"] as? String
-        let password = json["password"] as? String
        return GatewayConnectDeepLink(
            host: hostname,
-            port: port,
+            port: parsed.port ?? (tls ? 443 : 18789),
            tls: tls,
            bootstrapToken: bootstrapToken,
            token: token,
@@ -65,6 +165,19 @@ public struct GatewayConnectDeepLink: Codable, Sendable, Equatable {
        }
        return Data(base64Encoded: base64)
    }
+
+    private static func setupCodeCandidates(in input: String) -> [String] {
+        let surroundingPunctuation = CharacterSet(charactersIn: "`'\"“”‘’()[]{}<>.,;:")
+        return input
+            .components(separatedBy: .whitespacesAndNewlines)
+            .map { $0.trimmingCharacters(in: .whitespacesAndNewlines.union(surroundingPunctuation)) }
+            .filter { candidate in
+                guard candidate.count >= 24 else { return false }
+                return candidate.allSatisfy { ch in
+                    ch.isLetter || ch.isNumber || ch == "-" || ch == "_" || ch == "="
+                }
+            }
+    }
 }

 public struct AgentDeepLink: Codable, Sendable, Equatable {
--- a/apps/shared/OpenClawKit/Tests/OpenClawKitTests/DeepLinksSecurityTests.swift
+++ b/apps/shared/OpenClawKit/Tests/OpenClawKitTests/DeepLinksSecurityTests.swift
@@ -2,6 +2,14 @@ import Foundation
 import OpenClawKit
 import Testing

+private func setupCode(from payload: String) -> String {
+    Data(payload.utf8)
+        .base64EncodedString()
+        .replacingOccurrences(of: "+", with: "-")
+        .replacingOccurrences(of: "/", with: "_")
+        .replacingOccurrences(of: "=", with: "")
+}
+
@Suite struct DeepLinksSecurityTests {
    @Test func gatewayDeepLinkRejectsInsecureNonLoopbackWs() {
        let url = URL(
@@ -31,33 +39,18 @@ import Testing

    @Test func setupCodeRejectsInsecureNonLoopbackWs() {
        let payload = #"{"url":"ws://attacker.example:18789","bootstrapToken":"tok"}"#
-        let encoded = Data(payload.utf8)
-            .base64EncodedString()
-            .replacingOccurrences(of: "+", with: "-")
-            .replacingOccurrences(of: "/", with: "_")
-            .replacingOccurrences(of: "=", with: "")
-        #expect(GatewayConnectDeepLink.fromSetupCode(encoded) == nil)
+        #expect(GatewayConnectDeepLink.fromSetupCode(setupCode(from: payload)) == nil)
    }

    @Test func setupCodeRejectsInsecurePrefixBypassHost() {
        let payload = #"{"url":"ws://127.attacker.example:18789","bootstrapToken":"tok"}"#
-        let encoded = Data(payload.utf8)
-            .base64EncodedString()
-            .replacingOccurrences(of: "+", with: "-")
-            .replacingOccurrences(of: "/", with: "_")
-            .replacingOccurrences(of: "=", with: "")
-        #expect(GatewayConnectDeepLink.fromSetupCode(encoded) == nil)
+        #expect(GatewayConnectDeepLink.fromSetupCode(setupCode(from: payload)) == nil)
    }

    @Test func setupCodeAllowsLoopbackWs() {
        let payload = #"{"url":"ws://127.0.0.1:18789","bootstrapToken":"tok"}"#
-        let encoded = Data(payload.utf8)
-            .base64EncodedString()
-            .replacingOccurrences(of: "+", with: "-")
-            .replacingOccurrences(of: "/", with: "_")
-            .replacingOccurrences(of: "=", with: "")
        #expect(
-            GatewayConnectDeepLink.fromSetupCode(encoded) == .init(
+            GatewayConnectDeepLink.fromSetupCode(setupCode(from: payload)) == .init(
                host: "127.0.0.1",
                port: 18789,
                tls: false,
@@ -65,4 +58,62 @@ import Testing
                token: nil,
                password: nil))
    }
+
+    @Test func setupCodeParsesHostPayload() {
+        let payload = #"{"host":"gateway.tailnet.ts.net","port":443,"tls":true,"bootstrapToken":"tok"}"#
+        #expect(
+            GatewayConnectDeepLink.fromSetupCode(setupCode(from: payload)) == .init(
+                host: "gateway.tailnet.ts.net",
+                port: 443,
+                tls: true,
+                bootstrapToken: "tok",
+                token: nil,
+                password: nil))
+    }
+
+    @Test func setupCodeParsesHostPayloadWithTLSDefaultPort() {
+        let payload = #"{"host":"gateway.tailnet.ts.net","tls":true,"bootstrapToken":"tok"}"#
+        #expect(
+            GatewayConnectDeepLink.fromSetupCode(setupCode(from: payload)) == .init(
+                host: "gateway.tailnet.ts.net",
+                port: 443,
+                tls: true,
+                bootstrapToken: "tok",
+                token: nil,
+                password: nil))
+    }
+
+    @Test func setupCodeRejectsInsecureHostPayload() {
+        let payload = #"{"host":"gateway.tailnet.ts.net","port":18789,"tls":false,"bootstrapToken":"tok"}"#
+        #expect(GatewayConnectDeepLink.fromSetupCode(setupCode(from: payload)) == nil)
+    }
+
+    @Test func setupInputParsesFullCopiedSetupMessage() {
+        let payload = #"{"url":"wss://gateway.tailnet.ts.net","bootstrapToken":"tok"}"#
+        let message = """
+        Pairing setup code generated.
+
+        Setup code:
+        \(setupCode(from: payload))
+        """
+        #expect(
+            GatewayConnectDeepLink.fromSetupInput(message) == .init(
+                host: "gateway.tailnet.ts.net",
+                port: 443,
+                tls: true,
+                bootstrapToken: "tok",
+                token: nil,
+                password: nil))
+    }
+
+    @Test func setupInputParsesRawGatewayURL() {
+        #expect(
+            GatewayConnectDeepLink.fromSetupInput("wss://gateway.example.com:444") == .init(
+                host: "gateway.example.com",
+                port: 444,
+                tls: true,
+                bootstrapToken: nil,
+                token: nil,
+                password: nil))
+    }
 }
--- a/docs/channels/pairing.md
+++ b/docs/channels/pairing.md
@@ -113,7 +113,7 @@ If you use the `device-pair` plugin, you can do first-time device pairing entire
 1. In Telegram, message your bot: `/pair`
 2. The bot replies with two messages: an instruction message and a separate **setup code** message (easy to copy/paste in Telegram).
 3. On your phone, open the OpenClaw iOS app → Settings → Gateway.
-4. Paste the setup code and connect.
+4. Scan the QR code or paste the setup code and connect.
 5. Back in Telegram: `/pair pending` (review request IDs, role, and scopes), then approve.

 The setup code is a base64-encoded JSON payload that contains:
@@ -134,6 +134,13 @@ That bootstrap token carries the built-in pairing bootstrap profile:

 Treat the setup code like a password while it is valid.

+For Tailscale, public, or other non-loopback mobile pairing, use Tailscale
+Serve/Funnel or another `wss://` Gateway URL. Direct non-loopback `ws://` setup
+URLs are rejected before QR/setup-code issuance. Plaintext `ws://` setup codes
+are limited to loopback URLs; private-network `ws://` clients still require the explicit
+`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` break-glass described in the remote
+Gateway guide.
+
 ### Approve a node device

 ```bash
--- a/extensions/device-pair/index.test.ts
+++ b/extensions/device-pair/index.test.ts
@@ -56,7 +56,12 @@ vi.mock("./notify.js", () => ({
  registerPairingNotifierService: vi.fn(),
 }));

-import { approveDevicePairing, listDevicePairing } from "./api.js";
+import {
+  approveDevicePairing,
+  listDevicePairing,
+  resolveGatewayBindUrl,
+  resolveTailnetHostWithRunner,
+} from "./api.js";
 import registerDevicePair from "./index.js";

 type ListedPendingPairingRequest = Awaited<ReturnType<typeof listDevicePairing>>["pending"][number];
@@ -87,7 +92,7 @@ function createApi(params?: {
      },
    },
    pluginConfig: {
-      publicUrl: "ws://51.79.175.165:18789",
+      publicUrl: "wss://gateway.example.test",
      ...params?.pluginConfig,
    },
    runtime: (params?.runtime ?? {}) as OpenClawPluginApi["runtime"],
@@ -611,8 +616,17 @@ describe("device-pair /pair default setup code", () => {
    });
  });

-  it("normalizes bare publicUrl host ports before issuing setup codes", async () => {
+  it("normalizes secure bare publicUrl host ports before issuing setup codes", async () => {
    const command = registerPairCommand({
+      config: {
+        gateway: {
+          tls: { enabled: true },
+          auth: {
+            mode: "token",
+            token: "gateway-token",
+          },
+        },
+      },
      pluginConfig: {
        publicUrl: "gateway.example.test:18789/setup",
      },
@@ -628,7 +642,131 @@ describe("device-pair /pair default setup code", () => {
    const text = requireText(result);

    expect(pluginApiMocks.issueDeviceBootstrapToken).toHaveBeenCalledTimes(1);
-    expect(text).toContain("Gateway: ws://gateway.example.test:18789");
+    expect(text).toContain("Gateway: wss://gateway.example.test:18789");
+  });
+
+  it("allows loopback cleartext setup urls", async () => {
+    const command = registerPairCommand({
+      pluginConfig: {
+        publicUrl: "ws://127.0.0.1:18789",
+      },
+    });
+    const result = await command.handler(
+      createCommandContext({
+        channel: "webchat",
+        args: "",
+        commandBody: "/pair",
+        gatewayClientScopes: ["operator.write", "operator.pairing"],
+      }),
+    );
+    const text = requireText(result);
+
+    expect(pluginApiMocks.issueDeviceBootstrapToken).toHaveBeenCalledTimes(1);
+    expect(text).toContain("Gateway: ws://127.0.0.1:18789");
+  });
+
+  it("rejects private LAN cleartext setup urls before issuing setup codes", async () => {
+    const command = registerPairCommand({
+      pluginConfig: {
+        publicUrl: "ws://192.168.1.20:18789",
+      },
+    });
+    const result = await command.handler(
+      createCommandContext({
+        channel: "webchat",
+        args: "",
+        commandBody: "/pair",
+        gatewayClientScopes: ["operator.write", "operator.pairing"],
+      }),
+    );
+
+    expect(pluginApiMocks.issueDeviceBootstrapToken).not.toHaveBeenCalled();
+    expect(requireText(result)).toContain(
+      "Mobile pairing over non-loopback networks requires a secure gateway URL",
+    );
+  });
+
+  it("rejects public cleartext setup urls before issuing setup codes", async () => {
+    const command = registerPairCommand({
+      pluginConfig: {
+        publicUrl: "ws://gateway.example.test:18789",
+      },
+    });
+    const result = await command.handler(
+      createCommandContext({
+        channel: "webchat",
+        args: "",
+        commandBody: "/pair",
+        gatewayClientScopes: ["operator.write", "operator.pairing"],
+      }),
+    );
+
+    expect(pluginApiMocks.issueDeviceBootstrapToken).not.toHaveBeenCalled();
+    expect(requireText(result)).toContain(
+      "Mobile pairing over non-loopback networks requires a secure gateway URL",
+    );
+  });
+
+  it("rejects tailnet cleartext setup urls before issuing setup codes", async () => {
+    vi.mocked(resolveGatewayBindUrl).mockReturnValueOnce({
+      url: "ws://100.64.0.9:18789",
+      source: "gateway.bind=tailnet",
+    });
+    const command = registerPairCommand({
+      config: {
+        gateway: {
+          bind: "tailnet",
+          auth: {
+            mode: "token",
+            token: "gateway-token",
+          },
+        },
+      },
+      pluginConfig: {
+        publicUrl: undefined,
+      },
+    });
+    const result = await command.handler(
+      createCommandContext({
+        channel: "webchat",
+        args: "",
+        commandBody: "/pair",
+        gatewayClientScopes: ["operator.write", "operator.pairing"],
+      }),
+    );
+
+    expect(pluginApiMocks.issueDeviceBootstrapToken).not.toHaveBeenCalled();
+    expect(requireText(result)).toContain("prefer gateway.tailscale.mode=serve");
+  });
+
+  it("uses Tailscale Serve MagicDNS as a secure setup url", async () => {
+    vi.mocked(resolveTailnetHostWithRunner).mockResolvedValueOnce("gateway.tailnet.ts.net");
+    const command = registerPairCommand({
+      config: {
+        gateway: {
+          tailscale: { mode: "serve" },
+          auth: {
+            mode: "token",
+            token: "gateway-token",
+          },
+        },
+      },
+      pluginConfig: {
+        publicUrl: undefined,
+      },
+    });
+    const result = await command.handler(
+      createCommandContext({
+        channel: "webchat",
+        args: "",
+        commandBody: "/pair",
+        gatewayClientScopes: ["operator.write", "operator.pairing"],
+      }),
+    );
+    const text = requireText(result);
+
+    expect(pluginApiMocks.issueDeviceBootstrapToken).toHaveBeenCalledTimes(1);
+    expect(text).toContain("Gateway: wss://gateway.tailnet.ts.net");
  });

  it("rejects invalid bare publicUrl host ports", async () => {
--- a/extensions/device-pair/index.ts
+++ b/extensions/device-pair/index.ts
@@ -172,6 +172,47 @@ function parseNormalizedGatewayUrl(raw: string): string | null {
  }
 }

+function describeSecureMobilePairingFix(source?: string): string {
+  const sourceNote = source ? ` Resolved source: ${source}.` : "";
+  return (
+    "Mobile pairing over non-loopback networks requires a secure gateway URL (wss://) or Tailscale Serve/Funnel." +
+    sourceNote +
+    " Fix: prefer gateway.tailscale.mode=serve, or set " +
+    "gateway.remote.url / plugins.entries.device-pair.config.publicUrl to a wss:// URL. " +
+    "ws:// setup codes are only valid for localhost/loopback or the Android emulator."
+  );
+}
+
+function normalizeHostForIpCheck(host: string): string {
+  let normalized = normalizeLowercaseStringOrEmpty(host);
+  if (normalized.startsWith("[") && normalized.endsWith("]")) {
+    normalized = normalized.slice(1, -1);
+  }
+  if (normalized.endsWith(".")) {
+    normalized = normalized.slice(0, -1);
+  }
+  const zoneIndex = normalized.indexOf("%");
+  if (zoneIndex >= 0) {
+    normalized = normalized.slice(0, zoneIndex);
+  }
+  return normalized;
+}
+
+function isLoopbackHost(host: string): boolean {
+  const normalized = normalizeHostForIpCheck(host);
+  if (!normalized) {
+    return false;
+  }
+  if (normalized === "localhost" || normalized === "0.0.0.0" || normalized === "::") {
+    return true;
+  }
+  const octets = parseIPv4Octets(normalized);
+  if (octets) {
+    return octets[0] === 127;
+  }
+  return normalized === "::1" || normalized === "0:0:0:0:0:0:0:1";
+}
+
 function resolveScheme(
  cfg: OpenClawPluginApi["config"],
  opts?: { forceSecure?: boolean },
@@ -187,6 +228,9 @@ function parseIPv4Octets(address: string): [number, number, number, number] | nu
  if (parts.length !== 4) {
    return null;
  }
+  if (parts.some((part) => !/^\d+$/.test(part))) {
+    return null;
+  }
  const octets = parts.map((part) => Number.parseInt(part, 10));
  if (octets.some((value) => !Number.isFinite(value) || value < 0 || value > 255)) {
    return null;
@@ -221,6 +265,29 @@ function isTailnetIPv4(address: string): boolean {
  return a === 100 && b >= 64 && b <= 127;
 }

+function isMobilePairingCleartextAllowedHost(host: string): boolean {
+  const normalized = normalizeHostForIpCheck(host);
+  return isLoopbackHost(normalized) || normalized === "10.0.2.2";
+}
+
+function validateMobilePairingUrl(url: string, source?: string): string | null {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return "Resolved mobile pairing URL is invalid.";
+  }
+  const protocol =
+    parsed.protocol === "https:" ? "wss:" : parsed.protocol === "http:" ? "ws:" : parsed.protocol;
+  if (protocol === "wss:") {
+    return null;
+  }
+  if (protocol !== "ws:" || isMobilePairingCleartextAllowedHost(parsed.hostname)) {
+    return null;
+  }
+  return describeSecureMobilePairingFix(source);
+}
+
 function pickMatchingIPv4(predicate: (address: string) => boolean): string | null {
  const nets = os.networkInterfaces();
  for (const entries of Object.values(nets)) {
@@ -362,6 +429,18 @@ async function resolveGatewayUrl(api: OpenClawPluginApi): Promise<ResolveUrlResu
  };
 }

+async function resolveMobilePairingGatewayUrl(api: OpenClawPluginApi): Promise<ResolveUrlResult> {
+  const result = await resolveGatewayUrl(api);
+  if (!result.url) {
+    return result;
+  }
+  const mobilePairingUrlError = validateMobilePairingUrl(result.url, result.source);
+  if (mobilePairingUrlError) {
+    return { error: mobilePairingUrlError };
+  }
+  return result;
+}
+
 function encodeSetupCode(payload: SetupPayload): string {
  const json = JSON.stringify(payload);
  const base64 = Buffer.from(json, "utf8").toString("base64");
@@ -668,7 +747,7 @@ export default definePluginEntry({
          return buildMissingPairingScopeReply();
        }

-        const urlResult = await resolveGatewayUrl(api);
+        const urlResult = await resolveMobilePairingGatewayUrl(api);
        if (!urlResult.url) {
          return { text: `Error: ${urlResult.error ?? "Gateway URL unavailable."}` };
        }