OpenClaw OrbStack

One-click OpenClaw deployment on macOS via OrbStack VM.

What is this?

OpenClaw is an open-source personal AI assistant you run on your own devices.

This project (openclaw-orbstack) is a deployment tool — it automates OpenClaw installation and OrbStack VM setup on macOS. It uses the prebuilt npm package by default (with source build as fallback). The architecture below (Gateway process + Docker sandboxes) is OpenClaw's official design, not something we invented. We simply package it into a one-click installer with Mac convenience commands.

Architecture

☁️  Cloud AI (Anthropic/OpenAI/Google)  ← AI brain runs HERE
     ↑ API calls
     │
Mac ─┼─────────────────────────────────────────────────
     │
└── OrbStack
    └── Ubuntu VM (openclaw-vm)
        │
        ├── Gateway process (orchestrator, NOT in Docker)
        │   - Receives chat messages
        │   - Calls cloud AI APIs
        │   - Dispatches tool execution to sandboxes
        │
        └── Docker (two sandbox containers)
            ├── sandbox-common (code execution)  ← sandbox.docker config
            └── sandbox-browser (browser)        ← sandbox.browser config

Key Concepts:

• ☁️ AI brain runs in the cloud (Anthropic/OpenAI/Google servers)
• 🔧 Sandboxes are AI's "hands" — they only execute tools, not run AI
• 📦 Only TWO sandboxes: code execution + browser

Benefits:

• ✅ Follows OpenClaw's official recommended architecture
• ✅ Gateway can properly manage sandbox containers
• ✅ VM isolation layer protects your Mac

Prerequisites

• macOS 12.3+
• OrbStack installed

Installation

git clone https://github.com/aaajiao/openclaw-orbstack.git
cd openclaw-orbstack
bash openclaw-orbstack-setup.sh

The script starts with a language selection prompt (English / 中文), then automatically: Creates VM → Installs Docker & Node.js → Installs OpenClaw (via npm) → Builds sandbox images → Runs setup wizard → Starts service

To skip the prompt, set the language via environment variable:

OPENCLAW_LANG=en bash openclaw-orbstack-setup.sh      # English
OPENCLAW_LANG=zh-CN bash openclaw-orbstack-setup.sh   # Chinese

Access

Web Console: http://openclaw-vm.orb.local:18789

Quick Start

# PATH is auto-configured during install — just open a new terminal window

# Check service status
openclaw-status

# View logs
openclaw-logs

# Telegram Bot pairing
openclaw-telegram add <bot_token>      # Add Bot
openclaw-telegram approve <code>       # Approve with code

# WhatsApp login
openclaw-whatsapp

# Edit config
openclaw-config edit

# Use official CLI (150+ commands)
openclaw --help
openclaw status
openclaw channels list
openclaw doctor

Mac Commands

Command	Function
openclaw	CLI passthrough (all official commands)
openclaw-telegram	Telegram management (add/approve)
openclaw-whatsapp	WhatsApp login
openclaw-config	Config management
openclaw-status	Service status
openclaw-logs	Live logs
openclaw-restart	Restart service
openclaw-stop/start	Stop/start service
openclaw-shell	Enter VM terminal
openclaw-doctor	Run diagnostics
openclaw-update	Update app (--sandbox rebuild images, --force force rebuild)
openclaw-sandbox-rebuild	Rebuild sandbox Docker images

Full command reference: docs/commands.md

Configuration

Config file: ~/.openclaw/openclaw.json (inside VM)

openclaw-config edit     # Edit
openclaw-config show     # View
openclaw-config backup   # Backup

Detailed configuration guide: docs/configuration-guide.md

Troubleshooting

openclaw-status        # Service status
openclaw-logs          # View logs
openclaw doctor        # Run diagnostics
openclaw-shell         # Enter VM for debugging

Full troubleshooting guide: docs/troubleshooting.md

Upgrading Existing Installations

openclaw-update

This auto-detects and repairs outdated configurations (e.g. migrating from system-level to user-level service).

Common Issues

Issue	Solution
Bonjour hostname conflict	Re-run setup script or manually add env var
Port 18789 in use	openclaw-restart or openclaw-update
Memory directory error	mkdir -p ~/.openclaw/memory
Memory search not working	Add OpenAI/Google key to agent auth-profiles.json

Memory Directory Issue

If you see EISDIR: illegal operation on a directory error, create the memory index directory manually:

openclaw-shell
mkdir -p ~/.openclaw/memory
chmod 755 ~/.openclaw/memory
exit
openclaw-restart

Backup & Restore

orb export openclaw-vm ~/Desktop/backup.tar.zst   # Full VM snapshot
orb import -n openclaw-vm ~/Desktop/backup.tar.zst # Restore from snapshot

See docs/troubleshooting.md for details.

Documentation

Document	Content
docs/README.zh-CN.md	Chinese documentation
docs/commands.md	CLI command reference
docs/architecture.md	Architecture details
docs/configuration-guide.md	Configuration guide
docs/multi-agent.md	Multi-agent setup (routing, multi-bot, sandbox isolation)
docs/troubleshooting.md	Troubleshooting guide
docs/sandbox.md	Sandbox security
docs/skills.md	Skills guide
docs/voice-tts.md	Voice features
docs/development.md	Development guide

License

MIT