fix(macos): repair stale gateway tls pins (#75038)

Merged via squash.

Prepared head SHA: 35196f8f71
Co-authored-by: ngutman <1540134+ngutman@users.noreply.github.com>
Co-authored-by: ngutman <1540134+ngutman@users.noreply.github.com>
Reviewed-by: @ngutman

CHANGELOG.md

@@ -335,6 +335,7 @@ Docs: https://docs.openclaw.ai
 - Providers/GitHub Copilot: support the GUI/RPC wizard device-code auth flow so onboarding from non-TTY clients (gateway RPC bridge, GUI wizards) completes instead of returning empty profiles. Dangerous-state handling now distinguishes `access_denied` and `expired_token` from transport errors. (#73290) Thanks @indierawk2k2.
 - Installer/Linux: warn before switching an unwritable npm global prefix to `~/.npm-global`, then tell users to run future global updates with `npm i -g openclaw@latest` without `sudo` so npm keeps using the redirected user prefix. Fixes #44365; carries forward #50479. Thanks @Sayeem3051.
 - Gateway/plugins: enable the native `require()` fast path on Windows for bundled plugin modules so plugin loading uses `require()` instead of Jiti's transform pipeline, reducing startup from ~39s to ~2s on typical 6-plugin setups. Fixes #68656. (#74173) Thanks @galiniliev.
+- macOS app: detect stale Gateway TLS certificate pins, automatically repair trusted Tailscale Serve rotations, and surface paired-but-disconnected Mac companion nodes so partial Gateway connections no longer look healthy. Thanks @guti.
 
 ## 2026.4.27
 

apps/macos/Sources/OpenClaw/MenuContentView.swift

@@ -2,6 +2,7 @@ import AppKit
 import AVFoundation
 import Foundation
 import Observation
+import OpenClawKit
 import SwiftUI
 
 /// Menu contents for the OpenClaw menu bar extra.
@@ -14,6 +15,7 @@ struct MenuContent: View {
     private let heartbeatStore = HeartbeatStore.shared
     private let controlChannel = ControlChannel.shared
     private let activityStore = WorkActivityStore.shared
+    private let nodesStore = NodesStore.shared
     @Bindable private var pairingPrompter = NodePairingApprovalPrompter.shared
     @Bindable private var devicePairingPrompter = DevicePairingApprovalPrompter.shared
     @Environment(\.openSettings) private var openSettings
@@ -44,6 +46,9 @@ struct MenuContent: View {
                 VStack(alignment: .leading, spacing: 2) {
                     Text(self.connectionLabel)
                     self.statusLine(label: self.healthStatus.label, color: self.healthStatus.color)
+                    if let macNodeStatus = self.macNodeStatus {
+                        self.statusLine(label: macNodeStatus.label, color: macNodeStatus.color)
+                    }
                     if self.pairingPrompter.pendingCount > 0 {
                         let repairCount = self.pairingPrompter.pendingRepairCount
                         let repairSuffix = repairCount > 0 ? " · \(repairCount) repair" : ""
@@ -351,6 +356,31 @@ struct MenuContent: View {
         }
     }
 
+    private var macNodeStatus: (label: String, color: Color)? {
+        guard self.state.connectionMode != .unconfigured else { return nil }
+        guard case .connected = self.controlChannel.state else { return nil }
+
+        let deviceId = DeviceIdentityStore.loadOrCreate().deviceId
+        if let entry = self.nodesStore.nodes.first(where: { $0.nodeId == deviceId }) {
+            guard entry.isConnected else {
+                return ("Mac capabilities offline", .orange)
+            }
+            let commands = Set(entry.commands ?? [])
+            let missingRequiredCommands = [
+                OpenClawSystemCommand.notify.rawValue,
+                OpenClawSystemCommand.run.rawValue,
+                OpenClawSystemCommand.which.rawValue,
+            ].filter { !commands.contains($0) }
+            if !missingRequiredCommands.isEmpty {
+                return ("Mac capabilities incomplete", .orange)
+            }
+            return nil
+        }
+
+        guard !self.nodesStore.isLoading, !self.nodesStore.nodes.isEmpty else { return nil }
+        return ("Mac capabilities offline", .orange)
+    }
+
     private var healthStatus: (label: String, color: Color) {
         if let activity = self.activityStore.current {
             let color: Color = activity.role == .main ? .accentColor : .gray

apps/macos/Sources/OpenClaw/MenuSessionsInjector.swift

@@ -1156,7 +1156,7 @@ extension MenuSessionsInjector {
     }
 
     private func sortedNodeEntries() -> [NodeInfo] {
-        let entries = self.nodesStore.nodes.filter(\.isConnected)
+        let entries = self.nodesStore.nodes.filter { $0.isConnected || $0.isPaired }
         return entries.sorted { lhs, rhs in
             if lhs.isConnected != rhs.isConnected { return lhs.isConnected }
             if lhs.isPaired != rhs.isPaired { return lhs.isPaired }
@@ -1239,5 +1239,9 @@ extension MenuSessionsInjector {
     func testingFindNodesInsertIndex(in menu: NSMenu) -> Int? {
         self.findNodesInsertIndex(in: menu)
     }
+
+    func testingSortedNodeEntries() -> [NodeInfo] {
+        self.sortedNodeEntries()
+    }
 }
 #endif

apps/macos/Sources/OpenClaw/NodeMode/MacNodeModeCoordinator.swift

@@ -10,6 +10,7 @@ final class MacNodeModeCoordinator {
     private var task: Task<Void, Never>?
     private let runtime = MacNodeRuntime()
     private let session = GatewayNodeSession()
+    private var autoRepairedTLSFingerprintsByStoreKey: [String: String] = [:]
 
     func start() {
         guard self.task == nil else { return }
@@ -58,8 +59,10 @@ final class MacNodeModeCoordinator {
                 try? await Task.sleep(nanoseconds: 200_000_000)
             }
 
+            var attemptedURL: URL?
             do {
                 let config = try await GatewayEndpointStore.shared.requireConfig()
+                attemptedURL = config.url
                 let caps = self.currentCaps()
                 let commands = self.currentCommands(caps: caps)
                 let permissions = await self.currentPermissions()
@@ -109,6 +112,10 @@ final class MacNodeModeCoordinator {
                 retryDelay = 1_000_000_000
                 try? await Task.sleep(nanoseconds: 1_000_000_000)
             } catch {
+                if await self.autoRepairStaleTLSPinIfNeeded(error: error, url: attemptedURL) {
+                    retryDelay = 1_000_000_000
+                    continue
+                }
                 self.logger.error("mac node gateway connect failed: \(error.localizedDescription, privacy: .public)")
                 try? await Task.sleep(nanoseconds: min(retryDelay, 10_000_000_000))
                 retryDelay = min(retryDelay * 2, 10_000_000_000)
@@ -188,11 +195,49 @@ final class MacNodeModeCoordinator {
         Self.resolvedCommands(caps: caps)
     }
 
+    nonisolated static func tlsPinStoreKey(for url: URL) -> String {
+        let host = url.host?.trimmingCharacters(in: .whitespacesAndNewlines).nonEmpty ?? "gateway"
+        let port = url.port ?? 443
+        return "\(host):\(port)"
+    }
+
+    nonisolated static func shouldAutoRepairStaleTLSPin(url: URL, failure: GatewayTLSValidationFailure) -> Bool {
+        guard failure.kind == .pinMismatch else { return false }
+        guard url.scheme?.lowercased() == "wss" else { return false }
+        guard failure.storeKey == nil || failure.storeKey == self.tlsPinStoreKey(for: url) else { return false }
+        guard let host = url.host?.trimmingCharacters(in: .whitespacesAndNewlines).lowercased(), !host.isEmpty
+        else { return false }
+
+        if LoopbackHost.isLoopback(host) {
+            return failure.systemTrustOk
+        }
+
+        // Tailscale Serve uses publicly trusted, rotating certificates for *.ts.net names.
+        // A stale legacy leaf pin should not leave the companion app half-connected forever.
+        if host == "ts.net" || host.hasSuffix(".ts.net") {
+            return failure.systemTrustOk
+        }
+
+        return false
+    }
+
+    private func autoRepairStaleTLSPinIfNeeded(error: Error, url: URL?) async -> Bool {
+        guard let tlsError = error as? GatewayTLSValidationError, let url else { return false }
+        guard Self.shouldAutoRepairStaleTLSPin(url: url, failure: tlsError.failure) else { return false }
+        let storeKey = tlsError.failure.storeKey ?? Self.tlsPinStoreKey(for: url)
+        guard let observedFingerprint = tlsError.failure.observedFingerprint else { return false }
+        guard self.autoRepairedTLSFingerprintsByStoreKey[storeKey] != observedFingerprint else { return false }
+
+        guard GatewayTLSStore.replaceFingerprint(observedFingerprint, stableID: storeKey) else { return false }
+        self.autoRepairedTLSFingerprintsByStoreKey[storeKey] = observedFingerprint
+        self.logger.info("replaced stale gateway TLS pin storeKey=\(storeKey, privacy: .public)")
+        await self.session.disconnect()
+        return true
+    }
+
     private func buildSessionBox(url: URL) -> WebSocketSessionBox? {
         guard url.scheme?.lowercased() == "wss" else { return nil }
-        let host = url.host ?? "gateway"
-        let port = url.port ?? 443
-        let stableID = "\(host):\(port)"
+        let stableID = Self.tlsPinStoreKey(for: url)
         let stored = GatewayTLSStore.loadFingerprint(stableID: stableID)
         let params = GatewayTLSParams(
             required: true,

apps/macos/Sources/OpenClaw/NodesMenu.swift

@@ -44,10 +44,12 @@ struct NodeMenuEntryFormatter {
     }
 
     static func roleText(_ entry: NodeInfo) -> String {
-        if entry.isConnected { return "connected" }
-        if self.isGateway(entry) { return "disconnected" }
-        if entry.isPaired { return "paired" }
-        return "unpaired"
+        if self.isGateway(entry) {
+            return entry.isConnected ? "connected" : "disconnected"
+        }
+        let pairing = entry.isPaired ? "paired" : "unpaired"
+        let connection = entry.isConnected ? "connected" : "disconnected"
+        return "\(pairing) · \(connection)"
     }
 
     static func detailLeft(_ entry: NodeInfo) -> String {

apps/macos/Tests/OpenClawIPCTests/GatewayChannelConnectTests.swift

@@ -4,6 +4,30 @@ import Testing
 @testable import OpenClaw
 
 struct GatewayChannelConnectTests {
+    private final class TLSFailureSession: WebSocketSessioning, GatewayTLSFailureProviding, @unchecked Sendable {
+        private var failure: GatewayTLSValidationFailure?
+
+        init(failure: GatewayTLSValidationFailure) {
+            self.failure = failure
+        }
+
+        func makeWebSocketTask(url: URL) -> WebSocketTaskBox {
+            _ = url
+            let task = GatewayTestWebSocketTask(receiveHook: { _, receiveIndex in
+                if receiveIndex == 0 {
+                    return .data(GatewayWebSocketTestSupport.connectChallengeData())
+                }
+                throw URLError(.userCancelledAuthentication)
+            })
+            return WebSocketTaskBox(task: task)
+        }
+
+        func consumeLastTLSFailure() -> GatewayTLSValidationFailure? {
+            defer { self.failure = nil }
+            return self.failure
+        }
+    }
+
     private enum FakeResponse {
         case helloOk(delayMs: Int)
         case invalid(delayMs: Int)
@@ -109,4 +133,28 @@ struct GatewayChannelConnectTests {
             Issue.record("unexpected error: \(error)")
         }
     }
+
+    @Test func `connect maps user cancelled authentication with cached TLS failure`() async throws {
+        let failure = GatewayTLSValidationFailure(
+            kind: .pinMismatch,
+            host: "gateway.example.ts.net",
+            storeKey: "gateway.example.ts.net:443",
+            expectedFingerprint: "old",
+            observedFingerprint: "new",
+            systemTrustOk: true)
+        let session = TLSFailureSession(failure: failure)
+        let channel = try GatewayChannelActor(
+            url: #require(URL(string: "wss://gateway.example.ts.net")),
+            token: nil,
+            session: WebSocketSessionBox(session: session))
+
+        do {
+            try await channel.connect()
+            Issue.record("expected GatewayTLSValidationError")
+        } catch let error as GatewayTLSValidationError {
+            #expect(error.failure == failure)
+        } catch {
+            Issue.record("unexpected error: \(error)")
+        }
+    }
 }

apps/macos/Tests/OpenClawIPCTests/MacNodeModeCoordinatorTests.swift

@@ -29,4 +29,61 @@ struct MacNodeModeCoordinatorTests {
         #expect(caps.contains(OpenClawCapability.browser.rawValue))
         #expect(commands.contains(OpenClawBrowserCommand.proxy.rawValue))
     }
+
+    @Test func `tls pin store key uses default wss port`() throws {
+        let url = try #require(URL(string: "wss://gateway.example.ts.net"))
+        #expect(MacNodeModeCoordinator.tlsPinStoreKey(for: url) == "gateway.example.ts.net:443")
+    }
+
+    @Test func `auto repairs trusted tailscale serve pin mismatch`() throws {
+        let url = try #require(URL(string: "wss://gateway.example.ts.net"))
+        let failure = GatewayTLSValidationFailure(
+            kind: .pinMismatch,
+            host: "gateway.example.ts.net",
+            storeKey: "gateway.example.ts.net:443",
+            expectedFingerprint: "old",
+            observedFingerprint: "new",
+            systemTrustOk: true)
+
+        #expect(MacNodeModeCoordinator.shouldAutoRepairStaleTLSPin(url: url, failure: failure))
+    }
+
+    @Test func `does not auto repair untrusted remote pin mismatch`() throws {
+        let url = try #require(URL(string: "wss://gateway.example.com"))
+        let failure = GatewayTLSValidationFailure(
+            kind: .pinMismatch,
+            host: "gateway.example.com",
+            storeKey: "gateway.example.com:443",
+            expectedFingerprint: "old",
+            observedFingerprint: "new",
+            systemTrustOk: true)
+
+        #expect(!MacNodeModeCoordinator.shouldAutoRepairStaleTLSPin(url: url, failure: failure))
+    }
+
+    @Test func `auto repairs trusted loopback pin mismatch`() throws {
+        let url = try #require(URL(string: "wss://127.0.0.1:18789"))
+        let failure = GatewayTLSValidationFailure(
+            kind: .pinMismatch,
+            host: "127.0.0.1",
+            storeKey: "127.0.0.1:18789",
+            expectedFingerprint: "old",
+            observedFingerprint: "new",
+            systemTrustOk: true)
+
+        #expect(MacNodeModeCoordinator.shouldAutoRepairStaleTLSPin(url: url, failure: failure))
+    }
+
+    @Test func `does not auto repair untrusted loopback pin mismatch`() throws {
+        let url = try #require(URL(string: "wss://127.0.0.1:18789"))
+        let failure = GatewayTLSValidationFailure(
+            kind: .pinMismatch,
+            host: "127.0.0.1",
+            storeKey: "127.0.0.1:18789",
+            expectedFingerprint: "old",
+            observedFingerprint: "new",
+            systemTrustOk: false)
+
+        #expect(!MacNodeModeCoordinator.shouldAutoRepairStaleTLSPin(url: url, failure: failure))
+    }
 }

apps/macos/Tests/OpenClawIPCTests/MenuSessionsInjectorTests.swift

@@ -165,4 +165,50 @@ struct MenuSessionsInjectorTests {
         #expect(usageCostItem?.submenu != nil)
         #expect(usageCostItem?.submenu?.delegate == nil)
     }
+
+    @Test func `node status text distinguishes paired disconnected nodes`() {
+        let pairedDisconnected = Self.node(id: "paired", paired: true, connected: false)
+        let unpairedDisconnected = Self.node(id: "unpaired", paired: false, connected: false)
+        let connected = Self.node(id: "connected", paired: true, connected: true)
+
+        #expect(NodeMenuEntryFormatter.roleText(pairedDisconnected) == "paired · disconnected")
+        #expect(NodeMenuEntryFormatter.roleText(unpairedDisconnected) == "unpaired · disconnected")
+        #expect(NodeMenuEntryFormatter.roleText(connected) == "paired · connected")
+    }
+
+    @Test func `sorted node entries include paired disconnected nodes`() {
+        let injector = MenuSessionsInjector()
+        defer { NodesStore.shared.nodes = [] }
+        NodesStore.shared.nodes = [
+            Self.node(id: "ignored", paired: false, connected: false, displayName: "Ignored"),
+            Self.node(id: "paired", paired: true, connected: false, displayName: "MacBook"),
+            Self.node(id: "connected", paired: true, connected: true, displayName: "iPhone"),
+        ]
+
+        let entries = injector.testingSortedNodeEntries()
+        #expect(entries.map(\.nodeId) == ["connected", "paired"])
+    }
+
+    private static func node(
+        id: String,
+        paired: Bool,
+        connected: Bool,
+        displayName: String? = nil) -> NodeInfo
+    {
+        NodeInfo(
+            nodeId: id,
+            displayName: displayName ?? id,
+            platform: "macOS 26.3.1",
+            version: nil,
+            coreVersion: nil,
+            uiVersion: nil,
+            deviceFamily: "Mac",
+            modelIdentifier: nil,
+            remoteIp: nil,
+            caps: nil,
+            commands: nil,
+            permissions: nil,
+            paired: paired,
+            connected: connected)
+    }
 }

apps/shared/OpenClawKit/Sources/OpenClawKit/GatewayChannel.swift

@@ -1010,10 +1010,13 @@ public actor GatewayChannelActor {
 
     /// Wrap low-level URLSession/WebSocket errors with context so UI can surface them.
     private func wrap(_ error: Error, context: String) -> Error {
-        if error is GatewayConnectAuthError || error is GatewayResponseError || error is GatewayDecodingError {
+        if error is GatewayConnectAuthError || error is GatewayResponseError || error is GatewayDecodingError || error is GatewayTLSValidationError {
             return error
         }
         if let urlError = error as? URLError {
+            if let failure = (self.session as? GatewayTLSFailureProviding)?.consumeLastTLSFailure() {
+                return GatewayTLSValidationError(failure: failure, context: context)
+            }
             let desc = urlError.localizedDescription.isEmpty ? "cancelled" : urlError.localizedDescription
             return NSError(
                 domain: URLError.errorDomain,

apps/shared/OpenClawKit/Sources/OpenClawKit/GatewayConnectionProblem.swift

@@ -30,6 +30,9 @@ public struct GatewayConnectionProblem: Equatable, Sendable {
         case connectionRefused
         case reachabilityFailed
         case websocketCancelled
+        case tlsPinMismatch
+        case tlsCertificateUntrusted
+        case tlsCertificateUnavailable
         case unknown
     }
 
@@ -170,6 +173,9 @@ public enum GatewayConnectionProblemMapper {
         if let responseError = error as? GatewayResponseError {
             return self.map(responseError)
         }
+        if let tlsError = error as? GatewayTLSValidationError {
+            return self.map(tlsError)
+        }
         return self.mapTransportError(error)
     }
 
@@ -518,6 +524,51 @@ public enum GatewayConnectionProblemMapper {
         return nil
     }
 
+    private static func map(_ tlsError: GatewayTLSValidationError) -> GatewayConnectionProblem {
+        let failure = tlsError.failure
+        switch failure.kind {
+        case .pinMismatch:
+            let trustedSuffix = failure.systemTrustOk
+                ? " The new certificate is trusted by this device; this is commonly caused by certificate rotation."
+                : " This device could not verify the new certificate."
+            return GatewayConnectionProblem(
+                kind: .tlsPinMismatch,
+                owner: failure.systemTrustOk ? .network : .unknown,
+                title: "Gateway certificate changed",
+                message: "The saved TLS certificate pin for \(failure.host) no longer matches the gateway certificate.\(trustedSuffix)",
+                actionLabel: "Review certificate",
+                actionCommand: nil,
+                docsURL: URL(string: "https://docs.openclaw.ai/gateway/troubleshooting"),
+                retryable: false,
+                pauseReconnect: true,
+                technicalDetails: tlsError.localizedDescription)
+        case .certificateUnavailable:
+            return GatewayConnectionProblem(
+                kind: .tlsCertificateUnavailable,
+                owner: .network,
+                title: "Gateway certificate unavailable",
+                message: "OpenClaw could not read the gateway certificate for \(failure.host).",
+                actionLabel: "Retry",
+                actionCommand: nil,
+                docsURL: URL(string: "https://docs.openclaw.ai/gateway/troubleshooting"),
+                retryable: true,
+                pauseReconnect: false,
+                technicalDetails: tlsError.localizedDescription)
+        case .untrustedCertificate:
+            return GatewayConnectionProblem(
+                kind: .tlsCertificateUntrusted,
+                owner: .network,
+                title: "Gateway certificate is not trusted",
+                message: "This device does not trust the TLS certificate presented by \(failure.host).",
+                actionLabel: "Check certificate",
+                actionCommand: nil,
+                docsURL: URL(string: "https://docs.openclaw.ai/gateway/troubleshooting"),
+                retryable: false,
+                pauseReconnect: true,
+                technicalDetails: tlsError.localizedDescription)
+        }
+    }
+
     private static func mapTransportError(_ error: Error) -> GatewayConnectionProblem? {
         let nsError = error as NSError
         let rawMessage = nsError.userInfo[NSLocalizedDescriptionKey] as? String ?? nsError.localizedDescription

apps/shared/OpenClawKit/Sources/OpenClawKit/GatewayTLSPinning.swift

@@ -16,6 +16,65 @@ public struct GatewayTLSParams: Sendable {
     }
 }
 
+public enum GatewayTLSValidationFailureKind: String, Sendable {
+    case pinMismatch
+    case certificateUnavailable
+    case untrustedCertificate
+}
+
+public struct GatewayTLSValidationFailure: Equatable, Sendable {
+    public let kind: GatewayTLSValidationFailureKind
+    public let host: String
+    public let storeKey: String?
+    public let expectedFingerprint: String?
+    public let observedFingerprint: String?
+    public let systemTrustOk: Bool
+
+    public init(
+        kind: GatewayTLSValidationFailureKind,
+        host: String,
+        storeKey: String?,
+        expectedFingerprint: String?,
+        observedFingerprint: String?,
+        systemTrustOk: Bool)
+    {
+        self.kind = kind
+        self.host = host
+        self.storeKey = storeKey
+        self.expectedFingerprint = expectedFingerprint
+        self.observedFingerprint = observedFingerprint
+        self.systemTrustOk = systemTrustOk
+    }
+}
+
+public struct GatewayTLSValidationError: LocalizedError, Sendable {
+    public let failure: GatewayTLSValidationFailure
+    public let context: String
+
+    public init(failure: GatewayTLSValidationFailure, context: String) {
+        self.failure = failure
+        self.context = context
+    }
+
+    public var errorDescription: String? {
+        let prefix = self.context.trimmingCharacters(in: .whitespacesAndNewlines)
+        switch self.failure.kind {
+        case .pinMismatch:
+            let expected = self.failure.expectedFingerprint ?? "unknown"
+            let observed = self.failure.observedFingerprint ?? "unknown"
+            return "\(prefix): TLS certificate pin mismatch for \(self.failure.host) (expected \(expected), observed \(observed))"
+        case .certificateUnavailable:
+            return "\(prefix): TLS certificate unavailable for \(self.failure.host)"
+        case .untrustedCertificate:
+            return "\(prefix): TLS certificate is not trusted for \(self.failure.host)"
+        }
+    }
+}
+
+public protocol GatewayTLSFailureProviding: AnyObject {
+    func consumeLastTLSFailure() -> GatewayTLSValidationFailure?
+}
+
 public enum GatewayTLSStore {
     private static let keychainService = "ai.openclaw.tls-pinning"
 
@@ -35,6 +94,15 @@ public enum GatewayTLSStore {
         _ = GenericPasswordKeychainStore.saveString(value, service: self.keychainService, account: stableID)
     }
 
+    @discardableResult
+    public static func replaceFingerprint(_ value: String, stableID: String) -> Bool {
+        guard GenericPasswordKeychainStore.saveString(value, service: self.keychainService, account: stableID) else {
+            return false
+        }
+        self.clearLegacyFingerprint(stableID: stableID)
+        return true
+    }
+
     @discardableResult
     public static func clearFingerprint(stableID: String) -> Bool {
         let removedKeychain = GenericPasswordKeychainStore.delete(
@@ -87,8 +155,10 @@ public enum GatewayTLSStore {
     }
 }
 
-public final class GatewayTLSPinningSession: NSObject, WebSocketSessioning, URLSessionDelegate, @unchecked Sendable {
+public final class GatewayTLSPinningSession: NSObject, WebSocketSessioning, URLSessionDelegate, GatewayTLSFailureProviding, @unchecked Sendable {
     private let params: GatewayTLSParams
+    private let failureLock = NSLock()
+    private var lastTLSFailure: GatewayTLSValidationFailure?
     private lazy var session: URLSession = {
         let config = URLSessionConfiguration.default
         config.waitsForConnectivity = true
@@ -100,6 +170,26 @@ public final class GatewayTLSPinningSession: NSObject, WebSocketSessioning, URLS
         super.init()
     }
 
+    public func consumeLastTLSFailure() -> GatewayTLSValidationFailure? {
+        self.failureLock.lock()
+        defer { self.failureLock.unlock() }
+        let failure = self.lastTLSFailure
+        self.lastTLSFailure = nil
+        return failure
+    }
+
+    private func recordTLSFailure(_ failure: GatewayTLSValidationFailure) {
+        self.failureLock.lock()
+        self.lastTLSFailure = failure
+        self.failureLock.unlock()
+    }
+
+    private func clearTLSFailure() {
+        self.failureLock.lock()
+        self.lastTLSFailure = nil
+        self.failureLock.unlock()
+    }
+
     public func makeWebSocketTask(url: URL) -> WebSocketTaskBox {
         let task = self.session.webSocketTask(with: url)
         task.maximumMessageSize = 16 * 1024 * 1024
@@ -118,12 +208,23 @@ public final class GatewayTLSPinningSession: NSObject, WebSocketSessioning, URLS
             return
         }
 
+        let host = challenge.protectionSpace.host
+        let systemTrustOk = SecTrustEvaluateWithError(trust, nil)
         let expected = self.params.expectedFingerprint.map(normalizeFingerprint)
-        if let fingerprint = certificateFingerprint(trust) {
+        let fingerprint = certificateFingerprint(trust)
+        if let fingerprint {
             if let expected {
                 if fingerprint == expected {
+                    self.clearTLSFailure()
                     completionHandler(.useCredential, URLCredential(trust: trust))
                 } else {
+                    self.recordTLSFailure(GatewayTLSValidationFailure(
+                        kind: .pinMismatch,
+                        host: host,
+                        storeKey: self.params.storeKey,
+                        expectedFingerprint: expected,
+                        observedFingerprint: fingerprint,
+                        systemTrustOk: systemTrustOk))
                     completionHandler(.cancelAuthenticationChallenge, nil)
                 }
                 return
@@ -132,15 +233,23 @@ public final class GatewayTLSPinningSession: NSObject, WebSocketSessioning, URLS
                 if let storeKey = params.storeKey {
                     GatewayTLSStore.saveFingerprint(fingerprint, stableID: storeKey)
                 }
+                self.clearTLSFailure()
                 completionHandler(.useCredential, URLCredential(trust: trust))
                 return
             }
         }
 
-        let ok = SecTrustEvaluateWithError(trust, nil)
-        if ok || !self.params.required {
+        if systemTrustOk || !self.params.required {
+            self.clearTLSFailure()
             completionHandler(.useCredential, URLCredential(trust: trust))
         } else {
+            self.recordTLSFailure(GatewayTLSValidationFailure(
+                kind: fingerprint == nil ? .certificateUnavailable : .untrustedCertificate,
+                host: host,
+                storeKey: self.params.storeKey,
+                expectedFingerprint: expected,
+                observedFingerprint: fingerprint,
+                systemTrustOk: false))
             completionHandler(.cancelAuthenticationChallenge, nil)
         }
     }

apps/shared/OpenClawKit/Tests/OpenClawKitTests/GatewayErrorsTests.swift

@@ -89,4 +89,41 @@ import Testing
 
         #expect(mapped == nil)
     }
+
+    @Test func tlsPinMismatchMapsToActionableProblem() {
+        let error = GatewayTLSValidationError(
+            failure: GatewayTLSValidationFailure(
+                kind: .pinMismatch,
+                host: "gateway.example.ts.net",
+                storeKey: "gateway.example.ts.net:443",
+                expectedFingerprint: "old",
+                observedFingerprint: "new",
+                systemTrustOk: true),
+            context: "connect to gateway")
+
+        let problem = GatewayConnectionProblemMapper.map(error: error)
+
+        #expect(problem?.kind == .tlsPinMismatch)
+        #expect(problem?.retryable == false)
+        #expect(problem?.pauseReconnect == true)
+        #expect(problem?.actionLabel == "Review certificate")
+    }
+
+    @Test func untrustedTLSCertificatePausesReconnect() {
+        let error = GatewayTLSValidationError(
+            failure: GatewayTLSValidationFailure(
+                kind: .untrustedCertificate,
+                host: "gateway.example.com",
+                storeKey: "gateway.example.com:443",
+                expectedFingerprint: nil,
+                observedFingerprint: nil,
+                systemTrustOk: false),
+            context: "connect to gateway")
+
+        let problem = GatewayConnectionProblemMapper.map(error: error)
+
+        #expect(problem?.kind == .tlsCertificateUntrusted)
+        #expect(problem?.retryable == false)
+        #expect(problem?.pauseReconnect == true)
+    }
 }

docs/platforms/mac/remote.md

@@ -83,6 +83,7 @@ node.
 - **Health probe failed**: check SSH reachability, PATH, and that Baileys is logged in (`openclaw status --json`).
 - **Web Chat stuck**: confirm the gateway is running on the remote host and the forwarded port matches the gateway WS port; the UI requires a healthy WS connection.
 - **Node IP shows 127.0.0.1**: expected with the SSH tunnel. Switch **Transport** to **Direct (ws/wss)** if you want the gateway to see the real client IP.
+- **Dashboard works but Mac capabilities are offline**: this means the app's operator/control connection is healthy, but the companion node connection is not connected or is missing its command surface. Open the menu bar device section and check whether the Mac is `paired · disconnected`. For `wss://*.ts.net` Tailscale Serve endpoints, the app detects stale legacy TLS leaf pins after certificate rotation, clears the stale pin when macOS trusts the new certificate, and retries automatically. If the certificate is not system-trusted or the host is not a Tailscale Serve name, review the certificate or switch to **Remote over SSH**.
 - **Voice Wake**: trigger phrases are forwarded automatically in remote mode; no separate forwarder is needed.
 
 ## Notification sounds