deployment

How to Deploy Openclaw on macOS - Complete Setup Guide

deployment guide macos openclaw setup
Image
Karinov Webmaster
Table of contents: [Show]

Quick Start

The fastest way to install Openclaw on macOS is using the official installer script. This method automatically installs Node.js 22+ (via Homebrew if missing), installs the Openclaw CLI globally, and starts the onboarding wizard.

Step 1: Run the Installer

Open your terminal and run:

curl -fsSL https://Openclaw.ai/install.sh | bash

Step 2: Configure with Onboarding Wizard

Run the onboarding wizard to set up your model provider, workspace, and channels:

Openclaw onboard --install-daemon

The --install-daemon flag configures the Gateway to run as a macOS launchd background service (LaunchAgent ai.Openclaw.gateway), ensuring it restarts automatically and survives logouts.

Step 3: Open the Dashboard

Launch the WebChat interface in your browser:

Openclaw dashboard

This opens the Control UI where you can start chatting and managing your Gateway.

What the Installer Does

The official installer handles several setup tasks automatically:

  • Detects your macOS version and architecture
  • Installs Node.js 22+ if not present (via Homebrew)
  • Installs the Openclaw CLI globally
  • Guides you through model provider setup (Anthropic, OpenAI, etc.)
  • Configures workspace directories
  • Sets up the launchd service for background operation

For more deployment options, check out our guide on Fly.io Deployment. If you are new to Openclaw, you might also want to read about Elevated Mode for advanced permissions.

Working Example

After installation, test your setup by sending a message to your agent:

Request:

{ "message": "Hello, are you running?" }

Response:

{ "status": "ok", "reply": "Yes, I'm running on macOS via launchd!" }

Troubleshooting

  • Homebrew not found: Install Homebrew first with /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
  • Permission denied: Ensure your user has admin privileges for installing global packages
  • Service not starting: Check launchd logs with launchctl list | grep Openclaw
  • Port conflicts: The default Gateway port is 18789; ensure it's not in use by another application

Best Practices

  • Keep the launchd service enabled for 24/7 operation
  • Use ~/.Openclaw/Openclaw.json for persistent configuration
  • Store API keys in environment variables or the secure keychain
  • Regularly update Openclaw with openclaw update

Openclaw on macOS

Tags: