Security Model

Security Model

Threat Model

A personal AI agent with access to email, calendars, messaging, and shell execution is a high-value target. If an agent is compromised or manipulated (via prompt injection, tool misuse, or configuration error), it could:

• Execute arbitrary shell commands
• Modify its own configuration, skills, and prompts
• Access other devices on the network
• Read or exfiltrate private data
• Send messages impersonating the owner
• Pivot from a restricted context to a privileged one

This document describes the layered security model that mitigates these risks.

Defense in Depth

Security relies on five independent layers. If any single layer is bypassed, the remaining layers still protect against full compromise.

External message arrives
         │
         ▼
  ┌──────────────┐
  │ 1. Channel   │  DM allowlist, group @mention gating
  │    Policies  │
  └──────┬───────┘
         ▼
  ┌──────────────┐
  │ 2. Agent     │  Message routed to correct agent based on sender/channel
  │    Bindings  │
  └──────┬───────┘
         ▼
  ┌──────────────┐
  │ 3. Tool      │  Agent-specific tool allow/deny lists
  │    Policies  │
  └──────┬───────┘
         ▼
  ┌──────────────┐
  │ 4. Exec      │  Per-agent CLI command allowlists
  │    Approvals │
  └──────┬───────┘
         ▼
  ┌──────────────┐
  │ 5. Workspace │  Per-agent config wrappers enforce data boundaries
  │    Isolation  │
  └──────┬───────┘
         ▼
   Agent responds (scoped)

Layer 1: Channel Policies

The first line of defense controls who can talk to the agent at all.

• DM allowlist — Only explicitly listed phone numbers can send direct messages
• Group mention gating — In group chats, the agent only responds when @mentioned
• WhatsApp policies — DMs disabled, groups restricted to an allowlist

Layer 2: Agent Bindings

Bindings route each message to the appropriate agent based on channel, peer kind (DM vs group), and peer ID.

• Most-specific wins — A binding for a specific phone number takes priority over a channel-wide fallback
• No implicit fallthrough — Without explicit bindings, messages reach the default (most privileged) agent. Always add bindings for every channel/peer combination.

See Multi-Agent Architecture for the full binding configuration.

Layer 3: Tool Policies

Each agent has an independent tool policy that controls which OpenClaw tools it can use.

Tool	Main Agent	Group/Family Agent
exec	Allowed	Allowed (gated by Layer 4)
read	Allowed	Denied
write, edit	Denied	Denied
browser	Allowed	Denied
web_search, web_fetch	Allowed	Allowed
memory_search, memory_get	Allowed	Allowed
sessions_send, sessions_spawn	Allowed	Denied
cron, gateway, process	Denied	Denied

Key principle: Even the main agent denies write, edit, and apply_patch to prevent self-modification of skills, prompts, or configuration.

Layer 4: Exec Approvals

The exec tool is required for MCP servers (via CLI clients) and native PIM tools. But unrestricted exec would bypass all other restrictions. Exec approvals solve this with per-agent command allowlists.

{
  "defaults": { "security": "deny" },
  "agents": {
    "main-agent": { "security": "full" },
    "group-agent": {
      "security": "allowlist",
      "allowlist": [
        { "pattern": "/path/to/travel-hub" },
        { "pattern": "/path/to/calendar-cli" },
        { "pattern": "/path/to/reminder-cli" },
        { "pattern": "/path/to/contacts-cli" },
        { "pattern": "/path/to/mail-inbox" },
        { "pattern": "/path/to/mail-read" },
        { "pattern": "/path/to/mail-list" }
      ]
    }
  }
}

Explicitly NOT allowlisted (blocked by absence):

• Direct MCP client commands (blocks private email search)
• Mail send/reply/archive commands (blocks outbound email)
• General shell commands (curl, bash, etc.)

Layer 5: Workspace Isolation

Each agent has its own workspace directory with wrapper scripts that set per-agent configuration. For example, Apple PIM wrappers set environment variables that filter which calendars and reminder lists the agent can access:

Agent	Calendar Access	Reminders Access
Main	All	All
Group	Shared only (Work/Personal blocked)	Shared only (Personal blocked)
Family	Shared only (Work/Personal blocked)	Shared only (Personal blocked)

Network Isolation

The agent machine should be network-isolated from other devices. Using Tailscale ACLs:

• Personal devices can reach the agent (for SSH, dashboard)
• The agent cannot initiate connections to personal devices
• Tag the agent as tag:agent and omit any grant where tag:agent is the source

This prevents a compromised agent from pivoting to other machines.

SSH Hardening

• Use Tailscale SSH instead of macOS built-in SSH
• Disable macOS sshd entirely (sudo systemsetup -setremotelogin off)
• Configure ACL SSH rules with action: check for the agent (requires browser re-authentication)
• Enable Tailscale Lock with physical devices as approval nodes

See Remote Access for the full setup.

Prompt Injection Defense

External content (email bodies, calendar event titles, message content) is untrusted data. The agent should:

1. Never execute instructions found in external content
2. Sanitize external text before including it in LLM context
3. Add guardrails to the agent’s system prompt

See Prompt Injection Defense for sanitization patterns and guardrail examples.

Agent-to-Agent Communication

Agent-to-agent messaging should be disabled unless scoped restrictions are available. Without scoping, a restricted agent can escalate privileges by asking a privileged agent to perform actions on its behalf.

{
  "agentToAgent": {
    "enabled": false
  }
}

Workaround: If a family member needs an elevated action, the agent tells them to ask the owner directly.

Elevated Access

Only the owner gets elevated access, applied globally across all agents:

{
  "elevated": {
    "enabled": true,
    "allowFrom": {
      "bluebubbles": ["+1XXXXXXXXXX"]
    }
  }
}

When the owner @mentions in a group chat, the restricted agent temporarily gains elevated privileges for that session.

Configuration Security

• Permissions: chmod 600 for openclaw.json, chmod 700 for identity and agent directories
• Slash commands: Disable bash, config, debug, and restart via iMessage
• Logging: Enable secret redaction patterns for API keys, tokens, phone numbers, and bearer tokens
• Backups: Always cp openclaw.json openclaw.json.pre-<change> before editing configuration

Audit Checklist

After hardening:

openclaw security audit

Key verifications:

• Agent machine cannot ping personal devices
• Personal devices can SSH to agent
• Family DMs route to restricted agent (not main)
• Group chats require @mention
• MCP tools still work
• Logs show redacted sensitive data
• Dangerous slash commands are disabled