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
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.
iMessage Bridge (imsg)
imsg is a local CLI plus a private-API helper dylib injected into Messages.app. It reads the Messages SQLite database for inbound, and sends through the Messages framework for outbound. No separate server process, no webhooks, no API password — OpenClaw talks to imsg directly via channels.imessage.cliPath. Requires a dedicated Apple ID, Full Disk Access, and (for the Private API) SIP disabled on Apple Silicon.
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 the imsg private-API 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 |
| Voice | Talk Mode — voice conversations via iOS app, TUI, and control UI (ElevenLabs TTS) |
| Health | Self-healing iMessage bridge, stuck-session detection, automated secrets auditing |
| 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 with Apple Silicon (M1 or later), always-on
- macOS Sequoia (15) or later
- SIP disabled (required for iMessage Private API — see Phase 3 for Apple Silicon steps)
- Dedicated Apple ID for the agent
- Anthropic API key
Setup
- Clone the repository and run the setup script
- Configure iMessage 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 |