Include full contents of all nested repositories

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

openclaw/apps/macos/Sources/OpenClaw/AboutSettings.swift

@@ -0,0 +1,199 @@
+import SwiftUI
+
+struct AboutSettings: View {
+    weak var updater: UpdaterProviding?
+    @State private var iconHover = false
+    @AppStorage("autoUpdateEnabled") private var autoCheckEnabled = true
+    @State private var didLoadUpdaterState = false
+
+    var body: some View {
+        VStack(spacing: 8) {
+            let appIcon = NSApplication.shared.applicationIconImage ?? CritterIconRenderer.makeIcon(blink: 0)
+            Button {
+                if let url = URL(string: "https://github.com/openclaw/openclaw") {
+                    NSWorkspace.shared.open(url)
+                }
+            } label: {
+                Image(nsImage: appIcon)
+                    .resizable()
+                    .frame(width: 160, height: 160)
+                    .cornerRadius(24)
+                    .shadow(color: self.iconHover ? .accentColor.opacity(0.25) : .clear, radius: 10)
+                    .scaleEffect(self.iconHover ? 1.05 : 1.0)
+            }
+            .buttonStyle(.plain)
+            .focusable(false)
+            .pointingHandCursor()
+            .onHover { hover in
+                withAnimation(.spring(response: 0.3, dampingFraction: 0.72)) { self.iconHover = hover }
+            }
+
+            VStack(spacing: 3) {
+                Text("OpenClaw")
+                    .font(.title3.bold())
+                Text("Version \(self.versionString)")
+                    .foregroundStyle(.secondary)
+                if let buildTimestamp {
+                    Text("Built \(buildTimestamp)\(self.buildSuffix)")
+                        .font(.footnote)
+                        .foregroundStyle(.secondary)
+                }
+                Text("Menu bar companion for notifications, screenshots, and privileged agent actions.")
+                    .font(.footnote)
+                    .foregroundStyle(.secondary)
+                    .multilineTextAlignment(.center)
+                    .padding(.horizontal, 18)
+            }
+
+            VStack(alignment: .center, spacing: 6) {
+                AboutLinkRow(
+                    icon: "chevron.left.slash.chevron.right",
+                    title: "GitHub",
+                    url: "https://github.com/openclaw/openclaw")
+                AboutLinkRow(icon: "globe", title: "Website", url: "https://openclaw.ai")
+                AboutLinkRow(icon: "bird", title: "Twitter", url: "https://twitter.com/steipete")
+                AboutLinkRow(icon: "envelope", title: "Email", url: "mailto:peter@steipete.me")
+            }
+            .frame(maxWidth: .infinity)
+            .multilineTextAlignment(.center)
+            .padding(.vertical, 10)
+
+            if let updater {
+                Divider()
+                    .padding(.vertical, 8)
+
+                if updater.isAvailable {
+                    VStack(spacing: 10) {
+                        Toggle("Check for updates automatically", isOn: self.$autoCheckEnabled)
+                            .toggleStyle(.checkbox)
+                            .frame(maxWidth: .infinity, alignment: .center)
+
+                        Button("Check for Updates…") { updater.checkForUpdates(nil) }
+                    }
+                } else {
+                    Text("Updates unavailable in this build.")
+                        .foregroundStyle(.secondary)
+                        .padding(.top, 4)
+                }
+            }
+
+            Text("© 2025 Peter Steinberger — MIT License.")
+                .font(.footnote)
+                .foregroundStyle(.secondary)
+                .padding(.top, 4)
+
+            Spacer()
+        }
+        .frame(maxWidth: .infinity, maxHeight: .infinity)
+        .padding(.top, 4)
+        .padding(.horizontal, 24)
+        .padding(.bottom, 24)
+        .onAppear {
+            guard let updater, !self.didLoadUpdaterState else { return }
+            // Keep Sparkle’s auto-check setting in sync with the persisted toggle.
+            updater.automaticallyChecksForUpdates = self.autoCheckEnabled
+            updater.automaticallyDownloadsUpdates = self.autoCheckEnabled
+            self.didLoadUpdaterState = true
+        }
+        .onChange(of: self.autoCheckEnabled) { _, newValue in
+            self.updater?.automaticallyChecksForUpdates = newValue
+            self.updater?.automaticallyDownloadsUpdates = newValue
+        }
+    }
+
+    private var versionString: String {
+        let version = Bundle.main.object(forInfoDictionaryKey: "CFBundleShortVersionString") as? String ?? "dev"
+        let build = Bundle.main.object(forInfoDictionaryKey: "CFBundleVersion") as? String
+        return build.map { "\(version) (\($0))" } ?? version
+    }
+
+    private var buildTimestamp: String? {
+        guard
+            let raw =
+            (Bundle.main.object(forInfoDictionaryKey: "OpenClawBuildTimestamp") as? String) ??
+            (Bundle.main.object(forInfoDictionaryKey: "OpenClawBuildTimestamp") as? String)
+        else { return nil }
+        let parser = ISO8601DateFormatter()
+        parser.formatOptions = [.withInternetDateTime]
+        guard let date = parser.date(from: raw) else { return raw }
+
+        let formatter = DateFormatter()
+        formatter.dateStyle = .medium
+        formatter.timeStyle = .short
+        formatter.locale = .current
+        return formatter.string(from: date)
+    }
+
+    private var gitCommit: String {
+        (Bundle.main.object(forInfoDictionaryKey: "OpenClawGitCommit") as? String) ??
+            (Bundle.main.object(forInfoDictionaryKey: "OpenClawGitCommit") as? String) ??
+            "unknown"
+    }
+
+    private var bundleID: String {
+        Bundle.main.bundleIdentifier ?? "unknown"
+    }
+
+    private var buildSuffix: String {
+        let git = self.gitCommit
+        guard !git.isEmpty, git != "unknown" else { return "" }
+
+        var suffix = " (\(git)"
+        #if DEBUG
+        suffix += " DEBUG"
+        #endif
+        suffix += ")"
+        return suffix
+    }
+}
+
+@MainActor
+private struct AboutLinkRow: View {
+    let icon: String
+    let title: String
+    let url: String
+
+    @State private var hovering = false
+
+    var body: some View {
+        Button {
+            if let url = URL(string: url) { NSWorkspace.shared.open(url) }
+        } label: {
+            HStack(spacing: 6) {
+                Image(systemName: self.icon)
+                Text(self.title)
+                    .underline(self.hovering, color: .accentColor)
+            }
+            .foregroundColor(.accentColor)
+        }
+        .buttonStyle(.plain)
+        .onHover { self.hovering = $0 }
+        .pointingHandCursor()
+    }
+}
+
+private struct AboutMetaRow: View {
+    let label: String
+    let value: String
+
+    var body: some View {
+        HStack {
+            Text(self.label)
+                .foregroundStyle(.secondary)
+            Spacer()
+            Text(self.value)
+                .font(.caption.monospaced())
+                .foregroundStyle(.primary)
+        }
+    }
+}
+
+#if DEBUG
+struct AboutSettings_Previews: PreviewProvider {
+    private static let updater = DisabledUpdaterController()
+    static var previews: some View {
+        AboutSettings(updater: updater)
+            .frame(width: SettingsTab.windowWidth, height: SettingsTab.windowHeight)
+    }
+}
+#endif

openclaw/apps/macos/Sources/OpenClaw/AgeFormatting.swift

@@ -0,0 +1,17 @@
+import Foundation
+
+/// Human-friendly age string (e.g., "2m ago").
+func age(from date: Date, now: Date = .init()) -> String {
+    let seconds = max(0, Int(now.timeIntervalSince(date)))
+    let minutes = seconds / 60
+    let hours = minutes / 60
+    let days = hours / 24
+
+    if seconds < 60 { return "just now" }
+    if minutes == 1 { return "1 minute ago" }
+    if minutes < 60 { return "\(minutes)m ago" }
+    if hours == 1 { return "1 hour ago" }
+    if hours < 24 { return "\(hours)h ago" }
+    if days == 1 { return "yesterday" }
+    return "\(days)d ago"
+}

openclaw/apps/macos/Sources/OpenClaw/AgentEventStore.swift

@@ -0,0 +1,22 @@
+import Foundation
+import Observation
+
+@MainActor
+@Observable
+final class AgentEventStore {
+    static let shared = AgentEventStore()
+
+    private(set) var events: [ControlAgentEvent] = []
+    private let maxEvents = 400
+
+    func append(_ event: ControlAgentEvent) {
+        self.events.append(event)
+        if self.events.count > self.maxEvents {
+            self.events.removeFirst(self.events.count - self.maxEvents)
+        }
+    }
+
+    func clear() {
+        self.events.removeAll()
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/AgentEventsWindow.swift

@@ -0,0 +1,109 @@
+import OpenClawProtocol
+import SwiftUI
+
+@MainActor
+struct AgentEventsWindow: View {
+    private let store = AgentEventStore.shared
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 6) {
+            HStack {
+                Text("Agent Events")
+                    .font(.title3.weight(.semibold))
+                Spacer()
+                Button("Clear") { self.store.clear() }
+                    .buttonStyle(.bordered)
+            }
+            .padding(.bottom, 4)
+
+            ScrollView {
+                LazyVStack(alignment: .leading, spacing: 8) {
+                    ForEach(self.store.events.reversed(), id: \.seq) { evt in
+                        EventRow(event: evt)
+                    }
+                }
+            }
+        }
+        .padding(12)
+        .frame(minWidth: 520, minHeight: 360)
+    }
+}
+
+private struct EventRow: View {
+    let event: ControlAgentEvent
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 2) {
+            HStack(spacing: 6) {
+                Text(self.event.stream.uppercased())
+                    .font(.caption2.weight(.bold))
+                    .padding(.horizontal, 6)
+                    .padding(.vertical, 2)
+                    .background(self.tint)
+                    .foregroundStyle(Color.white)
+                    .clipShape(RoundedRectangle(cornerRadius: 5, style: .continuous))
+                Text("run " + self.event.runId)
+                    .font(.caption.monospaced())
+                    .foregroundStyle(.secondary)
+                Spacer()
+                Text(self.formattedTs)
+                    .font(.caption2)
+                    .foregroundStyle(.secondary)
+            }
+            if let json = self.prettyJSON(event.data) {
+                Text(json)
+                    .font(.caption.monospaced())
+                    .foregroundStyle(.primary)
+                    .textSelection(.enabled)
+                    .frame(maxWidth: .infinity, alignment: .leading)
+                    .padding(.top, 2)
+            }
+        }
+        .padding(8)
+        .background(
+            RoundedRectangle(cornerRadius: 8, style: .continuous)
+                .fill(Color.primary.opacity(0.04)))
+    }
+
+    private var tint: Color {
+        switch self.event.stream {
+        case "job": .blue
+        case "tool": .orange
+        case "assistant": .green
+        default: .gray
+        }
+    }
+
+    private var formattedTs: String {
+        let date = Date(timeIntervalSince1970: event.ts / 1000)
+        let f = DateFormatter()
+        f.dateFormat = "HH:mm:ss.SSS"
+        return f.string(from: date)
+    }
+
+    private func prettyJSON(_ dict: [String: OpenClawProtocol.AnyCodable]) -> String? {
+        let normalized = dict.mapValues { $0.value }
+        guard JSONSerialization.isValidJSONObject(normalized),
+              let data = try? JSONSerialization.data(withJSONObject: normalized, options: [.prettyPrinted]),
+              let str = String(data: data, encoding: .utf8)
+        else { return nil }
+        return str
+    }
+}
+
+struct AgentEventsWindow_Previews: PreviewProvider {
+    static var previews: some View {
+        let sample = ControlAgentEvent(
+            runId: "abc",
+            seq: 1,
+            stream: "tool",
+            ts: Date().timeIntervalSince1970 * 1000,
+            data: [
+                "phase": OpenClawProtocol.AnyCodable("start"),
+                "name": OpenClawProtocol.AnyCodable("bash"),
+            ],
+            summary: nil)
+        AgentEventStore.shared.append(sample)
+        return AgentEventsWindow()
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/AgentWorkspace.swift

@@ -0,0 +1,343 @@
+import Foundation
+import OSLog
+
+enum AgentWorkspace {
+    private static let logger = Logger(subsystem: "ai.openclaw", category: "workspace")
+    static let agentsFilename = "AGENTS.md"
+    static let soulFilename = "SOUL.md"
+    static let identityFilename = "IDENTITY.md"
+    static let userFilename = "USER.md"
+    static let bootstrapFilename = "BOOTSTRAP.md"
+    private static let templateDirname = "templates"
+    private static let ignoredEntries: Set<String> = [".DS_Store", ".git", ".gitignore"]
+    private static let templateEntries: Set<String> = [
+        AgentWorkspace.agentsFilename,
+        AgentWorkspace.soulFilename,
+        AgentWorkspace.identityFilename,
+        AgentWorkspace.userFilename,
+        AgentWorkspace.bootstrapFilename,
+    ]
+    struct BootstrapSafety: Equatable {
+        let unsafeReason: String?
+
+        static let safe = Self(unsafeReason: nil)
+
+        static func blocked(_ reason: String) -> Self {
+            Self(unsafeReason: reason)
+        }
+    }
+
+    static func displayPath(for url: URL) -> String {
+        let home = FileManager().homeDirectoryForCurrentUser.path
+        let path = url.path
+        if path == home { return "~" }
+        if path.hasPrefix(home + "/") {
+            return "~/" + String(path.dropFirst(home.count + 1))
+        }
+        return path
+    }
+
+    static func resolveWorkspaceURL(from userInput: String?) -> URL {
+        let trimmed = userInput?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        if trimmed.isEmpty { return OpenClawConfigFile.defaultWorkspaceURL() }
+        let expanded = (trimmed as NSString).expandingTildeInPath
+        return URL(fileURLWithPath: expanded, isDirectory: true)
+    }
+
+    static func agentsURL(workspaceURL: URL) -> URL {
+        workspaceURL.appendingPathComponent(self.agentsFilename)
+    }
+
+    static func workspaceEntries(workspaceURL: URL) throws -> [String] {
+        let contents = try FileManager().contentsOfDirectory(atPath: workspaceURL.path)
+        return contents.filter { !self.ignoredEntries.contains($0) }
+    }
+
+    static func isWorkspaceEmpty(workspaceURL: URL) -> Bool {
+        let fm = FileManager()
+        var isDir: ObjCBool = false
+        if !fm.fileExists(atPath: workspaceURL.path, isDirectory: &isDir) {
+            return true
+        }
+        guard isDir.boolValue else { return false }
+        guard let entries = try? self.workspaceEntries(workspaceURL: workspaceURL) else { return false }
+        return entries.isEmpty
+    }
+
+    static func isTemplateOnlyWorkspace(workspaceURL: URL) -> Bool {
+        guard let entries = try? self.workspaceEntries(workspaceURL: workspaceURL) else { return false }
+        guard !entries.isEmpty else { return true }
+        return Set(entries).isSubset(of: self.templateEntries)
+    }
+
+    static func bootstrapSafety(for workspaceURL: URL) -> BootstrapSafety {
+        let fm = FileManager()
+        var isDir: ObjCBool = false
+        if !fm.fileExists(atPath: workspaceURL.path, isDirectory: &isDir) {
+            return .safe
+        }
+        if !isDir.boolValue { return .blocked("Workspace path points to a file.") }
+        let agentsURL = self.agentsURL(workspaceURL: workspaceURL)
+        if fm.fileExists(atPath: agentsURL.path) {
+            return .safe
+        }
+        do {
+            let entries = try self.workspaceEntries(workspaceURL: workspaceURL)
+            return entries.isEmpty
+                ? .safe
+                : .blocked("Folder isn't empty. Choose a new folder or add AGENTS.md first.")
+        } catch {
+            return .blocked("Couldn't inspect the workspace folder.")
+        }
+    }
+
+    static func bootstrap(workspaceURL: URL) throws -> URL {
+        let shouldSeedBootstrap = self.isWorkspaceEmpty(workspaceURL: workspaceURL)
+        try FileManager().createDirectory(at: workspaceURL, withIntermediateDirectories: true)
+        let agentsURL = self.agentsURL(workspaceURL: workspaceURL)
+        if !FileManager().fileExists(atPath: agentsURL.path) {
+            try self.defaultTemplate().write(to: agentsURL, atomically: true, encoding: .utf8)
+            self.logger.info("Created AGENTS.md at \(agentsURL.path, privacy: .public)")
+        }
+        let soulURL = workspaceURL.appendingPathComponent(self.soulFilename)
+        if !FileManager().fileExists(atPath: soulURL.path) {
+            try self.defaultSoulTemplate().write(to: soulURL, atomically: true, encoding: .utf8)
+            self.logger.info("Created SOUL.md at \(soulURL.path, privacy: .public)")
+        }
+        let identityURL = workspaceURL.appendingPathComponent(self.identityFilename)
+        if !FileManager().fileExists(atPath: identityURL.path) {
+            try self.defaultIdentityTemplate().write(to: identityURL, atomically: true, encoding: .utf8)
+            self.logger.info("Created IDENTITY.md at \(identityURL.path, privacy: .public)")
+        }
+        let userURL = workspaceURL.appendingPathComponent(self.userFilename)
+        if !FileManager().fileExists(atPath: userURL.path) {
+            try self.defaultUserTemplate().write(to: userURL, atomically: true, encoding: .utf8)
+            self.logger.info("Created USER.md at \(userURL.path, privacy: .public)")
+        }
+        let bootstrapURL = workspaceURL.appendingPathComponent(self.bootstrapFilename)
+        if shouldSeedBootstrap, !FileManager().fileExists(atPath: bootstrapURL.path) {
+            try self.defaultBootstrapTemplate().write(to: bootstrapURL, atomically: true, encoding: .utf8)
+            self.logger.info("Created BOOTSTRAP.md at \(bootstrapURL.path, privacy: .public)")
+        }
+        return agentsURL
+    }
+
+    static func needsBootstrap(workspaceURL: URL) -> Bool {
+        let fm = FileManager()
+        var isDir: ObjCBool = false
+        if !fm.fileExists(atPath: workspaceURL.path, isDirectory: &isDir) {
+            return true
+        }
+        guard isDir.boolValue else { return true }
+        if self.hasIdentity(workspaceURL: workspaceURL) {
+            return false
+        }
+        let bootstrapURL = workspaceURL.appendingPathComponent(self.bootstrapFilename)
+        guard fm.fileExists(atPath: bootstrapURL.path) else { return false }
+        return self.isTemplateOnlyWorkspace(workspaceURL: workspaceURL)
+    }
+
+    static func hasIdentity(workspaceURL: URL) -> Bool {
+        let identityURL = workspaceURL.appendingPathComponent(self.identityFilename)
+        guard let contents = try? String(contentsOf: identityURL, encoding: .utf8) else { return false }
+        return self.identityLinesHaveValues(contents)
+    }
+
+    private static func identityLinesHaveValues(_ content: String) -> Bool {
+        for line in content.split(separator: "\n") {
+            let trimmed = line.trimmingCharacters(in: .whitespacesAndNewlines)
+            guard trimmed.hasPrefix("-"), let colon = trimmed.firstIndex(of: ":") else { continue }
+            let value = trimmed[trimmed.index(after: colon)...].trimmingCharacters(in: .whitespacesAndNewlines)
+            if !value.isEmpty {
+                return true
+            }
+        }
+        return false
+    }
+
+    static func defaultTemplate() -> String {
+        let fallback = """
+        # AGENTS.md - OpenClaw Workspace
+
+        This folder is the assistant's working directory.
+
+        ## First run (one-time)
+        - If BOOTSTRAP.md exists, follow its ritual and delete it once complete.
+        - Your agent identity lives in IDENTITY.md.
+        - Your profile lives in USER.md.
+
+        ## Backup tip (recommended)
+        If you treat this workspace as the agent's "memory", make it a git repo (ideally private) so identity
+        and notes are backed up.
+
+        ```bash
+        git init
+        git add AGENTS.md
+        git commit -m "Add agent workspace"
+        ```
+
+        ## Safety defaults
+        - Don't exfiltrate secrets or private data.
+        - Don't run destructive commands unless explicitly asked.
+        - Be concise in chat; write longer output to files in this workspace.
+
+        ## Daily memory (recommended)
+        - Keep a short daily log at memory/YYYY-MM-DD.md (create memory/ if needed).
+        - On session start, read today + yesterday if present.
+        - Capture durable facts, preferences, and decisions; avoid secrets.
+
+        ## Customize
+        - Add your preferred style, rules, and "memory" here.
+        """
+        return self.loadTemplate(named: self.agentsFilename, fallback: fallback)
+    }
+
+    static func defaultSoulTemplate() -> String {
+        let fallback = """
+        # SOUL.md - Persona & Boundaries
+
+        Describe who the assistant is, tone, and boundaries.
+
+        - Keep replies concise and direct.
+        - Ask clarifying questions when needed.
+        - Never send streaming/partial replies to external messaging surfaces.
+        """
+        return self.loadTemplate(named: self.soulFilename, fallback: fallback)
+    }
+
+    static func defaultIdentityTemplate() -> String {
+        let fallback = """
+        # IDENTITY.md - Agent Identity
+
+        - Name:
+        - Creature:
+        - Vibe:
+        - Emoji:
+        """
+        return self.loadTemplate(named: self.identityFilename, fallback: fallback)
+    }
+
+    static func defaultUserTemplate() -> String {
+        let fallback = """
+        # USER.md - User Profile
+
+        - Name:
+        - Preferred address:
+        - Pronouns (optional):
+        - Timezone (optional):
+        - Notes:
+        """
+        return self.loadTemplate(named: self.userFilename, fallback: fallback)
+    }
+
+    static func defaultBootstrapTemplate() -> String {
+        let fallback = """
+        # BOOTSTRAP.md - First Run Ritual (delete after)
+
+        Hello. I was just born.
+
+        ## Your mission
+        Start a short, playful conversation and learn:
+        - Who am I?
+        - What am I?
+        - Who are you?
+        - How should I call you?
+
+        ## How to ask (cute + helpful)
+        Say:
+        "Hello! I was just born. Who am I? What am I? Who are you? How should I call you?"
+
+        Then offer suggestions:
+        - 3-5 name ideas.
+        - 3-5 creature/vibe combos.
+        - 5 emoji ideas.
+
+        ## Write these files
+        After the user chooses, update:
+
+        1) IDENTITY.md
+        - Name
+        - Creature
+        - Vibe
+        - Emoji
+
+        2) USER.md
+        - Name
+        - Preferred address
+        - Pronouns (optional)
+        - Timezone (optional)
+        - Notes
+
+        3) ~/.openclaw/openclaw.json
+        Set identity.name, identity.theme, identity.emoji to match IDENTITY.md.
+
+        ## Cleanup
+        Delete BOOTSTRAP.md once this is complete.
+        """
+        return self.loadTemplate(named: self.bootstrapFilename, fallback: fallback)
+    }
+
+    private static func loadTemplate(named: String, fallback: String) -> String {
+        for url in self.templateURLs(named: named) {
+            if let content = try? String(contentsOf: url, encoding: .utf8) {
+                let stripped = self.stripFrontMatter(content)
+                if !stripped.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+                    return stripped
+                }
+            }
+        }
+        return fallback
+    }
+
+    private static func templateURLs(named: String) -> [URL] {
+        var urls: [URL] = []
+        if let resource = Bundle.main.url(
+            forResource: named.replacingOccurrences(of: ".md", with: ""),
+            withExtension: "md",
+            subdirectory: self.templateDirname)
+        {
+            urls.append(resource)
+        }
+        if let resource = Bundle.main.url(
+            forResource: named,
+            withExtension: nil,
+            subdirectory: self.templateDirname)
+        {
+            urls.append(resource)
+        }
+        if let dev = self.devTemplateURL(named: named) {
+            urls.append(dev)
+        }
+        let cwd = URL(fileURLWithPath: FileManager().currentDirectoryPath)
+        urls.append(cwd.appendingPathComponent("docs")
+            .appendingPathComponent(self.templateDirname)
+            .appendingPathComponent(named))
+        return urls
+    }
+
+    private static func devTemplateURL(named: String) -> URL? {
+        let sourceURL = URL(fileURLWithPath: #filePath)
+        let repoRoot = sourceURL
+            .deletingLastPathComponent()
+            .deletingLastPathComponent()
+            .deletingLastPathComponent()
+            .deletingLastPathComponent()
+            .deletingLastPathComponent()
+        return repoRoot.appendingPathComponent("docs")
+            .appendingPathComponent(self.templateDirname)
+            .appendingPathComponent(named)
+    }
+
+    private static func stripFrontMatter(_ content: String) -> String {
+        guard content.hasPrefix("---") else { return content }
+        let start = content.index(content.startIndex, offsetBy: 3)
+        guard let range = content.range(of: "\n---", range: start..<content.endIndex) else {
+            return content
+        }
+        let remainder = content[range.upperBound...]
+        let trimmed = remainder.trimmingCharacters(in: .whitespacesAndNewlines)
+        return trimmed + "\n"
+    }
+
+    // Identity is written by the agent during the bootstrap ritual.
+}

openclaw/apps/macos/Sources/OpenClaw/AnyCodable+Helpers.swift

@@ -0,0 +1,43 @@
+import Foundation
+import OpenClawKit
+
+// Prefer the OpenClawKit wrapper to keep gateway request payloads consistent.
+typealias AnyCodable = OpenClawKit.AnyCodable
+typealias InstanceIdentity = OpenClawKit.InstanceIdentity
+
+extension AnyCodable {
+    var stringValue: String? {
+        self.value as? String
+    }
+
+    var boolValue: Bool? {
+        self.value as? Bool
+    }
+
+    var intValue: Int? {
+        self.value as? Int
+    }
+
+    var doubleValue: Double? {
+        self.value as? Double
+    }
+
+    var dictionaryValue: [String: AnyCodable]? {
+        self.value as? [String: AnyCodable]
+    }
+
+    var arrayValue: [AnyCodable]? {
+        self.value as? [AnyCodable]
+    }
+
+    var foundationValue: Any {
+        switch self.value {
+        case let dict as [String: AnyCodable]:
+            dict.mapValues { $0.foundationValue }
+        case let array as [AnyCodable]:
+            array.map(\.foundationValue)
+        default:
+            self.value
+        }
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/AppState.swift

@@ -0,0 +1,731 @@
+import AppKit
+import Foundation
+import Observation
+import ServiceManagement
+import SwiftUI
+
+@MainActor
+@Observable
+final class AppState {
+    private let isPreview: Bool
+    private var isInitializing = true
+    private var configWatcher: ConfigFileWatcher?
+    private var suppressVoiceWakeGlobalSync = false
+    private var voiceWakeGlobalSyncTask: Task<Void, Never>?
+
+    private func ifNotPreview(_ action: () -> Void) {
+        guard !self.isPreview else { return }
+        action()
+    }
+
+    enum ConnectionMode: String {
+        case unconfigured
+        case local
+        case remote
+    }
+
+    enum RemoteTransport: String {
+        case ssh
+        case direct
+    }
+
+    var isPaused: Bool {
+        didSet { self.ifNotPreview { UserDefaults.standard.set(self.isPaused, forKey: pauseDefaultsKey) } }
+    }
+
+    var launchAtLogin: Bool {
+        didSet {
+            guard !self.isInitializing else { return }
+            self.ifNotPreview { Task { AppStateStore.updateLaunchAtLogin(enabled: self.launchAtLogin) } }
+        }
+    }
+
+    var onboardingSeen: Bool {
+        didSet { self.ifNotPreview { UserDefaults.standard.set(self.onboardingSeen, forKey: onboardingSeenKey) }
+        }
+    }
+
+    var debugPaneEnabled: Bool {
+        didSet {
+            self.ifNotPreview { UserDefaults.standard.set(self.debugPaneEnabled, forKey: debugPaneEnabledKey) }
+            CanvasManager.shared.refreshDebugStatus()
+        }
+    }
+
+    var swabbleEnabled: Bool {
+        didSet {
+            self.ifNotPreview {
+                UserDefaults.standard.set(self.swabbleEnabled, forKey: swabbleEnabledKey)
+                Task { await VoiceWakeRuntime.shared.refresh(state: self) }
+            }
+        }
+    }
+
+    var swabbleTriggerWords: [String] {
+        didSet {
+            // Preserve the raw editing state; sanitization happens when we actually use the triggers.
+            self.ifNotPreview {
+                UserDefaults.standard.set(self.swabbleTriggerWords, forKey: swabbleTriggersKey)
+                if self.swabbleEnabled {
+                    Task { await VoiceWakeRuntime.shared.refresh(state: self) }
+                }
+                self.scheduleVoiceWakeGlobalSyncIfNeeded()
+            }
+        }
+    }
+
+    var voiceWakeTriggerChime: VoiceWakeChime {
+        didSet { self.ifNotPreview { self.storeChime(self.voiceWakeTriggerChime, key: voiceWakeTriggerChimeKey) } }
+    }
+
+    var voiceWakeSendChime: VoiceWakeChime {
+        didSet { self.ifNotPreview { self.storeChime(self.voiceWakeSendChime, key: voiceWakeSendChimeKey) } }
+    }
+
+    var iconAnimationsEnabled: Bool {
+        didSet { self.ifNotPreview { UserDefaults.standard.set(
+            self.iconAnimationsEnabled,
+            forKey: iconAnimationsEnabledKey) } }
+    }
+
+    var showDockIcon: Bool {
+        didSet {
+            self.ifNotPreview {
+                UserDefaults.standard.set(self.showDockIcon, forKey: showDockIconKey)
+                AppActivationPolicy.apply(showDockIcon: self.showDockIcon)
+            }
+        }
+    }
+
+    var voiceWakeMicID: String {
+        didSet {
+            self.ifNotPreview {
+                UserDefaults.standard.set(self.voiceWakeMicID, forKey: voiceWakeMicKey)
+                if self.swabbleEnabled {
+                    Task { await VoiceWakeRuntime.shared.refresh(state: self) }
+                }
+            }
+        }
+    }
+
+    var voiceWakeMicName: String {
+        didSet { self.ifNotPreview { UserDefaults.standard.set(self.voiceWakeMicName, forKey: voiceWakeMicNameKey) } }
+    }
+
+    var voiceWakeLocaleID: String {
+        didSet {
+            self.ifNotPreview {
+                UserDefaults.standard.set(self.voiceWakeLocaleID, forKey: voiceWakeLocaleKey)
+                if self.swabbleEnabled {
+                    Task { await VoiceWakeRuntime.shared.refresh(state: self) }
+                }
+            }
+        }
+    }
+
+    var voiceWakeAdditionalLocaleIDs: [String] {
+        didSet { self.ifNotPreview { UserDefaults.standard.set(
+            self.voiceWakeAdditionalLocaleIDs,
+            forKey: voiceWakeAdditionalLocalesKey) } }
+    }
+
+    var voicePushToTalkEnabled: Bool {
+        didSet { self.ifNotPreview { UserDefaults.standard.set(
+            self.voicePushToTalkEnabled,
+            forKey: voicePushToTalkEnabledKey) } }
+    }
+
+    var talkEnabled: Bool {
+        didSet {
+            self.ifNotPreview {
+                UserDefaults.standard.set(self.talkEnabled, forKey: talkEnabledKey)
+                Task { await TalkModeController.shared.setEnabled(self.talkEnabled) }
+            }
+        }
+    }
+
+    /// Gateway-provided UI accent color (hex). Optional; clients provide a default.
+    var seamColorHex: String?
+
+    var iconOverride: IconOverrideSelection {
+        didSet { self.ifNotPreview { UserDefaults.standard.set(self.iconOverride.rawValue, forKey: iconOverrideKey) } }
+    }
+
+    var isWorking: Bool = false
+    var earBoostActive: Bool = false
+    var blinkTick: Int = 0
+    var sendCelebrationTick: Int = 0
+    var heartbeatsEnabled: Bool {
+        didSet {
+            self.ifNotPreview {
+                UserDefaults.standard.set(self.heartbeatsEnabled, forKey: heartbeatsEnabledKey)
+                Task { _ = await GatewayConnection.shared.setHeartbeatsEnabled(self.heartbeatsEnabled) }
+            }
+        }
+    }
+
+    var connectionMode: ConnectionMode {
+        didSet {
+            self.ifNotPreview { UserDefaults.standard.set(self.connectionMode.rawValue, forKey: connectionModeKey) }
+            self.syncGatewayConfigIfNeeded()
+        }
+    }
+
+    var remoteTransport: RemoteTransport {
+        didSet { self.syncGatewayConfigIfNeeded() }
+    }
+
+    var canvasEnabled: Bool {
+        didSet { self.ifNotPreview { UserDefaults.standard.set(self.canvasEnabled, forKey: canvasEnabledKey) } }
+    }
+
+    var execApprovalMode: ExecApprovalQuickMode {
+        didSet {
+            self.ifNotPreview {
+                ExecApprovalsStore.updateDefaults { defaults in
+                    defaults.security = self.execApprovalMode.security
+                    defaults.ask = self.execApprovalMode.ask
+                }
+            }
+        }
+    }
+
+    /// Tracks whether the Canvas panel is currently visible (not persisted).
+    var canvasPanelVisible: Bool = false
+
+    var peekabooBridgeEnabled: Bool {
+        didSet {
+            self.ifNotPreview {
+                UserDefaults.standard.set(self.peekabooBridgeEnabled, forKey: peekabooBridgeEnabledKey)
+                Task { await PeekabooBridgeHostCoordinator.shared.setEnabled(self.peekabooBridgeEnabled) }
+            }
+        }
+    }
+
+    var remoteTarget: String {
+        didSet {
+            self.ifNotPreview { UserDefaults.standard.set(self.remoteTarget, forKey: remoteTargetKey) }
+            self.syncGatewayConfigIfNeeded()
+        }
+    }
+
+    var remoteUrl: String {
+        didSet { self.syncGatewayConfigIfNeeded() }
+    }
+
+    var remoteIdentity: String {
+        didSet { self.ifNotPreview { UserDefaults.standard.set(self.remoteIdentity, forKey: remoteIdentityKey) } }
+    }
+
+    var remoteProjectRoot: String {
+        didSet { self.ifNotPreview { UserDefaults.standard.set(self.remoteProjectRoot, forKey: remoteProjectRootKey) } }
+    }
+
+    var remoteCliPath: String {
+        didSet { self.ifNotPreview { UserDefaults.standard.set(self.remoteCliPath, forKey: remoteCliPathKey) } }
+    }
+
+    private var earBoostTask: Task<Void, Never>?
+
+    init(preview: Bool = false) {
+        let isPreview = preview || ProcessInfo.processInfo.isRunningTests
+        self.isPreview = isPreview
+        if !isPreview {
+            migrateLegacyDefaults()
+        }
+        let onboardingSeen = UserDefaults.standard.bool(forKey: onboardingSeenKey)
+        self.isPaused = UserDefaults.standard.bool(forKey: pauseDefaultsKey)
+        self.launchAtLogin = false
+        self.onboardingSeen = onboardingSeen
+        self.debugPaneEnabled = UserDefaults.standard.bool(forKey: debugPaneEnabledKey)
+        let savedVoiceWake = UserDefaults.standard.bool(forKey: swabbleEnabledKey)
+        self.swabbleEnabled = voiceWakeSupported ? savedVoiceWake : false
+        self.swabbleTriggerWords = UserDefaults.standard
+            .stringArray(forKey: swabbleTriggersKey) ?? defaultVoiceWakeTriggers
+        self.voiceWakeTriggerChime = Self.loadChime(
+            key: voiceWakeTriggerChimeKey,
+            fallback: .system(name: "Glass"))
+        self.voiceWakeSendChime = Self.loadChime(
+            key: voiceWakeSendChimeKey,
+            fallback: .system(name: "Glass"))
+        if let storedIconAnimations = UserDefaults.standard.object(forKey: iconAnimationsEnabledKey) as? Bool {
+            self.iconAnimationsEnabled = storedIconAnimations
+        } else {
+            self.iconAnimationsEnabled = true
+            UserDefaults.standard.set(true, forKey: iconAnimationsEnabledKey)
+        }
+        self.showDockIcon = UserDefaults.standard.bool(forKey: showDockIconKey)
+        self.voiceWakeMicID = UserDefaults.standard.string(forKey: voiceWakeMicKey) ?? ""
+        self.voiceWakeMicName = UserDefaults.standard.string(forKey: voiceWakeMicNameKey) ?? ""
+        self.voiceWakeLocaleID = UserDefaults.standard.string(forKey: voiceWakeLocaleKey) ?? Locale.current.identifier
+        self.voiceWakeAdditionalLocaleIDs = UserDefaults.standard
+            .stringArray(forKey: voiceWakeAdditionalLocalesKey) ?? []
+        self.voicePushToTalkEnabled = UserDefaults.standard
+            .object(forKey: voicePushToTalkEnabledKey) as? Bool ?? false
+        self.talkEnabled = UserDefaults.standard.bool(forKey: talkEnabledKey)
+        self.seamColorHex = nil
+        if let storedHeartbeats = UserDefaults.standard.object(forKey: heartbeatsEnabledKey) as? Bool {
+            self.heartbeatsEnabled = storedHeartbeats
+        } else {
+            self.heartbeatsEnabled = true
+            UserDefaults.standard.set(true, forKey: heartbeatsEnabledKey)
+        }
+        if let storedOverride = UserDefaults.standard.string(forKey: iconOverrideKey),
+           let selection = IconOverrideSelection(rawValue: storedOverride)
+        {
+            self.iconOverride = selection
+        } else {
+            self.iconOverride = .system
+            UserDefaults.standard.set(IconOverrideSelection.system.rawValue, forKey: iconOverrideKey)
+        }
+
+        let configRoot = OpenClawConfigFile.loadDict()
+        let configRemoteUrl = GatewayRemoteConfig.resolveUrlString(root: configRoot)
+        let configRemoteTransport = GatewayRemoteConfig.resolveTransport(root: configRoot)
+        let resolvedConnectionMode = ConnectionModeResolver.resolve(root: configRoot).mode
+        self.remoteTransport = configRemoteTransport
+        self.connectionMode = resolvedConnectionMode
+
+        let storedRemoteTarget = UserDefaults.standard.string(forKey: remoteTargetKey) ?? ""
+        if resolvedConnectionMode == .remote,
+           configRemoteTransport != .direct,
+           storedRemoteTarget.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty,
+           let host = AppState.remoteHost(from: configRemoteUrl)
+        {
+            self.remoteTarget = "\(NSUserName())@\(host)"
+        } else {
+            self.remoteTarget = storedRemoteTarget
+        }
+        self.remoteUrl = configRemoteUrl ?? ""
+        self.remoteIdentity = UserDefaults.standard.string(forKey: remoteIdentityKey) ?? ""
+        self.remoteProjectRoot = UserDefaults.standard.string(forKey: remoteProjectRootKey) ?? ""
+        self.remoteCliPath = UserDefaults.standard.string(forKey: remoteCliPathKey) ?? ""
+        self.canvasEnabled = UserDefaults.standard.object(forKey: canvasEnabledKey) as? Bool ?? true
+        let execDefaults = ExecApprovalsStore.resolveDefaults()
+        self.execApprovalMode = ExecApprovalQuickMode.from(security: execDefaults.security, ask: execDefaults.ask)
+        self.peekabooBridgeEnabled = UserDefaults.standard
+            .object(forKey: peekabooBridgeEnabledKey) as? Bool ?? true
+        if !self.isPreview {
+            Task.detached(priority: .utility) { [weak self] in
+                let current = await LaunchAgentManager.status()
+                await MainActor.run { [weak self] in self?.launchAtLogin = current }
+            }
+        }
+
+        if self.swabbleEnabled, !PermissionManager.voiceWakePermissionsGranted() {
+            self.swabbleEnabled = false
+        }
+        if self.talkEnabled, !PermissionManager.voiceWakePermissionsGranted() {
+            self.talkEnabled = false
+        }
+
+        if !self.isPreview {
+            Task { await VoiceWakeRuntime.shared.refresh(state: self) }
+            Task { await TalkModeController.shared.setEnabled(self.talkEnabled) }
+        }
+
+        self.isInitializing = false
+        if !self.isPreview {
+            self.startConfigWatcher()
+        }
+    }
+
+    @MainActor
+    deinit {
+        self.configWatcher?.stop()
+    }
+
+    private static func remoteHost(from urlString: String?) -> String? {
+        guard let raw = urlString?.trimmingCharacters(in: .whitespacesAndNewlines),
+              !raw.isEmpty,
+              let url = URL(string: raw),
+              let host = url.host?.trimmingCharacters(in: .whitespacesAndNewlines),
+              !host.isEmpty
+        else {
+            return nil
+        }
+        return host
+    }
+
+    private static func sanitizeSSHTarget(_ value: String) -> String {
+        let trimmed = value.trimmingCharacters(in: .whitespacesAndNewlines)
+        if trimmed.hasPrefix("ssh ") {
+            return trimmed.replacingOccurrences(of: "ssh ", with: "")
+                .trimmingCharacters(in: .whitespacesAndNewlines)
+        }
+        return trimmed
+    }
+
+    private static func updateGatewayString(
+        _ dictionary: inout [String: Any],
+        key: String,
+        value: String?) -> Bool
+    {
+        let trimmed = value?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        if trimmed.isEmpty {
+            guard dictionary[key] != nil else { return false }
+            dictionary.removeValue(forKey: key)
+            return true
+        }
+        if (dictionary[key] as? String) != trimmed {
+            dictionary[key] = trimmed
+            return true
+        }
+        return false
+    }
+
+    private static func updatedRemoteGatewayConfig(
+        current: [String: Any],
+        transport: RemoteTransport,
+        remoteUrl: String,
+        remoteHost: String?,
+        remoteTarget: String,
+        remoteIdentity: String) -> (remote: [String: Any], changed: Bool)
+    {
+        var remote = current
+        var changed = false
+
+        switch transport {
+        case .direct:
+            changed = Self.updateGatewayString(
+                &remote,
+                key: "transport",
+                value: RemoteTransport.direct.rawValue) || changed
+
+            let trimmedUrl = remoteUrl.trimmingCharacters(in: .whitespacesAndNewlines)
+            if trimmedUrl.isEmpty {
+                changed = Self.updateGatewayString(&remote, key: "url", value: nil) || changed
+            } else if let normalizedUrl = GatewayRemoteConfig.normalizeGatewayUrlString(trimmedUrl) {
+                changed = Self.updateGatewayString(&remote, key: "url", value: normalizedUrl) || changed
+            }
+
+        case .ssh:
+            changed = Self.updateGatewayString(&remote, key: "transport", value: nil) || changed
+
+            if let host = remoteHost {
+                let existingUrl = (remote["url"] as? String)?
+                    .trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+                let parsedExisting = existingUrl.isEmpty ? nil : URL(string: existingUrl)
+                let scheme = parsedExisting?.scheme?.isEmpty == false ? parsedExisting?.scheme : "ws"
+                let port = parsedExisting?.port ?? 18789
+                let desiredUrl = "\(scheme ?? "ws")://\(host):\(port)"
+                changed = Self.updateGatewayString(&remote, key: "url", value: desiredUrl) || changed
+            }
+
+            let sanitizedTarget = Self.sanitizeSSHTarget(remoteTarget)
+            changed = Self.updateGatewayString(&remote, key: "sshTarget", value: sanitizedTarget) || changed
+            changed = Self.updateGatewayString(&remote, key: "sshIdentity", value: remoteIdentity) || changed
+        }
+
+        return (remote, changed)
+    }
+
+    private func startConfigWatcher() {
+        let configUrl = OpenClawConfigFile.url()
+        self.configWatcher = ConfigFileWatcher(url: configUrl) { [weak self] in
+            Task { @MainActor in
+                self?.applyConfigFromDisk()
+            }
+        }
+        self.configWatcher?.start()
+    }
+
+    private func applyConfigFromDisk() {
+        let root = OpenClawConfigFile.loadDict()
+        self.applyConfigOverrides(root)
+    }
+
+    private func applyConfigOverrides(_ root: [String: Any]) {
+        let gateway = root["gateway"] as? [String: Any]
+        let modeRaw = (gateway?["mode"] as? String)?.trimmingCharacters(in: .whitespacesAndNewlines)
+        let remoteUrl = GatewayRemoteConfig.resolveUrlString(root: root)
+        let hasRemoteUrl = !(remoteUrl?
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+            .isEmpty ?? true)
+        let remoteTransport = GatewayRemoteConfig.resolveTransport(root: root)
+
+        let desiredMode: ConnectionMode? = switch modeRaw {
+        case "local":
+            .local
+        case "remote":
+            .remote
+        case "unconfigured":
+            .unconfigured
+        default:
+            nil
+        }
+
+        if let desiredMode {
+            if desiredMode != self.connectionMode {
+                self.connectionMode = desiredMode
+            }
+        } else if hasRemoteUrl, self.connectionMode != .remote {
+            self.connectionMode = .remote
+        }
+
+        if remoteTransport != self.remoteTransport {
+            self.remoteTransport = remoteTransport
+        }
+        let remoteUrlText = remoteUrl ?? ""
+        if remoteUrlText != self.remoteUrl {
+            self.remoteUrl = remoteUrlText
+        }
+
+        let targetMode = desiredMode ?? self.connectionMode
+        if targetMode == .remote,
+           remoteTransport != .direct,
+           let host = AppState.remoteHost(from: remoteUrl)
+        {
+            self.updateRemoteTarget(host: host)
+        }
+    }
+
+    private func updateRemoteTarget(host: String) {
+        let trimmed = self.remoteTarget.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard let parsed = CommandResolver.parseSSHTarget(trimmed) else { return }
+        let trimmedUser = parsed.user?.trimmingCharacters(in: .whitespacesAndNewlines)
+        let user = (trimmedUser?.isEmpty ?? true) ? nil : trimmedUser
+        let port = parsed.port
+        let assembled: String = if let user {
+            port == 22 ? "\(user)@\(host)" : "\(user)@\(host):\(port)"
+        } else {
+            port == 22 ? host : "\(host):\(port)"
+        }
+        if assembled != self.remoteTarget {
+            self.remoteTarget = assembled
+        }
+    }
+
+    private func syncGatewayConfigIfNeeded() {
+        guard !self.isPreview, !self.isInitializing else { return }
+
+        let connectionMode = self.connectionMode
+        let remoteTarget = self.remoteTarget
+        let remoteIdentity = self.remoteIdentity
+        let remoteTransport = self.remoteTransport
+        let remoteUrl = self.remoteUrl
+        let desiredMode: String? = switch connectionMode {
+        case .local:
+            "local"
+        case .remote:
+            "remote"
+        case .unconfigured:
+            nil
+        }
+        let remoteHost = connectionMode == .remote
+            ? CommandResolver.parseSSHTarget(remoteTarget)?.host
+            : nil
+
+        Task { @MainActor in
+            // Keep app-only connection settings local to avoid overwriting remote gateway config.
+            var root = OpenClawConfigFile.loadDict()
+            var gateway = root["gateway"] as? [String: Any] ?? [:]
+            var changed = false
+
+            let currentMode = (gateway["mode"] as? String)?.trimmingCharacters(in: .whitespacesAndNewlines)
+            if let desiredMode {
+                if currentMode != desiredMode {
+                    gateway["mode"] = desiredMode
+                    changed = true
+                }
+            } else if currentMode != nil {
+                gateway.removeValue(forKey: "mode")
+                changed = true
+            }
+
+            if connectionMode == .remote {
+                let currentRemote = gateway["remote"] as? [String: Any] ?? [:]
+                let updated = Self.updatedRemoteGatewayConfig(
+                    current: currentRemote,
+                    transport: remoteTransport,
+                    remoteUrl: remoteUrl,
+                    remoteHost: remoteHost,
+                    remoteTarget: remoteTarget,
+                    remoteIdentity: remoteIdentity)
+                if updated.changed {
+                    gateway["remote"] = updated.remote
+                    changed = true
+                }
+            }
+
+            guard changed else { return }
+            if gateway.isEmpty {
+                root.removeValue(forKey: "gateway")
+            } else {
+                root["gateway"] = gateway
+            }
+            OpenClawConfigFile.saveDict(root)
+        }
+    }
+
+    func triggerVoiceEars(ttl: TimeInterval? = 5) {
+        self.earBoostTask?.cancel()
+        self.earBoostActive = true
+
+        guard let ttl else { return }
+
+        self.earBoostTask = Task { [weak self] in
+            try? await Task.sleep(nanoseconds: UInt64(ttl * 1_000_000_000))
+            await MainActor.run { [weak self] in self?.earBoostActive = false }
+        }
+    }
+
+    func stopVoiceEars() {
+        self.earBoostTask?.cancel()
+        self.earBoostTask = nil
+        self.earBoostActive = false
+    }
+
+    func blinkOnce() {
+        self.blinkTick &+= 1
+    }
+
+    func celebrateSend() {
+        self.sendCelebrationTick &+= 1
+    }
+
+    func setVoiceWakeEnabled(_ enabled: Bool) async {
+        guard voiceWakeSupported else {
+            self.swabbleEnabled = false
+            return
+        }
+
+        self.swabbleEnabled = enabled
+        guard !self.isPreview else { return }
+
+        if !enabled {
+            Task { await VoiceWakeRuntime.shared.refresh(state: self) }
+            return
+        }
+
+        if PermissionManager.voiceWakePermissionsGranted() {
+            Task { await VoiceWakeRuntime.shared.refresh(state: self) }
+            return
+        }
+
+        let granted = await PermissionManager.ensureVoiceWakePermissions(interactive: true)
+        self.swabbleEnabled = granted
+        Task { await VoiceWakeRuntime.shared.refresh(state: self) }
+    }
+
+    func setTalkEnabled(_ enabled: Bool) async {
+        guard voiceWakeSupported else {
+            self.talkEnabled = false
+            await GatewayConnection.shared.talkMode(enabled: false, phase: "disabled")
+            return
+        }
+
+        self.talkEnabled = enabled
+        guard !self.isPreview else { return }
+
+        if !enabled {
+            await GatewayConnection.shared.talkMode(enabled: false, phase: "disabled")
+            return
+        }
+
+        if PermissionManager.voiceWakePermissionsGranted() {
+            await GatewayConnection.shared.talkMode(enabled: true, phase: "enabled")
+            return
+        }
+
+        let granted = await PermissionManager.ensureVoiceWakePermissions(interactive: true)
+        self.talkEnabled = granted
+        await GatewayConnection.shared.talkMode(enabled: granted, phase: granted ? "enabled" : "denied")
+    }
+
+    // MARK: - Global wake words sync (Gateway-owned)
+
+    func applyGlobalVoiceWakeTriggers(_ triggers: [String]) {
+        self.suppressVoiceWakeGlobalSync = true
+        self.swabbleTriggerWords = triggers
+        self.suppressVoiceWakeGlobalSync = false
+    }
+
+    private func scheduleVoiceWakeGlobalSyncIfNeeded() {
+        guard !self.suppressVoiceWakeGlobalSync else { return }
+        let sanitized = sanitizeVoiceWakeTriggers(self.swabbleTriggerWords)
+        self.voiceWakeGlobalSyncTask?.cancel()
+        self.voiceWakeGlobalSyncTask = Task { [sanitized] in
+            try? await Task.sleep(nanoseconds: 650_000_000)
+            await GatewayConnection.shared.voiceWakeSetTriggers(sanitized)
+        }
+    }
+
+    func setWorking(_ working: Bool) {
+        self.isWorking = working
+    }
+
+    // MARK: - Chime persistence
+
+    private static func loadChime(key: String, fallback: VoiceWakeChime) -> VoiceWakeChime {
+        guard let data = UserDefaults.standard.data(forKey: key) else { return fallback }
+        if let decoded = try? JSONDecoder().decode(VoiceWakeChime.self, from: data) {
+            return decoded
+        }
+        return fallback
+    }
+
+    private func storeChime(_ chime: VoiceWakeChime, key: String) {
+        guard let data = try? JSONEncoder().encode(chime) else { return }
+        UserDefaults.standard.set(data, forKey: key)
+    }
+}
+
+extension AppState {
+    static var preview: AppState {
+        let state = AppState(preview: true)
+        state.isPaused = false
+        state.launchAtLogin = true
+        state.onboardingSeen = true
+        state.debugPaneEnabled = true
+        state.swabbleEnabled = true
+        state.swabbleTriggerWords = ["Claude", "Computer", "Jarvis"]
+        state.voiceWakeTriggerChime = .system(name: "Glass")
+        state.voiceWakeSendChime = .system(name: "Ping")
+        state.iconAnimationsEnabled = true
+        state.showDockIcon = true
+        state.voiceWakeMicID = "BuiltInMic"
+        state.voiceWakeMicName = "Built-in Microphone"
+        state.voiceWakeLocaleID = Locale.current.identifier
+        state.voiceWakeAdditionalLocaleIDs = ["en-US", "de-DE"]
+        state.voicePushToTalkEnabled = false
+        state.talkEnabled = false
+        state.iconOverride = .system
+        state.heartbeatsEnabled = true
+        state.connectionMode = .local
+        state.remoteTransport = .ssh
+        state.canvasEnabled = true
+        state.remoteTarget = "user@example.com"
+        state.remoteUrl = "wss://gateway.example.ts.net"
+        state.remoteIdentity = "~/.ssh/id_ed25519"
+        state.remoteProjectRoot = "~/Projects/openclaw"
+        state.remoteCliPath = ""
+        return state
+    }
+}
+
+@MainActor
+enum AppStateStore {
+    static let shared = AppState()
+    static var isPausedFlag: Bool {
+        UserDefaults.standard.bool(forKey: pauseDefaultsKey)
+    }
+
+    static func updateLaunchAtLogin(enabled: Bool) {
+        Task.detached(priority: .utility) {
+            await LaunchAgentManager.set(enabled: enabled, bundlePath: Bundle.main.bundlePath)
+        }
+    }
+
+    static var canvasEnabled: Bool {
+        UserDefaults.standard.object(forKey: canvasEnabledKey) as? Bool ?? true
+    }
+}
+
+@MainActor
+enum AppActivationPolicy {
+    static func apply(showDockIcon: Bool) {
+        _ = showDockIcon
+        DockIconManager.shared.updateDockVisibility()
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/AudioInputDeviceObserver.swift

@@ -0,0 +1,225 @@
+import CoreAudio
+import Foundation
+import OSLog
+
+final class AudioInputDeviceObserver {
+    private let logger = Logger(subsystem: "ai.openclaw", category: "audio.devices")
+    private var isActive = false
+    private var devicesListener: AudioObjectPropertyListenerBlock?
+    private var defaultInputListener: AudioObjectPropertyListenerBlock?
+
+    static func defaultInputDeviceUID() -> String? {
+        let systemObject = AudioObjectID(kAudioObjectSystemObject)
+        var address = AudioObjectPropertyAddress(
+            mSelector: kAudioHardwarePropertyDefaultInputDevice,
+            mScope: kAudioObjectPropertyScopeGlobal,
+            mElement: kAudioObjectPropertyElementMain)
+        var deviceID = AudioObjectID(0)
+        var size = UInt32(MemoryLayout<AudioObjectID>.size)
+        let status = AudioObjectGetPropertyData(
+            systemObject,
+            &address,
+            0,
+            nil,
+            &size,
+            &deviceID)
+        guard status == noErr, deviceID != 0 else { return nil }
+        return self.deviceUID(for: deviceID)
+    }
+
+    static func aliveInputDeviceUIDs() -> Set<String> {
+        let systemObject = AudioObjectID(kAudioObjectSystemObject)
+        var address = AudioObjectPropertyAddress(
+            mSelector: kAudioHardwarePropertyDevices,
+            mScope: kAudioObjectPropertyScopeGlobal,
+            mElement: kAudioObjectPropertyElementMain)
+        var size: UInt32 = 0
+        var status = AudioObjectGetPropertyDataSize(systemObject, &address, 0, nil, &size)
+        guard status == noErr, size > 0 else { return [] }
+
+        let count = Int(size) / MemoryLayout<AudioObjectID>.size
+        var deviceIDs = [AudioObjectID](repeating: 0, count: count)
+        status = AudioObjectGetPropertyData(systemObject, &address, 0, nil, &size, &deviceIDs)
+        guard status == noErr else { return [] }
+
+        var output = Set<String>()
+        for deviceID in deviceIDs {
+            guard self.deviceIsAlive(deviceID) else { continue }
+            guard self.deviceHasInput(deviceID) else { continue }
+            if let uid = self.deviceUID(for: deviceID) {
+                output.insert(uid)
+            }
+        }
+        return output
+    }
+
+    /// Returns true when the system default input device exists and is alive with input channels.
+    /// Use this preflight before accessing `AVAudioEngine.inputNode` to avoid SIGABRT on Macs
+    /// without a built-in microphone (Mac mini, Mac Pro, Mac Studio) or when an external mic
+    /// is disconnected.
+    static func hasUsableDefaultInputDevice() -> Bool {
+        guard let uid = self.defaultInputDeviceUID() else { return false }
+        return self.aliveInputDeviceUIDs().contains(uid)
+    }
+
+    static func defaultInputDeviceSummary() -> String {
+        let systemObject = AudioObjectID(kAudioObjectSystemObject)
+        var address = AudioObjectPropertyAddress(
+            mSelector: kAudioHardwarePropertyDefaultInputDevice,
+            mScope: kAudioObjectPropertyScopeGlobal,
+            mElement: kAudioObjectPropertyElementMain)
+        var deviceID = AudioObjectID(0)
+        var size = UInt32(MemoryLayout<AudioObjectID>.size)
+        let status = AudioObjectGetPropertyData(
+            systemObject,
+            &address,
+            0,
+            nil,
+            &size,
+            &deviceID)
+        guard status == noErr, deviceID != 0 else {
+            return "defaultInput=unknown"
+        }
+        let uid = self.deviceUID(for: deviceID) ?? "unknown"
+        let name = self.deviceName(for: deviceID) ?? "unknown"
+        return "defaultInput=\(name) (\(uid))"
+    }
+
+    func start(onChange: @escaping @Sendable () -> Void) {
+        guard !self.isActive else { return }
+        self.isActive = true
+
+        let systemObject = AudioObjectID(kAudioObjectSystemObject)
+        let queue = DispatchQueue.main
+
+        var devicesAddress = AudioObjectPropertyAddress(
+            mSelector: kAudioHardwarePropertyDevices,
+            mScope: kAudioObjectPropertyScopeGlobal,
+            mElement: kAudioObjectPropertyElementMain)
+        let devicesListener: AudioObjectPropertyListenerBlock = { _, _ in
+            self.logDefaultInputChange(reason: "devices")
+            onChange()
+        }
+        let devicesStatus = AudioObjectAddPropertyListenerBlock(
+            systemObject,
+            &devicesAddress,
+            queue,
+            devicesListener)
+
+        var defaultInputAddress = AudioObjectPropertyAddress(
+            mSelector: kAudioHardwarePropertyDefaultInputDevice,
+            mScope: kAudioObjectPropertyScopeGlobal,
+            mElement: kAudioObjectPropertyElementMain)
+        let defaultInputListener: AudioObjectPropertyListenerBlock = { _, _ in
+            self.logDefaultInputChange(reason: "default")
+            onChange()
+        }
+        let defaultStatus = AudioObjectAddPropertyListenerBlock(
+            systemObject,
+            &defaultInputAddress,
+            queue,
+            defaultInputListener)
+
+        if devicesStatus != noErr || defaultStatus != noErr {
+            self.logger.error("audio device observer install failed devices=\(devicesStatus) default=\(defaultStatus)")
+        }
+
+        self.logger.info("audio device observer started (\(Self.defaultInputDeviceSummary(), privacy: .public))")
+
+        self.devicesListener = devicesListener
+        self.defaultInputListener = defaultInputListener
+    }
+
+    func stop() {
+        guard self.isActive else { return }
+        self.isActive = false
+        let systemObject = AudioObjectID(kAudioObjectSystemObject)
+
+        if let devicesListener {
+            var devicesAddress = AudioObjectPropertyAddress(
+                mSelector: kAudioHardwarePropertyDevices,
+                mScope: kAudioObjectPropertyScopeGlobal,
+                mElement: kAudioObjectPropertyElementMain)
+            _ = AudioObjectRemovePropertyListenerBlock(
+                systemObject,
+                &devicesAddress,
+                DispatchQueue.main,
+                devicesListener)
+        }
+
+        if let defaultInputListener {
+            var defaultInputAddress = AudioObjectPropertyAddress(
+                mSelector: kAudioHardwarePropertyDefaultInputDevice,
+                mScope: kAudioObjectPropertyScopeGlobal,
+                mElement: kAudioObjectPropertyElementMain)
+            _ = AudioObjectRemovePropertyListenerBlock(
+                systemObject,
+                &defaultInputAddress,
+                DispatchQueue.main,
+                defaultInputListener)
+        }
+
+        self.devicesListener = nil
+        self.defaultInputListener = nil
+    }
+
+    private static func deviceUID(for deviceID: AudioObjectID) -> String? {
+        var address = AudioObjectPropertyAddress(
+            mSelector: kAudioDevicePropertyDeviceUID,
+            mScope: kAudioObjectPropertyScopeGlobal,
+            mElement: kAudioObjectPropertyElementMain)
+        var uid: Unmanaged<CFString>?
+        var size = UInt32(MemoryLayout<Unmanaged<CFString>?>.size)
+        let status = AudioObjectGetPropertyData(deviceID, &address, 0, nil, &size, &uid)
+        guard status == noErr, let uid else { return nil }
+        return uid.takeUnretainedValue() as String
+    }
+
+    private static func deviceName(for deviceID: AudioObjectID) -> String? {
+        var address = AudioObjectPropertyAddress(
+            mSelector: kAudioObjectPropertyName,
+            mScope: kAudioObjectPropertyScopeGlobal,
+            mElement: kAudioObjectPropertyElementMain)
+        var name: Unmanaged<CFString>?
+        var size = UInt32(MemoryLayout<Unmanaged<CFString>?>.size)
+        let status = AudioObjectGetPropertyData(deviceID, &address, 0, nil, &size, &name)
+        guard status == noErr, let name else { return nil }
+        return name.takeUnretainedValue() as String
+    }
+
+    private static func deviceIsAlive(_ deviceID: AudioObjectID) -> Bool {
+        var address = AudioObjectPropertyAddress(
+            mSelector: kAudioDevicePropertyDeviceIsAlive,
+            mScope: kAudioObjectPropertyScopeGlobal,
+            mElement: kAudioObjectPropertyElementMain)
+        var alive: UInt32 = 0
+        var size = UInt32(MemoryLayout<UInt32>.size)
+        let status = AudioObjectGetPropertyData(deviceID, &address, 0, nil, &size, &alive)
+        return status == noErr && alive != 0
+    }
+
+    private static func deviceHasInput(_ deviceID: AudioObjectID) -> Bool {
+        var address = AudioObjectPropertyAddress(
+            mSelector: kAudioDevicePropertyStreamConfiguration,
+            mScope: kAudioDevicePropertyScopeInput,
+            mElement: kAudioObjectPropertyElementMain)
+        var size: UInt32 = 0
+        var status = AudioObjectGetPropertyDataSize(deviceID, &address, 0, nil, &size)
+        guard status == noErr, size > 0 else { return false }
+
+        let raw = UnsafeMutableRawPointer.allocate(
+            byteCount: Int(size),
+            alignment: MemoryLayout<AudioBufferList>.alignment)
+        defer { raw.deallocate() }
+        let bufferList = raw.bindMemory(to: AudioBufferList.self, capacity: 1)
+        status = AudioObjectGetPropertyData(deviceID, &address, 0, nil, &size, bufferList)
+        guard status == noErr else { return false }
+
+        let buffers = UnsafeMutableAudioBufferListPointer(bufferList)
+        return buffers.contains(where: { $0.mNumberChannels > 0 })
+    }
+
+    private func logDefaultInputChange(reason: StaticString) {
+        self.logger.info("audio input changed (\(reason)) (\(Self.defaultInputDeviceSummary(), privacy: .public))")
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/CLIInstallPrompter.swift

@@ -0,0 +1,84 @@
+import AppKit
+import Foundation
+import OSLog
+
+@MainActor
+final class CLIInstallPrompter {
+    static let shared = CLIInstallPrompter()
+    private let logger = Logger(subsystem: "ai.openclaw", category: "cli.prompt")
+    private var isPrompting = false
+
+    func checkAndPromptIfNeeded(reason: String) {
+        guard self.shouldPrompt() else { return }
+        guard let version = Self.appVersion() else { return }
+        self.isPrompting = true
+        UserDefaults.standard.set(version, forKey: cliInstallPromptedVersionKey)
+
+        let alert = NSAlert()
+        alert.messageText = "Install OpenClaw CLI?"
+        alert.informativeText = "Local mode needs the CLI so launchd can run the gateway."
+        alert.addButton(withTitle: "Install CLI")
+        alert.addButton(withTitle: "Not now")
+        alert.addButton(withTitle: "Open Settings")
+        let response = alert.runModal()
+
+        switch response {
+        case .alertFirstButtonReturn:
+            Task { await self.installCLI() }
+        case .alertThirdButtonReturn:
+            self.openSettings(tab: .general)
+        default:
+            break
+        }
+
+        self.logger.debug("cli install prompt handled reason=\(reason, privacy: .public)")
+        self.isPrompting = false
+    }
+
+    private func shouldPrompt() -> Bool {
+        guard !self.isPrompting else { return false }
+        guard AppStateStore.shared.onboardingSeen else { return false }
+        guard AppStateStore.shared.connectionMode == .local else { return false }
+        guard CLIInstaller.installedLocation() == nil else { return false }
+        guard let version = Self.appVersion() else { return false }
+        let lastPrompt = UserDefaults.standard.string(forKey: cliInstallPromptedVersionKey)
+        return lastPrompt != version
+    }
+
+    private func installCLI() async {
+        let status = StatusBox()
+        await CLIInstaller.install { message in
+            await status.set(message)
+        }
+        if let message = await status.get() {
+            let alert = NSAlert()
+            alert.messageText = "CLI install finished"
+            alert.informativeText = message
+            alert.runModal()
+        }
+    }
+
+    private func openSettings(tab: SettingsTab) {
+        SettingsTabRouter.request(tab)
+        SettingsWindowOpener.shared.open()
+        DispatchQueue.main.async {
+            NotificationCenter.default.post(name: .openclawSelectSettingsTab, object: tab)
+        }
+    }
+
+    private static func appVersion() -> String? {
+        Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String
+    }
+}
+
+private actor StatusBox {
+    private var value: String?
+
+    func set(_ value: String) {
+        self.value = value
+    }
+
+    func get() -> String? {
+        self.value
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/CLIInstaller.swift

@@ -0,0 +1,103 @@
+import Foundation
+
+@MainActor
+enum CLIInstaller {
+    static func installedLocation() -> String? {
+        self.installedLocation(
+            searchPaths: CommandResolver.preferredPaths(),
+            fileManager: .default)
+    }
+
+    static func installedLocation(
+        searchPaths: [String],
+        fileManager: FileManager) -> String?
+    {
+        for basePath in searchPaths {
+            let candidate = URL(fileURLWithPath: basePath).appendingPathComponent("openclaw").path
+            var isDirectory: ObjCBool = false
+
+            guard fileManager.fileExists(atPath: candidate, isDirectory: &isDirectory),
+                  !isDirectory.boolValue
+            else {
+                continue
+            }
+
+            guard fileManager.isExecutableFile(atPath: candidate) else { continue }
+
+            return candidate
+        }
+
+        return nil
+    }
+
+    static func isInstalled() -> Bool {
+        self.installedLocation() != nil
+    }
+
+    static func install(statusHandler: @escaping @MainActor @Sendable (String) async -> Void) async {
+        let expected = GatewayEnvironment.expectedGatewayVersionString() ?? "latest"
+        let prefix = Self.installPrefix()
+        await statusHandler("Installing openclaw CLI…")
+        let cmd = self.installScriptCommand(version: expected, prefix: prefix)
+        let response = await ShellExecutor.runDetailed(command: cmd, cwd: nil, env: nil, timeout: 900)
+
+        if response.success {
+            let parsed = self.parseInstallEvents(response.stdout)
+            let installedVersion = parsed.last { $0.event == "done" }?.version
+            let summary = installedVersion.map { "Installed openclaw \($0)." } ?? "Installed openclaw."
+            await statusHandler(summary)
+            return
+        }
+
+        let parsed = self.parseInstallEvents(response.stdout)
+        if let error = parsed.last(where: { $0.event == "error" })?.message {
+            await statusHandler("Install failed: \(error)")
+            return
+        }
+
+        let detail = response.stderr.trimmingCharacters(in: .whitespacesAndNewlines)
+        let fallback = response.errorMessage ?? "install failed"
+        await statusHandler("Install failed: \(detail.isEmpty ? fallback : detail)")
+    }
+
+    private static func installPrefix() -> String {
+        FileManager().homeDirectoryForCurrentUser
+            .appendingPathComponent(".openclaw")
+            .path
+    }
+
+    private static func installScriptCommand(version: String, prefix: String) -> [String] {
+        let escapedVersion = self.shellEscape(version)
+        let escapedPrefix = self.shellEscape(prefix)
+        let script = """
+        curl -fsSL https://openclaw.bot/install-cli.sh | \
+        bash -s -- --json --no-onboard --prefix \(escapedPrefix) --version \(escapedVersion)
+        """
+        return ["/bin/bash", "-lc", script]
+    }
+
+    private static func parseInstallEvents(_ output: String) -> [InstallEvent] {
+        let decoder = JSONDecoder()
+        let lines = output
+            .split(whereSeparator: \.isNewline)
+            .map { String($0) }
+        var events: [InstallEvent] = []
+        for line in lines {
+            guard let data = line.data(using: .utf8) else { continue }
+            if let event = try? decoder.decode(InstallEvent.self, from: data) {
+                events.append(event)
+            }
+        }
+        return events
+    }
+
+    private static func shellEscape(_ raw: String) -> String {
+        "'" + raw.replacingOccurrences(of: "'", with: "'\"'\"'") + "'"
+    }
+}
+
+private struct InstallEvent: Decodable {
+    let event: String
+    let version: String?
+    let message: String?
+}

openclaw/apps/macos/Sources/OpenClaw/CameraCaptureService.swift

@@ -0,0 +1,427 @@
+import AVFoundation
+import CoreGraphics
+import Foundation
+import OpenClawIPC
+import OpenClawKit
+import OSLog
+
+actor CameraCaptureService {
+    struct CameraDeviceInfo: Encodable, Sendable {
+        let id: String
+        let name: String
+        let position: String
+        let deviceType: String
+    }
+
+    enum CameraError: LocalizedError, Sendable {
+        case cameraUnavailable
+        case microphoneUnavailable
+        case permissionDenied(kind: String)
+        case captureFailed(String)
+        case exportFailed(String)
+
+        var errorDescription: String? {
+            switch self {
+            case .cameraUnavailable:
+                "Camera unavailable"
+            case .microphoneUnavailable:
+                "Microphone unavailable"
+            case let .permissionDenied(kind):
+                "\(kind) permission denied"
+            case let .captureFailed(msg):
+                msg
+            case let .exportFailed(msg):
+                msg
+            }
+        }
+    }
+
+    private let logger = Logger(subsystem: "ai.openclaw", category: "camera")
+
+    func listDevices() -> [CameraDeviceInfo] {
+        Self.availableCameras().map { device in
+            CameraDeviceInfo(
+                id: device.uniqueID,
+                name: device.localizedName,
+                position: Self.positionLabel(device.position),
+                deviceType: device.deviceType.rawValue)
+        }
+    }
+
+    func snap(
+        facing: CameraFacing?,
+        maxWidth: Int?,
+        quality: Double?,
+        deviceId: String?,
+        delayMs: Int) async throws -> (data: Data, size: CGSize)
+    {
+        let facing = facing ?? .front
+        let normalized = Self.normalizeSnap(maxWidth: maxWidth, quality: quality)
+        let maxWidth = normalized.maxWidth
+        let quality = normalized.quality
+        let delayMs = max(0, delayMs)
+        let deviceId = deviceId?.trimmingCharacters(in: .whitespacesAndNewlines)
+
+        try await self.ensureAccess(for: .video)
+
+        let session = AVCaptureSession()
+        session.sessionPreset = .photo
+
+        guard let device = Self.pickCamera(facing: facing, deviceId: deviceId) else {
+            throw CameraError.cameraUnavailable
+        }
+
+        let input = try AVCaptureDeviceInput(device: device)
+        guard session.canAddInput(input) else {
+            throw CameraError.captureFailed("Failed to add camera input")
+        }
+        session.addInput(input)
+
+        let output = AVCapturePhotoOutput()
+        guard session.canAddOutput(output) else {
+            throw CameraError.captureFailed("Failed to add photo output")
+        }
+        session.addOutput(output)
+        output.maxPhotoQualityPrioritization = .quality
+
+        session.startRunning()
+        defer { session.stopRunning() }
+        await Self.warmUpCaptureSession()
+        await self.waitForExposureAndWhiteBalance(device: device)
+        await self.sleepDelayMs(delayMs)
+
+        let settings: AVCapturePhotoSettings = {
+            if output.availablePhotoCodecTypes.contains(.jpeg) {
+                return AVCapturePhotoSettings(format: [AVVideoCodecKey: AVVideoCodecType.jpeg])
+            }
+            return AVCapturePhotoSettings()
+        }()
+        settings.photoQualityPrioritization = .quality
+
+        var delegate: PhotoCaptureDelegate?
+        let rawData: Data = try await withCheckedThrowingContinuation { cont in
+            let d = PhotoCaptureDelegate(cont)
+            delegate = d
+            output.capturePhoto(with: settings, delegate: d)
+        }
+        withExtendedLifetime(delegate) {}
+
+        let res: (data: Data, widthPx: Int, heightPx: Int)
+        do {
+            res = try PhotoCapture.transcodeJPEGForGateway(
+                rawData: rawData,
+                maxWidthPx: maxWidth,
+                quality: quality)
+        } catch {
+            throw CameraError.captureFailed(error.localizedDescription)
+        }
+
+        return (data: res.data, size: CGSize(width: res.widthPx, height: res.heightPx))
+    }
+
+    func clip(
+        facing: CameraFacing?,
+        durationMs: Int?,
+        includeAudio: Bool,
+        deviceId: String?,
+        outPath: String?) async throws -> (path: String, durationMs: Int, hasAudio: Bool)
+    {
+        let facing = facing ?? .front
+        let durationMs = Self.clampDurationMs(durationMs)
+        let deviceId = deviceId?.trimmingCharacters(in: .whitespacesAndNewlines)
+
+        try await self.ensureAccess(for: .video)
+        if includeAudio {
+            try await self.ensureAccess(for: .audio)
+        }
+
+        let session = AVCaptureSession()
+        session.sessionPreset = .high
+
+        guard let camera = Self.pickCamera(facing: facing, deviceId: deviceId) else {
+            throw CameraError.cameraUnavailable
+        }
+        let cameraInput = try AVCaptureDeviceInput(device: camera)
+        guard session.canAddInput(cameraInput) else {
+            throw CameraError.captureFailed("Failed to add camera input")
+        }
+        session.addInput(cameraInput)
+
+        if includeAudio {
+            guard let mic = AVCaptureDevice.default(for: .audio) else {
+                throw CameraError.microphoneUnavailable
+            }
+            let micInput = try AVCaptureDeviceInput(device: mic)
+            guard session.canAddInput(micInput) else {
+                throw CameraError.captureFailed("Failed to add microphone input")
+            }
+            session.addInput(micInput)
+        }
+
+        let output = AVCaptureMovieFileOutput()
+        guard session.canAddOutput(output) else {
+            throw CameraError.captureFailed("Failed to add movie output")
+        }
+        session.addOutput(output)
+        output.maxRecordedDuration = CMTime(value: Int64(durationMs), timescale: 1000)
+
+        session.startRunning()
+        defer { session.stopRunning() }
+        await Self.warmUpCaptureSession()
+
+        let tmpMovURL = FileManager().temporaryDirectory
+            .appendingPathComponent("openclaw-camera-\(UUID().uuidString).mov")
+        defer { try? FileManager().removeItem(at: tmpMovURL) }
+
+        let outputURL: URL = {
+            if let outPath, !outPath.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+                return URL(fileURLWithPath: outPath)
+            }
+            return FileManager().temporaryDirectory
+                .appendingPathComponent("openclaw-camera-\(UUID().uuidString).mp4")
+        }()
+
+        // Ensure we don't fail exporting due to an existing file.
+        try? FileManager().removeItem(at: outputURL)
+
+        let logger = self.logger
+        var delegate: MovieFileDelegate?
+        let recordedURL: URL = try await withCheckedThrowingContinuation { cont in
+            let d = MovieFileDelegate(cont, logger: logger)
+            delegate = d
+            output.startRecording(to: tmpMovURL, recordingDelegate: d)
+        }
+        withExtendedLifetime(delegate) {}
+
+        try await Self.exportToMP4(inputURL: recordedURL, outputURL: outputURL)
+        return (path: outputURL.path, durationMs: durationMs, hasAudio: includeAudio)
+    }
+
+    private func ensureAccess(for mediaType: AVMediaType) async throws {
+        let status = AVCaptureDevice.authorizationStatus(for: mediaType)
+        switch status {
+        case .authorized:
+            return
+        case .notDetermined:
+            let ok = await withCheckedContinuation(isolation: nil) { cont in
+                AVCaptureDevice.requestAccess(for: mediaType) { granted in
+                    cont.resume(returning: granted)
+                }
+            }
+            if !ok {
+                throw CameraError.permissionDenied(kind: mediaType == .video ? "Camera" : "Microphone")
+            }
+        case .denied, .restricted:
+            throw CameraError.permissionDenied(kind: mediaType == .video ? "Camera" : "Microphone")
+        @unknown default:
+            throw CameraError.permissionDenied(kind: mediaType == .video ? "Camera" : "Microphone")
+        }
+    }
+
+    private nonisolated static func availableCameras() -> [AVCaptureDevice] {
+        var types: [AVCaptureDevice.DeviceType] = [
+            .builtInWideAngleCamera,
+            .continuityCamera,
+        ]
+        if let external = externalDeviceType() {
+            types.append(external)
+        }
+        let session = AVCaptureDevice.DiscoverySession(
+            deviceTypes: types,
+            mediaType: .video,
+            position: .unspecified)
+        return session.devices
+    }
+
+    private nonisolated static func externalDeviceType() -> AVCaptureDevice.DeviceType? {
+        if #available(macOS 14.0, *) {
+            return .external
+        }
+        // Use raw value to avoid deprecated symbol in the SDK.
+        return AVCaptureDevice.DeviceType(rawValue: "AVCaptureDeviceTypeExternalUnknown")
+    }
+
+    private nonisolated static func pickCamera(
+        facing: CameraFacing,
+        deviceId: String?) -> AVCaptureDevice?
+    {
+        if let deviceId, !deviceId.isEmpty {
+            if let match = availableCameras().first(where: { $0.uniqueID == deviceId }) {
+                return match
+            }
+        }
+        let position: AVCaptureDevice.Position = (facing == .front) ? .front : .back
+
+        if let device = AVCaptureDevice.default(.builtInWideAngleCamera, for: .video, position: position) {
+            return device
+        }
+
+        // Many macOS cameras report `unspecified` position; fall back to any default.
+        return AVCaptureDevice.default(for: .video)
+    }
+
+    private nonisolated static func clampQuality(_ quality: Double?) -> Double {
+        let q = quality ?? 0.9
+        return min(1.0, max(0.05, q))
+    }
+
+    nonisolated static func normalizeSnap(maxWidth: Int?, quality: Double?) -> (maxWidth: Int, quality: Double) {
+        // Default to a reasonable max width to keep downstream payload sizes manageable.
+        // If you need full-res, explicitly request a larger maxWidth.
+        let maxWidth = maxWidth.flatMap { $0 > 0 ? $0 : nil } ?? 1600
+        let quality = Self.clampQuality(quality)
+        return (maxWidth: maxWidth, quality: quality)
+    }
+
+    private nonisolated static func clampDurationMs(_ ms: Int?) -> Int {
+        let v = ms ?? 3000
+        return min(60000, max(250, v))
+    }
+
+    private nonisolated static func exportToMP4(inputURL: URL, outputURL: URL) async throws {
+        let asset = AVURLAsset(url: inputURL)
+        guard let export = AVAssetExportSession(asset: asset, presetName: AVAssetExportPresetMediumQuality) else {
+            throw CameraError.exportFailed("Failed to create export session")
+        }
+        export.shouldOptimizeForNetworkUse = true
+
+        if #available(macOS 15.0, *) {
+            do {
+                try await export.export(to: outputURL, as: .mp4)
+                return
+            } catch {
+                throw CameraError.exportFailed(error.localizedDescription)
+            }
+        } else {
+            export.outputURL = outputURL
+            export.outputFileType = .mp4
+
+            try await withCheckedThrowingContinuation(isolation: nil) { (cont: CheckedContinuation<Void, Error>) in
+                export.exportAsynchronously {
+                    cont.resume(returning: ())
+                }
+            }
+
+            switch export.status {
+            case .completed:
+                return
+            case .failed:
+                throw CameraError.exportFailed(export.error?.localizedDescription ?? "export failed")
+            case .cancelled:
+                throw CameraError.exportFailed("export cancelled")
+            default:
+                throw CameraError.exportFailed("export did not complete (\(export.status.rawValue))")
+            }
+        }
+    }
+
+    private nonisolated static func warmUpCaptureSession() async {
+        // A short delay after `startRunning()` significantly reduces "blank first frame" captures on some devices.
+        try? await Task.sleep(nanoseconds: 150_000_000) // 150ms
+    }
+
+    private func waitForExposureAndWhiteBalance(device: AVCaptureDevice) async {
+        let stepNs: UInt64 = 50_000_000
+        let maxSteps = 30 // ~1.5s
+        for _ in 0..<maxSteps {
+            if !(device.isAdjustingExposure || device.isAdjustingWhiteBalance) {
+                return
+            }
+            try? await Task.sleep(nanoseconds: stepNs)
+        }
+    }
+
+    private func sleepDelayMs(_ delayMs: Int) async {
+        guard delayMs > 0 else { return }
+        let ns = UInt64(min(delayMs, 10000)) * 1_000_000
+        try? await Task.sleep(nanoseconds: ns)
+    }
+
+    private nonisolated static func positionLabel(_ position: AVCaptureDevice.Position) -> String {
+        switch position {
+        case .front: "front"
+        case .back: "back"
+        default: "unspecified"
+        }
+    }
+}
+
+private final class PhotoCaptureDelegate: NSObject, AVCapturePhotoCaptureDelegate {
+    private var cont: CheckedContinuation<Data, Error>?
+    private var didResume = false
+
+    init(_ cont: CheckedContinuation<Data, Error>) {
+        self.cont = cont
+    }
+
+    func photoOutput(
+        _ output: AVCapturePhotoOutput,
+        didFinishProcessingPhoto photo: AVCapturePhoto,
+        error: Error?)
+    {
+        guard !self.didResume, let cont else { return }
+        self.didResume = true
+        self.cont = nil
+        if let error {
+            cont.resume(throwing: error)
+            return
+        }
+        guard let data = photo.fileDataRepresentation() else {
+            cont.resume(throwing: CameraCaptureService.CameraError.captureFailed("No photo data"))
+            return
+        }
+        if data.isEmpty {
+            cont.resume(throwing: CameraCaptureService.CameraError.captureFailed("Photo data empty"))
+            return
+        }
+        cont.resume(returning: data)
+    }
+
+    func photoOutput(
+        _ output: AVCapturePhotoOutput,
+        didFinishCaptureFor resolvedSettings: AVCaptureResolvedPhotoSettings,
+        error: Error?)
+    {
+        guard let error else { return }
+        guard !self.didResume, let cont else { return }
+        self.didResume = true
+        self.cont = nil
+        cont.resume(throwing: error)
+    }
+}
+
+private final class MovieFileDelegate: NSObject, AVCaptureFileOutputRecordingDelegate {
+    private var cont: CheckedContinuation<URL, Error>?
+    private let logger: Logger
+
+    init(_ cont: CheckedContinuation<URL, Error>, logger: Logger) {
+        self.cont = cont
+        self.logger = logger
+    }
+
+    func fileOutput(
+        _ output: AVCaptureFileOutput,
+        didFinishRecordingTo outputFileURL: URL,
+        from connections: [AVCaptureConnection],
+        error: Error?)
+    {
+        guard let cont else { return }
+        self.cont = nil
+
+        if let error {
+            let ns = error as NSError
+            if ns.domain == AVFoundationErrorDomain,
+               ns.code == AVError.maximumDurationReached.rawValue
+            {
+                cont.resume(returning: outputFileURL)
+                return
+            }
+
+            self.logger.error("camera record failed: \(error.localizedDescription, privacy: .public)")
+            cont.resume(throwing: error)
+            return
+        }
+
+        cont.resume(returning: outputFileURL)
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/CanvasA2UIActionMessageHandler.swift

@@ -0,0 +1,149 @@
+import AppKit
+import Foundation
+import OpenClawIPC
+import OpenClawKit
+import WebKit
+
+final class CanvasA2UIActionMessageHandler: NSObject, WKScriptMessageHandler {
+    static let messageName = "openclawCanvasA2UIAction"
+    static let allMessageNames = [messageName]
+
+    private let sessionKey: String
+
+    init(sessionKey: String) {
+        self.sessionKey = sessionKey
+        super.init()
+    }
+
+    func userContentController(_: WKUserContentController, didReceive message: WKScriptMessage) {
+        guard Self.allMessageNames.contains(message.name) else { return }
+
+        // Only accept actions from local Canvas content (not arbitrary web pages).
+        guard let webView = message.webView, let url = webView.url else { return }
+        if let scheme = url.scheme, CanvasScheme.allSchemes.contains(scheme) {
+            // ok
+        } else if Self.isLocalNetworkCanvasURL(url) {
+            // ok
+        } else {
+            return
+        }
+
+        let body: [String: Any] = {
+            if let dict = message.body as? [String: Any] { return dict }
+            if let dict = message.body as? [AnyHashable: Any] {
+                return dict.reduce(into: [String: Any]()) { acc, pair in
+                    guard let key = pair.key as? String else { return }
+                    acc[key] = pair.value
+                }
+            }
+            return [:]
+        }()
+        guard !body.isEmpty else { return }
+
+        let userActionAny = body["userAction"] ?? body
+        let userAction: [String: Any] = {
+            if let dict = userActionAny as? [String: Any] { return dict }
+            if let dict = userActionAny as? [AnyHashable: Any] {
+                return dict.reduce(into: [String: Any]()) { acc, pair in
+                    guard let key = pair.key as? String else { return }
+                    acc[key] = pair.value
+                }
+            }
+            return [:]
+        }()
+        guard !userAction.isEmpty else { return }
+
+        guard let name = OpenClawCanvasA2UIAction.extractActionName(userAction) else { return }
+        let actionId =
+            (userAction["id"] as? String)?.trimmingCharacters(in: .whitespacesAndNewlines).nonEmpty
+                ?? UUID().uuidString
+
+        canvasWindowLogger.info("A2UI action \(name, privacy: .public) session=\(self.sessionKey, privacy: .public)")
+
+        let surfaceId = (userAction["surfaceId"] as? String)?.trimmingCharacters(in: .whitespacesAndNewlines)
+            .nonEmpty ?? "main"
+        let sourceComponentId = (userAction["sourceComponentId"] as? String)?
+            .trimmingCharacters(in: .whitespacesAndNewlines).nonEmpty ?? "-"
+        let instanceId = InstanceIdentity.instanceId.lowercased()
+        let contextJSON = OpenClawCanvasA2UIAction.compactJSON(userAction["context"])
+
+        // Token-efficient and unambiguous. The agent should treat this as a UI event and (by default) update Canvas.
+        let messageContext = OpenClawCanvasA2UIAction.AgentMessageContext(
+            actionName: name,
+            session: .init(key: self.sessionKey, surfaceId: surfaceId),
+            component: .init(id: sourceComponentId, host: InstanceIdentity.displayName, instanceId: instanceId),
+            contextJSON: contextJSON)
+        let text = OpenClawCanvasA2UIAction.formatAgentMessage(messageContext)
+
+        Task { [weak webView] in
+            if AppStateStore.shared.connectionMode == .local {
+                GatewayProcessManager.shared.setActive(true)
+            }
+
+            let result = await GatewayConnection.shared.sendAgent(
+                GatewayAgentInvocation(
+                    message: text,
+                    sessionKey: self.sessionKey,
+                    thinking: "low",
+                    deliver: false,
+                    to: nil,
+                    channel: .last,
+                    idempotencyKey: actionId))
+
+            await MainActor.run {
+                guard let webView else { return }
+                let js = OpenClawCanvasA2UIAction.jsDispatchA2UIActionStatus(
+                    actionId: actionId,
+                    ok: result.ok,
+                    error: result.error)
+                webView.evaluateJavaScript(js) { _, _ in }
+            }
+            if !result.ok {
+                canvasWindowLogger.error(
+                    """
+                    A2UI action send failed name=\(name, privacy: .public) \
+                    error=\(result.error ?? "unknown", privacy: .public)
+                    """)
+            }
+        }
+    }
+
+    static func isLocalNetworkCanvasURL(_ url: URL) -> Bool {
+        guard let scheme = url.scheme?.lowercased(), scheme == "http" || scheme == "https" else {
+            return false
+        }
+        guard let host = url.host?.trimmingCharacters(in: .whitespacesAndNewlines), !host.isEmpty else {
+            return false
+        }
+        if host == "localhost" { return true }
+        if host.hasSuffix(".local") { return true }
+        if host.hasSuffix(".ts.net") { return true }
+        if host.hasSuffix(".tailscale.net") { return true }
+        if !host.contains("."), !host.contains(":") { return true }
+        if let ipv4 = Self.parseIPv4(host) {
+            return Self.isLocalNetworkIPv4(ipv4)
+        }
+        return false
+    }
+
+    static func parseIPv4(_ host: String) -> (UInt8, UInt8, UInt8, UInt8)? {
+        let parts = host.split(separator: ".", omittingEmptySubsequences: false)
+        guard parts.count == 4 else { return nil }
+        let bytes: [UInt8] = parts.compactMap { UInt8($0) }
+        guard bytes.count == 4 else { return nil }
+        return (bytes[0], bytes[1], bytes[2], bytes[3])
+    }
+
+    static func isLocalNetworkIPv4(_ ip: (UInt8, UInt8, UInt8, UInt8)) -> Bool {
+        let (a, b, _, _) = ip
+        if a == 10 { return true }
+        if a == 172, (16...31).contains(Int(b)) { return true }
+        if a == 192, b == 168 { return true }
+        if a == 127 { return true }
+        if a == 169, b == 254 { return true }
+        if a == 100, (64...127).contains(Int(b)) { return true }
+        return false
+    }
+
+    // Formatting helpers live in OpenClawKit (`OpenClawCanvasA2UIAction`).
+}

openclaw/apps/macos/Sources/OpenClaw/CanvasChromeContainerView.swift

@@ -0,0 +1,235 @@
+import AppKit
+import QuartzCore
+
+final class HoverChromeContainerView: NSView {
+    private let content: NSView
+    private let chrome: CanvasChromeOverlayView
+    private var tracking: NSTrackingArea?
+    var onClose: (() -> Void)?
+
+    init(containing content: NSView) {
+        self.content = content
+        self.chrome = CanvasChromeOverlayView(frame: .zero)
+        super.init(frame: .zero)
+
+        self.wantsLayer = true
+        self.layer?.cornerRadius = 12
+        self.layer?.masksToBounds = true
+        self.layer?.backgroundColor = NSColor.windowBackgroundColor.cgColor
+
+        self.content.translatesAutoresizingMaskIntoConstraints = false
+        self.addSubview(self.content)
+
+        self.chrome.translatesAutoresizingMaskIntoConstraints = false
+        self.chrome.alphaValue = 0
+        self.chrome.onClose = { [weak self] in self?.onClose?() }
+        self.addSubview(self.chrome)
+
+        NSLayoutConstraint.activate([
+            self.content.leadingAnchor.constraint(equalTo: self.leadingAnchor),
+            self.content.trailingAnchor.constraint(equalTo: self.trailingAnchor),
+            self.content.topAnchor.constraint(equalTo: self.topAnchor),
+            self.content.bottomAnchor.constraint(equalTo: self.bottomAnchor),
+
+            self.chrome.leadingAnchor.constraint(equalTo: self.leadingAnchor),
+            self.chrome.trailingAnchor.constraint(equalTo: self.trailingAnchor),
+            self.chrome.topAnchor.constraint(equalTo: self.topAnchor),
+            self.chrome.bottomAnchor.constraint(equalTo: self.bottomAnchor),
+        ])
+    }
+
+    @available(*, unavailable)
+    required init?(coder: NSCoder) {
+        fatalError("init(coder:) is not supported")
+    }
+
+    override func updateTrackingAreas() {
+        super.updateTrackingAreas()
+        if let tracking {
+            self.removeTrackingArea(tracking)
+        }
+        let area = NSTrackingArea(
+            rect: self.bounds,
+            options: [.activeAlways, .mouseEnteredAndExited, .inVisibleRect],
+            owner: self,
+            userInfo: nil)
+        self.addTrackingArea(area)
+        self.tracking = area
+    }
+
+    private final class CanvasDragHandleView: NSView {
+        override func mouseDown(with event: NSEvent) {
+            self.window?.performDrag(with: event)
+        }
+
+        override func acceptsFirstMouse(for _: NSEvent?) -> Bool {
+            true
+        }
+    }
+
+    private final class CanvasResizeHandleView: NSView {
+        private var startPoint: NSPoint = .zero
+        private var startFrame: NSRect = .zero
+
+        override func acceptsFirstMouse(for _: NSEvent?) -> Bool {
+            true
+        }
+
+        override func mouseDown(with event: NSEvent) {
+            guard let window else { return }
+            _ = window.makeFirstResponder(self)
+            self.startPoint = NSEvent.mouseLocation
+            self.startFrame = window.frame
+            super.mouseDown(with: event)
+        }
+
+        override func mouseDragged(with _: NSEvent) {
+            guard let window else { return }
+            let current = NSEvent.mouseLocation
+            let dx = current.x - self.startPoint.x
+            let dy = current.y - self.startPoint.y
+
+            var frame = self.startFrame
+            frame.size.width = max(CanvasLayout.minPanelSize.width, frame.size.width + dx)
+            frame.origin.y += dy
+            frame.size.height = max(CanvasLayout.minPanelSize.height, frame.size.height - dy)
+
+            if let screen = window.screen {
+                frame = CanvasWindowController.constrainFrame(frame, toVisibleFrame: screen.visibleFrame)
+            }
+            window.setFrame(frame, display: true)
+        }
+    }
+
+    private final class CanvasChromeOverlayView: NSView {
+        var onClose: (() -> Void)?
+
+        private let dragHandle = CanvasDragHandleView(frame: .zero)
+        private let resizeHandle = CanvasResizeHandleView(frame: .zero)
+
+        private final class PassthroughVisualEffectView: NSVisualEffectView {
+            override func hitTest(_: NSPoint) -> NSView? {
+                nil
+            }
+        }
+
+        private let closeBackground: NSVisualEffectView = {
+            let v = PassthroughVisualEffectView(frame: .zero)
+            v.material = .hudWindow
+            v.blendingMode = .withinWindow
+            v.state = .active
+            v.appearance = NSAppearance(named: .vibrantDark)
+            v.wantsLayer = true
+            v.layer?.cornerRadius = 10
+            v.layer?.masksToBounds = true
+            v.layer?.borderWidth = 1
+            v.layer?.borderColor = NSColor.white.withAlphaComponent(0.22).cgColor
+            v.layer?.backgroundColor = NSColor.black.withAlphaComponent(0.28).cgColor
+            v.layer?.shadowColor = NSColor.black.withAlphaComponent(0.35).cgColor
+            v.layer?.shadowOpacity = 0.35
+            v.layer?.shadowRadius = 8
+            v.layer?.shadowOffset = .zero
+            return v
+        }()
+
+        private let closeButton: NSButton = {
+            let cfg = NSImage.SymbolConfiguration(pointSize: 8, weight: .semibold)
+            let img = NSImage(systemSymbolName: "xmark", accessibilityDescription: "Close")?
+                .withSymbolConfiguration(cfg)
+                ?? NSImage(size: NSSize(width: 18, height: 18))
+            let btn = NSButton(image: img, target: nil, action: nil)
+            btn.isBordered = false
+            btn.bezelStyle = .regularSquare
+            btn.imageScaling = .scaleProportionallyDown
+            btn.contentTintColor = NSColor.white.withAlphaComponent(0.92)
+            btn.toolTip = "Close"
+            return btn
+        }()
+
+        override init(frame frameRect: NSRect) {
+            super.init(frame: frameRect)
+
+            self.wantsLayer = true
+            self.layer?.cornerRadius = 12
+            self.layer?.masksToBounds = true
+            self.layer?.borderWidth = 1
+            self.layer?.borderColor = NSColor.black.withAlphaComponent(0.18).cgColor
+            self.layer?.backgroundColor = NSColor.black.withAlphaComponent(0.02).cgColor
+
+            self.dragHandle.translatesAutoresizingMaskIntoConstraints = false
+            self.dragHandle.wantsLayer = true
+            self.dragHandle.layer?.backgroundColor = NSColor.clear.cgColor
+            self.addSubview(self.dragHandle)
+
+            self.resizeHandle.translatesAutoresizingMaskIntoConstraints = false
+            self.resizeHandle.wantsLayer = true
+            self.resizeHandle.layer?.backgroundColor = NSColor.clear.cgColor
+            self.addSubview(self.resizeHandle)
+
+            self.closeBackground.translatesAutoresizingMaskIntoConstraints = false
+            self.addSubview(self.closeBackground)
+
+            self.closeButton.translatesAutoresizingMaskIntoConstraints = false
+            self.closeButton.target = self
+            self.closeButton.action = #selector(self.handleClose)
+            self.addSubview(self.closeButton)
+
+            NSLayoutConstraint.activate([
+                self.dragHandle.leadingAnchor.constraint(equalTo: self.leadingAnchor),
+                self.dragHandle.trailingAnchor.constraint(equalTo: self.trailingAnchor),
+                self.dragHandle.topAnchor.constraint(equalTo: self.topAnchor),
+                self.dragHandle.heightAnchor.constraint(equalToConstant: 30),
+
+                self.closeBackground.centerXAnchor.constraint(equalTo: self.closeButton.centerXAnchor),
+                self.closeBackground.centerYAnchor.constraint(equalTo: self.closeButton.centerYAnchor),
+                self.closeBackground.widthAnchor.constraint(equalToConstant: 20),
+                self.closeBackground.heightAnchor.constraint(equalToConstant: 20),
+
+                self.closeButton.trailingAnchor.constraint(equalTo: self.trailingAnchor, constant: -8),
+                self.closeButton.topAnchor.constraint(equalTo: self.topAnchor, constant: 8),
+                self.closeButton.widthAnchor.constraint(equalToConstant: 16),
+                self.closeButton.heightAnchor.constraint(equalToConstant: 16),
+
+                self.resizeHandle.trailingAnchor.constraint(equalTo: self.trailingAnchor),
+                self.resizeHandle.bottomAnchor.constraint(equalTo: self.bottomAnchor),
+                self.resizeHandle.widthAnchor.constraint(equalToConstant: 18),
+                self.resizeHandle.heightAnchor.constraint(equalToConstant: 18),
+            ])
+        }
+
+        @available(*, unavailable)
+        required init?(coder: NSCoder) {
+            fatalError("init(coder:) is not supported")
+        }
+
+        override func hitTest(_ point: NSPoint) -> NSView? {
+            // When the chrome is hidden, do not intercept any mouse events (let the WKWebView receive them).
+            guard self.alphaValue > 0.02 else { return nil }
+
+            if self.closeButton.frame.contains(point) { return self.closeButton }
+            if self.dragHandle.frame.contains(point) { return self.dragHandle }
+            if self.resizeHandle.frame.contains(point) { return self.resizeHandle }
+            return nil
+        }
+
+        @objc private func handleClose() {
+            self.onClose?()
+        }
+    }
+
+    override func mouseEntered(with _: NSEvent) {
+        NSAnimationContext.runAnimationGroup { ctx in
+            ctx.duration = 0.12
+            ctx.timingFunction = CAMediaTimingFunction(name: .easeOut)
+            self.chrome.animator().alphaValue = 1
+        }
+    }
+
+    override func mouseExited(with _: NSEvent) {
+        NSAnimationContext.runAnimationGroup { ctx in
+            ctx.duration = 0.16
+            ctx.timingFunction = CAMediaTimingFunction(name: .easeOut)
+            self.chrome.animator().alphaValue = 0
+        }
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/CanvasFileWatcher.swift

@@ -0,0 +1,24 @@
+import Foundation
+
+final class CanvasFileWatcher: @unchecked Sendable {
+    private let watcher: CoalescingFSEventsWatcher
+
+    init(url: URL, onChange: @escaping () -> Void) {
+        self.watcher = CoalescingFSEventsWatcher(
+            paths: [url.path],
+            queueLabel: "ai.openclaw.canvaswatcher",
+            onChange: onChange)
+    }
+
+    deinit {
+        self.stop()
+    }
+
+    func start() {
+        self.watcher.start()
+    }
+
+    func stop() {
+        self.watcher.stop()
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/CanvasManager.swift

@@ -0,0 +1,342 @@
+import AppKit
+import Foundation
+import OpenClawIPC
+import OpenClawKit
+import OSLog
+
+@MainActor
+final class CanvasManager {
+    static let shared = CanvasManager()
+
+    private static let logger = Logger(subsystem: "ai.openclaw", category: "CanvasManager")
+
+    private var panelController: CanvasWindowController?
+    private var panelSessionKey: String?
+    private var lastAutoA2UIUrl: String?
+    private var gatewayWatchTask: Task<Void, Never>?
+
+    private init() {
+        self.startGatewayObserver()
+    }
+
+    var onPanelVisibilityChanged: ((Bool) -> Void)?
+
+    /// Optional anchor provider (e.g. menu bar status item). If nil, Canvas anchors to the mouse cursor.
+    var defaultAnchorProvider: (() -> NSRect?)?
+
+    private nonisolated static let canvasRoot: URL = {
+        let base = FileManager().urls(for: .applicationSupportDirectory, in: .userDomainMask).first!
+        return base.appendingPathComponent("OpenClaw/canvas", isDirectory: true)
+    }()
+
+    func show(sessionKey: String, path: String? = nil, placement: CanvasPlacement? = nil) throws -> String {
+        try self.showDetailed(sessionKey: sessionKey, target: path, placement: placement).directory
+    }
+
+    func showDetailed(
+        sessionKey: String,
+        target: String? = nil,
+        placement: CanvasPlacement? = nil) throws -> CanvasShowResult
+    {
+        Self.logger.debug(
+            """
+            showDetailed start session=\(sessionKey, privacy: .public) \
+            target=\(target ?? "", privacy: .public) \
+            placement=\(placement != nil)
+            """)
+        let anchorProvider = self.defaultAnchorProvider ?? Self.mouseAnchorProvider
+        let session = sessionKey.trimmingCharacters(in: .whitespacesAndNewlines)
+        let normalizedTarget = target?
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+            .nonEmpty
+
+        if let controller = self.panelController, self.panelSessionKey == session {
+            Self.logger.debug("showDetailed reuse existing session=\(session, privacy: .public)")
+            controller.onVisibilityChanged = { [weak self] visible in
+                self?.onPanelVisibilityChanged?(visible)
+            }
+            controller.presentAnchoredPanel(anchorProvider: anchorProvider)
+            controller.applyPreferredPlacement(placement)
+            self.refreshDebugStatus()
+
+            // Existing session: only navigate when an explicit target was provided.
+            if let normalizedTarget {
+                controller.load(target: normalizedTarget)
+                return self.makeShowResult(
+                    directory: controller.directoryPath,
+                    target: target,
+                    effectiveTarget: normalizedTarget)
+            }
+
+            self.maybeAutoNavigateToA2UIAsync(controller: controller)
+            return CanvasShowResult(
+                directory: controller.directoryPath,
+                target: target,
+                effectiveTarget: nil,
+                status: .shown,
+                url: nil)
+        }
+
+        Self.logger.debug("showDetailed creating new session=\(session, privacy: .public)")
+        self.panelController?.close()
+        self.panelController = nil
+        self.panelSessionKey = nil
+
+        Self.logger.debug("showDetailed ensure canvas root dir")
+        try FileManager().createDirectory(at: Self.canvasRoot, withIntermediateDirectories: true)
+        Self.logger.debug("showDetailed init CanvasWindowController")
+        let controller = try CanvasWindowController(
+            sessionKey: session,
+            root: Self.canvasRoot,
+            presentation: .panel(anchorProvider: anchorProvider))
+        Self.logger.debug("showDetailed CanvasWindowController init done")
+        controller.onVisibilityChanged = { [weak self] visible in
+            self?.onPanelVisibilityChanged?(visible)
+        }
+        self.panelController = controller
+        self.panelSessionKey = session
+        controller.applyPreferredPlacement(placement)
+
+        // New session: default to "/" so the user sees either the welcome page or `index.html`.
+        let effectiveTarget = normalizedTarget ?? "/"
+        Self.logger.debug("showDetailed showCanvas effectiveTarget=\(effectiveTarget, privacy: .public)")
+        controller.showCanvas(path: effectiveTarget)
+        Self.logger.debug("showDetailed showCanvas done")
+        if normalizedTarget == nil {
+            self.maybeAutoNavigateToA2UIAsync(controller: controller)
+        }
+        self.refreshDebugStatus()
+
+        return self.makeShowResult(
+            directory: controller.directoryPath,
+            target: target,
+            effectiveTarget: effectiveTarget)
+    }
+
+    func hide(sessionKey: String) {
+        let session = sessionKey.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard self.panelSessionKey == session else { return }
+        self.panelController?.hideCanvas()
+    }
+
+    func hideAll() {
+        self.panelController?.hideCanvas()
+    }
+
+    func eval(sessionKey: String, javaScript: String) async throws -> String {
+        _ = try self.show(sessionKey: sessionKey, path: nil)
+        guard let controller = self.panelController else { return "" }
+        return try await controller.eval(javaScript: javaScript)
+    }
+
+    func snapshot(sessionKey: String, outPath: String?) async throws -> String {
+        _ = try self.show(sessionKey: sessionKey, path: nil)
+        guard let controller = self.panelController else {
+            throw NSError(domain: "Canvas", code: 21, userInfo: [NSLocalizedDescriptionKey: "canvas not available"])
+        }
+        return try await controller.snapshot(to: outPath)
+    }
+
+    // MARK: - Gateway A2UI auto-nav
+
+    private func startGatewayObserver() {
+        self.gatewayWatchTask?.cancel()
+        self.gatewayWatchTask = Task { [weak self] in
+            guard let self else { return }
+            let stream = await GatewayConnection.shared.subscribe(bufferingNewest: 1)
+            for await push in stream {
+                self.handleGatewayPush(push)
+            }
+        }
+    }
+
+    private func handleGatewayPush(_ push: GatewayPush) {
+        guard case let .snapshot(snapshot) = push else { return }
+        let raw = snapshot.canvashosturl?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        if raw.isEmpty {
+            Self.logger.debug("canvas host url missing in gateway snapshot")
+        } else {
+            Self.logger.debug("canvas host url snapshot=\(raw, privacy: .public)")
+        }
+        let a2uiUrl = Self.resolveA2UIHostUrl(from: raw)
+        if a2uiUrl == nil, !raw.isEmpty {
+            Self.logger.debug("canvas host url invalid; cannot resolve A2UI")
+        }
+        guard let controller = self.panelController else {
+            if a2uiUrl != nil {
+                Self.logger.debug("canvas panel not visible; skipping auto-nav")
+            }
+            return
+        }
+        self.maybeAutoNavigateToA2UI(controller: controller, a2uiUrl: a2uiUrl)
+    }
+
+    private func maybeAutoNavigateToA2UIAsync(controller: CanvasWindowController) {
+        Task { [weak self] in
+            guard let self else { return }
+            let a2uiUrl = await self.resolveA2UIHostUrl()
+            await MainActor.run {
+                guard self.panelController === controller else { return }
+                self.maybeAutoNavigateToA2UI(controller: controller, a2uiUrl: a2uiUrl)
+            }
+        }
+    }
+
+    private func maybeAutoNavigateToA2UI(controller: CanvasWindowController, a2uiUrl: String?) {
+        guard let a2uiUrl else { return }
+        let shouldNavigate = controller.shouldAutoNavigateToA2UI(lastAutoTarget: self.lastAutoA2UIUrl)
+        guard shouldNavigate else {
+            Self.logger.debug("canvas auto-nav skipped; target unchanged")
+            return
+        }
+        Self.logger.debug("canvas auto-nav -> \(a2uiUrl, privacy: .public)")
+        controller.load(target: a2uiUrl)
+        self.lastAutoA2UIUrl = a2uiUrl
+    }
+
+    private func resolveA2UIHostUrl() async -> String? {
+        let raw = await GatewayConnection.shared.canvasHostUrl()
+        return Self.resolveA2UIHostUrl(from: raw)
+    }
+
+    func refreshDebugStatus() {
+        guard let controller = self.panelController else { return }
+        let enabled = AppStateStore.shared.debugPaneEnabled
+        let mode = AppStateStore.shared.connectionMode
+        let title: String?
+        let subtitle: String?
+        switch mode {
+        case .remote:
+            title = "Remote control"
+            switch ControlChannel.shared.state {
+            case .connected:
+                subtitle = "Connected"
+            case .connecting:
+                subtitle = "Connecting…"
+            case .disconnected:
+                subtitle = "Disconnected"
+            case let .degraded(message):
+                subtitle = message.isEmpty ? "Degraded" : message
+            }
+        case .local:
+            title = GatewayProcessManager.shared.status.label
+            subtitle = mode.rawValue
+        case .unconfigured:
+            title = "Unconfigured"
+            subtitle = mode.rawValue
+        }
+        controller.updateDebugStatus(enabled: enabled, title: title, subtitle: subtitle)
+    }
+
+    private static func resolveA2UIHostUrl(from raw: String?) -> String? {
+        let trimmed = raw?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        guard !trimmed.isEmpty, let base = URL(string: trimmed) else { return nil }
+        return base.appendingPathComponent("__openclaw__/a2ui/").absoluteString + "?platform=macos"
+    }
+
+    // MARK: - Anchoring
+
+    private static func mouseAnchorProvider() -> NSRect? {
+        let pt = NSEvent.mouseLocation
+        return NSRect(x: pt.x, y: pt.y, width: 1, height: 1)
+    }
+
+    // placement interpretation is handled by the window controller.
+
+    // MARK: - Helpers
+
+    private static func directURL(for target: String?) -> URL? {
+        guard let target else { return nil }
+        let trimmed = target.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return nil }
+
+        if let url = URL(string: trimmed), let scheme = url.scheme?.lowercased() {
+            if scheme == "https" || scheme == "http" || scheme == "file" { return url }
+        }
+
+        // Convenience: existing absolute *file* paths resolve as local files.
+        // (Avoid treating Canvas routes like "/" as filesystem paths.)
+        if trimmed.hasPrefix("/") {
+            var isDir: ObjCBool = false
+            if FileManager().fileExists(atPath: trimmed, isDirectory: &isDir), !isDir.boolValue {
+                return URL(fileURLWithPath: trimmed)
+            }
+        }
+
+        return nil
+    }
+
+    private func makeShowResult(
+        directory: String,
+        target: String?,
+        effectiveTarget: String) -> CanvasShowResult
+    {
+        if let url = Self.directURL(for: effectiveTarget) {
+            return CanvasShowResult(
+                directory: directory,
+                target: target,
+                effectiveTarget: effectiveTarget,
+                status: .web,
+                url: url.absoluteString)
+        }
+
+        let sessionDir = URL(fileURLWithPath: directory)
+        let status = Self.localStatus(sessionDir: sessionDir, target: effectiveTarget)
+        let host = sessionDir.lastPathComponent
+        let canvasURL = CanvasScheme.makeURL(session: host, path: effectiveTarget)?.absoluteString
+        return CanvasShowResult(
+            directory: directory,
+            target: target,
+            effectiveTarget: effectiveTarget,
+            status: status,
+            url: canvasURL)
+    }
+
+    private static func localStatus(sessionDir: URL, target: String) -> CanvasShowStatus {
+        let fm = FileManager()
+        let trimmed = target.trimmingCharacters(in: .whitespacesAndNewlines)
+        let withoutQuery = trimmed.split(separator: "?", maxSplits: 1, omittingEmptySubsequences: false).first
+            .map(String.init) ?? trimmed
+        var path = withoutQuery
+        if path.hasPrefix("/") { path.removeFirst() }
+        path = path.removingPercentEncoding ?? path
+
+        // Root special-case: built-in scaffold page when no index exists.
+        if path.isEmpty {
+            let a = sessionDir.appendingPathComponent("index.html", isDirectory: false)
+            let b = sessionDir.appendingPathComponent("index.htm", isDirectory: false)
+            if fm.fileExists(atPath: a.path) || fm.fileExists(atPath: b.path) { return .ok }
+            return .welcome
+        }
+
+        // Direct file or directory.
+        var candidate = sessionDir.appendingPathComponent(path, isDirectory: false)
+        var isDir: ObjCBool = false
+        if fm.fileExists(atPath: candidate.path, isDirectory: &isDir) {
+            if isDir.boolValue {
+                return Self.indexExists(in: candidate) ? .ok : .notFound
+            }
+            return .ok
+        }
+
+        // Directory index behavior ("/yolo" -> "yolo/index.html") if directory exists.
+        if !path.isEmpty, !path.hasSuffix("/") {
+            candidate = sessionDir.appendingPathComponent(path, isDirectory: true)
+            if fm.fileExists(atPath: candidate.path, isDirectory: &isDir), isDir.boolValue {
+                return Self.indexExists(in: candidate) ? .ok : .notFound
+            }
+        }
+
+        return .notFound
+    }
+
+    private static func indexExists(in dir: URL) -> Bool {
+        let fm = FileManager()
+        let a = dir.appendingPathComponent("index.html", isDirectory: false)
+        if fm.fileExists(atPath: a.path) { return true }
+        let b = dir.appendingPathComponent("index.htm", isDirectory: false)
+        return fm.fileExists(atPath: b.path)
+    }
+
+    // no bundled A2UI shell; scaffold fallback is purely visual
+}

openclaw/apps/macos/Sources/OpenClaw/CanvasScheme.swift

@@ -0,0 +1,42 @@
+import Foundation
+
+enum CanvasScheme {
+    static let scheme = "openclaw-canvas"
+    static let allSchemes = [scheme]
+
+    static func makeURL(session: String, path: String? = nil) -> URL? {
+        var comps = URLComponents()
+        comps.scheme = Self.scheme
+        comps.host = session
+        let p = (path ?? "/").trimmingCharacters(in: .whitespacesAndNewlines)
+        if p.isEmpty || p == "/" {
+            comps.path = "/"
+        } else if p.hasPrefix("/") {
+            comps.path = p
+        } else {
+            comps.path = "/" + p
+        }
+        return comps.url
+    }
+
+    static func mimeType(forExtension ext: String) -> String {
+        switch ext.lowercased() {
+        // Note: WKURLSchemeHandler uses URLResponse(mimeType:), which expects a bare MIME type
+        // (no `; charset=...`). Encoding is provided via URLResponse(textEncodingName:).
+        case "html", "htm": "text/html"
+        case "js", "mjs": "application/javascript"
+        case "css": "text/css"
+        case "json", "map": "application/json"
+        case "svg": "image/svg+xml"
+        case "png": "image/png"
+        case "jpg", "jpeg": "image/jpeg"
+        case "gif": "image/gif"
+        case "ico": "image/x-icon"
+        case "woff2": "font/woff2"
+        case "woff": "font/woff"
+        case "ttf": "font/ttf"
+        case "wasm": "application/wasm"
+        default: "application/octet-stream"
+        }
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/CanvasSchemeHandler.swift

@@ -0,0 +1,259 @@
+import Foundation
+import OpenClawKit
+import OSLog
+import WebKit
+
+private let canvasLogger = Logger(subsystem: "ai.openclaw", category: "Canvas")
+
+final class CanvasSchemeHandler: NSObject, WKURLSchemeHandler {
+    private let root: URL
+
+    init(root: URL) {
+        self.root = root
+    }
+
+    func webView(_: WKWebView, start urlSchemeTask: WKURLSchemeTask) {
+        guard let url = urlSchemeTask.request.url else {
+            urlSchemeTask.didFailWithError(NSError(domain: "Canvas", code: 1, userInfo: [
+                NSLocalizedDescriptionKey: "missing url",
+            ]))
+            return
+        }
+
+        let response = self.response(for: url)
+        let mime = response.mime
+        let data = response.data
+        let encoding = self.textEncodingName(forMimeType: mime)
+
+        let urlResponse = URLResponse(
+            url: url,
+            mimeType: mime,
+            expectedContentLength: data.count,
+            textEncodingName: encoding)
+        urlSchemeTask.didReceive(urlResponse)
+        urlSchemeTask.didReceive(data)
+        urlSchemeTask.didFinish()
+    }
+
+    func webView(_: WKWebView, stop _: WKURLSchemeTask) {
+        // no-op
+    }
+
+    private struct CanvasResponse {
+        let mime: String
+        let data: Data
+    }
+
+    private func response(for url: URL) -> CanvasResponse {
+        guard let scheme = url.scheme, CanvasScheme.allSchemes.contains(scheme) else {
+            return self.html("Invalid scheme.")
+        }
+        guard let session = url.host, !session.isEmpty else {
+            return self.html("Missing session.")
+        }
+
+        // Keep session component safe; don't allow slashes or traversal.
+        if session.contains("/") || session.contains("..") {
+            return self.html("Invalid session.")
+        }
+
+        let sessionRoot = self.root.appendingPathComponent(session, isDirectory: true)
+
+        // Path mapping: request path maps directly into the session dir.
+        var path = url.path
+        if let qIdx = path.firstIndex(of: "?") { path = String(path[..<qIdx]) }
+        if path.hasPrefix("/") { path.removeFirst() }
+        path = path.removingPercentEncoding ?? path
+
+        // Special-case: welcome page when root index is missing.
+        if path.isEmpty {
+            let indexA = sessionRoot.appendingPathComponent("index.html", isDirectory: false)
+            let indexB = sessionRoot.appendingPathComponent("index.htm", isDirectory: false)
+            if !FileManager().fileExists(atPath: indexA.path),
+               !FileManager().fileExists(atPath: indexB.path)
+            {
+                return self.scaffoldPage(sessionRoot: sessionRoot)
+            }
+        }
+
+        let resolved = self.resolveFileURL(sessionRoot: sessionRoot, requestPath: path)
+        guard let fileURL = resolved else {
+            return self.html("Not Found", title: "Canvas: 404")
+        }
+
+        // Directory traversal guard: served files must live under the session root.
+        let standardizedRoot = sessionRoot.standardizedFileURL
+        let standardizedFile = fileURL.standardizedFileURL
+        guard standardizedFile.path.hasPrefix(standardizedRoot.path) else {
+            return self.html("Forbidden", title: "Canvas: 403")
+        }
+
+        do {
+            let data = try Data(contentsOf: standardizedFile)
+            let mime = CanvasScheme.mimeType(forExtension: standardizedFile.pathExtension)
+            let servedPath = standardizedFile.path
+            canvasLogger.debug(
+                "served \(session, privacy: .public)/\(path, privacy: .public) -> \(servedPath, privacy: .public)")
+            return CanvasResponse(mime: mime, data: data)
+        } catch {
+            let failedPath = standardizedFile.path
+            let errorText = error.localizedDescription
+            canvasLogger
+                .error(
+                    "failed reading \(failedPath, privacy: .public): \(errorText, privacy: .public)")
+            return self.html("Failed to read file.", title: "Canvas error")
+        }
+    }
+
+    private func resolveFileURL(sessionRoot: URL, requestPath: String) -> URL? {
+        let fm = FileManager()
+        var candidate = sessionRoot.appendingPathComponent(requestPath, isDirectory: false)
+
+        var isDir: ObjCBool = false
+        if fm.fileExists(atPath: candidate.path, isDirectory: &isDir) {
+            if isDir.boolValue {
+                if let idx = self.resolveIndex(in: candidate) { return idx }
+                return nil
+            }
+            return candidate
+        }
+
+        // Directory index behavior:
+        // - "/yolo" serves "<yolo>/index.html" if that directory exists.
+        if !requestPath.isEmpty, !requestPath.hasSuffix("/") {
+            candidate = sessionRoot.appendingPathComponent(requestPath, isDirectory: true)
+            if fm.fileExists(atPath: candidate.path, isDirectory: &isDir), isDir.boolValue {
+                if let idx = self.resolveIndex(in: candidate) { return idx }
+            }
+        }
+
+        // Root fallback:
+        // - "/" serves "<sessionRoot>/index.html" if present.
+        if requestPath.isEmpty {
+            return self.resolveIndex(in: sessionRoot)
+        }
+
+        return nil
+    }
+
+    private func resolveIndex(in dir: URL) -> URL? {
+        let fm = FileManager()
+        let a = dir.appendingPathComponent("index.html", isDirectory: false)
+        if fm.fileExists(atPath: a.path) { return a }
+        let b = dir.appendingPathComponent("index.htm", isDirectory: false)
+        if fm.fileExists(atPath: b.path) { return b }
+        return nil
+    }
+
+    private func html(_ body: String, title: String = "Canvas") -> CanvasResponse {
+        let html = """
+        <!doctype html>
+        <html>
+          <head>
+            <meta charset="utf-8" />
+            <meta name="viewport" content="width=device-width, initial-scale=1" />
+            <title>\(title)</title>
+            <style>
+              :root { color-scheme: light; }
+              html,body { height:100%; margin:0; }
+              body {
+                font: 13px -apple-system, system-ui;
+                display:flex;
+                align-items:center;
+                justify-content:center;
+                background: #fff;
+                color:#111827;
+              }
+              .card {
+                max-width: 520px;
+                padding: 18px 18px;
+                border-radius: 12px;
+                border: 1px solid rgba(0,0,0,.08);
+                box-shadow: 0 10px 30px rgba(0,0,0,.08);
+              }
+              .muted { color:#6b7280; margin-top:8px; }
+              code { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; }
+            </style>
+          </head>
+          <body>
+            <div class="card">
+              <div>\(body)</div>
+            </div>
+          </body>
+        </html>
+        """
+        return CanvasResponse(mime: "text/html", data: Data(html.utf8))
+    }
+
+    private func welcomePage(sessionRoot: URL) -> CanvasResponse {
+        let escaped = sessionRoot.path
+            .replacingOccurrences(of: "&", with: "&amp;")
+            .replacingOccurrences(of: "<", with: "&lt;")
+            .replacingOccurrences(of: ">", with: "&gt;")
+        let body = """
+        <div style="font-weight:600; font-size:14px;">Canvas is ready.</div>
+        <div class="muted">Create <code>index.html</code> in:</div>
+        <div style="margin-top:10px;"><code>\(escaped)</code></div>
+        """
+        return self.html(body, title: "Canvas")
+    }
+
+    private func scaffoldPage(sessionRoot: URL) -> CanvasResponse {
+        // Default Canvas UX: when no index exists, show the built-in scaffold page.
+        if let data = self.loadBundledResourceData(relativePath: "CanvasScaffold/scaffold.html") {
+            return CanvasResponse(mime: "text/html", data: data)
+        }
+
+        // Fallback for dev misconfiguration: show the classic welcome page.
+        return self.welcomePage(sessionRoot: sessionRoot)
+    }
+
+    private func loadBundledResourceData(relativePath: String) -> Data? {
+        let trimmed = relativePath.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return nil }
+        if trimmed.contains("..") || trimmed.contains("\\") { return nil }
+
+        let parts = trimmed.split(separator: "/")
+        guard let filename = parts.last else { return nil }
+        let subdirectory =
+            parts.count > 1 ? parts.dropLast().joined(separator: "/") : nil
+        let fileURL = URL(fileURLWithPath: String(filename))
+        let ext = fileURL.pathExtension
+        let name = fileURL.deletingPathExtension().lastPathComponent
+        guard !name.isEmpty, !ext.isEmpty else { return nil }
+
+        let bundle = OpenClawKitResources.bundle
+        let resourceURL =
+            bundle.url(forResource: name, withExtension: ext, subdirectory: subdirectory)
+            ?? bundle.url(forResource: name, withExtension: ext)
+        guard let resourceURL else { return nil }
+        return try? Data(contentsOf: resourceURL)
+    }
+
+    private func textEncodingName(forMimeType mimeType: String) -> String? {
+        if mimeType.hasPrefix("text/") { return "utf-8" }
+        switch mimeType {
+        case "application/javascript", "application/json", "image/svg+xml":
+            return "utf-8"
+        default:
+            return nil
+        }
+    }
+}
+
+#if DEBUG
+extension CanvasSchemeHandler {
+    func _testResponse(for url: URL) -> (mime: String, data: Data) {
+        let response = self.response(for: url)
+        return (response.mime, response.data)
+    }
+
+    func _testResolveFileURL(sessionRoot: URL, requestPath: String) -> URL? {
+        self.resolveFileURL(sessionRoot: sessionRoot, requestPath: requestPath)
+    }
+
+    func _testTextEncodingName(for mimeType: String) -> String? {
+        self.textEncodingName(forMimeType: mimeType)
+    }
+}
+#endif

openclaw/apps/macos/Sources/OpenClaw/CanvasWindow.swift

@@ -0,0 +1,31 @@
+import AppKit
+
+let canvasWindowLogger = Logger(subsystem: "ai.openclaw", category: "Canvas")
+
+enum CanvasLayout {
+    static let panelSize = NSSize(width: 520, height: 680)
+    static let windowSize = NSSize(width: 1120, height: 840)
+    static let anchorPadding: CGFloat = 8
+    static let defaultPadding: CGFloat = 10
+    static let minPanelSize = NSSize(width: 360, height: 360)
+}
+
+final class CanvasPanel: NSPanel {
+    override var canBecomeKey: Bool {
+        true
+    }
+
+    override var canBecomeMain: Bool {
+        true
+    }
+}
+
+enum CanvasPresentation {
+    case window
+    case panel(anchorProvider: () -> NSRect?)
+
+    var isPanel: Bool {
+        if case .panel = self { return true }
+        return false
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/CanvasWindowController+Helpers.swift

@@ -0,0 +1,43 @@
+import AppKit
+import Foundation
+
+extension CanvasWindowController {
+    // MARK: - Helpers
+
+    static func sanitizeSessionKey(_ key: String) -> String {
+        let trimmed = key.trimmingCharacters(in: .whitespacesAndNewlines)
+        if trimmed.isEmpty { return "main" }
+        let allowed = CharacterSet(charactersIn: "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-+")
+        let scalars = trimmed.unicodeScalars.map { allowed.contains($0) ? Character($0) : "_" }
+        return String(scalars)
+    }
+
+    static func jsStringLiteral(_ value: String) -> String {
+        let data = try? JSONEncoder().encode(value)
+        return data.flatMap { String(data: $0, encoding: .utf8) } ?? "\"\""
+    }
+
+    static func jsOptionalStringLiteral(_ value: String?) -> String {
+        guard let value else { return "null" }
+        return Self.jsStringLiteral(value)
+    }
+
+    static func storedFrameDefaultsKey(sessionKey: String) -> String {
+        "openclaw.canvas.frame.\(self.sanitizeSessionKey(sessionKey))"
+    }
+
+    static func loadRestoredFrame(sessionKey: String) -> NSRect? {
+        let key = self.storedFrameDefaultsKey(sessionKey: sessionKey)
+        guard let arr = UserDefaults.standard.array(forKey: key) as? [Double], arr.count == 4 else { return nil }
+        let rect = NSRect(x: arr[0], y: arr[1], width: arr[2], height: arr[3])
+        if rect.width < CanvasLayout.minPanelSize.width || rect.height < CanvasLayout.minPanelSize.height { return nil }
+        return rect
+    }
+
+    static func storeRestoredFrame(_ frame: NSRect, sessionKey: String) {
+        let key = self.storedFrameDefaultsKey(sessionKey: sessionKey)
+        UserDefaults.standard.set(
+            [Double(frame.origin.x), Double(frame.origin.y), Double(frame.size.width), Double(frame.size.height)],
+            forKey: key)
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/CanvasWindowController+Navigation.swift

@@ -0,0 +1,64 @@
+import AppKit
+import WebKit
+
+extension CanvasWindowController {
+    // MARK: - WKNavigationDelegate
+
+    @MainActor
+    func webView(
+        _: WKWebView,
+        decidePolicyFor navigationAction: WKNavigationAction,
+        decisionHandler: @escaping @MainActor @Sendable (WKNavigationActionPolicy) -> Void)
+    {
+        guard let url = navigationAction.request.url else {
+            decisionHandler(.cancel)
+            return
+        }
+        let scheme = url.scheme?.lowercased()
+
+        // Deep links: allow local Canvas content to invoke the agent without bouncing through NSWorkspace.
+        if scheme == "openclaw" {
+            if let currentScheme = self.webView.url?.scheme,
+               CanvasScheme.allSchemes.contains(currentScheme)
+            {
+                Task { await DeepLinkHandler.shared.handle(url: url) }
+            } else {
+                canvasWindowLogger
+                    .debug("ignoring deep link from non-canvas page \(url.absoluteString, privacy: .public)")
+            }
+            decisionHandler(.cancel)
+            return
+        }
+
+        // Keep web content inside the panel when reasonable.
+        // `about:blank` and friends are common internal navigations for WKWebView; never send them to NSWorkspace.
+        if CanvasScheme.allSchemes.contains(scheme ?? "")
+            || scheme == "https"
+            || scheme == "http"
+            || scheme == "about"
+            || scheme == "blob"
+            || scheme == "data"
+            || scheme == "javascript"
+        {
+            decisionHandler(.allow)
+            return
+        }
+
+        // Only open external URLs when there is a registered handler, otherwise macOS will show a confusing
+        // "There is no application set to open the URL ..." alert (e.g. for about:blank).
+        if let appURL = NSWorkspace.shared.urlForApplication(toOpen: url) {
+            NSWorkspace.shared.open(
+                [url],
+                withApplicationAt: appURL,
+                configuration: NSWorkspace.OpenConfiguration(),
+                completionHandler: nil)
+        } else {
+            canvasWindowLogger.debug("no application to open url \(url.absoluteString, privacy: .public)")
+        }
+        decisionHandler(.cancel)
+    }
+
+    func webView(_: WKWebView, didFinish _: WKNavigation?) {
+        self.applyDebugStatusIfNeeded()
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/CanvasWindowController+Testing.swift

@@ -0,0 +1,39 @@
+#if DEBUG
+import AppKit
+import Foundation
+
+extension CanvasWindowController {
+    static func _testSanitizeSessionKey(_ key: String) -> String {
+        self.sanitizeSessionKey(key)
+    }
+
+    static func _testJSStringLiteral(_ value: String) -> String {
+        self.jsStringLiteral(value)
+    }
+
+    static func _testJSOptionalStringLiteral(_ value: String?) -> String {
+        self.jsOptionalStringLiteral(value)
+    }
+
+    static func _testStoredFrameKey(sessionKey: String) -> String {
+        self.storedFrameDefaultsKey(sessionKey: sessionKey)
+    }
+
+    static func _testStoreAndLoadFrame(sessionKey: String, frame: NSRect) -> NSRect? {
+        self.storeRestoredFrame(frame, sessionKey: sessionKey)
+        return self.loadRestoredFrame(sessionKey: sessionKey)
+    }
+
+    static func _testParseIPv4(_ host: String) -> (UInt8, UInt8, UInt8, UInt8)? {
+        CanvasA2UIActionMessageHandler.parseIPv4(host)
+    }
+
+    static func _testIsLocalNetworkIPv4(_ ip: (UInt8, UInt8, UInt8, UInt8)) -> Bool {
+        CanvasA2UIActionMessageHandler.isLocalNetworkIPv4(ip)
+    }
+
+    static func _testIsLocalNetworkCanvasURL(_ url: URL) -> Bool {
+        CanvasA2UIActionMessageHandler.isLocalNetworkCanvasURL(url)
+    }
+}
+#endif

openclaw/apps/macos/Sources/OpenClaw/CanvasWindowController+Window.swift

@@ -0,0 +1,166 @@
+import AppKit
+import OpenClawIPC
+
+extension CanvasWindowController {
+    // MARK: - Window
+
+    static func makeWindow(for presentation: CanvasPresentation, contentView: NSView) -> NSWindow {
+        switch presentation {
+        case .window:
+            let window = NSWindow(
+                contentRect: NSRect(origin: .zero, size: CanvasLayout.windowSize),
+                styleMask: [.titled, .closable, .resizable, .miniaturizable],
+                backing: .buffered,
+                defer: false)
+            window.title = "OpenClaw Canvas"
+            window.isReleasedWhenClosed = false
+            window.contentView = contentView
+            window.center()
+            window.minSize = NSSize(width: 880, height: 680)
+            return window
+
+        case .panel:
+            let panel = CanvasPanel(
+                contentRect: NSRect(origin: .zero, size: CanvasLayout.panelSize),
+                styleMask: [.borderless, .resizable],
+                backing: .buffered,
+                defer: false)
+            // Keep Canvas below the Voice Wake overlay panel.
+            panel.level = NSWindow.Level(rawValue: NSWindow.Level.statusBar.rawValue - 1)
+            panel.hasShadow = true
+            panel.isMovable = false
+            panel.collectionBehavior = [.canJoinAllSpaces, .fullScreenAuxiliary]
+            panel.titleVisibility = .hidden
+            panel.titlebarAppearsTransparent = true
+            panel.backgroundColor = .clear
+            panel.isOpaque = false
+            panel.contentView = contentView
+            panel.becomesKeyOnlyIfNeeded = true
+            panel.hidesOnDeactivate = false
+            panel.minSize = CanvasLayout.minPanelSize
+            return panel
+        }
+    }
+
+    func presentAnchoredPanel(anchorProvider: @escaping () -> NSRect?) {
+        guard case .panel = self.presentation, let window else { return }
+        self.repositionPanel(using: anchorProvider)
+        window.makeKeyAndOrderFront(nil)
+        NSApp.activate(ignoringOtherApps: true)
+        window.makeFirstResponder(self.webView)
+        VoiceWakeOverlayController.shared.bringToFrontIfVisible()
+        self.onVisibilityChanged?(true)
+    }
+
+    func repositionPanel(using anchorProvider: () -> NSRect?) {
+        guard let panel = self.window else { return }
+        let anchor = anchorProvider()
+        let targetScreen = Self.screen(forAnchor: anchor)
+            ?? Self.screenContainingMouseCursor()
+            ?? panel.screen
+            ?? NSScreen.main
+            ?? NSScreen.screens.first
+
+        let restored = Self.loadRestoredFrame(sessionKey: self.sessionKey)
+        let restoredIsValid = if let restored, let targetScreen {
+            Self.isFrameMeaningfullyVisible(restored, on: targetScreen)
+        } else {
+            restored != nil
+        }
+
+        var frame = if let restored, restoredIsValid {
+            restored
+        } else {
+            Self.defaultTopRightFrame(panel: panel, screen: targetScreen)
+        }
+
+        // Apply agent placement as partial overrides:
+        // - If agent provides x/y, override origin.
+        // - If agent provides width/height, override size.
+        // - If agent provides only size, keep the remembered origin.
+        if let placement = self.preferredPlacement {
+            if let x = placement.x { frame.origin.x = x }
+            if let y = placement.y { frame.origin.y = y }
+            if let w = placement.width { frame.size.width = max(CanvasLayout.minPanelSize.width, CGFloat(w)) }
+            if let h = placement.height { frame.size.height = max(CanvasLayout.minPanelSize.height, CGFloat(h)) }
+        }
+
+        self.setPanelFrame(frame, on: targetScreen)
+    }
+
+    static func defaultTopRightFrame(panel: NSWindow, screen: NSScreen?) -> NSRect {
+        let w = max(CanvasLayout.minPanelSize.width, panel.frame.width)
+        let h = max(CanvasLayout.minPanelSize.height, panel.frame.height)
+        return WindowPlacement.topRightFrame(
+            size: NSSize(width: w, height: h),
+            padding: CanvasLayout.defaultPadding,
+            on: screen)
+    }
+
+    func setPanelFrame(_ frame: NSRect, on screen: NSScreen?) {
+        guard let panel = self.window else { return }
+        guard let s = screen ?? panel.screen ?? NSScreen.main ?? NSScreen.screens.first else {
+            panel.setFrame(frame, display: false)
+            self.persistFrameIfPanel()
+            return
+        }
+
+        let constrained = Self.constrainFrame(frame, toVisibleFrame: s.visibleFrame)
+        panel.setFrame(constrained, display: false)
+        self.persistFrameIfPanel()
+    }
+
+    static func screen(forAnchor anchor: NSRect?) -> NSScreen? {
+        guard let anchor else { return nil }
+        let center = NSPoint(x: anchor.midX, y: anchor.midY)
+        return NSScreen.screens.first { screen in
+            screen.frame.contains(anchor.origin) || screen.frame.contains(center)
+        }
+    }
+
+    static func screenContainingMouseCursor() -> NSScreen? {
+        let point = NSEvent.mouseLocation
+        return NSScreen.screens.first { $0.frame.contains(point) }
+    }
+
+    static func isFrameMeaningfullyVisible(_ frame: NSRect, on screen: NSScreen) -> Bool {
+        frame.intersects(screen.visibleFrame.insetBy(dx: 12, dy: 12))
+    }
+
+    static func constrainFrame(_ frame: NSRect, toVisibleFrame bounds: NSRect) -> NSRect {
+        if bounds == .zero { return frame }
+
+        var next = frame
+        next.size.width = min(max(CanvasLayout.minPanelSize.width, next.size.width), bounds.width)
+        next.size.height = min(max(CanvasLayout.minPanelSize.height, next.size.height), bounds.height)
+
+        let maxX = bounds.maxX - next.size.width
+        let maxY = bounds.maxY - next.size.height
+
+        next.origin.x = maxX >= bounds.minX ? min(max(next.origin.x, bounds.minX), maxX) : bounds.minX
+        next.origin.y = maxY >= bounds.minY ? min(max(next.origin.y, bounds.minY), maxY) : bounds.minY
+
+        next.origin.x = round(next.origin.x)
+        next.origin.y = round(next.origin.y)
+        return next
+    }
+
+    // MARK: - NSWindowDelegate
+
+    func windowWillClose(_: Notification) {
+        self.onVisibilityChanged?(false)
+    }
+
+    func windowDidMove(_: Notification) {
+        self.persistFrameIfPanel()
+    }
+
+    func windowDidEndLiveResize(_: Notification) {
+        self.persistFrameIfPanel()
+    }
+
+    func persistFrameIfPanel() {
+        guard case .panel = self.presentation, let window else { return }
+        Self.storeRestoredFrame(window.frame, sessionKey: self.sessionKey)
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/CanvasWindowController.swift

@@ -0,0 +1,373 @@
+import AppKit
+import Foundation
+import OpenClawIPC
+import OpenClawKit
+import WebKit
+
+@MainActor
+final class CanvasWindowController: NSWindowController, WKNavigationDelegate, NSWindowDelegate {
+    let sessionKey: String
+    private let root: URL
+    private let sessionDir: URL
+    private let schemeHandler: CanvasSchemeHandler
+    let webView: WKWebView
+    private var a2uiActionMessageHandler: CanvasA2UIActionMessageHandler?
+    private let watcher: CanvasFileWatcher
+    private let container: HoverChromeContainerView
+    let presentation: CanvasPresentation
+    var preferredPlacement: CanvasPlacement?
+    private(set) var currentTarget: String?
+    private var debugStatusEnabled = false
+    private var debugStatusTitle: String?
+    private var debugStatusSubtitle: String?
+
+    var onVisibilityChanged: ((Bool) -> Void)?
+
+    init(sessionKey: String, root: URL, presentation: CanvasPresentation) throws {
+        self.sessionKey = sessionKey
+        self.root = root
+        self.presentation = presentation
+
+        canvasWindowLogger.debug("CanvasWindowController init start session=\(sessionKey, privacy: .public)")
+        let safeSessionKey = CanvasWindowController.sanitizeSessionKey(sessionKey)
+        canvasWindowLogger.debug("CanvasWindowController init sanitized session=\(safeSessionKey, privacy: .public)")
+        self.sessionDir = root.appendingPathComponent(safeSessionKey, isDirectory: true)
+        try FileManager().createDirectory(at: self.sessionDir, withIntermediateDirectories: true)
+        canvasWindowLogger.debug("CanvasWindowController init session dir ready")
+
+        self.schemeHandler = CanvasSchemeHandler(root: root)
+        canvasWindowLogger.debug("CanvasWindowController init scheme handler ready")
+
+        let config = WKWebViewConfiguration()
+        config.userContentController = WKUserContentController()
+        config.preferences.isElementFullscreenEnabled = true
+        config.preferences.setValue(true, forKey: "developerExtrasEnabled")
+        canvasWindowLogger.debug("CanvasWindowController init config ready")
+        for scheme in CanvasScheme.allSchemes {
+            config.setURLSchemeHandler(self.schemeHandler, forURLScheme: scheme)
+        }
+        canvasWindowLogger.debug("CanvasWindowController init scheme handler installed")
+
+        // Bridge A2UI "a2uiaction" DOM events back into the native agent loop.
+        //
+        // Prefer WKScriptMessageHandler when WebKit exposes it, otherwise fall back to an unattended deep link
+        // (includes the app-generated key so it won't prompt).
+        canvasWindowLogger.debug("CanvasWindowController init building A2UI bridge script")
+        let deepLinkKey = DeepLinkHandler.currentCanvasKey()
+        let injectedSessionKey = sessionKey.trimmingCharacters(in: .whitespacesAndNewlines).nonEmpty ?? "main"
+        let bridgeScript = """
+        (() => {
+          try {
+            const allowedSchemes = \(String(describing: CanvasScheme.allSchemes));
+            const protocol = location.protocol.replace(':', '');
+            if (!allowedSchemes.includes(protocol)) return;
+            if (globalThis.__openclawA2UIBridgeInstalled) return;
+            globalThis.__openclawA2UIBridgeInstalled = true;
+
+            const deepLinkKey = \(Self.jsStringLiteral(deepLinkKey));
+            const sessionKey = \(Self.jsStringLiteral(injectedSessionKey));
+            const machineName = \(Self.jsStringLiteral(InstanceIdentity.displayName));
+            const instanceId = \(Self.jsStringLiteral(InstanceIdentity.instanceId));
+
+            globalThis.addEventListener('a2uiaction', (evt) => {
+              try {
+                const payload = evt?.detail ?? evt?.payload ?? null;
+                if (!payload || payload.eventType !== 'a2ui.action') return;
+
+                const action = payload.action ?? null;
+                const name = action?.name ?? '';
+                if (!name) return;
+
+                const context = Array.isArray(action?.context) ? action.context : [];
+                const userAction = {
+                  id: (globalThis.crypto?.randomUUID?.() ?? String(Date.now())),
+                  name,
+                  surfaceId: payload.surfaceId ?? 'main',
+                  sourceComponentId: payload.sourceComponentId ?? '',
+                  dataContextPath: payload.dataContextPath ?? '',
+                  timestamp: new Date().toISOString(),
+                  ...(context.length ? { context } : {}),
+                };
+
+                const handler = globalThis.webkit?.messageHandlers?.openclawCanvasA2UIAction;
+
+                // If the bundled A2UI shell is present, let it forward actions so we keep its richer
+                // context resolution (data model path lookups, surface detection, etc.).
+                const hasBundledA2UIHost =
+                  !!globalThis.openclawA2UI ||
+                  !!document.querySelector('openclaw-a2ui-host');
+                if (hasBundledA2UIHost && handler?.postMessage) return;
+
+                // Otherwise, forward directly when possible.
+                if (!hasBundledA2UIHost && handler?.postMessage) {
+                  handler.postMessage({ userAction });
+                  return;
+                }
+
+                const ctx = userAction.context ? (' ctx=' + JSON.stringify(userAction.context)) : '';
+                const message =
+                  'CANVAS_A2UI action=' + userAction.name +
+                  ' session=' + sessionKey +
+                  ' surface=' + userAction.surfaceId +
+                  ' component=' + (userAction.sourceComponentId || '-') +
+                  ' host=' + machineName.replace(/\\s+/g, '_') +
+                  ' instance=' + instanceId +
+                  ctx +
+                  ' default=update_canvas';
+                const params = new URLSearchParams();
+                params.set('message', message);
+                params.set('sessionKey', sessionKey);
+                params.set('thinking', 'low');
+                params.set('deliver', 'false');
+                params.set('channel', 'last');
+                params.set('key', deepLinkKey);
+                location.href = 'openclaw://agent?' + params.toString();
+              } catch {}
+            }, true);
+          } catch {}
+        })();
+        """
+        config.userContentController.addUserScript(
+            WKUserScript(source: bridgeScript, injectionTime: .atDocumentStart, forMainFrameOnly: true))
+        canvasWindowLogger.debug("CanvasWindowController init A2UI bridge installed")
+
+        canvasWindowLogger.debug("CanvasWindowController init creating WKWebView")
+        self.webView = WKWebView(frame: .zero, configuration: config)
+        // Canvas scaffold is a fully self-contained HTML page; avoid relying on transparency underlays.
+        self.webView.setValue(true, forKey: "drawsBackground")
+
+        let sessionDir = self.sessionDir
+        let webView = self.webView
+        self.watcher = CanvasFileWatcher(url: sessionDir) { [weak webView] in
+            Task { @MainActor in
+                guard let webView else { return }
+
+                // Only auto-reload when we are showing local canvas content.
+                guard let scheme = webView.url?.scheme,
+                      CanvasScheme.allSchemes.contains(scheme) else { return }
+
+                let path = webView.url?.path ?? ""
+                if path == "/" || path.isEmpty {
+                    let indexA = sessionDir.appendingPathComponent("index.html", isDirectory: false)
+                    let indexB = sessionDir.appendingPathComponent("index.htm", isDirectory: false)
+                    if !FileManager().fileExists(atPath: indexA.path),
+                       !FileManager().fileExists(atPath: indexB.path)
+                    {
+                        return
+                    }
+                }
+
+                webView.reload()
+            }
+        }
+
+        self.container = HoverChromeContainerView(containing: self.webView)
+        let window = Self.makeWindow(for: presentation, contentView: self.container)
+        canvasWindowLogger.debug("CanvasWindowController init makeWindow done")
+        super.init(window: window)
+
+        let handler = CanvasA2UIActionMessageHandler(sessionKey: sessionKey)
+        self.a2uiActionMessageHandler = handler
+        for name in CanvasA2UIActionMessageHandler.allMessageNames {
+            self.webView.configuration.userContentController.add(handler, name: name)
+        }
+
+        self.webView.navigationDelegate = self
+        self.window?.delegate = self
+        self.container.onClose = { [weak self] in
+            self?.hideCanvas()
+        }
+
+        self.watcher.start()
+        canvasWindowLogger.debug("CanvasWindowController init done")
+    }
+
+    @available(*, unavailable)
+    required init?(coder: NSCoder) {
+        fatalError("init(coder:) is not supported")
+    }
+
+    @MainActor deinit {
+        for name in CanvasA2UIActionMessageHandler.allMessageNames {
+            self.webView.configuration.userContentController.removeScriptMessageHandler(forName: name)
+        }
+        self.watcher.stop()
+    }
+
+    func applyPreferredPlacement(_ placement: CanvasPlacement?) {
+        self.preferredPlacement = placement
+    }
+
+    func showCanvas(path: String? = nil) {
+        if case let .panel(anchorProvider) = self.presentation {
+            self.presentAnchoredPanel(anchorProvider: anchorProvider)
+            if let path {
+                self.load(target: path)
+            }
+            return
+        }
+
+        self.showWindow(nil)
+        self.window?.makeKeyAndOrderFront(nil)
+        NSApp.activate(ignoringOtherApps: true)
+        if let path {
+            self.load(target: path)
+        }
+        self.onVisibilityChanged?(true)
+    }
+
+    func hideCanvas() {
+        if case .panel = self.presentation {
+            self.persistFrameIfPanel()
+        }
+        self.window?.orderOut(nil)
+        self.onVisibilityChanged?(false)
+    }
+
+    func load(target: String) {
+        let trimmed = target.trimmingCharacters(in: .whitespacesAndNewlines)
+        self.currentTarget = trimmed
+
+        if let url = URL(string: trimmed), let scheme = url.scheme?.lowercased() {
+            if scheme == "https" || scheme == "http" {
+                canvasWindowLogger.debug("canvas load url \(url.absoluteString, privacy: .public)")
+                self.webView.load(URLRequest(url: url))
+                return
+            }
+            if scheme == "file" {
+                canvasWindowLogger.debug("canvas load file \(url.absoluteString, privacy: .public)")
+                self.loadFile(url)
+                return
+            }
+        }
+
+        // Convenience: absolute file paths resolve as local files when they exist.
+        // (Avoid treating Canvas routes like "/" as filesystem paths.)
+        if trimmed.hasPrefix("/") {
+            var isDir: ObjCBool = false
+            if FileManager().fileExists(atPath: trimmed, isDirectory: &isDir), !isDir.boolValue {
+                let url = URL(fileURLWithPath: trimmed)
+                canvasWindowLogger.debug("canvas load file \(url.absoluteString, privacy: .public)")
+                self.loadFile(url)
+                return
+            }
+        }
+
+        guard let url = CanvasScheme.makeURL(
+            session: CanvasWindowController.sanitizeSessionKey(self.sessionKey),
+            path: trimmed)
+        else {
+            canvasWindowLogger
+                .error(
+                    "invalid canvas url session=\(self.sessionKey, privacy: .public) path=\(trimmed, privacy: .public)")
+            return
+        }
+        canvasWindowLogger.debug("canvas load canvas \(url.absoluteString, privacy: .public)")
+        self.webView.load(URLRequest(url: url))
+    }
+
+    func updateDebugStatus(enabled: Bool, title: String?, subtitle: String?) {
+        self.debugStatusEnabled = enabled
+        self.debugStatusTitle = title
+        self.debugStatusSubtitle = subtitle
+        self.applyDebugStatusIfNeeded()
+    }
+
+    func applyDebugStatusIfNeeded() {
+        let enabled = self.debugStatusEnabled
+        let title = Self.jsOptionalStringLiteral(self.debugStatusTitle)
+        let subtitle = Self.jsOptionalStringLiteral(self.debugStatusSubtitle)
+        let js = """
+        (() => {
+          try {
+            const api = globalThis.__openclaw;
+            if (!api) return;
+            if (typeof api.setDebugStatusEnabled === 'function') {
+              api.setDebugStatusEnabled(\(enabled ? "true" : "false"));
+            }
+            if (!\(enabled ? "true" : "false")) return;
+            if (typeof api.setStatus === 'function') {
+              api.setStatus(\(title), \(subtitle));
+            }
+          } catch (_) {}
+        })();
+        """
+        self.webView.evaluateJavaScript(js) { _, _ in }
+    }
+
+    private func loadFile(_ url: URL) {
+        let fileURL = url.isFileURL ? url : URL(fileURLWithPath: url.path)
+        let accessDir = fileURL.deletingLastPathComponent()
+        self.webView.loadFileURL(fileURL, allowingReadAccessTo: accessDir)
+    }
+
+    func eval(javaScript: String) async throws -> String {
+        try await withCheckedThrowingContinuation { cont in
+            self.webView.evaluateJavaScript(javaScript) { result, error in
+                if let error {
+                    cont.resume(throwing: error)
+                    return
+                }
+                if let result {
+                    cont.resume(returning: String(describing: result))
+                } else {
+                    cont.resume(returning: "")
+                }
+            }
+        }
+    }
+
+    func snapshot(to outPath: String?) async throws -> String {
+        let image: NSImage = try await withCheckedThrowingContinuation { cont in
+            self.webView.takeSnapshot(with: nil) { image, error in
+                if let error {
+                    cont.resume(throwing: error)
+                    return
+                }
+                guard let image else {
+                    cont.resume(throwing: NSError(domain: "Canvas", code: 11, userInfo: [
+                        NSLocalizedDescriptionKey: "snapshot returned nil image",
+                    ]))
+                    return
+                }
+                cont.resume(returning: image)
+            }
+        }
+
+        guard let tiff = image.tiffRepresentation,
+              let rep = NSBitmapImageRep(data: tiff),
+              let png = rep.representation(using: .png, properties: [:])
+        else {
+            throw NSError(domain: "Canvas", code: 12, userInfo: [
+                NSLocalizedDescriptionKey: "failed to encode png",
+            ])
+        }
+
+        let path: String
+        if let outPath, !outPath.isEmpty {
+            path = outPath
+        } else {
+            let ts = Int(Date().timeIntervalSince1970)
+            path = "/tmp/openclaw-canvas-\(CanvasWindowController.sanitizeSessionKey(self.sessionKey))-\(ts).png"
+        }
+
+        try png.write(to: URL(fileURLWithPath: path), options: [.atomic])
+        return path
+    }
+
+    var directoryPath: String {
+        self.sessionDir.path
+    }
+
+    func shouldAutoNavigateToA2UI(lastAutoTarget: String?) -> Bool {
+        let trimmed = (self.currentTarget ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
+        if trimmed.isEmpty || trimmed == "/" { return true }
+        if let lastAuto = lastAutoTarget?.trimmingCharacters(in: .whitespacesAndNewlines),
+           !lastAuto.isEmpty,
+           trimmed == lastAuto
+        {
+            return true
+        }
+        return false
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/ChannelConfigForm.swift

@@ -0,0 +1,363 @@
+import SwiftUI
+
+struct ConfigSchemaForm: View {
+    @Bindable var store: ChannelsStore
+    let schema: ConfigSchemaNode
+    let path: ConfigPath
+
+    var body: some View {
+        self.renderNode(self.schema, path: self.path)
+    }
+
+    private func renderNode(_ schema: ConfigSchemaNode, path: ConfigPath) -> AnyView {
+        let storedValue = self.store.configValue(at: path)
+        let value = storedValue ?? schema.explicitDefault
+        let label = hintForPath(path, hints: store.configUiHints)?.label ?? schema.title
+        let help = hintForPath(path, hints: store.configUiHints)?.help ?? schema.description
+        let variants = schema.anyOf.isEmpty ? schema.oneOf : schema.anyOf
+
+        if !variants.isEmpty {
+            let nonNull = variants.filter { !$0.isNullSchema }
+            if nonNull.count == 1, let only = nonNull.first {
+                return self.renderNode(only, path: path)
+            }
+            let literals = nonNull.compactMap(\.literalValue)
+            if !literals.isEmpty, literals.count == nonNull.count {
+                return AnyView(
+                    VStack(alignment: .leading, spacing: 6) {
+                        if let label { Text(label).font(.callout.weight(.semibold)) }
+                        if let help {
+                            Text(help)
+                                .font(.caption)
+                                .foregroundStyle(.secondary)
+                        }
+                        Picker(
+                            "",
+                            selection: self.enumBinding(
+                                path,
+                                options: literals,
+                                defaultValue: schema.explicitDefault))
+                        {
+                            Text("Select…").tag(-1)
+                            ForEach(literals.indices, id: \ .self) { index in
+                                Text(String(describing: literals[index])).tag(index)
+                            }
+                        }
+                        .pickerStyle(.menu)
+                    })
+            }
+        }
+
+        switch schema.schemaType {
+        case "object":
+            return AnyView(
+                VStack(alignment: .leading, spacing: 12) {
+                    if let label {
+                        Text(label)
+                            .font(.callout.weight(.semibold))
+                    }
+                    if let help {
+                        Text(help)
+                            .font(.caption)
+                            .foregroundStyle(.secondary)
+                    }
+                    let properties = schema.properties
+                    let sortedKeys = properties.keys.sorted { lhs, rhs in
+                        let orderA = hintForPath(path + [.key(lhs)], hints: store.configUiHints)?.order ?? 0
+                        let orderB = hintForPath(path + [.key(rhs)], hints: store.configUiHints)?.order ?? 0
+                        if orderA != orderB { return orderA < orderB }
+                        return lhs < rhs
+                    }
+                    ForEach(sortedKeys, id: \ .self) { key in
+                        if let child = properties[key] {
+                            self.renderNode(child, path: path + [.key(key)])
+                        }
+                    }
+                    if schema.allowsAdditionalProperties {
+                        self.renderAdditionalProperties(schema, path: path, value: value)
+                    }
+                })
+        case "array":
+            return AnyView(self.renderArray(schema, path: path, value: value, label: label, help: help))
+        case "boolean":
+            return AnyView(
+                Toggle(isOn: self.boolBinding(path, defaultValue: schema.explicitDefault as? Bool)) {
+                    if let label { Text(label) } else { Text("Enabled") }
+                }
+                .help(help ?? ""))
+        case "number", "integer":
+            return AnyView(self.renderNumberField(schema, path: path, label: label, help: help))
+        case "string":
+            return AnyView(self.renderStringField(schema, path: path, label: label, help: help))
+        default:
+            return AnyView(
+                VStack(alignment: .leading, spacing: 6) {
+                    if let label { Text(label).font(.callout.weight(.semibold)) }
+                    Text("Unsupported field type.")
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                })
+        }
+    }
+
+    @ViewBuilder
+    private func renderStringField(
+        _ schema: ConfigSchemaNode,
+        path: ConfigPath,
+        label: String?,
+        help: String?) -> some View
+    {
+        let hint = hintForPath(path, hints: store.configUiHints)
+        let placeholder = hint?.placeholder ?? ""
+        let sensitive = hint?.sensitive ?? isSensitivePath(path)
+        let defaultValue = schema.explicitDefault as? String
+        VStack(alignment: .leading, spacing: 6) {
+            if let label { Text(label).font(.callout.weight(.semibold)) }
+            if let help {
+                Text(help)
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+            }
+            if let options = schema.enumValues {
+                Picker("", selection: self.enumBinding(path, options: options, defaultValue: schema.explicitDefault)) {
+                    Text("Select…").tag(-1)
+                    ForEach(options.indices, id: \ .self) { index in
+                        Text(String(describing: options[index])).tag(index)
+                    }
+                }
+                .pickerStyle(.menu)
+            } else if sensitive {
+                SecureField(placeholder, text: self.stringBinding(path, defaultValue: defaultValue))
+                    .textFieldStyle(.roundedBorder)
+            } else {
+                TextField(placeholder, text: self.stringBinding(path, defaultValue: defaultValue))
+                    .textFieldStyle(.roundedBorder)
+            }
+        }
+    }
+
+    @ViewBuilder
+    private func renderNumberField(
+        _ schema: ConfigSchemaNode,
+        path: ConfigPath,
+        label: String?,
+        help: String?) -> some View
+    {
+        let defaultValue = (schema.explicitDefault as? Double)
+            ?? (schema.explicitDefault as? Int).map(Double.init)
+        VStack(alignment: .leading, spacing: 6) {
+            if let label { Text(label).font(.callout.weight(.semibold)) }
+            if let help {
+                Text(help)
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+            }
+            TextField(
+                "",
+                text: self.numberBinding(
+                    path,
+                    isInteger: schema.schemaType == "integer",
+                    defaultValue: defaultValue))
+                .textFieldStyle(.roundedBorder)
+        }
+    }
+
+    @ViewBuilder
+    private func renderArray(
+        _ schema: ConfigSchemaNode,
+        path: ConfigPath,
+        value: Any?,
+        label: String?,
+        help: String?) -> some View
+    {
+        let items = value as? [Any] ?? []
+        let itemSchema = schema.items
+        VStack(alignment: .leading, spacing: 10) {
+            if let label { Text(label).font(.callout.weight(.semibold)) }
+            if let help {
+                Text(help)
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+            }
+            ForEach(items.indices, id: \ .self) { index in
+                HStack(alignment: .top, spacing: 8) {
+                    if let itemSchema {
+                        self.renderNode(itemSchema, path: path + [.index(index)])
+                    } else {
+                        Text(String(describing: items[index]))
+                    }
+                    Button("Remove") {
+                        var next = items
+                        next.remove(at: index)
+                        self.store.updateConfigValue(path: path, value: next)
+                    }
+                    .buttonStyle(.bordered)
+                    .controlSize(.small)
+                }
+            }
+            Button("Add") {
+                var next = items
+                if let itemSchema {
+                    next.append(itemSchema.defaultValue)
+                } else {
+                    next.append("")
+                }
+                self.store.updateConfigValue(path: path, value: next)
+            }
+            .buttonStyle(.bordered)
+            .controlSize(.small)
+        }
+    }
+
+    @ViewBuilder
+    private func renderAdditionalProperties(
+        _ schema: ConfigSchemaNode,
+        path: ConfigPath,
+        value: Any?) -> some View
+    {
+        if let additionalSchema = schema.additionalProperties {
+            let dict = value as? [String: Any] ?? [:]
+            let reserved = Set(schema.properties.keys)
+            let extras = dict.keys.filter { !reserved.contains($0) }.sorted()
+
+            VStack(alignment: .leading, spacing: 8) {
+                Text("Extra entries")
+                    .font(.callout.weight(.semibold))
+                if extras.isEmpty {
+                    Text("No extra entries yet.")
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                } else {
+                    ForEach(extras, id: \ .self) { key in
+                        let itemPath: ConfigPath = path + [.key(key)]
+                        HStack(alignment: .top, spacing: 8) {
+                            TextField("Key", text: self.mapKeyBinding(path: path, key: key))
+                                .textFieldStyle(.roundedBorder)
+                                .frame(width: 160)
+                            self.renderNode(additionalSchema, path: itemPath)
+                            Button("Remove") {
+                                var next = dict
+                                next.removeValue(forKey: key)
+                                self.store.updateConfigValue(path: path, value: next)
+                            }
+                            .buttonStyle(.bordered)
+                            .controlSize(.small)
+                        }
+                    }
+                }
+                Button("Add") {
+                    var next = dict
+                    var index = 1
+                    var key = "new-\(index)"
+                    while next[key] != nil {
+                        index += 1
+                        key = "new-\(index)"
+                    }
+                    next[key] = additionalSchema.defaultValue
+                    self.store.updateConfigValue(path: path, value: next)
+                }
+                .buttonStyle(.bordered)
+                .controlSize(.small)
+            }
+        }
+    }
+
+    private func stringBinding(_ path: ConfigPath, defaultValue: String?) -> Binding<String> {
+        Binding(
+            get: {
+                if let value = store.configValue(at: path) as? String { return value }
+                return defaultValue ?? ""
+            },
+            set: { newValue in
+                let trimmed = newValue.trimmingCharacters(in: .whitespacesAndNewlines)
+                self.store.updateConfigValue(path: path, value: trimmed.isEmpty ? nil : trimmed)
+            })
+    }
+
+    private func boolBinding(_ path: ConfigPath, defaultValue: Bool?) -> Binding<Bool> {
+        Binding(
+            get: {
+                if let value = store.configValue(at: path) as? Bool { return value }
+                return defaultValue ?? false
+            },
+            set: { newValue in
+                self.store.updateConfigValue(path: path, value: newValue)
+            })
+    }
+
+    private func numberBinding(
+        _ path: ConfigPath,
+        isInteger: Bool,
+        defaultValue: Double?) -> Binding<String>
+    {
+        Binding(
+            get: {
+                if let value = store.configValue(at: path) { return String(describing: value) }
+                guard let defaultValue else { return "" }
+                return isInteger ? String(Int(defaultValue)) : String(defaultValue)
+            },
+            set: { newValue in
+                let trimmed = newValue.trimmingCharacters(in: .whitespacesAndNewlines)
+                if trimmed.isEmpty {
+                    self.store.updateConfigValue(path: path, value: nil)
+                } else if let value = Double(trimmed) {
+                    self.store.updateConfigValue(path: path, value: isInteger ? Int(value) : value)
+                }
+            })
+    }
+
+    private func enumBinding(
+        _ path: ConfigPath,
+        options: [Any],
+        defaultValue: Any?) -> Binding<Int>
+    {
+        Binding(
+            get: {
+                let value = self.store.configValue(at: path) ?? defaultValue
+                guard let value else { return -1 }
+                return options.firstIndex { option in
+                    String(describing: option) == String(describing: value)
+                } ?? -1
+            },
+            set: { index in
+                guard index >= 0, index < options.count else {
+                    self.store.updateConfigValue(path: path, value: nil)
+                    return
+                }
+                self.store.updateConfigValue(path: path, value: options[index])
+            })
+    }
+
+    private func mapKeyBinding(path: ConfigPath, key: String) -> Binding<String> {
+        Binding(
+            get: { key },
+            set: { newValue in
+                let trimmed = newValue.trimmingCharacters(in: .whitespacesAndNewlines)
+                guard !trimmed.isEmpty else { return }
+                guard trimmed != key else { return }
+                let current = self.store.configValue(at: path) as? [String: Any] ?? [:]
+                guard current[trimmed] == nil else { return }
+                var next = current
+                next[trimmed] = current[key]
+                next.removeValue(forKey: key)
+                self.store.updateConfigValue(path: path, value: next)
+            })
+    }
+}
+
+struct ChannelConfigForm: View {
+    @Bindable var store: ChannelsStore
+    let channelId: String
+
+    var body: some View {
+        if self.store.configSchemaLoading {
+            ProgressView().controlSize(.small)
+        } else if let schema = store.channelConfigSchema(for: channelId) {
+            ConfigSchemaForm(store: self.store, schema: schema, path: [.key("channels"), .key(self.channelId)])
+        } else {
+            Text("Schema unavailable for this channel.")
+                .font(.caption)
+                .foregroundStyle(.secondary)
+        }
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/ChannelsSettings+ChannelSections.swift

@@ -0,0 +1,137 @@
+import SwiftUI
+
+extension ChannelsSettings {
+    func formSection(_ title: String, @ViewBuilder content: () -> some View) -> some View {
+        GroupBox(title) {
+            VStack(alignment: .leading, spacing: 10) {
+                content()
+            }
+            .frame(maxWidth: .infinity, alignment: .leading)
+        }
+    }
+
+    func channelHeaderActions(_ channel: ChannelItem) -> some View {
+        HStack(spacing: 8) {
+            if channel.id == "whatsapp" {
+                Button("Logout") {
+                    Task { await self.store.logoutWhatsApp() }
+                }
+                .buttonStyle(.bordered)
+                .disabled(self.store.whatsappBusy)
+            }
+
+            if channel.id == "telegram" {
+                Button("Logout") {
+                    Task { await self.store.logoutTelegram() }
+                }
+                .buttonStyle(.bordered)
+                .disabled(self.store.telegramBusy)
+            }
+
+            Button {
+                Task { await self.store.refresh(probe: true) }
+            } label: {
+                if self.store.isRefreshing {
+                    ProgressView().controlSize(.small)
+                } else {
+                    Text("Refresh")
+                }
+            }
+            .buttonStyle(.bordered)
+            .disabled(self.store.isRefreshing)
+        }
+        .controlSize(.small)
+    }
+
+    var whatsAppSection: some View {
+        VStack(alignment: .leading, spacing: 16) {
+            self.formSection("Linking") {
+                if let message = self.store.whatsappLoginMessage {
+                    Text(message)
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                        .fixedSize(horizontal: false, vertical: true)
+                }
+
+                if let qr = self.store.whatsappLoginQrDataUrl, let image = self.qrImage(from: qr) {
+                    Image(nsImage: image)
+                        .resizable()
+                        .interpolation(.none)
+                        .frame(width: 180, height: 180)
+                        .cornerRadius(8)
+                }
+
+                HStack(spacing: 12) {
+                    Button {
+                        Task { await self.store.startWhatsAppLogin(force: false) }
+                    } label: {
+                        if self.store.whatsappBusy {
+                            ProgressView().controlSize(.small)
+                        } else {
+                            Text("Show QR")
+                        }
+                    }
+                    .buttonStyle(.borderedProminent)
+                    .disabled(self.store.whatsappBusy)
+
+                    Button("Relink") {
+                        Task { await self.store.startWhatsAppLogin(force: true) }
+                    }
+                    .buttonStyle(.bordered)
+                    .disabled(self.store.whatsappBusy)
+                }
+                .font(.caption)
+            }
+
+            self.configEditorSection(channelId: "whatsapp")
+        }
+    }
+
+    func genericChannelSection(_ channel: ChannelItem) -> some View {
+        VStack(alignment: .leading, spacing: 16) {
+            self.configEditorSection(channelId: channel.id)
+        }
+    }
+
+    @ViewBuilder
+    private func configEditorSection(channelId: String) -> some View {
+        self.formSection("Configuration") {
+            ChannelConfigForm(store: self.store, channelId: channelId)
+        }
+
+        self.configStatusMessage
+
+        HStack(spacing: 12) {
+            Button {
+                Task { await self.store.saveConfigDraft() }
+            } label: {
+                if self.store.isSavingConfig {
+                    ProgressView().controlSize(.small)
+                } else {
+                    Text("Save")
+                }
+            }
+            .buttonStyle(.borderedProminent)
+            .disabled(self.store.isSavingConfig || !self.store.configDirty)
+
+            Button("Reload") {
+                Task { await self.store.reloadConfigDraft() }
+            }
+            .buttonStyle(.bordered)
+            .disabled(self.store.isSavingConfig)
+
+            Spacer()
+        }
+        .font(.caption)
+    }
+
+    @ViewBuilder
+    var configStatusMessage: some View {
+        if let status = self.store.configStatus {
+            Text(status)
+                .font(.caption)
+                .foregroundStyle(.secondary)
+                .fixedSize(horizontal: false, vertical: true)
+        }
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/ChannelsSettings+ChannelState.swift

@@ -0,0 +1,508 @@
+import OpenClawProtocol
+import SwiftUI
+
+extension ChannelsSettings {
+    private func channelStatus<T: Decodable>(
+        _ id: String,
+        as type: T.Type) -> T?
+    {
+        self.store.snapshot?.decodeChannel(id, as: type)
+    }
+
+    var whatsAppTint: Color {
+        guard let status = self.channelStatus("whatsapp", as: ChannelsStatusSnapshot.WhatsAppStatus.self)
+        else { return .secondary }
+        if !status.configured { return .secondary }
+        if !status.linked { return .red }
+        if status.lastError != nil { return .orange }
+        if status.connected { return .green }
+        if status.running { return .orange }
+        return .orange
+    }
+
+    var telegramTint: Color {
+        guard let status = self.channelStatus("telegram", as: ChannelsStatusSnapshot.TelegramStatus.self)
+        else { return .secondary }
+        if !status.configured { return .secondary }
+        if status.lastError != nil { return .orange }
+        if status.probe?.ok == false { return .orange }
+        if status.running { return .green }
+        return .orange
+    }
+
+    var discordTint: Color {
+        guard let status = self.channelStatus("discord", as: ChannelsStatusSnapshot.DiscordStatus.self)
+        else { return .secondary }
+        if !status.configured { return .secondary }
+        if status.lastError != nil { return .orange }
+        if status.probe?.ok == false { return .orange }
+        if status.running { return .green }
+        return .orange
+    }
+
+    var googlechatTint: Color {
+        guard let status = self.channelStatus("googlechat", as: ChannelsStatusSnapshot.GoogleChatStatus.self)
+        else { return .secondary }
+        if !status.configured { return .secondary }
+        if status.lastError != nil { return .orange }
+        if status.probe?.ok == false { return .orange }
+        if status.running { return .green }
+        return .orange
+    }
+
+    var signalTint: Color {
+        guard let status = self.channelStatus("signal", as: ChannelsStatusSnapshot.SignalStatus.self)
+        else { return .secondary }
+        if !status.configured { return .secondary }
+        if status.lastError != nil { return .orange }
+        if status.probe?.ok == false { return .orange }
+        if status.running { return .green }
+        return .orange
+    }
+
+    var imessageTint: Color {
+        guard let status = self.channelStatus("imessage", as: ChannelsStatusSnapshot.IMessageStatus.self)
+        else { return .secondary }
+        if !status.configured { return .secondary }
+        if status.lastError != nil { return .orange }
+        if status.probe?.ok == false { return .orange }
+        if status.running { return .green }
+        return .orange
+    }
+
+    var whatsAppSummary: String {
+        guard let status = self.channelStatus("whatsapp", as: ChannelsStatusSnapshot.WhatsAppStatus.self)
+        else { return "Checking…" }
+        if !status.linked { return "Not linked" }
+        if status.connected { return "Connected" }
+        if status.running { return "Running" }
+        return "Linked"
+    }
+
+    var telegramSummary: String {
+        guard let status = self.channelStatus("telegram", as: ChannelsStatusSnapshot.TelegramStatus.self)
+        else { return "Checking…" }
+        if !status.configured { return "Not configured" }
+        if status.running { return "Running" }
+        return "Configured"
+    }
+
+    var discordSummary: String {
+        guard let status = self.channelStatus("discord", as: ChannelsStatusSnapshot.DiscordStatus.self)
+        else { return "Checking…" }
+        if !status.configured { return "Not configured" }
+        if status.running { return "Running" }
+        return "Configured"
+    }
+
+    var googlechatSummary: String {
+        guard let status = self.channelStatus("googlechat", as: ChannelsStatusSnapshot.GoogleChatStatus.self)
+        else { return "Checking…" }
+        if !status.configured { return "Not configured" }
+        if status.running { return "Running" }
+        return "Configured"
+    }
+
+    var signalSummary: String {
+        guard let status = self.channelStatus("signal", as: ChannelsStatusSnapshot.SignalStatus.self)
+        else { return "Checking…" }
+        if !status.configured { return "Not configured" }
+        if status.running { return "Running" }
+        return "Configured"
+    }
+
+    var imessageSummary: String {
+        guard let status = self.channelStatus("imessage", as: ChannelsStatusSnapshot.IMessageStatus.self)
+        else { return "Checking…" }
+        if !status.configured { return "Not configured" }
+        if status.running { return "Running" }
+        return "Configured"
+    }
+
+    var whatsAppDetails: String? {
+        guard let status = self.channelStatus("whatsapp", as: ChannelsStatusSnapshot.WhatsAppStatus.self)
+        else { return nil }
+        var lines: [String] = []
+        if let e164 = status.`self`?.e164 ?? status.`self`?.jid {
+            lines.append("Linked as \(e164)")
+        }
+        if let age = status.authAgeMs {
+            lines.append("Auth age \(msToAge(age))")
+        }
+        if let last = self.date(fromMs: status.lastConnectedAt) {
+            lines.append("Last connect \(relativeAge(from: last))")
+        }
+        if let disconnect = status.lastDisconnect {
+            let when = self.date(fromMs: disconnect.at).map { relativeAge(from: $0) } ?? "unknown"
+            let code = disconnect.status.map { "status \($0)" } ?? "status unknown"
+            let err = disconnect.error ?? "disconnect"
+            lines.append("Last disconnect \(code) · \(err) · \(when)")
+        }
+        if status.reconnectAttempts > 0 {
+            lines.append("Reconnect attempts \(status.reconnectAttempts)")
+        }
+        if let msgAt = self.date(fromMs: status.lastMessageAt) {
+            lines.append("Last message \(relativeAge(from: msgAt))")
+        }
+        if let err = status.lastError, !err.isEmpty {
+            lines.append("Error: \(err)")
+        }
+        return lines.isEmpty ? nil : lines.joined(separator: " · ")
+    }
+
+    var telegramDetails: String? {
+        guard let status = self.channelStatus("telegram", as: ChannelsStatusSnapshot.TelegramStatus.self)
+        else { return nil }
+        var lines: [String] = []
+        if let source = status.tokenSource {
+            lines.append("Token source: \(source)")
+        }
+        if let mode = status.mode {
+            lines.append("Mode: \(mode)")
+        }
+        if let probe = status.probe {
+            if probe.ok {
+                if let name = probe.bot?.username {
+                    lines.append("Bot: @\(name)")
+                }
+                if let url = probe.webhook?.url, !url.isEmpty {
+                    lines.append("Webhook: \(url)")
+                }
+            } else {
+                let code = probe.status.map { String($0) } ?? "unknown"
+                lines.append("Probe failed (\(code))")
+            }
+        }
+        if let last = self.date(fromMs: status.lastProbeAt) {
+            lines.append("Last probe \(relativeAge(from: last))")
+        }
+        if let err = status.lastError, !err.isEmpty {
+            lines.append("Error: \(err)")
+        }
+        return lines.isEmpty ? nil : lines.joined(separator: " · ")
+    }
+
+    var discordDetails: String? {
+        guard let status = self.channelStatus("discord", as: ChannelsStatusSnapshot.DiscordStatus.self)
+        else { return nil }
+        var lines: [String] = []
+        if let source = status.tokenSource {
+            lines.append("Token source: \(source)")
+        }
+        if let probe = status.probe {
+            if probe.ok {
+                if let name = probe.bot?.username {
+                    lines.append("Bot: @\(name)")
+                }
+                if let elapsed = probe.elapsedMs {
+                    lines.append("Probe \(Int(elapsed))ms")
+                }
+            } else {
+                let code = probe.status.map { String($0) } ?? "unknown"
+                lines.append("Probe failed (\(code))")
+            }
+        }
+        if let last = self.date(fromMs: status.lastProbeAt) {
+            lines.append("Last probe \(relativeAge(from: last))")
+        }
+        if let err = status.lastError, !err.isEmpty {
+            lines.append("Error: \(err)")
+        }
+        return lines.isEmpty ? nil : lines.joined(separator: " · ")
+    }
+
+    var googlechatDetails: String? {
+        guard let status = self.channelStatus("googlechat", as: ChannelsStatusSnapshot.GoogleChatStatus.self)
+        else { return nil }
+        var lines: [String] = []
+        if let source = status.credentialSource {
+            lines.append("Credential: \(source)")
+        }
+        if let audienceType = status.audienceType {
+            let audience = status.audience ?? ""
+            let label = audience.isEmpty ? audienceType : "\(audienceType) \(audience)"
+            lines.append("Audience: \(label)")
+        }
+        if let probe = status.probe {
+            if probe.ok {
+                if let elapsed = probe.elapsedMs {
+                    lines.append("Probe \(Int(elapsed))ms")
+                }
+            } else {
+                let code = probe.status.map { String($0) } ?? "unknown"
+                lines.append("Probe failed (\(code))")
+            }
+        }
+        if let last = self.date(fromMs: status.lastProbeAt) {
+            lines.append("Last probe \(relativeAge(from: last))")
+        }
+        if let err = status.lastError, !err.isEmpty {
+            lines.append("Error: \(err)")
+        }
+        return lines.isEmpty ? nil : lines.joined(separator: " · ")
+    }
+
+    var signalDetails: String? {
+        guard let status = self.channelStatus("signal", as: ChannelsStatusSnapshot.SignalStatus.self)
+        else { return nil }
+        var lines: [String] = []
+        lines.append("Base URL: \(status.baseUrl)")
+        if let probe = status.probe {
+            if probe.ok {
+                if let version = probe.version, !version.isEmpty {
+                    lines.append("Version \(version)")
+                }
+                if let elapsed = probe.elapsedMs {
+                    lines.append("Probe \(Int(elapsed))ms")
+                }
+            } else {
+                let code = probe.status.map { String($0) } ?? "unknown"
+                lines.append("Probe failed (\(code))")
+            }
+        }
+        if let last = self.date(fromMs: status.lastProbeAt) {
+            lines.append("Last probe \(relativeAge(from: last))")
+        }
+        if let err = status.lastError, !err.isEmpty {
+            lines.append("Error: \(err)")
+        }
+        return lines.isEmpty ? nil : lines.joined(separator: " · ")
+    }
+
+    var imessageDetails: String? {
+        guard let status = self.channelStatus("imessage", as: ChannelsStatusSnapshot.IMessageStatus.self)
+        else { return nil }
+        var lines: [String] = []
+        if let cliPath = status.cliPath, !cliPath.isEmpty {
+            lines.append("CLI: \(cliPath)")
+        }
+        if let dbPath = status.dbPath, !dbPath.isEmpty {
+            lines.append("DB: \(dbPath)")
+        }
+        if let probe = status.probe, !probe.ok {
+            let err = probe.error ?? "probe failed"
+            lines.append("Probe error: \(err)")
+        }
+        if let last = self.date(fromMs: status.lastProbeAt) {
+            lines.append("Last probe \(relativeAge(from: last))")
+        }
+        if let err = status.lastError, !err.isEmpty {
+            lines.append("Error: \(err)")
+        }
+        return lines.isEmpty ? nil : lines.joined(separator: " · ")
+    }
+
+    var orderedChannels: [ChannelItem] {
+        let fallback = ["whatsapp", "telegram", "discord", "googlechat", "slack", "signal", "imessage"]
+        let order = self.store.snapshot?.channelOrder ?? fallback
+        let channels = order.enumerated().map { index, id in
+            ChannelItem(
+                id: id,
+                title: self.resolveChannelTitle(id),
+                detailTitle: self.resolveChannelDetailTitle(id),
+                systemImage: self.resolveChannelSystemImage(id),
+                sortOrder: index)
+        }
+        return channels.sorted { lhs, rhs in
+            let lhsEnabled = self.channelEnabled(lhs)
+            let rhsEnabled = self.channelEnabled(rhs)
+            if lhsEnabled != rhsEnabled { return lhsEnabled && !rhsEnabled }
+            return lhs.sortOrder < rhs.sortOrder
+        }
+    }
+
+    var enabledChannels: [ChannelItem] {
+        self.orderedChannels.filter { self.channelEnabled($0) }
+    }
+
+    var availableChannels: [ChannelItem] {
+        self.orderedChannels.filter { !self.channelEnabled($0) }
+    }
+
+    func ensureSelection() {
+        guard let selected = self.selectedChannel else {
+            self.selectedChannel = self.orderedChannels.first
+            return
+        }
+        if !self.orderedChannels.contains(selected) {
+            self.selectedChannel = self.orderedChannels.first
+        }
+    }
+
+    func channelEnabled(_ channel: ChannelItem) -> Bool {
+        let status = self.channelStatusDictionary(channel.id)
+        let configured = status?["configured"]?.boolValue ?? false
+        let running = status?["running"]?.boolValue ?? false
+        let connected = status?["connected"]?.boolValue ?? false
+        let accountActive = self.store.snapshot?.channelAccounts[channel.id]?.contains(
+            where: { $0.configured == true || $0.running == true || $0.connected == true }) ?? false
+        return configured || running || connected || accountActive
+    }
+
+    @ViewBuilder
+    func channelSection(_ channel: ChannelItem) -> some View {
+        if channel.id == "whatsapp" {
+            self.whatsAppSection
+        } else {
+            self.genericChannelSection(channel)
+        }
+    }
+
+    func channelTint(_ channel: ChannelItem) -> Color {
+        switch channel.id {
+        case "whatsapp":
+            return self.whatsAppTint
+        case "telegram":
+            return self.telegramTint
+        case "discord":
+            return self.discordTint
+        case "googlechat":
+            return self.googlechatTint
+        case "signal":
+            return self.signalTint
+        case "imessage":
+            return self.imessageTint
+        default:
+            if self.channelHasError(channel) { return .orange }
+            if self.channelEnabled(channel) { return .green }
+            return .secondary
+        }
+    }
+
+    func channelSummary(_ channel: ChannelItem) -> String {
+        switch channel.id {
+        case "whatsapp":
+            return self.whatsAppSummary
+        case "telegram":
+            return self.telegramSummary
+        case "discord":
+            return self.discordSummary
+        case "googlechat":
+            return self.googlechatSummary
+        case "signal":
+            return self.signalSummary
+        case "imessage":
+            return self.imessageSummary
+        default:
+            if self.channelHasError(channel) { return "Error" }
+            if self.channelEnabled(channel) { return "Active" }
+            return "Not configured"
+        }
+    }
+
+    func channelDetails(_ channel: ChannelItem) -> String? {
+        switch channel.id {
+        case "whatsapp":
+            return self.whatsAppDetails
+        case "telegram":
+            return self.telegramDetails
+        case "discord":
+            return self.discordDetails
+        case "googlechat":
+            return self.googlechatDetails
+        case "signal":
+            return self.signalDetails
+        case "imessage":
+            return self.imessageDetails
+        default:
+            let status = self.channelStatusDictionary(channel.id)
+            if let err = status?["lastError"]?.stringValue, !err.isEmpty {
+                return "Error: \(err)"
+            }
+            return nil
+        }
+    }
+
+    func channelLastCheckText(_ channel: ChannelItem) -> String {
+        guard let date = self.channelLastCheck(channel) else { return "never" }
+        return relativeAge(from: date)
+    }
+
+    func channelLastCheck(_ channel: ChannelItem) -> Date? {
+        switch channel.id {
+        case "whatsapp":
+            guard let status = self.channelStatus("whatsapp", as: ChannelsStatusSnapshot.WhatsAppStatus.self)
+            else { return nil }
+            return self.date(fromMs: status.lastEventAt ?? status.lastMessageAt ?? status.lastConnectedAt)
+        case "telegram":
+            return self
+                .date(fromMs: self.channelStatus("telegram", as: ChannelsStatusSnapshot.TelegramStatus.self)?
+                    .lastProbeAt)
+        case "discord":
+            return self
+                .date(fromMs: self.channelStatus("discord", as: ChannelsStatusSnapshot.DiscordStatus.self)?
+                    .lastProbeAt)
+        case "googlechat":
+            return self
+                .date(fromMs: self.channelStatus("googlechat", as: ChannelsStatusSnapshot.GoogleChatStatus.self)?
+                    .lastProbeAt)
+        case "signal":
+            return self
+                .date(fromMs: self.channelStatus("signal", as: ChannelsStatusSnapshot.SignalStatus.self)?.lastProbeAt)
+        case "imessage":
+            return self
+                .date(fromMs: self.channelStatus("imessage", as: ChannelsStatusSnapshot.IMessageStatus.self)?
+                    .lastProbeAt)
+        default:
+            let status = self.channelStatusDictionary(channel.id)
+            if let probeAt = status?["lastProbeAt"]?.doubleValue {
+                return self.date(fromMs: probeAt)
+            }
+            if let accounts = self.store.snapshot?.channelAccounts[channel.id] {
+                let last = accounts.compactMap { $0.lastInboundAt ?? $0.lastOutboundAt }.max()
+                return self.date(fromMs: last)
+            }
+            return nil
+        }
+    }
+
+    func channelHasError(_ channel: ChannelItem) -> Bool {
+        switch channel.id {
+        case "whatsapp":
+            guard let status = self.channelStatus("whatsapp", as: ChannelsStatusSnapshot.WhatsAppStatus.self)
+            else { return false }
+            return status.lastError?.isEmpty == false || status.lastDisconnect?.loggedOut == true
+        case "telegram":
+            guard let status = self.channelStatus("telegram", as: ChannelsStatusSnapshot.TelegramStatus.self)
+            else { return false }
+            return status.lastError?.isEmpty == false || status.probe?.ok == false
+        case "discord":
+            guard let status = self.channelStatus("discord", as: ChannelsStatusSnapshot.DiscordStatus.self)
+            else { return false }
+            return status.lastError?.isEmpty == false || status.probe?.ok == false
+        case "googlechat":
+            guard let status = self.channelStatus("googlechat", as: ChannelsStatusSnapshot.GoogleChatStatus.self)
+            else { return false }
+            return status.lastError?.isEmpty == false || status.probe?.ok == false
+        case "signal":
+            guard let status = self.channelStatus("signal", as: ChannelsStatusSnapshot.SignalStatus.self)
+            else { return false }
+            return status.lastError?.isEmpty == false || status.probe?.ok == false
+        case "imessage":
+            guard let status = self.channelStatus("imessage", as: ChannelsStatusSnapshot.IMessageStatus.self)
+            else { return false }
+            return status.lastError?.isEmpty == false || status.probe?.ok == false
+        default:
+            let status = self.channelStatusDictionary(channel.id)
+            return status?["lastError"]?.stringValue?.isEmpty == false
+        }
+    }
+
+    private func resolveChannelTitle(_ id: String) -> String {
+        let label = self.store.resolveChannelLabel(id)
+        if label != id { return label }
+        return id.prefix(1).uppercased() + id.dropFirst()
+    }
+
+    private func resolveChannelDetailTitle(_ id: String) -> String {
+        self.store.resolveChannelDetailLabel(id)
+    }
+
+    private func resolveChannelSystemImage(_ id: String) -> String {
+        self.store.resolveChannelSystemImage(id)
+    }
+
+    private func channelStatusDictionary(_ id: String) -> [String: AnyCodable]? {
+        self.store.snapshot?.channels[id]?.dictionaryValue
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/ChannelsSettings+Helpers.swift

@@ -0,0 +1,17 @@
+import AppKit
+
+extension ChannelsSettings {
+    func date(fromMs ms: Double?) -> Date? {
+        guard let ms else { return nil }
+        return Date(timeIntervalSince1970: ms / 1000)
+    }
+
+    func qrImage(from dataUrl: String) -> NSImage? {
+        guard let comma = dataUrl.firstIndex(of: ",") else { return nil }
+        let header = dataUrl[..<comma]
+        guard header.contains("base64") else { return nil }
+        let base64 = dataUrl[dataUrl.index(after: comma)...]
+        guard let data = Data(base64Encoded: String(base64)) else { return nil }
+        return NSImage(data: data)
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/ChannelsSettings+View.swift

@@ -0,0 +1,167 @@
+import SwiftUI
+
+extension ChannelsSettings {
+    var body: some View {
+        HStack(spacing: 0) {
+            self.sidebar
+            self.detail
+        }
+        .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .topLeading)
+        .onAppear {
+            self.store.start()
+            self.ensureSelection()
+        }
+        .onChange(of: self.orderedChannels) { _, _ in
+            self.ensureSelection()
+        }
+        .onDisappear { self.store.stop() }
+    }
+
+    private var sidebar: some View {
+        ScrollView {
+            LazyVStack(alignment: .leading, spacing: 8) {
+                if !self.enabledChannels.isEmpty {
+                    self.sidebarSectionHeader("Configured")
+                    ForEach(self.enabledChannels) { channel in
+                        self.sidebarRow(channel)
+                    }
+                }
+
+                if !self.availableChannels.isEmpty {
+                    self.sidebarSectionHeader("Available")
+                    ForEach(self.availableChannels) { channel in
+                        self.sidebarRow(channel)
+                    }
+                }
+            }
+            .padding(.vertical, 10)
+            .padding(.horizontal, 10)
+        }
+        .frame(minWidth: 220, idealWidth: 240, maxWidth: 280, maxHeight: .infinity, alignment: .topLeading)
+        .background(
+            RoundedRectangle(cornerRadius: 12, style: .continuous)
+                .fill(Color(nsColor: .windowBackgroundColor)))
+        .clipShape(RoundedRectangle(cornerRadius: 12, style: .continuous))
+    }
+
+    private var detail: some View {
+        Group {
+            if let channel = self.selectedChannel {
+                self.channelDetail(channel)
+            } else {
+                self.emptyDetail
+            }
+        }
+        .frame(minWidth: 460, maxWidth: .infinity, maxHeight: .infinity, alignment: .topLeading)
+    }
+
+    private var emptyDetail: some View {
+        VStack(alignment: .leading, spacing: 8) {
+            Text("Channels")
+                .font(.title3.weight(.semibold))
+            Text("Select a channel to view status and settings.")
+                .font(.callout)
+                .foregroundStyle(.secondary)
+        }
+        .padding(.horizontal, 24)
+        .padding(.vertical, 18)
+    }
+
+    private func channelDetail(_ channel: ChannelItem) -> some View {
+        ScrollView(.vertical) {
+            VStack(alignment: .leading, spacing: 16) {
+                self.detailHeader(for: channel)
+                Divider()
+                self.channelSection(channel)
+                Spacer(minLength: 0)
+            }
+            .frame(maxWidth: .infinity, alignment: .leading)
+            .padding(.horizontal, 24)
+            .padding(.vertical, 18)
+        }
+    }
+
+    private func sidebarRow(_ channel: ChannelItem) -> some View {
+        let isSelected = self.selectedChannel == channel
+        return Button {
+            self.selectedChannel = channel
+        } label: {
+            HStack(spacing: 8) {
+                Circle()
+                    .fill(self.channelTint(channel))
+                    .frame(width: 8, height: 8)
+                VStack(alignment: .leading, spacing: 2) {
+                    Text(channel.title)
+                    Text(self.channelSummary(channel))
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                }
+            }
+            .padding(.vertical, 4)
+            .padding(.horizontal, 6)
+            .frame(maxWidth: .infinity, alignment: .leading)
+            .background(isSelected ? Color.accentColor.opacity(0.18) : Color.clear)
+            .clipShape(RoundedRectangle(cornerRadius: 10, style: .continuous))
+            .background(Color.clear) // ensure full-width hit test area
+            .contentShape(Rectangle())
+        }
+        .frame(maxWidth: .infinity, alignment: .leading)
+        .buttonStyle(.plain)
+        .contentShape(Rectangle())
+    }
+
+    private func sidebarSectionHeader(_ title: String) -> some View {
+        Text(title)
+            .font(.caption.weight(.semibold))
+            .foregroundStyle(.secondary)
+            .textCase(.uppercase)
+            .padding(.horizontal, 4)
+            .padding(.top, 2)
+    }
+
+    private func detailHeader(for channel: ChannelItem) -> some View {
+        VStack(alignment: .leading, spacing: 8) {
+            HStack(alignment: .firstTextBaseline, spacing: 10) {
+                Label(channel.detailTitle, systemImage: channel.systemImage)
+                    .font(.title3.weight(.semibold))
+                self.statusBadge(
+                    self.channelSummary(channel),
+                    color: self.channelTint(channel))
+                Spacer()
+                self.channelHeaderActions(channel)
+            }
+
+            HStack(spacing: 10) {
+                Text("Last check \(self.channelLastCheckText(channel))")
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+                if self.channelHasError(channel) {
+                    Text("Error")
+                        .font(.caption2.weight(.semibold))
+                        .padding(.horizontal, 6)
+                        .padding(.vertical, 2)
+                        .background(Color.red.opacity(0.15))
+                        .foregroundStyle(.red)
+                        .clipShape(Capsule())
+                }
+            }
+
+            if let details = self.channelDetails(channel) {
+                Text(details)
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+                    .fixedSize(horizontal: false, vertical: true)
+            }
+        }
+    }
+
+    private func statusBadge(_ text: String, color: Color) -> some View {
+        Text(text)
+            .font(.caption2.weight(.semibold))
+            .padding(.horizontal, 8)
+            .padding(.vertical, 3)
+            .background(color.opacity(0.16))
+            .foregroundStyle(color)
+            .clipShape(Capsule())
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/ChannelsSettings.swift

@@ -0,0 +1,19 @@
+import AppKit
+import SwiftUI
+
+struct ChannelsSettings: View {
+    struct ChannelItem: Identifiable, Hashable {
+        let id: String
+        let title: String
+        let detailTitle: String
+        let systemImage: String
+        let sortOrder: Int
+    }
+
+    @Bindable var store: ChannelsStore
+    @State var selectedChannel: ChannelItem?
+
+    init(store: ChannelsStore = .shared) {
+        self.store = store
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/ChannelsStore+Config.swift

@@ -0,0 +1,154 @@
+import Foundation
+import OpenClawProtocol
+
+extension ChannelsStore {
+    func loadConfigSchema() async {
+        guard !self.configSchemaLoading else { return }
+        self.configSchemaLoading = true
+        defer { self.configSchemaLoading = false }
+
+        do {
+            let res: ConfigSchemaResponse = try await GatewayConnection.shared.requestDecoded(
+                method: .configSchema,
+                params: nil,
+                timeoutMs: 8000)
+            let schemaValue = res.schema.foundationValue
+            self.configSchema = ConfigSchemaNode(raw: schemaValue)
+            let hintValues = res.uihints.mapValues { $0.foundationValue }
+            self.configUiHints = decodeUiHints(hintValues)
+        } catch {
+            self.configStatus = error.localizedDescription
+        }
+    }
+
+    func loadConfig() async {
+        do {
+            let snap: ConfigSnapshot = try await GatewayConnection.shared.requestDecoded(
+                method: .configGet,
+                params: nil,
+                timeoutMs: 10000)
+            self.configStatus = snap.valid == false
+                ? "Config invalid; fix it in ~/.openclaw/openclaw.json."
+                : nil
+            self.configRoot = snap.config?.mapValues { $0.foundationValue } ?? [:]
+            self.configDraft = cloneConfigValue(self.configRoot) as? [String: Any] ?? self.configRoot
+            self.configDirty = false
+            self.configLoaded = true
+
+            self.applyUIConfig(snap)
+        } catch {
+            self.configStatus = error.localizedDescription
+        }
+    }
+
+    private func applyUIConfig(_ snap: ConfigSnapshot) {
+        let ui = snap.config?["ui"]?.dictionaryValue
+        let rawSeam = ui?["seamColor"]?.stringValue?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        AppStateStore.shared.seamColorHex = rawSeam.isEmpty ? nil : rawSeam
+    }
+
+    func channelConfigSchema(for channelId: String) -> ConfigSchemaNode? {
+        guard let root = self.configSchema else { return nil }
+        return root.node(at: [.key("channels"), .key(channelId)])
+    }
+
+    func configValue(at path: ConfigPath) -> Any? {
+        if let value = valueAtPath(self.configDraft, path: path) {
+            return value
+        }
+        guard path.count >= 2 else { return nil }
+        if case .key("channels") = path[0], case .key = path[1] {
+            let fallbackPath = Array(path.dropFirst())
+            return valueAtPath(self.configDraft, path: fallbackPath)
+        }
+        return nil
+    }
+
+    func updateConfigValue(path: ConfigPath, value: Any?) {
+        var root: Any = self.configDraft
+        setValue(&root, path: path, value: value)
+        self.configDraft = root as? [String: Any] ?? self.configDraft
+        self.configDirty = true
+    }
+
+    func saveConfigDraft() async {
+        guard !self.isSavingConfig else { return }
+        self.isSavingConfig = true
+        defer { self.isSavingConfig = false }
+
+        do {
+            try await ConfigStore.save(self.configDraft)
+            await self.loadConfig()
+        } catch {
+            self.configStatus = error.localizedDescription
+        }
+    }
+
+    func reloadConfigDraft() async {
+        await self.loadConfig()
+    }
+}
+
+private func valueAtPath(_ root: Any, path: ConfigPath) -> Any? {
+    var current: Any? = root
+    for segment in path {
+        switch segment {
+        case let .key(key):
+            guard let dict = current as? [String: Any] else { return nil }
+            current = dict[key]
+        case let .index(index):
+            guard let array = current as? [Any], array.indices.contains(index) else { return nil }
+            current = array[index]
+        }
+    }
+    return current
+}
+
+private func setValue(_ root: inout Any, path: ConfigPath, value: Any?) {
+    guard let segment = path.first else { return }
+    switch segment {
+    case let .key(key):
+        var dict = root as? [String: Any] ?? [:]
+        if path.count == 1 {
+            if let value {
+                dict[key] = value
+            } else {
+                dict.removeValue(forKey: key)
+            }
+            root = dict
+            return
+        }
+        var child = dict[key] ?? [:]
+        setValue(&child, path: Array(path.dropFirst()), value: value)
+        dict[key] = child
+        root = dict
+    case let .index(index):
+        var array = root as? [Any] ?? []
+        if index >= array.count {
+            array.append(contentsOf: repeatElement(NSNull() as Any, count: index - array.count + 1))
+        }
+        if path.count == 1 {
+            if let value {
+                array[index] = value
+            } else if array.indices.contains(index) {
+                array.remove(at: index)
+            }
+            root = array
+            return
+        }
+        var child = array[index]
+        setValue(&child, path: Array(path.dropFirst()), value: value)
+        array[index] = child
+        root = array
+    }
+}
+
+private func cloneConfigValue(_ value: Any) -> Any {
+    guard JSONSerialization.isValidJSONObject(value) else { return value }
+    do {
+        let data = try JSONSerialization.data(withJSONObject: value, options: [])
+        return try JSONSerialization.jsonObject(with: data, options: [])
+    } catch {
+        return value
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/ChannelsStore+Lifecycle.swift

@@ -0,0 +1,163 @@
+import Foundation
+import OpenClawProtocol
+
+extension ChannelsStore {
+    func start() {
+        guard !self.isPreview else { return }
+        guard self.pollTask == nil else { return }
+        self.pollTask = Task.detached { [weak self] in
+            guard let self else { return }
+            await self.refresh(probe: true)
+            await self.loadConfigSchema()
+            await self.loadConfig()
+            while !Task.isCancelled {
+                try? await Task.sleep(nanoseconds: UInt64(self.interval * 1_000_000_000))
+                await self.refresh(probe: false)
+            }
+        }
+    }
+
+    func stop() {
+        self.pollTask?.cancel()
+        self.pollTask = nil
+    }
+
+    func refresh(probe: Bool) async {
+        guard !self.isRefreshing else { return }
+        self.isRefreshing = true
+        defer { self.isRefreshing = false }
+
+        do {
+            let params: [String: AnyCodable] = [
+                "probe": AnyCodable(probe),
+                "timeoutMs": AnyCodable(8000),
+            ]
+            let snap: ChannelsStatusSnapshot = try await GatewayConnection.shared.requestDecoded(
+                method: .channelsStatus,
+                params: params,
+                timeoutMs: 12000)
+            self.snapshot = snap
+            self.lastSuccess = Date()
+            self.lastError = nil
+        } catch {
+            self.lastError = error.localizedDescription
+        }
+    }
+
+    func startWhatsAppLogin(force: Bool, autoWait: Bool = true) async {
+        guard !self.whatsappBusy else { return }
+        self.whatsappBusy = true
+        defer { self.whatsappBusy = false }
+        var shouldAutoWait = false
+        do {
+            let params: [String: AnyCodable] = [
+                "force": AnyCodable(force),
+                "timeoutMs": AnyCodable(30000),
+            ]
+            let result: WhatsAppLoginStartResult = try await GatewayConnection.shared.requestDecoded(
+                method: .webLoginStart,
+                params: params,
+                timeoutMs: 35000)
+            self.whatsappLoginMessage = result.message
+            self.whatsappLoginQrDataUrl = result.qrDataUrl
+            self.whatsappLoginConnected = nil
+            shouldAutoWait = autoWait && result.qrDataUrl != nil
+        } catch {
+            self.whatsappLoginMessage = error.localizedDescription
+            self.whatsappLoginQrDataUrl = nil
+            self.whatsappLoginConnected = nil
+        }
+        await self.refresh(probe: true)
+        if shouldAutoWait {
+            Task { await self.waitWhatsAppLogin() }
+        }
+    }
+
+    func waitWhatsAppLogin(timeoutMs: Int = 120_000) async {
+        guard !self.whatsappBusy else { return }
+        self.whatsappBusy = true
+        defer { self.whatsappBusy = false }
+        do {
+            let params: [String: AnyCodable] = [
+                "timeoutMs": AnyCodable(timeoutMs),
+            ]
+            let result: WhatsAppLoginWaitResult = try await GatewayConnection.shared.requestDecoded(
+                method: .webLoginWait,
+                params: params,
+                timeoutMs: Double(timeoutMs) + 5000)
+            self.whatsappLoginMessage = result.message
+            self.whatsappLoginConnected = result.connected
+            if result.connected {
+                self.whatsappLoginQrDataUrl = nil
+            }
+        } catch {
+            self.whatsappLoginMessage = error.localizedDescription
+        }
+        await self.refresh(probe: true)
+    }
+
+    func logoutWhatsApp() async {
+        guard !self.whatsappBusy else { return }
+        self.whatsappBusy = true
+        defer { self.whatsappBusy = false }
+        do {
+            let params: [String: AnyCodable] = [
+                "channel": AnyCodable("whatsapp"),
+            ]
+            let result: ChannelLogoutResult = try await GatewayConnection.shared.requestDecoded(
+                method: .channelsLogout,
+                params: params,
+                timeoutMs: 15000)
+            self.whatsappLoginMessage = result.cleared
+                ? "Logged out and cleared credentials."
+                : "No WhatsApp session found."
+            self.whatsappLoginQrDataUrl = nil
+        } catch {
+            self.whatsappLoginMessage = error.localizedDescription
+        }
+        await self.refresh(probe: true)
+    }
+
+    func logoutTelegram() async {
+        guard !self.telegramBusy else { return }
+        self.telegramBusy = true
+        defer { self.telegramBusy = false }
+        do {
+            let params: [String: AnyCodable] = [
+                "channel": AnyCodable("telegram"),
+            ]
+            let result: ChannelLogoutResult = try await GatewayConnection.shared.requestDecoded(
+                method: .channelsLogout,
+                params: params,
+                timeoutMs: 15000)
+            if result.envToken == true {
+                self.configStatus = "Telegram token still set via env; config cleared."
+            } else {
+                self.configStatus = result.cleared
+                    ? "Telegram token cleared."
+                    : "No Telegram token configured."
+            }
+            await self.loadConfig()
+        } catch {
+            self.configStatus = error.localizedDescription
+        }
+        await self.refresh(probe: true)
+    }
+}
+
+private struct WhatsAppLoginStartResult: Codable {
+    let qrDataUrl: String?
+    let message: String
+}
+
+private struct WhatsAppLoginWaitResult: Codable {
+    let connected: Bool
+    let message: String
+}
+
+private struct ChannelLogoutResult: Codable {
+    let channel: String?
+    let accountId: String?
+    let cleared: Bool
+    let envToken: Bool?
+}

openclaw/apps/macos/Sources/OpenClaw/ChannelsStore.swift

@@ -0,0 +1,296 @@
+import Foundation
+import Observation
+import OpenClawProtocol
+
+struct ChannelsStatusSnapshot: Codable {
+    struct WhatsAppSelf: Codable {
+        let e164: String?
+        let jid: String?
+    }
+
+    struct WhatsAppDisconnect: Codable {
+        let at: Double
+        let status: Int?
+        let error: String?
+        let loggedOut: Bool?
+    }
+
+    struct WhatsAppStatus: Codable {
+        let configured: Bool
+        let linked: Bool
+        let authAgeMs: Double?
+        let `self`: WhatsAppSelf?
+        let running: Bool
+        let connected: Bool
+        let lastConnectedAt: Double?
+        let lastDisconnect: WhatsAppDisconnect?
+        let reconnectAttempts: Int
+        let lastMessageAt: Double?
+        let lastEventAt: Double?
+        let lastError: String?
+    }
+
+    struct TelegramBot: Codable {
+        let id: Int?
+        let username: String?
+    }
+
+    struct TelegramWebhook: Codable {
+        let url: String?
+        let hasCustomCert: Bool?
+    }
+
+    struct TelegramProbe: Codable {
+        let ok: Bool
+        let status: Int?
+        let error: String?
+        let elapsedMs: Double?
+        let bot: TelegramBot?
+        let webhook: TelegramWebhook?
+    }
+
+    struct TelegramStatus: Codable {
+        let configured: Bool
+        let tokenSource: String?
+        let running: Bool
+        let mode: String?
+        let lastStartAt: Double?
+        let lastStopAt: Double?
+        let lastError: String?
+        let probe: TelegramProbe?
+        let lastProbeAt: Double?
+    }
+
+    struct DiscordBot: Codable {
+        let id: String?
+        let username: String?
+    }
+
+    struct DiscordProbe: Codable {
+        let ok: Bool
+        let status: Int?
+        let error: String?
+        let elapsedMs: Double?
+        let bot: DiscordBot?
+    }
+
+    struct DiscordStatus: Codable {
+        let configured: Bool
+        let tokenSource: String?
+        let running: Bool
+        let lastStartAt: Double?
+        let lastStopAt: Double?
+        let lastError: String?
+        let probe: DiscordProbe?
+        let lastProbeAt: Double?
+    }
+
+    struct GoogleChatProbe: Codable {
+        let ok: Bool
+        let status: Int?
+        let error: String?
+        let elapsedMs: Double?
+    }
+
+    struct GoogleChatStatus: Codable {
+        let configured: Bool
+        let credentialSource: String?
+        let audienceType: String?
+        let audience: String?
+        let webhookPath: String?
+        let webhookUrl: String?
+        let running: Bool
+        let lastStartAt: Double?
+        let lastStopAt: Double?
+        let lastError: String?
+        let probe: GoogleChatProbe?
+        let lastProbeAt: Double?
+    }
+
+    struct SignalProbe: Codable {
+        let ok: Bool
+        let status: Int?
+        let error: String?
+        let elapsedMs: Double?
+        let version: String?
+    }
+
+    struct SignalStatus: Codable {
+        let configured: Bool
+        let baseUrl: String
+        let running: Bool
+        let lastStartAt: Double?
+        let lastStopAt: Double?
+        let lastError: String?
+        let probe: SignalProbe?
+        let lastProbeAt: Double?
+    }
+
+    struct IMessageProbe: Codable {
+        let ok: Bool
+        let error: String?
+    }
+
+    struct IMessageStatus: Codable {
+        let configured: Bool
+        let running: Bool
+        let lastStartAt: Double?
+        let lastStopAt: Double?
+        let lastError: String?
+        let cliPath: String?
+        let dbPath: String?
+        let probe: IMessageProbe?
+        let lastProbeAt: Double?
+    }
+
+    struct ChannelAccountSnapshot: Codable {
+        let accountId: String
+        let name: String?
+        let enabled: Bool?
+        let configured: Bool?
+        let linked: Bool?
+        let running: Bool?
+        let connected: Bool?
+        let reconnectAttempts: Int?
+        let lastConnectedAt: Double?
+        let lastError: String?
+        let lastStartAt: Double?
+        let lastStopAt: Double?
+        let lastInboundAt: Double?
+        let lastOutboundAt: Double?
+        let lastProbeAt: Double?
+        let mode: String?
+        let dmPolicy: String?
+        let allowFrom: [String]?
+        let tokenSource: String?
+        let botTokenSource: String?
+        let appTokenSource: String?
+        let baseUrl: String?
+        let allowUnmentionedGroups: Bool?
+        let cliPath: String?
+        let dbPath: String?
+        let port: Int?
+        let probe: AnyCodable?
+        let audit: AnyCodable?
+        let application: AnyCodable?
+    }
+
+    struct ChannelUiMetaEntry: Codable {
+        let id: String
+        let label: String
+        let detailLabel: String
+        let systemImage: String?
+    }
+
+    let ts: Double
+    let channelOrder: [String]
+    let channelLabels: [String: String]
+    let channelDetailLabels: [String: String]?
+    let channelSystemImages: [String: String]?
+    let channelMeta: [ChannelUiMetaEntry]?
+    let channels: [String: AnyCodable]
+    let channelAccounts: [String: [ChannelAccountSnapshot]]
+    let channelDefaultAccountId: [String: String]
+
+    func decodeChannel<T: Decodable>(_ id: String, as type: T.Type) -> T? {
+        guard let value = self.channels[id] else { return nil }
+        do {
+            let data = try JSONEncoder().encode(value)
+            return try JSONDecoder().decode(type, from: data)
+        } catch {
+            return nil
+        }
+    }
+}
+
+struct ConfigSnapshot: Codable {
+    struct Issue: Codable {
+        let path: String
+        let message: String
+    }
+
+    let path: String?
+    let exists: Bool?
+    let raw: String?
+    let hash: String?
+    let parsed: AnyCodable?
+    let valid: Bool?
+    let config: [String: AnyCodable]?
+    let issues: [Issue]?
+}
+
+@MainActor
+@Observable
+final class ChannelsStore {
+    static let shared = ChannelsStore()
+
+    var snapshot: ChannelsStatusSnapshot?
+    var lastError: String?
+    var lastSuccess: Date?
+    var isRefreshing = false
+
+    var whatsappLoginMessage: String?
+    var whatsappLoginQrDataUrl: String?
+    var whatsappLoginConnected: Bool?
+    var whatsappBusy = false
+    var telegramBusy = false
+
+    var configStatus: String?
+    var isSavingConfig = false
+    var configSchemaLoading = false
+    var configSchema: ConfigSchemaNode?
+    var configUiHints: [String: ConfigUiHint] = [:]
+    var configDraft: [String: Any] = [:]
+    var configDirty = false
+
+    let interval: TimeInterval = 45
+    let isPreview: Bool
+    var pollTask: Task<Void, Never>?
+    var configRoot: [String: Any] = [:]
+    var configLoaded = false
+
+    func channelMetaEntry(_ id: String) -> ChannelsStatusSnapshot.ChannelUiMetaEntry? {
+        self.snapshot?.channelMeta?.first(where: { $0.id == id })
+    }
+
+    func resolveChannelLabel(_ id: String) -> String {
+        if let meta = self.channelMetaEntry(id), !meta.label.isEmpty {
+            return meta.label
+        }
+        if let label = self.snapshot?.channelLabels[id], !label.isEmpty {
+            return label
+        }
+        return id
+    }
+
+    func resolveChannelDetailLabel(_ id: String) -> String {
+        if let meta = self.channelMetaEntry(id), !meta.detailLabel.isEmpty {
+            return meta.detailLabel
+        }
+        if let detail = self.snapshot?.channelDetailLabels?[id], !detail.isEmpty {
+            return detail
+        }
+        return self.resolveChannelLabel(id)
+    }
+
+    func resolveChannelSystemImage(_ id: String) -> String {
+        if let meta = self.channelMetaEntry(id), let symbol = meta.systemImage, !symbol.isEmpty {
+            return symbol
+        }
+        if let symbol = self.snapshot?.channelSystemImages?[id], !symbol.isEmpty {
+            return symbol
+        }
+        return "message"
+    }
+
+    func orderedChannelIds() -> [String] {
+        if let meta = self.snapshot?.channelMeta, !meta.isEmpty {
+            return meta.map(\.id)
+        }
+        return self.snapshot?.channelOrder ?? []
+    }
+
+    init(isPreview: Bool = ProcessInfo.processInfo.isPreview) {
+        self.isPreview = isPreview
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/CoalescingFSEventsWatcher.swift

@@ -0,0 +1,110 @@
+import CoreServices
+import Foundation
+
+final class CoalescingFSEventsWatcher: @unchecked Sendable {
+    private let queue: DispatchQueue
+    private var stream: FSEventStreamRef?
+    private var pending = false
+
+    private let paths: [String]
+    private let shouldNotify: (Int, UnsafeMutableRawPointer?) -> Bool
+    private let onChange: () -> Void
+    private let coalesceDelay: TimeInterval
+
+    init(
+        paths: [String],
+        queueLabel: String,
+        coalesceDelay: TimeInterval = 0.12,
+        shouldNotify: @escaping (Int, UnsafeMutableRawPointer?) -> Bool = { _, _ in true },
+        onChange: @escaping () -> Void)
+    {
+        self.paths = paths
+        self.queue = DispatchQueue(label: queueLabel)
+        self.coalesceDelay = coalesceDelay
+        self.shouldNotify = shouldNotify
+        self.onChange = onChange
+    }
+
+    deinit {
+        self.stop()
+    }
+
+    func start() {
+        guard self.stream == nil else { return }
+
+        let retainedSelf = Unmanaged.passRetained(self)
+        var context = FSEventStreamContext(
+            version: 0,
+            info: retainedSelf.toOpaque(),
+            retain: nil,
+            release: { pointer in
+                guard let pointer else { return }
+                Unmanaged<CoalescingFSEventsWatcher>.fromOpaque(pointer).release()
+            },
+            copyDescription: nil)
+
+        let paths = self.paths as CFArray
+        let flags = FSEventStreamCreateFlags(
+            kFSEventStreamCreateFlagFileEvents |
+                kFSEventStreamCreateFlagUseCFTypes |
+                kFSEventStreamCreateFlagNoDefer)
+
+        guard let stream = FSEventStreamCreate(
+            kCFAllocatorDefault,
+            Self.callback,
+            &context,
+            paths,
+            FSEventStreamEventId(kFSEventStreamEventIdSinceNow),
+            0.05,
+            flags)
+        else {
+            retainedSelf.release()
+            return
+        }
+
+        self.stream = stream
+        FSEventStreamSetDispatchQueue(stream, self.queue)
+        if FSEventStreamStart(stream) == false {
+            self.stream = nil
+            FSEventStreamSetDispatchQueue(stream, nil)
+            FSEventStreamInvalidate(stream)
+            FSEventStreamRelease(stream)
+        }
+    }
+
+    func stop() {
+        guard let stream = self.stream else { return }
+        self.stream = nil
+        FSEventStreamStop(stream)
+        FSEventStreamSetDispatchQueue(stream, nil)
+        FSEventStreamInvalidate(stream)
+        FSEventStreamRelease(stream)
+    }
+}
+
+extension CoalescingFSEventsWatcher {
+    private static let callback: FSEventStreamCallback = { _, info, numEvents, eventPaths, eventFlags, _ in
+        guard let info else { return }
+        let watcher = Unmanaged<CoalescingFSEventsWatcher>.fromOpaque(info).takeUnretainedValue()
+        watcher.handleEvents(numEvents: numEvents, eventPaths: eventPaths, eventFlags: eventFlags)
+    }
+
+    private func handleEvents(
+        numEvents: Int,
+        eventPaths: UnsafeMutableRawPointer?,
+        eventFlags: UnsafePointer<FSEventStreamEventFlags>?)
+    {
+        guard numEvents > 0 else { return }
+        guard eventFlags != nil else { return }
+        guard self.shouldNotify(numEvents, eventPaths) else { return }
+
+        // Coalesce rapid changes (common during builds/atomic saves).
+        if self.pending { return }
+        self.pending = true
+        self.queue.asyncAfter(deadline: .now() + self.coalesceDelay) { [weak self] in
+            guard let self else { return }
+            self.pending = false
+            self.onChange()
+        }
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/CommandResolver.swift

@@ -0,0 +1,578 @@
+import Foundation
+
+enum CommandResolver {
+    private static let projectRootDefaultsKey = "openclaw.gatewayProjectRootPath"
+    private static let helperName = "openclaw"
+
+    static func gatewayEntrypoint(in root: URL) -> String? {
+        let distEntry = root.appendingPathComponent("dist/index.js").path
+        if FileManager().isReadableFile(atPath: distEntry) { return distEntry }
+        let openclawEntry = root.appendingPathComponent("openclaw.mjs").path
+        if FileManager().isReadableFile(atPath: openclawEntry) { return openclawEntry }
+        let binEntry = root.appendingPathComponent("bin/openclaw.js").path
+        if FileManager().isReadableFile(atPath: binEntry) { return binEntry }
+        return nil
+    }
+
+    static func runtimeResolution() -> Result<RuntimeResolution, RuntimeResolutionError> {
+        RuntimeLocator.resolve(searchPaths: self.preferredPaths())
+    }
+
+    static func runtimeResolution(searchPaths: [String]?) -> Result<RuntimeResolution, RuntimeResolutionError> {
+        RuntimeLocator.resolve(searchPaths: searchPaths ?? self.preferredPaths())
+    }
+
+    static func makeRuntimeCommand(
+        runtime: RuntimeResolution,
+        entrypoint: String,
+        subcommand: String,
+        extraArgs: [String]) -> [String]
+    {
+        [runtime.path, entrypoint, subcommand] + extraArgs
+    }
+
+    static func runtimeErrorCommand(_ error: RuntimeResolutionError) -> [String] {
+        let message = RuntimeLocator.describeFailure(error)
+        return self.errorCommand(with: message)
+    }
+
+    static func errorCommand(with message: String) -> [String] {
+        let script = """
+        cat <<'__OPENCLAW_ERR__' >&2
+        \(message)
+        __OPENCLAW_ERR__
+        exit 1
+        """
+        return ["/bin/sh", "-c", script]
+    }
+
+    static func projectRoot() -> URL {
+        if let stored = UserDefaults.standard.string(forKey: self.projectRootDefaultsKey),
+           let url = self.expandPath(stored),
+           FileManager().fileExists(atPath: url.path)
+        {
+            return url
+        }
+        let fallback = FileManager().homeDirectoryForCurrentUser
+            .appendingPathComponent("Projects/openclaw")
+        if FileManager().fileExists(atPath: fallback.path) {
+            return fallback
+        }
+        return FileManager().homeDirectoryForCurrentUser
+    }
+
+    static func setProjectRoot(_ path: String) {
+        UserDefaults.standard.set(path, forKey: self.projectRootDefaultsKey)
+    }
+
+    static func projectRootPath() -> String {
+        self.projectRoot().path
+    }
+
+    static func preferredPaths() -> [String] {
+        let current = ProcessInfo.processInfo.environment["PATH"]?
+            .split(separator: ":").map(String.init) ?? []
+        let home = FileManager().homeDirectoryForCurrentUser
+        let projectRoot = self.projectRoot()
+        return self.preferredPaths(home: home, current: current, projectRoot: projectRoot)
+    }
+
+    static func preferredPaths(home: URL, current: [String], projectRoot: URL) -> [String] {
+        var extras = [
+            home.appendingPathComponent("Library/pnpm").path,
+            "/opt/homebrew/bin",
+            "/usr/local/bin",
+            "/usr/bin",
+            "/bin",
+        ]
+        #if DEBUG
+        // Dev-only convenience. Avoid project-local PATH hijacking in release builds.
+        extras.insert(projectRoot.appendingPathComponent("node_modules/.bin").path, at: 0)
+        #endif
+        let openclawPaths = self.openclawManagedPaths(home: home)
+        if !openclawPaths.isEmpty {
+            extras.insert(contentsOf: openclawPaths, at: 1)
+        }
+        extras.insert(contentsOf: self.nodeManagerBinPaths(home: home), at: 1 + openclawPaths.count)
+        var seen = Set<String>()
+        // Preserve order while stripping duplicates so PATH lookups remain deterministic.
+        return (extras + current).filter { seen.insert($0).inserted }
+    }
+
+    private static func openclawManagedPaths(home: URL) -> [String] {
+        let bases = [
+            home.appendingPathComponent(".openclaw"),
+        ]
+        var paths: [String] = []
+        for base in bases {
+            let bin = base.appendingPathComponent("bin")
+            let nodeBin = base.appendingPathComponent("tools/node/bin")
+            if FileManager().fileExists(atPath: bin.path) {
+                paths.append(bin.path)
+            }
+            if FileManager().fileExists(atPath: nodeBin.path) {
+                paths.append(nodeBin.path)
+            }
+        }
+        return paths
+    }
+
+    private static func nodeManagerBinPaths(home: URL) -> [String] {
+        var bins: [String] = []
+
+        // Volta
+        let volta = home.appendingPathComponent(".volta/bin")
+        if FileManager().fileExists(atPath: volta.path) {
+            bins.append(volta.path)
+        }
+
+        // asdf
+        let asdf = home.appendingPathComponent(".asdf/shims")
+        if FileManager().fileExists(atPath: asdf.path) {
+            bins.append(asdf.path)
+        }
+
+        // fnm
+        bins.append(contentsOf: self.versionedNodeBinPaths(
+            base: home.appendingPathComponent(".local/share/fnm/node-versions"),
+            suffix: "installation/bin"))
+
+        // nvm
+        bins.append(contentsOf: self.versionedNodeBinPaths(
+            base: home.appendingPathComponent(".nvm/versions/node"),
+            suffix: "bin"))
+
+        return bins
+    }
+
+    private static func versionedNodeBinPaths(base: URL, suffix: String) -> [String] {
+        guard FileManager().fileExists(atPath: base.path) else { return [] }
+        let entries: [String]
+        do {
+            entries = try FileManager().contentsOfDirectory(atPath: base.path)
+        } catch {
+            return []
+        }
+
+        func parseVersion(_ name: String) -> [Int] {
+            let trimmed = name.hasPrefix("v") ? String(name.dropFirst()) : name
+            return trimmed.split(separator: ".").compactMap { Int($0) }
+        }
+
+        let sorted = entries.sorted { a, b in
+            let va = parseVersion(a)
+            let vb = parseVersion(b)
+            let maxCount = max(va.count, vb.count)
+            for i in 0..<maxCount {
+                let ai = i < va.count ? va[i] : 0
+                let bi = i < vb.count ? vb[i] : 0
+                if ai != bi { return ai > bi }
+            }
+            // If identical numerically, keep stable ordering.
+            return a > b
+        }
+
+        var paths: [String] = []
+        for entry in sorted {
+            let binDir = base.appendingPathComponent(entry).appendingPathComponent(suffix)
+            let node = binDir.appendingPathComponent("node")
+            if FileManager().isExecutableFile(atPath: node.path) {
+                paths.append(binDir.path)
+            }
+        }
+        return paths
+    }
+
+    static func findExecutable(named name: String, searchPaths: [String]? = nil) -> String? {
+        for dir in searchPaths ?? self.preferredPaths() {
+            let candidate = (dir as NSString).appendingPathComponent(name)
+            if FileManager().isExecutableFile(atPath: candidate) {
+                return candidate
+            }
+        }
+        return nil
+    }
+
+    static func openclawExecutable(searchPaths: [String]? = nil) -> String? {
+        self.findExecutable(named: self.helperName, searchPaths: searchPaths)
+    }
+
+    static func projectOpenClawExecutable(projectRoot: URL? = nil) -> String? {
+        #if DEBUG
+        let root = projectRoot ?? self.projectRoot()
+        let candidate = root.appendingPathComponent("node_modules/.bin").appendingPathComponent(self.helperName).path
+        return FileManager().isExecutableFile(atPath: candidate) ? candidate : nil
+        #else
+        return nil
+        #endif
+    }
+
+    static func nodeCliPath() -> String? {
+        let root = self.projectRoot()
+        let candidates = [
+            root.appendingPathComponent("openclaw.mjs").path,
+            root.appendingPathComponent("bin/openclaw.js").path,
+        ]
+        for candidate in candidates where FileManager().isReadableFile(atPath: candidate) {
+            return candidate
+        }
+        return nil
+    }
+
+    static func hasAnyOpenClawInvoker(searchPaths: [String]? = nil) -> Bool {
+        if self.openclawExecutable(searchPaths: searchPaths) != nil { return true }
+        if self.findExecutable(named: "pnpm", searchPaths: searchPaths) != nil { return true }
+        if self.findExecutable(named: "node", searchPaths: searchPaths) != nil,
+           self.nodeCliPath() != nil
+        {
+            return true
+        }
+        return false
+    }
+
+    static func openclawNodeCommand(
+        subcommand: String,
+        extraArgs: [String] = [],
+        defaults: UserDefaults = .standard,
+        configRoot: [String: Any]? = nil,
+        searchPaths: [String]? = nil) -> [String]
+    {
+        let settings = self.connectionSettings(defaults: defaults, configRoot: configRoot)
+        if settings.mode == .remote, let ssh = self.sshNodeCommand(
+            subcommand: subcommand,
+            extraArgs: extraArgs,
+            settings: settings)
+        {
+            return ssh
+        }
+
+        let root = self.projectRoot()
+        if let openclawPath = self.projectOpenClawExecutable(projectRoot: root) {
+            return [openclawPath, subcommand] + extraArgs
+        }
+        if let openclawPath = self.openclawExecutable(searchPaths: searchPaths) {
+            return [openclawPath, subcommand] + extraArgs
+        }
+
+        let runtimeResult = self.runtimeResolution(searchPaths: searchPaths)
+        switch runtimeResult {
+        case let .success(runtime):
+            if let entry = self.gatewayEntrypoint(in: root) {
+                return self.makeRuntimeCommand(
+                    runtime: runtime,
+                    entrypoint: entry,
+                    subcommand: subcommand,
+                    extraArgs: extraArgs)
+            }
+        case .failure:
+            break
+        }
+
+        if let pnpm = self.findExecutable(named: "pnpm", searchPaths: searchPaths) {
+            // Use --silent to avoid pnpm lifecycle banners that would corrupt JSON outputs.
+            return [pnpm, "--silent", "openclaw", subcommand] + extraArgs
+        }
+
+        switch runtimeResult {
+        case .success:
+            let missingEntry = """
+            openclaw entrypoint missing (looked for dist/index.js or openclaw.mjs); run pnpm build.
+            """
+            return self.errorCommand(with: missingEntry)
+        case let .failure(error):
+            return self.runtimeErrorCommand(error)
+        }
+    }
+
+    static func openclawCommand(
+        subcommand: String,
+        extraArgs: [String] = [],
+        defaults: UserDefaults = .standard,
+        configRoot: [String: Any]? = nil,
+        searchPaths: [String]? = nil) -> [String]
+    {
+        self.openclawNodeCommand(
+            subcommand: subcommand,
+            extraArgs: extraArgs,
+            defaults: defaults,
+            configRoot: configRoot,
+            searchPaths: searchPaths)
+    }
+
+    // MARK: - SSH helpers
+
+    private static func sshNodeCommand(subcommand: String, extraArgs: [String], settings: RemoteSettings) -> [String]? {
+        guard !settings.target.isEmpty else { return nil }
+        guard let parsed = self.parseSSHTarget(settings.target) else { return nil }
+
+        // Run the real openclaw CLI on the remote host.
+        let exportedPath = [
+            "/opt/homebrew/bin",
+            "/usr/local/bin",
+            "/usr/bin",
+            "/bin",
+            "/usr/sbin",
+            "/sbin",
+            "$HOME/Library/pnpm",
+            "$PATH",
+        ].joined(separator: ":")
+        let quotedArgs = ([subcommand] + extraArgs).map(self.shellQuote).joined(separator: " ")
+        let userPRJ = settings.projectRoot.trimmingCharacters(in: .whitespacesAndNewlines)
+        let userCLI = settings.cliPath.trimmingCharacters(in: .whitespacesAndNewlines)
+
+        let projectSection = if userPRJ.isEmpty {
+            """
+            DEFAULT_PRJ="$HOME/Projects/openclaw"
+            if [ -d "$DEFAULT_PRJ" ]; then
+              PRJ="$DEFAULT_PRJ"
+              cd "$PRJ" || { echo "Project root not found: $PRJ"; exit 127; }
+            fi
+            """
+        } else {
+            """
+            PRJ=\(self.shellQuote(userPRJ))
+            cd "$PRJ" || { echo "Project root not found: $PRJ"; exit 127; }
+            """
+        }
+
+        let cliSection = if userCLI.isEmpty {
+            ""
+        } else {
+            """
+            CLI_HINT=\(self.shellQuote(userCLI))
+            if [ -n "$CLI_HINT" ]; then
+              if [ -x "$CLI_HINT" ]; then
+                CLI="$CLI_HINT"
+                "$CLI_HINT" \(quotedArgs);
+                exit $?;
+              elif [ -f "$CLI_HINT" ]; then
+                if command -v node >/dev/null 2>&1; then
+                  CLI="node $CLI_HINT"
+                  node "$CLI_HINT" \(quotedArgs);
+                  exit $?;
+                fi
+              fi
+            fi
+            """
+        }
+
+        let scriptBody = """
+        PATH=\(exportedPath);
+        CLI="";
+        \(cliSection)
+        \(projectSection)
+        if command -v openclaw >/dev/null 2>&1; then
+          CLI="$(command -v openclaw)"
+          openclaw \(quotedArgs);
+        elif [ -n "${PRJ:-}" ] && [ -f "$PRJ/dist/index.js" ]; then
+          if command -v node >/dev/null 2>&1; then
+            CLI="node $PRJ/dist/index.js"
+            node "$PRJ/dist/index.js" \(quotedArgs);
+          else
+            echo "Node >=22 required on remote host"; exit 127;
+          fi
+        elif [ -n "${PRJ:-}" ] && [ -f "$PRJ/openclaw.mjs" ]; then
+          if command -v node >/dev/null 2>&1; then
+            CLI="node $PRJ/openclaw.mjs"
+            node "$PRJ/openclaw.mjs" \(quotedArgs);
+          else
+            echo "Node >=22 required on remote host"; exit 127;
+          fi
+        elif [ -n "${PRJ:-}" ] && [ -f "$PRJ/bin/openclaw.js" ]; then
+          if command -v node >/dev/null 2>&1; then
+            CLI="node $PRJ/bin/openclaw.js"
+            node "$PRJ/bin/openclaw.js" \(quotedArgs);
+          else
+            echo "Node >=22 required on remote host"; exit 127;
+          fi
+        elif command -v pnpm >/dev/null 2>&1; then
+          CLI="pnpm --silent openclaw"
+          pnpm --silent openclaw \(quotedArgs);
+        else
+          echo "openclaw CLI missing on remote host"; exit 127;
+        fi
+        """
+        let options: [String] = [
+            "-o", "BatchMode=yes",
+            "-o", "StrictHostKeyChecking=accept-new",
+            "-o", "UpdateHostKeys=yes",
+        ]
+        let args = self.sshArguments(
+            target: parsed,
+            identity: settings.identity,
+            options: options,
+            remoteCommand: ["/bin/sh", "-c", scriptBody])
+        return ["/usr/bin/ssh"] + args
+    }
+
+    struct RemoteSettings {
+        let mode: AppState.ConnectionMode
+        let target: String
+        let identity: String
+        let projectRoot: String
+        let cliPath: String
+    }
+
+    static func connectionSettings(
+        defaults: UserDefaults = .standard,
+        configRoot: [String: Any]? = nil) -> RemoteSettings
+    {
+        let root = configRoot ?? OpenClawConfigFile.loadDict()
+        let mode = ConnectionModeResolver.resolve(root: root, defaults: defaults).mode
+        let target = defaults.string(forKey: remoteTargetKey) ?? ""
+        let identity = defaults.string(forKey: remoteIdentityKey) ?? ""
+        let projectRoot = defaults.string(forKey: remoteProjectRootKey) ?? ""
+        let cliPath = defaults.string(forKey: remoteCliPathKey) ?? ""
+        return RemoteSettings(
+            mode: mode,
+            target: self.sanitizedTarget(target),
+            identity: identity,
+            projectRoot: projectRoot,
+            cliPath: cliPath)
+    }
+
+    static func connectionModeIsRemote(defaults: UserDefaults = .standard) -> Bool {
+        self.connectionSettings(defaults: defaults).mode == .remote
+    }
+
+    private static func sanitizedTarget(_ raw: String) -> String {
+        let trimmed = raw.trimmingCharacters(in: .whitespacesAndNewlines)
+        if trimmed.hasPrefix("ssh ") {
+            return trimmed.replacingOccurrences(of: "ssh ", with: "").trimmingCharacters(in: .whitespacesAndNewlines)
+        }
+        return trimmed
+    }
+
+    struct SSHParsedTarget {
+        let user: String?
+        let host: String
+        let port: Int
+    }
+
+    static func parseSSHTarget(_ target: String) -> SSHParsedTarget? {
+        let trimmed = self.normalizeSSHTargetInput(target)
+        guard !trimmed.isEmpty else { return nil }
+        if trimmed.rangeOfCharacter(from: CharacterSet.whitespacesAndNewlines.union(.controlCharacters)) != nil {
+            return nil
+        }
+        let userHostPort: String
+        let user: String?
+        if let atRange = trimmed.range(of: "@") {
+            user = String(trimmed[..<atRange.lowerBound])
+            userHostPort = String(trimmed[atRange.upperBound...])
+        } else {
+            user = nil
+            userHostPort = trimmed
+        }
+
+        let host: String
+        let port: Int
+        if let colon = userHostPort.lastIndex(of: ":"), colon != userHostPort.startIndex {
+            host = String(userHostPort[..<colon])
+            let portStr = String(userHostPort[userHostPort.index(after: colon)...])
+            guard let parsedPort = Int(portStr), parsedPort > 0, parsedPort <= 65535 else {
+                return nil
+            }
+            port = parsedPort
+        } else {
+            host = userHostPort
+            port = 22
+        }
+
+        return self.makeSSHTarget(user: user, host: host, port: port)
+    }
+
+    static func sshTargetValidationMessage(_ target: String) -> String? {
+        let trimmed = self.normalizeSSHTargetInput(target)
+        guard !trimmed.isEmpty else { return nil }
+        if trimmed.hasPrefix("-") {
+            return "SSH target cannot start with '-'"
+        }
+        if trimmed.rangeOfCharacter(from: CharacterSet.whitespacesAndNewlines.union(.controlCharacters)) != nil {
+            return "SSH target cannot contain spaces"
+        }
+        if self.parseSSHTarget(trimmed) == nil {
+            return "SSH target must look like user@host[:port]"
+        }
+        return nil
+    }
+
+    private static func shellQuote(_ text: String) -> String {
+        if text.isEmpty { return "''" }
+        let escaped = text.replacingOccurrences(of: "'", with: "'\\''")
+        return "'\(escaped)'"
+    }
+
+    private static func expandPath(_ path: String) -> URL? {
+        var expanded = path
+        if expanded.hasPrefix("~") {
+            let home = FileManager().homeDirectoryForCurrentUser.path
+            expanded.replaceSubrange(expanded.startIndex...expanded.startIndex, with: home)
+        }
+        return URL(fileURLWithPath: expanded)
+    }
+
+    private static func normalizeSSHTargetInput(_ target: String) -> String {
+        var trimmed = target.trimmingCharacters(in: .whitespacesAndNewlines)
+        if trimmed.hasPrefix("ssh ") {
+            trimmed = trimmed.replacingOccurrences(of: "ssh ", with: "")
+                .trimmingCharacters(in: .whitespacesAndNewlines)
+        }
+        return trimmed
+    }
+
+    private static func isValidSSHComponent(_ value: String, allowLeadingDash: Bool = false) -> Bool {
+        if value.isEmpty { return false }
+        if !allowLeadingDash, value.hasPrefix("-") { return false }
+        let invalid = CharacterSet.whitespacesAndNewlines.union(.controlCharacters)
+        return value.rangeOfCharacter(from: invalid) == nil
+    }
+
+    static func makeSSHTarget(user: String?, host: String, port: Int) -> SSHParsedTarget? {
+        let trimmedHost = host.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard self.isValidSSHComponent(trimmedHost) else { return nil }
+        let trimmedUser = user?.trimmingCharacters(in: .whitespacesAndNewlines)
+        let normalizedUser: String?
+        if let trimmedUser {
+            guard self.isValidSSHComponent(trimmedUser) else { return nil }
+            normalizedUser = trimmedUser.isEmpty ? nil : trimmedUser
+        } else {
+            normalizedUser = nil
+        }
+        guard port > 0, port <= 65535 else { return nil }
+        return SSHParsedTarget(user: normalizedUser, host: trimmedHost, port: port)
+    }
+
+    private static func sshTargetString(_ target: SSHParsedTarget) -> String {
+        target.user.map { "\($0)@\(target.host)" } ?? target.host
+    }
+
+    static func sshArguments(
+        target: SSHParsedTarget,
+        identity: String,
+        options: [String],
+        remoteCommand: [String] = []) -> [String]
+    {
+        var args = options
+        if target.port > 0 {
+            args.append(contentsOf: ["-p", String(target.port)])
+        }
+        let trimmedIdentity = identity.trimmingCharacters(in: .whitespacesAndNewlines)
+        if !trimmedIdentity.isEmpty {
+            // Only use IdentitiesOnly when an explicit identity file is provided.
+            // This allows 1Password SSH agent and other SSH agents to provide keys.
+            args.append(contentsOf: ["-o", "IdentitiesOnly=yes"])
+            args.append(contentsOf: ["-i", trimmedIdentity])
+        }
+        args.append("--")
+        args.append(self.sshTargetString(target))
+        args.append(contentsOf: remoteCommand)
+        return args
+    }
+
+    #if SWIFT_PACKAGE
+    static func _testNodeManagerBinPaths(home: URL) -> [String] {
+        self.nodeManagerBinPaths(home: home)
+    }
+    #endif
+}

openclaw/apps/macos/Sources/OpenClaw/ConfigFileWatcher.swift

@@ -0,0 +1,45 @@
+import Foundation
+
+final class ConfigFileWatcher: @unchecked Sendable {
+    private let url: URL
+    private let watchedDir: URL
+    private let targetPath: String
+    private let targetName: String
+    private let watcher: CoalescingFSEventsWatcher
+
+    init(url: URL, onChange: @escaping () -> Void) {
+        self.url = url
+        self.watchedDir = url.deletingLastPathComponent()
+        self.targetPath = url.path
+        self.targetName = url.lastPathComponent
+        let watchedDirPath = self.watchedDir.path
+        let targetPath = self.targetPath
+        let targetName = self.targetName
+        self.watcher = CoalescingFSEventsWatcher(
+            paths: [watchedDirPath],
+            queueLabel: "ai.openclaw.configwatcher",
+            shouldNotify: { _, eventPaths in
+                guard let eventPaths else { return true }
+                let paths = unsafeBitCast(eventPaths, to: NSArray.self)
+                for case let path as String in paths {
+                    if path == targetPath { return true }
+                    if path.hasSuffix("/\(targetName)") { return true }
+                    if path == watchedDirPath { return true }
+                }
+                return false
+            },
+            onChange: onChange)
+    }
+
+    deinit {
+        self.stop()
+    }
+
+    func start() {
+        self.watcher.start()
+    }
+
+    func stop() {
+        self.watcher.stop()
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/ConfigSchemaSupport.swift

@@ -0,0 +1,219 @@
+import Foundation
+
+enum ConfigPathSegment: Hashable {
+    case key(String)
+    case index(Int)
+}
+
+typealias ConfigPath = [ConfigPathSegment]
+
+struct ConfigUiHint {
+    let label: String?
+    let help: String?
+    let order: Double?
+    let advanced: Bool?
+    let sensitive: Bool?
+    let placeholder: String?
+
+    init(raw: [String: Any]) {
+        self.label = raw["label"] as? String
+        self.help = raw["help"] as? String
+        if let order = raw["order"] as? Double {
+            self.order = order
+        } else if let orderInt = raw["order"] as? Int {
+            self.order = Double(orderInt)
+        } else {
+            self.order = nil
+        }
+        self.advanced = raw["advanced"] as? Bool
+        self.sensitive = raw["sensitive"] as? Bool
+        self.placeholder = raw["placeholder"] as? String
+    }
+}
+
+struct ConfigSchemaNode {
+    let raw: [String: Any]
+
+    init?(raw: Any) {
+        guard let dict = raw as? [String: Any] else { return nil }
+        self.raw = dict
+    }
+
+    var title: String? {
+        self.raw["title"] as? String
+    }
+
+    var description: String? {
+        self.raw["description"] as? String
+    }
+
+    var enumValues: [Any]? {
+        self.raw["enum"] as? [Any]
+    }
+
+    var constValue: Any? {
+        self.raw["const"]
+    }
+
+    var explicitDefault: Any? {
+        self.raw["default"]
+    }
+
+    var requiredKeys: Set<String> {
+        Set((self.raw["required"] as? [String]) ?? [])
+    }
+
+    var typeList: [String] {
+        if let type = self.raw["type"] as? String { return [type] }
+        if let types = self.raw["type"] as? [String] { return types }
+        return []
+    }
+
+    var schemaType: String? {
+        let filtered = self.typeList.filter { $0 != "null" }
+        if let first = filtered.first { return first }
+        return self.typeList.first
+    }
+
+    var isNullSchema: Bool {
+        let types = self.typeList
+        return types.count == 1 && types.first == "null"
+    }
+
+    var properties: [String: ConfigSchemaNode] {
+        guard let props = self.raw["properties"] as? [String: Any] else { return [:] }
+        return props.compactMapValues { ConfigSchemaNode(raw: $0) }
+    }
+
+    var anyOf: [ConfigSchemaNode] {
+        guard let raw = self.raw["anyOf"] as? [Any] else { return [] }
+        return raw.compactMap { ConfigSchemaNode(raw: $0) }
+    }
+
+    var oneOf: [ConfigSchemaNode] {
+        guard let raw = self.raw["oneOf"] as? [Any] else { return [] }
+        return raw.compactMap { ConfigSchemaNode(raw: $0) }
+    }
+
+    var literalValue: Any? {
+        if let constValue { return constValue }
+        if let enumValues, enumValues.count == 1 { return enumValues[0] }
+        return nil
+    }
+
+    var items: ConfigSchemaNode? {
+        if let items = self.raw["items"] as? [Any], let first = items.first {
+            return ConfigSchemaNode(raw: first)
+        }
+        if let items = self.raw["items"] {
+            return ConfigSchemaNode(raw: items)
+        }
+        return nil
+    }
+
+    var additionalProperties: ConfigSchemaNode? {
+        if let additional = self.raw["additionalProperties"] as? [String: Any] {
+            return ConfigSchemaNode(raw: additional)
+        }
+        return nil
+    }
+
+    var allowsAdditionalProperties: Bool {
+        if let allow = self.raw["additionalProperties"] as? Bool { return allow }
+        return self.additionalProperties != nil
+    }
+
+    var defaultValue: Any {
+        if let value = self.raw["default"] { return value }
+        switch self.schemaType {
+        case "object":
+            return [String: Any]()
+        case "array":
+            return [Any]()
+        case "boolean":
+            return false
+        case "integer":
+            return 0
+        case "number":
+            return 0.0
+        case "string":
+            return ""
+        default:
+            return ""
+        }
+    }
+
+    func node(at path: ConfigPath) -> ConfigSchemaNode? {
+        var current: ConfigSchemaNode? = self
+        for segment in path {
+            guard let node = current else { return nil }
+            switch segment {
+            case let .key(key):
+                if node.schemaType == "object" {
+                    if let next = node.properties[key] {
+                        current = next
+                        continue
+                    }
+                    if let additional = node.additionalProperties {
+                        current = additional
+                        continue
+                    }
+                    return nil
+                }
+                return nil
+            case .index:
+                guard node.schemaType == "array" else { return nil }
+                current = node.items
+            }
+        }
+        return current
+    }
+}
+
+func decodeUiHints(_ raw: [String: Any]) -> [String: ConfigUiHint] {
+    raw.reduce(into: [:]) { result, entry in
+        if let hint = entry.value as? [String: Any] {
+            result[entry.key] = ConfigUiHint(raw: hint)
+        }
+    }
+}
+
+func hintForPath(_ path: ConfigPath, hints: [String: ConfigUiHint]) -> ConfigUiHint? {
+    let key = pathKey(path)
+    if let direct = hints[key] { return direct }
+    let segments = key.split(separator: ".").map(String.init)
+    for (hintKey, hint) in hints {
+        guard hintKey.contains("*") else { continue }
+        let hintSegments = hintKey.split(separator: ".").map(String.init)
+        guard hintSegments.count == segments.count else { continue }
+        var match = true
+        for (index, seg) in segments.enumerated() {
+            let hintSegment = hintSegments[index]
+            if hintSegment != "*", hintSegment != seg {
+                match = false
+                break
+            }
+        }
+        if match { return hint }
+    }
+    return nil
+}
+
+func isSensitivePath(_ path: ConfigPath) -> Bool {
+    let key = pathKey(path).lowercased()
+    return key.contains("token")
+        || key.contains("password")
+        || key.contains("secret")
+        || key.contains("apikey")
+        || key.hasSuffix("key")
+}
+
+func pathKey(_ path: ConfigPath) -> String {
+    path.compactMap { segment -> String? in
+        switch segment {
+        case let .key(key): return key
+        case .index: return nil
+        }
+    }
+    .joined(separator: ".")
+}

openclaw/apps/macos/Sources/OpenClaw/ConfigSettings.swift

@@ -0,0 +1,395 @@
+import SwiftUI
+
+@MainActor
+struct ConfigSettings: View {
+    private let isPreview = ProcessInfo.processInfo.isPreview
+    private let isNixMode = ProcessInfo.processInfo.isNixMode
+    @Bindable var store: ChannelsStore
+    @State private var hasLoaded = false
+    @State private var activeSectionKey: String?
+    @State private var activeSubsection: SubsectionSelection?
+
+    init(store: ChannelsStore = .shared) {
+        self.store = store
+    }
+
+    var body: some View {
+        HStack(spacing: 16) {
+            self.sidebar
+            self.detail
+        }
+        .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .topLeading)
+        .task {
+            guard !self.hasLoaded else { return }
+            guard !self.isPreview else { return }
+            self.hasLoaded = true
+            await self.store.loadConfigSchema()
+            await self.store.loadConfig()
+        }
+        .onAppear { self.ensureSelection() }
+        .onChange(of: self.store.configSchemaLoading) { _, loading in
+            if !loading { self.ensureSelection() }
+        }
+    }
+}
+
+extension ConfigSettings {
+    private enum SubsectionSelection: Hashable {
+        case all
+        case key(String)
+    }
+
+    private struct ConfigSection: Identifiable {
+        let key: String
+        let label: String
+        let help: String?
+        let node: ConfigSchemaNode
+
+        var id: String {
+            self.key
+        }
+    }
+
+    private struct ConfigSubsection: Identifiable {
+        let key: String
+        let label: String
+        let help: String?
+        let node: ConfigSchemaNode
+        let path: ConfigPath
+
+        var id: String {
+            self.key
+        }
+    }
+
+    private var sections: [ConfigSection] {
+        guard let schema = self.store.configSchema else { return [] }
+        return self.resolveSections(schema)
+    }
+
+    private var activeSection: ConfigSection? {
+        self.sections.first { $0.key == self.activeSectionKey }
+    }
+
+    private var sidebar: some View {
+        ScrollView {
+            LazyVStack(alignment: .leading, spacing: 8) {
+                if self.sections.isEmpty {
+                    Text("No config sections available.")
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                        .padding(.horizontal, 6)
+                        .padding(.vertical, 4)
+                } else {
+                    ForEach(self.sections) { section in
+                        self.sidebarRow(section)
+                    }
+                }
+            }
+            .padding(.vertical, 10)
+            .padding(.horizontal, 10)
+        }
+        .frame(minWidth: 220, idealWidth: 240, maxWidth: 280, maxHeight: .infinity, alignment: .topLeading)
+        .background(
+            RoundedRectangle(cornerRadius: 12, style: .continuous)
+                .fill(Color(nsColor: .windowBackgroundColor)))
+        .clipShape(RoundedRectangle(cornerRadius: 12, style: .continuous))
+    }
+
+    private var detail: some View {
+        VStack(alignment: .leading, spacing: 16) {
+            if self.store.configSchemaLoading {
+                ProgressView().controlSize(.small)
+            } else if let section = self.activeSection {
+                self.sectionDetail(section)
+            } else if self.store.configSchema != nil {
+                self.emptyDetail
+            } else {
+                Text("Schema unavailable.")
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+            }
+        }
+        .frame(minWidth: 460, maxWidth: .infinity, maxHeight: .infinity, alignment: .topLeading)
+    }
+
+    private var emptyDetail: some View {
+        VStack(alignment: .leading, spacing: 8) {
+            self.header
+            Text("Select a config section to view settings.")
+                .font(.callout)
+                .foregroundStyle(.secondary)
+        }
+        .padding(.horizontal, 24)
+        .padding(.vertical, 18)
+    }
+
+    private func sectionDetail(_ section: ConfigSection) -> some View {
+        ScrollView(.vertical) {
+            VStack(alignment: .leading, spacing: 16) {
+                self.header
+                if let status = self.store.configStatus {
+                    Text(status)
+                        .font(.callout)
+                        .foregroundStyle(.secondary)
+                }
+                self.actionRow
+                self.sectionHeader(section)
+                self.subsectionNav(section)
+                self.sectionForm(section)
+                if self.store.configDirty, !self.isNixMode {
+                    Text("Unsaved changes")
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                }
+                Spacer(minLength: 0)
+            }
+            .frame(maxWidth: .infinity, alignment: .leading)
+            .padding(.horizontal, 24)
+            .padding(.vertical, 18)
+            .groupBoxStyle(PlainSettingsGroupBoxStyle())
+        }
+    }
+
+    @ViewBuilder
+    private var header: some View {
+        Text("Config")
+            .font(.title3.weight(.semibold))
+        Text(self.isNixMode
+            ? "This tab is read-only in Nix mode. Edit config via Nix and rebuild."
+            : "Edit ~/.openclaw/openclaw.json using the schema-driven form.")
+            .font(.callout)
+            .foregroundStyle(.secondary)
+    }
+
+    private func sectionHeader(_ section: ConfigSection) -> some View {
+        VStack(alignment: .leading, spacing: 6) {
+            Text(section.label)
+                .font(.title3.weight(.semibold))
+            if let help = section.help {
+                Text(help)
+                    .font(.callout)
+                    .foregroundStyle(.secondary)
+            }
+        }
+    }
+
+    private var actionRow: some View {
+        HStack(spacing: 10) {
+            Button("Reload") {
+                Task { await self.store.reloadConfigDraft() }
+            }
+            .disabled(!self.store.configLoaded)
+
+            Button(self.store.isSavingConfig ? "Saving…" : "Save") {
+                Task { await self.store.saveConfigDraft() }
+            }
+            .disabled(self.isNixMode || self.store.isSavingConfig || !self.store.configDirty)
+        }
+        .buttonStyle(.bordered)
+    }
+
+    private func sidebarRow(_ section: ConfigSection) -> some View {
+        let isSelected = self.activeSectionKey == section.key
+        return Button {
+            self.selectSection(section)
+        } label: {
+            VStack(alignment: .leading, spacing: 2) {
+                Text(section.label)
+                if let help = section.help {
+                    Text(help)
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                        .lineLimit(2)
+                }
+            }
+            .padding(.vertical, 6)
+            .padding(.horizontal, 8)
+            .frame(maxWidth: .infinity, alignment: .leading)
+            .background(isSelected ? Color.accentColor.opacity(0.18) : Color.clear)
+            .clipShape(RoundedRectangle(cornerRadius: 10, style: .continuous))
+            .background(Color.clear)
+            .contentShape(Rectangle())
+        }
+        .frame(maxWidth: .infinity, alignment: .leading)
+        .buttonStyle(.plain)
+        .contentShape(Rectangle())
+    }
+
+    @ViewBuilder
+    private func subsectionNav(_ section: ConfigSection) -> some View {
+        let subsections = self.resolveSubsections(for: section)
+        if subsections.isEmpty {
+            EmptyView()
+        } else {
+            ScrollView(.horizontal, showsIndicators: false) {
+                HStack(spacing: 8) {
+                    self.subsectionButton(
+                        title: "All",
+                        isSelected: self.activeSubsection == .all)
+                    {
+                        self.activeSubsection = .all
+                    }
+                    ForEach(subsections) { subsection in
+                        self.subsectionButton(
+                            title: subsection.label,
+                            isSelected: self.activeSubsection == .key(subsection.key))
+                        {
+                            self.activeSubsection = .key(subsection.key)
+                        }
+                    }
+                }
+                .padding(.vertical, 2)
+            }
+        }
+    }
+
+    private func subsectionButton(
+        title: String,
+        isSelected: Bool,
+        action: @escaping () -> Void) -> some View
+    {
+        Button(action: action) {
+            Text(title)
+                .font(.callout.weight(.semibold))
+                .foregroundStyle(isSelected ? Color.accentColor : .primary)
+                .padding(.horizontal, 10)
+                .padding(.vertical, 6)
+                .background(isSelected ? Color.accentColor.opacity(0.18) : Color(nsColor: .controlBackgroundColor))
+                .clipShape(Capsule())
+        }
+        .buttonStyle(.plain)
+    }
+
+    private func sectionForm(_ section: ConfigSection) -> some View {
+        let subsection = self.activeSubsection
+        let defaultPath: ConfigPath = [.key(section.key)]
+        let subsections = self.resolveSubsections(for: section)
+        let resolved: (ConfigSchemaNode, ConfigPath) = {
+            if case let .key(key) = subsection,
+               let match = subsections.first(where: { $0.key == key })
+            {
+                return (match.node, match.path)
+            }
+            return (self.resolvedSchemaNode(section.node), defaultPath)
+        }()
+
+        return ConfigSchemaForm(store: self.store, schema: resolved.0, path: resolved.1)
+            .disabled(self.isNixMode)
+    }
+
+    private func ensureSelection() {
+        guard let schema = self.store.configSchema else { return }
+        let sections = self.resolveSections(schema)
+        guard !sections.isEmpty else { return }
+
+        let active = sections.first { $0.key == self.activeSectionKey } ?? sections[0]
+        if self.activeSectionKey != active.key {
+            self.activeSectionKey = active.key
+        }
+        self.ensureSubsection(for: active)
+    }
+
+    private func ensureSubsection(for section: ConfigSection) {
+        let subsections = self.resolveSubsections(for: section)
+        guard !subsections.isEmpty else {
+            self.activeSubsection = nil
+            return
+        }
+
+        switch self.activeSubsection {
+        case .all:
+            return
+        case let .key(key):
+            if subsections.contains(where: { $0.key == key }) { return }
+        case .none:
+            break
+        }
+
+        if let first = subsections.first {
+            self.activeSubsection = .key(first.key)
+        }
+    }
+
+    private func selectSection(_ section: ConfigSection) {
+        guard self.activeSectionKey != section.key else { return }
+        self.activeSectionKey = section.key
+        let subsections = self.resolveSubsections(for: section)
+        if let first = subsections.first {
+            self.activeSubsection = .key(first.key)
+        } else {
+            self.activeSubsection = nil
+        }
+    }
+
+    private func resolveSections(_ root: ConfigSchemaNode) -> [ConfigSection] {
+        let node = self.resolvedSchemaNode(root)
+        let hints = self.store.configUiHints
+        let keys = node.properties.keys.sorted { lhs, rhs in
+            let orderA = hintForPath([.key(lhs)], hints: hints)?.order ?? 0
+            let orderB = hintForPath([.key(rhs)], hints: hints)?.order ?? 0
+            if orderA != orderB { return orderA < orderB }
+            return lhs < rhs
+        }
+
+        return keys.compactMap { key in
+            guard let child = node.properties[key] else { return nil }
+            let path: ConfigPath = [.key(key)]
+            let hint = hintForPath(path, hints: hints)
+            let label = hint?.label
+                ?? child.title
+                ?? self.humanize(key)
+            let help = hint?.help ?? child.description
+            return ConfigSection(key: key, label: label, help: help, node: child)
+        }
+    }
+
+    private func resolveSubsections(for section: ConfigSection) -> [ConfigSubsection] {
+        let node = self.resolvedSchemaNode(section.node)
+        guard node.schemaType == "object" else { return [] }
+        let hints = self.store.configUiHints
+        let keys = node.properties.keys.sorted { lhs, rhs in
+            let orderA = hintForPath([.key(section.key), .key(lhs)], hints: hints)?.order ?? 0
+            let orderB = hintForPath([.key(section.key), .key(rhs)], hints: hints)?.order ?? 0
+            if orderA != orderB { return orderA < orderB }
+            return lhs < rhs
+        }
+
+        return keys.compactMap { key in
+            guard let child = node.properties[key] else { return nil }
+            let path: ConfigPath = [.key(section.key), .key(key)]
+            let hint = hintForPath(path, hints: hints)
+            let label = hint?.label
+                ?? child.title
+                ?? self.humanize(key)
+            let help = hint?.help ?? child.description
+            return ConfigSubsection(
+                key: key,
+                label: label,
+                help: help,
+                node: child,
+                path: path)
+        }
+    }
+
+    private func resolvedSchemaNode(_ node: ConfigSchemaNode) -> ConfigSchemaNode {
+        let variants = node.anyOf.isEmpty ? node.oneOf : node.anyOf
+        if !variants.isEmpty {
+            let nonNull = variants.filter { !$0.isNullSchema }
+            if nonNull.count == 1, let only = nonNull.first { return only }
+        }
+        return node
+    }
+
+    private func humanize(_ key: String) -> String {
+        key.replacingOccurrences(of: "_", with: " ")
+            .replacingOccurrences(of: "-", with: " ")
+            .capitalized
+    }
+}
+
+struct ConfigSettings_Previews: PreviewProvider {
+    static var previews: some View {
+        ConfigSettings()
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/ConfigStore.swift

@@ -0,0 +1,117 @@
+import Foundation
+import OpenClawProtocol
+
+enum ConfigStore {
+    struct Overrides: Sendable {
+        var isRemoteMode: (@Sendable () async -> Bool)?
+        var loadLocal: (@MainActor @Sendable () -> [String: Any])?
+        var saveLocal: (@MainActor @Sendable ([String: Any]) -> Void)?
+        var loadRemote: (@MainActor @Sendable () async -> [String: Any])?
+        var saveRemote: (@MainActor @Sendable ([String: Any]) async throws -> Void)?
+    }
+
+    private actor OverrideStore {
+        var overrides = Overrides()
+
+        func setOverride(_ overrides: Overrides) {
+            self.overrides = overrides
+        }
+    }
+
+    private static let overrideStore = OverrideStore()
+    @MainActor private static var lastHash: String?
+
+    private static func isRemoteMode() async -> Bool {
+        let overrides = await self.overrideStore.overrides
+        if let override = overrides.isRemoteMode {
+            return await override()
+        }
+        return await MainActor.run { AppStateStore.shared.connectionMode == .remote }
+    }
+
+    @MainActor
+    static func load() async -> [String: Any] {
+        let overrides = await self.overrideStore.overrides
+        if await self.isRemoteMode() {
+            if let override = overrides.loadRemote {
+                return await override()
+            }
+            return await self.loadFromGateway() ?? [:]
+        }
+        if let override = overrides.loadLocal {
+            return override()
+        }
+        if let gateway = await self.loadFromGateway() {
+            return gateway
+        }
+        return OpenClawConfigFile.loadDict()
+    }
+
+    @MainActor
+    static func save(_ root: sending [String: Any]) async throws {
+        let overrides = await self.overrideStore.overrides
+        if await self.isRemoteMode() {
+            if let override = overrides.saveRemote {
+                try await override(root)
+            } else {
+                try await self.saveToGateway(root)
+            }
+        } else {
+            if let override = overrides.saveLocal {
+                override(root)
+            } else {
+                do {
+                    try await self.saveToGateway(root)
+                } catch {
+                    OpenClawConfigFile.saveDict(root)
+                }
+            }
+        }
+    }
+
+    @MainActor
+    private static func loadFromGateway() async -> [String: Any]? {
+        do {
+            let snap: ConfigSnapshot = try await GatewayConnection.shared.requestDecoded(
+                method: .configGet,
+                params: nil,
+                timeoutMs: 8000)
+            self.lastHash = snap.hash
+            return snap.config?.mapValues { $0.foundationValue } ?? [:]
+        } catch {
+            return nil
+        }
+    }
+
+    @MainActor
+    private static func saveToGateway(_ root: [String: Any]) async throws {
+        if self.lastHash == nil {
+            _ = await self.loadFromGateway()
+        }
+        let data = try JSONSerialization.data(withJSONObject: root, options: [.prettyPrinted, .sortedKeys])
+        guard let raw = String(data: data, encoding: .utf8) else {
+            throw NSError(domain: "ConfigStore", code: 1, userInfo: [
+                NSLocalizedDescriptionKey: "Failed to encode config.",
+            ])
+        }
+        var params: [String: AnyCodable] = ["raw": AnyCodable(raw)]
+        if let baseHash = self.lastHash {
+            params["baseHash"] = AnyCodable(baseHash)
+        }
+        _ = try await GatewayConnection.shared.requestRaw(
+            method: .configSet,
+            params: params,
+            timeoutMs: 10000)
+        _ = await self.loadFromGateway()
+    }
+
+    #if DEBUG
+    static func _testSetOverrides(_ overrides: Overrides) async {
+        await self.overrideStore.setOverride(overrides)
+    }
+
+    static func _testClearOverrides() async {
+        await self.overrideStore.setOverride(.init())
+    }
+    #endif
+}

openclaw/apps/macos/Sources/OpenClaw/ConnectionModeCoordinator.swift

@@ -0,0 +1,79 @@
+import Foundation
+import OSLog
+
+@MainActor
+final class ConnectionModeCoordinator {
+    static let shared = ConnectionModeCoordinator()
+
+    private let logger = Logger(subsystem: "ai.openclaw", category: "connection")
+    private var lastMode: AppState.ConnectionMode?
+
+    /// Apply the requested connection mode by starting/stopping local gateway,
+    /// managing the control-channel SSH tunnel, and cleaning up chat windows/panels.
+    func apply(mode: AppState.ConnectionMode, paused: Bool) async {
+        if let lastMode = self.lastMode, lastMode != mode {
+            GatewayProcessManager.shared.clearLastFailure()
+            NodesStore.shared.lastError = nil
+        }
+        self.lastMode = mode
+        switch mode {
+        case .unconfigured:
+            _ = await NodeServiceManager.stop()
+            NodesStore.shared.lastError = nil
+            await RemoteTunnelManager.shared.stopAll()
+            WebChatManager.shared.resetTunnels()
+            GatewayProcessManager.shared.stop()
+            await GatewayConnection.shared.shutdown()
+            await ControlChannel.shared.disconnect()
+            Task.detached { await PortGuardian.shared.sweep(mode: .unconfigured) }
+
+        case .local:
+            _ = await NodeServiceManager.stop()
+            NodesStore.shared.lastError = nil
+            await RemoteTunnelManager.shared.stopAll()
+            WebChatManager.shared.resetTunnels()
+            let shouldStart = GatewayAutostartPolicy.shouldStartGateway(mode: .local, paused: paused)
+            if shouldStart {
+                GatewayProcessManager.shared.setActive(true)
+                if GatewayAutostartPolicy.shouldEnsureLaunchAgent(
+                    mode: .local,
+                    paused: paused)
+                {
+                    Task { await GatewayProcessManager.shared.ensureLaunchAgentEnabledIfNeeded() }
+                }
+                _ = await GatewayProcessManager.shared.waitForGatewayReady()
+            } else {
+                GatewayProcessManager.shared.stop()
+            }
+            do {
+                try await ControlChannel.shared.configure(mode: .local)
+            } catch {
+                // Control channel will mark itself degraded; nothing else to do here.
+                self.logger.error(
+                    "control channel local configure failed: \(error.localizedDescription, privacy: .public)")
+            }
+            Task.detached { await PortGuardian.shared.sweep(mode: .local) }
+
+        case .remote:
+            // Never run a local gateway in remote mode.
+            GatewayProcessManager.shared.stop()
+            WebChatManager.shared.resetTunnels()
+
+            do {
+                NodesStore.shared.lastError = nil
+                if let error = await NodeServiceManager.start() {
+                    NodesStore.shared.lastError = "Node service start failed: \(error)"
+                }
+                _ = try await GatewayEndpointStore.shared.ensureRemoteControlTunnel()
+                let settings = CommandResolver.connectionSettings()
+                try await ControlChannel.shared.configure(mode: .remote(
+                    target: settings.target,
+                    identity: settings.identity))
+            } catch {
+                self.logger.error("remote tunnel/configure failed: \(error.localizedDescription, privacy: .public)")
+            }
+
+            Task.detached { await PortGuardian.shared.sweep(mode: .remote) }
+        }
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/ConnectionModeResolver.swift

@@ -0,0 +1,49 @@
+import Foundation
+
+enum EffectiveConnectionModeSource: Sendable, Equatable {
+    case configMode
+    case configRemoteURL
+    case userDefaults
+    case onboarding
+}
+
+struct EffectiveConnectionMode: Sendable, Equatable {
+    let mode: AppState.ConnectionMode
+    let source: EffectiveConnectionModeSource
+}
+
+enum ConnectionModeResolver {
+    static func resolve(
+        root: [String: Any],
+        defaults: UserDefaults = .standard) -> EffectiveConnectionMode
+    {
+        let gateway = root["gateway"] as? [String: Any]
+        let configModeRaw = (gateway?["mode"] as? String) ?? ""
+        let configMode = configModeRaw
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+            .lowercased()
+
+        switch configMode {
+        case "local":
+            return EffectiveConnectionMode(mode: .local, source: .configMode)
+        case "remote":
+            return EffectiveConnectionMode(mode: .remote, source: .configMode)
+        default:
+            break
+        }
+
+        let remoteURLRaw = ((gateway?["remote"] as? [String: Any])?["url"] as? String) ?? ""
+        let remoteURL = remoteURLRaw.trimmingCharacters(in: .whitespacesAndNewlines)
+        if !remoteURL.isEmpty {
+            return EffectiveConnectionMode(mode: .remote, source: .configRemoteURL)
+        }
+
+        if let storedModeRaw = defaults.string(forKey: connectionModeKey) {
+            let storedMode = AppState.ConnectionMode(rawValue: storedModeRaw) ?? .local
+            return EffectiveConnectionMode(mode: storedMode, source: .userDefaults)
+        }
+
+        let seen = defaults.bool(forKey: "openclaw.onboardingSeen")
+        return EffectiveConnectionMode(mode: seen ? .local : .unconfigured, source: .onboarding)
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/Constants.swift

@@ -0,0 +1,48 @@
+import Foundation
+
+// Stable identifier used for both the macOS LaunchAgent label and Nix-managed defaults suite.
+// nix-openclaw writes app defaults into this suite to survive app bundle identifier churn.
+let launchdLabel = "ai.openclaw.mac"
+let gatewayLaunchdLabel = "ai.openclaw.gateway"
+let onboardingVersionKey = "openclaw.onboardingVersion"
+let onboardingSeenKey = "openclaw.onboardingSeen"
+let currentOnboardingVersion = 7
+let pauseDefaultsKey = "openclaw.pauseEnabled"
+let iconAnimationsEnabledKey = "openclaw.iconAnimationsEnabled"
+let swabbleEnabledKey = "openclaw.swabbleEnabled"
+let swabbleTriggersKey = "openclaw.swabbleTriggers"
+let voiceWakeTriggerChimeKey = "openclaw.voiceWakeTriggerChime"
+let voiceWakeSendChimeKey = "openclaw.voiceWakeSendChime"
+let showDockIconKey = "openclaw.showDockIcon"
+let defaultVoiceWakeTriggers = ["openclaw"]
+let voiceWakeMaxWords = 32
+let voiceWakeMaxWordLength = 64
+let voiceWakeMicKey = "openclaw.voiceWakeMicID"
+let voiceWakeMicNameKey = "openclaw.voiceWakeMicName"
+let voiceWakeLocaleKey = "openclaw.voiceWakeLocaleID"
+let voiceWakeAdditionalLocalesKey = "openclaw.voiceWakeAdditionalLocaleIDs"
+let voicePushToTalkEnabledKey = "openclaw.voicePushToTalkEnabled"
+let talkEnabledKey = "openclaw.talkEnabled"
+let iconOverrideKey = "openclaw.iconOverride"
+let connectionModeKey = "openclaw.connectionMode"
+let remoteTargetKey = "openclaw.remoteTarget"
+let remoteIdentityKey = "openclaw.remoteIdentity"
+let remoteProjectRootKey = "openclaw.remoteProjectRoot"
+let remoteCliPathKey = "openclaw.remoteCliPath"
+let canvasEnabledKey = "openclaw.canvasEnabled"
+let cameraEnabledKey = "openclaw.cameraEnabled"
+let systemRunPolicyKey = "openclaw.systemRunPolicy"
+let systemRunAllowlistKey = "openclaw.systemRunAllowlist"
+let systemRunEnabledKey = "openclaw.systemRunEnabled"
+let locationModeKey = "openclaw.locationMode"
+let locationPreciseKey = "openclaw.locationPreciseEnabled"
+let peekabooBridgeEnabledKey = "openclaw.peekabooBridgeEnabled"
+let deepLinkKeyKey = "openclaw.deepLinkKey"
+let modelCatalogPathKey = "openclaw.modelCatalogPath"
+let modelCatalogReloadKey = "openclaw.modelCatalogReload"
+let cliInstallPromptedVersionKey = "openclaw.cliInstallPromptedVersion"
+let heartbeatsEnabledKey = "openclaw.heartbeatsEnabled"
+let debugPaneEnabledKey = "openclaw.debugPaneEnabled"
+let debugFileLogEnabledKey = "openclaw.debug.fileLogEnabled"
+let appLogLevelKey = "openclaw.debug.appLogLevel"
+let voiceWakeSupported: Bool = ProcessInfo.processInfo.operatingSystemVersion.majorVersion >= 26

openclaw/apps/macos/Sources/OpenClaw/ContextMenuCardView.swift

@@ -0,0 +1,120 @@
+import Foundation
+import SwiftUI
+
+/// Context usage card shown at the top of the menubar menu.
+struct ContextMenuCardView: View {
+    private let rows: [SessionRow]
+    private let statusText: String?
+    private let isLoading: Bool
+    private let paddingTop: CGFloat = 8
+    private let paddingBottom: CGFloat = 8
+    private let paddingTrailing: CGFloat = 10
+    private let paddingLeading: CGFloat = 20
+    private let barHeight: CGFloat = 3
+
+    init(
+        rows: [SessionRow],
+        statusText: String? = nil,
+        isLoading: Bool = false)
+    {
+        self.rows = rows
+        self.statusText = statusText
+        self.isLoading = isLoading
+    }
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 6) {
+            HStack(alignment: .firstTextBaseline) {
+                Text("Context")
+                    .font(.caption.weight(.semibold))
+                    .foregroundStyle(.secondary)
+                Spacer(minLength: 10)
+                Text(self.subtitle)
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+            }
+
+            if let statusText {
+                Text(statusText)
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+            } else if self.rows.isEmpty, !self.isLoading {
+                Text("No active sessions")
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+            } else {
+                VStack(alignment: .leading, spacing: 12) {
+                    if self.rows.isEmpty, self.isLoading {
+                        ForEach(0..<2, id: \.self) { _ in
+                            self.placeholderRow
+                        }
+                    } else {
+                        ForEach(self.rows) { row in
+                            self.sessionRow(row)
+                        }
+                    }
+                }
+            }
+        }
+        .padding(.top, self.paddingTop)
+        .padding(.bottom, self.paddingBottom)
+        .padding(.leading, self.paddingLeading)
+        .padding(.trailing, self.paddingTrailing)
+        .frame(minWidth: 300, maxWidth: .infinity, alignment: .leading)
+        .transaction { txn in txn.animation = nil }
+    }
+
+    private var subtitle: String {
+        let count = self.rows.count
+        if count == 1 { return "1 session · 24h" }
+        return "\(count) sessions · 24h"
+    }
+
+    private func sessionRow(_ row: SessionRow) -> some View {
+        VStack(alignment: .leading, spacing: 5) {
+            ContextUsageBar(
+                usedTokens: row.tokens.total,
+                contextTokens: row.tokens.contextTokens,
+                height: self.barHeight)
+
+            HStack(alignment: .firstTextBaseline, spacing: 8) {
+                Text(row.label)
+                    .font(.caption.weight(row.key == "main" ? .semibold : .regular))
+                    .lineLimit(1)
+                    .truncationMode(.middle)
+                    .layoutPriority(1)
+                Spacer(minLength: 8)
+                Text(row.tokens.contextSummaryShort)
+                    .font(.caption.monospacedDigit())
+                    .foregroundStyle(.secondary)
+                    .lineLimit(1)
+                    .fixedSize(horizontal: true, vertical: false)
+                    .layoutPriority(2)
+            }
+        }
+        .padding(.vertical, 2)
+    }
+
+    private var placeholderRow: some View {
+        VStack(alignment: .leading, spacing: 5) {
+            ContextUsageBar(
+                usedTokens: 0,
+                contextTokens: 200_000,
+                height: self.barHeight)
+
+            HStack(alignment: .firstTextBaseline, spacing: 8) {
+                Text("main")
+                    .font(.caption.weight(.semibold))
+                    .lineLimit(1)
+                    .layoutPriority(1)
+                Spacer(minLength: 8)
+                Text("000k/000k")
+                    .font(.caption.monospacedDigit())
+                    .foregroundStyle(.secondary)
+                    .fixedSize(horizontal: true, vertical: false)
+                    .layoutPriority(2)
+            }
+            .redacted(reason: .placeholder)
+        }
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/ContextUsageBar.swift

@@ -0,0 +1,93 @@
+import SwiftUI
+
+struct ContextUsageBar: View {
+    let usedTokens: Int
+    let contextTokens: Int
+    var width: CGFloat?
+    var height: CGFloat = 6
+
+    private static let okGreen: NSColor = .init(name: nil) { appearance in
+        let base = NSColor.systemGreen
+        let match = appearance.bestMatch(from: [.aqua, .darkAqua])
+        if match == .darkAqua { return base }
+        return base.blended(withFraction: 0.24, of: .black) ?? base
+    }
+
+    private static let trackFill: NSColor = .init(name: nil) { appearance in
+        let match = appearance.bestMatch(from: [.aqua, .darkAqua])
+        if match == .darkAqua { return NSColor.white.withAlphaComponent(0.14) }
+        return NSColor.black.withAlphaComponent(0.12)
+    }
+
+    private static let trackStroke: NSColor = .init(name: nil) { appearance in
+        let match = appearance.bestMatch(from: [.aqua, .darkAqua])
+        if match == .darkAqua { return NSColor.white.withAlphaComponent(0.22) }
+        return NSColor.black.withAlphaComponent(0.2)
+    }
+
+    private var clampedFractionUsed: Double {
+        guard self.contextTokens > 0 else { return 0 }
+        return min(1, max(0, Double(self.usedTokens) / Double(self.contextTokens)))
+    }
+
+    private var percentUsed: Int? {
+        guard self.contextTokens > 0, self.usedTokens > 0 else { return nil }
+        return min(100, Int(round(self.clampedFractionUsed * 100)))
+    }
+
+    private var tint: Color {
+        guard let pct = self.percentUsed else { return .secondary }
+        if pct >= 95 { return Color(nsColor: .systemRed) }
+        if pct >= 80 { return Color(nsColor: .systemOrange) }
+        if pct >= 60 { return Color(nsColor: .systemYellow) }
+        return Color(nsColor: Self.okGreen)
+    }
+
+    var body: some View {
+        let fraction = self.clampedFractionUsed
+        Group {
+            if let width = self.width, width > 0 {
+                self.barBody(width: width, fraction: fraction)
+                    .frame(width: width, height: self.height)
+            } else {
+                GeometryReader { proxy in
+                    self.barBody(width: proxy.size.width, fraction: fraction)
+                        .frame(width: proxy.size.width, height: self.height)
+                }
+                .frame(height: self.height)
+            }
+        }
+        .accessibilityLabel("Context usage")
+        .accessibilityValue(self.accessibilityValue)
+    }
+
+    private var accessibilityValue: String {
+        if self.contextTokens <= 0 { return "Unknown context window" }
+        let pct = Int(round(self.clampedFractionUsed * 100))
+        return "\(pct) percent used"
+    }
+
+    @ViewBuilder
+    private func barBody(width: CGFloat, fraction: Double) -> some View {
+        let radius = self.height / 2
+        let trackFill = Color(nsColor: Self.trackFill)
+        let trackStroke = Color(nsColor: Self.trackStroke)
+        let fillWidth = max(1, floor(width * CGFloat(fraction)))
+
+        ZStack(alignment: .leading) {
+            RoundedRectangle(cornerRadius: radius, style: .continuous)
+                .fill(trackFill)
+                .overlay {
+                    RoundedRectangle(cornerRadius: radius, style: .continuous)
+                        .strokeBorder(trackStroke, lineWidth: 0.75)
+                }
+
+            RoundedRectangle(cornerRadius: radius, style: .continuous)
+                .fill(self.tint)
+                .frame(width: fillWidth)
+                .mask {
+                    RoundedRectangle(cornerRadius: radius, style: .continuous)
+                }
+        }
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/ControlChannel.swift

@@ -0,0 +1,428 @@
+import Foundation
+import Observation
+import OpenClawKit
+import OpenClawProtocol
+import SwiftUI
+
+struct ControlHeartbeatEvent: Codable {
+    let ts: Double
+    let status: String
+    let to: String?
+    let preview: String?
+    let durationMs: Double?
+    let hasMedia: Bool?
+    let reason: String?
+}
+
+struct ControlAgentEvent: Codable, Sendable, Identifiable {
+    var id: String {
+        "\(self.runId)-\(self.seq)"
+    }
+
+    let runId: String
+    let seq: Int
+    let stream: String
+    let ts: Double
+    let data: [String: OpenClawProtocol.AnyCodable]
+    let summary: String?
+}
+
+enum ControlChannelError: Error, LocalizedError {
+    case disconnected
+    case badResponse(String)
+
+    var errorDescription: String? {
+        switch self {
+        case .disconnected: "Control channel disconnected"
+        case let .badResponse(msg): msg
+        }
+    }
+}
+
+@MainActor
+@Observable
+final class ControlChannel {
+    static let shared = ControlChannel()
+
+    enum Mode {
+        case local
+        case remote(target: String, identity: String)
+    }
+
+    enum ConnectionState: Equatable {
+        case disconnected
+        case connecting
+        case connected
+        case degraded(String)
+    }
+
+    private(set) var state: ConnectionState = .disconnected {
+        didSet {
+            CanvasManager.shared.refreshDebugStatus()
+            guard oldValue != self.state else { return }
+            switch self.state {
+            case .connected:
+                self.logger.info("control channel state -> connected")
+            case .connecting:
+                self.logger.info("control channel state -> connecting")
+            case .disconnected:
+                self.logger.info("control channel state -> disconnected")
+                self.scheduleRecovery(reason: "disconnected")
+            case let .degraded(message):
+                let detail = message.isEmpty ? "degraded" : "degraded: \(message)"
+                self.logger.info("control channel state -> \(detail, privacy: .public)")
+                self.scheduleRecovery(reason: message)
+            }
+        }
+    }
+
+    private(set) var lastPingMs: Double?
+    private(set) var authSourceLabel: String?
+
+    private let logger = Logger(subsystem: "ai.openclaw", category: "control")
+
+    private var eventTask: Task<Void, Never>?
+    private var recoveryTask: Task<Void, Never>?
+    private var lastRecoveryAt: Date?
+
+    private init() {
+        self.startEventStream()
+    }
+
+    func configure() async {
+        self.logger.info("control channel configure mode=local")
+        await self.refreshEndpoint(reason: "configure")
+    }
+
+    func configure(mode: Mode = .local) async throws {
+        switch mode {
+        case .local:
+            await self.configure()
+        case let .remote(target, identity):
+            do {
+                _ = (target, identity)
+                let idSet = !identity.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
+                self.logger.info(
+                    "control channel configure mode=remote " +
+                        "target=\(target, privacy: .public) identitySet=\(idSet, privacy: .public)")
+                self.state = .connecting
+                _ = try await GatewayEndpointStore.shared.ensureRemoteControlTunnel()
+                await self.refreshEndpoint(reason: "configure")
+            } catch {
+                self.state = .degraded(error.localizedDescription)
+                throw error
+            }
+        }
+    }
+
+    func refreshEndpoint(reason: String) async {
+        self.logger.info("control channel refresh endpoint reason=\(reason, privacy: .public)")
+        self.state = .connecting
+        do {
+            try await self.establishGatewayConnection()
+            self.state = .connected
+            PresenceReporter.shared.sendImmediate(reason: "connect")
+        } catch {
+            let message = self.friendlyGatewayMessage(error)
+            self.state = .degraded(message)
+        }
+    }
+
+    func disconnect() async {
+        await GatewayConnection.shared.shutdown()
+        self.state = .disconnected
+        self.lastPingMs = nil
+        self.authSourceLabel = nil
+    }
+
+    func health(timeout: TimeInterval? = nil) async throws -> Data {
+        do {
+            let start = Date()
+            var params: [String: AnyHashable]?
+            if let timeout {
+                params = ["timeout": AnyHashable(Int(timeout * 1000))]
+            }
+            let timeoutMs = (timeout ?? 15) * 1000
+            let payload = try await self.request(method: "health", params: params, timeoutMs: timeoutMs)
+            let ms = Date().timeIntervalSince(start) * 1000
+            self.lastPingMs = ms
+            self.state = .connected
+            return payload
+        } catch {
+            let message = self.friendlyGatewayMessage(error)
+            self.state = .degraded(message)
+            throw ControlChannelError.badResponse(message)
+        }
+    }
+
+    func lastHeartbeat() async throws -> ControlHeartbeatEvent? {
+        let data = try await self.request(method: "last-heartbeat")
+        return try JSONDecoder().decode(ControlHeartbeatEvent?.self, from: data)
+    }
+
+    func request(
+        method: String,
+        params: [String: AnyHashable]? = nil,
+        timeoutMs: Double? = nil) async throws -> Data
+    {
+        do {
+            let rawParams = params?.reduce(into: [String: OpenClawKit.AnyCodable]()) {
+                $0[$1.key] = OpenClawKit.AnyCodable($1.value.base)
+            }
+            let data = try await GatewayConnection.shared.request(
+                method: method,
+                params: rawParams,
+                timeoutMs: timeoutMs)
+            self.state = .connected
+            return data
+        } catch {
+            let message = self.friendlyGatewayMessage(error)
+            self.state = .degraded(message)
+            throw ControlChannelError.badResponse(message)
+        }
+    }
+
+    private func friendlyGatewayMessage(_ error: Error) -> String {
+        // Map URLSession/WS errors into user-facing, actionable text.
+        if let ctrlErr = error as? ControlChannelError, let desc = ctrlErr.errorDescription {
+            return desc
+        }
+
+        // If the gateway explicitly rejects the hello (e.g., auth/token mismatch), surface it.
+        if let urlErr = error as? URLError,
+           urlErr.code == .dataNotAllowed // used for WS close 1008 auth failures
+        {
+            let reason = urlErr.failureURLString ?? urlErr.localizedDescription
+            let tokenKey = CommandResolver.connectionModeIsRemote()
+                ? "gateway.remote.token"
+                : "gateway.auth.token"
+            return
+                "Gateway rejected token; set \(tokenKey) or clear it on the gateway. Reason: \(reason)"
+        }
+
+        // Common misfire: we connected to the configured localhost port but it is occupied
+        // by some other process (e.g. a local dev gateway or a stuck SSH forward).
+        // The gateway handshake returns something we can't parse, which currently
+        // surfaces as "hello failed (unexpected response)". Give the user a pointer
+        // to free the port instead of a vague message.
+        let nsError = error as NSError
+        if nsError.domain == "Gateway",
+           nsError.localizedDescription.contains("hello failed (unexpected response)")
+        {
+            let port = GatewayEnvironment.gatewayPort()
+            return """
+            Gateway handshake got non-gateway data on localhost:\(port).
+            Another process is using that port or the SSH forward failed.
+            Stop the local gateway/port-forward on \(port) and retry Remote mode.
+            """
+        }
+
+        if let urlError = error as? URLError {
+            let port = GatewayEnvironment.gatewayPort()
+            switch urlError.code {
+            case .cancelled:
+                return "Gateway connection was closed; start the gateway (localhost:\(port)) and retry."
+            case .cannotFindHost, .cannotConnectToHost:
+                let isRemote = CommandResolver.connectionModeIsRemote()
+                if isRemote {
+                    return """
+                    Cannot reach gateway at localhost:\(port).
+                    Remote mode uses an SSH tunnel—check the SSH target and that the tunnel is running.
+                    """
+                }
+                return "Cannot reach gateway at localhost:\(port); ensure the gateway is running."
+            case .networkConnectionLost:
+                return "Gateway connection dropped; gateway likely restarted—retry."
+            case .timedOut:
+                return "Gateway request timed out; check gateway on localhost:\(port)."
+            case .notConnectedToInternet:
+                return "No network connectivity; cannot reach gateway."
+            default:
+                break
+            }
+        }
+
+        if nsError.domain == "Gateway", nsError.code == 5 {
+            let port = GatewayEnvironment.gatewayPort()
+            return "Gateway request timed out; check the gateway process on localhost:\(port)."
+        }
+
+        let detail = nsError.localizedDescription.isEmpty ? "unknown gateway error" : nsError.localizedDescription
+        let trimmed = detail.trimmingCharacters(in: .whitespacesAndNewlines)
+        if trimmed.lowercased().hasPrefix("gateway error:") { return trimmed }
+        return "Gateway error: \(trimmed)"
+    }
+
+    private func scheduleRecovery(reason: String) {
+        let now = Date()
+        if let last = self.lastRecoveryAt, now.timeIntervalSince(last) < 10 { return }
+        guard self.recoveryTask == nil else { return }
+        self.lastRecoveryAt = now
+
+        self.recoveryTask = Task { [weak self] in
+            guard let self else { return }
+            let mode = await MainActor.run { AppStateStore.shared.connectionMode }
+            guard mode != .unconfigured else {
+                self.recoveryTask = nil
+                return
+            }
+
+            let trimmedReason = reason.trimmingCharacters(in: .whitespacesAndNewlines)
+            let reasonText = trimmedReason.isEmpty ? "unknown" : trimmedReason
+            self.logger.info(
+                "control channel recovery starting " +
+                    "mode=\(String(describing: mode), privacy: .public) " +
+                    "reason=\(reasonText, privacy: .public)")
+            if mode == .local {
+                GatewayProcessManager.shared.setActive(true)
+            }
+            if mode == .remote {
+                do {
+                    let port = try await GatewayEndpointStore.shared.ensureRemoteControlTunnel()
+                    self.logger.info("control channel recovery ensured SSH tunnel port=\(port, privacy: .public)")
+                } catch {
+                    self.logger.error(
+                        "control channel recovery tunnel failed \(error.localizedDescription, privacy: .public)")
+                }
+            }
+
+            await self.refreshEndpoint(reason: "recovery:\(reasonText)")
+            if case .connected = self.state {
+                self.logger.info("control channel recovery finished")
+            } else if case let .degraded(message) = self.state {
+                self.logger.error("control channel recovery failed \(message, privacy: .public)")
+            }
+
+            self.recoveryTask = nil
+        }
+    }
+
+    private func establishGatewayConnection(timeoutMs: Int = 5000) async throws {
+        try await GatewayConnection.shared.refresh()
+        let ok = try await GatewayConnection.shared.healthOK(timeoutMs: timeoutMs)
+        if ok == false {
+            throw NSError(
+                domain: "Gateway",
+                code: 0,
+                userInfo: [NSLocalizedDescriptionKey: "gateway health not ok"])
+        }
+        await self.refreshAuthSourceLabel()
+    }
+
+    private func refreshAuthSourceLabel() async {
+        let isRemote = CommandResolver.connectionModeIsRemote()
+        let authSource = await GatewayConnection.shared.authSource()
+        self.authSourceLabel = Self.formatAuthSource(authSource, isRemote: isRemote)
+    }
+
+    private static func formatAuthSource(_ source: GatewayAuthSource?, isRemote: Bool) -> String? {
+        guard let source else { return nil }
+        switch source {
+        case .deviceToken:
+            return "Auth: device token (paired device)"
+        case .sharedToken:
+            return "Auth: shared token (\(isRemote ? "gateway.remote.token" : "gateway.auth.token"))"
+        case .password:
+            return "Auth: password (\(isRemote ? "gateway.remote.password" : "gateway.auth.password"))"
+        case .none:
+            return "Auth: none"
+        }
+    }
+
+    func sendSystemEvent(_ text: String, params: [String: AnyHashable] = [:]) async throws {
+        var merged = params
+        merged["text"] = AnyHashable(text)
+        _ = try await self.request(method: "system-event", params: merged)
+    }
+
+    private func startEventStream() {
+        self.eventTask?.cancel()
+        self.eventTask = Task { [weak self] in
+            guard let self else { return }
+            let stream = await GatewayConnection.shared.subscribe()
+            for await push in stream {
+                if Task.isCancelled { return }
+                await MainActor.run { [weak self] in
+                    self?.handle(push: push)
+                }
+            }
+        }
+    }
+
+    private func handle(push: GatewayPush) {
+        switch push {
+        case let .event(evt) where evt.event == "agent":
+            if let payload = evt.payload,
+               let agent = try? GatewayPayloadDecoding.decode(payload, as: ControlAgentEvent.self)
+            {
+                AgentEventStore.shared.append(agent)
+                self.routeWorkActivity(from: agent)
+            }
+        case let .event(evt) where evt.event == "heartbeat":
+            if let payload = evt.payload,
+               let heartbeat = try? GatewayPayloadDecoding.decode(payload, as: ControlHeartbeatEvent.self),
+               let data = try? JSONEncoder().encode(heartbeat)
+            {
+                NotificationCenter.default.post(name: .controlHeartbeat, object: data)
+            }
+        case let .event(evt) where evt.event == "shutdown":
+            self.state = .degraded("gateway shutdown")
+        case .snapshot:
+            self.state = .connected
+        default:
+            break
+        }
+    }
+
+    private func routeWorkActivity(from event: ControlAgentEvent) {
+        // We currently treat VoiceWake as the "main" session for UI purposes.
+        // In the future, the gateway can include a sessionKey to distinguish runs.
+        let sessionKey = (event.data["sessionKey"]?.value as? String) ?? "main"
+
+        switch event.stream.lowercased() {
+        case "job":
+            if let state = event.data["state"]?.value as? String {
+                WorkActivityStore.shared.handleJob(sessionKey: sessionKey, state: state)
+            }
+        case "tool":
+            let phase = event.data["phase"]?.value as? String ?? ""
+            let name = event.data["name"]?.value as? String
+            let meta = event.data["meta"]?.value as? String
+            let args = Self.bridgeToProtocolArgs(event.data["args"])
+            WorkActivityStore.shared.handleTool(
+                sessionKey: sessionKey,
+                phase: phase,
+                name: name,
+                meta: meta,
+                args: args)
+        default:
+            break
+        }
+    }
+
+    private static func bridgeToProtocolArgs(
+        _ value: OpenClawProtocol.AnyCodable?) -> [String: OpenClawProtocol.AnyCodable]?
+    {
+        guard let value else { return nil }
+        if let dict = value.value as? [String: OpenClawProtocol.AnyCodable] {
+            return dict
+        }
+        if let dict = value.value as? [String: OpenClawKit.AnyCodable],
+           let data = try? JSONEncoder().encode(dict),
+           let decoded = try? JSONDecoder().decode([String: OpenClawProtocol.AnyCodable].self, from: data)
+        {
+            return decoded
+        }
+        if let data = try? JSONEncoder().encode(value),
+           let decoded = try? JSONDecoder().decode([String: OpenClawProtocol.AnyCodable].self, from: data)
+        {
+            return decoded
+        }
+        return nil
+    }
+}
+
+extension Notification.Name {
+    static let controlHeartbeat = Notification.Name("openclaw.control.heartbeat")
+    static let controlAgentEvent = Notification.Name("openclaw.control.agent")
+}

openclaw/apps/macos/Sources/OpenClaw/CostUsageMenuView.swift

@@ -0,0 +1,99 @@
+import Charts
+import SwiftUI
+
+struct CostUsageHistoryMenuView: View {
+    let summary: GatewayCostUsageSummary
+    let width: CGFloat
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 10) {
+            self.header
+            self.chart
+            self.footer
+        }
+        .padding(.horizontal, 12)
+        .padding(.vertical, 10)
+        .frame(width: max(1, self.width), alignment: .leading)
+    }
+
+    private var header: some View {
+        let todayKey = CostUsageMenuDateParser.format(Date())
+        let todayEntry = self.summary.daily.first { $0.date == todayKey }
+        let todayCost = CostUsageFormatting.formatUsd(todayEntry?.totalCost) ?? "n/a"
+        let totalCost = CostUsageFormatting.formatUsd(self.summary.totals.totalCost) ?? "n/a"
+
+        return HStack(alignment: .firstTextBaseline, spacing: 12) {
+            VStack(alignment: .leading, spacing: 2) {
+                Text("Today")
+                    .font(.caption2)
+                    .foregroundStyle(.secondary)
+                Text(todayCost)
+                    .font(.system(size: 14, weight: .semibold))
+            }
+            VStack(alignment: .leading, spacing: 2) {
+                Text("Last \(self.summary.days)d")
+                    .font(.caption2)
+                    .foregroundStyle(.secondary)
+                Text(totalCost)
+                    .font(.system(size: 14, weight: .semibold))
+            }
+            Spacer()
+        }
+    }
+
+    private var chart: some View {
+        let entries = self.summary.daily.compactMap { entry -> (Date, Double)? in
+            guard let date = CostUsageMenuDateParser.parse(entry.date) else { return nil }
+            return (date, entry.totalCost)
+        }
+
+        return Chart(entries, id: \.0) { entry in
+            BarMark(
+                x: .value("Day", entry.0),
+                y: .value("Cost", entry.1))
+                .foregroundStyle(Color.accentColor)
+                .cornerRadius(3)
+        }
+        .chartXAxis {
+            AxisMarks(values: .stride(by: .day, count: 7)) {
+                AxisGridLine().foregroundStyle(.clear)
+                AxisValueLabel(format: .dateTime.month().day())
+            }
+        }
+        .chartYAxis {
+            AxisMarks(position: .leading) {
+                AxisGridLine()
+                AxisValueLabel()
+            }
+        }
+        .frame(height: 110)
+    }
+
+    private var footer: some View {
+        if self.summary.totals.missingCostEntries == 0 {
+            return AnyView(EmptyView())
+        }
+        return AnyView(
+            Text("Partial: \(self.summary.totals.missingCostEntries) entries missing cost")
+                .font(.caption2)
+                .foregroundStyle(.secondary))
+    }
+}
+
+private enum CostUsageMenuDateParser {
+    static let formatter: DateFormatter = {
+        let formatter = DateFormatter()
+        formatter.dateFormat = "yyyy-MM-dd"
+        formatter.locale = Locale(identifier: "en_US_POSIX")
+        formatter.timeZone = TimeZone.current
+        return formatter
+    }()
+
+    static func parse(_ value: String) -> Date? {
+        self.formatter.date(from: value)
+    }
+
+    static func format(_ date: Date) -> String {
+        self.formatter.string(from: date)
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/CritterIconRenderer.swift

@@ -0,0 +1,387 @@
+import AppKit
+
+enum CritterIconRenderer {
+    private static let size = NSSize(width: 18, height: 18)
+
+    struct Badge {
+        let symbolName: String
+        let prominence: IconState.BadgeProminence
+    }
+
+    private struct Canvas {
+        let w: CGFloat
+        let h: CGFloat
+        let stepX: CGFloat
+        let stepY: CGFloat
+        let snapX: (CGFloat) -> CGFloat
+        let snapY: (CGFloat) -> CGFloat
+        let context: CGContext
+    }
+
+    private struct Geometry {
+        let bodyRect: CGRect
+        let bodyCorner: CGFloat
+        let leftEarRect: CGRect
+        let rightEarRect: CGRect
+        let earCorner: CGFloat
+        let earW: CGFloat
+        let earH: CGFloat
+        let legW: CGFloat
+        let legH: CGFloat
+        let legSpacing: CGFloat
+        let legStartX: CGFloat
+        let legYBase: CGFloat
+        let legLift: CGFloat
+        let legHeightScale: CGFloat
+        let eyeW: CGFloat
+        let eyeY: CGFloat
+        let eyeOffset: CGFloat
+
+        init(canvas: Canvas, legWiggle: CGFloat, earWiggle: CGFloat, earScale: CGFloat) {
+            let w = canvas.w
+            let h = canvas.h
+            let snapX = canvas.snapX
+            let snapY = canvas.snapY
+
+            let bodyW = snapX(w * 0.78)
+            let bodyH = snapY(h * 0.58)
+            let bodyX = snapX((w - bodyW) / 2)
+            let bodyY = snapY(h * 0.36)
+            let bodyCorner = snapX(w * 0.09)
+
+            let earW = snapX(w * 0.22)
+            let earH = snapY(bodyH * 0.54 * earScale * (1 - 0.08 * abs(earWiggle)))
+            let earCorner = snapX(earW * 0.24)
+            let leftEarRect = CGRect(
+                x: snapX(bodyX - earW * 0.55 + earWiggle),
+                y: snapY(bodyY + bodyH * 0.08 + earWiggle * 0.4),
+                width: earW,
+                height: earH)
+            let rightEarRect = CGRect(
+                x: snapX(bodyX + bodyW - earW * 0.45 - earWiggle),
+                y: snapY(bodyY + bodyH * 0.08 - earWiggle * 0.4),
+                width: earW,
+                height: earH)
+
+            let legW = snapX(w * 0.11)
+            let legH = snapY(h * 0.26)
+            let legSpacing = snapX(w * 0.085)
+            let legsWidth = snapX(4 * legW + 3 * legSpacing)
+            let legStartX = snapX((w - legsWidth) / 2)
+            let legLift = snapY(legH * 0.35 * legWiggle)
+            let legYBase = snapY(bodyY - legH + h * 0.05)
+            let legHeightScale = 1 - 0.12 * legWiggle
+
+            let eyeW = snapX(bodyW * 0.2)
+            let eyeY = snapY(bodyY + bodyH * 0.56)
+            let eyeOffset = snapX(bodyW * 0.24)
+
+            self.bodyRect = CGRect(x: bodyX, y: bodyY, width: bodyW, height: bodyH)
+            self.bodyCorner = bodyCorner
+            self.leftEarRect = leftEarRect
+            self.rightEarRect = rightEarRect
+            self.earCorner = earCorner
+            self.earW = earW
+            self.earH = earH
+            self.legW = legW
+            self.legH = legH
+            self.legSpacing = legSpacing
+            self.legStartX = legStartX
+            self.legYBase = legYBase
+            self.legLift = legLift
+            self.legHeightScale = legHeightScale
+            self.eyeW = eyeW
+            self.eyeY = eyeY
+            self.eyeOffset = eyeOffset
+        }
+    }
+
+    private struct FaceOptions {
+        let blink: CGFloat
+        let earHoles: Bool
+        let earScale: CGFloat
+        let eyesClosedLines: Bool
+    }
+
+    static func makeIcon(
+        blink: CGFloat,
+        legWiggle: CGFloat = 0,
+        earWiggle: CGFloat = 0,
+        earScale: CGFloat = 1,
+        earHoles: Bool = false,
+        eyesClosedLines: Bool = false,
+        badge: Badge? = nil) -> NSImage
+    {
+        guard let rep = self.makeBitmapRep() else {
+            return NSImage(size: self.size)
+        }
+        rep.size = self.size
+
+        NSGraphicsContext.saveGraphicsState()
+        defer { NSGraphicsContext.restoreGraphicsState() }
+
+        guard let context = NSGraphicsContext(bitmapImageRep: rep) else {
+            return NSImage(size: self.size)
+        }
+        NSGraphicsContext.current = context
+        context.imageInterpolation = .none
+        context.cgContext.setShouldAntialias(false)
+
+        let canvas = self.makeCanvas(for: rep, context: context)
+        let geometry = Geometry(canvas: canvas, legWiggle: legWiggle, earWiggle: earWiggle, earScale: earScale)
+
+        self.drawBody(in: canvas, geometry: geometry)
+        let face = FaceOptions(
+            blink: blink,
+            earHoles: earHoles,
+            earScale: earScale,
+            eyesClosedLines: eyesClosedLines)
+        self.drawFace(in: canvas, geometry: geometry, options: face)
+
+        if let badge {
+            self.drawBadge(badge, canvas: canvas)
+        }
+
+        let image = NSImage(size: size)
+        image.addRepresentation(rep)
+        image.isTemplate = true
+        return image
+    }
+
+    private static func makeBitmapRep() -> NSBitmapImageRep? {
+        // Force a 36×36px backing store (2× for the 18pt logical canvas) so the menu bar icon stays crisp on Retina.
+        let pixelsWide = 36
+        let pixelsHigh = 36
+        return NSBitmapImageRep(
+            bitmapDataPlanes: nil,
+            pixelsWide: pixelsWide,
+            pixelsHigh: pixelsHigh,
+            bitsPerSample: 8,
+            samplesPerPixel: 4,
+            hasAlpha: true,
+            isPlanar: false,
+            colorSpaceName: .deviceRGB,
+            bitmapFormat: [],
+            bytesPerRow: 0,
+            bitsPerPixel: 0)
+    }
+
+    private static func makeCanvas(for rep: NSBitmapImageRep, context: NSGraphicsContext) -> Canvas {
+        let stepX = self.size.width / max(CGFloat(rep.pixelsWide), 1)
+        let stepY = self.size.height / max(CGFloat(rep.pixelsHigh), 1)
+        let snapX: (CGFloat) -> CGFloat = { ($0 / stepX).rounded() * stepX }
+        let snapY: (CGFloat) -> CGFloat = { ($0 / stepY).rounded() * stepY }
+
+        let w = snapX(size.width)
+        let h = snapY(size.height)
+
+        return Canvas(
+            w: w,
+            h: h,
+            stepX: stepX,
+            stepY: stepY,
+            snapX: snapX,
+            snapY: snapY,
+            context: context.cgContext)
+    }
+
+    private static func drawBody(in canvas: Canvas, geometry: Geometry) {
+        canvas.context.setFillColor(NSColor.labelColor.cgColor)
+
+        canvas.context.addPath(CGPath(
+            roundedRect: geometry.bodyRect,
+            cornerWidth: geometry.bodyCorner,
+            cornerHeight: geometry.bodyCorner,
+            transform: nil))
+        canvas.context.addPath(CGPath(
+            roundedRect: geometry.leftEarRect,
+            cornerWidth: geometry.earCorner,
+            cornerHeight: geometry.earCorner,
+            transform: nil))
+        canvas.context.addPath(CGPath(
+            roundedRect: geometry.rightEarRect,
+            cornerWidth: geometry.earCorner,
+            cornerHeight: geometry.earCorner,
+            transform: nil))
+
+        for i in 0..<4 {
+            let x = geometry.legStartX + CGFloat(i) * (geometry.legW + geometry.legSpacing)
+            let lift = i % 2 == 0 ? geometry.legLift : -geometry.legLift
+            let rect = CGRect(
+                x: x,
+                y: geometry.legYBase + lift,
+                width: geometry.legW,
+                height: geometry.legH * geometry.legHeightScale)
+            canvas.context.addPath(CGPath(
+                roundedRect: rect,
+                cornerWidth: geometry.legW * 0.34,
+                cornerHeight: geometry.legW * 0.34,
+                transform: nil))
+        }
+        canvas.context.fillPath()
+    }
+
+    private static func drawFace(
+        in canvas: Canvas,
+        geometry: Geometry,
+        options: FaceOptions)
+    {
+        canvas.context.saveGState()
+        canvas.context.setBlendMode(.clear)
+
+        let leftCenter = CGPoint(
+            x: canvas.snapX(canvas.w / 2 - geometry.eyeOffset),
+            y: canvas.snapY(geometry.eyeY))
+        let rightCenter = CGPoint(
+            x: canvas.snapX(canvas.w / 2 + geometry.eyeOffset),
+            y: canvas.snapY(geometry.eyeY))
+
+        if options.earHoles || options.earScale > 1.05 {
+            let holeW = canvas.snapX(geometry.earW * 0.6)
+            let holeH = canvas.snapY(geometry.earH * 0.46)
+            let holeCorner = canvas.snapX(holeW * 0.34)
+            let leftHoleRect = CGRect(
+                x: canvas.snapX(geometry.leftEarRect.midX - holeW / 2),
+                y: canvas.snapY(geometry.leftEarRect.midY - holeH / 2 + geometry.earH * 0.04),
+                width: holeW,
+                height: holeH)
+            let rightHoleRect = CGRect(
+                x: canvas.snapX(geometry.rightEarRect.midX - holeW / 2),
+                y: canvas.snapY(geometry.rightEarRect.midY - holeH / 2 + geometry.earH * 0.04),
+                width: holeW,
+                height: holeH)
+
+            canvas.context.addPath(CGPath(
+                roundedRect: leftHoleRect,
+                cornerWidth: holeCorner,
+                cornerHeight: holeCorner,
+                transform: nil))
+            canvas.context.addPath(CGPath(
+                roundedRect: rightHoleRect,
+                cornerWidth: holeCorner,
+                cornerHeight: holeCorner,
+                transform: nil))
+        }
+
+        if options.eyesClosedLines {
+            let lineW = canvas.snapX(geometry.eyeW * 0.95)
+            let lineH = canvas.snapY(max(canvas.stepY * 2, geometry.bodyRect.height * 0.06))
+            let corner = canvas.snapX(lineH * 0.6)
+            let leftRect = CGRect(
+                x: canvas.snapX(leftCenter.x - lineW / 2),
+                y: canvas.snapY(leftCenter.y - lineH / 2),
+                width: lineW,
+                height: lineH)
+            let rightRect = CGRect(
+                x: canvas.snapX(rightCenter.x - lineW / 2),
+                y: canvas.snapY(rightCenter.y - lineH / 2),
+                width: lineW,
+                height: lineH)
+            canvas.context.addPath(CGPath(
+                roundedRect: leftRect,
+                cornerWidth: corner,
+                cornerHeight: corner,
+                transform: nil))
+            canvas.context.addPath(CGPath(
+                roundedRect: rightRect,
+                cornerWidth: corner,
+                cornerHeight: corner,
+                transform: nil))
+        } else {
+            let eyeOpen = max(0.05, 1 - options.blink)
+            let eyeH = canvas.snapY(geometry.bodyRect.height * 0.26 * eyeOpen)
+
+            let left = CGMutablePath()
+            left.move(to: CGPoint(
+                x: canvas.snapX(leftCenter.x - geometry.eyeW / 2),
+                y: canvas.snapY(leftCenter.y - eyeH)))
+            left.addLine(to: CGPoint(
+                x: canvas.snapX(leftCenter.x + geometry.eyeW / 2),
+                y: canvas.snapY(leftCenter.y)))
+            left.addLine(to: CGPoint(
+                x: canvas.snapX(leftCenter.x - geometry.eyeW / 2),
+                y: canvas.snapY(leftCenter.y + eyeH)))
+            left.closeSubpath()
+
+            let right = CGMutablePath()
+            right.move(to: CGPoint(
+                x: canvas.snapX(rightCenter.x + geometry.eyeW / 2),
+                y: canvas.snapY(rightCenter.y - eyeH)))
+            right.addLine(to: CGPoint(
+                x: canvas.snapX(rightCenter.x - geometry.eyeW / 2),
+                y: canvas.snapY(rightCenter.y)))
+            right.addLine(to: CGPoint(
+                x: canvas.snapX(rightCenter.x + geometry.eyeW / 2),
+                y: canvas.snapY(rightCenter.y + eyeH)))
+            right.closeSubpath()
+
+            canvas.context.addPath(left)
+            canvas.context.addPath(right)
+        }
+
+        canvas.context.fillPath()
+        canvas.context.restoreGState()
+    }
+
+    private static func drawBadge(_ badge: Badge, canvas: Canvas) {
+        let strength: CGFloat = switch badge.prominence {
+        case .primary: 1.0
+        case .secondary: 0.58
+        case .overridden: 0.85
+        }
+
+        // Bigger, higher-contrast badge:
+        // - Increase diameter so tool activity is noticeable.
+        // - Draw a filled "puck", then knock out the symbol shape (transparent hole).
+        //   This reads better in template-rendered menu bar icons than tiny monochrome glyphs.
+        let diameter = canvas.snapX(canvas.w * 0.52 * (0.92 + 0.08 * strength)) // ~9–10pt on an 18pt canvas
+        let margin = canvas.snapX(max(0.45, canvas.w * 0.03))
+        let rect = CGRect(
+            x: canvas.snapX(canvas.w - diameter - margin),
+            y: canvas.snapY(margin),
+            width: diameter,
+            height: diameter)
+
+        canvas.context.saveGState()
+        canvas.context.setShouldAntialias(true)
+
+        // Clear the underlying pixels so the badge stays readable over the critter.
+        canvas.context.saveGState()
+        canvas.context.setBlendMode(.clear)
+        canvas.context.addEllipse(in: rect.insetBy(dx: -1.0, dy: -1.0))
+        canvas.context.fillPath()
+        canvas.context.restoreGState()
+
+        let fillAlpha: CGFloat = min(1.0, 0.36 + 0.24 * strength)
+        let strokeAlpha: CGFloat = min(1.0, 0.78 + 0.22 * strength)
+
+        canvas.context.setFillColor(NSColor.labelColor.withAlphaComponent(fillAlpha).cgColor)
+        canvas.context.addEllipse(in: rect)
+        canvas.context.fillPath()
+
+        canvas.context.setStrokeColor(NSColor.labelColor.withAlphaComponent(strokeAlpha).cgColor)
+        canvas.context.setLineWidth(max(1.25, canvas.snapX(canvas.w * 0.075)))
+        canvas.context.strokeEllipse(in: rect.insetBy(dx: 0.45, dy: 0.45))
+
+        if let base = NSImage(systemSymbolName: badge.symbolName, accessibilityDescription: nil) {
+            let pointSize = max(7.0, diameter * 0.82)
+            let config = NSImage.SymbolConfiguration(pointSize: pointSize, weight: .black)
+            let symbol = base.withSymbolConfiguration(config) ?? base
+            symbol.isTemplate = true
+
+            let symbolRect = rect.insetBy(dx: diameter * 0.17, dy: diameter * 0.17)
+            canvas.context.saveGState()
+            canvas.context.setBlendMode(.clear)
+            symbol.draw(
+                in: symbolRect,
+                from: .zero,
+                operation: .sourceOver,
+                fraction: 1,
+                respectFlipped: true,
+                hints: nil)
+            canvas.context.restoreGState()
+        }
+
+        canvas.context.restoreGState()
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/CritterStatusLabel+Behavior.swift

@@ -0,0 +1,305 @@
+import AppKit
+import SwiftUI
+
+extension CritterStatusLabel {
+    private var isWorkingNow: Bool {
+        self.iconState.isWorking || self.isWorking
+    }
+
+    private var effectiveAnimationsEnabled: Bool {
+        self.animationsEnabled && !self.isSleeping
+    }
+
+    var body: some View {
+        ZStack(alignment: .topTrailing) {
+            self.iconImage
+                .frame(width: 18, height: 18)
+                .rotationEffect(.degrees(self.wiggleAngle), anchor: .center)
+                .offset(x: self.wiggleOffset)
+                // Avoid Combine's TimerPublisher here: on macOS 26.2 we've seen crashes inside executor checks
+                // triggered by its callbacks. Drive periodic updates via a Swift-concurrency task instead.
+                .task(id: self.tickTaskID) {
+                    guard self.effectiveAnimationsEnabled, !self.earBoostActive else {
+                        await MainActor.run { self.resetMotion() }
+                        return
+                    }
+
+                    while !Task.isCancelled {
+                        let now = Date()
+                        await MainActor.run { self.tick(now) }
+                        try? await Task.sleep(nanoseconds: 350_000_000)
+                    }
+                }
+                .onChange(of: self.isPaused) { _, _ in self.resetMotion() }
+                .onChange(of: self.blinkTick) { _, _ in
+                    guard self.effectiveAnimationsEnabled, !self.earBoostActive else { return }
+                    self.blink()
+                }
+                .onChange(of: self.sendCelebrationTick) { _, _ in
+                    guard self.effectiveAnimationsEnabled, !self.earBoostActive else { return }
+                    self.wiggleLegs()
+                }
+                .onChange(of: self.animationsEnabled) { _, enabled in
+                    if enabled, !self.isSleeping {
+                        self.scheduleRandomTimers(from: Date())
+                    } else {
+                        self.resetMotion()
+                    }
+                }
+                .onChange(of: self.isSleeping) { _, _ in
+                    self.resetMotion()
+                }
+                .onChange(of: self.earBoostActive) { _, active in
+                    if active {
+                        self.resetMotion()
+                    } else if self.effectiveAnimationsEnabled {
+                        self.scheduleRandomTimers(from: Date())
+                    }
+                }
+
+            if self.gatewayNeedsAttention {
+                Circle()
+                    .fill(self.gatewayBadgeColor)
+                    .frame(width: 6, height: 6)
+                    .padding(1)
+            }
+        }
+        .frame(width: 18, height: 18)
+    }
+
+    private var tickTaskID: Int {
+        // Ensure SwiftUI restarts (and cancels) the task when these change.
+        (self.effectiveAnimationsEnabled ? 1 : 0) | (self.earBoostActive ? 2 : 0)
+    }
+
+    private func tick(_ now: Date) {
+        guard self.effectiveAnimationsEnabled, !self.earBoostActive else {
+            self.resetMotion()
+            return
+        }
+
+        if now >= self.nextBlink {
+            self.blink()
+            self.nextBlink = now.addingTimeInterval(Double.random(in: 3.5...8.5))
+        }
+
+        if now >= self.nextWiggle {
+            self.wiggle()
+            self.nextWiggle = now.addingTimeInterval(Double.random(in: 6.5...14))
+        }
+
+        if now >= self.nextLegWiggle {
+            self.wiggleLegs()
+            self.nextLegWiggle = now.addingTimeInterval(Double.random(in: 5.0...11.0))
+        }
+
+        if now >= self.nextEarWiggle {
+            self.wiggleEars()
+            self.nextEarWiggle = now.addingTimeInterval(Double.random(in: 7.0...14.0))
+        }
+
+        if self.isWorkingNow {
+            self.scurry()
+        }
+    }
+
+    private var iconImage: Image {
+        let badge: CritterIconRenderer.Badge? = if let prominence = self.iconState.badgeProminence, !self.isPaused {
+            CritterIconRenderer.Badge(
+                symbolName: self.iconState.badgeSymbolName,
+                prominence: prominence)
+        } else {
+            nil
+        }
+
+        if self.isPaused {
+            return Image(nsImage: CritterIconRenderer.makeIcon(blink: 0, badge: nil))
+        }
+
+        if self.isSleeping {
+            return Image(nsImage: CritterIconRenderer.makeIcon(blink: 1, eyesClosedLines: true, badge: nil))
+        }
+
+        return Image(nsImage: CritterIconRenderer.makeIcon(
+            blink: self.blinkAmount,
+            legWiggle: max(self.legWiggle, self.isWorkingNow ? 0.6 : 0),
+            earWiggle: self.earWiggle,
+            earScale: self.earBoostActive ? 1.9 : 1.0,
+            earHoles: self.earBoostActive,
+            badge: badge))
+    }
+
+    private func resetMotion() {
+        self.blinkAmount = 0
+        self.wiggleAngle = 0
+        self.wiggleOffset = 0
+        self.legWiggle = 0
+        self.earWiggle = 0
+    }
+
+    private func blink() {
+        withAnimation(.easeInOut(duration: 0.08)) { self.blinkAmount = 1 }
+        Task { @MainActor in
+            try? await Task.sleep(nanoseconds: 160_000_000)
+            withAnimation(.easeOut(duration: 0.12)) { self.blinkAmount = 0 }
+        }
+    }
+
+    private func wiggle() {
+        let targetAngle = Double.random(in: -4.5...4.5)
+        let targetOffset = CGFloat.random(in: -0.5...0.5)
+        withAnimation(.interpolatingSpring(stiffness: 220, damping: 18)) {
+            self.wiggleAngle = targetAngle
+            self.wiggleOffset = targetOffset
+        }
+        Task { @MainActor in
+            try? await Task.sleep(nanoseconds: 360_000_000)
+            withAnimation(.interpolatingSpring(stiffness: 220, damping: 18)) {
+                self.wiggleAngle = 0
+                self.wiggleOffset = 0
+            }
+        }
+    }
+
+    private func wiggleLegs() {
+        let target = CGFloat.random(in: 0.35...0.9)
+        withAnimation(.easeInOut(duration: 0.14)) {
+            self.legWiggle = target
+        }
+        Task { @MainActor in
+            try? await Task.sleep(nanoseconds: 220_000_000)
+            withAnimation(.easeOut(duration: 0.18)) { self.legWiggle = 0 }
+        }
+    }
+
+    private func scurry() {
+        let target = CGFloat.random(in: 0.7...1.0)
+        withAnimation(.easeInOut(duration: 0.12)) {
+            self.legWiggle = target
+            self.wiggleOffset = CGFloat.random(in: -0.6...0.6)
+        }
+        Task { @MainActor in
+            try? await Task.sleep(nanoseconds: 180_000_000)
+            withAnimation(.easeOut(duration: 0.16)) {
+                self.legWiggle = 0.25
+                self.wiggleOffset = 0
+            }
+        }
+    }
+
+    private func wiggleEars() {
+        let target = CGFloat.random(in: -1.2...1.2)
+        withAnimation(.interpolatingSpring(stiffness: 260, damping: 19)) {
+            self.earWiggle = target
+        }
+        Task { @MainActor in
+            try? await Task.sleep(nanoseconds: 320_000_000)
+            withAnimation(.interpolatingSpring(stiffness: 260, damping: 19)) {
+                self.earWiggle = 0
+            }
+        }
+    }
+
+    private func scheduleRandomTimers(from date: Date) {
+        self.nextBlink = date.addingTimeInterval(Double.random(in: 3.5...8.5))
+        self.nextWiggle = date.addingTimeInterval(Double.random(in: 6.5...14))
+        self.nextLegWiggle = date.addingTimeInterval(Double.random(in: 5.0...11.0))
+        self.nextEarWiggle = date.addingTimeInterval(Double.random(in: 7.0...14.0))
+    }
+
+    private var gatewayNeedsAttention: Bool {
+        if self.isSleeping { return false }
+        switch self.gatewayStatus {
+        case .failed, .stopped:
+            return !self.isPaused
+        case .starting, .running, .attachedExisting:
+            return false
+        }
+    }
+
+    private var gatewayBadgeColor: Color {
+        switch self.gatewayStatus {
+        case .failed: .red
+        case .stopped: .orange
+        default: .clear
+        }
+    }
+}
+
+#if DEBUG
+@MainActor
+extension CritterStatusLabel {
+    static func exerciseForTesting() async {
+        var label = CritterStatusLabel(
+            isPaused: false,
+            isSleeping: false,
+            isWorking: true,
+            earBoostActive: false,
+            blinkTick: 1,
+            sendCelebrationTick: 1,
+            gatewayStatus: .running(details: nil),
+            animationsEnabled: true,
+            iconState: .workingMain(.tool(.bash)))
+
+        _ = label.body
+        _ = label.iconImage
+        _ = label.tickTaskID
+        label.tick(Date())
+        label.resetMotion()
+        label.blink()
+        label.wiggle()
+        label.wiggleLegs()
+        label.wiggleEars()
+        label.scurry()
+        label.scheduleRandomTimers(from: Date())
+        _ = label.gatewayNeedsAttention
+        _ = label.gatewayBadgeColor
+
+        label.isPaused = true
+        _ = label.iconImage
+
+        label.isPaused = false
+        label.isSleeping = true
+        _ = label.iconImage
+
+        label.isSleeping = false
+        label.iconState = .idle
+        _ = label.iconImage
+
+        let failed = CritterStatusLabel(
+            isPaused: false,
+            isSleeping: false,
+            isWorking: false,
+            earBoostActive: false,
+            blinkTick: 0,
+            sendCelebrationTick: 0,
+            gatewayStatus: .failed("boom"),
+            animationsEnabled: false,
+            iconState: .idle)
+        _ = failed.gatewayNeedsAttention
+        _ = failed.gatewayBadgeColor
+
+        let stopped = CritterStatusLabel(
+            isPaused: false,
+            isSleeping: false,
+            isWorking: false,
+            earBoostActive: false,
+            blinkTick: 0,
+            sendCelebrationTick: 0,
+            gatewayStatus: .stopped,
+            animationsEnabled: false,
+            iconState: .idle)
+        _ = stopped.gatewayNeedsAttention
+        _ = stopped.gatewayBadgeColor
+
+        _ = CritterIconRenderer.makeIcon(
+            blink: 0.6,
+            legWiggle: 0.8,
+            earWiggle: 0.4,
+            earScale: 1.4,
+            earHoles: true,
+            eyesClosedLines: true,
+            badge: .init(symbolName: "gearshape.fill", prominence: .secondary))
+    }
+}
+#endif

openclaw/apps/macos/Sources/OpenClaw/CritterStatusLabel.swift

@@ -0,0 +1,23 @@
+import SwiftUI
+
+struct CritterStatusLabel: View {
+    var isPaused: Bool
+    var isSleeping: Bool
+    var isWorking: Bool
+    var earBoostActive: Bool
+    var blinkTick: Int
+    var sendCelebrationTick: Int
+    var gatewayStatus: GatewayProcessManager.Status
+    var animationsEnabled: Bool
+    var iconState: IconState
+
+    @State var blinkAmount: CGFloat = 0
+    @State var nextBlink = Date().addingTimeInterval(Double.random(in: 3.5...8.5))
+    @State var wiggleAngle: Double = 0
+    @State var wiggleOffset: CGFloat = 0
+    @State var nextWiggle = Date().addingTimeInterval(Double.random(in: 6.5...14))
+    @State var legWiggle: CGFloat = 0
+    @State var nextLegWiggle = Date().addingTimeInterval(Double.random(in: 5.0...11.0))
+    @State var earWiggle: CGFloat = 0
+    @State var nextEarWiggle = Date().addingTimeInterval(Double.random(in: 7.0...14.0))
+}

openclaw/apps/macos/Sources/OpenClaw/CronJobEditor+Helpers.swift

@@ -0,0 +1,271 @@
+import Foundation
+import OpenClawProtocol
+import SwiftUI
+
+extension CronJobEditor {
+    func gridLabel(_ text: String) -> some View {
+        Text(text)
+            .foregroundStyle(.secondary)
+            .frame(width: self.labelColumnWidth, alignment: .leading)
+    }
+
+    func hydrateFromJob() {
+        guard let job else { return }
+        self.name = job.name
+        self.description = job.description ?? ""
+        self.agentId = job.agentId ?? ""
+        self.enabled = job.enabled
+        self.deleteAfterRun = job.deleteAfterRun ?? false
+        self.sessionTarget = job.sessionTarget
+        self.wakeMode = job.wakeMode
+
+        switch job.schedule {
+        case let .at(at):
+            self.scheduleKind = .at
+            if let date = CronSchedule.parseAtDate(at) {
+                self.atDate = date
+            }
+        case let .every(everyMs, _):
+            self.scheduleKind = .every
+            self.everyText = self.formatDuration(ms: everyMs)
+        case let .cron(expr, tz):
+            self.scheduleKind = .cron
+            self.cronExpr = expr
+            self.cronTz = tz ?? ""
+        }
+
+        switch job.payload {
+        case let .systemEvent(text):
+            self.payloadKind = .systemEvent
+            self.systemEventText = text
+        case let .agentTurn(message, thinking, timeoutSeconds, _, _, _, _):
+            self.payloadKind = .agentTurn
+            self.agentMessage = message
+            self.thinking = thinking ?? ""
+            self.timeoutSeconds = timeoutSeconds.map(String.init) ?? ""
+        }
+
+        if let delivery = job.delivery {
+            self.deliveryMode = delivery.mode == .announce ? .announce : .none
+            let trimmed = (delivery.channel ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
+            self.channel = trimmed.isEmpty ? "last" : trimmed
+            self.to = delivery.to ?? ""
+            self.bestEffortDeliver = delivery.bestEffort ?? false
+        } else if self.sessionTarget == .isolated {
+            self.deliveryMode = .announce
+        }
+    }
+
+    func save() {
+        do {
+            self.error = nil
+            let payload = try self.buildPayload()
+            self.onSave(payload)
+        } catch {
+            self.error = error.localizedDescription
+        }
+    }
+
+    func buildPayload() throws -> [String: AnyCodable] {
+        let name = try self.requireName()
+        let description = self.trimmed(self.description)
+        let agentId = self.trimmed(self.agentId)
+        let schedule = try self.buildSchedule()
+        let payload = try self.buildSelectedPayload()
+
+        try self.validateSessionTarget(payload)
+        try self.validatePayloadRequiredFields(payload)
+
+        var root: [String: Any] = [
+            "name": name,
+            "enabled": self.enabled,
+            "schedule": schedule,
+            "sessionTarget": self.sessionTarget.rawValue,
+            "wakeMode": self.wakeMode.rawValue,
+            "payload": payload,
+        ]
+        self.applyDeleteAfterRun(to: &root)
+        if !description.isEmpty { root["description"] = description }
+        if !agentId.isEmpty {
+            root["agentId"] = agentId
+        } else if self.job?.agentId != nil {
+            root["agentId"] = NSNull()
+        }
+
+        if self.sessionTarget == .isolated {
+            root["delivery"] = self.buildDelivery()
+        }
+
+        return root.mapValues { AnyCodable($0) }
+    }
+
+    func buildDelivery() -> [String: Any] {
+        let mode = self.deliveryMode == .announce ? "announce" : "none"
+        var delivery: [String: Any] = ["mode": mode]
+        if self.deliveryMode == .announce {
+            let trimmed = self.channel.trimmingCharacters(in: .whitespacesAndNewlines)
+            delivery["channel"] = trimmed.isEmpty ? "last" : trimmed
+            let to = self.to.trimmingCharacters(in: .whitespacesAndNewlines)
+            if !to.isEmpty { delivery["to"] = to }
+            if self.bestEffortDeliver {
+                delivery["bestEffort"] = true
+            } else if self.job?.delivery?.bestEffort == true {
+                delivery["bestEffort"] = false
+            }
+        }
+        return delivery
+    }
+
+    func trimmed(_ value: String) -> String {
+        value.trimmingCharacters(in: .whitespacesAndNewlines)
+    }
+
+    func requireName() throws -> String {
+        let name = self.trimmed(self.name)
+        if name.isEmpty {
+            throw NSError(
+                domain: "Cron",
+                code: 0,
+                userInfo: [NSLocalizedDescriptionKey: "Name is required."])
+        }
+        return name
+    }
+
+    func buildSchedule() throws -> [String: Any] {
+        switch self.scheduleKind {
+        case .at:
+            return ["kind": "at", "at": CronSchedule.formatIsoDate(self.atDate)]
+        case .every:
+            guard let ms = Self.parseDurationMs(self.everyText) else {
+                throw NSError(
+                    domain: "Cron",
+                    code: 0,
+                    userInfo: [NSLocalizedDescriptionKey: "Invalid every duration (use 10m, 1h, 1d)."])
+            }
+            return ["kind": "every", "everyMs": ms]
+        case .cron:
+            let expr = self.trimmed(self.cronExpr)
+            if expr.isEmpty {
+                throw NSError(
+                    domain: "Cron",
+                    code: 0,
+                    userInfo: [NSLocalizedDescriptionKey: "Cron expression is required."])
+            }
+            let tz = self.trimmed(self.cronTz)
+            if tz.isEmpty {
+                return ["kind": "cron", "expr": expr]
+            }
+            return ["kind": "cron", "expr": expr, "tz": tz]
+        }
+    }
+
+    func buildSelectedPayload() throws -> [String: Any] {
+        if self.sessionTarget == .isolated { return self.buildAgentTurnPayload() }
+        switch self.payloadKind {
+        case .systemEvent:
+            let text = self.trimmed(self.systemEventText)
+            return ["kind": "systemEvent", "text": text]
+        case .agentTurn:
+            return self.buildAgentTurnPayload()
+        }
+    }
+
+    func validateSessionTarget(_ payload: [String: Any]) throws {
+        if self.sessionTarget == .main, payload["kind"] as? String == "agentTurn" {
+            throw NSError(
+                domain: "Cron",
+                code: 0,
+                userInfo: [
+                    NSLocalizedDescriptionKey:
+                        "Main session jobs require systemEvent payloads (switch Session target to isolated).",
+                ])
+        }
+
+        if self.sessionTarget == .isolated, payload["kind"] as? String == "systemEvent" {
+            throw NSError(
+                domain: "Cron",
+                code: 0,
+                userInfo: [NSLocalizedDescriptionKey: "Isolated jobs require agentTurn payloads."])
+        }
+    }
+
+    func validatePayloadRequiredFields(_ payload: [String: Any]) throws {
+        if payload["kind"] as? String == "systemEvent" {
+            if (payload["text"] as? String ?? "").isEmpty {
+                throw NSError(
+                    domain: "Cron",
+                    code: 0,
+                    userInfo: [NSLocalizedDescriptionKey: "System event text is required."])
+            }
+        }
+        if payload["kind"] as? String == "agentTurn" {
+            if (payload["message"] as? String ?? "").isEmpty {
+                throw NSError(
+                    domain: "Cron",
+                    code: 0,
+                    userInfo: [NSLocalizedDescriptionKey: "Agent message is required."])
+            }
+        }
+    }
+
+    func applyDeleteAfterRun(
+        to root: inout [String: Any],
+        scheduleKind: ScheduleKind? = nil,
+        deleteAfterRun: Bool? = nil)
+    {
+        let resolvedSchedule = scheduleKind ?? self.scheduleKind
+        let resolvedDelete = deleteAfterRun ?? self.deleteAfterRun
+        if resolvedSchedule == .at {
+            root["deleteAfterRun"] = resolvedDelete
+        } else if self.job?.deleteAfterRun != nil {
+            root["deleteAfterRun"] = false
+        }
+    }
+
+    func buildAgentTurnPayload() -> [String: Any] {
+        let msg = self.agentMessage.trimmingCharacters(in: .whitespacesAndNewlines)
+        var payload: [String: Any] = ["kind": "agentTurn", "message": msg]
+        let thinking = self.thinking.trimmingCharacters(in: .whitespacesAndNewlines)
+        if !thinking.isEmpty { payload["thinking"] = thinking }
+        if let n = Int(self.timeoutSeconds), n > 0 { payload["timeoutSeconds"] = n }
+        return payload
+    }
+
+    static func parseDurationMs(_ input: String) -> Int? {
+        let raw = input.trimmingCharacters(in: .whitespacesAndNewlines)
+        if raw.isEmpty { return nil }
+
+        let rx = try? NSRegularExpression(pattern: "^(\\d+(?:\\.\\d+)?)(ms|s|m|h|d)$", options: [.caseInsensitive])
+        guard let match = rx?.firstMatch(in: raw, range: NSRange(location: 0, length: raw.utf16.count)) else {
+            return nil
+        }
+        func group(_ idx: Int) -> String {
+            let range = match.range(at: idx)
+            guard let r = Range(range, in: raw) else { return "" }
+            return String(raw[r])
+        }
+        let n = Double(group(1)) ?? 0
+        if !n.isFinite || n <= 0 { return nil }
+        let unit = group(2).lowercased()
+        let factor: Double = switch unit {
+        case "ms": 1
+        case "s": 1000
+        case "m": 60000
+        case "h": 3_600_000
+        default: 86_400_000
+        }
+        return Int(floor(n * factor))
+    }
+
+    func formatDuration(ms: Int) -> String {
+        if ms < 1000 { return "\(ms)ms" }
+        let s = Double(ms) / 1000.0
+        if s < 60 { return "\(Int(round(s)))s" }
+        let m = s / 60.0
+        if m < 60 { return "\(Int(round(m)))m" }
+        let h = m / 60.0
+        if h < 48 { return "\(Int(round(h)))h" }
+        let d = h / 24.0
+        return "\(Int(round(d)))d"
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/CronJobEditor+Testing.swift

@@ -0,0 +1,28 @@
+#if DEBUG
+extension CronJobEditor {
+    mutating func exerciseForTesting() {
+        self.name = "Test job"
+        self.description = "Test description"
+        self.agentId = "ops"
+        self.enabled = true
+        self.sessionTarget = .isolated
+        self.wakeMode = .now
+
+        self.scheduleKind = .every
+        self.everyText = "15m"
+
+        self.payloadKind = .agentTurn
+        self.agentMessage = "Run diagnostic"
+        self.deliveryMode = .announce
+        self.channel = "last"
+        self.to = "+15551230000"
+        self.thinking = "low"
+        self.timeoutSeconds = "90"
+        self.bestEffortDeliver = true
+
+        _ = self.buildAgentTurnPayload()
+        _ = try? self.buildPayload()
+        _ = self.formatDuration(ms: 45000)
+    }
+}
+#endif

openclaw/apps/macos/Sources/OpenClaw/CronJobEditor.swift

@@ -0,0 +1,362 @@
+import Observation
+import OpenClawProtocol
+import SwiftUI
+
+struct CronJobEditor: View {
+    let job: CronJob?
+    @Binding var isSaving: Bool
+    @Binding var error: String?
+    @Bindable var channelsStore: ChannelsStore
+    let onCancel: () -> Void
+    let onSave: ([String: AnyCodable]) -> Void
+
+    let labelColumnWidth: CGFloat = 160
+    static let introText =
+        "Create a schedule that wakes OpenClaw via the Gateway. "
+            + "Use an isolated session for agent turns so your main chat stays clean."
+    static let sessionTargetNote =
+        "Main jobs post a system event into the current main session. "
+            + "Isolated jobs run OpenClaw in a dedicated session and can announce results to a channel."
+    static let scheduleKindNote =
+        "“At” runs once, “Every” repeats with a duration, “Cron” uses a 5-field Unix expression."
+    static let isolatedPayloadNote =
+        "Isolated jobs always run an agent turn. Announce sends a short summary to a channel."
+    static let mainPayloadNote =
+        "System events are injected into the current main session. Agent turns require an isolated session target."
+
+    @State var name: String = ""
+    @State var description: String = ""
+    @State var agentId: String = ""
+    @State var enabled: Bool = true
+    @State var sessionTarget: CronSessionTarget = .main
+    @State var wakeMode: CronWakeMode = .now
+    @State var deleteAfterRun: Bool = false
+
+    enum ScheduleKind: String, CaseIterable, Identifiable { case at, every, cron; var id: String {
+        rawValue
+    } }
+    @State var scheduleKind: ScheduleKind = .every
+    @State var atDate: Date = .init().addingTimeInterval(60 * 5)
+    @State var everyText: String = "1h"
+    @State var cronExpr: String = "0 9 * * 3"
+    @State var cronTz: String = ""
+
+    enum PayloadKind: String, CaseIterable, Identifiable { case systemEvent, agentTurn; var id: String {
+        rawValue
+    } }
+    @State var payloadKind: PayloadKind = .systemEvent
+    @State var systemEventText: String = ""
+    @State var agentMessage: String = ""
+    enum DeliveryChoice: String, CaseIterable, Identifiable { case announce, none; var id: String {
+        rawValue
+    } }
+    @State var deliveryMode: DeliveryChoice = .announce
+    @State var channel: String = "last"
+    @State var to: String = ""
+    @State var thinking: String = ""
+    @State var timeoutSeconds: String = ""
+    @State var bestEffortDeliver: Bool = false
+
+    var channelOptions: [String] {
+        let ordered = self.channelsStore.orderedChannelIds()
+        var options = ["last"] + ordered
+        let trimmed = self.channel.trimmingCharacters(in: .whitespacesAndNewlines)
+        if !trimmed.isEmpty, !options.contains(trimmed) {
+            options.append(trimmed)
+        }
+        var seen = Set<String>()
+        return options.filter { seen.insert($0).inserted }
+    }
+
+    func channelLabel(for id: String) -> String {
+        if id == "last" { return "last" }
+        return self.channelsStore.resolveChannelLabel(id)
+    }
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 16) {
+            VStack(alignment: .leading, spacing: 6) {
+                Text(self.job == nil ? "New cron job" : "Edit cron job")
+                    .font(.title3.weight(.semibold))
+                Text(Self.introText)
+                    .font(.callout)
+                    .foregroundStyle(.secondary)
+                    .fixedSize(horizontal: false, vertical: true)
+            }
+
+            ScrollView(.vertical) {
+                VStack(alignment: .leading, spacing: 14) {
+                    GroupBox("Basics") {
+                        Grid(alignment: .leadingFirstTextBaseline, horizontalSpacing: 14, verticalSpacing: 10) {
+                            GridRow {
+                                self.gridLabel("Name")
+                                TextField("Required (e.g. “Daily summary”)", text: self.$name)
+                                    .textFieldStyle(.roundedBorder)
+                                    .frame(maxWidth: .infinity)
+                            }
+                            GridRow {
+                                self.gridLabel("Description")
+                                TextField("Optional notes", text: self.$description)
+                                    .textFieldStyle(.roundedBorder)
+                                    .frame(maxWidth: .infinity)
+                            }
+                            GridRow {
+                                self.gridLabel("Agent ID")
+                                TextField("Optional (default agent)", text: self.$agentId)
+                                    .textFieldStyle(.roundedBorder)
+                                    .frame(maxWidth: .infinity)
+                            }
+                            GridRow {
+                                self.gridLabel("Enabled")
+                                Toggle("", isOn: self.$enabled)
+                                    .labelsHidden()
+                                    .toggleStyle(.switch)
+                            }
+                            GridRow {
+                                self.gridLabel("Session target")
+                                Picker("", selection: self.$sessionTarget) {
+                                    Text("main").tag(CronSessionTarget.main)
+                                    Text("isolated").tag(CronSessionTarget.isolated)
+                                }
+                                .labelsHidden()
+                                .pickerStyle(.segmented)
+                                .frame(maxWidth: .infinity, alignment: .leading)
+                            }
+                            GridRow {
+                                self.gridLabel("Wake mode")
+                                Picker("", selection: self.$wakeMode) {
+                                    Text("now").tag(CronWakeMode.now)
+                                    Text("next-heartbeat").tag(CronWakeMode.nextHeartbeat)
+                                }
+                                .labelsHidden()
+                                .pickerStyle(.segmented)
+                                .frame(maxWidth: .infinity, alignment: .leading)
+                            }
+                            GridRow {
+                                Color.clear
+                                    .frame(width: self.labelColumnWidth, height: 1)
+                                Text(
+                                    Self.sessionTargetNote)
+                                    .font(.footnote)
+                                    .foregroundStyle(.secondary)
+                                    .frame(maxWidth: .infinity, alignment: .leading)
+                            }
+                        }
+                    }
+
+                    GroupBox("Schedule") {
+                        Grid(alignment: .leadingFirstTextBaseline, horizontalSpacing: 14, verticalSpacing: 10) {
+                            GridRow {
+                                self.gridLabel("Kind")
+                                Picker("", selection: self.$scheduleKind) {
+                                    Text("at").tag(ScheduleKind.at)
+                                    Text("every").tag(ScheduleKind.every)
+                                    Text("cron").tag(ScheduleKind.cron)
+                                }
+                                .labelsHidden()
+                                .pickerStyle(.segmented)
+                                .frame(maxWidth: .infinity)
+                            }
+                            GridRow {
+                                Color.clear
+                                    .frame(width: self.labelColumnWidth, height: 1)
+                                Text(
+                                    Self.scheduleKindNote)
+                                    .font(.footnote)
+                                    .foregroundStyle(.secondary)
+                                    .frame(maxWidth: .infinity, alignment: .leading)
+                            }
+
+                            switch self.scheduleKind {
+                            case .at:
+                                GridRow {
+                                    self.gridLabel("At")
+                                    DatePicker(
+                                        "",
+                                        selection: self.$atDate,
+                                        displayedComponents: [.date, .hourAndMinute])
+                                        .labelsHidden()
+                                        .frame(maxWidth: .infinity, alignment: .leading)
+                                }
+                                GridRow {
+                                    self.gridLabel("Auto-delete")
+                                    Toggle("Delete after successful run", isOn: self.$deleteAfterRun)
+                                        .toggleStyle(.switch)
+                                }
+                            case .every:
+                                GridRow {
+                                    self.gridLabel("Every")
+                                    TextField("10m, 1h, 1d", text: self.$everyText)
+                                        .textFieldStyle(.roundedBorder)
+                                        .frame(maxWidth: .infinity)
+                                }
+                            case .cron:
+                                GridRow {
+                                    self.gridLabel("Expression")
+                                    TextField("e.g. 0 9 * * 3", text: self.$cronExpr)
+                                        .textFieldStyle(.roundedBorder)
+                                        .frame(maxWidth: .infinity)
+                                }
+                                GridRow {
+                                    self.gridLabel("Timezone")
+                                    TextField("Optional (e.g. America/Los_Angeles)", text: self.$cronTz)
+                                        .textFieldStyle(.roundedBorder)
+                                        .frame(maxWidth: .infinity)
+                                }
+                            }
+                        }
+                    }
+
+                    GroupBox("Payload") {
+                        VStack(alignment: .leading, spacing: 10) {
+                            if self.sessionTarget == .isolated {
+                                Text(Self.isolatedPayloadNote)
+                                    .font(.footnote)
+                                    .foregroundStyle(.secondary)
+                                    .fixedSize(horizontal: false, vertical: true)
+                                self.agentTurnEditor
+                            } else {
+                                Grid(alignment: .leadingFirstTextBaseline, horizontalSpacing: 14, verticalSpacing: 10) {
+                                    GridRow {
+                                        self.gridLabel("Kind")
+                                        Picker("", selection: self.$payloadKind) {
+                                            Text("systemEvent").tag(PayloadKind.systemEvent)
+                                            Text("agentTurn").tag(PayloadKind.agentTurn)
+                                        }
+                                        .labelsHidden()
+                                        .pickerStyle(.segmented)
+                                        .frame(maxWidth: .infinity)
+                                    }
+                                    GridRow {
+                                        Color.clear
+                                            .frame(width: self.labelColumnWidth, height: 1)
+                                        Text(
+                                            Self.mainPayloadNote)
+                                            .font(.footnote)
+                                            .foregroundStyle(.secondary)
+                                            .frame(maxWidth: .infinity, alignment: .leading)
+                                    }
+                                }
+
+                                switch self.payloadKind {
+                                case .systemEvent:
+                                    TextField("System event text", text: self.$systemEventText, axis: .vertical)
+                                        .textFieldStyle(.roundedBorder)
+                                        .lineLimit(3...7)
+                                        .frame(maxWidth: .infinity)
+                                case .agentTurn:
+                                    self.agentTurnEditor
+                                }
+                            }
+                        }
+                    }
+                }
+                .frame(maxWidth: .infinity, alignment: .leading)
+                .padding(.vertical, 2)
+            }
+
+            if let error, !error.isEmpty {
+                Text(error)
+                    .font(.footnote)
+                    .foregroundStyle(.red)
+                    .fixedSize(horizontal: false, vertical: true)
+            }
+
+            HStack {
+                Button("Cancel") { self.onCancel() }
+                    .keyboardShortcut(.cancelAction)
+                    .buttonStyle(.bordered)
+                Spacer()
+                Button {
+                    self.save()
+                } label: {
+                    if self.isSaving {
+                        ProgressView().controlSize(.small)
+                    } else {
+                        Text("Save")
+                    }
+                }
+                .keyboardShortcut(.defaultAction)
+                .buttonStyle(.borderedProminent)
+                .disabled(self.isSaving)
+            }
+        }
+        .padding(24)
+        .frame(minWidth: 720, minHeight: 640)
+        .onAppear { self.hydrateFromJob() }
+        .onChange(of: self.payloadKind) { _, newValue in
+            if newValue == .agentTurn, self.sessionTarget == .main {
+                self.sessionTarget = .isolated
+            }
+        }
+        .onChange(of: self.sessionTarget) { _, newValue in
+            if newValue == .isolated {
+                self.payloadKind = .agentTurn
+            } else if newValue == .main, self.payloadKind == .agentTurn {
+                self.payloadKind = .systemEvent
+            }
+        }
+    }
+
+    var agentTurnEditor: some View {
+        VStack(alignment: .leading, spacing: 10) {
+            Grid(alignment: .leadingFirstTextBaseline, horizontalSpacing: 14, verticalSpacing: 10) {
+                GridRow {
+                    self.gridLabel("Message")
+                    TextField("What should OpenClaw do?", text: self.$agentMessage, axis: .vertical)
+                        .textFieldStyle(.roundedBorder)
+                        .lineLimit(3...7)
+                        .frame(maxWidth: .infinity)
+                }
+                GridRow {
+                    self.gridLabel("Thinking")
+                    TextField("Optional (e.g. low)", text: self.$thinking)
+                        .textFieldStyle(.roundedBorder)
+                        .frame(maxWidth: .infinity)
+                }
+                GridRow {
+                    self.gridLabel("Timeout")
+                    TextField("Seconds (optional)", text: self.$timeoutSeconds)
+                        .textFieldStyle(.roundedBorder)
+                        .frame(width: 180, alignment: .leading)
+                }
+                GridRow {
+                    self.gridLabel("Delivery")
+                    Picker("", selection: self.$deliveryMode) {
+                        Text("Announce summary").tag(DeliveryChoice.announce)
+                        Text("None").tag(DeliveryChoice.none)
+                    }
+                    .labelsHidden()
+                    .pickerStyle(.segmented)
+                }
+            }
+
+            if self.deliveryMode == .announce {
+                Grid(alignment: .leadingFirstTextBaseline, horizontalSpacing: 14, verticalSpacing: 10) {
+                    GridRow {
+                        self.gridLabel("Channel")
+                        Picker("", selection: self.$channel) {
+                            ForEach(self.channelOptions, id: \.self) { channel in
+                                Text(self.channelLabel(for: channel)).tag(channel)
+                            }
+                        }
+                        .labelsHidden()
+                        .pickerStyle(.segmented)
+                        .frame(maxWidth: .infinity, alignment: .leading)
+                    }
+                    GridRow {
+                        self.gridLabel("To")
+                        TextField("Optional override (phone number / chat id / Discord channel)", text: self.$to)
+                            .textFieldStyle(.roundedBorder)
+                            .frame(maxWidth: .infinity)
+                    }
+                    GridRow {
+                        self.gridLabel("Best-effort")
+                        Toggle("Do not fail the job if announce fails", isOn: self.$bestEffortDeliver)
+                            .toggleStyle(.switch)
+                    }
+                }
+            }
+        }
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/CronJobsStore.swift

@@ -0,0 +1,200 @@
+import Foundation
+import Observation
+import OpenClawKit
+import OpenClawProtocol
+import OSLog
+
+@MainActor
+@Observable
+final class CronJobsStore {
+    static let shared = CronJobsStore()
+
+    var jobs: [CronJob] = []
+    var selectedJobId: String?
+    var runEntries: [CronRunLogEntry] = []
+
+    var schedulerEnabled: Bool?
+    var schedulerStorePath: String?
+    var schedulerNextWakeAtMs: Int?
+
+    var isLoadingJobs = false
+    var isLoadingRuns = false
+    var lastError: String?
+    var statusMessage: String?
+
+    private let logger = Logger(subsystem: "ai.openclaw", category: "cron.ui")
+    private var refreshTask: Task<Void, Never>?
+    private var runsTask: Task<Void, Never>?
+    private var eventTask: Task<Void, Never>?
+    private var pollTask: Task<Void, Never>?
+
+    private let interval: TimeInterval = 30
+    private let isPreview: Bool
+
+    init(isPreview: Bool = ProcessInfo.processInfo.isPreview) {
+        self.isPreview = isPreview
+    }
+
+    func start() {
+        guard !self.isPreview else { return }
+        guard self.eventTask == nil else { return }
+        self.startGatewaySubscription()
+        self.pollTask = Task.detached { [weak self] in
+            guard let self else { return }
+            await self.refreshJobs()
+            while !Task.isCancelled {
+                try? await Task.sleep(nanoseconds: UInt64(self.interval * 1_000_000_000))
+                await self.refreshJobs()
+            }
+        }
+    }
+
+    func stop() {
+        self.refreshTask?.cancel()
+        self.refreshTask = nil
+        self.runsTask?.cancel()
+        self.runsTask = nil
+        self.eventTask?.cancel()
+        self.eventTask = nil
+        self.pollTask?.cancel()
+        self.pollTask = nil
+    }
+
+    func refreshJobs() async {
+        guard !self.isLoadingJobs else { return }
+        self.isLoadingJobs = true
+        self.lastError = nil
+        self.statusMessage = nil
+        defer { self.isLoadingJobs = false }
+
+        do {
+            if let status = try? await GatewayConnection.shared.cronStatus() {
+                self.schedulerEnabled = status.enabled
+                self.schedulerStorePath = status.storePath
+                self.schedulerNextWakeAtMs = status.nextWakeAtMs
+            }
+            self.jobs = try await GatewayConnection.shared.cronList(includeDisabled: true)
+            if self.jobs.isEmpty {
+                self.statusMessage = "No cron jobs yet."
+            }
+        } catch {
+            self.logger.error("cron.list failed \(error.localizedDescription, privacy: .public)")
+            self.lastError = error.localizedDescription
+        }
+    }
+
+    func refreshRuns(jobId: String, limit: Int = 200) async {
+        guard !self.isLoadingRuns else { return }
+        self.isLoadingRuns = true
+        defer { self.isLoadingRuns = false }
+
+        do {
+            self.runEntries = try await GatewayConnection.shared.cronRuns(jobId: jobId, limit: limit)
+        } catch {
+            self.logger.error("cron.runs failed \(error.localizedDescription, privacy: .public)")
+            self.lastError = error.localizedDescription
+        }
+    }
+
+    func runJob(id: String, force: Bool = true) async {
+        do {
+            try await GatewayConnection.shared.cronRun(jobId: id, force: force)
+        } catch {
+            self.lastError = error.localizedDescription
+        }
+    }
+
+    func removeJob(id: String) async {
+        do {
+            try await GatewayConnection.shared.cronRemove(jobId: id)
+            await self.refreshJobs()
+            if self.selectedJobId == id {
+                self.selectedJobId = nil
+                self.runEntries = []
+            }
+        } catch {
+            self.lastError = error.localizedDescription
+        }
+    }
+
+    func setJobEnabled(id: String, enabled: Bool) async {
+        do {
+            try await GatewayConnection.shared.cronUpdate(
+                jobId: id,
+                patch: ["enabled": AnyCodable(enabled)])
+            await self.refreshJobs()
+        } catch {
+            self.lastError = error.localizedDescription
+        }
+    }
+
+    func upsertJob(
+        id: String?,
+        payload: [String: AnyCodable]) async throws
+    {
+        if let id {
+            try await GatewayConnection.shared.cronUpdate(jobId: id, patch: payload)
+        } else {
+            try await GatewayConnection.shared.cronAdd(payload: payload)
+        }
+        await self.refreshJobs()
+    }
+
+    // MARK: - Gateway events
+
+    private func startGatewaySubscription() {
+        self.eventTask?.cancel()
+        self.eventTask = Task { [weak self] in
+            guard let self else { return }
+            let stream = await GatewayConnection.shared.subscribe()
+            for await push in stream {
+                if Task.isCancelled { return }
+                await MainActor.run { [weak self] in
+                    self?.handle(push: push)
+                }
+            }
+        }
+    }
+
+    private func handle(push: GatewayPush) {
+        switch push {
+        case let .event(evt) where evt.event == "cron":
+            guard let payload = evt.payload else { return }
+            if let cronEvt = try? GatewayPayloadDecoding.decode(payload, as: CronEvent.self) {
+                self.handle(cronEvent: cronEvt)
+            }
+        case .seqGap:
+            self.scheduleRefresh()
+        default:
+            break
+        }
+    }
+
+    private func handle(cronEvent evt: CronEvent) {
+        // Keep UI in sync with the gateway scheduler.
+        self.scheduleRefresh(delayMs: 250)
+        if evt.action == "finished", let selected = self.selectedJobId, selected == evt.jobId {
+            self.scheduleRunsRefresh(jobId: selected, delayMs: 200)
+        }
+    }
+
+    private func scheduleRefresh(delayMs: Int = 250) {
+        self.refreshTask?.cancel()
+        self.refreshTask = Task { [weak self] in
+            guard let self else { return }
+            try? await Task.sleep(nanoseconds: UInt64(delayMs) * 1_000_000)
+            await self.refreshJobs()
+        }
+    }
+
+    private func scheduleRunsRefresh(jobId: String, delayMs: Int = 200) {
+        self.runsTask?.cancel()
+        self.runsTask = Task { [weak self] in
+            guard let self else { return }
+            try? await Task.sleep(nanoseconds: UInt64(delayMs) * 1_000_000)
+            await self.refreshRuns(jobId: jobId)
+        }
+    }
+
+    // MARK: - (no additional RPC helpers)
+}

openclaw/apps/macos/Sources/OpenClaw/CronModels.swift

@@ -0,0 +1,271 @@
+import Foundation
+
+enum CronSessionTarget: String, CaseIterable, Identifiable, Codable {
+    case main
+    case isolated
+
+    var id: String {
+        self.rawValue
+    }
+}
+
+enum CronWakeMode: String, CaseIterable, Identifiable, Codable {
+    case now
+    case nextHeartbeat = "next-heartbeat"
+
+    var id: String {
+        self.rawValue
+    }
+}
+
+enum CronDeliveryMode: String, CaseIterable, Identifiable, Codable {
+    case none
+    case announce
+    case webhook
+
+    var id: String {
+        self.rawValue
+    }
+}
+
+struct CronDelivery: Codable, Equatable {
+    var mode: CronDeliveryMode
+    var channel: String?
+    var to: String?
+    var bestEffort: Bool?
+}
+
+enum CronSchedule: Codable, Equatable {
+    case at(at: String)
+    case every(everyMs: Int, anchorMs: Int?)
+    case cron(expr: String, tz: String?)
+
+    enum CodingKeys: String, CodingKey { case kind, at, atMs, everyMs, anchorMs, expr, tz }
+
+    var kind: String {
+        switch self {
+        case .at: "at"
+        case .every: "every"
+        case .cron: "cron"
+        }
+    }
+
+    init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        let kind = try container.decode(String.self, forKey: .kind)
+        switch kind {
+        case "at":
+            if let at = try container.decodeIfPresent(String.self, forKey: .at),
+               !at.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
+            {
+                self = .at(at: at)
+                return
+            }
+            if let atMs = try container.decodeIfPresent(Int.self, forKey: .atMs) {
+                let date = Date(timeIntervalSince1970: TimeInterval(atMs) / 1000)
+                self = .at(at: Self.formatIsoDate(date))
+                return
+            }
+            throw DecodingError.dataCorruptedError(
+                forKey: .at,
+                in: container,
+                debugDescription: "Missing schedule.at")
+        case "every":
+            self = try .every(
+                everyMs: container.decode(Int.self, forKey: .everyMs),
+                anchorMs: container.decodeIfPresent(Int.self, forKey: .anchorMs))
+        case "cron":
+            self = try .cron(
+                expr: container.decode(String.self, forKey: .expr),
+                tz: container.decodeIfPresent(String.self, forKey: .tz))
+        default:
+            throw DecodingError.dataCorruptedError(
+                forKey: .kind,
+                in: container,
+                debugDescription: "Unknown schedule kind: \(kind)")
+        }
+    }
+
+    func encode(to encoder: Encoder) throws {
+        var container = encoder.container(keyedBy: CodingKeys.self)
+        try container.encode(self.kind, forKey: .kind)
+        switch self {
+        case let .at(at):
+            try container.encode(at, forKey: .at)
+        case let .every(everyMs, anchorMs):
+            try container.encode(everyMs, forKey: .everyMs)
+            try container.encodeIfPresent(anchorMs, forKey: .anchorMs)
+        case let .cron(expr, tz):
+            try container.encode(expr, forKey: .expr)
+            try container.encodeIfPresent(tz, forKey: .tz)
+        }
+    }
+
+    static func parseAtDate(_ value: String) -> Date? {
+        let trimmed = value.trimmingCharacters(in: .whitespacesAndNewlines)
+        if trimmed.isEmpty { return nil }
+        if let date = makeIsoFormatter(withFractional: true).date(from: trimmed) { return date }
+        return self.makeIsoFormatter(withFractional: false).date(from: trimmed)
+    }
+
+    static func formatIsoDate(_ date: Date) -> String {
+        self.makeIsoFormatter(withFractional: false).string(from: date)
+    }
+
+    private static func makeIsoFormatter(withFractional: Bool) -> ISO8601DateFormatter {
+        let formatter = ISO8601DateFormatter()
+        formatter.formatOptions = withFractional
+            ? [.withInternetDateTime, .withFractionalSeconds]
+            : [.withInternetDateTime]
+        return formatter
+    }
+}
+
+enum CronPayload: Codable, Equatable {
+    case systemEvent(text: String)
+    case agentTurn(
+        message: String,
+        thinking: String?,
+        timeoutSeconds: Int?,
+        deliver: Bool?,
+        channel: String?,
+        to: String?,
+        bestEffortDeliver: Bool?)
+
+    enum CodingKeys: String, CodingKey {
+        case kind, text, message, thinking, timeoutSeconds, deliver, channel, provider, to, bestEffortDeliver
+    }
+
+    var kind: String {
+        switch self {
+        case .systemEvent: "systemEvent"
+        case .agentTurn: "agentTurn"
+        }
+    }
+
+    init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        let kind = try container.decode(String.self, forKey: .kind)
+        switch kind {
+        case "systemEvent":
+            self = try .systemEvent(text: container.decode(String.self, forKey: .text))
+        case "agentTurn":
+            self = try .agentTurn(
+                message: container.decode(String.self, forKey: .message),
+                thinking: container.decodeIfPresent(String.self, forKey: .thinking),
+                timeoutSeconds: container.decodeIfPresent(Int.self, forKey: .timeoutSeconds),
+                deliver: container.decodeIfPresent(Bool.self, forKey: .deliver),
+                channel: container.decodeIfPresent(String.self, forKey: .channel)
+                    ?? container.decodeIfPresent(String.self, forKey: .provider),
+                to: container.decodeIfPresent(String.self, forKey: .to),
+                bestEffortDeliver: container.decodeIfPresent(Bool.self, forKey: .bestEffortDeliver))
+        default:
+            throw DecodingError.dataCorruptedError(
+                forKey: .kind,
+                in: container,
+                debugDescription: "Unknown payload kind: \(kind)")
+        }
+    }
+
+    func encode(to encoder: Encoder) throws {
+        var container = encoder.container(keyedBy: CodingKeys.self)
+        try container.encode(self.kind, forKey: .kind)
+        switch self {
+        case let .systemEvent(text):
+            try container.encode(text, forKey: .text)
+        case let .agentTurn(message, thinking, timeoutSeconds, deliver, channel, to, bestEffortDeliver):
+            try container.encode(message, forKey: .message)
+            try container.encodeIfPresent(thinking, forKey: .thinking)
+            try container.encodeIfPresent(timeoutSeconds, forKey: .timeoutSeconds)
+            try container.encodeIfPresent(deliver, forKey: .deliver)
+            try container.encodeIfPresent(channel, forKey: .channel)
+            try container.encodeIfPresent(to, forKey: .to)
+            try container.encodeIfPresent(bestEffortDeliver, forKey: .bestEffortDeliver)
+        }
+    }
+}
+
+struct CronJobState: Codable, Equatable {
+    var nextRunAtMs: Int?
+    var runningAtMs: Int?
+    var lastRunAtMs: Int?
+    var lastStatus: String?
+    var lastError: String?
+    var lastDurationMs: Int?
+}
+
+struct CronJob: Identifiable, Codable, Equatable {
+    let id: String
+    let agentId: String?
+    var name: String
+    var description: String?
+    var enabled: Bool
+    var deleteAfterRun: Bool?
+    let createdAtMs: Int
+    let updatedAtMs: Int
+    let schedule: CronSchedule
+    let sessionTarget: CronSessionTarget
+    let wakeMode: CronWakeMode
+    let payload: CronPayload
+    let delivery: CronDelivery?
+    let state: CronJobState
+
+    var displayName: String {
+        let trimmed = self.name.trimmingCharacters(in: .whitespacesAndNewlines)
+        return trimmed.isEmpty ? "Untitled job" : trimmed
+    }
+
+    var nextRunDate: Date? {
+        guard let ms = self.state.nextRunAtMs else { return nil }
+        return Date(timeIntervalSince1970: TimeInterval(ms) / 1000)
+    }
+
+    var lastRunDate: Date? {
+        guard let ms = self.state.lastRunAtMs else { return nil }
+        return Date(timeIntervalSince1970: TimeInterval(ms) / 1000)
+    }
+}
+
+struct CronEvent: Codable, Sendable {
+    let jobId: String
+    let action: String
+    let runAtMs: Int?
+    let durationMs: Int?
+    let status: String?
+    let error: String?
+    let summary: String?
+    let nextRunAtMs: Int?
+}
+
+struct CronRunLogEntry: Codable, Identifiable, Sendable {
+    var id: String {
+        "\(self.jobId)-\(self.ts)"
+    }
+
+    let ts: Int
+    let jobId: String
+    let action: String
+    let status: String?
+    let error: String?
+    let summary: String?
+    let runAtMs: Int?
+    let durationMs: Int?
+    let nextRunAtMs: Int?
+
+    var date: Date {
+        Date(timeIntervalSince1970: TimeInterval(self.ts) / 1000)
+    }
+
+    var runDate: Date? {
+        guard let runAtMs else { return nil }
+        return Date(timeIntervalSince1970: TimeInterval(runAtMs) / 1000)
+    }
+}
+
+struct CronListResponse: Codable {
+    let jobs: [CronJob]
+}
+
+struct CronRunsResponse: Codable {
+    let entries: [CronRunLogEntry]
+}

openclaw/apps/macos/Sources/OpenClaw/CronSettings+Actions.swift

@@ -0,0 +1,23 @@
+import Foundation
+import OpenClawProtocol
+
+extension CronSettings {
+    func save(payload: [String: AnyCodable]) async {
+        guard !self.isSaving else { return }
+        self.isSaving = true
+        self.editorError = nil
+        do {
+            try await self.store.upsertJob(id: self.editingJob?.id, payload: payload)
+            await MainActor.run {
+                self.isSaving = false
+                self.showEditor = false
+                self.editingJob = nil
+            }
+        } catch {
+            await MainActor.run {
+                self.isSaving = false
+                self.editorError = error.localizedDescription
+            }
+        }
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/CronSettings+Helpers.swift

@@ -0,0 +1,56 @@
+import SwiftUI
+
+extension CronSettings {
+    var selectedJob: CronJob? {
+        guard let id = self.store.selectedJobId else { return nil }
+        return self.store.jobs.first(where: { $0.id == id })
+    }
+
+    func statusTint(_ status: String?) -> Color {
+        switch (status ?? "").lowercased() {
+        case "ok": .green
+        case "error": .red
+        case "skipped": .orange
+        default: .secondary
+        }
+    }
+
+    func scheduleSummary(_ schedule: CronSchedule) -> String {
+        switch schedule {
+        case let .at(at):
+            if let date = CronSchedule.parseAtDate(at) {
+                return "at \(date.formatted(date: .abbreviated, time: .standard))"
+            }
+            return "at \(at)"
+        case let .every(everyMs, _):
+            return "every \(self.formatDuration(ms: everyMs))"
+        case let .cron(expr, tz):
+            if let tz, !tz.isEmpty { return "cron \(expr) (\(tz))" }
+            return "cron \(expr)"
+        }
+    }
+
+    func formatDuration(ms: Int) -> String {
+        if ms < 1000 { return "\(ms)ms" }
+        let s = Double(ms) / 1000.0
+        if s < 60 { return "\(Int(round(s)))s" }
+        let m = s / 60.0
+        if m < 60 { return "\(Int(round(m)))m" }
+        let h = m / 60.0
+        if h < 48 { return "\(Int(round(h)))h" }
+        let d = h / 24.0
+        return "\(Int(round(d)))d"
+    }
+
+    func nextRunLabel(_ date: Date, now: Date = .init()) -> String {
+        let delta = date.timeIntervalSince(now)
+        if delta <= 0 { return "due" }
+        if delta < 60 { return "in <1m" }
+        let minutes = Int(round(delta / 60))
+        if minutes < 60 { return "in \(minutes)m" }
+        let hours = Int(round(Double(minutes) / 60))
+        if hours < 48 { return "in \(hours)h" }
+        let days = Int(round(Double(hours) / 24))
+        return "in \(days)d"
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/CronSettings+Layout.swift

@@ -0,0 +1,179 @@
+import SwiftUI
+
+extension CronSettings {
+    var body: some View {
+        VStack(alignment: .leading, spacing: 12) {
+            self.header
+            self.schedulerBanner
+            self.content
+            Spacer(minLength: 0)
+        }
+        .onAppear {
+            self.store.start()
+            self.channelsStore.start()
+        }
+        .onDisappear {
+            self.store.stop()
+            self.channelsStore.stop()
+        }
+        .sheet(isPresented: self.$showEditor) {
+            CronJobEditor(
+                job: self.editingJob,
+                isSaving: self.$isSaving,
+                error: self.$editorError,
+                channelsStore: self.channelsStore,
+                onCancel: {
+                    self.showEditor = false
+                    self.editingJob = nil
+                },
+                onSave: { payload in
+                    Task {
+                        await self.save(payload: payload)
+                    }
+                })
+        }
+        .alert("Delete cron job?", isPresented: Binding(
+            get: { self.confirmDelete != nil },
+            set: { if !$0 { self.confirmDelete = nil } }))
+        {
+            Button("Cancel", role: .cancel) { self.confirmDelete = nil }
+            Button("Delete", role: .destructive) {
+                if let job = self.confirmDelete {
+                    Task { await self.store.removeJob(id: job.id) }
+                }
+                self.confirmDelete = nil
+            }
+        } message: {
+            if let job = self.confirmDelete {
+                Text(job.displayName)
+            }
+        }
+        .onChange(of: self.store.selectedJobId) { _, newValue in
+                guard let newValue else { return }
+                Task { await self.store.refreshRuns(jobId: newValue) }
+            }
+    }
+
+    var schedulerBanner: some View {
+        Group {
+            if self.store.schedulerEnabled == false {
+                VStack(alignment: .leading, spacing: 6) {
+                    HStack(spacing: 8) {
+                        Image(systemName: "exclamationmark.triangle.fill")
+                            .foregroundStyle(.orange)
+                        Text("Cron scheduler is disabled")
+                            .font(.headline)
+                        Spacer()
+                    }
+                    Text(
+                        "Jobs are saved, but they will not run automatically until `cron.enabled` is set to `true` " +
+                            "and the Gateway restarts.")
+                        .font(.footnote)
+                        .foregroundStyle(.secondary)
+                        .fixedSize(horizontal: false, vertical: true)
+                    if let storePath = self.store.schedulerStorePath, !storePath.isEmpty {
+                        Text(storePath)
+                            .font(.caption.monospaced())
+                            .foregroundStyle(.secondary)
+                            .textSelection(.enabled)
+                            .lineLimit(1)
+                            .truncationMode(.middle)
+                    }
+                }
+                .frame(maxWidth: .infinity, alignment: .leading)
+                .padding(10)
+                .background(Color.orange.opacity(0.10))
+                .cornerRadius(8)
+            }
+        }
+    }
+
+    var header: some View {
+        HStack(alignment: .top) {
+            VStack(alignment: .leading, spacing: 4) {
+                Text("Cron")
+                    .font(.headline)
+                Text("Manage Gateway cron jobs (main session vs isolated runs) and inspect run history.")
+                    .font(.footnote)
+                    .foregroundStyle(.secondary)
+                    .fixedSize(horizontal: false, vertical: true)
+            }
+            Spacer()
+            HStack(spacing: 8) {
+                Button {
+                    Task { await self.store.refreshJobs() }
+                } label: {
+                    Label("Refresh", systemImage: "arrow.clockwise")
+                }
+                .buttonStyle(.bordered)
+                .disabled(self.store.isLoadingJobs)
+
+                Button {
+                    self.editorError = nil
+                    self.editingJob = nil
+                    self.showEditor = true
+                } label: {
+                    Label("New Job", systemImage: "plus")
+                }
+                .buttonStyle(.borderedProminent)
+            }
+        }
+    }
+
+    var content: some View {
+        HStack(spacing: 12) {
+            VStack(alignment: .leading, spacing: 8) {
+                if let err = self.store.lastError {
+                    Text("Error: \(err)")
+                        .font(.footnote)
+                        .foregroundStyle(.red)
+                } else if let msg = self.store.statusMessage {
+                    Text(msg)
+                        .font(.footnote)
+                        .foregroundStyle(.secondary)
+                }
+
+                List(selection: self.$store.selectedJobId) {
+                    ForEach(self.store.jobs) { job in
+                        self.jobRow(job)
+                            .tag(job.id)
+                            .contextMenu { self.jobContextMenu(job) }
+                    }
+                }
+                .listStyle(.inset)
+            }
+            .frame(width: 250)
+
+            Divider()
+
+            self.detail
+                .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .topLeading)
+        }
+    }
+
+    @ViewBuilder
+    var detail: some View {
+        if let selected = self.selectedJob {
+            ScrollView(.vertical) {
+                VStack(alignment: .leading, spacing: 12) {
+                    self.detailHeader(selected)
+                    self.detailCard(selected)
+                    self.runHistoryCard(selected)
+                }
+                .frame(maxWidth: .infinity, alignment: .leading)
+                .padding(.top, 2)
+            }
+        } else {
+            VStack(alignment: .leading, spacing: 8) {
+                Text("Select a job to inspect details and run history.")
+                    .font(.callout)
+                    .foregroundStyle(.secondary)
+                Text("Tip: use ‘New Job’ to add one, or enable cron in your gateway config.")
+                    .font(.caption)
+                    .foregroundStyle(.tertiary)
+            }
+            .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .topLeading)
+            .padding(.top, 8)
+        }
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/CronSettings+Rows.swift

@@ -0,0 +1,246 @@
+import SwiftUI
+
+extension CronSettings {
+    func jobRow(_ job: CronJob) -> some View {
+        VStack(alignment: .leading, spacing: 6) {
+            HStack(spacing: 8) {
+                Text(job.displayName)
+                    .font(.subheadline.weight(.semibold))
+                    .lineLimit(1)
+                    .truncationMode(.middle)
+                Spacer()
+                if !job.enabled {
+                    StatusPill(text: "disabled", tint: .secondary)
+                } else if let next = job.nextRunDate {
+                    StatusPill(text: self.nextRunLabel(next), tint: .secondary)
+                } else {
+                    StatusPill(text: "no next run", tint: .secondary)
+                }
+            }
+            HStack(spacing: 6) {
+                StatusPill(text: job.sessionTarget.rawValue, tint: .secondary)
+                StatusPill(text: job.wakeMode.rawValue, tint: .secondary)
+                if let agentId = job.agentId, !agentId.isEmpty {
+                    StatusPill(text: "agent \(agentId)", tint: .secondary)
+                }
+                if let status = job.state.lastStatus {
+                    StatusPill(text: status, tint: status == "ok" ? .green : .orange)
+                }
+            }
+        }
+        .padding(.vertical, 6)
+    }
+
+    @ViewBuilder
+    func jobContextMenu(_ job: CronJob) -> some View {
+        Button("Run now") { Task { await self.store.runJob(id: job.id, force: true) } }
+        if job.sessionTarget == .isolated {
+            Button("Open transcript") {
+                WebChatManager.shared.show(sessionKey: "cron:\(job.id)")
+            }
+        }
+        Divider()
+        Button(job.enabled ? "Disable" : "Enable") {
+            Task { await self.store.setJobEnabled(id: job.id, enabled: !job.enabled) }
+        }
+        Button("Edit…") {
+            self.editingJob = job
+            self.editorError = nil
+            self.showEditor = true
+        }
+        Divider()
+        Button("Delete…", role: .destructive) {
+            self.confirmDelete = job
+        }
+    }
+
+    func detailHeader(_ job: CronJob) -> some View {
+        HStack(alignment: .center) {
+            VStack(alignment: .leading, spacing: 4) {
+                Text(job.displayName)
+                    .font(.title3.weight(.semibold))
+                Text(job.id)
+                    .font(.caption.monospaced())
+                    .foregroundStyle(.secondary)
+                    .textSelection(.enabled)
+                    .lineLimit(1)
+                    .truncationMode(.middle)
+            }
+            Spacer()
+            HStack(spacing: 8) {
+                Toggle("Enabled", isOn: Binding(
+                    get: { job.enabled },
+                    set: { enabled in Task { await self.store.setJobEnabled(id: job.id, enabled: enabled) } }))
+                    .toggleStyle(.switch)
+                    .labelsHidden()
+                Button("Run") { Task { await self.store.runJob(id: job.id, force: true) } }
+                    .buttonStyle(.borderedProminent)
+                if job.sessionTarget == .isolated {
+                    Button("Transcript") {
+                        WebChatManager.shared.show(sessionKey: "cron:\(job.id)")
+                    }
+                    .buttonStyle(.bordered)
+                }
+                Button("Edit") {
+                    self.editingJob = job
+                    self.editorError = nil
+                    self.showEditor = true
+                }
+                .buttonStyle(.bordered)
+            }
+        }
+    }
+
+    func detailCard(_ job: CronJob) -> some View {
+        VStack(alignment: .leading, spacing: 10) {
+            LabeledContent("Schedule") { Text(self.scheduleSummary(job.schedule)).font(.callout) }
+            if case .at = job.schedule, job.deleteAfterRun == true {
+                LabeledContent("Auto-delete") { Text("after success") }
+            }
+            if let desc = job.description, !desc.isEmpty {
+                LabeledContent("Description") { Text(desc).font(.callout) }
+            }
+            if let agentId = job.agentId, !agentId.isEmpty {
+                LabeledContent("Agent") { Text(agentId) }
+            }
+            LabeledContent("Session") { Text(job.sessionTarget.rawValue) }
+            LabeledContent("Wake") { Text(job.wakeMode.rawValue) }
+            LabeledContent("Next run") {
+                if let date = job.nextRunDate {
+                    Text(date.formatted(date: .abbreviated, time: .standard))
+                } else {
+                    Text("—").foregroundStyle(.secondary)
+                }
+            }
+            LabeledContent("Last run") {
+                if let date = job.lastRunDate {
+                    Text("\(date.formatted(date: .abbreviated, time: .standard)) · \(relativeAge(from: date))")
+                } else {
+                    Text("—").foregroundStyle(.secondary)
+                }
+            }
+            if let status = job.state.lastStatus {
+                LabeledContent("Last status") { Text(status) }
+            }
+            if let err = job.state.lastError, !err.isEmpty {
+                Text(err)
+                    .font(.footnote)
+                    .foregroundStyle(.orange)
+                    .textSelection(.enabled)
+            }
+            self.payloadSummary(job)
+        }
+        .frame(maxWidth: .infinity, alignment: .leading)
+        .padding(10)
+        .background(Color.secondary.opacity(0.06))
+        .cornerRadius(8)
+    }
+
+    func runHistoryCard(_ job: CronJob) -> some View {
+        VStack(alignment: .leading, spacing: 8) {
+            HStack {
+                Text("Run history")
+                    .font(.headline)
+                Spacer()
+                Button {
+                    Task { await self.store.refreshRuns(jobId: job.id) }
+                } label: {
+                    Label("Refresh", systemImage: "arrow.clockwise")
+                }
+                .buttonStyle(.bordered)
+                .disabled(self.store.isLoadingRuns)
+            }
+
+            if self.store.isLoadingRuns {
+                ProgressView().controlSize(.small)
+            }
+
+            if self.store.runEntries.isEmpty {
+                Text("No run log entries yet.")
+                    .font(.footnote)
+                    .foregroundStyle(.secondary)
+            } else {
+                VStack(alignment: .leading, spacing: 6) {
+                    ForEach(self.store.runEntries) { entry in
+                        self.runRow(entry)
+                    }
+                }
+            }
+        }
+        .frame(maxWidth: .infinity, alignment: .leading)
+        .padding(10)
+        .background(Color.secondary.opacity(0.06))
+        .cornerRadius(8)
+    }
+
+    func runRow(_ entry: CronRunLogEntry) -> some View {
+        VStack(alignment: .leading, spacing: 4) {
+            HStack(spacing: 8) {
+                StatusPill(text: entry.status ?? "unknown", tint: self.statusTint(entry.status))
+                Text(entry.date.formatted(date: .abbreviated, time: .standard))
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+                Spacer()
+                if let ms = entry.durationMs {
+                    Text("\(ms)ms")
+                        .font(.caption2.monospacedDigit())
+                        .foregroundStyle(.secondary)
+                }
+            }
+            if let summary = entry.summary, !summary.isEmpty {
+                Text(summary)
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+                    .textSelection(.enabled)
+                    .lineLimit(2)
+            }
+            if let error = entry.error, !error.isEmpty {
+                Text(error)
+                    .font(.caption)
+                    .foregroundStyle(.orange)
+                    .textSelection(.enabled)
+                    .lineLimit(2)
+            }
+        }
+        .padding(.vertical, 4)
+    }
+
+    func payloadSummary(_ job: CronJob) -> some View {
+        let payload = job.payload
+        return VStack(alignment: .leading, spacing: 6) {
+            Text("Payload")
+                .font(.caption.weight(.semibold))
+                .foregroundStyle(.secondary)
+            switch payload {
+            case let .systemEvent(text):
+                Text(text)
+                    .font(.callout)
+                    .textSelection(.enabled)
+            case let .agentTurn(message, thinking, timeoutSeconds, _, _, _, _):
+                VStack(alignment: .leading, spacing: 4) {
+                    Text(message)
+                        .font(.callout)
+                        .textSelection(.enabled)
+                    HStack(spacing: 8) {
+                        if let thinking, !thinking.isEmpty { StatusPill(text: "think \(thinking)", tint: .secondary) }
+                        if let timeoutSeconds { StatusPill(text: "\(timeoutSeconds)s", tint: .secondary) }
+                        if job.sessionTarget == .isolated {
+                            let delivery = job.delivery
+                            if let delivery {
+                                if delivery.mode == .announce {
+                                    StatusPill(text: "announce", tint: .secondary)
+                                    if let channel = delivery.channel, !channel.isEmpty {
+                                        StatusPill(text: channel, tint: .secondary)
+                                    }
+                                    if let to = delivery.to, !to.isEmpty { StatusPill(text: to, tint: .secondary) }
+                                } else {
+                                    StatusPill(text: "no delivery", tint: .secondary)
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/CronSettings+Testing.swift

@@ -0,0 +1,121 @@
+import SwiftUI
+
+#if DEBUG
+struct CronSettings_Previews: PreviewProvider {
+    static var previews: some View {
+        let store = CronJobsStore(isPreview: true)
+        store.jobs = [
+            CronJob(
+                id: "job-1",
+                agentId: "ops",
+                name: "Daily summary",
+                description: nil,
+                enabled: true,
+                deleteAfterRun: nil,
+                createdAtMs: 0,
+                updatedAtMs: 0,
+                schedule: .every(everyMs: 86_400_000, anchorMs: nil),
+                sessionTarget: .isolated,
+                wakeMode: .now,
+                payload: .agentTurn(
+                    message: "Summarize inbox",
+                    thinking: "low",
+                    timeoutSeconds: 600,
+                    deliver: nil,
+                    channel: nil,
+                    to: nil,
+                    bestEffortDeliver: nil),
+                delivery: CronDelivery(mode: .announce, channel: "last", to: nil, bestEffort: true),
+                state: CronJobState(
+                    nextRunAtMs: Int(Date().addingTimeInterval(3600).timeIntervalSince1970 * 1000),
+                    runningAtMs: nil,
+                    lastRunAtMs: nil,
+                    lastStatus: nil,
+                    lastError: nil,
+                    lastDurationMs: nil)),
+        ]
+        store.selectedJobId = "job-1"
+        store.runEntries = [
+            CronRunLogEntry(
+                ts: Int(Date().timeIntervalSince1970 * 1000),
+                jobId: "job-1",
+                action: "finished",
+                status: "ok",
+                error: nil,
+                summary: "All good.",
+                runAtMs: nil,
+                durationMs: 1234,
+                nextRunAtMs: nil),
+        ]
+        return CronSettings(store: store, channelsStore: ChannelsStore(isPreview: true))
+            .frame(width: SettingsTab.windowWidth, height: SettingsTab.windowHeight)
+    }
+}
+
+@MainActor
+extension CronSettings {
+    static func exerciseForTesting() {
+        let store = CronJobsStore(isPreview: true)
+        store.schedulerEnabled = false
+        store.schedulerStorePath = "/tmp/openclaw-cron-store.json"
+
+        let job = CronJob(
+            id: "job-1",
+            agentId: "ops",
+            name: "Daily summary",
+            description: "Summary job",
+            enabled: true,
+            deleteAfterRun: nil,
+            createdAtMs: 1_700_000_000_000,
+            updatedAtMs: 1_700_000_100_000,
+            schedule: .cron(expr: "0 8 * * *", tz: "UTC"),
+            sessionTarget: .isolated,
+            wakeMode: .nextHeartbeat,
+            payload: .agentTurn(
+                message: "Summarize",
+                thinking: "low",
+                timeoutSeconds: 120,
+                deliver: nil,
+                channel: nil,
+                to: nil,
+                bestEffortDeliver: nil),
+            delivery: CronDelivery(mode: .announce, channel: "whatsapp", to: "+15551234567", bestEffort: true),
+            state: CronJobState(
+                nextRunAtMs: 1_700_000_200_000,
+                runningAtMs: nil,
+                lastRunAtMs: 1_700_000_050_000,
+                lastStatus: "ok",
+                lastError: nil,
+                lastDurationMs: 1200))
+
+        let run = CronRunLogEntry(
+            ts: 1_700_000_050_000,
+            jobId: job.id,
+            action: "finished",
+            status: "ok",
+            error: nil,
+            summary: "done",
+            runAtMs: 1_700_000_050_000,
+            durationMs: 1200,
+            nextRunAtMs: 1_700_000_200_000)
+
+        store.jobs = [job]
+        store.selectedJobId = job.id
+        store.runEntries = [run]
+
+        let view = CronSettings(store: store, channelsStore: ChannelsStore(isPreview: true))
+        _ = view.body
+        _ = view.jobRow(job)
+        _ = view.jobContextMenu(job)
+        _ = view.detailHeader(job)
+        _ = view.detailCard(job)
+        _ = view.runHistoryCard(job)
+        _ = view.runRow(run)
+        _ = view.payloadSummary(job)
+        _ = view.scheduleSummary(job.schedule)
+        _ = view.statusTint(job.state.lastStatus)
+        _ = view.nextRunLabel(Date())
+        _ = view.formatDuration(ms: 1234)
+    }
+}
+#endif

openclaw/apps/macos/Sources/OpenClaw/CronSettings.swift

@@ -0,0 +1,17 @@
+import Observation
+import SwiftUI
+
+struct CronSettings: View {
+    @Bindable var store: CronJobsStore
+    @Bindable var channelsStore: ChannelsStore
+    @State var showEditor = false
+    @State var editingJob: CronJob?
+    @State var editorError: String?
+    @State var isSaving = false
+    @State var confirmDelete: CronJob?
+
+    init(store: CronJobsStore = .shared, channelsStore: ChannelsStore = .shared) {
+        self.store = store
+        self.channelsStore = channelsStore
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/DebugActions.swift

@@ -0,0 +1,265 @@
+import AppKit
+import Foundation
+import SwiftUI
+
+enum DebugActions {
+    private static let verboseDefaultsKey = "openclaw.debug.verboseMain"
+    private static let sessionMenuLimit = 12
+    private static let onboardingSeenKey = "openclaw.onboardingSeen"
+
+    @MainActor
+    static func openAgentEventsWindow() {
+        let window = NSWindow(
+            contentRect: NSRect(x: 0, y: 0, width: 620, height: 420),
+            styleMask: [.titled, .closable, .miniaturizable, .resizable],
+            backing: .buffered,
+            defer: false)
+        window.title = "Agent Events"
+        window.isReleasedWhenClosed = false
+        window.contentView = NSHostingView(rootView: AgentEventsWindow())
+        window.center()
+        window.makeKeyAndOrderFront(nil)
+        NSApp.activate(ignoringOtherApps: true)
+    }
+
+    @MainActor
+    static func openLog() {
+        let path = self.pinoLogPath()
+        let url = URL(fileURLWithPath: path)
+        guard FileManager().fileExists(atPath: path) else {
+            let alert = NSAlert()
+            alert.messageText = "Log file not found"
+            alert.informativeText = path
+            alert.runModal()
+            return
+        }
+        NSWorkspace.shared.activateFileViewerSelecting([url])
+    }
+
+    @MainActor
+    static func openConfigFolder() {
+        let url = OpenClawPaths.stateDirURL
+        NSWorkspace.shared.activateFileViewerSelecting([url])
+    }
+
+    @MainActor
+    static func openSessionStore() {
+        if AppStateStore.shared.connectionMode == .remote {
+            let alert = NSAlert()
+            alert.messageText = "Remote mode"
+            alert.informativeText = "Session store lives on the gateway host in remote mode."
+            alert.runModal()
+            return
+        }
+        let path = self.resolveSessionStorePath()
+        let url = URL(fileURLWithPath: path)
+        if FileManager().fileExists(atPath: path) {
+            NSWorkspace.shared.activateFileViewerSelecting([url])
+        } else {
+            NSWorkspace.shared.open(url.deletingLastPathComponent())
+        }
+    }
+
+    static func sendTestNotification() async {
+        _ = await NotificationManager().send(title: "OpenClaw", body: "Test notification", sound: nil)
+    }
+
+    static func sendDebugVoice() async -> Result<String, DebugActionError> {
+        let message = """
+        This is a debug test from the Mac app. Reply with "Debug test works (and a funny pun)" \
+        if you received that.
+        """
+        let result = await VoiceWakeForwarder.forward(transcript: message)
+        switch result {
+        case .success:
+            return .success("Sent. Await reply.")
+        case let .failure(error):
+            let detail = error.localizedDescription.trimmingCharacters(in: .whitespacesAndNewlines)
+            return .failure(.message("Send failed: \(detail)"))
+        }
+    }
+
+    static func restartGateway() {
+        Task { @MainActor in
+            switch AppStateStore.shared.connectionMode {
+            case .local:
+                GatewayProcessManager.shared.stop()
+                // Kick the control channel + health check so the UI recovers immediately.
+                await GatewayConnection.shared.shutdown()
+                try? await Task.sleep(nanoseconds: 300_000_000)
+                GatewayProcessManager.shared.setActive(true)
+                Task { try? await ControlChannel.shared.configure(mode: .local) }
+                Task { await HealthStore.shared.refresh(onDemand: true) }
+
+            case .remote:
+                // In remote mode, there is no local gateway to restart. "Restart Gateway" should
+                // reset the SSH control tunnel + reconnect so the menu recovers.
+                await RemoteTunnelManager.shared.stopAll()
+                await GatewayConnection.shared.shutdown()
+                do {
+                    _ = try await RemoteTunnelManager.shared.ensureControlTunnel()
+                    let settings = CommandResolver.connectionSettings()
+                    try await ControlChannel.shared.configure(mode: .remote(
+                        target: settings.target,
+                        identity: settings.identity))
+                } catch {
+                    // ControlChannel will surface a degraded state; also refresh health to update the menu text.
+                    Task { await HealthStore.shared.refresh(onDemand: true) }
+                }
+
+            case .unconfigured:
+                await GatewayConnection.shared.shutdown()
+                await ControlChannel.shared.disconnect()
+            }
+        }
+    }
+
+    static func resetGatewayTunnel() async -> Result<String, DebugActionError> {
+        let mode = CommandResolver.connectionSettings().mode
+        guard mode == .remote else {
+            return .failure(.message("Remote mode is not enabled."))
+        }
+        await RemoteTunnelManager.shared.stopAll()
+        await GatewayConnection.shared.shutdown()
+        do {
+            _ = try await RemoteTunnelManager.shared.ensureControlTunnel()
+            let settings = CommandResolver.connectionSettings()
+            try await ControlChannel.shared.configure(mode: .remote(
+                target: settings.target,
+                identity: settings.identity))
+            await HealthStore.shared.refresh(onDemand: true)
+            return .success("SSH tunnel reset.")
+        } catch {
+            Task { await HealthStore.shared.refresh(onDemand: true) }
+            return .failure(.message(error.localizedDescription))
+        }
+    }
+
+    static func pinoLogPath() -> String {
+        LogLocator.bestLogFile()?.path ?? LogLocator.launchdLogPath
+    }
+
+    @MainActor
+    static func runHealthCheckNow() async {
+        await HealthStore.shared.refresh(onDemand: true)
+    }
+
+    static func sendTestHeartbeat() async -> Result<ControlHeartbeatEvent?, Error> {
+        do {
+            _ = await GatewayConnection.shared.setHeartbeatsEnabled(true)
+            await ControlChannel.shared.configure()
+            let data = try await ControlChannel.shared.request(method: "last-heartbeat")
+            if let evt = try? JSONDecoder().decode(ControlHeartbeatEvent.self, from: data) {
+                return .success(evt)
+            }
+            return .success(nil)
+        } catch {
+            return .failure(error)
+        }
+    }
+
+    static var verboseLoggingEnabledMain: Bool {
+        UserDefaults.standard.bool(forKey: self.verboseDefaultsKey)
+    }
+
+    static func toggleVerboseLoggingMain() async -> Bool {
+        let newValue = !self.verboseLoggingEnabledMain
+        UserDefaults.standard.set(newValue, forKey: self.verboseDefaultsKey)
+        _ = try? await ControlChannel.shared.request(
+            method: "system-event",
+            params: ["text": AnyHashable("verbose-main:\(newValue ? "on" : "off")")])
+        return newValue
+    }
+
+    @MainActor
+    static func restartApp() {
+        let url = Bundle.main.bundleURL
+        let task = Process()
+        // Relaunch shortly after this instance exits so we get a true restart even in debug.
+        task.launchPath = "/bin/sh"
+        task.arguments = ["-c", "sleep 0.2; open -n \"$1\"", "_", url.path]
+        try? task.run()
+        NSApp.terminate(nil)
+    }
+
+    @MainActor
+    static func restartOnboarding() {
+        UserDefaults.standard.set(false, forKey: self.onboardingSeenKey)
+        UserDefaults.standard.set(0, forKey: onboardingVersionKey)
+        AppStateStore.shared.onboardingSeen = false
+        OnboardingController.shared.restart()
+    }
+
+    @MainActor
+    private static func resolveSessionStorePath() -> String {
+        let defaultPath = SessionLoader.defaultStorePath
+        let configURL = OpenClawPaths.configURL
+        guard
+            let data = try? Data(contentsOf: configURL),
+            let parsed = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
+            let session = parsed["session"] as? [String: Any],
+            let path = session["store"] as? String,
+            !path.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
+        else {
+            return defaultPath
+        }
+        return path
+    }
+
+    // MARK: - Sessions (thinking / verbose)
+
+    static func recentSessions(limit: Int = sessionMenuLimit) async -> [SessionRow] {
+        guard let snapshot = try? await SessionLoader.loadSnapshot(limit: limit) else { return [] }
+        return Array(snapshot.rows.prefix(limit))
+    }
+
+    static func updateSession(
+        key: String,
+        thinking: String?,
+        verbose: String?) async throws
+    {
+        var params: [String: AnyHashable] = ["key": AnyHashable(key)]
+        params["thinkingLevel"] = thinking.map(AnyHashable.init) ?? AnyHashable(NSNull())
+        params["verboseLevel"] = verbose.map(AnyHashable.init) ?? AnyHashable(NSNull())
+        _ = try await ControlChannel.shared.request(method: "sessions.patch", params: params)
+    }
+
+    // MARK: - Port diagnostics
+
+    typealias PortListener = PortGuardian.ReportListener
+    typealias PortReport = PortGuardian.PortReport
+
+    static func checkGatewayPorts() async -> [PortReport] {
+        let mode = CommandResolver.connectionSettings().mode
+        return await PortGuardian.shared.diagnose(mode: mode)
+    }
+
+    static func killProcess(_ pid: Int) async -> Result<Void, DebugActionError> {
+        let primary = await ShellExecutor.run(command: ["kill", "-TERM", "\(pid)"], cwd: nil, env: nil, timeout: 2)
+        if primary.ok { return .success(()) }
+        let force = await ShellExecutor.run(command: ["kill", "-KILL", "\(pid)"], cwd: nil, env: nil, timeout: 2)
+        if force.ok { return .success(()) }
+        let detail = force.message ?? primary.message ?? "kill failed"
+        return .failure(.message(detail))
+    }
+
+    @MainActor
+    static func openSessionStoreInCode() {
+        let path = SessionLoader.defaultStorePath
+        let proc = Process()
+        proc.launchPath = "/usr/bin/env"
+        proc.arguments = ["code", path]
+        try? proc.run()
+    }
+}
+
+enum DebugActionError: LocalizedError {
+    case message(String)
+
+    var errorDescription: String? {
+        switch self {
+        case let .message(text):
+            text
+        }
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/DeepLinks.swift

@@ -0,0 +1,199 @@
+import AppKit
+import Foundation
+import OpenClawKit
+import OSLog
+import Security
+
+private let deepLinkLogger = Logger(subsystem: "ai.openclaw", category: "DeepLink")
+
+enum DeepLinkAgentPolicy {
+    static let maxMessageChars = 20000
+    static let maxUnkeyedConfirmChars = 240
+
+    enum ValidationError: Error, Equatable, LocalizedError {
+        case messageTooLongForConfirmation(max: Int, actual: Int)
+
+        var errorDescription: String? {
+            switch self {
+            case let .messageTooLongForConfirmation(max, actual):
+                "Message is too long to confirm safely (\(actual) chars; max \(max) without key)."
+            }
+        }
+    }
+
+    static func validateMessageForHandle(message: String, allowUnattended: Bool) -> Result<Void, ValidationError> {
+        if !allowUnattended, message.count > self.maxUnkeyedConfirmChars {
+            return .failure(.messageTooLongForConfirmation(max: self.maxUnkeyedConfirmChars, actual: message.count))
+        }
+        return .success(())
+    }
+
+    static func effectiveDelivery(
+        link: AgentDeepLink,
+        allowUnattended: Bool) -> (deliver: Bool, to: String?, channel: GatewayAgentChannel)
+    {
+        if !allowUnattended {
+            // Without the unattended key, ignore delivery/routing knobs to reduce exfiltration risk.
+            return (deliver: false, to: nil, channel: .last)
+        }
+        let channel = GatewayAgentChannel(raw: link.channel)
+        let deliver = channel.shouldDeliver(link.deliver)
+        let to = link.to?.trimmingCharacters(in: .whitespacesAndNewlines).nonEmpty
+        return (deliver: deliver, to: to, channel: channel)
+    }
+}
+
+@MainActor
+final class DeepLinkHandler {
+    static let shared = DeepLinkHandler()
+
+    private var lastPromptAt: Date = .distantPast
+
+    /// Ephemeral, in-memory key used for unattended deep links originating from the in-app Canvas.
+    /// This avoids blocking Canvas init on UserDefaults and doesn't weaken the external deep-link prompt:
+    /// outside callers can't know this randomly generated key.
+    private nonisolated static let canvasUnattendedKey: String = DeepLinkHandler.generateRandomKey()
+
+    func handle(url: URL) async {
+        guard let route = DeepLinkParser.parse(url) else {
+            deepLinkLogger.debug("ignored url \(url.absoluteString, privacy: .public)")
+            return
+        }
+        guard !AppStateStore.shared.isPaused else {
+            self.presentAlert(title: "OpenClaw is paused", message: "Unpause OpenClaw to run agent actions.")
+            return
+        }
+
+        switch route {
+        case let .agent(link):
+            await self.handleAgent(link: link, originalURL: url)
+        case .gateway:
+            break
+        }
+    }
+
+    private func handleAgent(link: AgentDeepLink, originalURL: URL) async {
+        let messagePreview = link.message.trimmingCharacters(in: .whitespacesAndNewlines)
+        if messagePreview.count > DeepLinkAgentPolicy.maxMessageChars {
+            self.presentAlert(title: "Deep link too large", message: "Message exceeds 20,000 characters.")
+            return
+        }
+
+        let allowUnattended = link.key == Self.canvasUnattendedKey || link.key == Self.expectedKey()
+        if !allowUnattended {
+            if Date().timeIntervalSince(self.lastPromptAt) < 1.0 {
+                deepLinkLogger.debug("throttling deep link prompt")
+                return
+            }
+            self.lastPromptAt = Date()
+
+            if case let .failure(error) = DeepLinkAgentPolicy.validateMessageForHandle(
+                message: messagePreview,
+                allowUnattended: allowUnattended)
+            {
+                self.presentAlert(title: "Deep link blocked", message: error.localizedDescription)
+                return
+            }
+
+            let urlText = originalURL.absoluteString
+            let urlPreview = urlText.count > 500 ? "\(urlText.prefix(500))…" : urlText
+            let body =
+                "Run the agent with this message?\n\n\(messagePreview)\n\nURL:\n\(urlPreview)"
+            guard self.confirm(title: "Run OpenClaw agent?", message: body) else { return }
+        }
+
+        if AppStateStore.shared.connectionMode == .local {
+            GatewayProcessManager.shared.setActive(true)
+        }
+
+        do {
+            let effectiveDelivery = DeepLinkAgentPolicy.effectiveDelivery(link: link, allowUnattended: allowUnattended)
+            let explicitSessionKey = link.sessionKey?
+                .trimmingCharacters(in: .whitespacesAndNewlines)
+                .nonEmpty
+            let resolvedSessionKey: String = if let explicitSessionKey {
+                explicitSessionKey
+            } else {
+                await GatewayConnection.shared.mainSessionKey()
+            }
+            let invocation = GatewayAgentInvocation(
+                message: messagePreview,
+                sessionKey: resolvedSessionKey,
+                thinking: link.thinking?.trimmingCharacters(in: .whitespacesAndNewlines).nonEmpty,
+                deliver: effectiveDelivery.deliver,
+                to: effectiveDelivery.to,
+                channel: effectiveDelivery.channel,
+                timeoutSeconds: link.timeoutSeconds,
+                idempotencyKey: UUID().uuidString)
+
+            let res = await GatewayConnection.shared.sendAgent(invocation)
+            if !res.ok {
+                throw NSError(
+                    domain: "DeepLink",
+                    code: 1,
+                    userInfo: [NSLocalizedDescriptionKey: res.error ?? "agent request failed"])
+            }
+        } catch {
+            self.presentAlert(title: "Agent request failed", message: error.localizedDescription)
+        }
+    }
+
+    // MARK: - Auth
+
+    static func currentKey() -> String {
+        self.expectedKey()
+    }
+
+    static func currentCanvasKey() -> String {
+        self.canvasUnattendedKey
+    }
+
+    private static func expectedKey() -> String {
+        let defaults = UserDefaults.standard
+        if let key = defaults.string(forKey: deepLinkKeyKey), !key.isEmpty {
+            return key
+        }
+        var bytes = [UInt8](repeating: 0, count: 32)
+        _ = SecRandomCopyBytes(kSecRandomDefault, bytes.count, &bytes)
+        let data = Data(bytes)
+        let key = data
+            .base64EncodedString()
+            .replacingOccurrences(of: "+", with: "-")
+            .replacingOccurrences(of: "/", with: "_")
+            .replacingOccurrences(of: "=", with: "")
+        defaults.set(key, forKey: deepLinkKeyKey)
+        return key
+    }
+
+    private nonisolated static func generateRandomKey() -> String {
+        var bytes = [UInt8](repeating: 0, count: 32)
+        _ = SecRandomCopyBytes(kSecRandomDefault, bytes.count, &bytes)
+        let data = Data(bytes)
+        return data
+            .base64EncodedString()
+            .replacingOccurrences(of: "+", with: "-")
+            .replacingOccurrences(of: "/", with: "_")
+            .replacingOccurrences(of: "=", with: "")
+    }
+
+    // MARK: - UI
+
+    private func confirm(title: String, message: String) -> Bool {
+        let alert = NSAlert()
+        alert.messageText = title
+        alert.informativeText = message
+        alert.addButton(withTitle: "Run")
+        alert.addButton(withTitle: "Cancel")
+        alert.alertStyle = .warning
+        return alert.runModal() == .alertFirstButtonReturn
+    }
+
+    private func presentAlert(title: String, message: String) {
+        let alert = NSAlert()
+        alert.messageText = title
+        alert.informativeText = message
+        alert.addButton(withTitle: "OK")
+        alert.alertStyle = .informational
+        alert.runModal()
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/DeviceModelCatalog.swift

@@ -0,0 +1,188 @@
+import Foundation
+
+struct DevicePresentation: Sendable {
+    let title: String
+    let symbol: String?
+}
+
+enum DeviceModelCatalog {
+    private static let modelIdentifierToName: [String: String] = loadModelIdentifierToName()
+    private static let resourceBundle: Bundle? = locateResourceBundle()
+    private static let resourceSubdirectory = "DeviceModels"
+
+    static func presentation(deviceFamily: String?, modelIdentifier: String?) -> DevicePresentation? {
+        let family = (deviceFamily ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
+        let model = (modelIdentifier ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
+
+        let friendlyName = model.isEmpty ? nil : self.modelIdentifierToName[model]
+        let symbol = self.symbol(deviceFamily: family, modelIdentifier: model, friendlyName: friendlyName)
+
+        let title = if let friendlyName, !friendlyName.isEmpty {
+            friendlyName
+        } else if !family.isEmpty, !model.isEmpty {
+            "\(family) (\(model))"
+        } else if !family.isEmpty {
+            family
+        } else if !model.isEmpty {
+            model
+        } else {
+            ""
+        }
+
+        if title.isEmpty { return nil }
+        return DevicePresentation(title: title, symbol: symbol)
+    }
+
+    static func symbol(
+        deviceFamily familyRaw: String,
+        modelIdentifier modelIdentifierRaw: String,
+        friendlyName: String?) -> String?
+    {
+        let family = familyRaw.trimmingCharacters(in: .whitespacesAndNewlines)
+        let modelIdentifier = modelIdentifierRaw.trimmingCharacters(in: .whitespacesAndNewlines)
+
+        return self.symbolFor(modelIdentifier: modelIdentifier, friendlyName: friendlyName)
+            ?? self.fallbackSymbol(for: family, modelIdentifier: modelIdentifier)
+    }
+
+    private static func symbolFor(modelIdentifier rawModelIdentifier: String, friendlyName: String?) -> String? {
+        let modelIdentifier = rawModelIdentifier.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !modelIdentifier.isEmpty else { return nil }
+
+        let lower = modelIdentifier.lowercased()
+        if lower.hasPrefix("ipad") { return "ipad" }
+        if lower.hasPrefix("iphone") { return "iphone" }
+        if lower.hasPrefix("ipod") { return "iphone" }
+        if lower.hasPrefix("watch") { return "applewatch" }
+        if lower.hasPrefix("appletv") { return "appletv" }
+        if lower.hasPrefix("audio") || lower.hasPrefix("homepod") { return "speaker" }
+
+        if lower.hasPrefix("macbook") || lower.hasPrefix("macbookpro") || lower.hasPrefix("macbookair") {
+            return "laptopcomputer"
+        }
+        if lower.hasPrefix("macstudio") { return "macstudio" }
+        if lower.hasPrefix("macmini") { return "macmini" }
+        if lower.hasPrefix("imac") || lower.hasPrefix("macpro") { return "desktopcomputer" }
+
+        if lower.hasPrefix("mac"), let friendlyNameLower = friendlyName?.lowercased() {
+            if friendlyNameLower.contains("macbook") { return "laptopcomputer" }
+            if friendlyNameLower.contains("imac") { return "desktopcomputer" }
+            if friendlyNameLower.contains("mac mini") { return "macmini" }
+            if friendlyNameLower.contains("mac studio") { return "macstudio" }
+            if friendlyNameLower.contains("mac pro") { return "desktopcomputer" }
+        }
+
+        return nil
+    }
+
+    private static func fallbackSymbol(for familyRaw: String, modelIdentifier: String) -> String? {
+        let family = familyRaw.trimmingCharacters(in: .whitespacesAndNewlines)
+        if family.isEmpty { return nil }
+        switch family.lowercased() {
+        case "ipad":
+            return "ipad"
+        case "iphone":
+            return "iphone"
+        case "mac":
+            return "laptopcomputer"
+        case "android":
+            return "android"
+        case "linux":
+            return "cpu"
+        default:
+            return "cpu"
+        }
+    }
+
+    private static func loadModelIdentifierToName() -> [String: String] {
+        var combined: [String: String] = [:]
+        combined.merge(
+            self.loadMapping(resourceName: "ios-device-identifiers"),
+            uniquingKeysWith: { current, _ in current })
+        combined.merge(
+            self.loadMapping(resourceName: "mac-device-identifiers"),
+            uniquingKeysWith: { current, _ in current })
+        return combined
+    }
+
+    private static func loadMapping(resourceName: String) -> [String: String] {
+        guard let url = self.resourceBundle?.url(
+            forResource: resourceName,
+            withExtension: "json",
+            subdirectory: self.resourceSubdirectory)
+        else { return [:] }
+
+        do {
+            let data = try Data(contentsOf: url)
+            let decoded = try JSONDecoder().decode([String: NameValue].self, from: data)
+            return decoded.compactMapValues { $0.normalizedName }
+        } catch {
+            return [:]
+        }
+    }
+
+    private static func locateResourceBundle() -> Bundle? {
+        // Prefer main bundle (packaged app), then module bundle (SwiftPM/tests).
+        // Accessing Bundle.module in the packaged app can crash if the bundle isn't where SwiftPM expects it.
+        if let bundle = self.bundleIfContainsDeviceModels(Bundle.main) {
+            return bundle
+        }
+
+        if let bundle = self.bundleIfContainsDeviceModels(Bundle.module) {
+            return bundle
+        }
+        return nil
+    }
+
+    private static func bundleIfContainsDeviceModels(_ bundle: Bundle) -> Bundle? {
+        if bundle.url(
+            forResource: "ios-device-identifiers",
+            withExtension: "json",
+            subdirectory: self.resourceSubdirectory) != nil
+        {
+            return bundle
+        }
+        if bundle.url(
+            forResource: "mac-device-identifiers",
+            withExtension: "json",
+            subdirectory: self.resourceSubdirectory) != nil
+        {
+            return bundle
+        }
+        return nil
+    }
+
+    private enum NameValue: Decodable {
+        case string(String)
+        case stringArray([String])
+
+        init(from decoder: Decoder) throws {
+            let container = try decoder.singleValueContainer()
+            if let s = try? container.decode(String.self) {
+                self = .string(s)
+                return
+            }
+            if let arr = try? container.decode([String].self) {
+                self = .stringArray(arr)
+                return
+            }
+            throw DecodingError.typeMismatch(
+                String.self,
+                .init(codingPath: decoder.codingPath, debugDescription: "Expected string or string array"))
+        }
+
+        var normalizedName: String? {
+            switch self {
+            case let .string(s):
+                let trimmed = s.trimmingCharacters(in: .whitespacesAndNewlines)
+                return trimmed.isEmpty ? nil : trimmed
+            case let .stringArray(arr):
+                let values = arr
+                    .map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }
+                    .filter { !$0.isEmpty }
+                guard !values.isEmpty else { return nil }
+                return values.joined(separator: " / ")
+            }
+        }
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/DevicePairingApprovalPrompter.swift

@@ -0,0 +1,307 @@
+import AppKit
+import Foundation
+import Observation
+import OpenClawKit
+import OpenClawProtocol
+import OSLog
+
+@MainActor
+@Observable
+final class DevicePairingApprovalPrompter {
+    static let shared = DevicePairingApprovalPrompter()
+
+    private let logger = Logger(subsystem: "ai.openclaw", category: "device-pairing")
+    private var task: Task<Void, Never>?
+    private var isStopping = false
+    private var isPresenting = false
+    private var queue: [PendingRequest] = []
+    var pendingCount: Int = 0
+    var pendingRepairCount: Int = 0
+    private var activeAlert: NSAlert?
+    private var activeRequestId: String?
+    private var alertHostWindow: NSWindow?
+    private var resolvedByRequestId: Set<String> = []
+
+    private struct PairingList: Codable {
+        let pending: [PendingRequest]
+        let paired: [PairedDevice]?
+    }
+
+    private struct PairedDevice: Codable, Equatable {
+        let deviceId: String
+        let approvedAtMs: Double?
+        let displayName: String?
+        let platform: String?
+        let remoteIp: String?
+    }
+
+    private struct PendingRequest: Codable, Equatable, Identifiable {
+        let requestId: String
+        let deviceId: String
+        let publicKey: String
+        let displayName: String?
+        let platform: String?
+        let clientId: String?
+        let clientMode: String?
+        let role: String?
+        let scopes: [String]?
+        let remoteIp: String?
+        let silent: Bool?
+        let isRepair: Bool?
+        let ts: Double
+
+        var id: String {
+            self.requestId
+        }
+    }
+
+    private struct PairingResolvedEvent: Codable {
+        let requestId: String
+        let deviceId: String
+        let decision: String
+        let ts: Double
+    }
+
+    private enum PairingResolution: String {
+        case approved
+        case rejected
+    }
+
+    func start() {
+        guard self.task == nil else { return }
+        self.isStopping = false
+        self.task = Task { [weak self] in
+            guard let self else { return }
+            _ = try? await GatewayConnection.shared.refresh()
+            await self.loadPendingRequestsFromGateway()
+            let stream = await GatewayConnection.shared.subscribe(bufferingNewest: 200)
+            for await push in stream {
+                if Task.isCancelled { return }
+                await MainActor.run { [weak self] in self?.handle(push: push) }
+            }
+        }
+    }
+
+    func stop() {
+        self.isStopping = true
+        self.endActiveAlert()
+        self.task?.cancel()
+        self.task = nil
+        self.queue.removeAll(keepingCapacity: false)
+        self.updatePendingCounts()
+        self.isPresenting = false
+        self.activeRequestId = nil
+        self.alertHostWindow?.orderOut(nil)
+        self.alertHostWindow?.close()
+        self.alertHostWindow = nil
+        self.resolvedByRequestId.removeAll(keepingCapacity: false)
+    }
+
+    private func loadPendingRequestsFromGateway() async {
+        do {
+            let list: PairingList = try await GatewayConnection.shared.requestDecoded(method: .devicePairList)
+            await self.apply(list: list)
+        } catch {
+            self.logger.error("failed to load device pairing requests: \(error.localizedDescription, privacy: .public)")
+        }
+    }
+
+    private func apply(list: PairingList) async {
+        self.queue = list.pending.sorted(by: { $0.ts > $1.ts })
+        self.updatePendingCounts()
+        self.presentNextIfNeeded()
+    }
+
+    private func updatePendingCounts() {
+        self.pendingCount = self.queue.count
+        self.pendingRepairCount = self.queue.count(where: { $0.isRepair == true })
+    }
+
+    private func presentNextIfNeeded() {
+        guard !self.isStopping else { return }
+        guard !self.isPresenting else { return }
+        guard let next = self.queue.first else { return }
+        self.isPresenting = true
+        self.presentAlert(for: next)
+    }
+
+    private func presentAlert(for req: PendingRequest) {
+        self.logger.info("presenting device pairing alert requestId=\(req.requestId, privacy: .public)")
+        NSApp.activate(ignoringOtherApps: true)
+
+        let alert = NSAlert()
+        alert.alertStyle = .warning
+        alert.messageText = "Allow device to connect?"
+        alert.informativeText = Self.describe(req)
+        alert.addButton(withTitle: "Later")
+        alert.addButton(withTitle: "Approve")
+        alert.addButton(withTitle: "Reject")
+        if #available(macOS 11.0, *), alert.buttons.indices.contains(2) {
+            alert.buttons[2].hasDestructiveAction = true
+        }
+
+        self.activeAlert = alert
+        self.activeRequestId = req.requestId
+        let hostWindow = self.requireAlertHostWindow()
+
+        let sheetSize = alert.window.frame.size
+        if let screen = hostWindow.screen ?? NSScreen.main {
+            let bounds = screen.visibleFrame
+            let x = bounds.midX - (sheetSize.width / 2)
+            let sheetOriginY = bounds.midY - (sheetSize.height / 2)
+            let hostY = sheetOriginY + sheetSize.height - hostWindow.frame.height
+            hostWindow.setFrameOrigin(NSPoint(x: x, y: hostY))
+        } else {
+            hostWindow.center()
+        }
+
+        hostWindow.makeKeyAndOrderFront(nil)
+        alert.beginSheetModal(for: hostWindow) { [weak self] response in
+            Task { @MainActor [weak self] in
+                guard let self else { return }
+                self.activeRequestId = nil
+                self.activeAlert = nil
+                await self.handleAlertResponse(response, request: req)
+                hostWindow.orderOut(nil)
+            }
+        }
+    }
+
+    private func handleAlertResponse(_ response: NSApplication.ModalResponse, request: PendingRequest) async {
+        var shouldRemove = response != .alertFirstButtonReturn
+        defer {
+            if shouldRemove {
+                if self.queue.first == request {
+                    self.queue.removeFirst()
+                } else {
+                    self.queue.removeAll { $0 == request }
+                }
+            }
+            self.updatePendingCounts()
+            self.isPresenting = false
+            self.presentNextIfNeeded()
+        }
+
+        guard !self.isStopping else { return }
+
+        if self.resolvedByRequestId.remove(request.requestId) != nil {
+            return
+        }
+
+        switch response {
+        case .alertFirstButtonReturn:
+            shouldRemove = false
+            if let idx = self.queue.firstIndex(of: request) {
+                self.queue.remove(at: idx)
+            }
+            self.queue.append(request)
+            return
+        case .alertSecondButtonReturn:
+            _ = await self.approve(requestId: request.requestId)
+        case .alertThirdButtonReturn:
+            await self.reject(requestId: request.requestId)
+        default:
+            return
+        }
+    }
+
+    private func approve(requestId: String) async -> Bool {
+        do {
+            try await GatewayConnection.shared.devicePairApprove(requestId: requestId)
+            self.logger.info("approved device pairing requestId=\(requestId, privacy: .public)")
+            return true
+        } catch {
+            self.logger.error("approve failed requestId=\(requestId, privacy: .public)")
+            self.logger.error("approve failed: \(error.localizedDescription, privacy: .public)")
+            return false
+        }
+    }
+
+    private func reject(requestId: String) async {
+        do {
+            try await GatewayConnection.shared.devicePairReject(requestId: requestId)
+            self.logger.info("rejected device pairing requestId=\(requestId, privacy: .public)")
+        } catch {
+            self.logger.error("reject failed requestId=\(requestId, privacy: .public)")
+            self.logger.error("reject failed: \(error.localizedDescription, privacy: .public)")
+        }
+    }
+
+    private func endActiveAlert() {
+        PairingAlertSupport.endActiveAlert(activeAlert: &self.activeAlert, activeRequestId: &self.activeRequestId)
+    }
+
+    private func requireAlertHostWindow() -> NSWindow {
+        PairingAlertSupport.requireAlertHostWindow(alertHostWindow: &self.alertHostWindow)
+    }
+
+    private func handle(push: GatewayPush) {
+        switch push {
+        case let .event(evt) where evt.event == "device.pair.requested":
+            guard let payload = evt.payload else { return }
+            do {
+                let req = try GatewayPayloadDecoding.decode(payload, as: PendingRequest.self)
+                self.enqueue(req)
+            } catch {
+                self.logger
+                    .error("failed to decode device pairing request: \(error.localizedDescription, privacy: .public)")
+            }
+        case let .event(evt) where evt.event == "device.pair.resolved":
+            guard let payload = evt.payload else { return }
+            do {
+                let resolved = try GatewayPayloadDecoding.decode(payload, as: PairingResolvedEvent.self)
+                self.handleResolved(resolved)
+            } catch {
+                self.logger
+                    .error(
+                        "failed to decode device pairing resolution: \(error.localizedDescription, privacy: .public)")
+            }
+        default:
+            break
+        }
+    }
+
+    private func enqueue(_ req: PendingRequest) {
+        guard !self.queue.contains(req) else { return }
+        self.queue.append(req)
+        self.updatePendingCounts()
+        self.presentNextIfNeeded()
+    }
+
+    private func handleResolved(_ resolved: PairingResolvedEvent) {
+        let resolution = resolved.decision == PairingResolution.approved.rawValue ? PairingResolution
+            .approved : .rejected
+        if let activeRequestId, activeRequestId == resolved.requestId {
+            self.resolvedByRequestId.insert(resolved.requestId)
+            self.endActiveAlert()
+            let decision = resolution.rawValue
+            self.logger.info(
+                "device pairing resolved while active requestId=\(resolved.requestId, privacy: .public) " +
+                    "decision=\(decision, privacy: .public)")
+            return
+        }
+        self.queue.removeAll { $0.requestId == resolved.requestId }
+        self.updatePendingCounts()
+    }
+
+    private static func describe(_ req: PendingRequest) -> String {
+        var lines: [String] = []
+        lines.append("Device: \(req.displayName ?? req.deviceId)")
+        if let platform = req.platform {
+            lines.append("Platform: \(platform)")
+        }
+        if let role = req.role {
+            lines.append("Role: \(role)")
+        }
+        if let scopes = req.scopes, !scopes.isEmpty {
+            lines.append("Scopes: \(scopes.joined(separator: ", "))")
+        }
+        if let remoteIp = req.remoteIp {
+            lines.append("IP: \(remoteIp)")
+        }
+        if req.isRepair == true {
+            lines.append("Repair: yes")
+        }
+        return lines.joined(separator: "\n")
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/DiagnosticsFileLog.swift

@@ -0,0 +1,133 @@
+import Foundation
+
+actor DiagnosticsFileLog {
+    static let shared = DiagnosticsFileLog()
+
+    private let fileName = "diagnostics.jsonl"
+    private let maxBytes: Int64 = 5 * 1024 * 1024
+    private let maxBackups = 5
+
+    struct Record: Codable, Sendable {
+        let ts: String
+        let pid: Int32
+        let category: String
+        let event: String
+        let fields: [String: String]?
+    }
+
+    nonisolated static func isEnabled() -> Bool {
+        UserDefaults.standard.bool(forKey: debugFileLogEnabledKey)
+    }
+
+    nonisolated static func logDirectoryURL() -> URL {
+        let library = FileManager().urls(for: .libraryDirectory, in: .userDomainMask).first
+            ?? FileManager().homeDirectoryForCurrentUser.appendingPathComponent("Library", isDirectory: true)
+        return library
+            .appendingPathComponent("Logs", isDirectory: true)
+            .appendingPathComponent("OpenClaw", isDirectory: true)
+    }
+
+    nonisolated static func logFileURL() -> URL {
+        self.logDirectoryURL().appendingPathComponent("diagnostics.jsonl", isDirectory: false)
+    }
+
+    nonisolated func log(category: String, event: String, fields: [String: String]? = nil) {
+        guard Self.isEnabled() else { return }
+        let record = Record(
+            ts: ISO8601DateFormatter().string(from: Date()),
+            pid: ProcessInfo.processInfo.processIdentifier,
+            category: category,
+            event: event,
+            fields: fields)
+        Task { await self.write(record: record) }
+    }
+
+    func clear() throws {
+        let fm = FileManager()
+        let base = Self.logFileURL()
+        if fm.fileExists(atPath: base.path) {
+            try fm.removeItem(at: base)
+        }
+        for idx in 1...self.maxBackups {
+            let url = self.rotatedURL(index: idx)
+            if fm.fileExists(atPath: url.path) {
+                try fm.removeItem(at: url)
+            }
+        }
+    }
+
+    private func write(record: Record) {
+        do {
+            try self.ensureDirectory()
+            try self.rotateIfNeeded()
+            try self.append(record: record)
+        } catch {
+            // Best-effort only: never crash or block the app on logging.
+        }
+    }
+
+    private func ensureDirectory() throws {
+        try FileManager().createDirectory(
+            at: Self.logDirectoryURL(),
+            withIntermediateDirectories: true)
+    }
+
+    private func append(record: Record) throws {
+        let url = Self.logFileURL()
+        let data = try JSONEncoder().encode(record)
+        var line = Data()
+        line.append(data)
+        line.append(0x0A) // newline
+
+        let fm = FileManager()
+        if !fm.fileExists(atPath: url.path) {
+            fm.createFile(atPath: url.path, contents: nil)
+        }
+
+        let handle = try FileHandle(forWritingTo: url)
+        defer { try? handle.close() }
+        try handle.seekToEnd()
+        try handle.write(contentsOf: line)
+    }
+
+    private func rotateIfNeeded() throws {
+        let url = Self.logFileURL()
+        guard let attrs = try? FileManager().attributesOfItem(atPath: url.path),
+              let size = attrs[.size] as? NSNumber
+        else { return }
+
+        if size.int64Value < self.maxBytes { return }
+
+        let fm = FileManager()
+
+        let oldest = self.rotatedURL(index: self.maxBackups)
+        if fm.fileExists(atPath: oldest.path) {
+            try fm.removeItem(at: oldest)
+        }
+
+        if self.maxBackups > 1 {
+            for idx in stride(from: self.maxBackups - 1, through: 1, by: -1) {
+                let src = self.rotatedURL(index: idx)
+                let dst = self.rotatedURL(index: idx + 1)
+                if fm.fileExists(atPath: src.path) {
+                    if fm.fileExists(atPath: dst.path) {
+                        try fm.removeItem(at: dst)
+                    }
+                    try fm.moveItem(at: src, to: dst)
+                }
+            }
+        }
+
+        let first = self.rotatedURL(index: 1)
+        if fm.fileExists(atPath: first.path) {
+            try fm.removeItem(at: first)
+        }
+        if fm.fileExists(atPath: url.path) {
+            try fm.moveItem(at: url, to: first)
+        }
+    }
+
+    private func rotatedURL(index: Int) -> URL {
+        Self.logDirectoryURL().appendingPathComponent("\(self.fileName).\(index)", isDirectory: false)
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/DockIconManager.swift

@@ -0,0 +1,116 @@
+import AppKit
+
+/// Central manager for Dock icon visibility.
+/// Shows the Dock icon while any windows are visible, regardless of user preference.
+final class DockIconManager: NSObject, @unchecked Sendable {
+    static let shared = DockIconManager()
+
+    private var windowsObservation: NSKeyValueObservation?
+    private let logger = Logger(subsystem: "ai.openclaw", category: "DockIconManager")
+
+    override private init() {
+        super.init()
+        self.setupObservers()
+        Task { @MainActor in
+            self.updateDockVisibility()
+        }
+    }
+
+    deinit {
+        self.windowsObservation?.invalidate()
+        NotificationCenter.default.removeObserver(self)
+    }
+
+    func updateDockVisibility() {
+        Task { @MainActor in
+            guard NSApp != nil else {
+                self.logger.warning("NSApp not ready, skipping Dock visibility update")
+                return
+            }
+
+            let userWantsDockHidden = !UserDefaults.standard.bool(forKey: showDockIconKey)
+            let visibleWindows = NSApp?.windows.filter { window in
+                window.isVisible &&
+                    window.frame.width > 1 &&
+                    window.frame.height > 1 &&
+                    !window.isKind(of: NSPanel.self) &&
+                    "\(type(of: window))" != "NSPopupMenuWindow" &&
+                    window.contentViewController != nil
+            } ?? []
+
+            let hasVisibleWindows = !visibleWindows.isEmpty
+            if !userWantsDockHidden || hasVisibleWindows {
+                NSApp?.setActivationPolicy(.regular)
+            } else {
+                NSApp?.setActivationPolicy(.accessory)
+            }
+        }
+    }
+
+    func temporarilyShowDock() {
+        Task { @MainActor in
+            guard NSApp != nil else {
+                self.logger.warning("NSApp not ready, cannot show Dock icon")
+                return
+            }
+            NSApp.setActivationPolicy(.regular)
+        }
+    }
+
+    private func setupObservers() {
+        Task { @MainActor in
+            guard let app = NSApp else {
+                self.logger.warning("NSApp not ready, delaying Dock observers")
+                try? await Task.sleep(for: .milliseconds(200))
+                self.setupObservers()
+                return
+            }
+
+            self.windowsObservation = app.observe(\.windows, options: [.new]) { [weak self] _, _ in
+                Task { @MainActor in
+                    try? await Task.sleep(for: .milliseconds(50))
+                    self?.updateDockVisibility()
+                }
+            }
+
+            NotificationCenter.default.addObserver(
+                self,
+                selector: #selector(self.windowVisibilityChanged),
+                name: NSWindow.didBecomeKeyNotification,
+                object: nil)
+            NotificationCenter.default.addObserver(
+                self,
+                selector: #selector(self.windowVisibilityChanged),
+                name: NSWindow.didResignKeyNotification,
+                object: nil)
+            NotificationCenter.default.addObserver(
+                self,
+                selector: #selector(self.windowVisibilityChanged),
+                name: NSWindow.willCloseNotification,
+                object: nil)
+            NotificationCenter.default.addObserver(
+                self,
+                selector: #selector(self.dockPreferenceChanged),
+                name: UserDefaults.didChangeNotification,
+                object: nil)
+        }
+    }
+
+    @objc
+    private func windowVisibilityChanged(_: Notification) {
+        Task { @MainActor in
+            self.updateDockVisibility()
+        }
+    }
+
+    @objc
+    private func dockPreferenceChanged(_ notification: Notification) {
+        guard let userDefaults = notification.object as? UserDefaults,
+              userDefaults == UserDefaults.standard
+        else { return }
+
+        Task { @MainActor in
+            self.updateDockVisibility()
+        }
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/ExecAllowlistMatcher.swift

@@ -0,0 +1,79 @@
+import Foundation
+
+enum ExecAllowlistMatcher {
+    static func match(entries: [ExecAllowlistEntry], resolution: ExecCommandResolution?) -> ExecAllowlistEntry? {
+        guard let resolution, !entries.isEmpty else { return nil }
+        let rawExecutable = resolution.rawExecutable
+        let resolvedPath = resolution.resolvedPath
+
+        for entry in entries {
+            switch ExecApprovalHelpers.validateAllowlistPattern(entry.pattern) {
+            case let .valid(pattern):
+                let target = resolvedPath ?? rawExecutable
+                if self.matches(pattern: pattern, target: target) { return entry }
+            case .invalid:
+                continue
+            }
+        }
+        return nil
+    }
+
+    static func matchAll(
+        entries: [ExecAllowlistEntry],
+        resolutions: [ExecCommandResolution]) -> [ExecAllowlistEntry]
+    {
+        guard !entries.isEmpty, !resolutions.isEmpty else { return [] }
+        var matches: [ExecAllowlistEntry] = []
+        matches.reserveCapacity(resolutions.count)
+        for resolution in resolutions {
+            guard let match = self.match(entries: entries, resolution: resolution) else {
+                return []
+            }
+            matches.append(match)
+        }
+        return matches
+    }
+
+    private static func matches(pattern: String, target: String) -> Bool {
+        let trimmed = pattern.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return false }
+        let expanded = trimmed.hasPrefix("~") ? (trimmed as NSString).expandingTildeInPath : trimmed
+        let normalizedPattern = self.normalizeMatchTarget(expanded)
+        let normalizedTarget = self.normalizeMatchTarget(target)
+        guard let regex = self.regex(for: normalizedPattern) else { return false }
+        let range = NSRange(location: 0, length: normalizedTarget.utf16.count)
+        return regex.firstMatch(in: normalizedTarget, options: [], range: range) != nil
+    }
+
+    private static func normalizeMatchTarget(_ value: String) -> String {
+        value.replacingOccurrences(of: "\\\\", with: "/").lowercased()
+    }
+
+    private static func regex(for pattern: String) -> NSRegularExpression? {
+        var regex = "^"
+        var idx = pattern.startIndex
+        while idx < pattern.endIndex {
+            let ch = pattern[idx]
+            if ch == "*" {
+                let next = pattern.index(after: idx)
+                if next < pattern.endIndex, pattern[next] == "*" {
+                    regex += ".*"
+                    idx = pattern.index(after: next)
+                } else {
+                    regex += "[^/]*"
+                    idx = next
+                }
+                continue
+            }
+            if ch == "?" {
+                regex += "."
+                idx = pattern.index(after: idx)
+                continue
+            }
+            regex += NSRegularExpression.escapedPattern(for: String(ch))
+            idx = pattern.index(after: idx)
+        }
+        regex += "$"
+        return try? NSRegularExpression(pattern: regex, options: [.caseInsensitive])
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/ExecApprovalEvaluation.swift

@@ -0,0 +1,68 @@
+import Foundation
+
+struct ExecApprovalEvaluation {
+    let command: [String]
+    let displayCommand: String
+    let agentId: String?
+    let security: ExecSecurity
+    let ask: ExecAsk
+    let env: [String: String]
+    let resolution: ExecCommandResolution?
+    let allowlistResolutions: [ExecCommandResolution]
+    let allowlistMatches: [ExecAllowlistEntry]
+    let allowlistSatisfied: Bool
+    let allowlistMatch: ExecAllowlistEntry?
+    let skillAllow: Bool
+}
+
+enum ExecApprovalEvaluator {
+    static func evaluate(
+        command: [String],
+        rawCommand: String?,
+        cwd: String?,
+        envOverrides: [String: String]?,
+        agentId: String?) async -> ExecApprovalEvaluation
+    {
+        let trimmedAgent = agentId?.trimmingCharacters(in: .whitespacesAndNewlines)
+        let normalizedAgentId = (trimmedAgent?.isEmpty == false) ? trimmedAgent : nil
+        let approvals = ExecApprovalsStore.resolve(agentId: normalizedAgentId)
+        let security = approvals.agent.security
+        let ask = approvals.agent.ask
+        let shellWrapper = ExecShellWrapperParser.extract(command: command, rawCommand: rawCommand).isWrapper
+        let env = HostEnvSanitizer.sanitize(overrides: envOverrides, shellWrapper: shellWrapper)
+        let displayCommand = ExecCommandFormatter.displayString(for: command, rawCommand: rawCommand)
+        let allowlistResolutions = ExecCommandResolution.resolveForAllowlist(
+            command: command,
+            rawCommand: rawCommand,
+            cwd: cwd,
+            env: env)
+        let allowlistMatches = security == .allowlist
+            ? ExecAllowlistMatcher.matchAll(entries: approvals.allowlist, resolutions: allowlistResolutions)
+            : []
+        let allowlistSatisfied = security == .allowlist &&
+            !allowlistResolutions.isEmpty &&
+            allowlistMatches.count == allowlistResolutions.count
+
+        let skillAllow: Bool
+        if approvals.agent.autoAllowSkills, !allowlistResolutions.isEmpty {
+            let bins = await SkillBinsCache.shared.currentBins()
+            skillAllow = allowlistResolutions.allSatisfy { bins.contains($0.executableName) }
+        } else {
+            skillAllow = false
+        }
+
+        return ExecApprovalEvaluation(
+            command: command,
+            displayCommand: displayCommand,
+            agentId: normalizedAgentId,
+            security: security,
+            ask: ask,
+            env: env,
+            resolution: allowlistResolutions.first,
+            allowlistResolutions: allowlistResolutions,
+            allowlistMatches: allowlistMatches,
+            allowlistSatisfied: allowlistSatisfied,
+            allowlistMatch: allowlistSatisfied ? allowlistMatches.first : nil,
+            skillAllow: skillAllow)
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/ExecApprovals.swift

@@ -0,0 +1,794 @@
+import CryptoKit
+import Foundation
+import OSLog
+import Security
+
+enum ExecSecurity: String, CaseIterable, Codable, Identifiable {
+    case deny
+    case allowlist
+    case full
+
+    var id: String {
+        self.rawValue
+    }
+
+    var title: String {
+        switch self {
+        case .deny: "Deny"
+        case .allowlist: "Allowlist"
+        case .full: "Always Allow"
+        }
+    }
+}
+
+enum ExecApprovalQuickMode: String, CaseIterable, Identifiable {
+    case deny
+    case ask
+    case allow
+
+    var id: String {
+        self.rawValue
+    }
+
+    var title: String {
+        switch self {
+        case .deny: "Deny"
+        case .ask: "Always Ask"
+        case .allow: "Always Allow"
+        }
+    }
+
+    var security: ExecSecurity {
+        switch self {
+        case .deny: .deny
+        case .ask: .allowlist
+        case .allow: .full
+        }
+    }
+
+    var ask: ExecAsk {
+        switch self {
+        case .deny: .off
+        case .ask: .onMiss
+        case .allow: .off
+        }
+    }
+
+    static func from(security: ExecSecurity, ask: ExecAsk) -> ExecApprovalQuickMode {
+        switch security {
+        case .deny:
+            .deny
+        case .full:
+            .allow
+        case .allowlist:
+            .ask
+        }
+    }
+}
+
+enum ExecAsk: String, CaseIterable, Codable, Identifiable {
+    case off
+    case onMiss = "on-miss"
+    case always
+
+    var id: String {
+        self.rawValue
+    }
+
+    var title: String {
+        switch self {
+        case .off: "Never Ask"
+        case .onMiss: "Ask on Allowlist Miss"
+        case .always: "Always Ask"
+        }
+    }
+}
+
+enum ExecApprovalDecision: String, Codable, Sendable {
+    case allowOnce = "allow-once"
+    case allowAlways = "allow-always"
+    case deny
+}
+
+enum ExecAllowlistPatternValidationReason: String, Codable, Sendable, Equatable {
+    case empty
+    case missingPathComponent
+
+    var message: String {
+        switch self {
+        case .empty:
+            "Pattern cannot be empty."
+        case .missingPathComponent:
+            "Path patterns only. Include '/', '~', or '\\\\'."
+        }
+    }
+}
+
+enum ExecAllowlistPatternValidation: Sendable, Equatable {
+    case valid(String)
+    case invalid(ExecAllowlistPatternValidationReason)
+}
+
+struct ExecAllowlistRejectedEntry: Sendable, Equatable {
+    let id: UUID
+    let pattern: String
+    let reason: ExecAllowlistPatternValidationReason
+}
+
+struct ExecAllowlistEntry: Codable, Hashable, Identifiable {
+    var id: UUID
+    var pattern: String
+    var lastUsedAt: Double?
+    var lastUsedCommand: String?
+    var lastResolvedPath: String?
+
+    init(
+        id: UUID = UUID(),
+        pattern: String,
+        lastUsedAt: Double? = nil,
+        lastUsedCommand: String? = nil,
+        lastResolvedPath: String? = nil)
+    {
+        self.id = id
+        self.pattern = pattern
+        self.lastUsedAt = lastUsedAt
+        self.lastUsedCommand = lastUsedCommand
+        self.lastResolvedPath = lastResolvedPath
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case id
+        case pattern
+        case lastUsedAt
+        case lastUsedCommand
+        case lastResolvedPath
+    }
+
+    init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        self.id = try container.decodeIfPresent(UUID.self, forKey: .id) ?? UUID()
+        self.pattern = try container.decode(String.self, forKey: .pattern)
+        self.lastUsedAt = try container.decodeIfPresent(Double.self, forKey: .lastUsedAt)
+        self.lastUsedCommand = try container.decodeIfPresent(String.self, forKey: .lastUsedCommand)
+        self.lastResolvedPath = try container.decodeIfPresent(String.self, forKey: .lastResolvedPath)
+    }
+
+    func encode(to encoder: Encoder) throws {
+        var container = encoder.container(keyedBy: CodingKeys.self)
+        try container.encode(self.id, forKey: .id)
+        try container.encode(self.pattern, forKey: .pattern)
+        try container.encodeIfPresent(self.lastUsedAt, forKey: .lastUsedAt)
+        try container.encodeIfPresent(self.lastUsedCommand, forKey: .lastUsedCommand)
+        try container.encodeIfPresent(self.lastResolvedPath, forKey: .lastResolvedPath)
+    }
+}
+
+struct ExecApprovalsDefaults: Codable {
+    var security: ExecSecurity?
+    var ask: ExecAsk?
+    var askFallback: ExecSecurity?
+    var autoAllowSkills: Bool?
+}
+
+struct ExecApprovalsAgent: Codable {
+    var security: ExecSecurity?
+    var ask: ExecAsk?
+    var askFallback: ExecSecurity?
+    var autoAllowSkills: Bool?
+    var allowlist: [ExecAllowlistEntry]?
+
+    var isEmpty: Bool {
+        self.security == nil && self.ask == nil && self.askFallback == nil && self
+            .autoAllowSkills == nil && (self.allowlist?.isEmpty ?? true)
+    }
+}
+
+struct ExecApprovalsSocketConfig: Codable {
+    var path: String?
+    var token: String?
+}
+
+struct ExecApprovalsFile: Codable {
+    var version: Int
+    var socket: ExecApprovalsSocketConfig?
+    var defaults: ExecApprovalsDefaults?
+    var agents: [String: ExecApprovalsAgent]?
+}
+
+struct ExecApprovalsSnapshot: Codable {
+    var path: String
+    var exists: Bool
+    var hash: String
+    var file: ExecApprovalsFile
+}
+
+struct ExecApprovalsResolved {
+    let url: URL
+    let socketPath: String
+    let token: String
+    let defaults: ExecApprovalsResolvedDefaults
+    let agent: ExecApprovalsResolvedDefaults
+    let allowlist: [ExecAllowlistEntry]
+    var file: ExecApprovalsFile
+}
+
+struct ExecApprovalsResolvedDefaults {
+    var security: ExecSecurity
+    var ask: ExecAsk
+    var askFallback: ExecSecurity
+    var autoAllowSkills: Bool
+}
+
+enum ExecApprovalsStore {
+    private static let logger = Logger(subsystem: "ai.openclaw", category: "exec-approvals")
+    private static let defaultAgentId = "main"
+    private static let defaultSecurity: ExecSecurity = .deny
+    private static let defaultAsk: ExecAsk = .onMiss
+    private static let defaultAskFallback: ExecSecurity = .deny
+    private static let defaultAutoAllowSkills = false
+
+    static func fileURL() -> URL {
+        OpenClawPaths.stateDirURL.appendingPathComponent("exec-approvals.json")
+    }
+
+    static func socketPath() -> String {
+        OpenClawPaths.stateDirURL.appendingPathComponent("exec-approvals.sock").path
+    }
+
+    static func normalizeIncoming(_ file: ExecApprovalsFile) -> ExecApprovalsFile {
+        let socketPath = file.socket?.path?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        let token = file.socket?.token?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        var agents = file.agents ?? [:]
+        if let legacyDefault = agents["default"] {
+            if let main = agents[self.defaultAgentId] {
+                agents[self.defaultAgentId] = self.mergeAgents(current: main, legacy: legacyDefault)
+            } else {
+                agents[self.defaultAgentId] = legacyDefault
+            }
+            agents.removeValue(forKey: "default")
+        }
+        if !agents.isEmpty {
+            var normalizedAgents: [String: ExecApprovalsAgent] = [:]
+            normalizedAgents.reserveCapacity(agents.count)
+            for (key, var agent) in agents {
+                if let allowlist = agent.allowlist {
+                    let normalized = self.normalizeAllowlistEntries(allowlist, dropInvalid: false).entries
+                    agent.allowlist = normalized.isEmpty ? nil : normalized
+                }
+                normalizedAgents[key] = agent
+            }
+            agents = normalizedAgents
+        }
+        return ExecApprovalsFile(
+            version: 1,
+            socket: ExecApprovalsSocketConfig(
+                path: socketPath.isEmpty ? nil : socketPath,
+                token: token.isEmpty ? nil : token),
+            defaults: file.defaults,
+            agents: agents.isEmpty ? nil : agents)
+    }
+
+    static func readSnapshot() -> ExecApprovalsSnapshot {
+        let url = self.fileURL()
+        guard FileManager().fileExists(atPath: url.path) else {
+            return ExecApprovalsSnapshot(
+                path: url.path,
+                exists: false,
+                hash: self.hashRaw(nil),
+                file: ExecApprovalsFile(version: 1, socket: nil, defaults: nil, agents: [:]))
+        }
+        let raw = try? String(contentsOf: url, encoding: .utf8)
+        let data = raw.flatMap { $0.data(using: .utf8) }
+        let decoded: ExecApprovalsFile = {
+            if let data, let file = try? JSONDecoder().decode(ExecApprovalsFile.self, from: data), file.version == 1 {
+                return file
+            }
+            return ExecApprovalsFile(version: 1, socket: nil, defaults: nil, agents: [:])
+        }()
+        return ExecApprovalsSnapshot(
+            path: url.path,
+            exists: true,
+            hash: self.hashRaw(raw),
+            file: decoded)
+    }
+
+    static func redactForSnapshot(_ file: ExecApprovalsFile) -> ExecApprovalsFile {
+        let socketPath = file.socket?.path?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        if socketPath.isEmpty {
+            return ExecApprovalsFile(
+                version: file.version,
+                socket: nil,
+                defaults: file.defaults,
+                agents: file.agents)
+        }
+        return ExecApprovalsFile(
+            version: file.version,
+            socket: ExecApprovalsSocketConfig(path: socketPath, token: nil),
+            defaults: file.defaults,
+            agents: file.agents)
+    }
+
+    static func loadFile() -> ExecApprovalsFile {
+        let url = self.fileURL()
+        guard FileManager().fileExists(atPath: url.path) else {
+            return ExecApprovalsFile(version: 1, socket: nil, defaults: nil, agents: [:])
+        }
+        do {
+            let data = try Data(contentsOf: url)
+            let decoded = try JSONDecoder().decode(ExecApprovalsFile.self, from: data)
+            if decoded.version != 1 {
+                return ExecApprovalsFile(version: 1, socket: nil, defaults: nil, agents: [:])
+            }
+            return decoded
+        } catch {
+            self.logger.warning("exec approvals load failed: \(error.localizedDescription, privacy: .public)")
+            return ExecApprovalsFile(version: 1, socket: nil, defaults: nil, agents: [:])
+        }
+    }
+
+    static func saveFile(_ file: ExecApprovalsFile) {
+        do {
+            let encoder = JSONEncoder()
+            encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
+            let data = try encoder.encode(file)
+            let url = self.fileURL()
+            try FileManager().createDirectory(
+                at: url.deletingLastPathComponent(),
+                withIntermediateDirectories: true)
+            try data.write(to: url, options: [.atomic])
+            try? FileManager().setAttributes([.posixPermissions: 0o600], ofItemAtPath: url.path)
+        } catch {
+            self.logger.error("exec approvals save failed: \(error.localizedDescription, privacy: .public)")
+        }
+    }
+
+    static func ensureFile() -> ExecApprovalsFile {
+        let url = self.fileURL()
+        let existed = FileManager().fileExists(atPath: url.path)
+        let loaded = self.loadFile()
+        let loadedHash = self.hashFile(loaded)
+
+        var file = self.normalizeIncoming(loaded)
+        if file.socket == nil { file.socket = ExecApprovalsSocketConfig(path: nil, token: nil) }
+        let path = file.socket?.path?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        if path.isEmpty {
+            file.socket?.path = self.socketPath()
+        }
+        let token = file.socket?.token?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        if token.isEmpty {
+            file.socket?.token = self.generateToken()
+        }
+        if file.agents == nil { file.agents = [:] }
+        if !existed || loadedHash != self.hashFile(file) {
+            self.saveFile(file)
+        }
+        return file
+    }
+
+    static func resolve(agentId: String?) -> ExecApprovalsResolved {
+        let file = self.ensureFile()
+        let defaults = file.defaults ?? ExecApprovalsDefaults()
+        let resolvedDefaults = ExecApprovalsResolvedDefaults(
+            security: defaults.security ?? self.defaultSecurity,
+            ask: defaults.ask ?? self.defaultAsk,
+            askFallback: defaults.askFallback ?? self.defaultAskFallback,
+            autoAllowSkills: defaults.autoAllowSkills ?? self.defaultAutoAllowSkills)
+        let key = self.agentKey(agentId)
+        let agentEntry = file.agents?[key] ?? ExecApprovalsAgent()
+        let wildcardEntry = file.agents?["*"] ?? ExecApprovalsAgent()
+        let resolvedAgent = ExecApprovalsResolvedDefaults(
+            security: agentEntry.security ?? wildcardEntry.security ?? resolvedDefaults.security,
+            ask: agentEntry.ask ?? wildcardEntry.ask ?? resolvedDefaults.ask,
+            askFallback: agentEntry.askFallback ?? wildcardEntry.askFallback
+                ?? resolvedDefaults.askFallback,
+            autoAllowSkills: agentEntry.autoAllowSkills ?? wildcardEntry.autoAllowSkills
+                ?? resolvedDefaults.autoAllowSkills)
+        let allowlist = self.normalizeAllowlistEntries(
+            (wildcardEntry.allowlist ?? []) + (agentEntry.allowlist ?? []),
+            dropInvalid: true).entries
+        let socketPath = self.expandPath(file.socket?.path ?? self.socketPath())
+        let token = file.socket?.token ?? ""
+        return ExecApprovalsResolved(
+            url: self.fileURL(),
+            socketPath: socketPath,
+            token: token,
+            defaults: resolvedDefaults,
+            agent: resolvedAgent,
+            allowlist: allowlist,
+            file: file)
+    }
+
+    static func resolveDefaults() -> ExecApprovalsResolvedDefaults {
+        let file = self.ensureFile()
+        let defaults = file.defaults ?? ExecApprovalsDefaults()
+        return ExecApprovalsResolvedDefaults(
+            security: defaults.security ?? self.defaultSecurity,
+            ask: defaults.ask ?? self.defaultAsk,
+            askFallback: defaults.askFallback ?? self.defaultAskFallback,
+            autoAllowSkills: defaults.autoAllowSkills ?? self.defaultAutoAllowSkills)
+    }
+
+    static func saveDefaults(_ defaults: ExecApprovalsDefaults) {
+        self.updateFile { file in
+            file.defaults = defaults
+        }
+    }
+
+    static func updateDefaults(_ mutate: (inout ExecApprovalsDefaults) -> Void) {
+        self.updateFile { file in
+            var defaults = file.defaults ?? ExecApprovalsDefaults()
+            mutate(&defaults)
+            file.defaults = defaults
+        }
+    }
+
+    static func saveAgent(_ agent: ExecApprovalsAgent, agentId: String?) {
+        self.updateFile { file in
+            var agents = file.agents ?? [:]
+            let key = self.agentKey(agentId)
+            if agent.isEmpty {
+                agents.removeValue(forKey: key)
+            } else {
+                agents[key] = agent
+            }
+            file.agents = agents.isEmpty ? nil : agents
+        }
+    }
+
+    @discardableResult
+    static func addAllowlistEntry(agentId: String?, pattern: String) -> ExecAllowlistPatternValidationReason? {
+        let normalizedPattern: String
+        switch ExecApprovalHelpers.validateAllowlistPattern(pattern) {
+        case let .valid(validPattern):
+            normalizedPattern = validPattern
+        case let .invalid(reason):
+            return reason
+        }
+
+        self.updateFile { file in
+            let key = self.agentKey(agentId)
+            var agents = file.agents ?? [:]
+            var entry = agents[key] ?? ExecApprovalsAgent()
+            var allowlist = entry.allowlist ?? []
+            if allowlist.contains(where: { $0.pattern == normalizedPattern }) { return }
+            allowlist.append(ExecAllowlistEntry(
+                pattern: normalizedPattern,
+                lastUsedAt: Date().timeIntervalSince1970 * 1000))
+            entry.allowlist = allowlist
+            agents[key] = entry
+            file.agents = agents
+        }
+        return nil
+    }
+
+    static func recordAllowlistUse(
+        agentId: String?,
+        pattern: String,
+        command: String,
+        resolvedPath: String?)
+    {
+        self.updateFile { file in
+            let key = self.agentKey(agentId)
+            var agents = file.agents ?? [:]
+            var entry = agents[key] ?? ExecApprovalsAgent()
+            let allowlist = (entry.allowlist ?? []).map { item -> ExecAllowlistEntry in
+                guard item.pattern == pattern else { return item }
+                return ExecAllowlistEntry(
+                    id: item.id,
+                    pattern: item.pattern,
+                    lastUsedAt: Date().timeIntervalSince1970 * 1000,
+                    lastUsedCommand: command,
+                    lastResolvedPath: resolvedPath)
+            }
+            entry.allowlist = allowlist
+            agents[key] = entry
+            file.agents = agents
+        }
+    }
+
+    @discardableResult
+    static func updateAllowlist(agentId: String?, allowlist: [ExecAllowlistEntry]) -> [ExecAllowlistRejectedEntry] {
+        var rejected: [ExecAllowlistRejectedEntry] = []
+        self.updateFile { file in
+            let key = self.agentKey(agentId)
+            var agents = file.agents ?? [:]
+            var entry = agents[key] ?? ExecApprovalsAgent()
+            let normalized = self.normalizeAllowlistEntries(allowlist, dropInvalid: true)
+            rejected = normalized.rejected
+            let cleaned = normalized.entries
+            entry.allowlist = cleaned
+            agents[key] = entry
+            file.agents = agents
+        }
+        return rejected
+    }
+
+    static func updateAgentSettings(agentId: String?, mutate: (inout ExecApprovalsAgent) -> Void) {
+        self.updateFile { file in
+            let key = self.agentKey(agentId)
+            var agents = file.agents ?? [:]
+            var entry = agents[key] ?? ExecApprovalsAgent()
+            mutate(&entry)
+            if entry.isEmpty {
+                agents.removeValue(forKey: key)
+            } else {
+                agents[key] = entry
+            }
+            file.agents = agents.isEmpty ? nil : agents
+        }
+    }
+
+    private static func updateFile(_ mutate: (inout ExecApprovalsFile) -> Void) {
+        var file = self.ensureFile()
+        mutate(&file)
+        self.saveFile(file)
+    }
+
+    private static func generateToken() -> String {
+        var bytes = [UInt8](repeating: 0, count: 24)
+        let status = SecRandomCopyBytes(kSecRandomDefault, bytes.count, &bytes)
+        if status == errSecSuccess {
+            return Data(bytes)
+                .base64EncodedString()
+                .replacingOccurrences(of: "+", with: "-")
+                .replacingOccurrences(of: "/", with: "_")
+                .replacingOccurrences(of: "=", with: "")
+        }
+        return UUID().uuidString
+    }
+
+    private static func hashRaw(_ raw: String?) -> String {
+        let data = Data((raw ?? "").utf8)
+        let digest = SHA256.hash(data: data)
+        return digest.map { String(format: "%02x", $0) }.joined()
+    }
+
+    private static func hashFile(_ file: ExecApprovalsFile) -> String {
+        let encoder = JSONEncoder()
+        encoder.outputFormatting = [.sortedKeys]
+        let data = (try? encoder.encode(file)) ?? Data()
+        let digest = SHA256.hash(data: data)
+        return digest.map { String(format: "%02x", $0) }.joined()
+    }
+
+    private static func expandPath(_ raw: String) -> String {
+        let trimmed = raw.trimmingCharacters(in: .whitespacesAndNewlines)
+        if trimmed == "~" {
+            return FileManager().homeDirectoryForCurrentUser.path
+        }
+        if trimmed.hasPrefix("~/") {
+            let suffix = trimmed.dropFirst(2)
+            return FileManager().homeDirectoryForCurrentUser
+                .appendingPathComponent(String(suffix)).path
+        }
+        return trimmed
+    }
+
+    private static func agentKey(_ agentId: String?) -> String {
+        let trimmed = agentId?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        return trimmed.isEmpty ? self.defaultAgentId : trimmed
+    }
+
+    private static func normalizedPattern(_ pattern: String?) -> String? {
+        switch ExecApprovalHelpers.validateAllowlistPattern(pattern) {
+        case let .valid(normalized):
+            return normalized.lowercased()
+        case .invalid(.empty):
+            return nil
+        case .invalid:
+            let trimmed = pattern?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+            return trimmed.isEmpty ? nil : trimmed.lowercased()
+        }
+    }
+
+    private static func migrateLegacyPattern(_ entry: ExecAllowlistEntry) -> ExecAllowlistEntry {
+        let trimmedPattern = entry.pattern.trimmingCharacters(in: .whitespacesAndNewlines)
+        let trimmedResolved = entry.lastResolvedPath?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        let normalizedResolved = trimmedResolved.isEmpty ? nil : trimmedResolved
+
+        switch ExecApprovalHelpers.validateAllowlistPattern(trimmedPattern) {
+        case let .valid(pattern):
+            return ExecAllowlistEntry(
+                id: entry.id,
+                pattern: pattern,
+                lastUsedAt: entry.lastUsedAt,
+                lastUsedCommand: entry.lastUsedCommand,
+                lastResolvedPath: normalizedResolved)
+        case .invalid:
+            switch ExecApprovalHelpers.validateAllowlistPattern(trimmedResolved) {
+            case let .valid(migratedPattern):
+                return ExecAllowlistEntry(
+                    id: entry.id,
+                    pattern: migratedPattern,
+                    lastUsedAt: entry.lastUsedAt,
+                    lastUsedCommand: entry.lastUsedCommand,
+                    lastResolvedPath: normalizedResolved)
+            case .invalid:
+                return ExecAllowlistEntry(
+                    id: entry.id,
+                    pattern: trimmedPattern,
+                    lastUsedAt: entry.lastUsedAt,
+                    lastUsedCommand: entry.lastUsedCommand,
+                    lastResolvedPath: normalizedResolved)
+            }
+        }
+    }
+
+    private static func normalizeAllowlistEntries(
+        _ entries: [ExecAllowlistEntry],
+        dropInvalid: Bool) -> (entries: [ExecAllowlistEntry], rejected: [ExecAllowlistRejectedEntry])
+    {
+        var normalized: [ExecAllowlistEntry] = []
+        normalized.reserveCapacity(entries.count)
+        var rejected: [ExecAllowlistRejectedEntry] = []
+
+        for entry in entries {
+            let migrated = self.migrateLegacyPattern(entry)
+            let trimmedPattern = migrated.pattern.trimmingCharacters(in: .whitespacesAndNewlines)
+            let trimmedResolvedPath = migrated.lastResolvedPath?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+            let normalizedResolvedPath = trimmedResolvedPath.isEmpty ? nil : trimmedResolvedPath
+
+            switch ExecApprovalHelpers.validateAllowlistPattern(trimmedPattern) {
+            case let .valid(pattern):
+                normalized.append(
+                    ExecAllowlistEntry(
+                        id: migrated.id,
+                        pattern: pattern,
+                        lastUsedAt: migrated.lastUsedAt,
+                        lastUsedCommand: migrated.lastUsedCommand,
+                        lastResolvedPath: normalizedResolvedPath))
+            case let .invalid(reason):
+                if dropInvalid {
+                    rejected.append(
+                        ExecAllowlistRejectedEntry(
+                            id: migrated.id,
+                            pattern: trimmedPattern,
+                            reason: reason))
+                } else if reason != .empty {
+                    normalized.append(
+                        ExecAllowlistEntry(
+                            id: migrated.id,
+                            pattern: trimmedPattern,
+                            lastUsedAt: migrated.lastUsedAt,
+                            lastUsedCommand: migrated.lastUsedCommand,
+                            lastResolvedPath: normalizedResolvedPath))
+                }
+            }
+        }
+
+        return (normalized, rejected)
+    }
+
+    private static func mergeAgents(
+        current: ExecApprovalsAgent,
+        legacy: ExecApprovalsAgent) -> ExecApprovalsAgent
+    {
+        let currentAllowlist = self.normalizeAllowlistEntries(current.allowlist ?? [], dropInvalid: false).entries
+        let legacyAllowlist = self.normalizeAllowlistEntries(legacy.allowlist ?? [], dropInvalid: false).entries
+        var seen = Set<String>()
+        var allowlist: [ExecAllowlistEntry] = []
+        func append(_ entry: ExecAllowlistEntry) {
+            guard let key = self.normalizedPattern(entry.pattern), !seen.contains(key) else {
+                return
+            }
+            seen.insert(key)
+            allowlist.append(entry)
+        }
+        for entry in currentAllowlist {
+            append(entry)
+        }
+        for entry in legacyAllowlist {
+            append(entry)
+        }
+
+        return ExecApprovalsAgent(
+            security: current.security ?? legacy.security,
+            ask: current.ask ?? legacy.ask,
+            askFallback: current.askFallback ?? legacy.askFallback,
+            autoAllowSkills: current.autoAllowSkills ?? legacy.autoAllowSkills,
+            allowlist: allowlist.isEmpty ? nil : allowlist)
+    }
+}
+
+enum ExecApprovalHelpers {
+    static func validateAllowlistPattern(_ pattern: String?) -> ExecAllowlistPatternValidation {
+        let trimmed = pattern?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        guard !trimmed.isEmpty else { return .invalid(.empty) }
+        guard self.containsPathComponent(trimmed) else { return .invalid(.missingPathComponent) }
+        return .valid(trimmed)
+    }
+
+    static func isPathPattern(_ pattern: String?) -> Bool {
+        switch self.validateAllowlistPattern(pattern) {
+        case .valid:
+            true
+        case .invalid:
+            false
+        }
+    }
+
+    static func parseDecision(_ raw: String?) -> ExecApprovalDecision? {
+        let trimmed = raw?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        guard !trimmed.isEmpty else { return nil }
+        return ExecApprovalDecision(rawValue: trimmed)
+    }
+
+    static func requiresAsk(
+        ask: ExecAsk,
+        security: ExecSecurity,
+        allowlistMatch: ExecAllowlistEntry?,
+        skillAllow: Bool) -> Bool
+    {
+        if ask == .always { return true }
+        if ask == .onMiss, security == .allowlist, allowlistMatch == nil, !skillAllow { return true }
+        return false
+    }
+
+    static func allowlistPattern(command: [String], resolution: ExecCommandResolution?) -> String? {
+        let pattern = resolution?.resolvedPath ?? resolution?.rawExecutable ?? command.first ?? ""
+        return pattern.isEmpty ? nil : pattern
+    }
+
+    private static func containsPathComponent(_ pattern: String) -> Bool {
+        pattern.contains("/") || pattern.contains("~") || pattern.contains("\\")
+    }
+}
+
+struct ExecEventPayload: Codable, Sendable {
+    var sessionKey: String
+    var runId: String
+    var host: String
+    var command: String?
+    var exitCode: Int?
+    var timedOut: Bool?
+    var success: Bool?
+    var output: String?
+    var reason: String?
+
+    static func truncateOutput(_ raw: String, maxChars: Int = 20000) -> String? {
+        let trimmed = raw.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return nil }
+        if trimmed.count <= maxChars { return trimmed }
+        let suffix = trimmed.suffix(maxChars)
+        return "... (truncated) \(suffix)"
+    }
+}
+
+actor SkillBinsCache {
+    static let shared = SkillBinsCache()
+
+    private var bins: Set<String> = []
+    private var lastRefresh: Date?
+    private let refreshInterval: TimeInterval = 90
+
+    func currentBins(force: Bool = false) async -> Set<String> {
+        if force || self.isStale() {
+            await self.refresh()
+        }
+        return self.bins
+    }
+
+    func refresh() async {
+        do {
+            let report = try await GatewayConnection.shared.skillsStatus()
+            var next = Set<String>()
+            for skill in report.skills {
+                for bin in skill.requirements.bins {
+                    let trimmed = bin.trimmingCharacters(in: .whitespacesAndNewlines)
+                    if !trimmed.isEmpty { next.insert(trimmed) }
+                }
+            }
+            self.bins = next
+            self.lastRefresh = Date()
+        } catch {
+            if self.lastRefresh == nil {
+                self.bins = []
+            }
+        }
+    }
+
+    private func isStale() -> Bool {
+        guard let lastRefresh else { return true }
+        return Date().timeIntervalSince(lastRefresh) > self.refreshInterval
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/ExecApprovalsGatewayPrompter.swift

@@ -0,0 +1,123 @@
+import CoreGraphics
+import Foundation
+import OpenClawKit
+import OpenClawProtocol
+import OSLog
+
+@MainActor
+final class ExecApprovalsGatewayPrompter {
+    static let shared = ExecApprovalsGatewayPrompter()
+
+    private let logger = Logger(subsystem: "ai.openclaw", category: "exec-approvals.gateway")
+    private var task: Task<Void, Never>?
+
+    struct GatewayApprovalRequest: Codable, Sendable {
+        var id: String
+        var request: ExecApprovalPromptRequest
+        var createdAtMs: Int
+        var expiresAtMs: Int
+    }
+
+    func start() {
+        guard self.task == nil else { return }
+        self.task = Task { [weak self] in
+            await self?.run()
+        }
+    }
+
+    func stop() {
+        self.task?.cancel()
+        self.task = nil
+    }
+
+    private func run() async {
+        let stream = await GatewayConnection.shared.subscribe(bufferingNewest: 200)
+        for await push in stream {
+            if Task.isCancelled { return }
+            await self.handle(push: push)
+        }
+    }
+
+    private func handle(push: GatewayPush) async {
+        guard case let .event(evt) = push else { return }
+        guard evt.event == "exec.approval.requested" else { return }
+        guard let payload = evt.payload else { return }
+        do {
+            let data = try JSONEncoder().encode(payload)
+            let request = try JSONDecoder().decode(GatewayApprovalRequest.self, from: data)
+            guard self.shouldPresent(request: request) else { return }
+            let decision = ExecApprovalsPromptPresenter.prompt(request.request)
+            try await GatewayConnection.shared.requestVoid(
+                method: .execApprovalResolve,
+                params: [
+                    "id": AnyCodable(request.id),
+                    "decision": AnyCodable(decision.rawValue),
+                ],
+                timeoutMs: 10000)
+        } catch {
+            self.logger.error("exec approval handling failed \(error.localizedDescription, privacy: .public)")
+        }
+    }
+
+    private func shouldPresent(request: GatewayApprovalRequest) -> Bool {
+        let mode = AppStateStore.shared.connectionMode
+        let activeSession = WebChatManager.shared.activeSessionKey?.trimmingCharacters(in: .whitespacesAndNewlines)
+        let requestSession = request.request.sessionKey?.trimmingCharacters(in: .whitespacesAndNewlines)
+        return Self.shouldPresent(
+            mode: mode,
+            activeSession: activeSession,
+            requestSession: requestSession,
+            lastInputSeconds: Self.lastInputSeconds(),
+            thresholdSeconds: 120)
+    }
+
+    private static func shouldPresent(
+        mode: AppState.ConnectionMode,
+        activeSession: String?,
+        requestSession: String?,
+        lastInputSeconds: Int?,
+        thresholdSeconds: Int) -> Bool
+    {
+        let active = activeSession?.trimmingCharacters(in: .whitespacesAndNewlines)
+        let requested = requestSession?.trimmingCharacters(in: .whitespacesAndNewlines)
+        let recentlyActive = lastInputSeconds.map { $0 <= thresholdSeconds } ?? (mode == .local)
+
+        if let session = requested, !session.isEmpty {
+            if let active, !active.isEmpty {
+                return active == session
+            }
+            return recentlyActive
+        }
+
+        if let active, !active.isEmpty {
+            return true
+        }
+        return mode == .local
+    }
+
+    private static func lastInputSeconds() -> Int? {
+        let anyEvent = CGEventType(rawValue: UInt32.max) ?? .null
+        let seconds = CGEventSource.secondsSinceLastEventType(.combinedSessionState, eventType: anyEvent)
+        if seconds.isNaN || seconds.isInfinite || seconds < 0 { return nil }
+        return Int(seconds.rounded())
+    }
+}
+
+#if DEBUG
+extension ExecApprovalsGatewayPrompter {
+    static func _testShouldPresent(
+        mode: AppState.ConnectionMode,
+        activeSession: String?,
+        requestSession: String?,
+        lastInputSeconds: Int?,
+        thresholdSeconds: Int = 120) -> Bool
+    {
+        self.shouldPresent(
+            mode: mode,
+            activeSession: activeSession,
+            requestSession: requestSession,
+            lastInputSeconds: lastInputSeconds,
+            thresholdSeconds: thresholdSeconds)
+    }
+}
+#endif

openclaw/apps/macos/Sources/OpenClaw/ExecApprovalsSocket.swift

@@ -0,0 +1,787 @@
+import AppKit
+import CryptoKit
+import Darwin
+import Foundation
+import OpenClawKit
+import OSLog
+
+struct ExecApprovalPromptRequest: Codable, Sendable {
+    var command: String
+    var cwd: String?
+    var host: String?
+    var security: String?
+    var ask: String?
+    var agentId: String?
+    var resolvedPath: String?
+    var sessionKey: String?
+}
+
+private struct ExecApprovalSocketRequest: Codable {
+    var type: String
+    var token: String
+    var id: String
+    var request: ExecApprovalPromptRequest
+}
+
+private struct ExecApprovalSocketDecision: Codable {
+    var type: String
+    var id: String
+    var decision: ExecApprovalDecision
+}
+
+private struct ExecHostSocketRequest: Codable {
+    var type: String
+    var id: String
+    var nonce: String
+    var ts: Int
+    var hmac: String
+    var requestJson: String
+}
+
+struct ExecHostRequest: Codable {
+    var command: [String]
+    var rawCommand: String?
+    var cwd: String?
+    var env: [String: String]?
+    var timeoutMs: Int?
+    var needsScreenRecording: Bool?
+    var agentId: String?
+    var sessionKey: String?
+    var approvalDecision: ExecApprovalDecision?
+}
+
+private struct ExecHostRunResult: Codable {
+    var exitCode: Int?
+    var timedOut: Bool
+    var success: Bool
+    var stdout: String
+    var stderr: String
+    var error: String?
+}
+
+struct ExecHostError: Codable, Error {
+    var code: String
+    var message: String
+    var reason: String?
+}
+
+private struct ExecHostResponse: Codable {
+    var type: String
+    var id: String
+    var ok: Bool
+    var payload: ExecHostRunResult?
+    var error: ExecHostError?
+}
+
+enum ExecApprovalsSocketClient {
+    private struct TimeoutError: LocalizedError {
+        var message: String
+        var errorDescription: String? {
+            self.message
+        }
+    }
+
+    static func requestDecision(
+        socketPath: String,
+        token: String,
+        request: ExecApprovalPromptRequest,
+        timeoutMs: Int = 15000) async -> ExecApprovalDecision?
+    {
+        let trimmedPath = socketPath.trimmingCharacters(in: .whitespacesAndNewlines)
+        let trimmedToken = token.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmedPath.isEmpty, !trimmedToken.isEmpty else { return nil }
+        do {
+            return try await AsyncTimeout.withTimeoutMs(
+                timeoutMs: timeoutMs,
+                onTimeout: {
+                    TimeoutError(message: "exec approvals socket timeout")
+                },
+                operation: {
+                    try await Task.detached {
+                        try self.requestDecisionSync(
+                            socketPath: trimmedPath,
+                            token: trimmedToken,
+                            request: request)
+                    }.value
+                })
+        } catch {
+            return nil
+        }
+    }
+
+    private static func requestDecisionSync(
+        socketPath: String,
+        token: String,
+        request: ExecApprovalPromptRequest) throws -> ExecApprovalDecision?
+    {
+        let fd = socket(AF_UNIX, SOCK_STREAM, 0)
+        guard fd >= 0 else {
+            throw NSError(domain: "ExecApprovals", code: 1, userInfo: [
+                NSLocalizedDescriptionKey: "socket create failed",
+            ])
+        }
+
+        var addr = sockaddr_un()
+        addr.sun_family = sa_family_t(AF_UNIX)
+        let maxLen = MemoryLayout.size(ofValue: addr.sun_path)
+        if socketPath.utf8.count >= maxLen {
+            throw NSError(domain: "ExecApprovals", code: 2, userInfo: [
+                NSLocalizedDescriptionKey: "socket path too long",
+            ])
+        }
+        socketPath.withCString { cstr in
+            withUnsafeMutablePointer(to: &addr.sun_path) { ptr in
+                let raw = UnsafeMutableRawPointer(ptr).assumingMemoryBound(to: Int8.self)
+                strncpy(raw, cstr, maxLen - 1)
+            }
+        }
+        let size = socklen_t(MemoryLayout.size(ofValue: addr))
+        let result = withUnsafePointer(to: &addr) { ptr in
+            ptr.withMemoryRebound(to: sockaddr.self, capacity: 1) { rebound in
+                connect(fd, rebound, size)
+            }
+        }
+        if result != 0 {
+            throw NSError(domain: "ExecApprovals", code: 3, userInfo: [
+                NSLocalizedDescriptionKey: "socket connect failed",
+            ])
+        }
+
+        let handle = FileHandle(fileDescriptor: fd, closeOnDealloc: true)
+
+        let message = ExecApprovalSocketRequest(
+            type: "request",
+            token: token,
+            id: UUID().uuidString,
+            request: request)
+        let data = try JSONEncoder().encode(message)
+        var payload = data
+        payload.append(0x0A)
+        try handle.write(contentsOf: payload)
+
+        guard let line = try self.readLine(from: handle, maxBytes: 256_000),
+              let lineData = line.data(using: .utf8)
+        else { return nil }
+        let response = try JSONDecoder().decode(ExecApprovalSocketDecision.self, from: lineData)
+        return response.decision
+    }
+
+    private static func readLine(from handle: FileHandle, maxBytes: Int) throws -> String? {
+        var buffer = Data()
+        while buffer.count < maxBytes {
+            let chunk = try handle.read(upToCount: 4096) ?? Data()
+            if chunk.isEmpty { break }
+            buffer.append(chunk)
+            if buffer.contains(0x0A) { break }
+        }
+        guard let newlineIndex = buffer.firstIndex(of: 0x0A) else {
+            guard !buffer.isEmpty else { return nil }
+            return String(data: buffer, encoding: .utf8)
+        }
+        let lineData = buffer.subdata(in: 0..<newlineIndex)
+        return String(data: lineData, encoding: .utf8)
+    }
+}
+
+@MainActor
+final class ExecApprovalsPromptServer {
+    static let shared = ExecApprovalsPromptServer()
+
+    private var server: ExecApprovalsSocketServer?
+
+    func start() {
+        guard self.server == nil else { return }
+        let approvals = ExecApprovalsStore.resolve(agentId: nil)
+        let server = ExecApprovalsSocketServer(
+            socketPath: approvals.socketPath,
+            token: approvals.token,
+            onPrompt: { request in
+                await ExecApprovalsPromptPresenter.prompt(request)
+            },
+            onExec: { request in
+                await ExecHostExecutor.handle(request)
+            })
+        server.start()
+        self.server = server
+    }
+
+    func stop() {
+        self.server?.stop()
+        self.server = nil
+    }
+}
+
+enum ExecApprovalsPromptPresenter {
+    @MainActor
+    static func prompt(_ request: ExecApprovalPromptRequest) -> ExecApprovalDecision {
+        NSApp.activate(ignoringOtherApps: true)
+        let alert = NSAlert()
+        alert.alertStyle = .warning
+        alert.messageText = "Allow this command?"
+        alert.informativeText = "Review the command details before allowing."
+        alert.accessoryView = self.buildAccessoryView(request)
+
+        alert.addButton(withTitle: "Allow Once")
+        alert.addButton(withTitle: "Always Allow")
+        alert.addButton(withTitle: "Don't Allow")
+        if #available(macOS 11.0, *), alert.buttons.indices.contains(2) {
+            alert.buttons[2].hasDestructiveAction = true
+        }
+
+        switch alert.runModal() {
+        case .alertFirstButtonReturn:
+            return .allowOnce
+        case .alertSecondButtonReturn:
+            return .allowAlways
+        default:
+            return .deny
+        }
+    }
+
+    @MainActor
+    private static func buildAccessoryView(_ request: ExecApprovalPromptRequest) -> NSView {
+        let stack = NSStackView()
+        stack.orientation = .vertical
+        stack.spacing = 8
+        stack.alignment = .leading
+        stack.translatesAutoresizingMaskIntoConstraints = false
+        stack.widthAnchor.constraint(greaterThanOrEqualToConstant: 380).isActive = true
+
+        let commandTitle = NSTextField(labelWithString: "Command")
+        commandTitle.font = NSFont.boldSystemFont(ofSize: NSFont.systemFontSize)
+        stack.addArrangedSubview(commandTitle)
+
+        let commandText = NSTextView()
+        commandText.isEditable = false
+        commandText.isSelectable = true
+        commandText.drawsBackground = true
+        commandText.backgroundColor = NSColor.textBackgroundColor
+        commandText.font = NSFont.monospacedSystemFont(ofSize: NSFont.systemFontSize, weight: .regular)
+        commandText.string = request.command
+        commandText.textContainerInset = NSSize(width: 6, height: 6)
+        commandText.textContainer?.lineFragmentPadding = 0
+        commandText.textContainer?.widthTracksTextView = true
+        commandText.isHorizontallyResizable = false
+        commandText.isVerticallyResizable = true
+
+        let commandScroll = NSScrollView()
+        commandScroll.borderType = .lineBorder
+        commandScroll.hasVerticalScroller = true
+        commandScroll.hasHorizontalScroller = false
+        commandScroll.autohidesScrollers = true
+        commandScroll.documentView = commandText
+        commandScroll.translatesAutoresizingMaskIntoConstraints = false
+        commandScroll.widthAnchor.constraint(greaterThanOrEqualToConstant: 380).isActive = true
+        commandScroll.widthAnchor.constraint(lessThanOrEqualToConstant: 440).isActive = true
+        commandScroll.heightAnchor.constraint(greaterThanOrEqualToConstant: 56).isActive = true
+        commandScroll.heightAnchor.constraint(lessThanOrEqualToConstant: 120).isActive = true
+        stack.addArrangedSubview(commandScroll)
+
+        let contextTitle = NSTextField(labelWithString: "Context")
+        contextTitle.font = NSFont.boldSystemFont(ofSize: NSFont.systemFontSize)
+        stack.addArrangedSubview(contextTitle)
+
+        let contextStack = NSStackView()
+        contextStack.orientation = .vertical
+        contextStack.spacing = 4
+        contextStack.alignment = .leading
+
+        let trimmedCwd = request.cwd?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        if !trimmedCwd.isEmpty {
+            self.addDetailRow(title: "Working directory", value: trimmedCwd, to: contextStack)
+        }
+        let trimmedAgent = request.agentId?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        if !trimmedAgent.isEmpty {
+            self.addDetailRow(title: "Agent", value: trimmedAgent, to: contextStack)
+        }
+        let trimmedPath = request.resolvedPath?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        if !trimmedPath.isEmpty {
+            self.addDetailRow(title: "Executable", value: trimmedPath, to: contextStack)
+        }
+        let trimmedHost = request.host?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        if !trimmedHost.isEmpty {
+            self.addDetailRow(title: "Host", value: trimmedHost, to: contextStack)
+        }
+        if let security = request.security?.trimmingCharacters(in: .whitespacesAndNewlines), !security.isEmpty {
+            self.addDetailRow(title: "Security", value: security, to: contextStack)
+        }
+        if let ask = request.ask?.trimmingCharacters(in: .whitespacesAndNewlines), !ask.isEmpty {
+            self.addDetailRow(title: "Ask mode", value: ask, to: contextStack)
+        }
+
+        if contextStack.arrangedSubviews.isEmpty {
+            let empty = NSTextField(labelWithString: "No additional context provided.")
+            empty.textColor = NSColor.secondaryLabelColor
+            empty.font = NSFont.systemFont(ofSize: NSFont.smallSystemFontSize)
+            contextStack.addArrangedSubview(empty)
+        }
+
+        stack.addArrangedSubview(contextStack)
+
+        let footer = NSTextField(labelWithString: "This runs on this machine.")
+        footer.textColor = NSColor.secondaryLabelColor
+        footer.font = NSFont.systemFont(ofSize: NSFont.smallSystemFontSize)
+        stack.addArrangedSubview(footer)
+
+        return stack
+    }
+
+    @MainActor
+    private static func addDetailRow(title: String, value: String, to stack: NSStackView) {
+        let row = NSStackView()
+        row.orientation = .horizontal
+        row.spacing = 6
+        row.alignment = .firstBaseline
+
+        let titleLabel = NSTextField(labelWithString: "\(title):")
+        titleLabel.font = NSFont.systemFont(ofSize: NSFont.smallSystemFontSize, weight: .semibold)
+        titleLabel.textColor = NSColor.secondaryLabelColor
+
+        let valueLabel = NSTextField(labelWithString: value)
+        valueLabel.font = NSFont.systemFont(ofSize: NSFont.smallSystemFontSize)
+        valueLabel.lineBreakMode = .byTruncatingMiddle
+        valueLabel.setContentCompressionResistancePriority(.defaultLow, for: .horizontal)
+
+        row.addArrangedSubview(titleLabel)
+        row.addArrangedSubview(valueLabel)
+        stack.addArrangedSubview(row)
+    }
+}
+
+@MainActor
+private enum ExecHostExecutor {
+    private typealias ExecApprovalContext = ExecApprovalEvaluation
+
+    static func handle(_ request: ExecHostRequest) async -> ExecHostResponse {
+        let validatedRequest: ExecHostValidatedRequest
+        switch ExecHostRequestEvaluator.validateRequest(request) {
+        case let .success(request):
+            validatedRequest = request
+        case let .failure(error):
+            return self.errorResponse(error)
+        }
+
+        let context = await self.buildContext(
+            request: request,
+            command: validatedRequest.command,
+            rawCommand: validatedRequest.displayCommand)
+
+        switch ExecHostRequestEvaluator.evaluate(
+            context: context,
+            approvalDecision: request.approvalDecision)
+        {
+        case let .deny(error):
+            return self.errorResponse(error)
+        case .allow:
+            break
+        case .requiresPrompt:
+            let decision = ExecApprovalsPromptPresenter.prompt(
+                ExecApprovalPromptRequest(
+                    command: context.displayCommand,
+                    cwd: request.cwd,
+                    host: "node",
+                    security: context.security.rawValue,
+                    ask: context.ask.rawValue,
+                    agentId: context.agentId,
+                    resolvedPath: context.resolution?.resolvedPath,
+                    sessionKey: request.sessionKey))
+
+            let followupDecision: ExecApprovalDecision
+            switch decision {
+            case .deny:
+                followupDecision = .deny
+            case .allowAlways:
+                followupDecision = .allowAlways
+                self.persistAllowlistEntry(decision: decision, context: context)
+            case .allowOnce:
+                followupDecision = .allowOnce
+            }
+
+            switch ExecHostRequestEvaluator.evaluate(
+                context: context,
+                approvalDecision: followupDecision)
+            {
+            case let .deny(error):
+                return self.errorResponse(error)
+            case .allow:
+                break
+            case .requiresPrompt:
+                return self.errorResponse(
+                    code: "INVALID_REQUEST",
+                    message: "unexpected approval state",
+                    reason: "invalid")
+            }
+        }
+
+        self.persistAllowlistEntry(decision: request.approvalDecision, context: context)
+
+        if context.allowlistSatisfied {
+            var seenPatterns = Set<String>()
+            for (idx, match) in context.allowlistMatches.enumerated() {
+                if !seenPatterns.insert(match.pattern).inserted {
+                    continue
+                }
+                let resolvedPath = idx < context.allowlistResolutions.count
+                    ? context.allowlistResolutions[idx].resolvedPath
+                    : nil
+                ExecApprovalsStore.recordAllowlistUse(
+                    agentId: context.agentId,
+                    pattern: match.pattern,
+                    command: context.displayCommand,
+                    resolvedPath: resolvedPath)
+            }
+        }
+
+        if let errorResponse = await self.ensureScreenRecordingAccess(request.needsScreenRecording) {
+            return errorResponse
+        }
+
+        return await self.runCommand(
+            command: validatedRequest.command,
+            cwd: request.cwd,
+            env: context.env,
+            timeoutMs: request.timeoutMs)
+    }
+
+    private static func buildContext(
+        request: ExecHostRequest,
+        command: [String],
+        rawCommand: String?) async -> ExecApprovalContext
+    {
+        await ExecApprovalEvaluator.evaluate(
+            command: command,
+            rawCommand: rawCommand,
+            cwd: request.cwd,
+            envOverrides: request.env,
+            agentId: request.agentId)
+    }
+
+    private static func persistAllowlistEntry(
+        decision: ExecApprovalDecision?,
+        context: ExecApprovalContext)
+    {
+        guard decision == .allowAlways, context.security == .allowlist else { return }
+        var seenPatterns = Set<String>()
+        for candidate in context.allowlistResolutions {
+            guard let pattern = ExecApprovalHelpers.allowlistPattern(
+                command: context.command,
+                resolution: candidate)
+            else {
+                continue
+            }
+            if seenPatterns.insert(pattern).inserted {
+                ExecApprovalsStore.addAllowlistEntry(agentId: context.agentId, pattern: pattern)
+            }
+        }
+    }
+
+    private static func ensureScreenRecordingAccess(_ needsScreenRecording: Bool?) async -> ExecHostResponse? {
+        guard needsScreenRecording == true else { return nil }
+        let authorized = await PermissionManager
+            .status([.screenRecording])[.screenRecording] ?? false
+        if authorized { return nil }
+        return self.errorResponse(
+            code: "UNAVAILABLE",
+            message: "PERMISSION_MISSING: screenRecording",
+            reason: "permission:screenRecording")
+    }
+
+    private static func runCommand(
+        command: [String],
+        cwd: String?,
+        env: [String: String]?,
+        timeoutMs: Int?) async -> ExecHostResponse
+    {
+        let timeoutSec = timeoutMs.flatMap { Double($0) / 1000.0 }
+        let result = await Task.detached { () -> ShellExecutor.ShellResult in
+            await ShellExecutor.runDetailed(
+                command: command,
+                cwd: cwd,
+                env: env,
+                timeout: timeoutSec)
+        }.value
+        let payload = ExecHostRunResult(
+            exitCode: result.exitCode,
+            timedOut: result.timedOut,
+            success: result.success,
+            stdout: result.stdout,
+            stderr: result.stderr,
+            error: result.errorMessage)
+        return self.successResponse(payload)
+    }
+
+    private static func errorResponse(
+        _ error: ExecHostError) -> ExecHostResponse
+    {
+        ExecHostResponse(
+            type: "response",
+            id: UUID().uuidString,
+            ok: false,
+            payload: nil,
+            error: error)
+    }
+
+    private static func errorResponse(
+        code: String,
+        message: String,
+        reason: String?) -> ExecHostResponse
+    {
+        ExecHostResponse(
+            type: "exec-res",
+            id: UUID().uuidString,
+            ok: false,
+            payload: nil,
+            error: ExecHostError(code: code, message: message, reason: reason))
+    }
+
+    private static func successResponse(_ payload: ExecHostRunResult) -> ExecHostResponse {
+        ExecHostResponse(
+            type: "exec-res",
+            id: UUID().uuidString,
+            ok: true,
+            payload: payload,
+            error: nil)
+    }
+}
+
+private final class ExecApprovalsSocketServer: @unchecked Sendable {
+    private let logger = Logger(subsystem: "ai.openclaw", category: "exec-approvals.socket")
+    private let socketPath: String
+    private let token: String
+    private let onPrompt: @Sendable (ExecApprovalPromptRequest) async -> ExecApprovalDecision
+    private let onExec: @Sendable (ExecHostRequest) async -> ExecHostResponse
+    private var socketFD: Int32 = -1
+    private var acceptTask: Task<Void, Never>?
+    private var isRunning = false
+
+    init(
+        socketPath: String,
+        token: String,
+        onPrompt: @escaping @Sendable (ExecApprovalPromptRequest) async -> ExecApprovalDecision,
+        onExec: @escaping @Sendable (ExecHostRequest) async -> ExecHostResponse)
+    {
+        self.socketPath = socketPath
+        self.token = token
+        self.onPrompt = onPrompt
+        self.onExec = onExec
+    }
+
+    func start() {
+        guard !self.isRunning else { return }
+        self.isRunning = true
+        self.acceptTask = Task.detached { [weak self] in
+            await self?.runAcceptLoop()
+        }
+    }
+
+    func stop() {
+        self.isRunning = false
+        self.acceptTask?.cancel()
+        self.acceptTask = nil
+        if self.socketFD >= 0 {
+            close(self.socketFD)
+            self.socketFD = -1
+        }
+        if !self.socketPath.isEmpty {
+            unlink(self.socketPath)
+        }
+    }
+
+    private func runAcceptLoop() async {
+        let fd = self.openSocket()
+        guard fd >= 0 else {
+            self.isRunning = false
+            return
+        }
+        self.socketFD = fd
+        while self.isRunning {
+            var addr = sockaddr_un()
+            var len = socklen_t(MemoryLayout.size(ofValue: addr))
+            let client = withUnsafeMutablePointer(to: &addr) { ptr in
+                ptr.withMemoryRebound(to: sockaddr.self, capacity: 1) { rebound in
+                    accept(fd, rebound, &len)
+                }
+            }
+            if client < 0 {
+                if errno == EINTR { continue }
+                break
+            }
+            Task.detached { [weak self] in
+                await self?.handleClient(fd: client)
+            }
+        }
+    }
+
+    private func openSocket() -> Int32 {
+        let fd = socket(AF_UNIX, SOCK_STREAM, 0)
+        guard fd >= 0 else {
+            self.logger.error("exec approvals socket create failed")
+            return -1
+        }
+        unlink(self.socketPath)
+        var addr = sockaddr_un()
+        addr.sun_family = sa_family_t(AF_UNIX)
+        let maxLen = MemoryLayout.size(ofValue: addr.sun_path)
+        if self.socketPath.utf8.count >= maxLen {
+            self.logger.error("exec approvals socket path too long")
+            close(fd)
+            return -1
+        }
+        self.socketPath.withCString { cstr in
+            withUnsafeMutablePointer(to: &addr.sun_path) { ptr in
+                let raw = UnsafeMutableRawPointer(ptr).assumingMemoryBound(to: Int8.self)
+                memset(raw, 0, maxLen)
+                strncpy(raw, cstr, maxLen - 1)
+            }
+        }
+        let size = socklen_t(MemoryLayout.size(ofValue: addr))
+        let result = withUnsafePointer(to: &addr) { ptr in
+            ptr.withMemoryRebound(to: sockaddr.self, capacity: 1) { rebound in
+                bind(fd, rebound, size)
+            }
+        }
+        if result != 0 {
+            self.logger.error("exec approvals socket bind failed")
+            close(fd)
+            return -1
+        }
+        if listen(fd, 16) != 0 {
+            self.logger.error("exec approvals socket listen failed")
+            close(fd)
+            return -1
+        }
+        chmod(self.socketPath, 0o600)
+        self.logger.info("exec approvals socket listening at \(self.socketPath, privacy: .public)")
+        return fd
+    }
+
+    private func handleClient(fd: Int32) async {
+        let handle = FileHandle(fileDescriptor: fd, closeOnDealloc: true)
+        do {
+            guard self.isAllowedPeer(fd: fd) else {
+                try self.sendApprovalResponse(handle: handle, id: UUID().uuidString, decision: .deny)
+                return
+            }
+            guard let line = try self.readLine(from: handle, maxBytes: 256_000),
+                  let data = line.data(using: .utf8)
+            else {
+                return
+            }
+            guard
+                let envelope = try JSONSerialization.jsonObject(with: data) as? [String: Any],
+                let type = envelope["type"] as? String
+            else {
+                return
+            }
+
+            if type == "request" {
+                let request = try JSONDecoder().decode(ExecApprovalSocketRequest.self, from: data)
+                guard request.token == self.token else {
+                    try self.sendApprovalResponse(handle: handle, id: request.id, decision: .deny)
+                    return
+                }
+                let decision = await self.onPrompt(request.request)
+                try self.sendApprovalResponse(handle: handle, id: request.id, decision: decision)
+                return
+            }
+
+            if type == "exec" {
+                let request = try JSONDecoder().decode(ExecHostSocketRequest.self, from: data)
+                let response = await self.handleExecRequest(request)
+                try self.sendExecResponse(handle: handle, response: response)
+                return
+            }
+        } catch {
+            self.logger.error("exec approvals socket handling failed: \(error.localizedDescription, privacy: .public)")
+        }
+    }
+
+    private func readLine(from handle: FileHandle, maxBytes: Int) throws -> String? {
+        var buffer = Data()
+        while buffer.count < maxBytes {
+            let chunk = try handle.read(upToCount: 4096) ?? Data()
+            if chunk.isEmpty { break }
+            buffer.append(chunk)
+            if buffer.contains(0x0A) { break }
+        }
+        guard let newlineIndex = buffer.firstIndex(of: 0x0A) else {
+            guard !buffer.isEmpty else { return nil }
+            return String(data: buffer, encoding: .utf8)
+        }
+        let lineData = buffer.subdata(in: 0..<newlineIndex)
+        return String(data: lineData, encoding: .utf8)
+    }
+
+    private func sendApprovalResponse(
+        handle: FileHandle,
+        id: String,
+        decision: ExecApprovalDecision) throws
+    {
+        let response = ExecApprovalSocketDecision(type: "decision", id: id, decision: decision)
+        let data = try JSONEncoder().encode(response)
+        var payload = data
+        payload.append(0x0A)
+        try handle.write(contentsOf: payload)
+    }
+
+    private func sendExecResponse(handle: FileHandle, response: ExecHostResponse) throws {
+        let data = try JSONEncoder().encode(response)
+        var payload = data
+        payload.append(0x0A)
+        try handle.write(contentsOf: payload)
+    }
+
+    private func isAllowedPeer(fd: Int32) -> Bool {
+        var uid = uid_t(0)
+        var gid = gid_t(0)
+        if getpeereid(fd, &uid, &gid) != 0 {
+            return false
+        }
+        return uid == geteuid()
+    }
+
+    private func handleExecRequest(_ request: ExecHostSocketRequest) async -> ExecHostResponse {
+        let nowMs = Int(Date().timeIntervalSince1970 * 1000)
+        if abs(nowMs - request.ts) > 10000 {
+            return ExecHostResponse(
+                type: "exec-res",
+                id: request.id,
+                ok: false,
+                payload: nil,
+                error: ExecHostError(code: "INVALID_REQUEST", message: "expired request", reason: "ttl"))
+        }
+        let expected = self.hmacHex(nonce: request.nonce, ts: request.ts, requestJson: request.requestJson)
+        if expected != request.hmac {
+            return ExecHostResponse(
+                type: "exec-res",
+                id: request.id,
+                ok: false,
+                payload: nil,
+                error: ExecHostError(code: "INVALID_REQUEST", message: "invalid auth", reason: "hmac"))
+        }
+        guard let requestData = request.requestJson.data(using: .utf8),
+              let payload = try? JSONDecoder().decode(ExecHostRequest.self, from: requestData)
+        else {
+            return ExecHostResponse(
+                type: "exec-res",
+                id: request.id,
+                ok: false,
+                payload: nil,
+                error: ExecHostError(code: "INVALID_REQUEST", message: "invalid payload", reason: "json"))
+        }
+        let response = await self.onExec(payload)
+        return ExecHostResponse(
+            type: "exec-res",
+            id: request.id,
+            ok: response.ok,
+            payload: response.payload,
+            error: response.error)
+    }
+
+    private func hmacHex(nonce: String, ts: Int, requestJson: String) -> String {
+        let key = SymmetricKey(data: Data(self.token.utf8))
+        let message = "\(nonce):\(ts):\(requestJson)"
+        let mac = HMAC<SHA256>.authenticationCode(for: Data(message.utf8), using: key)
+        return mac.map { String(format: "%02x", $0) }.joined()
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/ExecCommandResolution.swift

@@ -0,0 +1,265 @@
+import Foundation
+
+struct ExecCommandResolution: Sendable {
+    let rawExecutable: String
+    let resolvedPath: String?
+    let executableName: String
+    let cwd: String?
+
+    static func resolve(
+        command: [String],
+        rawCommand: String?,
+        cwd: String?,
+        env: [String: String]?) -> ExecCommandResolution?
+    {
+        let trimmedRaw = rawCommand?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        if !trimmedRaw.isEmpty, let token = self.parseFirstToken(trimmedRaw) {
+            return self.resolveExecutable(rawExecutable: token, cwd: cwd, env: env)
+        }
+        return self.resolve(command: command, cwd: cwd, env: env)
+    }
+
+    static func resolveForAllowlist(
+        command: [String],
+        rawCommand: String?,
+        cwd: String?,
+        env: [String: String]?) -> [ExecCommandResolution]
+    {
+        let shell = ExecShellWrapperParser.extract(command: command, rawCommand: rawCommand)
+        if shell.isWrapper {
+            guard let shellCommand = shell.command,
+                  let segments = self.splitShellCommandChain(shellCommand)
+            else {
+                // Fail closed: if we cannot safely parse a shell wrapper payload,
+                // treat this as an allowlist miss and require approval.
+                return []
+            }
+            var resolutions: [ExecCommandResolution] = []
+            resolutions.reserveCapacity(segments.count)
+            for segment in segments {
+                guard let token = self.parseFirstToken(segment),
+                      let resolution = self.resolveExecutable(rawExecutable: token, cwd: cwd, env: env)
+                else {
+                    return []
+                }
+                resolutions.append(resolution)
+            }
+            return resolutions
+        }
+
+        guard let resolution = self.resolve(command: command, rawCommand: rawCommand, cwd: cwd, env: env) else {
+            return []
+        }
+        return [resolution]
+    }
+
+    static func resolve(command: [String], cwd: String?, env: [String: String]?) -> ExecCommandResolution? {
+        let effective = ExecEnvInvocationUnwrapper.unwrapDispatchWrappersForResolution(command)
+        guard let raw = effective.first?.trimmingCharacters(in: .whitespacesAndNewlines), !raw.isEmpty else {
+            return nil
+        }
+        return self.resolveExecutable(rawExecutable: raw, cwd: cwd, env: env)
+    }
+
+    private static func resolveExecutable(
+        rawExecutable: String,
+        cwd: String?,
+        env: [String: String]?) -> ExecCommandResolution?
+    {
+        let expanded = rawExecutable.hasPrefix("~") ? (rawExecutable as NSString).expandingTildeInPath : rawExecutable
+        let hasPathSeparator = expanded.contains("/") || expanded.contains("\\")
+        let resolvedPath: String? = {
+            if hasPathSeparator {
+                if expanded.hasPrefix("/") {
+                    return expanded
+                }
+                let base = cwd?.trimmingCharacters(in: .whitespacesAndNewlines)
+                let root = (base?.isEmpty == false) ? base! : FileManager().currentDirectoryPath
+                return URL(fileURLWithPath: root).appendingPathComponent(expanded).path
+            }
+            let searchPaths = self.searchPaths(from: env)
+            return CommandResolver.findExecutable(named: expanded, searchPaths: searchPaths)
+        }()
+        let name = resolvedPath.map { URL(fileURLWithPath: $0).lastPathComponent } ?? expanded
+        return ExecCommandResolution(
+            rawExecutable: expanded,
+            resolvedPath: resolvedPath,
+            executableName: name,
+            cwd: cwd)
+    }
+
+    private static func parseFirstToken(_ command: String) -> String? {
+        let trimmed = command.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return nil }
+        guard let first = trimmed.first else { return nil }
+        if first == "\"" || first == "'" {
+            let rest = trimmed.dropFirst()
+            if let end = rest.firstIndex(of: first) {
+                return String(rest[..<end])
+            }
+            return String(rest)
+        }
+        return trimmed.split(whereSeparator: { $0.isWhitespace }).first.map(String.init)
+    }
+
+    private enum ShellTokenContext {
+        case unquoted
+        case doubleQuoted
+    }
+
+    private struct ShellFailClosedRule {
+        let token: Character
+        let next: Character?
+    }
+
+    private static let shellFailClosedRules: [ShellTokenContext: [ShellFailClosedRule]] = [
+        .unquoted: [
+            ShellFailClosedRule(token: "`", next: nil),
+            ShellFailClosedRule(token: "$", next: "("),
+            ShellFailClosedRule(token: "<", next: "("),
+            ShellFailClosedRule(token: ">", next: "("),
+        ],
+        .doubleQuoted: [
+            ShellFailClosedRule(token: "`", next: nil),
+            ShellFailClosedRule(token: "$", next: "("),
+        ],
+    ]
+
+    private static func splitShellCommandChain(_ command: String) -> [String]? {
+        let trimmed = command.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return nil }
+
+        var segments: [String] = []
+        var current = ""
+        var inSingle = false
+        var inDouble = false
+        var escaped = false
+        let chars = Array(trimmed)
+        var idx = 0
+
+        func appendCurrent() -> Bool {
+            let segment = current.trimmingCharacters(in: .whitespacesAndNewlines)
+            guard !segment.isEmpty else { return false }
+            segments.append(segment)
+            current.removeAll(keepingCapacity: true)
+            return true
+        }
+
+        while idx < chars.count {
+            let ch = chars[idx]
+            let next: Character? = idx + 1 < chars.count ? chars[idx + 1] : nil
+
+            if escaped {
+                current.append(ch)
+                escaped = false
+                idx += 1
+                continue
+            }
+
+            if ch == "\\", !inSingle {
+                current.append(ch)
+                escaped = true
+                idx += 1
+                continue
+            }
+
+            if ch == "'", !inDouble {
+                inSingle.toggle()
+                current.append(ch)
+                idx += 1
+                continue
+            }
+
+            if ch == "\"", !inSingle {
+                inDouble.toggle()
+                current.append(ch)
+                idx += 1
+                continue
+            }
+
+            if !inSingle, self.shouldFailClosedForShell(ch: ch, next: next, inDouble: inDouble) {
+                // Fail closed on command/process substitution in allowlist mode,
+                // including command substitution inside double-quoted shell strings.
+                return nil
+            }
+
+            if !inSingle, !inDouble {
+                let prev: Character? = idx > 0 ? chars[idx - 1] : nil
+                if let delimiterStep = self.chainDelimiterStep(ch: ch, prev: prev, next: next) {
+                    guard appendCurrent() else { return nil }
+                    idx += delimiterStep
+                    continue
+                }
+            }
+
+            current.append(ch)
+            idx += 1
+        }
+
+        if escaped || inSingle || inDouble { return nil }
+        guard appendCurrent() else { return nil }
+        return segments
+    }
+
+    private static func shouldFailClosedForShell(ch: Character, next: Character?, inDouble: Bool) -> Bool {
+        let context: ShellTokenContext = inDouble ? .doubleQuoted : .unquoted
+        guard let rules = self.shellFailClosedRules[context] else {
+            return false
+        }
+        for rule in rules {
+            if ch == rule.token, rule.next == nil || next == rule.next {
+                return true
+            }
+        }
+        return false
+    }
+
+    private static func chainDelimiterStep(ch: Character, prev: Character?, next: Character?) -> Int? {
+        if ch == ";" || ch == "\n" {
+            return 1
+        }
+        if ch == "&" {
+            if next == "&" {
+                return 2
+            }
+            // Keep fd redirections like 2>&1 or &>file intact.
+            let prevIsRedirect = prev == ">"
+            let nextIsRedirect = next == ">"
+            return (!prevIsRedirect && !nextIsRedirect) ? 1 : nil
+        }
+        if ch == "|" {
+            if next == "|" || next == "&" {
+                return 2
+            }
+            return 1
+        }
+        return nil
+    }
+
+    private static func searchPaths(from env: [String: String]?) -> [String] {
+        let raw = env?["PATH"]
+        if let raw, !raw.isEmpty {
+            return raw.split(separator: ":").map(String.init)
+        }
+        return CommandResolver.preferredPaths()
+    }
+}
+
+enum ExecCommandFormatter {
+    static func displayString(for argv: [String]) -> String {
+        argv.map { arg in
+            let trimmed = arg.trimmingCharacters(in: .whitespacesAndNewlines)
+            guard !trimmed.isEmpty else { return "\"\"" }
+            let needsQuotes = trimmed.contains { $0.isWhitespace || $0 == "\"" }
+            if !needsQuotes { return trimmed }
+            let escaped = trimmed.replacingOccurrences(of: "\"", with: "\\\"")
+            return "\"\(escaped)\""
+        }.joined(separator: " ")
+    }
+
+    static func displayString(for argv: [String], rawCommand: String?) -> String {
+        let trimmed = rawCommand?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        if !trimmed.isEmpty { return trimmed }
+        return self.displayString(for: argv)
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/ExecEnvInvocationUnwrapper.swift

@@ -0,0 +1,108 @@
+import Foundation
+
+enum ExecCommandToken {
+    static func basenameLower(_ token: String) -> String {
+        let trimmed = token.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return "" }
+        let normalized = trimmed.replacingOccurrences(of: "\\", with: "/")
+        return normalized.split(separator: "/").last.map { String($0).lowercased() } ?? normalized.lowercased()
+    }
+}
+
+enum ExecEnvInvocationUnwrapper {
+    static let maxWrapperDepth = 4
+
+    private static let optionsWithValue = Set([
+        "-u",
+        "--unset",
+        "-c",
+        "--chdir",
+        "-s",
+        "--split-string",
+        "--default-signal",
+        "--ignore-signal",
+        "--block-signal",
+    ])
+    private static let flagOptions = Set(["-i", "--ignore-environment", "-0", "--null"])
+
+    private static func isEnvAssignment(_ token: String) -> Bool {
+        let pattern = #"^[A-Za-z_][A-Za-z0-9_]*=.*"#
+        return token.range(of: pattern, options: .regularExpression) != nil
+    }
+
+    static func unwrap(_ command: [String]) -> [String]? {
+        var idx = 1
+        var expectsOptionValue = false
+        while idx < command.count {
+            let token = command[idx].trimmingCharacters(in: .whitespacesAndNewlines)
+            if token.isEmpty {
+                idx += 1
+                continue
+            }
+            if expectsOptionValue {
+                expectsOptionValue = false
+                idx += 1
+                continue
+            }
+            if token == "--" || token == "-" {
+                idx += 1
+                break
+            }
+            if self.isEnvAssignment(token) {
+                idx += 1
+                continue
+            }
+            if token.hasPrefix("-"), token != "-" {
+                let lower = token.lowercased()
+                let flag = lower.split(separator: "=", maxSplits: 1).first.map(String.init) ?? lower
+                if self.flagOptions.contains(flag) {
+                    idx += 1
+                    continue
+                }
+                if self.optionsWithValue.contains(flag) {
+                    if !lower.contains("=") {
+                        expectsOptionValue = true
+                    }
+                    idx += 1
+                    continue
+                }
+                if lower.hasPrefix("-u") ||
+                    lower.hasPrefix("-c") ||
+                    lower.hasPrefix("-s") ||
+                    lower.hasPrefix("--unset=") ||
+                    lower.hasPrefix("--chdir=") ||
+                    lower.hasPrefix("--split-string=") ||
+                    lower.hasPrefix("--default-signal=") ||
+                    lower.hasPrefix("--ignore-signal=") ||
+                    lower.hasPrefix("--block-signal=")
+                {
+                    idx += 1
+                    continue
+                }
+                return nil
+            }
+            break
+        }
+        guard idx < command.count else { return nil }
+        return Array(command[idx...])
+    }
+
+    static func unwrapDispatchWrappersForResolution(_ command: [String]) -> [String] {
+        var current = command
+        var depth = 0
+        while depth < self.maxWrapperDepth {
+            guard let token = current.first?.trimmingCharacters(in: .whitespacesAndNewlines), !token.isEmpty else {
+                break
+            }
+            guard ExecCommandToken.basenameLower(token) == "env" else {
+                break
+            }
+            guard let unwrapped = self.unwrap(current), !unwrapped.isEmpty else {
+                break
+            }
+            current = unwrapped
+            depth += 1
+        }
+        return current
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/ExecHostRequestEvaluator.swift

@@ -0,0 +1,84 @@
+import Foundation
+
+struct ExecHostValidatedRequest {
+    let command: [String]
+    let displayCommand: String
+}
+
+enum ExecHostPolicyDecision {
+    case deny(ExecHostError)
+    case requiresPrompt
+    case allow(approvedByAsk: Bool)
+}
+
+enum ExecHostRequestEvaluator {
+    static func validateRequest(_ request: ExecHostRequest) -> Result<ExecHostValidatedRequest, ExecHostError> {
+        let command = request.command.map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }
+        guard !command.isEmpty else {
+            return .failure(
+                ExecHostError(
+                    code: "INVALID_REQUEST",
+                    message: "command required",
+                    reason: "invalid"))
+        }
+
+        let validatedCommand = ExecSystemRunCommandValidator.resolve(
+            command: command,
+            rawCommand: request.rawCommand)
+        switch validatedCommand {
+        case let .ok(resolved):
+            return .success(ExecHostValidatedRequest(command: command, displayCommand: resolved.displayCommand))
+        case let .invalid(message):
+            return .failure(
+                ExecHostError(
+                    code: "INVALID_REQUEST",
+                    message: message,
+                    reason: "invalid"))
+        }
+    }
+
+    static func evaluate(
+        context: ExecApprovalEvaluation,
+        approvalDecision: ExecApprovalDecision?) -> ExecHostPolicyDecision
+    {
+        if context.security == .deny {
+            return .deny(
+                ExecHostError(
+                    code: "UNAVAILABLE",
+                    message: "SYSTEM_RUN_DISABLED: security=deny",
+                    reason: "security=deny"))
+        }
+
+        if approvalDecision == .deny {
+            return .deny(
+                ExecHostError(
+                    code: "UNAVAILABLE",
+                    message: "SYSTEM_RUN_DENIED: user denied",
+                    reason: "user-denied"))
+        }
+
+        let approvedByAsk = approvalDecision != nil
+        let requiresPrompt = ExecApprovalHelpers.requiresAsk(
+            ask: context.ask,
+            security: context.security,
+            allowlistMatch: context.allowlistMatch,
+            skillAllow: context.skillAllow) && approvalDecision == nil
+        if requiresPrompt {
+            return .requiresPrompt
+        }
+
+        if context.security == .allowlist,
+           !context.allowlistSatisfied,
+           !context.skillAllow,
+           !approvedByAsk
+        {
+            return .deny(
+                ExecHostError(
+                    code: "UNAVAILABLE",
+                    message: "SYSTEM_RUN_DENIED: allowlist miss",
+                    reason: "allowlist-miss"))
+        }
+
+        return .allow(approvedByAsk: approvedByAsk)
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/ExecShellWrapperParser.swift

@@ -0,0 +1,108 @@
+import Foundation
+
+enum ExecShellWrapperParser {
+    struct ParsedShellWrapper {
+        let isWrapper: Bool
+        let command: String?
+
+        static let notWrapper = ParsedShellWrapper(isWrapper: false, command: nil)
+    }
+
+    private enum Kind {
+        case posix
+        case cmd
+        case powershell
+    }
+
+    private struct WrapperSpec {
+        let kind: Kind
+        let names: Set<String>
+    }
+
+    private static let posixInlineFlags = Set(["-lc", "-c", "--command"])
+    private static let powershellInlineFlags = Set(["-c", "-command", "--command"])
+
+    private static let wrapperSpecs: [WrapperSpec] = [
+        WrapperSpec(kind: .posix, names: ["ash", "sh", "bash", "zsh", "dash", "ksh", "fish"]),
+        WrapperSpec(kind: .cmd, names: ["cmd.exe", "cmd"]),
+        WrapperSpec(kind: .powershell, names: ["powershell", "powershell.exe", "pwsh", "pwsh.exe"]),
+    ]
+
+    static func extract(command: [String], rawCommand: String?) -> ParsedShellWrapper {
+        let trimmedRaw = rawCommand?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        let preferredRaw = trimmedRaw.isEmpty ? nil : trimmedRaw
+        return self.extract(command: command, preferredRaw: preferredRaw, depth: 0)
+    }
+
+    private static func extract(command: [String], preferredRaw: String?, depth: Int) -> ParsedShellWrapper {
+        guard depth < ExecEnvInvocationUnwrapper.maxWrapperDepth else {
+            return .notWrapper
+        }
+        guard let token0 = command.first?.trimmingCharacters(in: .whitespacesAndNewlines), !token0.isEmpty else {
+            return .notWrapper
+        }
+
+        let base0 = ExecCommandToken.basenameLower(token0)
+        if base0 == "env" {
+            guard let unwrapped = ExecEnvInvocationUnwrapper.unwrap(command) else {
+                return .notWrapper
+            }
+            return self.extract(command: unwrapped, preferredRaw: preferredRaw, depth: depth + 1)
+        }
+
+        guard let spec = self.wrapperSpecs.first(where: { $0.names.contains(base0) }) else {
+            return .notWrapper
+        }
+        guard let payload = self.extractPayload(command: command, spec: spec) else {
+            return .notWrapper
+        }
+        let normalized = preferredRaw ?? payload
+        return ParsedShellWrapper(isWrapper: true, command: normalized)
+    }
+
+    private static func extractPayload(command: [String], spec: WrapperSpec) -> String? {
+        switch spec.kind {
+        case .posix:
+            self.extractPosixInlineCommand(command)
+        case .cmd:
+            self.extractCmdInlineCommand(command)
+        case .powershell:
+            self.extractPowerShellInlineCommand(command)
+        }
+    }
+
+    private static func extractPosixInlineCommand(_ command: [String]) -> String? {
+        let flag = command.count > 1 ? command[1].trimmingCharacters(in: .whitespacesAndNewlines) : ""
+        guard self.posixInlineFlags.contains(flag.lowercased()) else {
+            return nil
+        }
+        let payload = command.count > 2 ? command[2].trimmingCharacters(in: .whitespacesAndNewlines) : ""
+        return payload.isEmpty ? nil : payload
+    }
+
+    private static func extractCmdInlineCommand(_ command: [String]) -> String? {
+        guard let idx = command
+            .firstIndex(where: { $0.trimmingCharacters(in: .whitespacesAndNewlines).lowercased() == "/c" })
+        else {
+            return nil
+        }
+        let tail = command.suffix(from: command.index(after: idx)).joined(separator: " ")
+        let payload = tail.trimmingCharacters(in: .whitespacesAndNewlines)
+        return payload.isEmpty ? nil : payload
+    }
+
+    private static func extractPowerShellInlineCommand(_ command: [String]) -> String? {
+        for idx in 1..<command.count {
+            let token = command[idx].trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+            if token.isEmpty { continue }
+            if token == "--" { break }
+            if self.powershellInlineFlags.contains(token) {
+                let payload = idx + 1 < command.count
+                    ? command[idx + 1].trimmingCharacters(in: .whitespacesAndNewlines)
+                    : ""
+                return payload.isEmpty ? nil : payload
+            }
+        }
+        return nil
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/ExecSystemRunCommandValidator.swift

@@ -0,0 +1,414 @@
+import Foundation
+
+enum ExecSystemRunCommandValidator {
+    struct ResolvedCommand {
+        let displayCommand: String
+    }
+
+    enum ValidationResult {
+        case ok(ResolvedCommand)
+        case invalid(message: String)
+    }
+
+    private static let shellWrapperNames = Set([
+        "ash",
+        "bash",
+        "cmd",
+        "dash",
+        "fish",
+        "ksh",
+        "powershell",
+        "pwsh",
+        "sh",
+        "zsh",
+    ])
+
+    private static let posixOrPowerShellInlineWrapperNames = Set([
+        "ash",
+        "bash",
+        "dash",
+        "fish",
+        "ksh",
+        "powershell",
+        "pwsh",
+        "sh",
+        "zsh",
+    ])
+
+    private static let shellMultiplexerWrapperNames = Set(["busybox", "toybox"])
+    private static let posixInlineCommandFlags = Set(["-lc", "-c", "--command"])
+    private static let powershellInlineCommandFlags = Set(["-c", "-command", "--command"])
+
+    private static let envOptionsWithValue = Set([
+        "-u",
+        "--unset",
+        "-c",
+        "--chdir",
+        "-s",
+        "--split-string",
+        "--default-signal",
+        "--ignore-signal",
+        "--block-signal",
+    ])
+    private static let envFlagOptions = Set(["-i", "--ignore-environment", "-0", "--null"])
+    private static let envInlineValuePrefixes = [
+        "-u",
+        "-c",
+        "-s",
+        "--unset=",
+        "--chdir=",
+        "--split-string=",
+        "--default-signal=",
+        "--ignore-signal=",
+        "--block-signal=",
+    ]
+
+    private struct EnvUnwrapResult {
+        let argv: [String]
+        let usesModifiers: Bool
+    }
+
+    static func resolve(command: [String], rawCommand: String?) -> ValidationResult {
+        let normalizedRaw = self.normalizeRaw(rawCommand)
+        let shell = ExecShellWrapperParser.extract(command: command, rawCommand: nil)
+        let shellCommand = shell.isWrapper ? self.trimmedNonEmpty(shell.command) : nil
+
+        let envManipulationBeforeShellWrapper = self.hasEnvManipulationBeforeShellWrapper(command)
+        let shellWrapperPositionalArgv = self.hasTrailingPositionalArgvAfterInlineCommand(command)
+        let mustBindDisplayToFullArgv = envManipulationBeforeShellWrapper || shellWrapperPositionalArgv
+
+        let inferred: String = if let shellCommand, !mustBindDisplayToFullArgv {
+            shellCommand
+        } else {
+            ExecCommandFormatter.displayString(for: command)
+        }
+
+        if let raw = normalizedRaw, raw != inferred {
+            return .invalid(message: "INVALID_REQUEST: rawCommand does not match command")
+        }
+
+        return .ok(ResolvedCommand(displayCommand: normalizedRaw ?? inferred))
+    }
+
+    private static func normalizeRaw(_ rawCommand: String?) -> String? {
+        let trimmed = rawCommand?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        return trimmed.isEmpty ? nil : trimmed
+    }
+
+    private static func trimmedNonEmpty(_ value: String?) -> String? {
+        let trimmed = value?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        return trimmed.isEmpty ? nil : trimmed
+    }
+
+    private static func normalizeExecutableToken(_ token: String) -> String {
+        let base = ExecCommandToken.basenameLower(token)
+        if base.hasSuffix(".exe") {
+            return String(base.dropLast(4))
+        }
+        return base
+    }
+
+    private static func isEnvAssignment(_ token: String) -> Bool {
+        token.range(of: #"^[A-Za-z_][A-Za-z0-9_]*=.*"#, options: .regularExpression) != nil
+    }
+
+    private static func hasEnvInlineValuePrefix(_ lowerToken: String) -> Bool {
+        self.envInlineValuePrefixes.contains { lowerToken.hasPrefix($0) }
+    }
+
+    private static func unwrapEnvInvocationWithMetadata(_ argv: [String]) -> EnvUnwrapResult? {
+        var idx = 1
+        var expectsOptionValue = false
+        var usesModifiers = false
+
+        while idx < argv.count {
+            let token = argv[idx].trimmingCharacters(in: .whitespacesAndNewlines)
+            if token.isEmpty {
+                idx += 1
+                continue
+            }
+            if expectsOptionValue {
+                expectsOptionValue = false
+                usesModifiers = true
+                idx += 1
+                continue
+            }
+            if token == "--" || token == "-" {
+                idx += 1
+                break
+            }
+            if self.isEnvAssignment(token) {
+                usesModifiers = true
+                idx += 1
+                continue
+            }
+            if !token.hasPrefix("-") || token == "-" {
+                break
+            }
+
+            let lower = token.lowercased()
+            let flag = lower.split(separator: "=", maxSplits: 1).first.map(String.init) ?? lower
+            if self.envFlagOptions.contains(flag) {
+                usesModifiers = true
+                idx += 1
+                continue
+            }
+            if self.envOptionsWithValue.contains(flag) {
+                usesModifiers = true
+                if !lower.contains("=") {
+                    expectsOptionValue = true
+                }
+                idx += 1
+                continue
+            }
+            if self.hasEnvInlineValuePrefix(lower) {
+                usesModifiers = true
+                idx += 1
+                continue
+            }
+            return nil
+        }
+
+        if expectsOptionValue {
+            return nil
+        }
+        guard idx < argv.count else {
+            return nil
+        }
+        return EnvUnwrapResult(argv: Array(argv[idx...]), usesModifiers: usesModifiers)
+    }
+
+    private static func unwrapShellMultiplexerInvocation(_ argv: [String]) -> [String]? {
+        guard let token0 = self.trimmedNonEmpty(argv.first) else {
+            return nil
+        }
+        let wrapper = self.normalizeExecutableToken(token0)
+        guard self.shellMultiplexerWrapperNames.contains(wrapper) else {
+            return nil
+        }
+
+        var appletIndex = 1
+        if appletIndex < argv.count, argv[appletIndex].trimmingCharacters(in: .whitespacesAndNewlines) == "--" {
+            appletIndex += 1
+        }
+        guard appletIndex < argv.count else {
+            return nil
+        }
+        let applet = argv[appletIndex].trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !applet.isEmpty else {
+            return nil
+        }
+        let normalizedApplet = self.normalizeExecutableToken(applet)
+        guard self.shellWrapperNames.contains(normalizedApplet) else {
+            return nil
+        }
+        return Array(argv[appletIndex...])
+    }
+
+    private static func hasEnvManipulationBeforeShellWrapper(
+        _ argv: [String],
+        depth: Int = 0,
+        envManipulationSeen: Bool = false) -> Bool
+    {
+        if depth >= ExecEnvInvocationUnwrapper.maxWrapperDepth {
+            return false
+        }
+        guard let token0 = self.trimmedNonEmpty(argv.first) else {
+            return false
+        }
+
+        let normalized = self.normalizeExecutableToken(token0)
+        if normalized == "env" {
+            guard let envUnwrap = self.unwrapEnvInvocationWithMetadata(argv) else {
+                return false
+            }
+            return self.hasEnvManipulationBeforeShellWrapper(
+                envUnwrap.argv,
+                depth: depth + 1,
+                envManipulationSeen: envManipulationSeen || envUnwrap.usesModifiers)
+        }
+
+        if let shellMultiplexer = self.unwrapShellMultiplexerInvocation(argv) {
+            return self.hasEnvManipulationBeforeShellWrapper(
+                shellMultiplexer,
+                depth: depth + 1,
+                envManipulationSeen: envManipulationSeen)
+        }
+
+        guard self.shellWrapperNames.contains(normalized) else {
+            return false
+        }
+        guard self.extractShellInlinePayload(argv, normalizedWrapper: normalized) != nil else {
+            return false
+        }
+        return envManipulationSeen
+    }
+
+    private static func hasTrailingPositionalArgvAfterInlineCommand(_ argv: [String]) -> Bool {
+        let wrapperArgv = self.unwrapShellWrapperArgv(argv)
+        guard let token0 = self.trimmedNonEmpty(wrapperArgv.first) else {
+            return false
+        }
+        let wrapper = self.normalizeExecutableToken(token0)
+        guard self.posixOrPowerShellInlineWrapperNames.contains(wrapper) else {
+            return false
+        }
+
+        let inlineCommandIndex: Int? = if wrapper == "powershell" || wrapper == "pwsh" {
+            self.resolveInlineCommandTokenIndex(
+                wrapperArgv,
+                flags: self.powershellInlineCommandFlags,
+                allowCombinedC: false)
+        } else {
+            self.resolveInlineCommandTokenIndex(
+                wrapperArgv,
+                flags: self.posixInlineCommandFlags,
+                allowCombinedC: true)
+        }
+        guard let inlineCommandIndex else {
+            return false
+        }
+        let start = inlineCommandIndex + 1
+        guard start < wrapperArgv.count else {
+            return false
+        }
+        return wrapperArgv[start...].contains { !$0.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty }
+    }
+
+    private static func unwrapShellWrapperArgv(_ argv: [String]) -> [String] {
+        var current = argv
+        for _ in 0..<ExecEnvInvocationUnwrapper.maxWrapperDepth {
+            guard let token0 = self.trimmedNonEmpty(current.first) else {
+                break
+            }
+            let normalized = self.normalizeExecutableToken(token0)
+            if normalized == "env" {
+                guard let envUnwrap = self.unwrapEnvInvocationWithMetadata(current),
+                      !envUnwrap.usesModifiers,
+                      !envUnwrap.argv.isEmpty
+                else {
+                    break
+                }
+                current = envUnwrap.argv
+                continue
+            }
+            if let shellMultiplexer = self.unwrapShellMultiplexerInvocation(current) {
+                current = shellMultiplexer
+                continue
+            }
+            break
+        }
+        return current
+    }
+
+    private static func resolveInlineCommandTokenIndex(
+        _ argv: [String],
+        flags: Set<String>,
+        allowCombinedC: Bool) -> Int?
+    {
+        var idx = 1
+        while idx < argv.count {
+            let token = argv[idx].trimmingCharacters(in: .whitespacesAndNewlines)
+            if token.isEmpty {
+                idx += 1
+                continue
+            }
+            let lower = token.lowercased()
+            if lower == "--" {
+                break
+            }
+            if flags.contains(lower) {
+                return idx + 1 < argv.count ? idx + 1 : nil
+            }
+            if allowCombinedC, let inlineOffset = self.combinedCommandInlineOffset(token) {
+                let inline = String(token.dropFirst(inlineOffset))
+                    .trimmingCharacters(in: .whitespacesAndNewlines)
+                if !inline.isEmpty {
+                    return idx
+                }
+                return idx + 1 < argv.count ? idx + 1 : nil
+            }
+            idx += 1
+        }
+        return nil
+    }
+
+    private static func combinedCommandInlineOffset(_ token: String) -> Int? {
+        let chars = Array(token.lowercased())
+        guard chars.count >= 2, chars[0] == "-", chars[1] != "-" else {
+            return nil
+        }
+        if chars.dropFirst().contains("-") {
+            return nil
+        }
+        guard let commandIndex = chars.firstIndex(of: "c"), commandIndex > 0 else {
+            return nil
+        }
+        return commandIndex + 1
+    }
+
+    private static func extractShellInlinePayload(
+        _ argv: [String],
+        normalizedWrapper: String) -> String?
+    {
+        if normalizedWrapper == "cmd" {
+            return self.extractCmdInlineCommand(argv)
+        }
+        if normalizedWrapper == "powershell" || normalizedWrapper == "pwsh" {
+            return self.extractInlineCommandByFlags(
+                argv,
+                flags: self.powershellInlineCommandFlags,
+                allowCombinedC: false)
+        }
+        return self.extractInlineCommandByFlags(
+            argv,
+            flags: self.posixInlineCommandFlags,
+            allowCombinedC: true)
+    }
+
+    private static func extractInlineCommandByFlags(
+        _ argv: [String],
+        flags: Set<String>,
+        allowCombinedC: Bool) -> String?
+    {
+        var idx = 1
+        while idx < argv.count {
+            let token = argv[idx].trimmingCharacters(in: .whitespacesAndNewlines)
+            if token.isEmpty {
+                idx += 1
+                continue
+            }
+            let lower = token.lowercased()
+            if lower == "--" {
+                break
+            }
+            if flags.contains(lower) {
+                return self.trimmedNonEmpty(idx + 1 < argv.count ? argv[idx + 1] : nil)
+            }
+            if allowCombinedC, let inlineOffset = self.combinedCommandInlineOffset(token) {
+                let inline = String(token.dropFirst(inlineOffset))
+                if let inlineValue = self.trimmedNonEmpty(inline) {
+                    return inlineValue
+                }
+                return self.trimmedNonEmpty(idx + 1 < argv.count ? argv[idx + 1] : nil)
+            }
+            idx += 1
+        }
+        return nil
+    }
+
+    private static func extractCmdInlineCommand(_ argv: [String]) -> String? {
+        guard let idx = argv.firstIndex(where: {
+            let token = $0.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+            return token == "/c" || token == "/k"
+        }) else {
+            return nil
+        }
+        let tailIndex = idx + 1
+        guard tailIndex < argv.count else {
+            return nil
+        }
+        let payload = argv[tailIndex...].joined(separator: " ").trimmingCharacters(in: .whitespacesAndNewlines)
+        return payload.isEmpty ? nil : payload
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/FileHandle+SafeRead.swift

@@ -0,0 +1,28 @@
+import Foundation
+
+extension FileHandle {
+    /// Reads until EOF using the throwing FileHandle API and returns empty `Data` on failure.
+    ///
+    /// Important: Avoid legacy, non-throwing FileHandle read APIs (e.g. `readDataToEndOfFile()` and
+    /// `availableData`). They can raise Objective-C exceptions when the handle is closed/invalid, which
+    /// will abort the process.
+    func readToEndSafely() -> Data {
+        do {
+            return try self.readToEnd() ?? Data()
+        } catch {
+            return Data()
+        }
+    }
+
+    /// Reads up to `count` bytes using the throwing FileHandle API and returns empty `Data` on failure/EOF.
+    ///
+    /// Important: Use this instead of `availableData` in callbacks like `readabilityHandler` to avoid
+    /// Objective-C exceptions terminating the process.
+    func readSafely(upToCount count: Int) -> Data {
+        do {
+            return try self.read(upToCount: count) ?? Data()
+        } catch {
+            return Data()
+        }
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/GatewayAutostartPolicy.swift

@@ -0,0 +1,14 @@
+import Foundation
+
+enum GatewayAutostartPolicy {
+    static func shouldStartGateway(mode: AppState.ConnectionMode, paused: Bool) -> Bool {
+        mode == .local && !paused
+    }
+
+    static func shouldEnsureLaunchAgent(
+        mode: AppState.ConnectionMode,
+        paused: Bool) -> Bool
+    {
+        self.shouldStartGateway(mode: mode, paused: paused)
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/GatewayConnection.swift

@@ -0,0 +1,742 @@
+import Foundation
+import OpenClawChatUI
+import OpenClawKit
+import OpenClawProtocol
+import OSLog
+
+private let gatewayConnectionLogger = Logger(subsystem: "ai.openclaw", category: "gateway.connection")
+
+enum GatewayAgentChannel: String, Codable, CaseIterable, Sendable {
+    case last
+    case whatsapp
+    case telegram
+    case discord
+    case googlechat
+    case slack
+    case signal
+    case imessage
+    case msteams
+    case bluebubbles
+    case webchat
+
+    init(raw: String?) {
+        let normalized = (raw ?? "").trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+        self = GatewayAgentChannel(rawValue: normalized) ?? .last
+    }
+
+    var isDeliverable: Bool {
+        self != .webchat
+    }
+
+    func shouldDeliver(_ deliver: Bool) -> Bool {
+        deliver && self.isDeliverable
+    }
+}
+
+struct GatewayAgentInvocation: Sendable {
+    var message: String
+    var sessionKey: String = "main"
+    var thinking: String?
+    var deliver: Bool = false
+    var to: String?
+    var channel: GatewayAgentChannel = .last
+    var timeoutSeconds: Int?
+    var idempotencyKey: String = UUID().uuidString
+}
+
+/// Single, shared Gateway websocket connection for the whole app.
+///
+/// This owns exactly one `GatewayChannelActor` and reuses it across all callers
+/// (ControlChannel, debug actions, SwiftUI WebChat, etc.).
+actor GatewayConnection {
+    static let shared = GatewayConnection()
+
+    typealias Config = (url: URL, token: String?, password: String?)
+
+    enum Method: String, Sendable {
+        case agent
+        case status
+        case setHeartbeats = "set-heartbeats"
+        case systemEvent = "system-event"
+        case health
+        case channelsStatus = "channels.status"
+        case configGet = "config.get"
+        case configSet = "config.set"
+        case configPatch = "config.patch"
+        case configSchema = "config.schema"
+        case wizardStart = "wizard.start"
+        case wizardNext = "wizard.next"
+        case wizardCancel = "wizard.cancel"
+        case wizardStatus = "wizard.status"
+        case talkConfig = "talk.config"
+        case talkMode = "talk.mode"
+        case webLoginStart = "web.login.start"
+        case webLoginWait = "web.login.wait"
+        case channelsLogout = "channels.logout"
+        case modelsList = "models.list"
+        case chatHistory = "chat.history"
+        case sessionsPreview = "sessions.preview"
+        case chatSend = "chat.send"
+        case chatAbort = "chat.abort"
+        case skillsStatus = "skills.status"
+        case skillsInstall = "skills.install"
+        case skillsUpdate = "skills.update"
+        case voicewakeGet = "voicewake.get"
+        case voicewakeSet = "voicewake.set"
+        case nodePairApprove = "node.pair.approve"
+        case nodePairReject = "node.pair.reject"
+        case devicePairList = "device.pair.list"
+        case devicePairApprove = "device.pair.approve"
+        case devicePairReject = "device.pair.reject"
+        case execApprovalResolve = "exec.approval.resolve"
+        case cronList = "cron.list"
+        case cronRuns = "cron.runs"
+        case cronRun = "cron.run"
+        case cronRemove = "cron.remove"
+        case cronUpdate = "cron.update"
+        case cronAdd = "cron.add"
+        case cronStatus = "cron.status"
+    }
+
+    private let configProvider: @Sendable () async throws -> Config
+    private let sessionBox: WebSocketSessionBox?
+    private let decoder = JSONDecoder()
+
+    private var client: GatewayChannelActor?
+    private var configuredURL: URL?
+    private var configuredToken: String?
+    private var configuredPassword: String?
+
+    private var subscribers: [UUID: AsyncStream<GatewayPush>.Continuation] = [:]
+    private var lastSnapshot: HelloOk?
+
+    init(
+        configProvider: @escaping @Sendable () async throws -> Config = GatewayConnection.defaultConfigProvider,
+        sessionBox: WebSocketSessionBox? = nil)
+    {
+        self.configProvider = configProvider
+        self.sessionBox = sessionBox
+    }
+
+    // MARK: - Low-level request
+
+    func request(
+        method: String,
+        params: [String: AnyCodable]?,
+        timeoutMs: Double? = nil) async throws -> Data
+    {
+        let cfg = try await self.configProvider()
+        await self.configure(url: cfg.url, token: cfg.token, password: cfg.password)
+        guard let client else {
+            throw NSError(domain: "Gateway", code: 0, userInfo: [NSLocalizedDescriptionKey: "gateway not configured"])
+        }
+
+        do {
+            return try await client.request(method: method, params: params, timeoutMs: timeoutMs)
+        } catch {
+            if error is GatewayResponseError || error is GatewayDecodingError {
+                throw error
+            }
+
+            // Auto-recover in local mode by spawning/attaching a gateway and retrying a few times.
+            // Canvas interactions should "just work" even if the local gateway isn't running yet.
+            let mode = await MainActor.run { AppStateStore.shared.connectionMode }
+            switch mode {
+            case .local:
+                await MainActor.run { GatewayProcessManager.shared.setActive(true) }
+
+                var lastError: Error = error
+                for delayMs in [150, 400, 900] {
+                    try await Task.sleep(nanoseconds: UInt64(delayMs) * 1_000_000)
+                    do {
+                        return try await client.request(method: method, params: params, timeoutMs: timeoutMs)
+                    } catch {
+                        lastError = error
+                    }
+                }
+
+                let nsError = lastError as NSError
+                if nsError.domain == URLError.errorDomain,
+                   let fallback = await GatewayEndpointStore.shared.maybeFallbackToTailnet(from: cfg.url)
+                {
+                    await self.configure(url: fallback.url, token: fallback.token, password: fallback.password)
+                    for delayMs in [150, 400, 900] {
+                        try await Task.sleep(nanoseconds: UInt64(delayMs) * 1_000_000)
+                        do {
+                            guard let client = self.client else {
+                                throw NSError(
+                                    domain: "Gateway",
+                                    code: 0,
+                                    userInfo: [NSLocalizedDescriptionKey: "gateway not configured"])
+                            }
+                            return try await client.request(method: method, params: params, timeoutMs: timeoutMs)
+                        } catch {
+                            lastError = error
+                        }
+                    }
+                }
+
+                throw lastError
+            case .remote:
+                let nsError = error as NSError
+                guard nsError.domain == URLError.errorDomain else { throw error }
+
+                var lastError: Error = error
+                await RemoteTunnelManager.shared.stopAll()
+                do {
+                    _ = try await GatewayEndpointStore.shared.ensureRemoteControlTunnel()
+                } catch {
+                    lastError = error
+                }
+
+                for delayMs in [150, 400, 900] {
+                    try await Task.sleep(nanoseconds: UInt64(delayMs) * 1_000_000)
+                    do {
+                        let cfg = try await self.configProvider()
+                        await self.configure(url: cfg.url, token: cfg.token, password: cfg.password)
+                        guard let client = self.client else {
+                            throw NSError(
+                                domain: "Gateway",
+                                code: 0,
+                                userInfo: [NSLocalizedDescriptionKey: "gateway not configured"])
+                        }
+                        return try await client.request(method: method, params: params, timeoutMs: timeoutMs)
+                    } catch {
+                        lastError = error
+                    }
+                }
+
+                throw lastError
+            case .unconfigured:
+                throw error
+            }
+        }
+    }
+
+    func requestRaw(
+        method: Method,
+        params: [String: AnyCodable]? = nil,
+        timeoutMs: Double? = nil) async throws -> Data
+    {
+        try await self.request(method: method.rawValue, params: params, timeoutMs: timeoutMs)
+    }
+
+    func requestRaw(
+        method: String,
+        params: [String: AnyCodable]? = nil,
+        timeoutMs: Double? = nil) async throws -> Data
+    {
+        try await self.request(method: method, params: params, timeoutMs: timeoutMs)
+    }
+
+    func requestDecoded<T: Decodable>(
+        method: Method,
+        params: [String: AnyCodable]? = nil,
+        timeoutMs: Double? = nil) async throws -> T
+    {
+        let data = try await self.requestRaw(method: method, params: params, timeoutMs: timeoutMs)
+        do {
+            return try self.decoder.decode(T.self, from: data)
+        } catch {
+            throw GatewayDecodingError(method: method.rawValue, message: error.localizedDescription)
+        }
+    }
+
+    func requestVoid(
+        method: Method,
+        params: [String: AnyCodable]? = nil,
+        timeoutMs: Double? = nil) async throws
+    {
+        _ = try await self.requestRaw(method: method, params: params, timeoutMs: timeoutMs)
+    }
+
+    /// Ensure the underlying socket is configured (and replaced if config changed).
+    func refresh() async throws {
+        let cfg = try await self.configProvider()
+        await self.configure(url: cfg.url, token: cfg.token, password: cfg.password)
+    }
+
+    func authSource() async -> GatewayAuthSource? {
+        guard let client else { return nil }
+        return await client.authSource()
+    }
+
+    func shutdown() async {
+        if let client {
+            await client.shutdown()
+        }
+        self.client = nil
+        self.configuredURL = nil
+        self.configuredToken = nil
+        self.lastSnapshot = nil
+    }
+
+    func canvasHostUrl() async -> String? {
+        guard let snapshot = self.lastSnapshot else { return nil }
+        let trimmed = snapshot.canvashosturl?.trimmingCharacters(in: CharacterSet.whitespacesAndNewlines) ?? ""
+        return trimmed.isEmpty ? nil : trimmed
+    }
+
+    private func sessionDefaultString(_ defaults: [String: OpenClawProtocol.AnyCodable]?, key: String) -> String {
+        let raw = defaults?[key]?.value as? String
+        return (raw ?? "").trimmingCharacters(in: CharacterSet.whitespacesAndNewlines)
+    }
+
+    func cachedMainSessionKey() -> String? {
+        guard let snapshot = self.lastSnapshot else { return nil }
+        let trimmed = self.sessionDefaultString(snapshot.snapshot.sessiondefaults, key: "mainSessionKey")
+        return trimmed.isEmpty ? nil : trimmed
+    }
+
+    func cachedGatewayVersion() -> String? {
+        guard let snapshot = self.lastSnapshot else { return nil }
+        let raw = snapshot.server["version"]?.value as? String
+        let trimmed = raw?.trimmingCharacters(in: CharacterSet.whitespacesAndNewlines) ?? ""
+        return trimmed.isEmpty ? nil : trimmed
+    }
+
+    func snapshotPaths() -> (configPath: String?, stateDir: String?) {
+        guard let snapshot = self.lastSnapshot else { return (nil, nil) }
+        let configPath = snapshot.snapshot.configpath?.trimmingCharacters(in: .whitespacesAndNewlines)
+        let stateDir = snapshot.snapshot.statedir?.trimmingCharacters(in: .whitespacesAndNewlines)
+        return (
+            configPath?.isEmpty == false ? configPath : nil,
+            stateDir?.isEmpty == false ? stateDir : nil)
+    }
+
+    func subscribe(bufferingNewest: Int = 100) -> AsyncStream<GatewayPush> {
+        let id = UUID()
+        let snapshot = self.lastSnapshot
+        let connection = self
+        return AsyncStream(bufferingPolicy: .bufferingNewest(bufferingNewest)) { continuation in
+            if let snapshot {
+                continuation.yield(.snapshot(snapshot))
+            }
+            self.subscribers[id] = continuation
+            continuation.onTermination = { @Sendable _ in
+                Task { await connection.removeSubscriber(id) }
+            }
+        }
+    }
+
+    private func removeSubscriber(_ id: UUID) {
+        self.subscribers[id] = nil
+    }
+
+    private func broadcast(_ push: GatewayPush) {
+        if case let .snapshot(snapshot) = push {
+            self.lastSnapshot = snapshot
+            if let mainSessionKey = self.cachedMainSessionKey() {
+                Task { @MainActor in
+                    WorkActivityStore.shared.setMainSessionKey(mainSessionKey)
+                }
+            }
+        }
+        for (_, continuation) in self.subscribers {
+            continuation.yield(push)
+        }
+    }
+
+    private func canonicalizeSessionKey(_ raw: String) -> String {
+        let trimmed = raw.trimmingCharacters(in: CharacterSet.whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return trimmed }
+        guard let defaults = self.lastSnapshot?.snapshot.sessiondefaults else { return trimmed }
+        let mainSessionKey = self.sessionDefaultString(defaults, key: "mainSessionKey")
+        guard !mainSessionKey.isEmpty else { return trimmed }
+        let mainKey = self.sessionDefaultString(defaults, key: "mainKey")
+        let defaultAgentId = self.sessionDefaultString(defaults, key: "defaultAgentId")
+        let isMainAlias =
+            trimmed == "main" ||
+            (!mainKey.isEmpty && trimmed == mainKey) ||
+            trimmed == mainSessionKey ||
+            (!defaultAgentId.isEmpty &&
+                (trimmed == "agent:\(defaultAgentId):main" ||
+                    (mainKey.isEmpty == false && trimmed == "agent:\(defaultAgentId):\(mainKey)")))
+        return isMainAlias ? mainSessionKey : trimmed
+    }
+
+    private func configure(url: URL, token: String?, password: String?) async {
+        if self.client != nil, self.configuredURL == url, self.configuredToken == token,
+           self.configuredPassword == password
+        {
+            return
+        }
+        if let client {
+            await client.shutdown()
+        }
+        self.lastSnapshot = nil
+        self.client = GatewayChannelActor(
+            url: url,
+            token: token,
+            password: password,
+            session: self.sessionBox,
+            pushHandler: { [weak self] push in
+                await self?.handle(push: push)
+            })
+        self.configuredURL = url
+        self.configuredToken = token
+        self.configuredPassword = password
+    }
+
+    private func handle(push: GatewayPush) {
+        self.broadcast(push)
+    }
+
+    private static func defaultConfigProvider() async throws -> Config {
+        try await GatewayEndpointStore.shared.requireConfig()
+    }
+}
+
+// MARK: - Typed gateway API
+
+extension GatewayConnection {
+    struct ConfigGetSnapshot: Decodable, Sendable {
+        struct SnapshotConfig: Decodable, Sendable {
+            struct Session: Decodable, Sendable {
+                let mainKey: String?
+                let scope: String?
+            }
+
+            let session: Session?
+        }
+
+        let config: SnapshotConfig?
+    }
+
+    static func mainSessionKey(fromConfigGetData data: Data) throws -> String {
+        let snapshot = try JSONDecoder().decode(ConfigGetSnapshot.self, from: data)
+        let scope = snapshot.config?.session?.scope?.trimmingCharacters(in: .whitespacesAndNewlines)
+        if scope == "global" {
+            return "global"
+        }
+        return "main"
+    }
+
+    func mainSessionKey(timeoutMs: Double = 15000) async -> String {
+        if let cached = self.cachedMainSessionKey() {
+            return cached
+        }
+        do {
+            let data = try await self.requestRaw(method: "config.get", params: nil, timeoutMs: timeoutMs)
+            return try Self.mainSessionKey(fromConfigGetData: data)
+        } catch {
+            return "main"
+        }
+    }
+
+    func status() async -> (ok: Bool, error: String?) {
+        do {
+            _ = try await self.requestRaw(method: .status)
+            return (true, nil)
+        } catch {
+            return (false, error.localizedDescription)
+        }
+    }
+
+    func setHeartbeatsEnabled(_ enabled: Bool) async -> Bool {
+        do {
+            try await self.requestVoid(method: .setHeartbeats, params: ["enabled": AnyCodable(enabled)])
+            return true
+        } catch {
+            gatewayConnectionLogger.error("setHeartbeatsEnabled failed \(error.localizedDescription, privacy: .public)")
+            return false
+        }
+    }
+
+    func sendAgent(_ invocation: GatewayAgentInvocation) async -> (ok: Bool, error: String?) {
+        let trimmed = invocation.message.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return (false, "message empty") }
+        let sessionKey = self.canonicalizeSessionKey(invocation.sessionKey)
+
+        var params: [String: AnyCodable] = [
+            "message": AnyCodable(trimmed),
+            "sessionKey": AnyCodable(sessionKey),
+            "thinking": AnyCodable(invocation.thinking ?? "default"),
+            "deliver": AnyCodable(invocation.deliver),
+            "to": AnyCodable(invocation.to ?? ""),
+            "channel": AnyCodable(invocation.channel.rawValue),
+            "idempotencyKey": AnyCodable(invocation.idempotencyKey),
+        ]
+        if let timeout = invocation.timeoutSeconds {
+            params["timeout"] = AnyCodable(timeout)
+        }
+
+        do {
+            try await self.requestVoid(method: .agent, params: params)
+            return (true, nil)
+        } catch {
+            return (false, error.localizedDescription)
+        }
+    }
+
+    func sendAgent(
+        message: String,
+        thinking: String?,
+        sessionKey: String,
+        deliver: Bool,
+        to: String?,
+        channel: GatewayAgentChannel = .last,
+        timeoutSeconds: Int? = nil,
+        idempotencyKey: String = UUID().uuidString) async -> (ok: Bool, error: String?)
+    {
+        await self.sendAgent(GatewayAgentInvocation(
+            message: message,
+            sessionKey: sessionKey,
+            thinking: thinking,
+            deliver: deliver,
+            to: to,
+            channel: channel,
+            timeoutSeconds: timeoutSeconds,
+            idempotencyKey: idempotencyKey))
+    }
+
+    func sendSystemEvent(_ params: [String: AnyCodable]) async {
+        do {
+            try await self.requestVoid(method: .systemEvent, params: params)
+        } catch {
+            // Best-effort only.
+        }
+    }
+
+    // MARK: - Health
+
+    func healthSnapshot(timeoutMs: Double? = nil) async throws -> HealthSnapshot {
+        let data = try await self.requestRaw(method: .health, timeoutMs: timeoutMs)
+        if let snap = decodeHealthSnapshot(from: data) { return snap }
+        throw GatewayDecodingError(method: Method.health.rawValue, message: "failed to decode health snapshot")
+    }
+
+    func healthOK(timeoutMs: Int = 8000) async throws -> Bool {
+        let data = try await self.requestRaw(method: .health, timeoutMs: Double(timeoutMs))
+        return (try? self.decoder.decode(OpenClawGatewayHealthOK.self, from: data))?.ok ?? true
+    }
+
+    // MARK: - Skills
+
+    func skillsStatus() async throws -> SkillsStatusReport {
+        try await self.requestDecoded(method: .skillsStatus)
+    }
+
+    func skillsInstall(
+        name: String,
+        installId: String,
+        timeoutMs: Int? = nil) async throws -> SkillInstallResult
+    {
+        var params: [String: AnyCodable] = [
+            "name": AnyCodable(name),
+            "installId": AnyCodable(installId),
+        ]
+        if let timeoutMs {
+            params["timeoutMs"] = AnyCodable(timeoutMs)
+        }
+        return try await self.requestDecoded(method: .skillsInstall, params: params)
+    }
+
+    func skillsUpdate(
+        skillKey: String,
+        enabled: Bool? = nil,
+        apiKey: String? = nil,
+        env: [String: String]? = nil) async throws -> SkillUpdateResult
+    {
+        var params: [String: AnyCodable] = [
+            "skillKey": AnyCodable(skillKey),
+        ]
+        if let enabled { params["enabled"] = AnyCodable(enabled) }
+        if let apiKey { params["apiKey"] = AnyCodable(apiKey) }
+        if let env, !env.isEmpty { params["env"] = AnyCodable(env) }
+        return try await self.requestDecoded(method: .skillsUpdate, params: params)
+    }
+
+    // MARK: - Sessions
+
+    func sessionsPreview(
+        keys: [String],
+        limit: Int? = nil,
+        maxChars: Int? = nil,
+        timeoutMs: Int? = nil) async throws -> OpenClawSessionsPreviewPayload
+    {
+        let resolvedKeys = keys
+            .map { self.canonicalizeSessionKey($0) }
+            .filter { !$0.isEmpty }
+        if resolvedKeys.isEmpty {
+            return OpenClawSessionsPreviewPayload(ts: 0, previews: [])
+        }
+        var params: [String: AnyCodable] = ["keys": AnyCodable(resolvedKeys)]
+        if let limit { params["limit"] = AnyCodable(limit) }
+        if let maxChars { params["maxChars"] = AnyCodable(maxChars) }
+        let timeout = timeoutMs.map { Double($0) }
+        return try await self.requestDecoded(
+            method: .sessionsPreview,
+            params: params,
+            timeoutMs: timeout)
+    }
+
+    // MARK: - Chat
+
+    func chatHistory(
+        sessionKey: String,
+        limit: Int? = nil,
+        timeoutMs: Int? = nil) async throws -> OpenClawChatHistoryPayload
+    {
+        let resolvedKey = self.canonicalizeSessionKey(sessionKey)
+        var params: [String: AnyCodable] = ["sessionKey": AnyCodable(resolvedKey)]
+        if let limit { params["limit"] = AnyCodable(limit) }
+        let timeout = timeoutMs.map { Double($0) }
+        return try await self.requestDecoded(
+            method: .chatHistory,
+            params: params,
+            timeoutMs: timeout)
+    }
+
+    func chatSend(
+        sessionKey: String,
+        message: String,
+        thinking: String,
+        idempotencyKey: String,
+        attachments: [OpenClawChatAttachmentPayload],
+        timeoutMs: Int = 30000) async throws -> OpenClawChatSendResponse
+    {
+        let resolvedKey = self.canonicalizeSessionKey(sessionKey)
+        var params: [String: AnyCodable] = [
+            "sessionKey": AnyCodable(resolvedKey),
+            "message": AnyCodable(message),
+            "thinking": AnyCodable(thinking),
+            "idempotencyKey": AnyCodable(idempotencyKey),
+            "timeoutMs": AnyCodable(timeoutMs),
+        ]
+
+        if !attachments.isEmpty {
+            let encoded = attachments.map { att in
+                [
+                    "type": att.type,
+                    "mimeType": att.mimeType,
+                    "fileName": att.fileName,
+                    "content": att.content,
+                ]
+            }
+            params["attachments"] = AnyCodable(encoded)
+        }
+
+        return try await self.requestDecoded(
+            method: .chatSend,
+            params: params,
+            timeoutMs: Double(timeoutMs))
+    }
+
+    func chatAbort(sessionKey: String, runId: String) async throws -> Bool {
+        let resolvedKey = self.canonicalizeSessionKey(sessionKey)
+        struct AbortResponse: Decodable { let ok: Bool?; let aborted: Bool? }
+        let res: AbortResponse = try await self.requestDecoded(
+            method: .chatAbort,
+            params: ["sessionKey": AnyCodable(resolvedKey), "runId": AnyCodable(runId)])
+        return res.aborted ?? false
+    }
+
+    func talkMode(enabled: Bool, phase: String? = nil) async {
+        var params: [String: AnyCodable] = ["enabled": AnyCodable(enabled)]
+        if let phase { params["phase"] = AnyCodable(phase) }
+        try? await self.requestVoid(method: .talkMode, params: params)
+    }
+
+    // MARK: - VoiceWake
+
+    func voiceWakeGetTriggers() async throws -> [String] {
+        struct VoiceWakePayload: Decodable { let triggers: [String] }
+        let payload: VoiceWakePayload = try await self.requestDecoded(method: .voicewakeGet)
+        return payload.triggers
+    }
+
+    func voiceWakeSetTriggers(_ triggers: [String]) async {
+        do {
+            try await self.requestVoid(
+                method: .voicewakeSet,
+                params: ["triggers": AnyCodable(triggers)],
+                timeoutMs: 10000)
+        } catch {
+            // Best-effort only.
+        }
+    }
+
+    // MARK: - Node pairing
+
+    func nodePairApprove(requestId: String) async throws {
+        try await self.requestVoid(
+            method: .nodePairApprove,
+            params: ["requestId": AnyCodable(requestId)],
+            timeoutMs: 10000)
+    }
+
+    func nodePairReject(requestId: String) async throws {
+        try await self.requestVoid(
+            method: .nodePairReject,
+            params: ["requestId": AnyCodable(requestId)],
+            timeoutMs: 10000)
+    }
+
+    // MARK: - Device pairing
+
+    func devicePairApprove(requestId: String) async throws {
+        try await self.requestVoid(
+            method: .devicePairApprove,
+            params: ["requestId": AnyCodable(requestId)],
+            timeoutMs: 10000)
+    }
+
+    func devicePairReject(requestId: String) async throws {
+        try await self.requestVoid(
+            method: .devicePairReject,
+            params: ["requestId": AnyCodable(requestId)],
+            timeoutMs: 10000)
+    }
+
+    // MARK: - Cron
+
+    struct CronSchedulerStatus: Decodable, Sendable {
+        let enabled: Bool
+        let storePath: String
+        let jobs: Int
+        let nextWakeAtMs: Int?
+    }
+
+    func cronStatus() async throws -> CronSchedulerStatus {
+        try await self.requestDecoded(method: .cronStatus)
+    }
+
+    func cronList(includeDisabled: Bool = true) async throws -> [CronJob] {
+        let res: CronListResponse = try await self.requestDecoded(
+            method: .cronList,
+            params: ["includeDisabled": AnyCodable(includeDisabled)])
+        return res.jobs
+    }
+
+    func cronRuns(jobId: String, limit: Int = 200) async throws -> [CronRunLogEntry] {
+        let res: CronRunsResponse = try await self.requestDecoded(
+            method: .cronRuns,
+            params: ["id": AnyCodable(jobId), "limit": AnyCodable(limit)])
+        return res.entries
+    }
+
+    func cronRun(jobId: String, force: Bool = true) async throws {
+        try await self.requestVoid(
+            method: .cronRun,
+            params: [
+                "id": AnyCodable(jobId),
+                "mode": AnyCodable(force ? "force" : "due"),
+            ],
+            timeoutMs: 20000)
+    }
+
+    func cronRemove(jobId: String) async throws {
+        try await self.requestVoid(method: .cronRemove, params: ["id": AnyCodable(jobId)])
+    }
+
+    func cronUpdate(jobId: String, patch: [String: AnyCodable]) async throws {
+        try await self.requestVoid(
+            method: .cronUpdate,
+            params: ["id": AnyCodable(jobId), "patch": AnyCodable(patch)])
+    }
+
+    func cronAdd(payload: [String: AnyCodable]) async throws {
+        try await self.requestVoid(method: .cronAdd, params: payload)
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/GatewayConnectivityCoordinator.swift

@@ -0,0 +1,63 @@
+import Foundation
+import Observation
+import OSLog
+
+@MainActor
+@Observable
+final class GatewayConnectivityCoordinator {
+    static let shared = GatewayConnectivityCoordinator()
+
+    private let logger = Logger(subsystem: "ai.openclaw", category: "gateway.connectivity")
+    private var endpointTask: Task<Void, Never>?
+    private var lastResolvedURL: URL?
+
+    private(set) var endpointState: GatewayEndpointState?
+    private(set) var resolvedURL: URL?
+    private(set) var resolvedMode: AppState.ConnectionMode?
+    private(set) var resolvedHostLabel: String?
+
+    private init() {
+        self.start()
+    }
+
+    func start() {
+        guard self.endpointTask == nil else { return }
+        self.endpointTask = Task { [weak self] in
+            guard let self else { return }
+            let stream = await GatewayEndpointStore.shared.subscribe()
+            for await state in stream {
+                await MainActor.run { self.handleEndpointState(state) }
+            }
+        }
+    }
+
+    var localEndpointHostLabel: String? {
+        guard self.resolvedMode == .local, let url = self.resolvedURL else { return nil }
+        return Self.hostLabel(for: url)
+    }
+
+    private func handleEndpointState(_ state: GatewayEndpointState) {
+        self.endpointState = state
+        switch state {
+        case let .ready(mode, url, _, _):
+            self.resolvedMode = mode
+            self.resolvedURL = url
+            self.resolvedHostLabel = Self.hostLabel(for: url)
+            let urlChanged = self.lastResolvedURL?.absoluteString != url.absoluteString
+            if urlChanged {
+                self.lastResolvedURL = url
+                Task { await ControlChannel.shared.refreshEndpoint(reason: "endpoint changed") }
+            }
+        case let .connecting(mode, _):
+            self.resolvedMode = mode
+        case let .unavailable(mode, _):
+            self.resolvedMode = mode
+        }
+    }
+
+    private static func hostLabel(for url: URL) -> String {
+        let host = url.host ?? url.absoluteString
+        if let port = url.port { return "\(host):\(port)" }
+        return host
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/GatewayDiscoveryHelpers.swift

@@ -0,0 +1,77 @@
+import Foundation
+import OpenClawDiscovery
+
+enum GatewayDiscoveryHelpers {
+    static func resolvedServiceHost(
+        for gateway: GatewayDiscoveryModel.DiscoveredGateway) -> String?
+    {
+        self.resolvedServiceHost(gateway.serviceHost)
+    }
+
+    static func resolvedServiceHost(_ host: String?) -> String? {
+        guard let host = self.trimmed(host), !host.isEmpty else { return nil }
+        return host
+    }
+
+    static func serviceEndpoint(
+        for gateway: GatewayDiscoveryModel.DiscoveredGateway) -> (host: String, port: Int)?
+    {
+        self.serviceEndpoint(serviceHost: gateway.serviceHost, servicePort: gateway.servicePort)
+    }
+
+    static func serviceEndpoint(
+        serviceHost: String?,
+        servicePort: Int?) -> (host: String, port: Int)?
+    {
+        guard let host = self.resolvedServiceHost(serviceHost) else { return nil }
+        guard let port = servicePort, port > 0, port <= 65535 else { return nil }
+        return (host, port)
+    }
+
+    static func sshTarget(for gateway: GatewayDiscoveryModel.DiscoveredGateway) -> String? {
+        guard let host = self.resolvedServiceHost(for: gateway) else { return nil }
+        let user = NSUserName()
+        var target = "\(user)@\(host)"
+        if gateway.sshPort != 22 {
+            target += ":\(gateway.sshPort)"
+        }
+        return target
+    }
+
+    static func directUrl(for gateway: GatewayDiscoveryModel.DiscoveredGateway) -> String? {
+        self.directGatewayUrl(
+            serviceHost: gateway.serviceHost,
+            servicePort: gateway.servicePort)
+    }
+
+    static func directGatewayUrl(
+        serviceHost: String?,
+        servicePort: Int?) -> String?
+    {
+        // Security: do not route using unauthenticated TXT hints (tailnetDns/lanHost/gatewayPort).
+        // Prefer the resolved service endpoint (SRV + A/AAAA).
+        guard let endpoint = self.serviceEndpoint(serviceHost: serviceHost, servicePort: servicePort) else {
+            return nil
+        }
+        // Security: for non-loopback hosts, force TLS to avoid plaintext credential/session leakage.
+        let scheme = self.isLoopbackHost(endpoint.host) ? "ws" : "wss"
+        let portSuffix = endpoint.port == 443 ? "" : ":\(endpoint.port)"
+        return "\(scheme)://\(endpoint.host)\(portSuffix)"
+    }
+
+    private static func trimmed(_ value: String?) -> String? {
+        value?.trimmingCharacters(in: .whitespacesAndNewlines)
+    }
+
+    private static func isLoopbackHost(_ rawHost: String) -> Bool {
+        let host = rawHost.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+        guard !host.isEmpty else { return false }
+        if host == "localhost" || host == "::1" || host == "0:0:0:0:0:0:0:1" {
+            return true
+        }
+        if host.hasPrefix("::ffff:127.") {
+            return true
+        }
+        return host.hasPrefix("127.")
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/GatewayDiscoveryMenu.swift

@@ -0,0 +1,139 @@
+import OpenClawDiscovery
+import SwiftUI
+
+struct GatewayDiscoveryInlineList: View {
+    var discovery: GatewayDiscoveryModel
+    var currentTarget: String?
+    var currentUrl: String?
+    var transport: AppState.RemoteTransport
+    var onSelect: (GatewayDiscoveryModel.DiscoveredGateway) -> Void
+    @State private var hoveredGatewayID: GatewayDiscoveryModel.DiscoveredGateway.ID?
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 6) {
+            HStack(alignment: .firstTextBaseline, spacing: 6) {
+                Image(systemName: "dot.radiowaves.left.and.right")
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+                Text(self.discovery.statusText)
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+            }
+
+            if self.discovery.gateways.isEmpty {
+                Text("No gateways found yet.")
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+            } else {
+                VStack(alignment: .leading, spacing: 6) {
+                    ForEach(self.discovery.gateways.prefix(6)) { gateway in
+                        let display = self.displayInfo(for: gateway)
+                        let selected = display.selected
+
+                        Button {
+                            withAnimation(.spring(response: 0.25, dampingFraction: 0.9)) {
+                                self.onSelect(gateway)
+                            }
+                        } label: {
+                            HStack(alignment: .center, spacing: 10) {
+                                VStack(alignment: .leading, spacing: 2) {
+                                    Text(gateway.displayName)
+                                        .font(.callout.weight(.semibold))
+                                        .lineLimit(1)
+                                        .truncationMode(.tail)
+                                    Text(display.label)
+                                        .font(.caption.monospaced())
+                                        .foregroundStyle(.secondary)
+                                        .lineLimit(1)
+                                        .truncationMode(.middle)
+                                }
+                                Spacer(minLength: 0)
+                                if selected {
+                                    Image(systemName: "checkmark.circle.fill")
+                                        .foregroundStyle(Color.accentColor)
+                                } else {
+                                    Image(systemName: "arrow.right.circle")
+                                        .foregroundStyle(.secondary)
+                                }
+                            }
+                            .padding(.horizontal, 10)
+                            .padding(.vertical, 8)
+                            .frame(maxWidth: .infinity, alignment: .leading)
+                            .background(
+                                RoundedRectangle(cornerRadius: 10, style: .continuous)
+                                    .fill(self.rowBackground(
+                                        selected: selected,
+                                        hovered: self.hoveredGatewayID == gateway.id)))
+                            .overlay(
+                                RoundedRectangle(cornerRadius: 10, style: .continuous)
+                                    .strokeBorder(
+                                        selected ? Color.accentColor.opacity(0.45) : Color.clear,
+                                        lineWidth: 1))
+                            .contentShape(Rectangle())
+                        }
+                        .buttonStyle(.plain)
+                        .onHover { hovering in
+                            self.hoveredGatewayID = hovering ? gateway
+                                .id : (self.hoveredGatewayID == gateway.id ? nil : self.hoveredGatewayID)
+                        }
+                    }
+                }
+                .padding(10)
+                .background(
+                    RoundedRectangle(cornerRadius: 10, style: .continuous)
+                        .fill(Color(NSColor.controlBackgroundColor)))
+            }
+        }
+        .help(self.transport == .direct
+            ? "Click a discovered gateway to fill the gateway URL."
+            : "Click a discovered gateway to fill the SSH target.")
+    }
+
+    private func displayInfo(
+        for gateway: GatewayDiscoveryModel.DiscoveredGateway) -> (label: String, selected: Bool)
+    {
+        switch self.transport {
+        case .direct:
+            let url = GatewayDiscoveryHelpers.directUrl(for: gateway)
+            let label = url ?? "Gateway pairing only"
+            let selected = url != nil && self.trimmed(self.currentUrl) == url
+            return (label, selected)
+        case .ssh:
+            let target = GatewayDiscoveryHelpers.sshTarget(for: gateway)
+            let label = target ?? "Gateway pairing only"
+            let selected = target != nil && self.trimmed(self.currentTarget) == target
+            return (label, selected)
+        }
+    }
+
+    private func rowBackground(selected: Bool, hovered: Bool) -> Color {
+        if selected { return Color.accentColor.opacity(0.12) }
+        if hovered { return Color.secondary.opacity(0.08) }
+        return Color.clear
+    }
+
+    private func trimmed(_ value: String?) -> String {
+        value?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+    }
+}
+
+struct GatewayDiscoveryMenu: View {
+    var discovery: GatewayDiscoveryModel
+    var onSelect: (GatewayDiscoveryModel.DiscoveredGateway) -> Void
+
+    var body: some View {
+        Menu {
+            if self.discovery.gateways.isEmpty {
+                Button(self.discovery.statusText) {}
+                    .disabled(true)
+            } else {
+                ForEach(self.discovery.gateways) { gateway in
+                    Button(gateway.displayName) { self.onSelect(gateway) }
+                }
+            }
+        } label: {
+            Image(systemName: "dot.radiowaves.left.and.right")
+        }
+        .help("Discover OpenClaw gateways on your LAN")
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/GatewayDiscoveryPreferences.swift

@@ -0,0 +1,25 @@
+import Foundation
+
+enum GatewayDiscoveryPreferences {
+    private static let preferredStableIDKey = "gateway.preferredStableID"
+    private static let legacyPreferredStableIDKey = "bridge.preferredStableID"
+
+    static func preferredStableID() -> String? {
+        let defaults = UserDefaults.standard
+        let raw = defaults.string(forKey: self.preferredStableIDKey)
+            ?? defaults.string(forKey: self.legacyPreferredStableIDKey)
+        let trimmed = raw?.trimmingCharacters(in: .whitespacesAndNewlines)
+        return trimmed?.isEmpty == false ? trimmed : nil
+    }
+
+    static func setPreferredStableID(_ stableID: String?) {
+        let trimmed = stableID?.trimmingCharacters(in: .whitespacesAndNewlines)
+        if let trimmed, !trimmed.isEmpty {
+            UserDefaults.standard.set(trimmed, forKey: self.preferredStableIDKey)
+            UserDefaults.standard.removeObject(forKey: self.legacyPreferredStableIDKey)
+        } else {
+            UserDefaults.standard.removeObject(forKey: self.preferredStableIDKey)
+            UserDefaults.standard.removeObject(forKey: self.legacyPreferredStableIDKey)
+        }
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/GatewayEndpointStore.swift

@@ -0,0 +1,728 @@
+import ConcurrencyExtras
+import Foundation
+import OSLog
+
+enum GatewayEndpointState: Sendable, Equatable {
+    case ready(mode: AppState.ConnectionMode, url: URL, token: String?, password: String?)
+    case connecting(mode: AppState.ConnectionMode, detail: String)
+    case unavailable(mode: AppState.ConnectionMode, reason: String)
+}
+
+/// Single place to resolve (and publish) the effective gateway control endpoint.
+///
+/// This is intentionally separate from `GatewayConnection`:
+/// - `GatewayConnection` consumes the resolved endpoint (no tunnel side-effects).
+/// - The endpoint store owns observation + explicit "ensure tunnel" actions.
+actor GatewayEndpointStore {
+    static let shared = GatewayEndpointStore()
+    private static let supportedBindModes: Set<String> = [
+        "loopback",
+        "tailnet",
+        "lan",
+        "auto",
+        "custom",
+    ]
+    private static let remoteConnectingDetail = "Connecting to remote gateway…"
+    private static let staticLogger = Logger(subsystem: "ai.openclaw", category: "gateway-endpoint")
+    private enum EnvOverrideWarningKind: Sendable {
+        case token
+        case password
+    }
+
+    private static let envOverrideWarnings = LockIsolated((token: false, password: false))
+
+    struct Deps: Sendable {
+        let mode: @Sendable () async -> AppState.ConnectionMode
+        let token: @Sendable () -> String?
+        let password: @Sendable () -> String?
+        let localPort: @Sendable () -> Int
+        let localHost: @Sendable () async -> String
+        let remotePortIfRunning: @Sendable () async -> UInt16?
+        let ensureRemoteTunnel: @Sendable () async throws -> UInt16
+
+        static let live = Deps(
+            mode: { await MainActor.run { AppStateStore.shared.connectionMode } },
+            token: {
+                let root = OpenClawConfigFile.loadDict()
+                let isRemote = ConnectionModeResolver.resolve(root: root).mode == .remote
+                return GatewayEndpointStore.resolveGatewayToken(
+                    isRemote: isRemote,
+                    root: root,
+                    env: ProcessInfo.processInfo.environment,
+                    launchdSnapshot: GatewayLaunchAgentManager.launchdConfigSnapshot())
+            },
+            password: {
+                let root = OpenClawConfigFile.loadDict()
+                let isRemote = ConnectionModeResolver.resolve(root: root).mode == .remote
+                return GatewayEndpointStore.resolveGatewayPassword(
+                    isRemote: isRemote,
+                    root: root,
+                    env: ProcessInfo.processInfo.environment,
+                    launchdSnapshot: GatewayLaunchAgentManager.launchdConfigSnapshot())
+            },
+            localPort: { GatewayEnvironment.gatewayPort() },
+            localHost: {
+                let root = OpenClawConfigFile.loadDict()
+                let bind = GatewayEndpointStore.resolveGatewayBindMode(
+                    root: root,
+                    env: ProcessInfo.processInfo.environment)
+                let customBindHost = GatewayEndpointStore.resolveGatewayCustomBindHost(root: root)
+                let tailscaleIP = await MainActor.run { TailscaleService.shared.tailscaleIP }
+                    ?? TailscaleService.fallbackTailnetIPv4()
+                return GatewayEndpointStore.resolveLocalGatewayHost(
+                    bindMode: bind,
+                    customBindHost: customBindHost,
+                    tailscaleIP: tailscaleIP)
+            },
+            remotePortIfRunning: { await RemoteTunnelManager.shared.controlTunnelPortIfRunning() },
+            ensureRemoteTunnel: { try await RemoteTunnelManager.shared.ensureControlTunnel() })
+    }
+
+    private static func resolveGatewayPassword(
+        isRemote: Bool,
+        root: [String: Any],
+        env: [String: String],
+        launchdSnapshot: LaunchAgentPlistSnapshot?) -> String?
+    {
+        let raw = env["OPENCLAW_GATEWAY_PASSWORD"] ?? ""
+        let trimmed = raw.trimmingCharacters(in: .whitespacesAndNewlines)
+        if !trimmed.isEmpty {
+            if let configPassword = self.resolveConfigPassword(isRemote: isRemote, root: root),
+               !configPassword.isEmpty
+            {
+                self.warnEnvOverrideOnce(
+                    kind: .password,
+                    envVar: "OPENCLAW_GATEWAY_PASSWORD",
+                    configKey: isRemote ? "gateway.remote.password" : "gateway.auth.password")
+            }
+            return trimmed
+        }
+        if isRemote {
+            if let gateway = root["gateway"] as? [String: Any],
+               let remote = gateway["remote"] as? [String: Any],
+               let password = remote["password"] as? String
+            {
+                let pw = password.trimmingCharacters(in: .whitespacesAndNewlines)
+                if !pw.isEmpty {
+                    return pw
+                }
+            }
+            return nil
+        }
+        if let gateway = root["gateway"] as? [String: Any],
+           let auth = gateway["auth"] as? [String: Any],
+           let password = auth["password"] as? String
+        {
+            let pw = password.trimmingCharacters(in: .whitespacesAndNewlines)
+            if !pw.isEmpty {
+                return pw
+            }
+        }
+        if let password = launchdSnapshot?.password?.trimmingCharacters(in: .whitespacesAndNewlines),
+           !password.isEmpty
+        {
+            return password
+        }
+        return nil
+    }
+
+    private static func resolveConfigPassword(isRemote: Bool, root: [String: Any]) -> String? {
+        if isRemote {
+            if let gateway = root["gateway"] as? [String: Any],
+               let remote = gateway["remote"] as? [String: Any],
+               let password = remote["password"] as? String
+            {
+                return password.trimmingCharacters(in: .whitespacesAndNewlines)
+            }
+            return nil
+        }
+
+        if let gateway = root["gateway"] as? [String: Any],
+           let auth = gateway["auth"] as? [String: Any],
+           let password = auth["password"] as? String
+        {
+            return password.trimmingCharacters(in: .whitespacesAndNewlines)
+        }
+        return nil
+    }
+
+    private static func resolveGatewayToken(
+        isRemote: Bool,
+        root: [String: Any],
+        env: [String: String],
+        launchdSnapshot: LaunchAgentPlistSnapshot?) -> String?
+    {
+        let raw = env["OPENCLAW_GATEWAY_TOKEN"] ?? ""
+        let trimmed = raw.trimmingCharacters(in: .whitespacesAndNewlines)
+        if !trimmed.isEmpty {
+            if let configToken = self.resolveConfigToken(isRemote: isRemote, root: root),
+               !configToken.isEmpty,
+               configToken != trimmed
+            {
+                self.warnEnvOverrideOnce(
+                    kind: .token,
+                    envVar: "OPENCLAW_GATEWAY_TOKEN",
+                    configKey: isRemote ? "gateway.remote.token" : "gateway.auth.token")
+            }
+            return trimmed
+        }
+
+        if let configToken = self.resolveConfigToken(isRemote: isRemote, root: root),
+           !configToken.isEmpty
+        {
+            return configToken
+        }
+
+        if isRemote {
+            return nil
+        }
+
+        if let token = launchdSnapshot?.token?.trimmingCharacters(in: .whitespacesAndNewlines),
+           !token.isEmpty
+        {
+            return token
+        }
+
+        return nil
+    }
+
+    private static func resolveConfigToken(isRemote: Bool, root: [String: Any]) -> String? {
+        if isRemote {
+            if let gateway = root["gateway"] as? [String: Any],
+               let remote = gateway["remote"] as? [String: Any],
+               let token = remote["token"] as? String
+            {
+                return token.trimmingCharacters(in: .whitespacesAndNewlines)
+            }
+            return nil
+        }
+
+        if let gateway = root["gateway"] as? [String: Any],
+           let auth = gateway["auth"] as? [String: Any],
+           let token = auth["token"] as? String
+        {
+            return token.trimmingCharacters(in: .whitespacesAndNewlines)
+        }
+        return nil
+    }
+
+    private static func warnEnvOverrideOnce(
+        kind: EnvOverrideWarningKind,
+        envVar: String,
+        configKey: String)
+    {
+        let shouldWarn = Self.envOverrideWarnings.withValue { state in
+            switch kind {
+            case .token:
+                guard !state.token else { return false }
+                state.token = true
+                return true
+            case .password:
+                guard !state.password else { return false }
+                state.password = true
+                return true
+            }
+        }
+        guard shouldWarn else { return }
+        Self.staticLogger.warning(
+            "\(envVar, privacy: .public) is set and overrides \(configKey, privacy: .public). " +
+                "If this is unintentional, clear it with: launchctl unsetenv \(envVar, privacy: .public)")
+    }
+
+    private let deps: Deps
+    private let logger = Logger(subsystem: "ai.openclaw", category: "gateway-endpoint")
+
+    private var state: GatewayEndpointState
+    private var subscribers: [UUID: AsyncStream<GatewayEndpointState>.Continuation] = [:]
+    private var remoteEnsure: (token: UUID, task: Task<UInt16, Error>)?
+
+    init(deps: Deps = .live) {
+        self.deps = deps
+        let modeRaw = UserDefaults.standard.string(forKey: connectionModeKey)
+        let initialMode: AppState.ConnectionMode
+        if let modeRaw {
+            initialMode = AppState.ConnectionMode(rawValue: modeRaw) ?? .local
+        } else {
+            let seen = UserDefaults.standard.bool(forKey: "openclaw.onboardingSeen")
+            initialMode = seen ? .local : .unconfigured
+        }
+
+        let port = deps.localPort()
+        let bind = GatewayEndpointStore.resolveGatewayBindMode(
+            root: OpenClawConfigFile.loadDict(),
+            env: ProcessInfo.processInfo.environment)
+        let customBindHost = GatewayEndpointStore.resolveGatewayCustomBindHost(root: OpenClawConfigFile.loadDict())
+        let scheme = GatewayEndpointStore.resolveGatewayScheme(
+            root: OpenClawConfigFile.loadDict(),
+            env: ProcessInfo.processInfo.environment)
+        let host = GatewayEndpointStore.resolveLocalGatewayHost(
+            bindMode: bind,
+            customBindHost: customBindHost,
+            tailscaleIP: nil)
+        let token = deps.token()
+        let password = deps.password()
+        switch initialMode {
+        case .local:
+            self.state = .ready(
+                mode: .local,
+                url: URL(string: "\(scheme)://\(host):\(port)")!,
+                token: token,
+                password: password)
+        case .remote:
+            self.state = .connecting(mode: .remote, detail: Self.remoteConnectingDetail)
+            Task { await self.setMode(.remote) }
+        case .unconfigured:
+            self.state = .unavailable(mode: .unconfigured, reason: "Gateway not configured")
+        }
+    }
+
+    func subscribe(bufferingNewest: Int = 1) -> AsyncStream<GatewayEndpointState> {
+        let id = UUID()
+        let initial = self.state
+        let store = self
+        return AsyncStream(bufferingPolicy: .bufferingNewest(bufferingNewest)) { continuation in
+            continuation.yield(initial)
+            self.subscribers[id] = continuation
+            continuation.onTermination = { @Sendable _ in
+                Task { await store.removeSubscriber(id) }
+            }
+        }
+    }
+
+    func refresh() async {
+        let mode = await self.deps.mode()
+        await self.setMode(mode)
+    }
+
+    func setMode(_ mode: AppState.ConnectionMode) async {
+        let token = self.deps.token()
+        let password = self.deps.password()
+        switch mode {
+        case .local:
+            self.cancelRemoteEnsure()
+            let port = self.deps.localPort()
+            let host = await self.deps.localHost()
+            let scheme = GatewayEndpointStore.resolveGatewayScheme(
+                root: OpenClawConfigFile.loadDict(),
+                env: ProcessInfo.processInfo.environment)
+            self.setState(.ready(
+                mode: .local,
+                url: URL(string: "\(scheme)://\(host):\(port)")!,
+                token: token,
+                password: password))
+        case .remote:
+            let root = OpenClawConfigFile.loadDict()
+            if GatewayRemoteConfig.resolveTransport(root: root) == .direct {
+                guard let url = GatewayRemoteConfig.resolveGatewayUrl(root: root) else {
+                    self.cancelRemoteEnsure()
+                    self.setState(.unavailable(
+                        mode: .remote,
+                        reason: "gateway.remote.url missing or invalid for direct transport"))
+                    return
+                }
+                self.cancelRemoteEnsure()
+                self.setState(.ready(mode: .remote, url: url, token: token, password: password))
+                return
+            }
+            let port = await self.deps.remotePortIfRunning()
+            guard let port else {
+                self.setState(.connecting(mode: .remote, detail: Self.remoteConnectingDetail))
+                self.kickRemoteEnsureIfNeeded(detail: Self.remoteConnectingDetail)
+                return
+            }
+            self.cancelRemoteEnsure()
+            let scheme = GatewayEndpointStore.resolveGatewayScheme(
+                root: OpenClawConfigFile.loadDict(),
+                env: ProcessInfo.processInfo.environment)
+            self.setState(.ready(
+                mode: .remote,
+                url: URL(string: "\(scheme)://127.0.0.1:\(Int(port))")!,
+                token: token,
+                password: password))
+        case .unconfigured:
+            self.cancelRemoteEnsure()
+            self.setState(.unavailable(mode: .unconfigured, reason: "Gateway not configured"))
+        }
+    }
+
+    /// Explicit action: ensure the remote control tunnel is established and publish the resolved endpoint.
+    func ensureRemoteControlTunnel() async throws -> UInt16 {
+        let mode = await self.deps.mode()
+        guard mode == .remote else {
+            throw NSError(
+                domain: "RemoteTunnel",
+                code: 1,
+                userInfo: [NSLocalizedDescriptionKey: "Remote mode is not enabled"])
+        }
+        let root = OpenClawConfigFile.loadDict()
+        if GatewayRemoteConfig.resolveTransport(root: root) == .direct {
+            guard let url = GatewayRemoteConfig.resolveGatewayUrl(root: root) else {
+                throw NSError(
+                    domain: "GatewayEndpoint",
+                    code: 1,
+                    userInfo: [NSLocalizedDescriptionKey: "gateway.remote.url missing or invalid"])
+            }
+            guard let port = GatewayRemoteConfig.defaultPort(for: url),
+                  let portInt = UInt16(exactly: port)
+            else {
+                throw NSError(
+                    domain: "GatewayEndpoint",
+                    code: 1,
+                    userInfo: [NSLocalizedDescriptionKey: "Invalid gateway.remote.url port"])
+            }
+            self.logger.info("remote transport direct; skipping SSH tunnel")
+            return portInt
+        }
+        let config = try await self.ensureRemoteConfig(detail: Self.remoteConnectingDetail)
+        guard let portInt = config.0.port, let port = UInt16(exactly: portInt) else {
+            throw NSError(
+                domain: "GatewayEndpoint",
+                code: 1,
+                userInfo: [NSLocalizedDescriptionKey: "Missing tunnel port"])
+        }
+        return port
+    }
+
+    func requireConfig() async throws -> GatewayConnection.Config {
+        await self.refresh()
+        switch self.state {
+        case let .ready(_, url, token, password):
+            return (url, token, password)
+        case let .connecting(mode, _):
+            guard mode == .remote else {
+                throw NSError(domain: "GatewayEndpoint", code: 1, userInfo: [NSLocalizedDescriptionKey: "Connecting…"])
+            }
+            return try await self.ensureRemoteConfig(detail: Self.remoteConnectingDetail)
+        case let .unavailable(mode, reason):
+            guard mode == .remote else {
+                throw NSError(domain: "GatewayEndpoint", code: 1, userInfo: [NSLocalizedDescriptionKey: reason])
+            }
+
+            // Auto-recover for remote mode: if the SSH control tunnel died (or hasn't been created yet),
+            // recreate it on demand so callers can recover without a manual reconnect.
+            self.logger.info(
+                "endpoint unavailable; ensuring remote control tunnel reason=\(reason, privacy: .public)")
+            return try await self.ensureRemoteConfig(detail: Self.remoteConnectingDetail)
+        }
+    }
+
+    private func cancelRemoteEnsure() {
+        self.remoteEnsure?.task.cancel()
+        self.remoteEnsure = nil
+    }
+
+    private func kickRemoteEnsureIfNeeded(detail: String) {
+        if self.remoteEnsure != nil {
+            self.setState(.connecting(mode: .remote, detail: detail))
+            return
+        }
+
+        let deps = self.deps
+        let token = UUID()
+        let task = Task.detached(priority: .utility) { try await deps.ensureRemoteTunnel() }
+        self.remoteEnsure = (token: token, task: task)
+        self.setState(.connecting(mode: .remote, detail: detail))
+    }
+
+    private func ensureRemoteConfig(detail: String) async throws -> GatewayConnection.Config {
+        let mode = await self.deps.mode()
+        guard mode == .remote else {
+            throw NSError(
+                domain: "RemoteTunnel",
+                code: 1,
+                userInfo: [NSLocalizedDescriptionKey: "Remote mode is not enabled"])
+        }
+
+        let root = OpenClawConfigFile.loadDict()
+        if GatewayRemoteConfig.resolveTransport(root: root) == .direct {
+            guard let url = GatewayRemoteConfig.resolveGatewayUrl(root: root) else {
+                throw NSError(
+                    domain: "GatewayEndpoint",
+                    code: 1,
+                    userInfo: [NSLocalizedDescriptionKey: "gateway.remote.url missing or invalid"])
+            }
+            let token = self.deps.token()
+            let password = self.deps.password()
+            self.cancelRemoteEnsure()
+            self.setState(.ready(mode: .remote, url: url, token: token, password: password))
+            return (url, token, password)
+        }
+
+        self.kickRemoteEnsureIfNeeded(detail: detail)
+        guard let ensure = self.remoteEnsure else {
+            throw NSError(domain: "GatewayEndpoint", code: 1, userInfo: [NSLocalizedDescriptionKey: "Connecting…"])
+        }
+
+        do {
+            let forwarded = try await ensure.task.value
+            let stillRemote = await self.deps.mode() == .remote
+            guard stillRemote else {
+                throw NSError(
+                    domain: "RemoteTunnel",
+                    code: 1,
+                    userInfo: [NSLocalizedDescriptionKey: "Remote mode is not enabled"])
+            }
+
+            if self.remoteEnsure?.token == ensure.token {
+                self.remoteEnsure = nil
+            }
+
+            let token = self.deps.token()
+            let password = self.deps.password()
+            let scheme = GatewayEndpointStore.resolveGatewayScheme(
+                root: OpenClawConfigFile.loadDict(),
+                env: ProcessInfo.processInfo.environment)
+            let url = URL(string: "\(scheme)://127.0.0.1:\(Int(forwarded))")!
+            self.setState(.ready(mode: .remote, url: url, token: token, password: password))
+            return (url, token, password)
+        } catch let err as CancellationError {
+            if self.remoteEnsure?.token == ensure.token {
+                self.remoteEnsure = nil
+            }
+            throw err
+        } catch {
+            if self.remoteEnsure?.token == ensure.token {
+                self.remoteEnsure = nil
+            }
+            let msg = "Remote control tunnel failed (\(error.localizedDescription))"
+            self.setState(.unavailable(mode: .remote, reason: msg))
+            self.logger.error("remote control tunnel ensure failed \(msg, privacy: .public)")
+            throw NSError(domain: "GatewayEndpoint", code: 1, userInfo: [NSLocalizedDescriptionKey: msg])
+        }
+    }
+
+    private func removeSubscriber(_ id: UUID) {
+        self.subscribers[id] = nil
+    }
+
+    private func setState(_ next: GatewayEndpointState) {
+        guard next != self.state else { return }
+        self.state = next
+        for (_, continuation) in self.subscribers {
+            continuation.yield(next)
+        }
+        switch next {
+        case let .ready(mode, url, _, _):
+            let modeDesc = String(describing: mode)
+            let urlDesc = url.absoluteString
+            self.logger
+                .debug(
+                    "resolved endpoint mode=\(modeDesc, privacy: .public) url=\(urlDesc, privacy: .public)")
+        case let .connecting(mode, detail):
+            let modeDesc = String(describing: mode)
+            self.logger
+                .debug(
+                    "endpoint connecting mode=\(modeDesc, privacy: .public) detail=\(detail, privacy: .public)")
+        case let .unavailable(mode, reason):
+            let modeDesc = String(describing: mode)
+            self.logger
+                .debug(
+                    "endpoint unavailable mode=\(modeDesc, privacy: .public) reason=\(reason, privacy: .public)")
+        }
+    }
+
+    func maybeFallbackToTailnet(from currentURL: URL) async -> GatewayConnection.Config? {
+        let mode = await self.deps.mode()
+        guard mode == .local else { return nil }
+
+        let root = OpenClawConfigFile.loadDict()
+        let bind = GatewayEndpointStore.resolveGatewayBindMode(
+            root: root,
+            env: ProcessInfo.processInfo.environment)
+        guard bind == "tailnet" else { return nil }
+
+        let currentHost = currentURL.host?.lowercased() ?? ""
+        guard currentHost == "127.0.0.1" || currentHost == "localhost" else { return nil }
+
+        let tailscaleIP = await MainActor.run { TailscaleService.shared.tailscaleIP }
+            ?? TailscaleService.fallbackTailnetIPv4()
+        guard let tailscaleIP, !tailscaleIP.isEmpty else { return nil }
+
+        let scheme = GatewayEndpointStore.resolveGatewayScheme(
+            root: root,
+            env: ProcessInfo.processInfo.environment)
+        let port = self.deps.localPort()
+        let token = self.deps.token()
+        let password = self.deps.password()
+        let url = URL(string: "\(scheme)://\(tailscaleIP):\(port)")!
+
+        self.logger.info("auto bind fallback to tailnet host=\(tailscaleIP, privacy: .public)")
+        self.setState(.ready(mode: .local, url: url, token: token, password: password))
+        return (url, token, password)
+    }
+
+    private static func resolveGatewayBindMode(
+        root: [String: Any],
+        env: [String: String]) -> String?
+    {
+        if let envBind = env["OPENCLAW_GATEWAY_BIND"] {
+            let trimmed = envBind.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+            if self.supportedBindModes.contains(trimmed) {
+                return trimmed
+            }
+        }
+        if let gateway = root["gateway"] as? [String: Any],
+           let bind = gateway["bind"] as? String
+        {
+            let trimmed = bind.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+            if self.supportedBindModes.contains(trimmed) {
+                return trimmed
+            }
+        }
+        return nil
+    }
+
+    private static func resolveGatewayCustomBindHost(root: [String: Any]) -> String? {
+        if let gateway = root["gateway"] as? [String: Any],
+           let customBindHost = gateway["customBindHost"] as? String
+        {
+            let trimmed = customBindHost.trimmingCharacters(in: .whitespacesAndNewlines)
+            return trimmed.isEmpty ? nil : trimmed
+        }
+        return nil
+    }
+
+    private static func resolveGatewayScheme(
+        root: [String: Any],
+        env: [String: String]) -> String
+    {
+        if let envValue = env["OPENCLAW_GATEWAY_TLS"]?.trimmingCharacters(in: .whitespacesAndNewlines),
+           !envValue.isEmpty
+        {
+            return (envValue == "1" || envValue.lowercased() == "true") ? "wss" : "ws"
+        }
+        if let gateway = root["gateway"] as? [String: Any],
+           let tls = gateway["tls"] as? [String: Any],
+           let enabled = tls["enabled"] as? Bool
+        {
+            return enabled ? "wss" : "ws"
+        }
+        return "ws"
+    }
+
+    private static func resolveLocalGatewayHost(
+        bindMode: String?,
+        customBindHost: String?,
+        tailscaleIP: String?) -> String
+    {
+        switch bindMode {
+        case "tailnet":
+            tailscaleIP ?? "127.0.0.1"
+        case "auto":
+            "127.0.0.1"
+        case "custom":
+            customBindHost ?? "127.0.0.1"
+        default:
+            "127.0.0.1"
+        }
+    }
+}
+
+extension GatewayEndpointStore {
+    private static func normalizeDashboardPath(_ rawPath: String?) -> String {
+        let trimmed = (rawPath ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return "/" }
+        let withLeadingSlash = trimmed.hasPrefix("/") ? trimmed : "/" + trimmed
+        guard withLeadingSlash != "/" else { return "/" }
+        return withLeadingSlash.hasSuffix("/") ? withLeadingSlash : withLeadingSlash + "/"
+    }
+
+    private static func localControlUiBasePath() -> String {
+        let root = OpenClawConfigFile.loadDict()
+        guard let gateway = root["gateway"] as? [String: Any],
+              let controlUi = gateway["controlUi"] as? [String: Any]
+        else {
+            return "/"
+        }
+        return self.normalizeDashboardPath(controlUi["basePath"] as? String)
+    }
+
+    static func dashboardURL(
+        for config: GatewayConnection.Config,
+        mode: AppState.ConnectionMode,
+        localBasePath: String? = nil) throws -> URL
+    {
+        guard var components = URLComponents(url: config.url, resolvingAgainstBaseURL: false) else {
+            throw NSError(domain: "Dashboard", code: 1, userInfo: [
+                NSLocalizedDescriptionKey: "Invalid gateway URL",
+            ])
+        }
+        switch components.scheme?.lowercased() {
+        case "ws":
+            components.scheme = "http"
+        case "wss":
+            components.scheme = "https"
+        default:
+            components.scheme = "http"
+        }
+
+        let urlPath = self.normalizeDashboardPath(components.path)
+        if urlPath != "/" {
+            components.path = urlPath
+        } else if mode == .local {
+            let fallbackPath = localBasePath ?? self.localControlUiBasePath()
+            components.path = self.normalizeDashboardPath(fallbackPath)
+        } else {
+            components.path = "/"
+        }
+
+        var queryItems: [URLQueryItem] = []
+        if let token = config.token?.trimmingCharacters(in: .whitespacesAndNewlines),
+           !token.isEmpty
+        {
+            queryItems.append(URLQueryItem(name: "token", value: token))
+        }
+        if let password = config.password?.trimmingCharacters(in: .whitespacesAndNewlines),
+           !password.isEmpty
+        {
+            queryItems.append(URLQueryItem(name: "password", value: password))
+        }
+        components.queryItems = queryItems.isEmpty ? nil : queryItems
+        guard let url = components.url else {
+            throw NSError(domain: "Dashboard", code: 2, userInfo: [
+                NSLocalizedDescriptionKey: "Failed to build dashboard URL",
+            ])
+        }
+        return url
+    }
+}
+
+#if DEBUG
+extension GatewayEndpointStore {
+    static func _testResolveGatewayPassword(
+        isRemote: Bool,
+        root: [String: Any],
+        env: [String: String],
+        launchdSnapshot: LaunchAgentPlistSnapshot? = nil) -> String?
+    {
+        self.resolveGatewayPassword(isRemote: isRemote, root: root, env: env, launchdSnapshot: launchdSnapshot)
+    }
+
+    static func _testResolveGatewayToken(
+        isRemote: Bool,
+        root: [String: Any],
+        env: [String: String],
+        launchdSnapshot: LaunchAgentPlistSnapshot? = nil) -> String?
+    {
+        self.resolveGatewayToken(isRemote: isRemote, root: root, env: env, launchdSnapshot: launchdSnapshot)
+    }
+
+    static func _testResolveGatewayBindMode(
+        root: [String: Any],
+        env: [String: String]) -> String?
+    {
+        self.resolveGatewayBindMode(root: root, env: env)
+    }
+
+    static func _testResolveLocalGatewayHost(
+        bindMode: String?,
+        tailscaleIP: String?,
+        customBindHost: String? = nil) -> String
+    {
+        self.resolveLocalGatewayHost(
+            bindMode: bindMode,
+            customBindHost: customBindHost,
+            tailscaleIP: tailscaleIP)
+    }
+}
+#endif

openclaw/apps/macos/Sources/OpenClaw/GatewayEnvironment.swift

@@ -0,0 +1,344 @@
+import Foundation
+import OpenClawIPC
+import OSLog
+
+/// Lightweight SemVer helper (major.minor.patch only) for gateway compatibility checks.
+struct Semver: Comparable, CustomStringConvertible, Sendable {
+    let major: Int
+    let minor: Int
+    let patch: Int
+
+    var description: String {
+        "\(self.major).\(self.minor).\(self.patch)"
+    }
+
+    static func < (lhs: Semver, rhs: Semver) -> Bool {
+        if lhs.major != rhs.major { return lhs.major < rhs.major }
+        if lhs.minor != rhs.minor { return lhs.minor < rhs.minor }
+        return lhs.patch < rhs.patch
+    }
+
+    static func parse(_ raw: String?) -> Semver? {
+        guard let raw, !raw.isEmpty else { return nil }
+        let cleaned = raw.trimmingCharacters(in: .whitespacesAndNewlines)
+            .replacingOccurrences(of: "^v", with: "", options: .regularExpression)
+        let parts = cleaned.split(separator: ".")
+        guard parts.count >= 3,
+              let major = Int(parts[0]),
+              let minor = Int(parts[1])
+        else { return nil }
+        // Strip prerelease suffix (e.g., "11-4" → "11", "5-beta.1" → "5")
+        let patchRaw = String(parts[2])
+        guard let patchToken = patchRaw.split(whereSeparator: { $0 == "-" || $0 == "+" }).first,
+              let patchNumeric = Int(patchToken)
+        else {
+            return nil
+        }
+        return Semver(major: major, minor: minor, patch: patchNumeric)
+    }
+
+    func compatible(with required: Semver) -> Bool {
+        // Same major and not older than required.
+        self.major == required.major && self >= required
+    }
+}
+
+enum GatewayEnvironmentKind: Equatable {
+    case checking
+    case ok
+    case missingNode
+    case missingGateway
+    case incompatible(found: String, required: String)
+    case error(String)
+}
+
+struct GatewayEnvironmentStatus: Equatable {
+    let kind: GatewayEnvironmentKind
+    let nodeVersion: String?
+    let gatewayVersion: String?
+    let requiredGateway: String?
+    let message: String
+
+    static var checking: Self {
+        .init(kind: .checking, nodeVersion: nil, gatewayVersion: nil, requiredGateway: nil, message: "Checking…")
+    }
+}
+
+struct GatewayCommandResolution {
+    let status: GatewayEnvironmentStatus
+    let command: [String]?
+}
+
+enum GatewayEnvironment {
+    private static let logger = Logger(subsystem: "ai.openclaw", category: "gateway.env")
+    private static let supportedBindModes: Set<String> = ["loopback", "tailnet", "lan", "auto"]
+
+    static func gatewayPort() -> Int {
+        if let raw = ProcessInfo.processInfo.environment["OPENCLAW_GATEWAY_PORT"] {
+            let trimmed = raw.trimmingCharacters(in: .whitespacesAndNewlines)
+            if let parsed = Int(trimmed), parsed > 0 { return parsed }
+        }
+        if let configPort = OpenClawConfigFile.gatewayPort(), configPort > 0 {
+            return configPort
+        }
+        let stored = UserDefaults.standard.integer(forKey: "gatewayPort")
+        return stored > 0 ? stored : 18789
+    }
+
+    static func expectedGatewayVersion() -> Semver? {
+        Semver.parse(self.expectedGatewayVersionString())
+    }
+
+    static func expectedGatewayVersionString() -> String? {
+        let bundleVersion = Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String
+        let trimmed = bundleVersion?.trimmingCharacters(in: .whitespacesAndNewlines)
+        return (trimmed?.isEmpty == false) ? trimmed : nil
+    }
+
+    /// Exposed for tests so we can inject fake version checks without rewriting bundle metadata.
+    static func expectedGatewayVersion(from versionString: String?) -> Semver? {
+        Semver.parse(versionString)
+    }
+
+    static func check() -> GatewayEnvironmentStatus {
+        let start = Date()
+        defer {
+            let elapsedMs = Int(Date().timeIntervalSince(start) * 1000)
+            if elapsedMs > 500 {
+                self.logger.warning("gateway env check slow (\(elapsedMs, privacy: .public)ms)")
+            } else {
+                self.logger.debug("gateway env check ok (\(elapsedMs, privacy: .public)ms)")
+            }
+        }
+        let expected = self.expectedGatewayVersion()
+        let expectedString = self.expectedGatewayVersionString()
+
+        let projectRoot = CommandResolver.projectRoot()
+        let projectEntrypoint = CommandResolver.gatewayEntrypoint(in: projectRoot)
+
+        switch RuntimeLocator.resolve(searchPaths: CommandResolver.preferredPaths()) {
+        case let .failure(err):
+            return GatewayEnvironmentStatus(
+                kind: .missingNode,
+                nodeVersion: nil,
+                gatewayVersion: nil,
+                requiredGateway: expectedString,
+                message: RuntimeLocator.describeFailure(err))
+        case let .success(runtime):
+            let gatewayBin = CommandResolver.openclawExecutable()
+
+            if gatewayBin == nil, projectEntrypoint == nil {
+                return GatewayEnvironmentStatus(
+                    kind: .missingGateway,
+                    nodeVersion: runtime.version.description,
+                    gatewayVersion: nil,
+                    requiredGateway: expectedString,
+                    message: "openclaw CLI not found in PATH; install the CLI.")
+            }
+
+            let installed = gatewayBin.flatMap { self.readGatewayVersion(binary: $0) }
+                ?? self.readLocalGatewayVersion(projectRoot: projectRoot)
+
+            if let expected, let installed, !installed.compatible(with: expected) {
+                let expectedText = expectedString ?? expected.description
+                return GatewayEnvironmentStatus(
+                    kind: .incompatible(found: installed.description, required: expectedText),
+                    nodeVersion: runtime.version.description,
+                    gatewayVersion: installed.description,
+                    requiredGateway: expectedText,
+                    message: """
+                    Gateway version \(installed.description) is incompatible with app \(expectedText);
+                    install or update the global package.
+                    """)
+            }
+
+            let gatewayLabel = gatewayBin != nil ? "global" : "local"
+            let gatewayVersionText = installed?.description ?? "unknown"
+            // Avoid repeating "(local)" twice; if using the local entrypoint, show the path once.
+            let localPathHint = gatewayBin == nil && projectEntrypoint != nil
+                ? " (local: \(projectEntrypoint ?? "unknown"))"
+                : ""
+            let gatewayLabelText = gatewayBin != nil
+                ? "(\(gatewayLabel))"
+                : localPathHint.isEmpty ? "(\(gatewayLabel))" : localPathHint
+            return GatewayEnvironmentStatus(
+                kind: .ok,
+                nodeVersion: runtime.version.description,
+                gatewayVersion: gatewayVersionText,
+                requiredGateway: expectedString,
+                message: "Node \(runtime.version.description); gateway \(gatewayVersionText) \(gatewayLabelText)")
+        }
+    }
+
+    static func resolveGatewayCommand() -> GatewayCommandResolution {
+        let start = Date()
+        defer {
+            let elapsedMs = Int(Date().timeIntervalSince(start) * 1000)
+            if elapsedMs > 500 {
+                self.logger.warning("gateway command resolve slow (\(elapsedMs, privacy: .public)ms)")
+            } else {
+                self.logger.debug("gateway command resolve ok (\(elapsedMs, privacy: .public)ms)")
+            }
+        }
+        let projectRoot = CommandResolver.projectRoot()
+        let projectEntrypoint = CommandResolver.gatewayEntrypoint(in: projectRoot)
+        let status = self.check()
+        let gatewayBin = CommandResolver.openclawExecutable()
+        let runtime = RuntimeLocator.resolve(searchPaths: CommandResolver.preferredPaths())
+
+        guard case .ok = status.kind else {
+            return GatewayCommandResolution(status: status, command: nil)
+        }
+
+        let port = self.gatewayPort()
+        if let gatewayBin {
+            let bind = self.preferredGatewayBind() ?? "loopback"
+            let cmd = [gatewayBin, "gateway-daemon", "--port", "\(port)", "--bind", bind]
+            return GatewayCommandResolution(status: status, command: cmd)
+        }
+
+        if let entry = projectEntrypoint,
+           case let .success(resolvedRuntime) = runtime
+        {
+            let bind = self.preferredGatewayBind() ?? "loopback"
+            let cmd = [resolvedRuntime.path, entry, "gateway-daemon", "--port", "\(port)", "--bind", bind]
+            return GatewayCommandResolution(status: status, command: cmd)
+        }
+
+        return GatewayCommandResolution(status: status, command: nil)
+    }
+
+    private static func preferredGatewayBind() -> String? {
+        if CommandResolver.connectionModeIsRemote() {
+            return nil
+        }
+        if let env = ProcessInfo.processInfo.environment["OPENCLAW_GATEWAY_BIND"] {
+            let trimmed = env.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+            if self.supportedBindModes.contains(trimmed) {
+                return trimmed
+            }
+        }
+
+        let root = OpenClawConfigFile.loadDict()
+        if let gateway = root["gateway"] as? [String: Any],
+           let bind = gateway["bind"] as? String
+        {
+            let trimmed = bind.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+            if self.supportedBindModes.contains(trimmed) {
+                return trimmed
+            }
+        }
+
+        return nil
+    }
+
+    static func installGlobal(version: Semver?, statusHandler: @escaping @Sendable (String) -> Void) async {
+        await self.installGlobal(versionString: version?.description, statusHandler: statusHandler)
+    }
+
+    static func installGlobal(versionString: String?, statusHandler: @escaping @Sendable (String) -> Void) async {
+        let preferred = CommandResolver.preferredPaths().joined(separator: ":")
+        let trimmed = versionString?.trimmingCharacters(in: .whitespacesAndNewlines)
+        let target: String = if let trimmed, !trimmed.isEmpty {
+            trimmed
+        } else {
+            "latest"
+        }
+        let npm = CommandResolver.findExecutable(named: "npm")
+        let pnpm = CommandResolver.findExecutable(named: "pnpm")
+        let bun = CommandResolver.findExecutable(named: "bun")
+        let (label, cmd): (String, [String]) =
+            if let npm {
+                ("npm", [npm, "install", "-g", "openclaw@\(target)"])
+            } else if let pnpm {
+                ("pnpm", [pnpm, "add", "-g", "openclaw@\(target)"])
+            } else if let bun {
+                ("bun", [bun, "add", "-g", "openclaw@\(target)"])
+            } else {
+                ("npm", ["npm", "install", "-g", "openclaw@\(target)"])
+            }
+
+        statusHandler("Installing openclaw@\(target) via \(label)…")
+
+        func summarize(_ text: String) -> String? {
+            let lines = text
+                .split(whereSeparator: \.isNewline)
+                .map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }
+                .filter { !$0.isEmpty }
+            guard let last = lines.last else { return nil }
+            let normalized = last.replacingOccurrences(of: "\\s+", with: " ", options: .regularExpression)
+            return normalized.count > 200 ? String(normalized.prefix(199)) + "…" : normalized
+        }
+
+        let response = await ShellExecutor.runDetailed(command: cmd, cwd: nil, env: ["PATH": preferred], timeout: 300)
+        if response.success {
+            statusHandler("Installed openclaw@\(target)")
+        } else {
+            if response.timedOut {
+                statusHandler("Install failed: timed out. Check your internet connection and try again.")
+                return
+            }
+
+            let exit = response.exitCode.map { "exit \($0)" } ?? (response.errorMessage ?? "failed")
+            let detail = summarize(response.stderr) ?? summarize(response.stdout)
+            if let detail {
+                statusHandler("Install failed (\(exit)): \(detail)")
+            } else {
+                statusHandler("Install failed (\(exit))")
+            }
+        }
+    }
+
+    // MARK: - Internals
+
+    private static func readGatewayVersion(binary: String) -> Semver? {
+        let start = Date()
+        let process = Process()
+        process.executableURL = URL(fileURLWithPath: binary)
+        process.arguments = ["--version"]
+        process.environment = ["PATH": CommandResolver.preferredPaths().joined(separator: ":")]
+
+        let pipe = Pipe()
+        process.standardOutput = pipe
+        process.standardError = pipe
+        do {
+            let data = try process.runAndReadToEnd(from: pipe)
+            let elapsedMs = Int(Date().timeIntervalSince(start) * 1000)
+            if elapsedMs > 500 {
+                self.logger.warning(
+                    """
+                    gateway --version slow (\(elapsedMs, privacy: .public)ms) \
+                    bin=\(binary, privacy: .public)
+                    """)
+            } else {
+                self.logger.debug(
+                    """
+                    gateway --version ok (\(elapsedMs, privacy: .public)ms) \
+                    bin=\(binary, privacy: .public)
+                    """)
+            }
+            let raw = String(data: data, encoding: .utf8)?
+                .trimmingCharacters(in: .whitespacesAndNewlines)
+            return Semver.parse(raw)
+        } catch {
+            let elapsedMs = Int(Date().timeIntervalSince(start) * 1000)
+            self.logger.error(
+                """
+                gateway --version failed (\(elapsedMs, privacy: .public)ms) \
+                bin=\(binary, privacy: .public) \
+                err=\(error.localizedDescription, privacy: .public)
+                """)
+            return nil
+        }
+    }
+
+    private static func readLocalGatewayVersion(projectRoot: URL) -> Semver? {
+        let pkg = projectRoot.appendingPathComponent("package.json")
+        guard let data = try? Data(contentsOf: pkg) else { return nil }
+        guard
+            let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
+            let version = json["version"] as? String
+        else { return nil }
+        return Semver.parse(version)
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/GatewayLaunchAgentManager.swift

@@ -0,0 +1,204 @@
+import Foundation
+
+enum GatewayLaunchAgentManager {
+    private static let logger = Logger(subsystem: "ai.openclaw", category: "gateway.launchd")
+    private static let disableLaunchAgentMarker = ".openclaw/disable-launchagent"
+
+    private static var disableLaunchAgentMarkerURL: URL {
+        FileManager().homeDirectoryForCurrentUser
+            .appendingPathComponent(self.disableLaunchAgentMarker)
+    }
+
+    private static var plistURL: URL {
+        FileManager().homeDirectoryForCurrentUser
+            .appendingPathComponent("Library/LaunchAgents/\(gatewayLaunchdLabel).plist")
+    }
+
+    static func isLaunchAgentWriteDisabled() -> Bool {
+        if FileManager().fileExists(atPath: self.disableLaunchAgentMarkerURL.path) { return true }
+        return false
+    }
+
+    static func setLaunchAgentWriteDisabled(_ disabled: Bool) -> String? {
+        let marker = self.disableLaunchAgentMarkerURL
+        if disabled {
+            do {
+                try FileManager().createDirectory(
+                    at: marker.deletingLastPathComponent(),
+                    withIntermediateDirectories: true)
+                if !FileManager().fileExists(atPath: marker.path) {
+                    FileManager().createFile(atPath: marker.path, contents: nil)
+                }
+            } catch {
+                return error.localizedDescription
+            }
+            return nil
+        }
+
+        if FileManager().fileExists(atPath: marker.path) {
+            do {
+                try FileManager().removeItem(at: marker)
+            } catch {
+                return error.localizedDescription
+            }
+        }
+        return nil
+    }
+
+    static func isLoaded() async -> Bool {
+        guard let loaded = await self.readDaemonLoaded() else { return false }
+        return loaded
+    }
+
+    static func set(enabled: Bool, bundlePath: String, port: Int) async -> String? {
+        _ = bundlePath
+        guard !CommandResolver.connectionModeIsRemote() else {
+            self.logger.info("launchd change skipped (remote mode)")
+            return nil
+        }
+        if enabled, self.isLaunchAgentWriteDisabled() {
+            self.logger.info("launchd enable skipped (disable marker set)")
+            return nil
+        }
+
+        if enabled {
+            self.logger.info("launchd enable requested via CLI port=\(port)")
+            return await self.runDaemonCommand([
+                "install",
+                "--force",
+                "--port",
+                "\(port)",
+                "--runtime",
+                "node",
+            ])
+        }
+
+        self.logger.info("launchd disable requested via CLI")
+        return await self.runDaemonCommand(["uninstall"])
+    }
+
+    static func kickstart() async {
+        _ = await self.runDaemonCommand(["restart"], timeout: 20)
+    }
+
+    static func launchdConfigSnapshot() -> LaunchAgentPlistSnapshot? {
+        LaunchAgentPlist.snapshot(url: self.plistURL)
+    }
+
+    static func launchdGatewayLogPath() -> String {
+        let snapshot = self.launchdConfigSnapshot()
+        if let stdout = snapshot?.stdoutPath?.trimmingCharacters(in: .whitespacesAndNewlines),
+           !stdout.isEmpty
+        {
+            return stdout
+        }
+        if let stderr = snapshot?.stderrPath?.trimmingCharacters(in: .whitespacesAndNewlines),
+           !stderr.isEmpty
+        {
+            return stderr
+        }
+        return LogLocator.launchdGatewayLogPath
+    }
+}
+
+extension GatewayLaunchAgentManager {
+    private static func readDaemonLoaded() async -> Bool? {
+        let result = await self.runDaemonCommandResult(
+            ["status", "--json", "--no-probe"],
+            timeout: 15,
+            quiet: true)
+        guard result.success, let payload = result.payload else { return nil }
+        guard
+            let json = try? JSONSerialization.jsonObject(with: payload) as? [String: Any],
+            let service = json["service"] as? [String: Any],
+            let loaded = service["loaded"] as? Bool
+        else {
+            return nil
+        }
+        return loaded
+    }
+
+    private struct CommandResult {
+        let success: Bool
+        let payload: Data?
+        let message: String?
+    }
+
+    private struct ParsedDaemonJson {
+        let text: String
+        let object: [String: Any]
+    }
+
+    private static func runDaemonCommand(
+        _ args: [String],
+        timeout: Double = 15,
+        quiet: Bool = false) async -> String?
+    {
+        let result = await self.runDaemonCommandResult(args, timeout: timeout, quiet: quiet)
+        if result.success { return nil }
+        return result.message ?? "Gateway daemon command failed"
+    }
+
+    private static func runDaemonCommandResult(
+        _ args: [String],
+        timeout: Double,
+        quiet: Bool) async -> CommandResult
+    {
+        let command = CommandResolver.openclawCommand(
+            subcommand: "gateway",
+            extraArgs: self.withJsonFlag(args),
+            // Launchd management must always run locally, even if remote mode is configured.
+            configRoot: ["gateway": ["mode": "local"]])
+        var env = ProcessInfo.processInfo.environment
+        env["PATH"] = CommandResolver.preferredPaths().joined(separator: ":")
+        let response = await ShellExecutor.runDetailed(command: command, cwd: nil, env: env, timeout: timeout)
+        let parsed = self.parseDaemonJson(from: response.stdout) ?? self.parseDaemonJson(from: response.stderr)
+        let ok = parsed?.object["ok"] as? Bool
+        let message = (parsed?.object["error"] as? String) ?? (parsed?.object["message"] as? String)
+        let payload = parsed?.text.data(using: .utf8)
+            ?? (response.stdout.isEmpty ? response.stderr : response.stdout).data(using: .utf8)
+        let success = ok ?? response.success
+        if success {
+            return CommandResult(success: true, payload: payload, message: nil)
+        }
+
+        if quiet {
+            return CommandResult(success: false, payload: payload, message: message)
+        }
+
+        let detail = message ?? self.summarize(response.stderr) ?? self.summarize(response.stdout)
+        let exit = response.exitCode.map { "exit \($0)" } ?? (response.errorMessage ?? "failed")
+        let fullMessage = detail.map { "Gateway daemon command failed (\(exit)): \($0)" }
+            ?? "Gateway daemon command failed (\(exit))"
+        self.logger.error("\(fullMessage, privacy: .public)")
+        return CommandResult(success: false, payload: payload, message: detail)
+    }
+
+    private static func withJsonFlag(_ args: [String]) -> [String] {
+        if args.contains("--json") { return args }
+        return args + ["--json"]
+    }
+
+    private static func parseDaemonJson(from raw: String) -> ParsedDaemonJson? {
+        let trimmed = raw.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard let start = trimmed.firstIndex(of: "{"),
+              let end = trimmed.lastIndex(of: "}")
+        else {
+            return nil
+        }
+        let jsonText = String(trimmed[start...end])
+        guard let data = jsonText.data(using: .utf8) else { return nil }
+        guard let object = try? JSONSerialization.jsonObject(with: data) as? [String: Any] else { return nil }
+        return ParsedDaemonJson(text: jsonText, object: object)
+    }
+
+    private static func summarize(_ text: String) -> String? {
+        let lines = text
+            .split(whereSeparator: \.isNewline)
+            .map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }
+            .filter { !$0.isEmpty }
+        guard let last = lines.last else { return nil }
+        let normalized = last.replacingOccurrences(of: "\\s+", with: " ", options: .regularExpression)
+        return normalized.count > 200 ? String(normalized.prefix(199)) + "…" : normalized
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/GatewayProcessManager.swift

@@ -0,0 +1,432 @@
+import Foundation
+import Observation
+
+@MainActor
+@Observable
+final class GatewayProcessManager {
+    static let shared = GatewayProcessManager()
+
+    enum Status: Equatable {
+        case stopped
+        case starting
+        case running(details: String?)
+        case attachedExisting(details: String?)
+        case failed(String)
+
+        var label: String {
+            switch self {
+            case .stopped: return "Stopped"
+            case .starting: return "Starting…"
+            case let .running(details):
+                if let details, !details.isEmpty { return "Running (\(details))" }
+                return "Running"
+            case let .attachedExisting(details):
+                if let details, !details.isEmpty {
+                    return "Using existing gateway (\(details))"
+                }
+                return "Using existing gateway"
+            case let .failed(reason): return "Failed: \(reason)"
+            }
+        }
+    }
+
+    private(set) var status: Status = .stopped {
+        didSet { CanvasManager.shared.refreshDebugStatus() }
+    }
+
+    private(set) var log: String = ""
+    private(set) var environmentStatus: GatewayEnvironmentStatus = .checking
+    private(set) var existingGatewayDetails: String?
+    private(set) var lastFailureReason: String?
+    private var desiredActive = false
+    private var environmentRefreshTask: Task<Void, Never>?
+    private var lastEnvironmentRefresh: Date?
+    private var logRefreshTask: Task<Void, Never>?
+    #if DEBUG
+    private var testingConnection: GatewayConnection?
+    #endif
+    private let logger = Logger(subsystem: "ai.openclaw", category: "gateway.process")
+
+    private let logLimit = 20000 // characters to keep in-memory
+    private let environmentRefreshMinInterval: TimeInterval = 30
+    private var connection: GatewayConnection {
+        #if DEBUG
+        return self.testingConnection ?? .shared
+        #else
+        return .shared
+        #endif
+    }
+
+    func setActive(_ active: Bool) {
+        // Remote mode should never spawn a local gateway; treat as stopped.
+        if CommandResolver.connectionModeIsRemote() {
+            self.desiredActive = false
+            self.stop()
+            self.status = .stopped
+            self.appendLog("[gateway] remote mode active; skipping local gateway\n")
+            self.logger.info("gateway process skipped: remote mode active")
+            return
+        }
+        self.logger.debug("gateway active requested active=\(active)")
+        self.desiredActive = active
+        self.refreshEnvironmentStatus()
+        if active {
+            self.startIfNeeded()
+        } else {
+            self.stop()
+        }
+    }
+
+    func ensureLaunchAgentEnabledIfNeeded() async {
+        guard !CommandResolver.connectionModeIsRemote() else { return }
+        if GatewayLaunchAgentManager.isLaunchAgentWriteDisabled() {
+            self.appendLog("[gateway] launchd auto-enable skipped (attach-only)\n")
+            self.logger.info("gateway launchd auto-enable skipped (disable marker set)")
+            return
+        }
+        let enabled = await GatewayLaunchAgentManager.isLoaded()
+        guard !enabled else { return }
+        let bundlePath = Bundle.main.bundleURL.path
+        let port = GatewayEnvironment.gatewayPort()
+        self.appendLog("[gateway] auto-enabling launchd job (\(gatewayLaunchdLabel)) on port \(port)\n")
+        let err = await GatewayLaunchAgentManager.set(enabled: true, bundlePath: bundlePath, port: port)
+        if let err {
+            self.appendLog("[gateway] launchd auto-enable failed: \(err)\n")
+        }
+    }
+
+    func startIfNeeded() {
+        guard self.desiredActive else { return }
+        // Do not spawn in remote mode (the gateway should run on the remote host).
+        guard !CommandResolver.connectionModeIsRemote() else {
+            self.status = .stopped
+            return
+        }
+        // Many surfaces can call `setActive(true)` in quick succession (startup, Canvas, health checks).
+        // Avoid spawning multiple concurrent "start" tasks that can thrash launchd and flap the port.
+        switch self.status {
+        case .starting, .running, .attachedExisting:
+            return
+        case .stopped, .failed:
+            break
+        }
+        self.status = .starting
+        self.logger.debug("gateway start requested")
+
+        // First try to latch onto an already-running gateway to avoid spawning a duplicate.
+        Task { [weak self] in
+            guard let self else { return }
+            if await self.attachExistingGatewayIfAvailable() {
+                return
+            }
+            await self.enableLaunchdGateway()
+        }
+    }
+
+    func stop() {
+        self.desiredActive = false
+        self.existingGatewayDetails = nil
+        self.lastFailureReason = nil
+        self.status = .stopped
+        self.logger.info("gateway stop requested")
+        if CommandResolver.connectionModeIsRemote() {
+            return
+        }
+        let bundlePath = Bundle.main.bundleURL.path
+        Task {
+            _ = await GatewayLaunchAgentManager.set(
+                enabled: false,
+                bundlePath: bundlePath,
+                port: GatewayEnvironment.gatewayPort())
+        }
+    }
+
+    func clearLastFailure() {
+        self.lastFailureReason = nil
+    }
+
+    func refreshEnvironmentStatus(force: Bool = false) {
+        let now = Date()
+        if !force {
+            if self.environmentRefreshTask != nil { return }
+            if let last = self.lastEnvironmentRefresh,
+               now.timeIntervalSince(last) < self.environmentRefreshMinInterval
+            {
+                return
+            }
+        }
+        self.lastEnvironmentRefresh = now
+        self.environmentRefreshTask = Task { [weak self] in
+            let status = await Task.detached(priority: .utility) {
+                GatewayEnvironment.check()
+            }.value
+            await MainActor.run {
+                guard let self else { return }
+                self.environmentStatus = status
+                self.environmentRefreshTask = nil
+            }
+        }
+    }
+
+    func refreshLog() {
+        guard self.logRefreshTask == nil else { return }
+        let path = GatewayLaunchAgentManager.launchdGatewayLogPath()
+        let limit = self.logLimit
+        self.logRefreshTask = Task { [weak self] in
+            let log = await Task.detached(priority: .utility) {
+                Self.readGatewayLog(path: path, limit: limit)
+            }.value
+            await MainActor.run {
+                guard let self else { return }
+                if !log.isEmpty {
+                    self.log = log
+                }
+                self.logRefreshTask = nil
+            }
+        }
+    }
+
+    // MARK: - Internals
+
+    /// Attempt to connect to an already-running gateway on the configured port.
+    /// If successful, mark status as attached and skip spawning a new process.
+    private func attachExistingGatewayIfAvailable() async -> Bool {
+        let port = GatewayEnvironment.gatewayPort()
+        let instance = await PortGuardian.shared.describe(port: port)
+        let instanceText = instance.map { self.describe(instance: $0) }
+        let hasListener = instance != nil
+
+        let attemptAttach = {
+            try await self.connection.requestRaw(method: .health, timeoutMs: 2000)
+        }
+
+        for attempt in 0..<(hasListener ? 3 : 1) {
+            do {
+                let data = try await attemptAttach()
+                let snap = decodeHealthSnapshot(from: data)
+                let details = self.describe(details: instanceText, port: port, snap: snap)
+                self.existingGatewayDetails = details
+                self.clearLastFailure()
+                self.status = .attachedExisting(details: details)
+                self.appendLog("[gateway] using existing instance: \(details)\n")
+                self.logger.info("gateway using existing instance details=\(details)")
+                self.refreshControlChannelIfNeeded(reason: "attach existing")
+                self.refreshLog()
+                return true
+            } catch {
+                if attempt < 2, hasListener {
+                    try? await Task.sleep(nanoseconds: 250_000_000)
+                    continue
+                }
+
+                if hasListener {
+                    let reason = self.describeAttachFailure(error, port: port, instance: instance)
+                    self.existingGatewayDetails = instanceText
+                    self.status = .failed(reason)
+                    self.lastFailureReason = reason
+                    self.appendLog("[gateway] existing listener on port \(port) but attach failed: \(reason)\n")
+                    self.logger.warning("gateway attach failed reason=\(reason)")
+                    return true
+                }
+
+                // No reachable gateway (and no listener) — fall through to spawn.
+                self.existingGatewayDetails = nil
+                return false
+            }
+        }
+
+        self.existingGatewayDetails = nil
+        return false
+    }
+
+    private func describe(details instance: String?, port: Int, snap: HealthSnapshot?) -> String {
+        let instanceText = instance ?? "pid unknown"
+        if let snap {
+            let order = snap.channelOrder ?? Array(snap.channels.keys)
+            let linkId = order.first(where: { snap.channels[$0]?.linked == true })
+                ?? order.first(where: { snap.channels[$0]?.linked != nil })
+            guard let linkId else {
+                return "port \(port), health probe succeeded, \(instanceText)"
+            }
+            let linked = snap.channels[linkId]?.linked ?? false
+            let authAge = snap.channels[linkId]?.authAgeMs.flatMap(msToAge) ?? "unknown age"
+            let label =
+                snap.channelLabels?[linkId] ??
+                linkId.capitalized
+            let linkText = linked ? "linked" : "not linked"
+            return "port \(port), \(label) \(linkText), auth \(authAge), \(instanceText)"
+        }
+        return "port \(port), health probe succeeded, \(instanceText)"
+    }
+
+    private func describe(instance: PortGuardian.Descriptor) -> String {
+        let path = instance.executablePath ?? "path unknown"
+        return "pid \(instance.pid) \(instance.command) @ \(path)"
+    }
+
+    private func describeAttachFailure(_ error: Error, port: Int, instance: PortGuardian.Descriptor?) -> String {
+        let ns = error as NSError
+        let message = ns.localizedDescription.isEmpty ? "unknown error" : ns.localizedDescription
+        let lower = message.lowercased()
+        if self.isGatewayAuthFailure(error) {
+            return """
+            Gateway on port \(port) rejected auth. Set gateway.auth.token to match the running gateway \
+            (or clear it on the gateway) and retry.
+            """
+        }
+        if lower.contains("protocol mismatch") {
+            return "Gateway on port \(port) is incompatible (protocol mismatch). Update the app/gateway."
+        }
+        if lower.contains("unexpected response") || lower.contains("invalid response") {
+            return "Port \(port) returned non-gateway data; another process is using it."
+        }
+        if let instance {
+            let instanceText = self.describe(instance: instance)
+            return "Gateway listener found on port \(port) (\(instanceText)) but health check failed: \(message)"
+        }
+        return "Gateway listener found on port \(port) but health check failed: \(message)"
+    }
+
+    private func isGatewayAuthFailure(_ error: Error) -> Bool {
+        if let urlError = error as? URLError, urlError.code == .dataNotAllowed {
+            return true
+        }
+        let ns = error as NSError
+        if ns.domain == "Gateway", ns.code == 1008 { return true }
+        let lower = ns.localizedDescription.lowercased()
+        return lower.contains("unauthorized") || lower.contains("auth")
+    }
+
+    private func enableLaunchdGateway() async {
+        self.existingGatewayDetails = nil
+        let resolution = await Task.detached(priority: .utility) {
+            GatewayEnvironment.resolveGatewayCommand()
+        }.value
+        await MainActor.run { self.environmentStatus = resolution.status }
+        guard resolution.command != nil else {
+            await MainActor.run {
+                self.status = .failed(resolution.status.message)
+            }
+            self.logger.error("gateway command resolve failed: \(resolution.status.message)")
+            return
+        }
+
+        if GatewayLaunchAgentManager.isLaunchAgentWriteDisabled() {
+            let message = "Launchd disabled; start the Gateway manually or disable attach-only."
+            self.status = .failed(message)
+            self.lastFailureReason = "launchd disabled"
+            self.appendLog("[gateway] launchd disabled; skipping auto-start\n")
+            self.logger.info("gateway launchd enable skipped (disable marker set)")
+            return
+        }
+
+        let bundlePath = Bundle.main.bundleURL.path
+        let port = GatewayEnvironment.gatewayPort()
+        self.appendLog("[gateway] enabling launchd job (\(gatewayLaunchdLabel)) on port \(port)\n")
+        self.logger.info("gateway enabling launchd port=\(port)")
+        let err = await GatewayLaunchAgentManager.set(enabled: true, bundlePath: bundlePath, port: port)
+        if let err {
+            self.status = .failed(err)
+            self.lastFailureReason = err
+            self.logger.error("gateway launchd enable failed: \(err)")
+            return
+        }
+
+        // Best-effort: wait for the gateway to accept connections.
+        let deadline = Date().addingTimeInterval(6)
+        while Date() < deadline {
+            if !self.desiredActive { return }
+            do {
+                _ = try await self.connection.requestRaw(method: .health, timeoutMs: 1500)
+                let instance = await PortGuardian.shared.describe(port: port)
+                let details = instance.map { "pid \($0.pid)" }
+                self.clearLastFailure()
+                self.status = .running(details: details)
+                self.logger.info("gateway started details=\(details ?? "ok")")
+                self.refreshControlChannelIfNeeded(reason: "gateway started")
+                self.refreshLog()
+                return
+            } catch {
+                try? await Task.sleep(nanoseconds: 400_000_000)
+            }
+        }
+
+        self.status = .failed("Gateway did not start in time")
+        self.lastFailureReason = "launchd start timeout"
+        self.logger.warning("gateway start timed out")
+    }
+
+    private func appendLog(_ chunk: String) {
+        self.log.append(chunk)
+        if self.log.count > self.logLimit {
+            self.log = String(self.log.suffix(self.logLimit))
+        }
+    }
+
+    private func refreshControlChannelIfNeeded(reason: String) {
+        switch ControlChannel.shared.state {
+        case .connected, .connecting:
+            return
+        case .disconnected, .degraded:
+            break
+        }
+        self.appendLog("[gateway] refreshing control channel (\(reason))\n")
+        self.logger.debug("gateway control channel refresh reason=\(reason)")
+        Task { await ControlChannel.shared.configure() }
+    }
+
+    func waitForGatewayReady(timeout: TimeInterval = 6) async -> Bool {
+        let deadline = Date().addingTimeInterval(timeout)
+        while Date() < deadline {
+            if !self.desiredActive { return false }
+            do {
+                _ = try await self.connection.requestRaw(method: .health, timeoutMs: 1500)
+                self.clearLastFailure()
+                return true
+            } catch {
+                try? await Task.sleep(nanoseconds: 300_000_000)
+            }
+        }
+        self.appendLog("[gateway] readiness wait timed out\n")
+        self.logger.warning("gateway readiness wait timed out")
+        return false
+    }
+
+    func clearLog() {
+        self.log = ""
+        try? FileManager().removeItem(atPath: GatewayLaunchAgentManager.launchdGatewayLogPath())
+        self.logger.debug("gateway log cleared")
+    }
+
+    func setProjectRoot(path: String) {
+        CommandResolver.setProjectRoot(path)
+    }
+
+    func projectRootPath() -> String {
+        CommandResolver.projectRootPath()
+    }
+
+    private nonisolated static func readGatewayLog(path: String, limit: Int) -> String {
+        guard FileManager().fileExists(atPath: path) else { return "" }
+        guard let data = try? Data(contentsOf: URL(fileURLWithPath: path)) else { return "" }
+        let text = String(data: data, encoding: .utf8) ?? ""
+        if text.count <= limit { return text }
+        return String(text.suffix(limit))
+    }
+}
+
+#if DEBUG
+extension GatewayProcessManager {
+    func setTestingConnection(_ connection: GatewayConnection?) {
+        self.testingConnection = connection
+    }
+
+    func setTestingDesiredActive(_ active: Bool) {
+        self.desiredActive = active
+    }
+
+    func setTestingLastFailureReason(_ reason: String?) {
+        self.lastFailureReason = reason
+    }
+}
+#endif

openclaw/apps/macos/Sources/OpenClaw/GatewayRemoteConfig.swift

@@ -0,0 +1,102 @@
+import Foundation
+import Network
+
+enum GatewayRemoteConfig {
+    private static func isLoopbackHost(_ rawHost: String) -> Bool {
+        var host = rawHost
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+            .lowercased()
+            .trimmingCharacters(in: CharacterSet(charactersIn: "[]"))
+        if host.hasSuffix(".") {
+            host.removeLast()
+        }
+        if let zoneIndex = host.firstIndex(of: "%") {
+            host = String(host[..<zoneIndex])
+        }
+        if host.isEmpty {
+            return false
+        }
+        if host == "localhost" || host == "0.0.0.0" || host == "::" {
+            return true
+        }
+
+        if let ipv4 = IPv4Address(host) {
+            return ipv4.rawValue.first == 127
+        }
+        if let ipv6 = IPv6Address(host) {
+            let bytes = Array(ipv6.rawValue)
+            let isV6Loopback = bytes[0..<15].allSatisfy { $0 == 0 } && bytes[15] == 1
+            if isV6Loopback {
+                return true
+            }
+            let isMappedV4 = bytes[0..<10].allSatisfy { $0 == 0 } && bytes[10] == 0xFF && bytes[11] == 0xFF
+            return isMappedV4 && bytes[12] == 127
+        }
+
+        return false
+    }
+
+    static func resolveTransport(root: [String: Any]) -> AppState.RemoteTransport {
+        guard let gateway = root["gateway"] as? [String: Any],
+              let remote = gateway["remote"] as? [String: Any],
+              let raw = remote["transport"] as? String
+        else {
+            return .ssh
+        }
+        let trimmed = raw.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+        return trimmed == AppState.RemoteTransport.direct.rawValue ? .direct : .ssh
+    }
+
+    static func resolveUrlString(root: [String: Any]) -> String? {
+        guard let gateway = root["gateway"] as? [String: Any],
+              let remote = gateway["remote"] as? [String: Any],
+              let urlRaw = remote["url"] as? String
+        else {
+            return nil
+        }
+        let trimmed = urlRaw.trimmingCharacters(in: .whitespacesAndNewlines)
+        return trimmed.isEmpty ? nil : trimmed
+    }
+
+    static func resolveGatewayUrl(root: [String: Any]) -> URL? {
+        guard let raw = self.resolveUrlString(root: root) else { return nil }
+        return self.normalizeGatewayUrl(raw)
+    }
+
+    static func normalizeGatewayUrlString(_ raw: String) -> String? {
+        self.normalizeGatewayUrl(raw)?.absoluteString
+    }
+
+    static func normalizeGatewayUrl(_ raw: String) -> URL? {
+        let trimmed = raw.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty, let url = URL(string: trimmed) else { return nil }
+        let scheme = url.scheme?.lowercased() ?? ""
+        guard scheme == "ws" || scheme == "wss" else { return nil }
+        let host = url.host?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        guard !host.isEmpty else { return nil }
+        if scheme == "ws", !self.isLoopbackHost(host) {
+            return nil
+        }
+        if scheme == "ws", url.port == nil {
+            guard var components = URLComponents(url: url, resolvingAgainstBaseURL: false) else {
+                return url
+            }
+            components.port = 18789
+            return components.url
+        }
+        return url
+    }
+
+    static func defaultPort(for url: URL) -> Int? {
+        if let port = url.port { return port }
+        let scheme = url.scheme?.lowercased() ?? ""
+        switch scheme {
+        case "wss":
+            return 443
+        case "ws":
+            return 18789
+        default:
+            return nil
+        }
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/GeneralSettings.swift

@@ -0,0 +1,741 @@
+import AppKit
+import Observation
+import OpenClawDiscovery
+import OpenClawIPC
+import OpenClawKit
+import SwiftUI
+
+struct GeneralSettings: View {
+    @Bindable var state: AppState
+    @AppStorage(cameraEnabledKey) private var cameraEnabled: Bool = false
+    private let healthStore = HealthStore.shared
+    private let gatewayManager = GatewayProcessManager.shared
+    @State private var gatewayDiscovery = GatewayDiscoveryModel(
+        localDisplayName: InstanceIdentity.displayName)
+    @State private var gatewayStatus: GatewayEnvironmentStatus = .checking
+    @State private var remoteStatus: RemoteStatus = .idle
+    @State private var showRemoteAdvanced = false
+    private let isPreview = ProcessInfo.processInfo.isPreview
+    private var isNixMode: Bool {
+        ProcessInfo.processInfo.isNixMode
+    }
+
+    private var remoteLabelWidth: CGFloat {
+        88
+    }
+
+    var body: some View {
+        ScrollView(.vertical) {
+            VStack(alignment: .leading, spacing: 18) {
+                VStack(alignment: .leading, spacing: 12) {
+                    SettingsToggleRow(
+                        title: "OpenClaw active",
+                        subtitle: "Pause to stop the OpenClaw gateway; no messages will be processed.",
+                        binding: self.activeBinding)
+
+                    self.connectionSection
+
+                    Divider()
+
+                    SettingsToggleRow(
+                        title: "Launch at login",
+                        subtitle: "Automatically start OpenClaw after you sign in.",
+                        binding: self.$state.launchAtLogin)
+
+                    SettingsToggleRow(
+                        title: "Show Dock icon",
+                        subtitle: "Keep OpenClaw visible in the Dock instead of menu-bar-only mode.",
+                        binding: self.$state.showDockIcon)
+
+                    SettingsToggleRow(
+                        title: "Play menu bar icon animations",
+                        subtitle: "Enable idle blinks and wiggles on the status icon.",
+                        binding: self.$state.iconAnimationsEnabled)
+
+                    SettingsToggleRow(
+                        title: "Allow Canvas",
+                        subtitle: "Allow the agent to show and control the Canvas panel.",
+                        binding: self.$state.canvasEnabled)
+
+                    SettingsToggleRow(
+                        title: "Allow Camera",
+                        subtitle: "Allow the agent to capture a photo or short video via the built-in camera.",
+                        binding: self.$cameraEnabled)
+
+                    SettingsToggleRow(
+                        title: "Enable Peekaboo Bridge",
+                        subtitle: "Allow signed tools (e.g. `peekaboo`) to drive UI automation via PeekabooBridge.",
+                        binding: self.$state.peekabooBridgeEnabled)
+
+                    SettingsToggleRow(
+                        title: "Enable debug tools",
+                        subtitle: "Show the Debug tab with development utilities.",
+                        binding: self.$state.debugPaneEnabled)
+                }
+
+                Spacer(minLength: 12)
+                HStack {
+                    Spacer()
+                    Button("Quit OpenClaw") { NSApp.terminate(nil) }
+                        .buttonStyle(.borderedProminent)
+                }
+            }
+            .frame(maxWidth: .infinity, alignment: .leading)
+            .padding(.horizontal, 22)
+            .padding(.bottom, 16)
+        }
+        .onAppear {
+            guard !self.isPreview else { return }
+            self.refreshGatewayStatus()
+        }
+        .onChange(of: self.state.canvasEnabled) { _, enabled in
+            if !enabled {
+                CanvasManager.shared.hideAll()
+            }
+        }
+    }
+
+    private var activeBinding: Binding<Bool> {
+        Binding(
+            get: { !self.state.isPaused },
+            set: { self.state.isPaused = !$0 })
+    }
+
+    private var connectionSection: some View {
+        VStack(alignment: .leading, spacing: 10) {
+            Text("OpenClaw runs")
+                .font(.title3.weight(.semibold))
+                .frame(maxWidth: .infinity, alignment: .leading)
+
+            Picker("Mode", selection: self.$state.connectionMode) {
+                Text("Not configured").tag(AppState.ConnectionMode.unconfigured)
+                Text("Local (this Mac)").tag(AppState.ConnectionMode.local)
+                Text("Remote (another host)").tag(AppState.ConnectionMode.remote)
+            }
+            .pickerStyle(.menu)
+            .labelsHidden()
+            .frame(width: 260, alignment: .leading)
+
+            if self.state.connectionMode == .unconfigured {
+                Text("Pick Local or Remote to start the Gateway.")
+                    .font(.footnote)
+                    .foregroundStyle(.secondary)
+                    .fixedSize(horizontal: false, vertical: true)
+            }
+
+            if self.state.connectionMode == .local {
+                // In Nix mode, gateway is managed declaratively - no install buttons.
+                if !self.isNixMode {
+                    self.gatewayInstallerCard
+                }
+                TailscaleIntegrationSection(
+                    connectionMode: self.state.connectionMode,
+                    isPaused: self.state.isPaused)
+                self.healthRow
+            }
+
+            if self.state.connectionMode == .remote {
+                self.remoteCard
+            }
+        }
+    }
+
+    private var remoteCard: some View {
+        VStack(alignment: .leading, spacing: 10) {
+            self.remoteTransportRow
+
+            if self.state.remoteTransport == .ssh {
+                self.remoteSshRow
+            } else {
+                self.remoteDirectRow
+            }
+
+            GatewayDiscoveryInlineList(
+                discovery: self.gatewayDiscovery,
+                currentTarget: self.state.remoteTarget,
+                currentUrl: self.state.remoteUrl,
+                transport: self.state.remoteTransport)
+            { gateway in
+                self.applyDiscoveredGateway(gateway)
+            }
+            .padding(.leading, self.remoteLabelWidth + 10)
+
+            self.remoteStatusView
+                .padding(.leading, self.remoteLabelWidth + 10)
+
+            if self.state.remoteTransport == .ssh {
+                DisclosureGroup(isExpanded: self.$showRemoteAdvanced) {
+                    VStack(alignment: .leading, spacing: 8) {
+                        LabeledContent("Identity file") {
+                            TextField("/Users/you/.ssh/id_ed25519", text: self.$state.remoteIdentity)
+                                .textFieldStyle(.roundedBorder)
+                                .frame(width: 280)
+                        }
+                        LabeledContent("Project root") {
+                            TextField("/home/you/Projects/openclaw", text: self.$state.remoteProjectRoot)
+                                .textFieldStyle(.roundedBorder)
+                                .frame(width: 280)
+                        }
+                        LabeledContent("CLI path") {
+                            TextField("/Applications/OpenClaw.app/.../openclaw", text: self.$state.remoteCliPath)
+                                .textFieldStyle(.roundedBorder)
+                                .frame(width: 280)
+                        }
+                    }
+                    .padding(.top, 4)
+                } label: {
+                    Text("Advanced")
+                        .font(.callout.weight(.semibold))
+                }
+            }
+
+            // Diagnostics
+            VStack(alignment: .leading, spacing: 4) {
+                Text("Control channel")
+                    .font(.caption.weight(.semibold))
+                if !self.isControlStatusDuplicate || ControlChannel.shared.lastPingMs != nil {
+                    let status = self.isControlStatusDuplicate ? nil : self.controlStatusLine
+                    let ping = ControlChannel.shared.lastPingMs.map { "Ping \(Int($0)) ms" }
+                    let line = [status, ping].compactMap(\.self).joined(separator: " · ")
+                    if !line.isEmpty {
+                        Text(line)
+                            .font(.caption)
+                            .foregroundStyle(.secondary)
+                    }
+                }
+                if let hb = HeartbeatStore.shared.lastEvent {
+                    let ageText = age(from: Date(timeIntervalSince1970: hb.ts / 1000))
+                    Text("Last heartbeat: \(hb.status) · \(ageText)")
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                }
+                if let authLabel = ControlChannel.shared.authSourceLabel {
+                    Text(authLabel)
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                }
+            }
+
+            if self.state.remoteTransport == .ssh {
+                Text("Tip: enable Tailscale for stable remote access.")
+                    .font(.footnote)
+                    .foregroundStyle(.secondary)
+                    .lineLimit(1)
+            } else {
+                Text("Tip: use Tailscale Serve so the gateway has a valid HTTPS cert.")
+                    .font(.footnote)
+                    .foregroundStyle(.secondary)
+                    .lineLimit(2)
+            }
+        }
+        .transition(.opacity)
+        .onAppear { self.gatewayDiscovery.start() }
+        .onDisappear { self.gatewayDiscovery.stop() }
+    }
+
+    private var remoteTransportRow: some View {
+        HStack(alignment: .center, spacing: 10) {
+            Text("Transport")
+                .font(.callout.weight(.semibold))
+                .frame(width: self.remoteLabelWidth, alignment: .leading)
+            Picker("Transport", selection: self.$state.remoteTransport) {
+                Text("SSH tunnel").tag(AppState.RemoteTransport.ssh)
+                Text("Direct (ws/wss)").tag(AppState.RemoteTransport.direct)
+            }
+            .pickerStyle(.segmented)
+            .frame(maxWidth: 320)
+        }
+    }
+
+    private var remoteSshRow: some View {
+        let trimmedTarget = self.state.remoteTarget.trimmingCharacters(in: .whitespacesAndNewlines)
+        let validationMessage = CommandResolver.sshTargetValidationMessage(trimmedTarget)
+        let canTest = !trimmedTarget.isEmpty && validationMessage == nil
+
+        return VStack(alignment: .leading, spacing: 4) {
+            HStack(alignment: .center, spacing: 10) {
+                Text("SSH target")
+                    .font(.callout.weight(.semibold))
+                    .frame(width: self.remoteLabelWidth, alignment: .leading)
+                TextField("user@host[:22]", text: self.$state.remoteTarget)
+                    .textFieldStyle(.roundedBorder)
+                    .frame(maxWidth: .infinity)
+                Button {
+                    Task { await self.testRemote() }
+                } label: {
+                    if self.remoteStatus == .checking {
+                        ProgressView().controlSize(.small)
+                    } else {
+                        Text("Test remote")
+                    }
+                }
+                .buttonStyle(.borderedProminent)
+                .disabled(self.remoteStatus == .checking || !canTest)
+            }
+            if let validationMessage {
+                Text(validationMessage)
+                    .font(.caption)
+                    .foregroundStyle(.red)
+                    .padding(.leading, self.remoteLabelWidth + 10)
+            }
+        }
+    }
+
+    private var remoteDirectRow: some View {
+        VStack(alignment: .leading, spacing: 6) {
+            HStack(alignment: .center, spacing: 10) {
+                Text("Gateway")
+                    .font(.callout.weight(.semibold))
+                    .frame(width: self.remoteLabelWidth, alignment: .leading)
+                TextField("wss://gateway.example.ts.net", text: self.$state.remoteUrl)
+                    .textFieldStyle(.roundedBorder)
+                    .frame(maxWidth: .infinity)
+                Button {
+                    Task { await self.testRemote() }
+                } label: {
+                    if self.remoteStatus == .checking {
+                        ProgressView().controlSize(.small)
+                    } else {
+                        Text("Test remote")
+                    }
+                }
+                .buttonStyle(.borderedProminent)
+                .disabled(self.remoteStatus == .checking || self.state.remoteUrl
+                    .trimmingCharacters(in: .whitespacesAndNewlines).isEmpty)
+            }
+            Text(
+                "Direct mode requires wss:// for remote hosts. ws:// is only allowed for localhost/127.0.0.1.")
+                .font(.caption)
+                .foregroundStyle(.secondary)
+                .padding(.leading, self.remoteLabelWidth + 10)
+        }
+    }
+
+    private var controlStatusLine: String {
+        switch ControlChannel.shared.state {
+        case .connected: "Connected"
+        case .connecting: "Connecting…"
+        case .disconnected: "Disconnected"
+        case let .degraded(msg): msg
+        }
+    }
+
+    @ViewBuilder
+    private var remoteStatusView: some View {
+        switch self.remoteStatus {
+        case .idle:
+            EmptyView()
+        case .checking:
+            Text("Testing…")
+                .font(.caption)
+                .foregroundStyle(.secondary)
+        case .ok:
+            Label("Ready", systemImage: "checkmark.circle.fill")
+                .font(.caption)
+                .foregroundStyle(.green)
+        case let .failed(message):
+            Text(message)
+                .font(.caption)
+                .foregroundStyle(.secondary)
+                .lineLimit(2)
+        }
+    }
+
+    private var isControlStatusDuplicate: Bool {
+        guard case let .failed(message) = self.remoteStatus else { return false }
+        return message == self.controlStatusLine
+    }
+
+    private var gatewayInstallerCard: some View {
+        VStack(alignment: .leading, spacing: 8) {
+            HStack(spacing: 10) {
+                Circle()
+                    .fill(self.gatewayStatusColor)
+                    .frame(width: 10, height: 10)
+                Text(self.gatewayStatus.message)
+                    .font(.callout)
+                    .frame(maxWidth: .infinity, alignment: .leading)
+            }
+
+            if let gatewayVersion = self.gatewayStatus.gatewayVersion,
+               let required = self.gatewayStatus.requiredGateway,
+               gatewayVersion != required
+            {
+                Text("Installed: \(gatewayVersion) · Required: \(required)")
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+            } else if let gatewayVersion = self.gatewayStatus.gatewayVersion {
+                Text("Gateway \(gatewayVersion) detected")
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+            }
+
+            if let node = self.gatewayStatus.nodeVersion {
+                Text("Node \(node)")
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+            }
+
+            if case let .attachedExisting(details) = self.gatewayManager.status {
+                Text(details ?? "Using existing gateway instance")
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+            }
+
+            if let failure = self.gatewayManager.lastFailureReason {
+                Text("Last failure: \(failure)")
+                    .font(.caption)
+                    .foregroundStyle(.red)
+            }
+
+            Button("Recheck") { self.refreshGatewayStatus() }
+                .buttonStyle(.bordered)
+
+            Text("Gateway auto-starts in local mode via launchd (\(gatewayLaunchdLabel)).")
+                .font(.caption)
+                .foregroundStyle(.secondary)
+                .lineLimit(2)
+        }
+        .padding(12)
+        .background(Color.gray.opacity(0.08))
+        .cornerRadius(10)
+    }
+
+    private func refreshGatewayStatus() {
+        Task {
+            let status = await Task.detached(priority: .utility) {
+                GatewayEnvironment.check()
+            }.value
+            self.gatewayStatus = status
+        }
+    }
+
+    private var gatewayStatusColor: Color {
+        switch self.gatewayStatus.kind {
+        case .ok: .green
+        case .checking: .secondary
+        case .missingNode, .missingGateway, .incompatible, .error: .orange
+        }
+    }
+
+    private var healthCard: some View {
+        let snapshot = self.healthStore.snapshot
+        return VStack(alignment: .leading, spacing: 6) {
+            HStack(spacing: 8) {
+                Circle()
+                    .fill(self.healthStore.state.tint)
+                    .frame(width: 10, height: 10)
+                Text(self.healthStore.summaryLine)
+                    .font(.callout.weight(.semibold))
+            }
+
+            if let snap = snapshot {
+                let linkId = snap.channelOrder?.first(where: {
+                    if let summary = snap.channels[$0] { return summary.linked != nil }
+                    return false
+                }) ?? snap.channels.keys.first(where: {
+                    if let summary = snap.channels[$0] { return summary.linked != nil }
+                    return false
+                })
+                let linkLabel =
+                    linkId.flatMap { snap.channelLabels?[$0] } ??
+                    linkId?.capitalized ??
+                    "Link channel"
+                let linkAge = linkId.flatMap { snap.channels[$0]?.authAgeMs }
+                Text("\(linkLabel) auth age: \(healthAgeString(linkAge))")
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+                Text("Session store: \(snap.sessions.path) (\(snap.sessions.count) entries)")
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+                if let recent = snap.sessions.recent.first {
+                    let lastActivity = recent.updatedAt != nil
+                        ? relativeAge(from: Date(timeIntervalSince1970: (recent.updatedAt ?? 0) / 1000))
+                        : "unknown"
+                    Text("Last activity: \(recent.key) \(lastActivity)")
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                }
+                Text("Last check: \(relativeAge(from: self.healthStore.lastSuccess))")
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+            } else if let error = self.healthStore.lastError {
+                Text(error)
+                    .font(.caption)
+                    .foregroundStyle(.red)
+            } else {
+                Text("Health check pending…")
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+            }
+
+            HStack(spacing: 12) {
+                Button {
+                    Task { await self.healthStore.refresh(onDemand: true) }
+                } label: {
+                    if self.healthStore.isRefreshing {
+                        ProgressView().controlSize(.small)
+                    } else {
+                        Label("Run Health Check", systemImage: "arrow.clockwise")
+                    }
+                }
+                .disabled(self.healthStore.isRefreshing)
+
+                Divider().frame(height: 18)
+
+                Button {
+                    self.revealLogs()
+                } label: {
+                    Label("Reveal Logs", systemImage: "doc.text.magnifyingglass")
+                }
+            }
+        }
+        .padding(12)
+        .background(Color.gray.opacity(0.08))
+        .cornerRadius(10)
+    }
+}
+
+private enum RemoteStatus: Equatable {
+    case idle
+    case checking
+    case ok
+    case failed(String)
+}
+
+extension GeneralSettings {
+    private var healthRow: some View {
+        VStack(alignment: .leading, spacing: 6) {
+            HStack(spacing: 10) {
+                Circle()
+                    .fill(self.healthStore.state.tint)
+                    .frame(width: 10, height: 10)
+                Text(self.healthStore.summaryLine)
+                    .font(.callout)
+                    .frame(maxWidth: .infinity, alignment: .leading)
+            }
+
+            if let detail = self.healthStore.detailLine {
+                Text(detail)
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+                    .fixedSize(horizontal: false, vertical: true)
+            }
+
+            HStack(spacing: 10) {
+                Button("Retry now") {
+                    Task { await HealthStore.shared.refresh(onDemand: true) }
+                }
+                .disabled(self.healthStore.isRefreshing)
+
+                Button("Open logs") { self.revealLogs() }
+                    .buttonStyle(.link)
+                    .foregroundStyle(.secondary)
+            }
+            .font(.caption)
+        }
+    }
+
+    @MainActor
+    func testRemote() async {
+        self.remoteStatus = .checking
+        let settings = CommandResolver.connectionSettings()
+        if self.state.remoteTransport == .direct {
+            let trimmedUrl = self.state.remoteUrl.trimmingCharacters(in: .whitespacesAndNewlines)
+            guard !trimmedUrl.isEmpty else {
+                self.remoteStatus = .failed("Set a gateway URL first")
+                return
+            }
+            guard Self.isValidWsUrl(trimmedUrl) else {
+                self.remoteStatus = .failed(
+                    "Gateway URL must use wss:// for remote hosts (ws:// only for localhost)")
+                return
+            }
+        } else {
+            guard !settings.target.isEmpty else {
+                self.remoteStatus = .failed("Set an SSH target first")
+                return
+            }
+
+            // Step 1: basic SSH reachability check
+            guard let sshCommand = Self.sshCheckCommand(
+                target: settings.target,
+                identity: settings.identity)
+            else {
+                self.remoteStatus = .failed("SSH target is invalid")
+                return
+            }
+            let sshResult = await ShellExecutor.run(
+                command: sshCommand,
+                cwd: nil,
+                env: nil,
+                timeout: 8)
+
+            guard sshResult.ok else {
+                self.remoteStatus = .failed(self.formatSSHFailure(sshResult, target: settings.target))
+                return
+            }
+        }
+
+        // Step 2: control channel health check
+        let originalMode = AppStateStore.shared.connectionMode
+        do {
+            try await ControlChannel.shared.configure(mode: .remote(
+                target: settings.target,
+                identity: settings.identity))
+            let data = try await ControlChannel.shared.health(timeout: 10)
+            if decodeHealthSnapshot(from: data) != nil {
+                self.remoteStatus = .ok
+            } else {
+                self.remoteStatus = .failed("Control channel returned invalid health JSON")
+            }
+        } catch {
+            self.remoteStatus = .failed(error.localizedDescription)
+        }
+
+        // Restore original mode if we temporarily switched
+        switch originalMode {
+        case .remote:
+            break
+        case .local:
+            try? await ControlChannel.shared.configure(mode: .local)
+        case .unconfigured:
+            await ControlChannel.shared.disconnect()
+        }
+    }
+
+    private static func isValidWsUrl(_ raw: String) -> Bool {
+        GatewayRemoteConfig.normalizeGatewayUrl(raw) != nil
+    }
+
+    private static func sshCheckCommand(target: String, identity: String) -> [String]? {
+        guard let parsed = CommandResolver.parseSSHTarget(target) else { return nil }
+        let options = [
+            "-o", "BatchMode=yes",
+            "-o", "ConnectTimeout=5",
+            "-o", "StrictHostKeyChecking=accept-new",
+            "-o", "UpdateHostKeys=yes",
+        ]
+        let args = CommandResolver.sshArguments(
+            target: parsed,
+            identity: identity,
+            options: options,
+            remoteCommand: ["echo", "ok"])
+        return ["/usr/bin/ssh"] + args
+    }
+
+    private func formatSSHFailure(_ response: Response, target: String) -> String {
+        let payload = response.payload.flatMap { String(data: $0, encoding: .utf8) }
+        let trimmed = payload?
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+            .split(whereSeparator: \.isNewline)
+            .joined(separator: " ")
+        if let trimmed,
+           trimmed.localizedCaseInsensitiveContains("host key verification failed")
+        {
+            let host = CommandResolver.parseSSHTarget(target)?.host ?? target
+            return "SSH check failed: Host key verification failed. Remove the old key with " +
+                "`ssh-keygen -R \(host)` and try again."
+        }
+        if let trimmed, !trimmed.isEmpty {
+            if let message = response.message, message.hasPrefix("exit ") {
+                return "SSH check failed: \(trimmed) (\(message))"
+            }
+            return "SSH check failed: \(trimmed)"
+        }
+        if let message = response.message {
+            return "SSH check failed (\(message))"
+        }
+        return "SSH check failed"
+    }
+
+    private func revealLogs() {
+        let target = LogLocator.bestLogFile()
+
+        if let target {
+            NSWorkspace.shared.selectFile(
+                target.path,
+                inFileViewerRootedAtPath: target.deletingLastPathComponent().path)
+            return
+        }
+
+        let alert = NSAlert()
+        alert.messageText = "Log file not found"
+        alert.informativeText = """
+        Looked for openclaw logs in /tmp/openclaw/.
+        Run a health check or send a message to generate activity, then try again.
+        """
+        alert.alertStyle = .informational
+        alert.addButton(withTitle: "OK")
+        alert.runModal()
+    }
+
+    private func applyDiscoveredGateway(_ gateway: GatewayDiscoveryModel.DiscoveredGateway) {
+        MacNodeModeCoordinator.shared.setPreferredGatewayStableID(gateway.stableID)
+
+        if self.state.remoteTransport == .direct {
+            self.state.remoteUrl = GatewayDiscoveryHelpers.directUrl(for: gateway) ?? ""
+        } else {
+            self.state.remoteTarget = GatewayDiscoveryHelpers.sshTarget(for: gateway) ?? ""
+        }
+        if let endpoint = GatewayDiscoveryHelpers.serviceEndpoint(for: gateway) {
+            OpenClawConfigFile.setRemoteGatewayUrl(
+                host: endpoint.host,
+                port: endpoint.port)
+        } else {
+            OpenClawConfigFile.clearRemoteGatewayUrl()
+        }
+    }
+}
+
+private func healthAgeString(_ ms: Double?) -> String {
+    guard let ms else { return "unknown" }
+    return msToAge(ms)
+}
+
+#if DEBUG
+struct GeneralSettings_Previews: PreviewProvider {
+    static var previews: some View {
+        GeneralSettings(state: .preview)
+            .frame(width: SettingsTab.windowWidth, height: SettingsTab.windowHeight)
+            .environment(TailscaleService.shared)
+    }
+}
+
+@MainActor
+extension GeneralSettings {
+    static func exerciseForTesting() {
+        let state = AppState(preview: true)
+        state.connectionMode = .remote
+        state.remoteTransport = .ssh
+        state.remoteTarget = "user@host:2222"
+        state.remoteUrl = "wss://gateway.example.ts.net"
+        state.remoteIdentity = "/tmp/id_ed25519"
+        state.remoteProjectRoot = "/tmp/openclaw"
+        state.remoteCliPath = "/tmp/openclaw"
+
+        let view = GeneralSettings(state: state)
+        view.gatewayStatus = GatewayEnvironmentStatus(
+            kind: .ok,
+            nodeVersion: "1.0.0",
+            gatewayVersion: "1.0.0",
+            requiredGateway: nil,
+            message: "Gateway ready")
+        view.remoteStatus = .failed("SSH failed")
+        view.showRemoteAdvanced = true
+        _ = view.body
+
+        state.connectionMode = .unconfigured
+        _ = view.body
+
+        state.connectionMode = .local
+        view.gatewayStatus = GatewayEnvironmentStatus(
+            kind: .error("Gateway offline"),
+            nodeVersion: nil,
+            gatewayVersion: nil,
+            requiredGateway: nil,
+            message: "Gateway offline")
+        _ = view.body
+    }
+}
+#endif

openclaw/apps/macos/Sources/OpenClaw/HealthStore.swift

@@ -0,0 +1,301 @@
+import Foundation
+import Network
+import Observation
+import SwiftUI
+
+struct HealthSnapshot: Codable, Sendable {
+    struct ChannelSummary: Codable, Sendable {
+        struct Probe: Codable, Sendable {
+            struct Bot: Codable, Sendable {
+                let username: String?
+            }
+
+            struct Webhook: Codable, Sendable {
+                let url: String?
+            }
+
+            let ok: Bool?
+            let status: Int?
+            let error: String?
+            let elapsedMs: Double?
+            let bot: Bot?
+            let webhook: Webhook?
+        }
+
+        let configured: Bool?
+        let linked: Bool?
+        let authAgeMs: Double?
+        let probe: Probe?
+        let lastProbeAt: Double?
+    }
+
+    struct SessionInfo: Codable, Sendable {
+        let key: String
+        let updatedAt: Double?
+        let age: Double?
+    }
+
+    struct Sessions: Codable, Sendable {
+        let path: String
+        let count: Int
+        let recent: [SessionInfo]
+    }
+
+    let ok: Bool?
+    let ts: Double
+    let durationMs: Double
+    let channels: [String: ChannelSummary]
+    let channelOrder: [String]?
+    let channelLabels: [String: String]?
+    let heartbeatSeconds: Int?
+    let sessions: Sessions
+}
+
+enum HealthState: Equatable {
+    case unknown
+    case ok
+    case linkingNeeded
+    case degraded(String)
+
+    var tint: Color {
+        switch self {
+        case .ok: .green
+        case .linkingNeeded: .red
+        case .degraded: .orange
+        case .unknown: .secondary
+        }
+    }
+}
+
+@MainActor
+@Observable
+final class HealthStore {
+    static let shared = HealthStore()
+
+    private static let logger = Logger(subsystem: "ai.openclaw", category: "health")
+
+    private(set) var snapshot: HealthSnapshot?
+    private(set) var lastSuccess: Date?
+    private(set) var lastError: String?
+    private(set) var isRefreshing = false
+
+    private var loopTask: Task<Void, Never>?
+    private let refreshInterval: TimeInterval = 60
+
+    private init() {
+        // Avoid background health polling in SwiftUI previews and tests.
+        if !ProcessInfo.processInfo.isPreview, !ProcessInfo.processInfo.isRunningTests {
+            self.start()
+        }
+    }
+
+    /// Test-only escape hatch: the HealthStore is a process-wide singleton but
+    /// state derivation is pure from `snapshot` + `lastError`.
+    func __setSnapshotForTest(_ snapshot: HealthSnapshot?, lastError: String? = nil) {
+        self.snapshot = snapshot
+        self.lastError = lastError
+    }
+
+    func start() {
+        guard self.loopTask == nil else { return }
+        self.loopTask = Task { [weak self] in
+            guard let self else { return }
+            while !Task.isCancelled {
+                await self.refresh()
+                try? await Task.sleep(nanoseconds: UInt64(self.refreshInterval * 1_000_000_000))
+            }
+        }
+    }
+
+    func stop() {
+        self.loopTask?.cancel()
+        self.loopTask = nil
+    }
+
+    func refresh(onDemand: Bool = false) async {
+        guard !self.isRefreshing else { return }
+        self.isRefreshing = true
+        defer { self.isRefreshing = false }
+        let previousError = self.lastError
+
+        do {
+            let data = try await ControlChannel.shared.health(timeout: 15)
+            if let decoded = decodeHealthSnapshot(from: data) {
+                self.snapshot = decoded
+                self.lastSuccess = Date()
+                self.lastError = nil
+                if previousError != nil {
+                    Self.logger.info("health refresh recovered")
+                }
+            } else {
+                self.lastError = "health output not JSON"
+                if onDemand { self.snapshot = nil }
+                if previousError != self.lastError {
+                    Self.logger.warning("health refresh failed: output not JSON")
+                }
+            }
+        } catch {
+            let desc = error.localizedDescription
+            self.lastError = desc
+            if onDemand { self.snapshot = nil }
+            if previousError != desc {
+                Self.logger.error("health refresh failed \(desc, privacy: .public)")
+            }
+        }
+    }
+
+    private static func isChannelHealthy(_ summary: HealthSnapshot.ChannelSummary) -> Bool {
+        guard summary.configured == true else { return false }
+        // If probe is missing, treat it as "configured but unknown health" (not a hard fail).
+        return summary.probe?.ok ?? true
+    }
+
+    private static func describeProbeFailure(_ probe: HealthSnapshot.ChannelSummary.Probe) -> String {
+        let elapsed = probe.elapsedMs.map { "\(Int($0))ms" }
+        if let error = probe.error, error.lowercased().contains("timeout") || probe.status == nil {
+            if let elapsed { return "Health check timed out (\(elapsed))" }
+            return "Health check timed out"
+        }
+        let code = probe.status.map { "status \($0)" } ?? "status unknown"
+        let reason = probe.error?.isEmpty == false ? probe.error! : "health probe failed"
+        if let elapsed { return "\(reason) (\(code), \(elapsed))" }
+        return "\(reason) (\(code))"
+    }
+
+    private func resolveLinkChannel(
+        _ snap: HealthSnapshot) -> (id: String, summary: HealthSnapshot.ChannelSummary)?
+    {
+        let order = snap.channelOrder ?? Array(snap.channels.keys)
+        for id in order {
+            if let summary = snap.channels[id], summary.linked == true {
+                return (id: id, summary: summary)
+            }
+        }
+        for id in order {
+            if let summary = snap.channels[id], summary.linked != nil {
+                return (id: id, summary: summary)
+            }
+        }
+        return nil
+    }
+
+    private func resolveFallbackChannel(
+        _ snap: HealthSnapshot,
+        excluding id: String?) -> (id: String, summary: HealthSnapshot.ChannelSummary)?
+    {
+        let order = snap.channelOrder ?? Array(snap.channels.keys)
+        for channelId in order {
+            if channelId == id { continue }
+            guard let summary = snap.channels[channelId] else { continue }
+            if Self.isChannelHealthy(summary) {
+                return (id: channelId, summary: summary)
+            }
+        }
+        return nil
+    }
+
+    var state: HealthState {
+        if let error = self.lastError, !error.isEmpty {
+            return .degraded(error)
+        }
+        guard let snap = self.snapshot else { return .unknown }
+        guard let link = self.resolveLinkChannel(snap) else { return .unknown }
+        if link.summary.linked != true {
+            // Linking is optional if any other channel is healthy; don't paint the whole app red.
+            let fallback = self.resolveFallbackChannel(snap, excluding: link.id)
+            return fallback != nil ? .degraded("Not linked") : .linkingNeeded
+        }
+        // A channel can be "linked" but still unhealthy (failed probe / cannot connect).
+        if let probe = link.summary.probe, probe.ok == false {
+            return .degraded(Self.describeProbeFailure(probe))
+        }
+        return .ok
+    }
+
+    var summaryLine: String {
+        if self.isRefreshing { return "Health check running…" }
+        if let error = self.lastError { return "Health check failed: \(error)" }
+        guard let snap = self.snapshot else { return "Health check pending" }
+        guard let link = self.resolveLinkChannel(snap) else { return "Health check pending" }
+        if link.summary.linked != true {
+            if let fallback = self.resolveFallbackChannel(snap, excluding: link.id) {
+                let fallbackLabel = snap.channelLabels?[fallback.id] ?? fallback.id.capitalized
+                let fallbackState = (fallback.summary.probe?.ok ?? true) ? "ok" : "degraded"
+                return "\(fallbackLabel) \(fallbackState) · Not linked — run openclaw login"
+            }
+            return "Not linked — run openclaw login"
+        }
+        let auth = link.summary.authAgeMs.map { msToAge($0) } ?? "unknown"
+        if let probe = link.summary.probe, probe.ok == false {
+            let status = probe.status.map(String.init) ?? "?"
+            let suffix = probe.status == nil ? "probe degraded" : "probe degraded · status \(status)"
+            return "linked · auth \(auth) · \(suffix)"
+        }
+        return "linked · auth \(auth)"
+    }
+
+    /// Short, human-friendly detail for the last failure, used in the UI.
+    var detailLine: String? {
+        if let error = self.lastError, !error.isEmpty {
+            let lower = error.lowercased()
+            if lower.contains("connection refused") {
+                let port = GatewayEnvironment.gatewayPort()
+                let host = GatewayConnectivityCoordinator.shared.localEndpointHostLabel ?? "127.0.0.1:\(port)"
+                return "The gateway control port (\(host)) isn’t listening — restart OpenClaw to bring it back."
+            }
+            if lower.contains("timeout") {
+                return "Timed out waiting for the control server; the gateway may be crashed or still starting."
+            }
+            return error
+        }
+        return nil
+    }
+
+    func describeFailure(from snap: HealthSnapshot, fallback: String?) -> String {
+        if let link = self.resolveLinkChannel(snap), link.summary.linked != true {
+            return "Not linked — run openclaw login"
+        }
+        if let link = self.resolveLinkChannel(snap), let probe = link.summary.probe, probe.ok == false {
+            return Self.describeProbeFailure(probe)
+        }
+        if let fallback, !fallback.isEmpty {
+            return fallback
+        }
+        return "health probe failed"
+    }
+
+    var degradedSummary: String? {
+        guard case let .degraded(reason) = self.state else { return nil }
+        if reason == "[object Object]" || reason.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty,
+           let snap = self.snapshot
+        {
+            return self.describeFailure(from: snap, fallback: reason)
+        }
+        return reason
+    }
+}
+
+func msToAge(_ ms: Double) -> String {
+    let minutes = Int(round(ms / 60000))
+    if minutes < 1 { return "just now" }
+    if minutes < 60 { return "\(minutes)m" }
+    let hours = Int(round(Double(minutes) / 60))
+    if hours < 48 { return "\(hours)h" }
+    let days = Int(round(Double(hours) / 24))
+    return "\(days)d"
+}
+
+/// Decode a health snapshot, tolerating stray log lines before/after the JSON blob.
+func decodeHealthSnapshot(from data: Data) -> HealthSnapshot? {
+    let decoder = JSONDecoder()
+    if let snap = try? decoder.decode(HealthSnapshot.self, from: data) {
+        return snap
+    }
+    guard let text = String(data: data, encoding: .utf8) else { return nil }
+    guard let firstBrace = text.firstIndex(of: "{"), let lastBrace = text.lastIndex(of: "}") else {
+        return nil
+    }
+    let slice = text[firstBrace...lastBrace]
+    let cleaned = Data(slice.utf8)
+    return try? decoder.decode(HealthSnapshot.self, from: cleaned)
+}

openclaw/apps/macos/Sources/OpenClaw/HeartbeatStore.swift

@@ -0,0 +1,39 @@
+import Foundation
+import Observation
+import SwiftUI
+
+@MainActor
+@Observable
+final class HeartbeatStore {
+    static let shared = HeartbeatStore()
+
+    private(set) var lastEvent: ControlHeartbeatEvent?
+
+    private var observer: NSObjectProtocol?
+
+    private init() {
+        self.observer = NotificationCenter.default.addObserver(
+            forName: .controlHeartbeat,
+            object: nil,
+            queue: .main)
+        { [weak self] note in
+            guard let data = note.object as? Data else { return }
+            if let decoded = try? JSONDecoder().decode(ControlHeartbeatEvent.self, from: data) {
+                Task { @MainActor in self?.lastEvent = decoded }
+            }
+        }
+
+        Task {
+            if self.lastEvent == nil {
+                if let evt = try? await ControlChannel.shared.lastHeartbeat() {
+                    self.lastEvent = evt
+                }
+            }
+        }
+    }
+
+    @MainActor
+    deinit {
+        if let observer { NotificationCenter.default.removeObserver(observer) }
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/HostEnvSanitizer.swift

@@ -0,0 +1,66 @@
+import Foundation
+
+enum HostEnvSanitizer {
+    /// Generated from src/infra/host-env-security-policy.json via scripts/generate-host-env-security-policy-swift.mjs.
+    /// Parity is validated by src/infra/host-env-security.policy-parity.test.ts.
+    private static let blockedKeys = HostEnvSecurityPolicy.blockedKeys
+    private static let blockedPrefixes = HostEnvSecurityPolicy.blockedPrefixes
+    private static let blockedOverrideKeys = HostEnvSecurityPolicy.blockedOverrideKeys
+    private static let shellWrapperAllowedOverrideKeys: Set<String> = [
+        "TERM",
+        "LANG",
+        "LC_ALL",
+        "LC_CTYPE",
+        "LC_MESSAGES",
+        "COLORTERM",
+        "NO_COLOR",
+        "FORCE_COLOR",
+    ]
+
+    private static func isBlocked(_ upperKey: String) -> Bool {
+        if self.blockedKeys.contains(upperKey) { return true }
+        return self.blockedPrefixes.contains(where: { upperKey.hasPrefix($0) })
+    }
+
+    private static func filterOverridesForShellWrapper(_ overrides: [String: String]?) -> [String: String]? {
+        guard let overrides else { return nil }
+        var filtered: [String: String] = [:]
+        for (rawKey, value) in overrides {
+            let key = rawKey.trimmingCharacters(in: .whitespacesAndNewlines)
+            guard !key.isEmpty else { continue }
+            if self.shellWrapperAllowedOverrideKeys.contains(key.uppercased()) {
+                filtered[key] = value
+            }
+        }
+        return filtered.isEmpty ? nil : filtered
+    }
+
+    static func sanitize(overrides: [String: String]?, shellWrapper: Bool = false) -> [String: String] {
+        var merged: [String: String] = [:]
+        for (rawKey, value) in ProcessInfo.processInfo.environment {
+            let key = rawKey.trimmingCharacters(in: .whitespacesAndNewlines)
+            guard !key.isEmpty else { continue }
+            let upper = key.uppercased()
+            if self.isBlocked(upper) { continue }
+            merged[key] = value
+        }
+
+        let effectiveOverrides = shellWrapper
+            ? self.filterOverridesForShellWrapper(overrides)
+            : overrides
+
+        guard let effectiveOverrides else { return merged }
+        for (rawKey, value) in effectiveOverrides {
+            let key = rawKey.trimmingCharacters(in: .whitespacesAndNewlines)
+            guard !key.isEmpty else { continue }
+            let upper = key.uppercased()
+            // PATH is part of the security boundary (command resolution + safe-bin checks). Never
+            // allow request-scoped PATH overrides from agents/gateways.
+            if upper == "PATH" { continue }
+            if self.blockedOverrideKeys.contains(upper) { continue }
+            if self.isBlocked(upper) { continue }
+            merged[key] = value
+        }
+        return merged
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/HostEnvSecurityPolicy.generated.swift

@@ -0,0 +1,38 @@
+// Generated file. Do not edit directly.
+// Source: src/infra/host-env-security-policy.json
+// Regenerate: node scripts/generate-host-env-security-policy-swift.mjs --write
+
+import Foundation
+
+enum HostEnvSecurityPolicy {
+    static let blockedKeys: Set<String> = [
+        "NODE_OPTIONS",
+        "NODE_PATH",
+        "PYTHONHOME",
+        "PYTHONPATH",
+        "PERL5LIB",
+        "PERL5OPT",
+        "RUBYLIB",
+        "RUBYOPT",
+        "BASH_ENV",
+        "ENV",
+        "GIT_EXTERNAL_DIFF",
+        "SHELL",
+        "SHELLOPTS",
+        "PS4",
+        "GCONV_PATH",
+        "IFS",
+        "SSLKEYLOGFILE"
+    ]
+
+    static let blockedOverrideKeys: Set<String> = [
+        "HOME",
+        "ZDOTDIR"
+    ]
+
+    static let blockedPrefixes: [String] = [
+        "DYLD_",
+        "LD_",
+        "BASH_FUNC_"
+    ]
+}

openclaw/apps/macos/Sources/OpenClaw/HoverHUD.swift

@@ -0,0 +1,311 @@
+import AppKit
+import Observation
+import QuartzCore
+import SwiftUI
+
+/// Hover-only HUD anchored to the menu bar item. Click expands into full Web Chat.
+@MainActor
+@Observable
+final class HoverHUDController {
+    static let shared = HoverHUDController()
+
+    struct Model {
+        var isVisible: Bool = false
+        var isSuppressed: Bool = false
+        var hoveringStatusItem: Bool = false
+        var hoveringPanel: Bool = false
+    }
+
+    private(set) var model = Model()
+
+    private var window: NSPanel?
+    private var hostingView: NSHostingView<HoverHUDView>?
+    private var dismissMonitor: Any?
+    private var dismissTask: Task<Void, Never>?
+    private var showTask: Task<Void, Never>?
+    private var anchorProvider: (() -> NSRect?)?
+
+    private let width: CGFloat = 360
+    private let height: CGFloat = 74
+    private let padding: CGFloat = 8
+    private let hoverShowDelay: TimeInterval = 0.18
+
+    func setSuppressed(_ suppressed: Bool) {
+        self.model.isSuppressed = suppressed
+        if suppressed {
+            self.showTask?.cancel()
+            self.showTask = nil
+            self.dismiss(reason: "suppressed")
+        }
+    }
+
+    func statusItemHoverChanged(inside: Bool, anchorProvider: @escaping () -> NSRect?) {
+        self.model.hoveringStatusItem = inside
+        self.anchorProvider = anchorProvider
+
+        guard !self.model.isSuppressed else { return }
+
+        if inside {
+            self.dismissTask?.cancel()
+            self.dismissTask = nil
+            self.showTask?.cancel()
+            self.showTask = Task { [weak self] in
+                guard let self else { return }
+                try? await Task.sleep(nanoseconds: UInt64(self.hoverShowDelay * 1_000_000_000))
+                await MainActor.run { [weak self] in
+                    guard let self else { return }
+                    guard !Task.isCancelled else { return }
+                    guard self.model.hoveringStatusItem else { return }
+                    guard !self.model.isSuppressed else { return }
+                    self.present()
+                }
+            }
+        } else {
+            self.showTask?.cancel()
+            self.showTask = nil
+            self.scheduleDismiss()
+        }
+    }
+
+    func panelHoverChanged(inside: Bool) {
+        self.model.hoveringPanel = inside
+        if inside {
+            self.dismissTask?.cancel()
+            self.dismissTask = nil
+        } else if !self.model.hoveringStatusItem {
+            self.scheduleDismiss()
+        }
+    }
+
+    func openChat() {
+        guard let anchorProvider = self.anchorProvider else { return }
+        self.dismiss(reason: "openChat")
+        Task { @MainActor in
+            let sessionKey = await WebChatManager.shared.preferredSessionKey()
+            WebChatManager.shared.togglePanel(sessionKey: sessionKey, anchorProvider: anchorProvider)
+        }
+    }
+
+    func dismiss(reason: String = "explicit") {
+        self.dismissTask?.cancel()
+        self.dismissTask = nil
+        self.removeDismissMonitor()
+        guard let window else {
+            self.model.isVisible = false
+            return
+        }
+
+        if !self.model.isVisible {
+            window.orderOut(nil)
+            return
+        }
+
+        let target = window.frame.offsetBy(dx: 0, dy: 6)
+        NSAnimationContext.runAnimationGroup { context in
+            context.duration = 0.14
+            context.timingFunction = CAMediaTimingFunction(name: .easeOut)
+            window.animator().setFrame(target, display: true)
+            window.animator().alphaValue = 0
+        } completionHandler: {
+            Task { @MainActor in
+                window.orderOut(nil)
+                self.model.isVisible = false
+            }
+        }
+    }
+
+    // MARK: - Private
+
+    private func scheduleDismiss() {
+        self.dismissTask?.cancel()
+        self.dismissTask = Task { [weak self] in
+            try? await Task.sleep(nanoseconds: 250_000_000)
+            await MainActor.run {
+                guard let self else { return }
+                if self.model.hoveringStatusItem || self.model.hoveringPanel { return }
+                self.dismiss(reason: "hoverExit")
+            }
+        }
+    }
+
+    private func present() {
+        guard !self.model.isSuppressed else { return }
+        self.ensureWindow()
+        self.hostingView?.rootView = HoverHUDView(controller: self)
+        let target = self.targetFrame()
+
+        guard let window else { return }
+        self.installDismissMonitor()
+
+        if !self.model.isVisible {
+            self.model.isVisible = true
+            let start = target.offsetBy(dx: 0, dy: 8)
+            window.setFrame(start, display: true)
+            window.alphaValue = 0
+            window.orderFrontRegardless()
+            NSAnimationContext.runAnimationGroup { context in
+                context.duration = 0.18
+                context.timingFunction = CAMediaTimingFunction(name: .easeOut)
+                window.animator().setFrame(target, display: true)
+                window.animator().alphaValue = 1
+            }
+        } else {
+            window.orderFrontRegardless()
+            self.updateWindowFrame(animate: true)
+        }
+    }
+
+    private func ensureWindow() {
+        if self.window != nil { return }
+        let panel = NSPanel(
+            contentRect: NSRect(x: 0, y: 0, width: self.width, height: self.height),
+            styleMask: [.nonactivatingPanel, .borderless],
+            backing: .buffered,
+            defer: false)
+        panel.isOpaque = false
+        panel.backgroundColor = .clear
+        panel.hasShadow = true
+        panel.level = .statusBar
+        panel.collectionBehavior = [.canJoinAllSpaces, .fullScreenAuxiliary, .transient]
+        panel.hidesOnDeactivate = false
+        panel.isMovable = false
+        panel.isFloatingPanel = true
+        panel.becomesKeyOnlyIfNeeded = true
+        panel.titleVisibility = .hidden
+        panel.titlebarAppearsTransparent = true
+
+        let host = NSHostingView(rootView: HoverHUDView(controller: self))
+        host.translatesAutoresizingMaskIntoConstraints = false
+        panel.contentView = host
+        self.hostingView = host
+        self.window = panel
+    }
+
+    private func targetFrame() -> NSRect {
+        guard let anchor = self.anchorProvider?() else {
+            return WindowPlacement.topRightFrame(
+                size: NSSize(width: self.width, height: self.height),
+                padding: self.padding)
+        }
+
+        let screen = NSScreen.screens.first { screen in
+            screen.frame.contains(anchor.origin) || screen.frame.contains(NSPoint(x: anchor.midX, y: anchor.midY))
+        } ?? NSScreen.main
+
+        let bounds = (screen?.visibleFrame ?? .zero).insetBy(dx: self.padding, dy: self.padding)
+        return WindowPlacement.anchoredBelowFrame(
+            size: NSSize(width: self.width, height: self.height),
+            anchor: anchor,
+            padding: self.padding,
+            in: bounds)
+    }
+
+    private func updateWindowFrame(animate: Bool = false) {
+        guard let window else { return }
+        let frame = self.targetFrame()
+        if animate {
+            NSAnimationContext.runAnimationGroup { context in
+                context.duration = 0.12
+                context.timingFunction = CAMediaTimingFunction(name: .easeOut)
+                window.animator().setFrame(frame, display: true)
+            }
+        } else {
+            window.setFrame(frame, display: true)
+        }
+    }
+
+    private func installDismissMonitor() {
+        if ProcessInfo.processInfo.isRunningTests { return }
+        guard self.dismissMonitor == nil, let window else { return }
+        self.dismissMonitor = NSEvent.addGlobalMonitorForEvents(matching: [
+            .leftMouseDown,
+            .rightMouseDown,
+            .otherMouseDown,
+        ]) { [weak self] _ in
+            guard let self, self.model.isVisible else { return }
+            let pt = NSEvent.mouseLocation
+            if !window.frame.contains(pt) {
+                Task { @MainActor in self.dismiss(reason: "outsideClick") }
+            }
+        }
+    }
+
+    private func removeDismissMonitor() {
+        if let monitor = self.dismissMonitor {
+            NSEvent.removeMonitor(monitor)
+            self.dismissMonitor = nil
+        }
+    }
+}
+
+private struct HoverHUDView: View {
+    var controller: HoverHUDController
+    private let activityStore = WorkActivityStore.shared
+
+    private var statusTitle: String {
+        if self.activityStore.iconState.isWorking { return "Working" }
+        return "Idle"
+    }
+
+    private var detail: String {
+        if let current = self.activityStore.current?.label, !current.isEmpty { return current }
+        if let last = self.activityStore.lastToolLabel, !last.isEmpty { return last }
+        return "No recent activity"
+    }
+
+    private var symbolName: String {
+        if self.activityStore.iconState.isWorking {
+            return self.activityStore.iconState.badgeSymbolName
+        }
+        return "moon.zzz.fill"
+    }
+
+    private var dotColor: Color {
+        if self.activityStore.iconState.isWorking {
+            return Color(nsColor: NSColor.systemGreen.withAlphaComponent(0.7))
+        }
+        return .secondary
+    }
+
+    var body: some View {
+        HStack(alignment: .top, spacing: 10) {
+            Circle()
+                .fill(self.dotColor)
+                .frame(width: 7, height: 7)
+                .padding(.top, 5)
+
+            VStack(alignment: .leading, spacing: 4) {
+                Text(self.statusTitle)
+                    .font(.system(size: 13, weight: .semibold))
+                    .foregroundStyle(.primary)
+                Text(self.detail)
+                    .font(.system(size: 12))
+                    .foregroundStyle(.secondary)
+                    .lineLimit(2)
+                    .truncationMode(.middle)
+                    .fixedSize(horizontal: false, vertical: true)
+            }
+
+            Spacer(minLength: 8)
+
+            Image(systemName: self.symbolName)
+                .font(.system(size: 14, weight: .semibold))
+                .foregroundStyle(.secondary)
+                .padding(.top, 1)
+        }
+        .padding(12)
+        .background(
+            RoundedRectangle(cornerRadius: 14, style: .continuous)
+                .fill(.regularMaterial))
+        .overlay(
+            RoundedRectangle(cornerRadius: 14, style: .continuous)
+                .strokeBorder(Color.black.opacity(0.10), lineWidth: 1))
+        .contentShape(Rectangle())
+        .onHover { inside in
+            self.controller.panelHoverChanged(inside: inside)
+        }
+        .onTapGesture {
+            self.controller.openChat()
+        }
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/IconState.swift

@@ -0,0 +1,113 @@
+import Foundation
+import SwiftUI
+
+enum SessionRole {
+    case main
+    case other
+}
+
+enum ToolKind: String, Codable {
+    case bash, read, write, edit, attach, other
+}
+
+enum ActivityKind: Codable, Equatable {
+    case job
+    case tool(ToolKind)
+}
+
+enum IconState: Equatable {
+    case idle
+    case workingMain(ActivityKind)
+    case workingOther(ActivityKind)
+    case overridden(ActivityKind)
+
+    enum BadgeProminence: Equatable {
+        case primary
+        case secondary
+        case overridden
+    }
+
+    var badgeSymbolName: String {
+        switch self.activity {
+        case .tool(.bash): "chevron.left.slash.chevron.right"
+        case .tool(.read): "doc"
+        case .tool(.write): "pencil"
+        case .tool(.edit): "pencil.tip"
+        case .tool(.attach): "paperclip"
+        case .tool(.other), .job: "gearshape.fill"
+        }
+    }
+
+    var badgeProminence: BadgeProminence? {
+        switch self {
+        case .idle: nil
+        case .workingMain: .primary
+        case .workingOther: .secondary
+        case .overridden: .overridden
+        }
+    }
+
+    var isWorking: Bool {
+        switch self {
+        case .idle: false
+        default: true
+        }
+    }
+
+    private var activity: ActivityKind {
+        switch self {
+        case let .workingMain(kind),
+             let .workingOther(kind),
+             let .overridden(kind):
+            kind
+        case .idle:
+            .job
+        }
+    }
+}
+
+enum IconOverrideSelection: String, CaseIterable, Identifiable {
+    case system
+    case idle
+    case mainBash, mainRead, mainWrite, mainEdit, mainOther
+    case otherBash, otherRead, otherWrite, otherEdit, otherOther
+
+    var id: String {
+        self.rawValue
+    }
+
+    var label: String {
+        switch self {
+        case .system: "System (auto)"
+        case .idle: "Idle"
+        case .mainBash: "Working main – bash"
+        case .mainRead: "Working main – read"
+        case .mainWrite: "Working main – write"
+        case .mainEdit: "Working main – edit"
+        case .mainOther: "Working main – other"
+        case .otherBash: "Working other – bash"
+        case .otherRead: "Working other – read"
+        case .otherWrite: "Working other – write"
+        case .otherEdit: "Working other – edit"
+        case .otherOther: "Working other – other"
+        }
+    }
+
+    func toIconState() -> IconState {
+        let map: (ToolKind) -> ActivityKind = { .tool($0) }
+        switch self {
+        case .system: return .idle
+        case .idle: return .idle
+        case .mainBash: return .workingMain(map(.bash))
+        case .mainRead: return .workingMain(map(.read))
+        case .mainWrite: return .workingMain(map(.write))
+        case .mainEdit: return .workingMain(map(.edit))
+        case .mainOther: return .workingMain(map(.other))
+        case .otherBash: return .workingOther(map(.bash))
+        case .otherRead: return .workingOther(map(.read))
+        case .otherWrite: return .workingOther(map(.write))
+        case .otherEdit: return .workingOther(map(.edit))
+        case .otherOther: return .workingOther(map(.other))
+        }
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/InstancesSettings.swift

@@ -0,0 +1,479 @@
+import AppKit
+import SwiftUI
+
+struct InstancesSettings: View {
+    var store: InstancesStore
+
+    init(store: InstancesStore = .shared) {
+        self.store = store
+    }
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 12) {
+            self.header
+            if let err = store.lastError {
+                Text("Error: \(err)")
+                    .foregroundStyle(.red)
+            } else if let info = store.statusMessage {
+                Text(info)
+                    .foregroundStyle(.secondary)
+            }
+            if self.store.instances.isEmpty {
+                Text("No instances reported yet.")
+                    .foregroundStyle(.secondary)
+            } else {
+                List(self.store.instances) { inst in
+                    self.instanceRow(inst)
+                }
+                .listStyle(.inset)
+            }
+            Spacer()
+        }
+        .onAppear { self.store.start() }
+        .onDisappear { self.store.stop() }
+    }
+
+    private var header: some View {
+        HStack {
+            VStack(alignment: .leading, spacing: 4) {
+                Text("Connected Instances")
+                    .font(.headline)
+                Text("Latest presence beacons from OpenClaw nodes. Updated periodically.")
+                    .font(.footnote)
+                    .foregroundStyle(.secondary)
+            }
+            Spacer()
+            if self.store.isLoading {
+                ProgressView()
+            } else {
+                Button {
+                    Task { await self.store.refresh() }
+                } label: {
+                    Label("Refresh", systemImage: "arrow.clockwise")
+                }
+                .buttonStyle(.bordered)
+                .help("Refresh")
+            }
+        }
+    }
+
+    @ViewBuilder
+    private func instanceRow(_ inst: InstanceInfo) -> some View {
+        let isGateway = (inst.mode ?? "").trimmingCharacters(in: .whitespacesAndNewlines).lowercased() == "gateway"
+        let prettyPlatform = inst.platform.flatMap { self.prettyPlatform($0) }
+        let device = DeviceModelCatalog.presentation(
+            deviceFamily: inst.deviceFamily,
+            modelIdentifier: inst.modelIdentifier)
+
+        HStack(alignment: .top, spacing: 12) {
+            self.leadingDeviceIcon(inst, device: device)
+                .frame(width: 28, height: 28, alignment: .center)
+                .padding(.top, 1)
+
+            VStack(alignment: .leading, spacing: 4) {
+                HStack(spacing: 8) {
+                    Text(inst.host ?? "unknown host").font(.subheadline.bold())
+                    self.presenceIndicator(inst)
+                    if let ip = inst.ip { Text("(") + Text(ip).monospaced() + Text(")") }
+                }
+
+                HStack(spacing: 8) {
+                    if let version = inst.version {
+                        self.label(icon: "shippingbox", text: version)
+                    }
+
+                    if let device {
+                        // Avoid showing generic "Mac"/"iPhone"/etc; prefer the concrete model name.
+                        let family = (inst.deviceFamily ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
+                        let isGeneric = !family.isEmpty && device.title == family
+                        if !isGeneric {
+                            if let prettyPlatform {
+                                self.label(icon: device.symbol, text: "\(device.title) · \(prettyPlatform)")
+                            } else {
+                                self.label(icon: device.symbol, text: device.title)
+                            }
+                        } else if let prettyPlatform, let platform = inst.platform {
+                            self.label(icon: self.platformIcon(platform), text: prettyPlatform)
+                        }
+                    } else if let prettyPlatform, let platform = inst.platform {
+                        self.label(icon: self.platformIcon(platform), text: prettyPlatform)
+                    }
+
+                    if let mode = inst.mode { self.label(icon: "network", text: mode) }
+                }
+                .layoutPriority(1)
+
+                if !isGateway, self.shouldShowUpdateRow(inst) {
+                    HStack(spacing: 8) {
+                        Spacer(minLength: 0)
+
+                        // Last local input is helpful for interactive nodes, but noisy/meaningless for the gateway.
+                        if let secs = inst.lastInputSeconds {
+                            self.label(icon: "clock", text: "\(secs)s ago")
+                        }
+
+                        if let update = self.updateSummaryText(inst, isGateway: isGateway) {
+                            self.label(icon: "arrow.clockwise", text: update)
+                                .help(self.presenceUpdateSourceHelp(inst.reason ?? ""))
+                        }
+                    }
+                    .foregroundStyle(.secondary)
+                }
+            }
+        }
+        .padding(.vertical, 6)
+        .help(inst.text)
+        .contextMenu {
+            Button("Copy Debug Summary") {
+                NSPasteboard.general.clearContents()
+                NSPasteboard.general.setString(inst.text, forType: .string)
+            }
+        }
+    }
+
+    private func label(icon: String?, text: String) -> some View {
+        HStack(spacing: 4) {
+            if let icon {
+                if icon == Self.androidSymbolToken {
+                    AndroidMark()
+                        .foregroundStyle(.secondary)
+                        .frame(width: 12, height: 12, alignment: .center)
+                } else if self.isSystemSymbolAvailable(icon) {
+                    Image(systemName: icon).foregroundStyle(.secondary).font(.caption)
+                }
+            }
+            Text(text)
+        }
+        .font(.footnote)
+    }
+
+    private func presenceIndicator(_ inst: InstanceInfo) -> some View {
+        let status = self.presenceStatus(for: inst)
+        return HStack(spacing: 4) {
+            Circle()
+                .fill(status.color)
+                .frame(width: 6, height: 6)
+                .accessibilityHidden(true)
+            Text(status.label)
+                .foregroundStyle(.secondary)
+        }
+        .font(.caption)
+        .help("Presence updated \(inst.ageDescription).")
+        .accessibilityLabel("\(status.label) presence")
+    }
+
+    private func presenceStatus(for inst: InstanceInfo) -> (label: String, color: Color) {
+        let nowMs = Date().timeIntervalSince1970 * 1000
+        let ageSeconds = max(0, Int((nowMs - inst.ts) / 1000))
+        if ageSeconds <= 120 { return ("Active", .green) }
+        if ageSeconds <= 300 { return ("Idle", .yellow) }
+        return ("Stale", .gray)
+    }
+
+    @ViewBuilder
+    private func leadingDeviceIcon(_ inst: InstanceInfo, device: DevicePresentation?) -> some View {
+        let symbol = self.leadingDeviceSymbol(inst, device: device)
+        if symbol == Self.androidSymbolToken {
+            AndroidMark()
+                .foregroundStyle(.secondary)
+                .frame(width: 24, height: 24, alignment: .center)
+                .accessibilityHidden(true)
+        } else {
+            Image(systemName: symbol)
+                .font(.system(size: 26, weight: .regular))
+                .foregroundStyle(.secondary)
+                .accessibilityHidden(true)
+        }
+    }
+
+    private static let androidSymbolToken = "android"
+
+    private func leadingDeviceSymbol(_ inst: InstanceInfo, device: DevicePresentation?) -> String {
+        let family = (inst.deviceFamily ?? "").trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+        if family == "android" {
+            return Self.androidSymbolToken
+        }
+
+        if let title = device?.title.lowercased() {
+            if title.contains("mac studio") {
+                return self.safeSystemSymbol("macstudio", fallback: "desktopcomputer")
+            }
+            if title.contains("macbook") {
+                return self.safeSystemSymbol("laptopcomputer", fallback: "laptopcomputer")
+            }
+            if title.contains("ipad") {
+                return self.safeSystemSymbol("ipad", fallback: "ipad")
+            }
+            if title.contains("iphone") {
+                return self.safeSystemSymbol("iphone", fallback: "iphone")
+            }
+        }
+
+        if let symbol = device?.symbol {
+            return self.safeSystemSymbol(symbol, fallback: "cpu")
+        }
+
+        if let platform = inst.platform {
+            return self.safeSystemSymbol(self.platformIcon(platform), fallback: "cpu")
+        }
+
+        return "cpu"
+    }
+
+    private func shouldShowUpdateRow(_ inst: InstanceInfo) -> Bool {
+        if inst.lastInputSeconds != nil { return true }
+        if self.updateSummaryText(inst, isGateway: false) != nil { return true }
+        return false
+    }
+
+    private func safeSystemSymbol(_ preferred: String, fallback: String) -> String {
+        if self.isSystemSymbolAvailable(preferred) { return preferred }
+        return fallback
+    }
+
+    private func isSystemSymbolAvailable(_ name: String) -> Bool {
+        NSImage(systemSymbolName: name, accessibilityDescription: nil) != nil
+    }
+
+    private struct AndroidMark: View {
+        var body: some View {
+            GeometryReader { geo in
+                let w = geo.size.width
+                let h = geo.size.height
+                let headHeight = h * 0.68
+                let headWidth = w * 0.92
+                let headY = h * 0.18
+                let corner = headHeight * 0.28
+
+                ZStack {
+                    RoundedRectangle(cornerRadius: corner, style: .continuous)
+                        .frame(width: headWidth, height: headHeight)
+                        .position(x: w / 2, y: headY + headHeight / 2)
+
+                    Circle()
+                        .frame(width: max(1, w * 0.1), height: max(1, w * 0.1))
+                        .position(x: w * 0.38, y: headY + headHeight * 0.55)
+                        .blendMode(.destinationOut)
+
+                    Circle()
+                        .frame(width: max(1, w * 0.1), height: max(1, w * 0.1))
+                        .position(x: w * 0.62, y: headY + headHeight * 0.55)
+                        .blendMode(.destinationOut)
+
+                    Rectangle()
+                        .frame(width: max(1, w * 0.08), height: max(1, h * 0.18))
+                        .rotationEffect(.degrees(-25))
+                        .position(x: w * 0.34, y: h * 0.12)
+
+                    Rectangle()
+                        .frame(width: max(1, w * 0.08), height: max(1, h * 0.18))
+                        .rotationEffect(.degrees(25))
+                        .position(x: w * 0.66, y: h * 0.12)
+                }
+                .compositingGroup()
+            }
+        }
+    }
+
+    private func platformIcon(_ raw: String) -> String {
+        let (prefix, _) = self.parsePlatform(raw)
+        switch prefix {
+        case "macos":
+            return "laptopcomputer"
+        case "ios":
+            return "iphone"
+        case "ipados":
+            return "ipad"
+        case "tvos":
+            return "appletv"
+        case "watchos":
+            return "applewatch"
+        default:
+            return "cpu"
+        }
+    }
+
+    private func prettyPlatform(_ raw: String) -> String? {
+        let (prefix, version) = self.parsePlatform(raw)
+        if prefix.isEmpty { return nil }
+        let name: String = switch prefix {
+        case "macos": "macOS"
+        case "ios": "iOS"
+        case "ipados": "iPadOS"
+        case "tvos": "tvOS"
+        case "watchos": "watchOS"
+        default: prefix.prefix(1).uppercased() + prefix.dropFirst()
+        }
+        guard let version, !version.isEmpty else { return name }
+        let parts = version.split(separator: ".").map(String.init)
+        if parts.count >= 2 {
+            return "\(name) \(parts[0]).\(parts[1])"
+        }
+        return "\(name) \(version)"
+    }
+
+    private func parsePlatform(_ raw: String) -> (prefix: String, version: String?) {
+        let trimmed = raw.trimmingCharacters(in: .whitespacesAndNewlines)
+        if trimmed.isEmpty { return ("", nil) }
+        let parts = trimmed.split(whereSeparator: { $0 == " " || $0 == "\t" }).map(String.init)
+        let prefix = parts.first?.lowercased() ?? ""
+        let versionToken = parts.dropFirst().first
+        return (prefix, versionToken)
+    }
+
+    private func presenceUpdateSourceShortText(_ reason: String) -> String? {
+        let trimmed = reason.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return nil }
+        switch trimmed {
+        case "self":
+            return "Self"
+        case "connect":
+            return "Connect"
+        case "disconnect":
+            return "Disconnect"
+        case "node-connected":
+            return "Node connect"
+        case "node-disconnected":
+            return "Node disconnect"
+        case "launch":
+            return "Launch"
+        case "periodic":
+            return "Heartbeat"
+        case "instances-refresh":
+            return "Instances"
+        case "seq gap":
+            return "Resync"
+        default:
+            return trimmed
+        }
+    }
+
+    private func updateSummaryText(_ inst: InstanceInfo, isGateway: Bool) -> String? {
+        // For gateway rows, omit the "updated via/by" provenance entirely.
+        if isGateway {
+            return nil
+        }
+
+        let age = inst.ageDescription.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !age.isEmpty else { return nil }
+
+        let source = self.presenceUpdateSourceShortText(inst.reason ?? "")
+        if let source, !source.isEmpty {
+            return "\(age) · \(source)"
+        }
+        return age
+    }
+
+    private func presenceUpdateSourceHelp(_ reason: String) -> String {
+        let trimmed = reason.trimmingCharacters(in: .whitespacesAndNewlines)
+        if trimmed.isEmpty {
+            return "Why this presence entry was last updated (debug marker)."
+        }
+        return "Why this presence entry was last updated (debug marker). Raw: \(trimmed)"
+    }
+}
+
+#if DEBUG
+extension InstancesSettings {
+    static func exerciseForTesting() {
+        let view = InstancesSettings(store: InstancesStore(isPreview: true))
+        let mac = InstanceInfo(
+            id: "mac",
+            host: "studio",
+            ip: "10.0.0.2",
+            version: "1.2.3",
+            platform: "macOS 14.2",
+            deviceFamily: "Mac",
+            modelIdentifier: "Mac14,10",
+            lastInputSeconds: 12,
+            mode: "local",
+            reason: "self",
+            text: "Mac Studio",
+            ts: 1_700_000_000_000)
+        let genericIOS = InstanceInfo(
+            id: "iphone",
+            host: "phone",
+            ip: "10.0.0.3",
+            version: "2.0.0",
+            platform: "iOS 18.0",
+            deviceFamily: "iPhone",
+            modelIdentifier: nil,
+            lastInputSeconds: 35,
+            mode: "node",
+            reason: "connect",
+            text: "iPhone node",
+            ts: 1_700_000_100_000)
+        let android = InstanceInfo(
+            id: "android",
+            host: "pixel",
+            ip: nil,
+            version: "3.1.0",
+            platform: "Android 14",
+            deviceFamily: "Android",
+            modelIdentifier: nil,
+            lastInputSeconds: 90,
+            mode: "node",
+            reason: "seq gap",
+            text: "Android node",
+            ts: 1_700_000_200_000)
+        let gateway = InstanceInfo(
+            id: "gateway",
+            host: "gateway",
+            ip: "10.0.0.9",
+            version: "4.0.0",
+            platform: "Linux",
+            deviceFamily: nil,
+            modelIdentifier: nil,
+            lastInputSeconds: nil,
+            mode: "gateway",
+            reason: "periodic",
+            text: "Gateway",
+            ts: 1_700_000_300_000)
+
+        _ = view.instanceRow(mac)
+        _ = view.instanceRow(genericIOS)
+        _ = view.instanceRow(android)
+        _ = view.instanceRow(gateway)
+
+        _ = view.leadingDeviceSymbol(
+            mac,
+            device: DevicePresentation(title: "Mac Studio", symbol: "macstudio"))
+        _ = view.leadingDeviceSymbol(
+            mac,
+            device: DevicePresentation(title: "MacBook Pro", symbol: "laptopcomputer"))
+        _ = view.leadingDeviceSymbol(android, device: nil)
+        _ = view.platformIcon("tvOS 17.1")
+        _ = view.platformIcon("watchOS 10")
+        _ = view.platformIcon("unknown 1.0")
+        _ = view.prettyPlatform("macOS 14.2")
+        _ = view.prettyPlatform("iOS 18")
+        _ = view.prettyPlatform("ipados 17.1")
+        _ = view.prettyPlatform("linux")
+        _ = view.prettyPlatform("   ")
+        _ = view.parsePlatform("macOS 14.1")
+        _ = view.parsePlatform(" ")
+        _ = view.presenceUpdateSourceShortText("self")
+        _ = view.presenceUpdateSourceShortText("instances-refresh")
+        _ = view.presenceUpdateSourceShortText("seq gap")
+        _ = view.presenceUpdateSourceShortText("custom")
+        _ = view.presenceUpdateSourceShortText(" ")
+        _ = view.updateSummaryText(mac, isGateway: false)
+        _ = view.updateSummaryText(gateway, isGateway: true)
+        _ = view.presenceUpdateSourceHelp("")
+        _ = view.presenceUpdateSourceHelp("connect")
+        _ = view.safeSystemSymbol("not-a-symbol", fallback: "cpu")
+        _ = view.isSystemSymbolAvailable("sparkles")
+        _ = view.label(icon: "android", text: "Android")
+        _ = view.label(icon: "sparkles", text: "Sparkles")
+        _ = view.label(icon: nil, text: "Plain")
+        _ = AndroidMark().body
+    }
+}
+
+struct InstancesSettings_Previews: PreviewProvider {
+    static var previews: some View {
+        InstancesSettings(store: .preview())
+            .frame(width: SettingsTab.windowWidth, height: SettingsTab.windowHeight)
+    }
+}
+#endif

openclaw/apps/macos/Sources/OpenClaw/InstancesStore.swift

@@ -0,0 +1,349 @@
+import Cocoa
+import Foundation
+import Observation
+import OpenClawKit
+import OpenClawProtocol
+import OSLog
+
+struct InstanceInfo: Identifiable, Codable {
+    let id: String
+    let host: String?
+    let ip: String?
+    let version: String?
+    let platform: String?
+    let deviceFamily: String?
+    let modelIdentifier: String?
+    let lastInputSeconds: Int?
+    let mode: String?
+    let reason: String?
+    let text: String
+    let ts: Double
+
+    var ageDescription: String {
+        let date = Date(timeIntervalSince1970: ts / 1000)
+        return age(from: date)
+    }
+
+    var lastInputDescription: String {
+        guard let secs = lastInputSeconds else { return "unknown" }
+        return "\(secs)s ago"
+    }
+}
+
+@MainActor
+@Observable
+final class InstancesStore {
+    static let shared = InstancesStore()
+    let isPreview: Bool
+
+    var instances: [InstanceInfo] = []
+    var lastError: String?
+    var statusMessage: String?
+    var isLoading = false
+
+    private let logger = Logger(subsystem: "ai.openclaw", category: "instances")
+    private var task: Task<Void, Never>?
+    private let interval: TimeInterval = 30
+    private var eventTask: Task<Void, Never>?
+    private var startCount = 0
+    private var lastPresenceById: [String: InstanceInfo] = [:]
+    private var lastLoginNotifiedAtMs: [String: Double] = [:]
+
+    private struct PresenceEventPayload: Codable {
+        let presence: [PresenceEntry]
+    }
+
+    init(isPreview: Bool = false) {
+        self.isPreview = isPreview
+    }
+
+    func start() {
+        guard !self.isPreview else { return }
+        self.startCount += 1
+        guard self.startCount == 1 else { return }
+        guard self.task == nil else { return }
+        self.startGatewaySubscription()
+        self.task = Task.detached { [weak self] in
+            guard let self else { return }
+            await self.refresh()
+            while !Task.isCancelled {
+                try? await Task.sleep(nanoseconds: UInt64(self.interval * 1_000_000_000))
+                await self.refresh()
+            }
+        }
+    }
+
+    func stop() {
+        guard !self.isPreview else { return }
+        guard self.startCount > 0 else { return }
+        self.startCount -= 1
+        guard self.startCount == 0 else { return }
+        self.task?.cancel()
+        self.task = nil
+        self.eventTask?.cancel()
+        self.eventTask = nil
+    }
+
+    private func startGatewaySubscription() {
+        self.eventTask?.cancel()
+        self.eventTask = Task { [weak self] in
+            guard let self else { return }
+            let stream = await GatewayConnection.shared.subscribe()
+            for await push in stream {
+                if Task.isCancelled { return }
+                await MainActor.run { [weak self] in
+                    self?.handle(push: push)
+                }
+            }
+        }
+    }
+
+    private func handle(push: GatewayPush) {
+        switch push {
+        case let .event(evt) where evt.event == "presence":
+            if let payload = evt.payload {
+                self.handlePresenceEventPayload(payload)
+            }
+        case .seqGap:
+            Task { await self.refresh() }
+        case let .snapshot(hello):
+            self.applyPresence(hello.snapshot.presence)
+        default:
+            break
+        }
+    }
+
+    func refresh() async {
+        if self.isLoading { return }
+        self.statusMessage = nil
+        self.isLoading = true
+        defer { self.isLoading = false }
+        do {
+            PresenceReporter.shared.sendImmediate(reason: "instances-refresh")
+            let data = try await ControlChannel.shared.request(method: "system-presence")
+            self.lastPayload = data
+            if data.isEmpty {
+                self.logger.error("instances fetch returned empty payload")
+                self.instances = [self.localFallbackInstance(reason: "no presence payload")]
+                self.lastError = nil
+                self.statusMessage = "No presence payload from gateway; showing local fallback + health probe."
+                await self.probeHealthIfNeeded(reason: "no payload")
+                return
+            }
+            let decoded = try JSONDecoder().decode([PresenceEntry].self, from: data)
+            let withIDs = self.normalizePresence(decoded)
+            if withIDs.isEmpty {
+                self.instances = [self.localFallbackInstance(reason: "no presence entries")]
+                self.lastError = nil
+                self.statusMessage = "Presence list was empty; showing local fallback + health probe."
+                await self.probeHealthIfNeeded(reason: "empty list")
+            } else {
+                self.instances = withIDs
+                self.lastError = nil
+                self.statusMessage = nil
+            }
+        } catch {
+            self.logger.error(
+                """
+                instances fetch failed: \(error.localizedDescription, privacy: .public) \
+                len=\(self.lastPayload?.count ?? 0, privacy: .public) \
+                utf8=\(self.snippet(self.lastPayload), privacy: .public)
+                """)
+            self.instances = [self.localFallbackInstance(reason: "presence decode failed")]
+            self.lastError = nil
+            self.statusMessage = "Presence data invalid; showing local fallback + health probe."
+            await self.probeHealthIfNeeded(reason: "decode failed")
+        }
+    }
+
+    private func localFallbackInstance(reason: String) -> InstanceInfo {
+        let host = Host.current().localizedName ?? "this-mac"
+        let ip = SystemPresenceInfo.primaryIPv4Address()
+        let version = Bundle.main.object(forInfoDictionaryKey: "CFBundleShortVersionString") as? String
+        let osVersion = ProcessInfo.processInfo.operatingSystemVersion
+        let platform = "macos \(osVersion.majorVersion).\(osVersion.minorVersion).\(osVersion.patchVersion)"
+        let text = "Local node: \(host)\(ip.map { " (\($0))" } ?? "") · app \(version ?? "dev")"
+        let ts = Date().timeIntervalSince1970 * 1000
+        return InstanceInfo(
+            id: "local-\(host)",
+            host: host,
+            ip: ip,
+            version: version,
+            platform: platform,
+            deviceFamily: "Mac",
+            modelIdentifier: InstanceIdentity.modelIdentifier,
+            lastInputSeconds: SystemPresenceInfo.lastInputSeconds(),
+            mode: "local",
+            reason: reason,
+            text: text,
+            ts: ts)
+    }
+
+    // MARK: - Helpers
+
+    /// Keep the last raw payload for logging.
+    private var lastPayload: Data?
+
+    private func snippet(_ data: Data?, limit: Int = 256) -> String {
+        guard let data else { return "<none>" }
+        if data.isEmpty { return "<empty>" }
+        let prefix = data.prefix(limit)
+        if let asString = String(data: prefix, encoding: .utf8) {
+            return asString.replacingOccurrences(of: "\n", with: " ")
+        }
+        return "<\(data.count) bytes non-utf8>"
+    }
+
+    private func probeHealthIfNeeded(reason: String? = nil) async {
+        do {
+            let data = try await ControlChannel.shared.health(timeout: 8)
+            guard let snap = decodeHealthSnapshot(from: data) else { return }
+            let linkId = snap.channelOrder?.first(where: {
+                if let summary = snap.channels[$0] { return summary.linked != nil }
+                return false
+            }) ?? snap.channels.keys.first(where: {
+                if let summary = snap.channels[$0] { return summary.linked != nil }
+                return false
+            })
+            let linked = linkId.flatMap { snap.channels[$0]?.linked } ?? false
+            let linkLabel =
+                linkId.flatMap { snap.channelLabels?[$0] } ??
+                linkId?.capitalized ??
+                "channel"
+            let entry = InstanceInfo(
+                id: "health-\(snap.ts)",
+                host: "gateway (health)",
+                ip: nil,
+                version: nil,
+                platform: nil,
+                deviceFamily: nil,
+                modelIdentifier: nil,
+                lastInputSeconds: nil,
+                mode: "health",
+                reason: "health probe",
+                text: "Health ok · \(linkLabel) linked=\(linked)",
+                ts: snap.ts)
+            if !self.instances.contains(where: { $0.id == entry.id }) {
+                self.instances.insert(entry, at: 0)
+            }
+            self.lastError = nil
+            self.statusMessage =
+                "Presence unavailable (\(reason ?? "refresh")); showing health probe + local fallback."
+        } catch {
+            self.logger.error("instances health probe failed: \(error.localizedDescription, privacy: .public)")
+            if let reason {
+                self.statusMessage =
+                    "Presence unavailable (\(reason)), health probe failed: \(error.localizedDescription)"
+            }
+        }
+    }
+
+    private func decodeAndApplyPresenceData(_ data: Data) {
+        do {
+            let decoded = try JSONDecoder().decode([PresenceEntry].self, from: data)
+            self.applyPresence(decoded)
+        } catch {
+            self.logger.error("presence decode from event failed: \(error.localizedDescription, privacy: .public)")
+            self.lastError = error.localizedDescription
+        }
+    }
+
+    func handlePresenceEventPayload(_ payload: OpenClawProtocol.AnyCodable) {
+        do {
+            let wrapper = try GatewayPayloadDecoding.decode(payload, as: PresenceEventPayload.self)
+            self.applyPresence(wrapper.presence)
+        } catch {
+            self.logger.error("presence event decode failed: \(error.localizedDescription, privacy: .public)")
+            self.lastError = error.localizedDescription
+        }
+    }
+
+    private func normalizePresence(_ entries: [PresenceEntry]) -> [InstanceInfo] {
+        entries.map { entry -> InstanceInfo in
+            let key = entry.instanceid ?? entry.host ?? entry.ip ?? entry.text ?? "entry-\(entry.ts)"
+            return InstanceInfo(
+                id: key,
+                host: entry.host,
+                ip: entry.ip,
+                version: entry.version,
+                platform: entry.platform,
+                deviceFamily: entry.devicefamily,
+                modelIdentifier: entry.modelidentifier,
+                lastInputSeconds: entry.lastinputseconds,
+                mode: entry.mode,
+                reason: entry.reason,
+                text: entry.text ?? "Unnamed node",
+                ts: Double(entry.ts))
+        }
+    }
+
+    private func applyPresence(_ entries: [PresenceEntry]) {
+        let withIDs = self.normalizePresence(entries)
+        self.notifyOnNodeLogin(withIDs)
+        self.lastPresenceById = Dictionary(uniqueKeysWithValues: withIDs.map { ($0.id, $0) })
+        self.instances = withIDs
+        self.statusMessage = nil
+        self.lastError = nil
+    }
+
+    private func notifyOnNodeLogin(_ instances: [InstanceInfo]) {
+        for inst in instances {
+            guard let reason = inst.reason?.trimmingCharacters(in: .whitespacesAndNewlines) else { continue }
+            guard reason == "node-connected" else { continue }
+            if let mode = inst.mode?.lowercased(), mode == "local" { continue }
+
+            let previous = self.lastPresenceById[inst.id]
+            if previous?.reason == "node-connected", previous?.ts == inst.ts { continue }
+
+            let lastNotified = self.lastLoginNotifiedAtMs[inst.id] ?? 0
+            if inst.ts <= lastNotified { continue }
+            self.lastLoginNotifiedAtMs[inst.id] = inst.ts
+
+            let name = inst.host?.trimmingCharacters(in: .whitespacesAndNewlines)
+            let device = name?.isEmpty == false ? name! : inst.id
+            Task { @MainActor in
+                _ = await NotificationManager().send(
+                    title: "Node connected",
+                    body: device,
+                    sound: nil,
+                    priority: .active)
+            }
+        }
+    }
+}
+
+extension InstancesStore {
+    static func preview(instances: [InstanceInfo] = [
+        InstanceInfo(
+            id: "local",
+            host: "steipete-mac",
+            ip: "10.0.0.12",
+            version: "1.2.3",
+            platform: "macos 26.2.0",
+            deviceFamily: "Mac",
+            modelIdentifier: "Mac16,6",
+            lastInputSeconds: 12,
+            mode: "local",
+            reason: "preview",
+            text: "Local node: steipete-mac (10.0.0.12) · app 1.2.3",
+            ts: Date().timeIntervalSince1970 * 1000),
+        InstanceInfo(
+            id: "gateway",
+            host: "gateway",
+            ip: "100.64.0.2",
+            version: "1.2.3",
+            platform: "linux 6.6.0",
+            deviceFamily: "Linux",
+            modelIdentifier: "x86_64",
+            lastInputSeconds: 45,
+            mode: "remote",
+            reason: "preview",
+            text: "Gateway node · tunnel ok",
+            ts: Date().timeIntervalSince1970 * 1000 - 45000),
+    ]) -> InstancesStore {
+        let store = InstancesStore(isPreview: true)
+        store.instances = instances
+        store.statusMessage = "Preview data"
+        return store
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/LaunchAgentManager.swift

@@ -0,0 +1,78 @@
+import Foundation
+
+enum LaunchAgentManager {
+    private static var plistURL: URL {
+        FileManager().homeDirectoryForCurrentUser
+            .appendingPathComponent("Library/LaunchAgents/ai.openclaw.mac.plist")
+    }
+
+    static func status() async -> Bool {
+        guard FileManager().fileExists(atPath: self.plistURL.path) else { return false }
+        let result = await self.runLaunchctl(["print", "gui/\(getuid())/\(launchdLabel)"])
+        return result == 0
+    }
+
+    static func set(enabled: Bool, bundlePath: String) async {
+        if enabled {
+            self.writePlist(bundlePath: bundlePath)
+            _ = await self.runLaunchctl(["bootout", "gui/\(getuid())/\(launchdLabel)"])
+            _ = await self.runLaunchctl(["bootstrap", "gui/\(getuid())", self.plistURL.path])
+            _ = await self.runLaunchctl(["kickstart", "-k", "gui/\(getuid())/\(launchdLabel)"])
+        } else {
+            // Disable autostart going forward but leave the current app running.
+            // bootout would terminate the launchd job immediately (and crash the app if launched via agent).
+            try? FileManager().removeItem(at: self.plistURL)
+        }
+    }
+
+    private static func writePlist(bundlePath: String) {
+        let plist = """
+        <?xml version="1.0" encoding="UTF-8"?>
+        <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+        <plist version="1.0">
+        <dict>
+          <key>Label</key>
+          <string>ai.openclaw.mac</string>
+          <key>ProgramArguments</key>
+          <array>
+            <string>\(bundlePath)/Contents/MacOS/OpenClaw</string>
+          </array>
+          <key>WorkingDirectory</key>
+          <string>\(FileManager().homeDirectoryForCurrentUser.path)</string>
+          <key>RunAtLoad</key>
+          <true/>
+          <key>KeepAlive</key>
+          <true/>
+          <key>EnvironmentVariables</key>
+          <dict>
+            <key>PATH</key>
+            <string>\(CommandResolver.preferredPaths().joined(separator: ":"))</string>
+          </dict>
+          <key>StandardOutPath</key>
+          <string>\(LogLocator.launchdLogPath)</string>
+          <key>StandardErrorPath</key>
+          <string>\(LogLocator.launchdLogPath)</string>
+        </dict>
+        </plist>
+        """
+        try? plist.write(to: self.plistURL, atomically: true, encoding: .utf8)
+    }
+
+    @discardableResult
+    private static func runLaunchctl(_ args: [String]) async -> Int32 {
+        await Task.detached(priority: .utility) { () -> Int32 in
+            let process = Process()
+            process.launchPath = "/bin/launchctl"
+            process.arguments = args
+            let pipe = Pipe()
+            process.standardOutput = pipe
+            process.standardError = pipe
+            do {
+                _ = try process.runAndReadToEnd(from: pipe)
+                return process.terminationStatus
+            } catch {
+                return -1
+            }
+        }.value
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/Launchctl.swift

@@ -0,0 +1,87 @@
+import Foundation
+
+enum Launchctl {
+    struct Result: Sendable {
+        let status: Int32
+        let output: String
+    }
+
+    @discardableResult
+    static func run(_ args: [String]) async -> Result {
+        await Task.detached(priority: .utility) { () -> Result in
+            let process = Process()
+            process.launchPath = "/bin/launchctl"
+            process.arguments = args
+            let pipe = Pipe()
+            process.standardOutput = pipe
+            process.standardError = pipe
+            do {
+                let data = try process.runAndReadToEnd(from: pipe)
+                let output = String(data: data, encoding: .utf8) ?? ""
+                return Result(status: process.terminationStatus, output: output)
+            } catch {
+                return Result(status: -1, output: error.localizedDescription)
+            }
+        }.value
+    }
+}
+
+struct LaunchAgentPlistSnapshot: Equatable, Sendable {
+    let programArguments: [String]
+    let environment: [String: String]
+    let stdoutPath: String?
+    let stderrPath: String?
+
+    let port: Int?
+    let bind: String?
+    let token: String?
+    let password: String?
+}
+
+enum LaunchAgentPlist {
+    static func snapshot(url: URL) -> LaunchAgentPlistSnapshot? {
+        guard let data = try? Data(contentsOf: url) else { return nil }
+        let rootAny: Any
+        do {
+            rootAny = try PropertyListSerialization.propertyList(
+                from: data,
+                options: [],
+                format: nil)
+        } catch {
+            return nil
+        }
+        guard let root = rootAny as? [String: Any] else { return nil }
+        let programArguments = root["ProgramArguments"] as? [String] ?? []
+        let env = root["EnvironmentVariables"] as? [String: String] ?? [:]
+        let stdoutPath = (root["StandardOutPath"] as? String)?
+            .trimmingCharacters(in: .whitespacesAndNewlines).nonEmpty
+        let stderrPath = (root["StandardErrorPath"] as? String)?
+            .trimmingCharacters(in: .whitespacesAndNewlines).nonEmpty
+        let port = Self.extractFlagInt(programArguments, flag: "--port")
+        let bind = Self.extractFlagString(programArguments, flag: "--bind")?.lowercased()
+        let token = env["OPENCLAW_GATEWAY_TOKEN"]?.trimmingCharacters(in: .whitespacesAndNewlines).nonEmpty
+        let password = env["OPENCLAW_GATEWAY_PASSWORD"]?.trimmingCharacters(in: .whitespacesAndNewlines).nonEmpty
+        return LaunchAgentPlistSnapshot(
+            programArguments: programArguments,
+            environment: env,
+            stdoutPath: stdoutPath,
+            stderrPath: stderrPath,
+            port: port,
+            bind: bind,
+            token: token,
+            password: password)
+    }
+
+    private static func extractFlagInt(_ args: [String], flag: String) -> Int? {
+        guard let raw = self.extractFlagString(args, flag: flag) else { return nil }
+        return Int(raw)
+    }
+
+    private static func extractFlagString(_ args: [String], flag: String) -> String? {
+        guard let idx = args.firstIndex(of: flag) else { return nil }
+        let valueIdx = args.index(after: idx)
+        guard valueIdx < args.endIndex else { return nil }
+        let token = args[valueIdx].trimmingCharacters(in: .whitespacesAndNewlines)
+        return token.isEmpty ? nil : token
+    }
+}

openclaw/apps/macos/Sources/OpenClaw/LaunchdManager.swift

@@ -0,0 +1,20 @@
+import Foundation
+
+enum LaunchdManager {
+    private static func runLaunchctl(_ args: [String]) {
+        let process = Process()
+        process.launchPath = "/bin/launchctl"
+        process.arguments = args
+        try? process.run()
+    }
+
+    static func startOpenClaw() {
+        let userTarget = "gui/\(getuid())/\(launchdLabel)"
+        self.runLaunchctl(["kickstart", "-k", userTarget])
+    }
+
+    static func stopOpenClaw() {
+        let userTarget = "gui/\(getuid())/\(launchdLabel)"
+        self.runLaunchctl(["stop", userTarget])
+    }
+}