skills.install Fails on macOS 26: Command Line Tools Incompatibility

Error Output:

⇄ res ✗ skills.install 3243ms errorCode=UNAVAILABLE errorMessage=Install failed (exit 1): Error: Your Command Line Tools (CLT) does not support macOS 26. conn=23be7d37…afc5 id=6FA944C0…F29E

Manifestations:

• All skill installation attempts via OpenClaw fail on macOS 26
• Exit code 1 is returned from the underlying installation process
• Error occurs immediately after initiating skills.install
• No skills can be installed regardless of skill type or source
• The error is reproducible on clean macOS 26 installations

Affected Configurations:

• OS: macOS 26 ( Sequoia 26 / next-gen macOS )
• OpenClaw: v2026.3.8-beta.1
• Install Method: Mac App distribution
• Typical CLT State: Xcode-managed or standalone CLT < 18.0

Primary Cause: Version Mismatch Between macOS 26 and Installed Command Line Tools

macOS 26 introduces new SDK requirements and system framework changes that older CLT versions (prior to CLT 18.0) do not recognize. When OpenClaw’s skill installation process invokes system tools (typically via xcodebuild, git, or sw_vers), the CLT reports the macOS version as unsupported.

Technical Failure Sequence:

1. OpenClaw initiates skills.install command
2. Internal installer script detects macOS version via sw_vers -productVersion
3. macOS 26 returns version string 26.x.x
4. CLT version check compares against known supported versions
5. CLT < 18.0 lacks macOS 26 in its internal version table
6. CLT returns exit code 1 with message: Your Command Line Tools (CLT) does not support macOS 26
7. OpenClaw wraps this as errorCode=UNAVAILABLE

Architectural Inconsistency: The macOS 26 beta/developer preview ships with an SDK version that CLT 17.x cannot parse. This is a deliberate gatekeeping mechanism—Apple prevents tooling mismatch at the cost of usability on pre-release OS versions.

Why This Is a Regression: In prior macOS versions (Ventura, Sonoma), the CLT would silently accept unrecognized versions or fall back gracefully. The stricter version checking was introduced in CLT 17.5+ as a defensive measure against SDK/ABI mismatches.

Option A: Update Command Line Tools to Beta/Unsupported Version

Before:

$ xcode-select -p
/Applications/Xcode.app/Contents/Developer
$ clang --version
Apple clang version 17.0.0 (clang-1700.0.41.2)
Target: arm64-apple-darwin26.0.0

Step 1: Check Current CLT Status

$ xcode-select --print-path
/Library/Developer/CommandLineTools
$ ls /Library/Developer/CommandLineTools/SDKs/
MacOSX.sdk
MacOSX26.0.sdk  # May be missing or broken

Step 2: Remove Outdated Standalone CLT

$ sudo rm -rf /Library/Developer/CommandLineTools
$ xcode-select --reset

Step 3: Install Latest Xcode Beta (Includes macOS 26 Support)

$ # Download Xcode 26 beta from developer.apple.com
$ # Requires Apple Developer account
$ sudo xcodebuild -downloadBetaPlatform
$ xcode-select --switch /Applications/Xcode-26.app/Contents/Developer

After:

$ clang --version
Apple clang version 18.0.0 (clang-1800.0.50.1)
Target: arm64-apple-darwin26.0.0

Option B: Install macOS-Specific CLT Package

Step 1: Identify Required CLT Version

$ # macOS 26 requires CLT 18.0 or later
$ # Check Apple Developer Downloads for "Command Line Tools for Xcode 26"

Step 2: Direct CLT Installation

$ # Download CLT-18.0.pkg from Apple Developer Portal
$ sudo installer -pkg CLT-18.0.pkg -target /
$ xcode-select --switch /Library/Developer/CommandLineTools

Step 3: Verify Installation

$ xcodebuild -version
Xcode 26.0
Build version 26A123

Option C: Use OpenClaw Beta with CLT Workaround (If Available)

# Check for OpenClaw updates that patch CLT detection
$ openclaw update --channel beta
$ openclaw doctor --fix-clt

Test 1: Verify CLT Version Recognition

$ sw_vers -productVersion
26.0

$ xcodebuild -version
Xcode 26.0
Build version 26A123

$ clang --version | grep version
Apple clang version 18.0.0

Expected: Version 18.0+; no “does not support” warnings

Test 2: Verify SDK Availability

$ ls /Library/Developer/CommandLineTools/SDKs/
MacOSX.sdk
MacOSX26.0.sdk  # ← Must exist

$ xcrun --show-sdk-version
26.0

Expected: MacOSX26.0.sdk present and version matches

Test 3: Re-attempt Skill Installation

$ openclaw skills.install example-skill
⇄ res ✓ skills.install 2847ms
Skill 'example-skill' installed successfully.

Expected: Exit code 0; ✓ indicator in output

Test 4: Run OpenClaw Diagnostic

$ openclaw doctor
Checking system requirements...
✓ macOS version: 26.0
✓ Command Line Tools: 18.0
✓ Xcode: 26.0
✓ Skill installation: ready
All checks passed.

Expected: All items show ✓ status

• Xcode App Store Version: The App Store version of Xcode often lags behind beta releases. It may not include macOS 26 SDK support even after updating.
• Multiple CLT Installations: Running both standalone CLT and Xcode-bundled CLT causes conflicts. Use sudo rm -rf /Library/Developer/CommandLineTools when relying on Xcode-bundled tools.
• Beta Channel Mismatch: OpenClaw v2026.3.8-beta.1 may require specific CLT API calls that only newer CLT versions expose. Ensure both are from the same beta epoch.
• Entitlements on macOS 26: New security policies in macOS 26 may block skill installation processes. Check System Settings → Privacy & Security for any pending approvals.
• Rosetta 2 Conflicts: On Apple Silicon, ensure skill installation processes are arch-native. Mixed x86/arm invocations can trigger false CLT version mismatches.
• Beta Re-signing: If using a beta OpenClaw build with ad-hoc signing, macOS 26 may quarantine toolchain invocations. Run sudo xattr -cr /Applications/OpenClaw.app if installation fails silently.
• Network Proxy Interference: Some corporate proxies modify CLT package downloads, corrupting the installation. Verify checksum if downloads appear truncated.

• UNAVAILABLE exit code 1 (General) — Generic OpenClaw wrapper error when underlying CLI tool fails. Always check the errorMessage field for the actual cause.
• xcodebuild: error: SDK "MacOSX26.0" could not be located — Indicates Xcode is installed but CLT SDK directory is missing. Fix by reinstalling CLT or Xcode beta.
• clang: error: unsupported option '-stdlib=libc++' for target 'arm64-apple-darwin26' — Version skew between CLT and system libraries. Update to CLT 18+.
• Install failed (exit 127): command not found — PATH resolution failure; verify /usr/bin precedes /opt/homebrew/bin in $PATH.
• skills.install: connection timeout — Network-level issue unrelated to CLT but may surface during CLT package downloads. Check conn hash in error for retry endpoint.
• Historical CLT version mismatches:
  • macOS Sonoma (14.x) required CLT 16.0 minimum
  • macOS Ventura (13.x) required CLT 15.0 minimum
  • Pattern: Each major macOS release requires +2 major CLT versions