Personal assistant setup

Building a personal assistant with OpenClaw

OpenClaw is a self-hosted gateway that connects Discord, Google Chat, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo, and more to AI agents. This guide covers the "personal assistant" setup: a dedicated WhatsApp number that behaves like your always-on AI assistant.

⚠️ Safety first

You’re putting an agent in a position to:

• run commands on your machine (depending on your tool policy)
• read/write files in your workspace
• send messages back out via WhatsApp/Telegram/Discord/Mattermost and other bundled channels

Start conservative:

• Always set
  text

  Copy

  channels.whatsapp.allowFrom
  (never run open-to-the-world on your personal Mac).
• Use a dedicated WhatsApp number for the assistant.
• Heartbeats now default to every 30 minutes. Disable until you trust the setup by setting
  text

  Copy

  agents.defaults.heartbeat.every: "0m"
  .

Prerequisites

• OpenClaw installed and onboarded — see Getting Started if you haven't done this yet
• A second phone number (SIM/eSIM/prepaid) for the assistant

The two-phone setup (recommended)

You want this:

mermaid
Copy
flowchart TB
    A["<b>Your Phone (personal)<br></b><br>Your WhatsApp<br>+1-555-YOU"] -- message --> B["<b>Second Phone (assistant)<br></b><br>Assistant WA<br>+1-555-ASSIST"]
    B -- linked via QR --> C["<b>Your Mac (openclaw)<br></b><br>AI agent"]

If you link your personal WhatsApp to OpenClaw, every message to you becomes “agent input”. That’s rarely what you want.

5-minute quick start

1. Pair WhatsApp Web (shows QR; scan with the assistant phone):

bash
Copy
openclaw channels login

2. Start the Gateway (leave it running):

bash
Copy
openclaw gateway --port 18789

3. Put a minimal config in
   text

   Copy

   ~/.openclaw/openclaw.json
   :

json5
Copy
{
  gateway: { mode: "local" },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

Now message the assistant number from your allowlisted phone.

When onboarding finishes, OpenClaw auto-opens the dashboard and prints a clean (non-tokenized) link. If the dashboard prompts for auth, paste the configured shared secret into Control UI settings. Onboarding uses a token by default (

), but password auth works too if you switched to . To reopen later: .

Give the agent a workspace (AGENTS)

OpenClaw reads operating instructions and “memory” from its workspace directory.

By default, OpenClaw uses

as the agent workspace, and will create it (plus starter , , , , , ) automatically on setup/first agent run. is only created when the workspace is brand new (it should not come back after you delete it). is optional (not auto-created); when present, it is loaded for normal sessions. Subagent sessions only inject and .

bash
Copy
openclaw setup

Full workspace layout + backup guide: Agent workspace Memory workflow: Memory

Optional: choose a different workspace with

(supports ).

json5
Copy
{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
    },
  },
}

If you already ship your own workspace files from a repo, you can disable bootstrap file creation entirely:

json5
Copy
{
  agents: {
    defaults: {
      skipBootstrap: true,
    },
  },
}

The config that turns it into "an assistant"

OpenClaw defaults to a good assistant setup, but you’ll usually want to tune:

• persona/instructions in
  text

  Copy

  SOUL.md
• thinking defaults (if desired)
• heartbeats (once you trust it)

Example:

json5
Copy
{
  logging: { level: "info" },
  agent: {
    model: "anthropic/claude-opus-4-6",
    workspace: "~/.openclaw/workspace",
    thinkingDefault: "high",
    timeoutSeconds: 1800,
    // Start with 0; enable later.
    heartbeat: { every: "0m" },
  },
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: {
        "*": { requireMention: true },
      },
    },
  },
  routing: {
    groupChat: {
      mentionPatterns: ["@openclaw", "openclaw"],
    },
  },
  session: {
    scope: "per-sender",
    resetTriggers: ["/new", "/reset"],
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 10080,
    },
  },
}

Sessions and memory

• Session files:
  text

  Copy

  ~/.openclaw/agents/<agentId>/sessions/{{SessionId}}.jsonl
• Session metadata (token usage, last route, etc):
  text

  Copy

  ~/.openclaw/agents/<agentId>/sessions/sessions.json
  (legacy:
  text

  Copy

  ~/.openclaw/sessions/sessions.json
  )
• text

  Copy

  /new
  or
  text

  Copy

  /reset
  starts a fresh session for that chat (configurable via
  text

  Copy

  resetTriggers
  ). If sent alone, OpenClaw acknowledges the reset without invoking the model.
• text

  Copy

  /compact [instructions]
  compacts the session context and reports the remaining context budget.

Heartbeats (proactive mode)

By default, OpenClaw runs a heartbeat every 30 minutes with the prompt:

Set to disable.

• If
  text

  Copy

  HEARTBEAT.md
  exists but is effectively empty (only blank lines and markdown headers like
  text

  Copy

  # Heading
  ), OpenClaw skips the heartbeat run to save API calls.
• If the file is missing, the heartbeat still runs and the model decides what to do.
• If the agent replies with
  text

  Copy

  HEARTBEAT_OK
  (optionally with short padding; see
  text

  Copy

  agents.defaults.heartbeat.ackMaxChars
  ), OpenClaw suppresses outbound delivery for that heartbeat.
• By default, heartbeat delivery to DM-style
  text

  Copy

  user:<id>
  targets is allowed. Set
  text

  Copy

  agents.defaults.heartbeat.directPolicy: "block"
  to suppress direct-target delivery while keeping heartbeat runs active.
• Heartbeats run full agent turns — shorter intervals burn more tokens.

json5
Copy
{
  agent: {
    heartbeat: { every: "30m" },
  },
}

Media in and out

Inbound attachments (images/audio/docs) can be surfaced to your command via templates:

• text

  Copy

  {{MediaPath}}
  (local temp file path)
• text

  Copy

  {{MediaUrl}}
  (pseudo-URL)
• text

  Copy

  {{Transcript}}
  (if audio transcription is enabled)

Outbound attachments from the agent: include

on its own line (no spaces). Example:

text
Copy
Here’s the screenshot.
MEDIA:https://example.com/screenshot.png

OpenClaw extracts these and sends them as media alongside the text.

Local-path behavior follows the same file-read trust model as the agent:

• If
  text

  Copy

  tools.fs.workspaceOnly
  is
  text

  Copy

  true
  , outbound
  text

  Copy

  MEDIA:
  local paths stay restricted to the OpenClaw temp root, the media cache, agent workspace paths, and sandbox-generated files.
• If
  text

  Copy

  tools.fs.workspaceOnly
  is
  text

  Copy

  false
  , outbound
  text

  Copy

  MEDIA:
  can use host-local files the agent is already allowed to read.
• Host-local sends still only allow media and safe document types (images, audio, video, PDF, and Office documents). Plain text and secret-like files are not treated as sendable media.

That means generated images/files outside the workspace can now send when your fs policy already allows those reads, without reopening arbitrary host-text attachment exfiltration.

Operations checklist

bash
Copy
openclaw status          # local status (creds, sessions, queued events)
openclaw status --all    # full diagnosis (read-only, pasteable)
openclaw status --deep   # asks the gateway for a live health probe with channel probes when supported
openclaw health --json   # gateway health snapshot (WS; default can return a fresh cached snapshot)

Logs live under

(default: ).

Next steps

• WebChat: WebChat
• Gateway ops: Gateway runbook
• Cron + wakeups: Cron jobs
• macOS menu bar companion: OpenClaw macOS app
• iOS node app: iOS app
• Android node app: Android app
• Windows status: Windows (WSL2)
• Linux status: Linux app
• Security: Security

Related

• Getting started
• Setup
• Channels overview