Getting Started
Getting Started
A personal AI agent is an always-on assistant running on a dedicated Mac that your family can message via iMessage. It manages calendars, email, travel, reminders, and more — acting as a proactive Chief of Staff for your household.
What You’re Building
┌───────────────────────────────────────────────────────────────┐│ Dedicated Mac (Always-On) ││ ││ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ││ │ BlueBubbles │───>│ OpenClaw │───>│ Docker │ ││ │ Server │ │ Gateway │ │ Sandbox │ ││ └──────────────┘ └──────────────┘ └──────────────┘ ││ │ │ ││ v v ││ ┌──────────────┐ ┌──────────────────────────────────┐ ││ │ iMessage │ │ MCP Servers │ ││ │ (dedicated │ │ - Email (Fastmail, Gmail, etc.) │ ││ │ Apple ID) │ │ - Calendars & Reminders │ ││ └──────────────┘ │ - Custom services │ ││ └──────────────────────────────────┘ │└───────────────────────────────────────────────────────────────┘Key Concepts
OpenClaw Gateway
OpenClaw is the runtime that manages conversations, tool access, sessions, and scheduled tasks. It runs as a LaunchAgent on macOS and exposes a web dashboard for monitoring.
BlueBubbles (iMessage Bridge)
BlueBubbles bridges iMessage to the OpenClaw gateway via webhooks. It requires a dedicated Apple ID and Full Disk Access on the host Mac.
Multi-Agent Architecture
A single OpenClaw gateway can run multiple agents with different security profiles. The recommended pattern uses three agents:
- Main agent — handles the owner’s DMs with full tool access
- Group agent — handles group chats with restricted tools
- Family agent — handles family member DMs with the same restrictions
See Multi-Agent Architecture for the full design.
MCP Servers
Model Context Protocol servers give the agent access to external services — email, calendars, travel management, and more. These can be local (stdio) or remote (HTTP).
See MCP Servers for setup instructions.
Defense in Depth
Security is layered: channel bindings route messages to the correct agent, tool policies restrict what each agent can do, exec approvals control which CLI commands are allowed, and workspace wrappers enforce per-agent access restrictions.
See Security Model for the full threat model and mitigation strategy.
Capabilities
A fully configured agent can:
| Category | Examples |
|---|---|
| iMessage | Family DMs and group chats via BlueBubbles bridge |
| Triage inbox, search messages, flag important items | |
| Calendar | Check schedules, create events, send meeting reminders |
| Reminders | Create and complete tasks across shared lists |
| Contacts | Look up people by name, email, or phone number |
| Travel | Look up trips, track flights, manage reservations |
| Packages | Track deliveries, set vacation holds |
| Documents | Organize files in a structured filing system |
| Web | Search the web, fetch pages, answer questions |
| Proactive | Heartbeat checks, cron jobs, morning briefings |
Calendar, Reminders, and Contacts are powered by Apple PIM — native Swift CLIs that access macOS EventKit and Contacts directly on the host Mac. No cloud API needed. See Phase 8 for setup details.
Quick Start
Prerequisites
- Mac (M1 or later recommended), always-on
- macOS Sequoia (15) or later
- Dedicated Apple ID for the agent
- Anthropic API key
Setup
- Clone the repository and run the setup script
- Configure BlueBubbles and connect to OpenClaw
- Share calendars and reminders via iCloud
- Add MCP servers for email and other services
- Configure remote access via Tailscale
- Harden the deployment
For the complete walkthrough, see How to Build Your Own.
Documentation Map
| Section | What’s There |
|---|---|
| Architecture | Multi-agent model, security design |
| Guides | Step-by-step setup for each component |
| Security | Hardening, email auth, prompt injection defense |
| Reference | Plugin sharing research, troubleshooting |