The following manifestations indicate the presence of this configuration persistence and auto-update bug:

1. Automatic Beta Version Installation

Companion App v2026.03.02 installed
→ Restart Application
→ Automatic update to v2026.03.09beta initiated
→ Compatibility warning displayed on next launch

2. Configuration Vanishing After Reinstall

# Before reinstall - configuration exists
$ ls -la ~/.openclaw/
-rw-r--r--  1 user  staff  1024 Mar  8 10:30 openclaw.json

# After reinstalling Companion App
$ ls -la ~/.openclaw/
ls: /Users/username/.openclaw/: No such file or directory

3. Gateway Compatibility Warning

┌─────────────────────────────────────────┐
│  ⚠️  Compatibility Warning              │
│                                         │
│  Gateway version 2026.03.02 is not      │
│  compatible with Companion App           │
│  version 2026.03.09beta                  │
└─────────────────────────────────────────┘

Primary Root Cause: Configuration Storage Location Conflict

The configuration loss occurs due to a fundamental architectural issue in how the Companion App manages its configuration storage:

1. Incorrect Configuration Storage Path: The Companion App stores user configurations in an ephemeral or app-bundle-relative path (~/Library/Application Support/OpenClaw/ or within the app container) instead of the standard user home directory location (~/.openclaw/).
2. Sandbox-Scoped Persistence: When the app is uninstalled via standard macOS removal (drag to Trash or Application Remove), all sandbox-scoped data including ~/Library/Application Support/OpenClaw/ and ~/Library/Preferences/ai.openclaw.companion.plist is deleted.
3. Gateway vs Companion App Scope Confusion: The gateway configurations (~/.openclaw/openclaw.json) are managed by the gateway binary, but the Companion App treats them as transient app-specific data.

Secondary Root Cause: Aggressive Auto-Update Behavior

┌────────────────────────────────────────────────────────────┐
│  Update Check Flow (Defective)                             │
├────────────────────────────────────────────────────────────┤
│                                                            │
│  App Launch → Check Update Server → Fetch Manifest         │
│     ↓                                                      │
│  If beta available AND auto-update enabled:                │
│     ↓                                                      │
│  Download beta → Replace current version → Launch new      │
│                                                            │
│  ❌ No version pinning check                               │
│  ❌ No user consent prompt                                 │
│  ❌ No compatibility verification                          │
│                                                            │
└────────────────────────────────────────────────────────────┘

The auto-updater lacks the following safeguards:

• Release Channel Validation: No distinction between stable and beta releases during auto-update checks
• Semantic Version Comparison: No parsing of version strings to determine stability status (beta suffix not recognized
• Compatibility Gate: No verification that the target update is compatible with the installed gateway version
• User Consent Checkpoint: No modal dialog or setting to control beta installations

Architectural Inconsistency

The issue stems from a separation of concerns violation:

• Gateway Binary: Correctly stores config at ~/.openclaw/openclaw.json
• Companion App: Stores a copy or sync of config in sandbox-scoped storage
• On Reinstall: Sandbox data erased → configuration loss despite gateway binary maintaining its own copy

Phase 1: Immediate Configuration Recovery

If you have already lost your configurations, attempt recovery before taking further steps:

# Check if gateway binary still has valid config
$ cat ~/.openclaw/openclaw.json

# If empty or missing, check Time Machine backup
$ tmutil list backups | grep -i openclaw

# Restore from Time Machine if available
$ tmutil restore "/Volumes/BackupDrive/Backups.backupdb/mac/2026-03-09-120000/OpenClaw" ~/.openclaw/

Phase 2: Disable Auto-Beta Updates

Step 1: Modify Companion App Update Preferences

# Navigate to app configuration directory
$ cd ~/Library/Application\ Support/OpenClaw/

# Edit or create preferences file
$ vim preferences.json

Add or modify the following configuration:

{
  "autoUpdate": {
    "enabled": false,
    "includeBeta": false,
    "checkInterval": 0
  },
  "releaseChannel": "stable"
}

Step 2: Disable via macOS System Preferences

# Lock the preferences file to prevent writes
$ chflags uchg ~/Library/Application\ Support/OpenClaw/preferences.json

# Or alternatively, remove write permissions
$ chmod 444 ~/Library/Application\ Support/OpenClaw/preferences.json

Step 3: Pin Gateway Version to Prevent Incompatibility

# Create version lock file
$ echo "2026.03.02" > ~/.openclaw/.version-lock

# Set immutable attribute on macOS (requires SIP consideration)
$ sudo chflags uchg ~/.openclaw/.version-lock

Phase 3: Reinstall Companion App with Configuration Preservation

Step 1: Backup Current Configuration

# Create timestamped backup
$ cp -r ~/.openclaw ~/.openclaw.backup.$(date +%Y%m%d%H%M%S)

# Verify backup integrity
$ shasum -a 256 ~/.openclaw/openclaw.json

Step 2: Remove Companion App Correctly

# Remove Companion App
$ rm -rf /Applications/OpenClaw\ Companion.app

# DO NOT remove gateway configuration directory
$ ls -la ~/.openclaw/  # Should still exist

# Remove only Companion App-specific sandbox data
$ rm -rf ~/Library/Application\ Support/OpenClaw/
$ rm -rf ~/Library/Preferences/ai.openclaw.companion.plist
$ rm -rf ~/Library/Saved\ Application\ State/ai.openclaw.companion.savedState

Step 3: Fresh Installation of Specific Version

# Download specific stable version directly
$ curl -fsSL "https://openclaw.ai/releases/2026.03.02/openclaw-companion-macos.dmg" \
  -o /tmp/openclaw-companion.dmg

# Mount and install
$ hdiutil attach /tmp/openclaw-companion.dmg
$ cp -r "/Volumes/OpenClaw Companion/OpenClaw Companion.app" /Applications/
$ hdiutil detach "/Volumes/OpenClaw Companion"

Step 4: Configure Companion App to Use Canonical Config Path

# Create symlink to ensure Companion App reads from gateway location
$ ln -sf ~/.openclaw/openclaw.json \
  ~/Library/Application\ Support/OpenClaw/openclaw.json

# Verify symlink
$ ls -la ~/Library/Application\ Support/OpenClaw/openclaw.json

Phase 4: Prevent Future Configuration Loss

Create a LaunchAgent to Maintain Configuration

# Create OpenClaw config guardian launch agent
$ cat > ~/Library/LaunchAgents/ai.openclaw.config-guardian.plist << 'EOF'




    Label
    ai.openclaw.config-guardian
    ProgramArguments
    
        /bin/bash
        -c
        
            CONFIG_DIR="$HOME/.openclaw"
            BACKUP_DIR="$HOME/.openclaw.backups"
            
            # Ensure backup directory exists
            mkdir -p "$BACKUP_DIR"
            
            # Keep last 5 backups
            ls -t "$BACKUP_DIR" | tail -n +6 | xargs -r rm -rf
            
            # Sync current config to backup
            rsync -av "$CONFIG_DIR/" "$BACKUP_DIR/$(date +%Y%m%d%H%M%S)/"
        
    
    StartInterval
    3600


EOF

# Load the guardian
$ launchctl load ~/Library/LaunchAgents/ai.openclaw.config-guardian.plist

After implementing the fix, verify system state with the following validation steps:

1. Configuration Persistence Verification

# Test 1: Confirm gateway config exists and is readable
$ test -f ~/.openclaw/openclaw.json && echo "✓ Gateway config exists" || echo "✗ Missing"

$ test -r ~/.openclaw/openclaw.json && echo "✓ Config is readable" || echo "✗ Permission denied"

# Test 2: Verify JSON validity
$ python3 -c "import json; json.load(open('$HOME/.openclaw/openclaw.json'))" \
  && echo "✓ Valid JSON" || echo "✗ Invalid JSON"

# Test 3: Check for expected configuration keys
$ grep -q '"models"' ~/.openclaw/openclaw.json && echo "✓ Models configured" || echo "✗ No models"
$ grep -q '"channels"' ~/.openclaw/openclaw.json && echo "✓ Channels configured" || echo "✗ No channels"
$ grep -q '"cronjobs"' ~/.openclaw/openclaw.json && echo "✓ Cronjobs configured" || echo "✗ No cronjobs"

2. Auto-Update Restriction Verification

# Test 1: Verify preferences file is locked
$ ls -lO ~/Library/Application\ Support/OpenClaw/preferences.json
# Expected: -rw-r--r-- 1 user staff restricted 256 Mar 10 09:00 preferences.json

# Test 2: Confirm auto-update disabled in preferences
$ cat ~/Library/Application\ Support/OpenClaw/preferences.json | python3 -c "
import json, sys
data = json.load(sys.stdin)
assert data.get('autoUpdate', {}).get('enabled') == False, 'Auto-update still enabled'
assert data.get('autoUpdate', {}).get('includeBeta') == False, 'Beta updates still allowed'
print('✓ Auto-update restrictions verified')
"

# Test 3: Attempt to trigger update check (should respect preferences)
$ open -a "OpenClaw Companion" --args --check-updates
# Expected: No download initiated, log shows skipped due to preferences

3. Version Pinning Verification

# Test: Confirm version lock exists
$ cat ~/.openclaw/.version-lock
# Expected output: 2026.03.02

# Test: Verify lock file is immutable (if SIP allows)
$ ls -lO ~/.openclaw/.version-lock
# Expected: -rw-r--r-- 1 user staff opaque 17 Mar 10 09:00 .version-lock

4. Config Guardian Verification

# Test: Verify launch agent is loaded
$ launchctl list | grep openclaw.config-guardian
# Expected: Entry showing loaded status

# Test: Check for recent backup
$ ls -la ~/.openclaw.backups/ | head -5
# Expected: Timestamped backup directories

# Test: Manual trigger of guardian
$ launchctl start ai.openclaw.config-guardian
$ sleep 2
$ ls -lt ~/.openclaw.backups/ | head -3
# Expected: New backup directory with current timestamp

5. Companion App Functional Verification

# Launch app and verify no compatibility warnings
$ open -a "OpenClaw Companion"
# Expected: App launches without warning dialog

# Check app logs for update-related errors
$ cat ~/Library/Logs/OpenClaw/companion.log | grep -i "update\|beta\|compatibility"
# Expected: No unauthorized beta downloads logged

Environment-Specific Traps

• macOS System Integrity Protection (SIP): Attempting to set chflags uchg on files in /Applications will fail silently. Always operate on user-space directories for locking.

  # FAILS - SIP protection
  $ sudo chflags uchg /Applications/OpenClaw\ Companion.app/Contents/Info.plist
  WORKS - User space
  $ chflags uchg ~/Library/Application\ Support/OpenClaw/preferences.json
  

• Time Machine Local Snapshots: On systems where Time Machine uses local snapshots (APFS), tmutil restore may fail with permission errors. Use tmutil list backups first to identify snapshot availability.
• Home Directory Encryption: If FileVault is enabled and the user logs out before checking ~/.openclaw/, the directory may appear empty due to encrypted volume not being mounted.

  # Verify directory is accessible
  $ cd ~/.openclaw && ls -la
  # If permission denied, volume may be locked
  

• Companion App Sandbox Restrictions: The macOS sandbox prevents the app from directly reading ~/.openclaw/. The symlink approach may fail; verify with:

  # Test Companion App access to symlinked path
  $ open -a "OpenClaw Companion" --args --verify-config-path
  

Configuration Missteps

• Incorrect JSON Syntax: A trailing comma in the preferences JSON will cause silent failure:

  # WRONG
  {
    "autoUpdate": {
      "enabled": false,
    },  // ← trailing comma causes parse failure
  }
  CORRECT
  {
  “autoUpdate”: {
  “enabled”: false
  }
  }
  

• Race Condition on LaunchAgent: The guardian may try to back up before the directory is fully mounted. Add a wait condition:

  # Add to guardian script
  sleep 5  # Wait for filesystem stabilization
  

• Version String Parsing Ambiguity: Version 2026.03.09beta may be parsed as greater than 2026.03.02 by naive string comparison due to length. Always use semantic version parsing.

Edge Cases

• Concurrent Gateway and Companion Access: If the gateway binary modifies openclaw.json while the Companion App reads it, partial writes may corrupt the JSON. Implement file locking:

  # Use flock for atomic access
  $ flock ~/.openclaw/openclaw.json -c "cat ~/.openclaw/openclaw.json"
  

• Migration from Old Config Format: If upgrading from pre-2026.03 versions, the JSON schema may differ. Validate migration:

  $ openclaw gateway migrate --dry-run --config ~/.openclaw/openclaw.json
  

• Multiple Companion App Instances: Running both stable and beta versions simultaneously causes port conflicts and unpredictable config synchronization behavior.

• ERR_COMPAT_GATEWAY_MISMATCH: Gateway version incompatible with Companion App version. Occurs when auto-update pulls a beta that targets a newer gateway API.
• ERR_CONFIG_SANDBOX_VIOLATION: Configuration file outside allowed sandbox scope. Companion App cannot access ~/.openclaw/ due to macOS sandbox entitlements.
• ERR_AUTO_UPDATE_NO_CONSENT: Beta version auto-downloaded without user opt-in. Logged when includeBeta preference is not explicitly set to false.
• ERR_CONFIG_JSON_PARSE: Corrupted or malformed openclaw.json. Often caused by interrupted writes during concurrent gateway/companion access.
• WARN_BETA_INSTALLED_STABLE_REQUIRED: Warning emitted when beta companion detects stable-only gateway mode. Prevents feature compatibility issues.
• Issue #1452: Configuration not persisting across app reinstalls on macOS (duplicate report)
• Issue #1398: Auto-update installing beta versions without opt-in (similar report)
• Issue #1311: Companion App storing config in ephemeral storage instead of user directory (architecture discussion)