fix(macos): preserve PATH for SSH helpers (#100214)

steipete · web-flow · commit c64a306f908b · 2026-07-05T00:45:08.000-07:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -31,6 +31,7 @@ Docs: https://docs.openclaw.ai
 
 ### Fixes
 
+- **macOS SSH tunnels:** resolve user-installed SSH `ProxyCommand` helpers through the app's managed PATH while preserving inherited connection environment, so remote aliases work after Finder and sanitized-script launches.
 - **Control UI terminal rendering:** adopt the shared `@openclaw/libterminal` browser lifecycle and add Nerd Font fallbacks so icon-enabled shell listings render their glyphs when a compatible local font is installed.
 - **Slack transcript history:** let Codex app-server own its persisted assistant replies so Slack does not append redundant delivery-mirror rows, while the Control UI keeps legacy duplicate mirrors hidden.
 - **Control UI chat history:** hide redundant channel-final delivery mirrors when the preceding app-server assistant reply already shows the same text.
diff --git a/apps/macos/Sources/OpenClaw/CommandResolver.swift b/apps/macos/Sources/OpenClaw/CommandResolver.swift
@@ -107,6 +107,7 @@ enum CommandResolver {
             "/usr/local/bin",
             "/usr/bin",
             "/bin",
+            home.appendingPathComponent(".local/bin").path,
         ]
         #if DEBUG
         // Dev-only convenience. Avoid project-local PATH hijacking in release builds.
@@ -338,6 +339,15 @@ enum CommandResolver {
 
     // MARK: - SSH helpers
 
+    static func sshEnvironment(
+        base: [String: String] = ProcessInfo.processInfo.environment,
+        searchPaths: [String]? = nil) -> [String: String]
+    {
+        var environment = base
+        environment["PATH"] = (searchPaths ?? self.preferredPaths()).joined(separator: ":")
+        return environment
+    }
+
     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 }
diff --git a/apps/macos/Sources/OpenClaw/RemoteGatewayProbe.swift b/apps/macos/Sources/OpenClaw/RemoteGatewayProbe.swift
@@ -186,7 +186,7 @@ enum RemoteGatewayProbe {
             let sshResult = await ShellExecutor.run(
                 command: sshCommand,
                 cwd: nil,
-                env: nil,
+                env: CommandResolver.sshEnvironment(),
                 timeout: 8)
             guard sshResult.ok else {
                 return .failed(self.formatSSHFailure(sshResult, target: settings.target))
diff --git a/apps/macos/Sources/OpenClaw/RemotePortTunnel.swift b/apps/macos/Sources/OpenClaw/RemotePortTunnel.swift
@@ -109,6 +109,7 @@ final class RemotePortTunnel: @unchecked Sendable {
         let process = Process()
         process.executableURL = URL(fileURLWithPath: "/usr/bin/ssh")
         process.arguments = args
+        process.environment = CommandResolver.sshEnvironment()
 
         let pipe = Pipe()
         process.standardError = pipe
diff --git a/apps/macos/Tests/OpenClawIPCTests/CommandResolverTests.swift b/apps/macos/Tests/OpenClawIPCTests/CommandResolverTests.swift
@@ -187,6 +187,35 @@ import Testing
         #expect(managerIndex < systemIndex)
     }
 
+    @Test func `preferred paths include local user bin after system bins`() throws {
+        let home = try makeTempDirForTests()
+        let localBin = home.appendingPathComponent(".local/bin").path
+        let paths = CommandResolver.preferredPaths(
+            home: home,
+            current: [],
+            projectRoot: home)
+
+        let localIndex = try #require(paths.firstIndex(of: localBin))
+        let systemIndex = try #require(paths.firstIndex(of: "/bin"))
+        #expect(localIndex > systemIndex)
+        #expect(paths.count(where: { $0 == localBin }) == 1)
+    }
+
+    @Test func `SSH environment replaces path without dropping inherited values`() {
+        let paths = ["/usr/bin", "/bin", "/Users/test/.local/bin", "/opt/homebrew/bin"]
+        let environment = CommandResolver.sshEnvironment(
+            base: [
+                "HOME": "/Users/test",
+                "PATH": "/stale/path",
+                "SSH_AUTH_SOCK": "/tmp/ssh-agent.sock",
+            ],
+            searchPaths: paths)
+
+        #expect(environment["PATH"] == paths.joined(separator: ":"))
+        #expect(environment["HOME"] == "/Users/test")
+        #expect(environment["SSH_AUTH_SOCK"] == "/tmp/ssh-agent.sock")
+    }
+
     @Test func `validated CLI preference expires when the app requires a newer version`() throws {
         let defaults = self.makeDefaults()
         let root = try makeTempDirForTests()
