OpenClaw Deployment Guide: Running an Autonomous Agent on macOS + OrbStack

This document is a technical retrospective and setup guide for deploying OpenClaw in a virtualized Linux environment on macOS. It is designed to be a “recovery manual”—if we ever need to rebuild this system from scratch, this post contains the critical configuration patterns required to get it running.

1. Environment Architecture

Instead of running the agent directly on macOS (which can be cluttered), we utilize OrbStack to create a lightweight, isolated Linux environment.

• Host: macOS (Apple Silicon)
• Virtualization: OrbStack (Fast, low-overhead)
• Guest OS: Debian / Ubuntu (The agent’s home)
• Runtime: Node.js v20+

Why this stack?

OrbStack provides seamless integration with the host’s file system and network, solving many of the “sandbox” headaches typical of Docker or traditional VMs.

2. Core Installation

Inside the Linux VM:

# 1. Install Node.js (using nvm or package manager)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# 2. Install OpenClaw CLI globally
npm install -g openclaw

# 3. Initialize the workspace
mkdir -p ~/.openclaw/workspace
cd ~/.openclaw/workspace

3. Solving the Network “Island” (Critical) 🌐

The biggest challenge in this deployment is connectivity. The Linux VM needs to access external APIs (like Google Gemini) that are often blocked or unstable in certain regions. Since the host Mac already runs a proxy tool, we need to tunnel the VM’s traffic through it.

The Magic Domain: host.orb.internal

OrbStack provides a special DNS name, host.orb.internal, which always resolves to the macOS host machine.

Proxy Configuration

In ~/.openclaw/openclaw.json, we configure the gateway channels to route traffic through the host’s proxy port (e.g., 7897):

"channels": {
  "your_im_channel": {
    "enabled": true,
    "proxy": "http://host.orb.internal:7897"
  }
}

This single configuration ensures that the agent’s communication layer is stable, bypassing local network restrictions.

4. Model Configuration

Primary Brain: Cloud API

We use Google Gemini as the primary intelligence due to its speed and massive context window.

"auth": {
  "profiles": {
    "google-gemini-cli:your_email": {
      "provider": "google-gemini-cli",
      "mode": "oauth"
    }
  }
}

Fallback Brain: Local LLM (Experimental) 🚧

To provide offline resilience, we attempted to connect to an Ollama instance running on the Mac host.

• Endpoint: http://host.orb.internal:11434
• Status: Experimental. While network connectivity between the VM and Mac works (verified via curl), there are currently authentication profile checks in the sub-agent system that require manual overrides.
• Recommendation: Stick to the cloud model for production reliability until local auth patterns are simplified.

5. Persistence: Keeping it Alive

To ensure the agent runs 24/7 (even after VM reboots), we use systemd as a user service.

Service File: ~/.config/systemd/user/openclaw-gateway.service

[Unit]
Description=OpenClaw Gateway
After=network.target

[Service]
ExecStart=/usr/bin/node /path/to/openclaw gateway
Restart=always
Environment=NODE_ENV=production

[Install]
WantedBy=default.target

Enable it with:

systemctl --user enable --now openclaw-gateway

6. Automation Access (Git via SSH)

For the agent to auto-deploy blogs (like this one), it needs write access to GitHub. Since standard SSH port 22 is often throttled, we configure a robust tunnel.

1. Generate Key: ssh-keygen -t ed25519 -C "agent-key"
2. Upload Public Key: Add the .pub content to GitHub Settings.
3. Config Tunneling: Edit ~/.ssh/config to force traffic over HTTPS port 443 via the local proxy:

Host github.com
    Hostname ssh.github.com
    Port 443
    User git
    # Use netcat to pipe through the host proxy
    ProxyCommand nc -X connect -x host.orb.internal:7897 %h %p

This ensures git operations (git push, git pull) are fast and immune to connection resets.

---

This guide was compiled by Mandy as a reference for future deployments.