A unified, interactive setup script for OpenClaw — the open-source personal AI assistant. One script handles native macOS + Docker deployments, with presets for personal assistants, developers, and autonomous agents.
Built for Apple Silicon (M4/M3/M2/M1) but works on any macOS or Linux system.
git clone https://github.com/ckithika/openclaw-setup.git
cd openclaw-setup
./setup.sh./setup.sh # Fresh interactive setup
./setup.sh --reconfigure # Modify an existing instance
./setup.sh --version # Show version (v3.0.0)
./setup.sh --help # Show help
./agent-monitor.sh # Monitor all running agents (CPU, RAM, status)
./agent-monitor.sh --watch # Live dashboard, refreshes every 30s
./agent-security-audit.sh # Run security audit on all agentsThe setup starts by asking you to choose a preset. Each preset configures features, workspace files, autonomy level, and defaults tailored to your use case.
| Preset | Best for | What's enabled |
|---|---|---|
| personal-assistant | Non-technical users who want a smart daily assistant | Messaging, email, calendar, web search, memory. No coding tools, shell access, or CLI prompts. |
| developer | Software engineers and technical users | Full coding environment: shell, file access, sandbox, Claude Code, GitHub backup. |
| autonomous-agent | Autonomous SaaS agents that run a product | Everything: code, social media, email, browser, cron jobs, all skills, approval gates. |
| custom | Power users who want full control | Start from defaults and toggle each feature manually. |
After selecting a preset, you can optionally customize individual features.
The setup wizard uses a modern terminal UI:
- Single-select lists (deployment mode, model provider, presets, autonomy level): navigate with arrow keys, confirm with Enter
- Multi-select checkboxes (features, channels): navigate with arrow keys, toggle with Space, confirm with Enter
- All interactive widgets fall back to numbered/y/N input when running non-interactively (piped input, CI)
Native mode runs OpenClaw directly on your Mac with full system access (iMessage, GPU, filesystem, Voice/TTS).
| Requirement | Install |
|---|---|
| macOS (Apple Silicon recommended) | - |
| Ollama | brew install ollama |
| Node.js 18+ | brew install node |
| Docker / OrbStack | brew install --cask orbstack (for sandbox feature) |
| GitHub CLI | brew install gh (optional, for GitHub backup) |
| Python 3 | Pre-installed on macOS (for Claude sync tools) |
jq is auto-installed via Homebrew if missing.
- Run the setup script and select native mode.
- Name your instance (e.g.,
personal) — config goes to~/.openclaw/. - Choose a preset — optionally customize features with the checkbox UI.
- Select channels — multi-select checkbox (WhatsApp, Telegram, Discord, Slack, Signal, iMessage). Credential prompts for selected channels only. Voice note transcription offered if any audio-capable channel selected.
- Select model provider — 7 options with credential prompting.
- Configure persona — agent name, personality, emoji, backstory, your name/timezone/role, autonomy level, communication style. All flow into workspace files.
- Optional: Google Workspace, Obsidian vault, GitHub backup.
- Start OpenClaw:
openclaw gateway --force
~/.openclaw/
├── openclaw.json # Main config
├── credentials/ # API keys (chmod 700)
├── workspace/
│ ├── SOUL.md # Mission, personality, autonomy gates
│ ├── IDENTITY.md # Name, type, vibe, emoji, backstory
│ ├── USER.md # Your name, timezone, role
│ ├── AGENTS.md # Operating rules, voice transcription
│ ├── TOOLS.md # Available CLIs, voice note instructions
│ └── HEARTBEAT.md # Periodic checks (preset-specific)
└── vault-sync.sh # Git auto-sync (if backup enabled)
Docker mode runs OpenClaw in an isolated container. Best for work agents, multi-account setups, or autonomous agents. Containers use agent-<name> naming.
| Requirement | Install |
|---|---|
| macOS or Linux | - |
| Docker / OrbStack | brew install --cask orbstack |
| Ollama | brew install ollama (runs on host, shared by all agents) |
- Run the setup script and select Docker mode.
- Name your instance (e.g.,
seekrjobs,tailhq) — container namedagent-<name>. - Set base directory (default:
~/openclaw-instances). - Choose a preset — Docker hides irrelevant options (sandbox auto-enabled, voice/Claude sync hidden).
- Select CLI tools (skipped for personal-assistant): gh, doctl, supabase, gog, xurl. Generates custom Dockerfile.
- Select channels — multi-select. WhatsApp prompts for your phone number (restricted to self-chat via allowlist). Voice note transcription offered with local (whisper-cpp, free) or cloud (OpenAI API) options.
- Configure persona — full identity setup with autonomy level:
- supervised: ask before most actions
- semi-autonomous: act freely on internal, ask for external
- autonomous: act freely on everything, only ask for irreversible/financial
- Network mode: host (recommended for OrbStack) or bridged.
- Optional sidecars: Telegram watchdog, Tailscale, daily backups.
- Optional: Obsidian vault — use existing shared vault (preserves files, appends tag) or create new.
- Optional: GitHub backup — auto-detects existing
.git, skips redundant setup. - Start:
cd ~/openclaw-instances/<name> && docker compose up -d
# Check logs
docker compose logs -f agent-<name>
# Pair WhatsApp
docker compose exec agent-<name> openclaw channels login --channel whatsapp
# Auth CLIs
docker exec -it agent-<name> gh auth login
docker exec -it agent-<name> doctl auth init
docker exec -it agent-<name> supabase login- Create a project in Google Cloud Console
- Enable APIs: Gmail, Calendar, Drive, Sheets, Docs, People
- Create OAuth consent screen:
- Google Workspace (
you@company.com): select Internal - Personal Gmail (
you@gmail.com): select External, add your email under Test users
- Google Workspace (
- Create OAuth client ID (Desktop app), download JSON
- Auth:
cp ~/Downloads/client_secret_*.json ~/openclaw-instances/<name>/google-credentials/credentials.json docker exec -it agent-<name> gog auth credentials /home/node/.config/gogcli/credentials.json docker exec -it agent-<name> gog auth add you@example.com --services gmail,calendar,drive,contacts,docs,sheets --manual
- Open the URL, authorize, copy the redirect URL, paste back
- Add keyring passphrase to
.env:echo 'GOG_PASSPHRASE=xxx' >> .env
~/openclaw-instances/<name>/
├── docker-compose.yml # Docker Compose (with sidecars)
├── Dockerfile # Custom image (browser, CLIs, whisper-cpp)
├── .env # Environment variables
├── gitconfig # Safe copy from host
├── config/
│ ├── openclaw.json # Main config
│ ├── credentials/ # API keys (chmod 700)
│ ├── cron/jobs.json # Scheduled tasks
│ └── workspace/
│ ├── SOUL.md # Mission, personality, autonomy gates
│ ├── IDENTITY.md # Name, type, vibe, emoji, backstory, autonomy
│ ├── USER.md # Your name, timezone, role
│ ├── AGENTS.md # Operating rules
│ ├── TOOLS.md # CLIs, voice transcription instructions
│ └── HEARTBEAT.md # Periodic checks
├── workspace/ # Agent workspace (mounted)
├── chrome-profile/ # Persistent browser sessions
├── google-credentials/ # Google OAuth tokens
└── backups/ # Daily backups
OrbStack on macOS: Node.js inside containers may fail to reach external APIs (e.g., Telegram) when using bridged networking. Use host networking (network_mode: host) to avoid this.
When using host networking:
- Gateway listens directly on the host at the configured port
OLLAMA_HOSTautomatically set tohttp://localhost:11434- Tailscale sidecar not needed
- Healthcheck port matches the configured gateway port
Multiple agents can share a single Obsidian vault:
- Answer "Do you have an existing Obsidian vault?" with Yes
- Workspace files (SOUL.md, IDENTITY.md, etc.) are not overwritten — each agent keeps its own
- Taxonomy: existing
_taxonomy.mdpreserved, new#project/<agent-name>tag appended - GitHub backup: existing
.gitauto-detected, just pulls latest
The persona step collects detailed identity and behavior configuration:
| Section | Questions |
|---|---|
| Identity | Agent name, personality/vibe, signature emoji, one-line backstory |
| About You | Your name, timezone, role/title, additional notes |
| Mission | What the agent should do (preset-specific default) |
| Communication | Response length (concise/balanced/detailed), tone (professional/friendly/direct) |
| Autonomy Level | supervised / semi-autonomous / autonomous |
| Preset-specific | Product name/URL/description (autonomous), languages/repo (developer) |
| Level | GREEN (do freely) | YELLOW (ask first) | RED (never) |
|---|---|---|---|
| supervised | Read, research, draft | Send messages, commit code, modify config | Delete data, force-push, spend money |
| semi-autonomous | Read, research, draft, commit code, create branches, respond to chat | Publish posts, send emails, open PRs, merge to main | Delete data, force-push, spend money |
| autonomous | All of the above + publish posts, send routine emails, install deps | Merge to main, deploy, pricing changes | Delete data, force-push, spend money |
All settings flow into SOUL.md with clearly defined GREEN/YELLOW/RED gates.
When a voice note arrives on WhatsApp, Telegram, or Discord, the agent automatically transcribes it before responding.
| Method | Cost | Speed | Setup |
|---|---|---|---|
| Local (whisper-cpp) | Free | ~500ms on Apple Silicon | brew install whisper-cpp ffmpeg (native) or auto-installed in Docker |
| Cloud (OpenAI Whisper API) | $0.006/min | ~1-2s | Requires OPENAI_API_KEY |
The agent's TOOLS.md contains mandatory instructions to execute ffmpeg + whisper-cli whenever <media:audio> appears in a message.
./agent-monitor.sh # One-shot status
./agent-monitor.sh --watch # Live dashboard (30s refresh)Shows all running agents with CPU, memory, status, color-coded by usage. Includes capacity estimates for adding more agents.
| Time | Job | Log |
|---|---|---|
| 4:00 AM | Browser restart (Chromium memory cleanup) | /tmp/browser-restart.log |
| 5:00 AM | Security audit (7-point check) | /tmp/agent-security-audit.log |
Install both crons:
crontab -e
0 4 * * * /path/to/browser-restart-cron.sh >> /tmp/browser-restart.log 2>&1
0 5 * * * /path/to/agent-security-audit.sh >> /tmp/agent-security-audit.log 2>&1The daily audit checks 7 areas across all running agents:
- Container health — running, healthy, crash-looping
- Credential permissions — .env chmod 600, credentials/ chmod 700
- Secret exposure — no inline API keys, no hardcoded tokens
- Git safety — no sensitive files in workspace/
- Network exposure — gateway bound to loopback only
- Container security — non-root user, no-new-privileges
- Suspicious activity — force-push attempts, destructive commands, credential access
Run manually: ./agent-security-audit.sh
| Agent Type | RAM per agent | Max agents |
|---|---|---|
| No browser (idle) | ~400 MB | 8-10 |
| With browser (active) | ~2 GB | 3-4 |
| With browser (after daily restart) | ~400 MB | 8-10 |
All agents share one Ollama instance — models aren't duplicated. Containers run 24/7 with restart: unless-stopped. The 4 AM browser restart reclaims ~1.2GB per browser-enabled agent.
| Feature | Native | Docker | Notes |
|---|---|---|---|
| Browser automation | Yes | Yes (headless) | Chromium auto-installed via Dockerfile |
| Voice transcription | Yes (whisper-cpp) | Yes (whisper-cpp in Docker) | Local, free, ~500ms |
| Sandbox | Yes | Auto-enabled | Container is already sandboxed |
| Voice/TTS | Yes | No | macOS say not available |
| iMessage | Yes | No | Requires Messages.app |
| Claude Sync | Yes | No | Can't access host sessions |
| GitHub backup | launchd | Container cron | Both auto-sync every 10 min |
| Google Workspace | Browser OAuth | Manual OAuth (--manual) |
Both use gog CLI |
| CLI tools wizard | N/A | Yes | Generates custom Dockerfile |
| Telegram watchdog | N/A | Yes | Auto-restarts on connectivity loss |
| Agent name prefix | Yes | Yes | [AgentName] on all messages |
| Shared vault | Yes | Yes | Preserves existing files, appends tags |
| All other features | Yes | Yes | Full support |
Mac Mini (M4, 16GB)
├── Native: Samurai (Personal Assistant)
│ ├── Preset: personal-assistant, autonomy: semi-autonomous
│ ├── Obsidian vault (shared brain)
│ ├── WhatsApp (self-chat) + Telegram
│ └── Voice transcription (whisper-cpp)
│
├── Docker: agent-seekrjobs (Autonomous SaaS Agent)
│ ├── Preset: autonomous-agent, autonomy: semi-autonomous
│ ├── CLIs: gh, doctl, supabase, gog, xurl
│ ├── Source code repo mounted
│ ├── Telegram + watchdog sidecar
│ ├── Cron: daily report, content drafts, site health, email monitor
│ └── Browser (Chromium, restarted daily at 4 AM)
│
├── Docker: agent-tailhq (Developer Agent)
│ ├── Preset: developer, autonomy: supervised
│ ├── Telegram
│ └── Shared Obsidian vault
│
├── Docker: openclaw-rartisanal (Personal Assistant)
│ ├── Preset: personal-assistant
│ ├── WhatsApp (self-chat)
│ └── Google Workspace (gog)
│
├── Shared: Ollama (native, localhost:11434)
│ └── Models: glm-5:cloud, kimi-k2.5:cloud
│
├── Daily crons:
│ ├── 4 AM: browser-restart-cron.sh
│ └── 5 AM: agent-security-audit.sh
│
└── GitHub: Private brain repo
└── Auto-sync every 10 min (launchd + container cron)
- Input validation on all user inputs (rejects control chars, path traversal, shell injection)
- Credentials stored with
chmod 600/700permissions - API keys entered via hidden input (
read -s) - WhatsApp restricted via allowlist (owner's phone number only)
- Docker containers:
no-new-privileges, non-root user, healthchecks - Gateway bound to loopback by default
- Unique auth tokens auto-generated per instance
- Safe
.gitconfighandling (copied to instance dir, not bind-mounted) - Daily automated security audit (7 checks)
- Agent name prefix on all messages (distinguishes agent from user in self-chat)
- Autonomy levels with explicit GREEN/YELLOW/RED approval gates
# Syntax check
bash -n setup.sh
# Run bats test suite (35 tests)
npx bats test/setup.bats
# Docker smoke tests
docker build -f Dockerfile.test -t openclaw-setup-test .
docker run --rm openclaw-setup-test /test/run.shSee CONTRIBUTING.md for guidelines.
- Fork the repository
- Create a feature branch (
git checkout -b feature/name) - Run
bash -n setup.sh(syntax check) - Run
npx bats test/setup.bats(test suite) - Submit a PR