ClawdHome

English | 中文

Native macOS control plane for securely running and managing multiple isolated OpenClaw gateway instances on a single Mac.

ClawdHome is built for people who want one machine to host multiple OpenClaw "Shrimps" without mixing identities, data, permissions, or operational risk. It combines a SwiftUI admin app, a privileged XPC helper daemon, and macOS multi-user isolation into a single workflow for setup, monitoring, cloning, maintenance, and recovery.

Website: clawdhome.app
Downloads: GitHub Releases
Changelog: English | 中文

Screenshots

Why ClawdHome

• Real isolation: each Shrimp maps to its own macOS user account, runtime context, data, and permission boundary.
• Safer privilege model: system-level actions are routed through an explicit XPC helper instead of ad-hoc shell flows inside the UI app.
• Faster iteration: clone an existing Shrimp for experiments, rehearsal, or regression checks, then promote what works.
• Native Mac fit: uses macOS user and process primitives instead of heavier VM or container workflows for this class of desktop automation.
• Unified operations: manage onboarding, gateway lifecycle, files, logs, processes, config, and diagnostics from one place.

Highlights

• Run multiple OpenClaw gateway instances on one Mac with clear per-instance boundaries.
• Guided onboarding for new Shrimps, including channel-specific setup flows such as WeChat pairing.
• Clone an existing Shrimp into a new isolated account for low-risk testing and rollout rehearsal.
• Gateway lifecycle management with health visibility and watchdog-based recovery.
• Built-in tools for files, sessions, processes, logs, and maintenance operations.
• Model and provider configuration from the app, including direct model setup and Role Market-based presets.
• Local AI operations support, including integration hooks for local model services where configured.
• English and Chinese localization based on Stable.xcstrings.

Architecture

ClawdHome.app (SwiftUI admin UI)
  -> XPC -> ClawdHomeHelper (privileged LaunchDaemon)
      -> per-user OpenClaw gateway instances

• ClawdHome.app is the operator-facing control plane for status, setup, and day-to-day maintenance.
• ClawdHomeHelper is the privileged boundary for user management, process control, file operations, installs, and system automation.
• Each Shrimp runs as a separate macOS user with its own OpenClaw runtime and data.

Security Model

• Privileged operations stay inside the helper boundary.
• Sensitive actions use explicit XPC methods rather than arbitrary shell paths.
• Ownership and permission repair are built into important lifecycle workflows.
• Runtime resources are separated per Shrimp to reduce blast radius and accidental cross-contamination.

Quick Start

Requirements

• macOS 14+
• Xcode 15+
• Optional: XcodeGen

Build From Source

open ClawdHome.xcodeproj

If you prefer to regenerate the Xcode project first:

xcodegen generate
open ClawdHome.xcodeproj

Install Helper For Local Development

make install-helper

Equivalent direct command:

sudo bash scripts/install-helper-dev.sh install

Common Commands

Purpose	Command
Build app (Debug)	make build
Build helper only	make build-helper
Build release archive	make build-release
Build unsigned local package	make pkg
Build signed package for local validation	make pkg-signed
Build signed and notarized package	make notarize-pkg
Run full release flow	make release NOTARIZE=true
Run exported Release app directly	make run-release
Install latest generated package	make install-pkg
Uninstall development helper	make uninstall-helper
Tail helper logs	make log-helper
Tail app logs	make log-app
Run localization checks	make i18n-check
Clean build artifacts	make clean

Troubleshooting

npm install -g fails on macOS

Check whether Xcode Command Line Tools are available:

xcode-select -p

If the command fails, install them:

xcode-select --install

If you hit an Xcode license error, accept it as an admin user:

sudo xcodebuild -license
# or non-interactive:
sudo xcodebuild -license accept

Where to look for logs

• Helper log: /tmp/clawdhome-helper.log
• App log stream: make log-app

Repository Layout

ClawdHome/          SwiftUI app, views, models, services
ClawdHomeHelper/    privileged helper daemon and operations
Shared/             protocols and shared models for app/helper
Resources/          launch daemon plist and packaging resources
scripts/            build, install, packaging, release, and i18n utilities
docs/               project documentation and README assets
release-notes/      generated release-note drafts

Localization

• Languages: English and Chinese
• String system: Stable.xcstrings
• Checks: make i18n-check
• Guide: docs/i18n.md

Roadmap

• External key management with an exec-based secrets provider
• Finer-grained network access control management
• Simpler setup for more model providers and IM channels
• Better local small-model workflows and OpenClaw integration
• Stronger rescue and diagnostics capabilities
• Better gateway probing and historical health tracking
• More production-ready signed and notarized distribution workflows

Contributing

• Open an issue before large or structural changes.
• Keep pull requests small, focused, and easy to review.
• Include validation evidence for behavior changes.
• Avoid committing local or private environment artifacts.
• Follow the existing Swift and project structure conventions.
• The repository currently does not ship automated unit tests, so manual verification notes are especially important in PRs.

Star History

License

Apache License 2.0. See LICENSE.