Install OpenClaw on macOS

macOS is one of the best-supported platforms for OpenClaw, offering native performance, seamless integration, and optional companion app features that enhance the AI assistant experience. Whether you're running an Apple Silicon Mac with M-series chips or an Intel-based Mac, OpenClaw provides optimized binaries for both architectures.

The macOS experience includes features not available on other platforms: the optional menu bar companion app, Voice Wake for hands-free activation, push-to-talk functionality, and deep system integration through macOS permissions. These capabilities transform OpenClaw from a chat assistant into a system-wide AI companion.

macOS Advantages

Running OpenClaw on macOS offers distinct advantages. The launchd daemon system provides robust service management with automatic restart capabilities. Apple's security model, while requiring permission grants, ensures your assistant operates safely. Integration with Keychain enables secure API key storage. The companion app adds voice features and quick access from the menu bar.

macOS users also benefit from excellent developer tools and shell environments. Terminal, iTerm2, or Warp combined with zsh provide a productive environment for OpenClaw configuration and customization. The Unix underpinnings mean all standard Linux documentation and tools apply with minimal adaptation.

Apple Silicon Optimization

OpenClaw and Node.js run natively on Apple Silicon, taking full advantage of M-series chip efficiency and performance. The ARM64 architecture support means no Rosetta 2 translation overhead. Energy efficiency is excellent, with OpenClaw consuming minimal power during idle periods, making it suitable for laptop use without significant battery impact.

OpenClaw can be installed on macOS through several methods. This section covers the recommended approaches: Homebrew for the simplest experience and npm for more control.

Method 1: Homebrew (Recommended)

Homebrew provides the simplest installation path for macOS users. If you don't have Homebrew installed, install it first using the official installer script. Homebrew handles dependencies and updates automatically, making maintenance straightforward.

With Homebrew installed, add the OpenClaw tap and install. The formula installs Node.js if needed and sets up OpenClaw with appropriate macOS configurations. After installation, the openclaw command is available in your terminal.

Method 2: npm Global Install

If you prefer managing Node.js separately or already have a Node.js development environment, install OpenClaw via npm. First, ensure Node.js 22 or later is installed. Then install OpenClaw globally. This approach gives you more control over Node.js version management, especially useful if you use nvm or similar tools.

Method 3: From Source

Developers or users wanting the latest features can build from source. Clone the repository, install dependencies with pnpm, and build the project. This approach requires more setup but provides access to development builds and the ability to modify OpenClaw.

Verifying Installation

After installation via any method, verify OpenClaw is properly installed by checking the version. The openclaw --version command should display the installed version number. If the command isn't found, ensure your PATH includes the installation directory (Homebrew's /opt/homebrew/bin or npm's global bin directory).

The onboarding wizard configures OpenClaw for your system, creating necessary directories, setting up the daemon, and walking you through initial configuration.

Starting Onboarding

Run the onboarding command with the daemon installation flag. The wizard is interactive, guiding you through each step. On macOS, it uses launchd for the daemon, which is the native macOS service management system.

Daemon Configuration

The onboarding wizard asks if you want to install the Gateway daemon. Answer yes for always-on operation. The daemon installs as a launchd user agent at ~/Library/LaunchAgents/ai.openclaw.gateway.plist. This ensures OpenClaw starts automatically when you log in and restarts if it crashes.

API Key Setup

During onboarding, configure your AI model provider. You can enter API keys interactively or set them as environment variables. For macOS, consider using Keychain for secure storage, though environment variables in your shell profile work for most users.

The recommended configuration uses Anthropic's Claude models for best results. Enter your Anthropic API key when prompted, or configure environment variables in your .zshrc or .bash_profile to persist across sessions.

Channel Configuration

The wizard offers to configure messaging channels. You can skip this initially and add channels later through the web interface or CLI commands. Common first channels include WhatsApp, Telegram, or Discord, each with their own authentication process.

Completing Setup

After onboarding completes, the daemon starts automatically. Verify operation by checking the Gateway status. Access the WebChat interface at http://localhost:18789 to test your installation with a simple message.

OpenClaw offers an optional macOS companion app that adds system-level features including Voice Wake, push-to-talk, menu bar access, and enhanced notifications. This section covers installation and configuration of the companion app.

Installing the Companion App

Download the companion app from the OpenClaw website or install via Homebrew Cask. The app is a separate download from the CLI tools, providing a native macOS experience with menu bar integration and system permissions management.

After downloading, move the app to your Applications folder. On first launch, macOS may display a security warning for apps from outside the App Store. Right-click the app and select Open to bypass Gatekeeper, or allow it in System Settings > Privacy & Security.

Required Permissions

The companion app requests several macOS permissions for full functionality. Microphone access enables Voice Wake and push-to-talk features. Accessibility access allows global keyboard shortcuts. Screen recording enables certain AI-assisted screen interactions if configured.

Grant permissions when prompted, or configure them later in System Settings > Privacy & Security. Voice features won't work without microphone access. Consider which features you need and grant only necessary permissions.

Voice Wake Configuration

Voice Wake enables hands-free activation of your OpenClaw assistant. Configure your wake phrase in the companion app preferences. The default "Hey Claw" works well, but custom phrases are supported. Voice Wake runs locally for privacy, only sending audio to AI services after wake phrase detection.

Menu Bar Features

The menu bar icon provides quick access to OpenClaw status, recent conversations, and common actions. Click to open the chat interface, view connection status, or access preferences. The icon color indicates status: normal operation, disconnected, or processing.

Keyboard Shortcuts

Configure global keyboard shortcuts for common actions: activate assistant, toggle listening mode, or open preferences. Default shortcuts use Command combinations that don't conflict with common applications. Customize in the companion app preferences.

The Gateway daemon runs OpenClaw as a background service. Understanding daemon management helps with troubleshooting and maintenance.

launchd Basics

macOS uses launchd for service management. The OpenClaw daemon installs as a user agent, meaning it runs in your user context and starts when you log in. The configuration file at ~/Library/LaunchAgents/ai.openclaw.gateway.plist defines how and when the daemon runs.

Checking Daemon Status

Use the OpenClaw CLI to check daemon status. The gateway status command reports whether the daemon is running and its current state. For more detail, use launchctl to list and examine the service directly.

Starting and Stopping

Control the daemon with openclaw gateway start and openclaw gateway stop. These commands interact with launchd appropriately. After configuration changes, restart the daemon with openclaw gateway restart to apply new settings.

Viewing Logs

Access daemon logs with openclaw gateway logs or by examining the log files directly. The daemon logs to ~/Library/Logs/OpenClaw/ by default. Console.app can also display these logs with filtering for easier reading.

Manual launchctl Commands

For advanced management, use launchctl directly. Load the agent with launchctl load, unload with launchctl unload. These commands affect immediate state; the RunAtLoad property in the plist controls automatic startup at login.

Troubleshooting Daemon Issues

If the daemon won't start, check for configuration errors with launchctl list | grep openclaw and examine the plist file for syntax issues. Verify the openclaw binary exists at the path specified in the plist. System log messages provide additional diagnostic information for startup failures.

OpenClaw configuration on macOS follows the standard pattern with some platform-specific considerations. This section covers macOS-relevant configuration options.

Configuration File Location

The main configuration file lives at ~/.openclaw/openclaw.json. This hidden directory in your home folder contains all OpenClaw settings, workspace files, and data. Edit the configuration with any text editor; changes require a daemon restart to take effect.

Environment Variables

Set environment variables in your shell profile (.zshrc for the default macOS shell). API keys and other sensitive values should be set as environment variables rather than stored in configuration files. The daemon inherits environment variables from your login session when using launchd.

For launchd to see environment variables, they must be set before the daemon loads or defined in the launchd plist directly. The safest approach sets them in .zshrc and loads them with launchctl setenv for immediate effect without logout.

Keychain Integration

For enhanced security, store API keys in macOS Keychain and retrieve them in your shell profile. This prevents keys from appearing in plain text files. Use the security command to add and retrieve Keychain items in shell scripts.

Tailscale Configuration

OpenClaw includes built-in Tailscale support for remote access. If Tailscale is installed on your Mac, configure OpenClaw to use it through the gateway.tailscale settings. Serve mode exposes OpenClaw to your tailnet; Funnel mode provides public HTTPS access with authentication.

Companion App Settings

If using the companion app, additional settings exist in its preferences. These include Voice Wake sensitivity, wake phrase, keyboard shortcuts, and notification preferences. Companion app settings are separate from the main openclaw.json configuration.

macOS provides robust security features that affect how OpenClaw operates. Understanding these helps with proper configuration and troubleshooting.

Gatekeeper and Code Signing

macOS Gatekeeper may warn about OpenClaw components not from the App Store. Homebrew installations are typically signed; manual downloads may require explicit approval in System Settings > Privacy & Security. Never disable Gatekeeper entirely; instead, allow specific apps as needed.

Permission Requests

The companion app requests permissions for microphone, accessibility, and potentially screen recording. Each permission has a specific purpose: microphone for voice features, accessibility for global shortcuts, screen recording for screen-aware AI features. Review and grant only permissions you need.

Permissions can be managed in System Settings > Privacy & Security. If a feature stops working, verify the relevant permission is still granted, as macOS may revoke permissions after updates or security changes.

Firewall Configuration

The macOS firewall may prompt about OpenClaw accepting incoming connections. Allow this for WebChat access from other devices on your network. For local-only use, you can deny external connections while maintaining localhost access.

FileVault Considerations

If using FileVault encryption, the daemon starts only after you log in and decrypt the disk. This is normal behavior; for always-on operation before login, consider cloud deployment or a non-encrypted separate installation (not recommended for sensitive data).

App Sandbox Limitations

If running OpenClaw inside an app sandbox (unusual for CLI tools), some operations may be restricted. The standard CLI installation runs outside the sandbox with full filesystem and network access. Be aware of this when integrating with sandboxed applications.

This section addresses common issues specific to macOS OpenClaw installations.

Command Not Found

If openclaw isn't found after installation, the installation directory isn't in your PATH. For Homebrew installations, ensure /opt/homebrew/bin (Apple Silicon) or /usr/local/bin (Intel) is in your PATH. For npm installations, add npm's global bin directory. Check your .zshrc or .bash_profile for PATH configuration.

Daemon Won't Start After Update

macOS may revoke permissions after software updates. If the daemon stops working after updating OpenClaw or macOS, check System Settings > Privacy & Security for any permission revocations. Re-grant necessary permissions and restart the daemon.

Voice Wake Not Responding

Voice Wake requires microphone permission granted to the companion app. Verify in System Settings > Privacy & Security > Microphone. Also check Voice Wake is enabled in companion app preferences and the wake phrase is correctly configured. Test microphone access with Voice Memos or another app first.

High CPU Usage

Unusual CPU usage typically indicates an issue with conversation history, channel connections, or a skill. Check openclaw doctor for diagnostics. Restarting the daemon clears accumulated state. If the issue persists, review recent configuration changes or installed skills.

Network Issues

Connection failures to messaging platforms or AI APIs may indicate network issues or macOS firewall blocking. Test connectivity with curl to relevant endpoints. Check the firewall for blocked applications. Corporate networks may require proxy configuration.

Cannot Access WebChat

If localhost:18789 doesn't load, verify the daemon is running with openclaw gateway status. Check that no other application is using port 18789. The daemon must be fully started before WebChat becomes accessible; wait a few seconds after starting.