Personal Assistant Configuration

OpenClaw is a WhatsApp + Telegram + Discord + iMessage gateway for **Pi** agents. Plugins also allow access to Mattermost. This guide is for "Personal Assistant" configuration: using a dedicated WhatsApp number to act as an always-online Agent.

You are putting an Agent in a position where it can: - Run commands on your machine (depending on your Pi tool config) - Read/write files in your workspace - Send outbound messages via WhatsApp/Telegram/Discord/Mattermost (via plugin) We recommend starting with a conservative configuration:

- Always set `channels.whatsapp.allowFrom` (don't run a "world-open" assistant on your personal machine).

- Use a separate WhatsApp number for the assistant.

- Heartbeat defaults to every 30 minutes. We suggest disabling it until you trust the setup: `agents.defaults.heartbeat.every: "0m"`.

- Node **22+** - OpenClaw available in your system PATH (recommended: global install) - A second phone number (SIM/eSIM/prepaid all work) for the assistant number

npm install -g openclaw@latest

Running from source (dev mode):

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build # installs UI dependencies on first run
pnpm build
pnpm link --global

This is the structure you want:

Your Phone (Personal)             Assistant Phone (Secondary)
┌─────────────────┐           ┌─────────────────┐
│  Your WhatsApp  │  ──────▶  │ Assistant WhatsApp│
│  +1-555-YOU      │  message  │  +1-555-ASSIST  │
└─────────────────┘           └────────┬────────┘
                                       │ Link via QR code
                                       ▼
                              ┌─────────────────┐
                              │  Your Mac        │
                              │  (openclaw)      │
                              │    Pi agent      │
                              └─────────────────┘

If you link your personal WhatsApp account to OpenClaw, every message sent to you becomes "agent input." This is usually not what you want.

openclaw channels login

openclaw gateway --port 18789

'{'
  channels: '{' whatsapp: '{' allowFrom: ["+15555550123"] '}' '}',
'}'

Now, message the assistant number from your allowlisted phone. Once onboarding is complete, we automatically open the dashboard link with a token and print the tokenized URL. To open it later: `openclaw dashboard`.

OpenClaw reads operational instructions and "memories" from its workspace directory. By default, OpenClaw uses `~/.openclaw/workspace` as the agent workspace and auto-creates it upon setup/first-run (along with initial `AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`). `BOOTSTRAP.md` is only created when the workspace is brand new (and shouldn't reappear after deletion).

Recommendation: Treat this folder as OpenClaw's "memory" and back it up by making it a git repository (private repo preferred) for `AGENTS.md` and memory files. If git is installed, a new workspace will be auto-initialized as a repo.

openclaw setup

Optional: Set a different workspace path via `agents.defaults.workspace` (supports `~`):

{
  agent: {
    workspace: "~/.openclaw/workspace",
  },
}

If you are already distributing your own workspace files via repo, you can disable bootstrap file creation entirely:

{
  agent: {
    skipBootstrap: true,
  },
}

OpenClaw comes with decent assistant defaults, but you will usually want to tune:

- Persona / Instructions in `SOUL.md`

- Thinking defaults (if needed)

- Heartbeat (enable after you trust it)

Example:

{
  logging: { level: "info" },
  agent: {
    model: "anthropic/claude-opus-4-5",
    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,
    },
  },
}

- Session files: `<code1>~/.openclaw/agents/<agentId>/sessions/{'{SessionId}'}.jsonl</code1>`

- Session metadata (token usage, last route, etc.): `<code1>~/.openclaw/agents/<agentId>/sessions/sessions.json</code1>` (old path: `<code2>~/.openclaw/sessions/sessions.json</code2>` )

- `/new` or `/reset` starts a new session for that chat (configured via `resetTriggers`). If sent as a standalone command, the Agent replies with a short confirmation message.

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

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

`Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`

Setting `agents.defaults.heartbeat.every: "0m"` disables heartbeats.

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

Inbound attachments (images/audio/docs) are provided to your commands via template parameters:

- `<code1>'{'{MediaPath}'}'</code1>` (local temp file path)

- `<code2>'{'{MediaUrl}'}'</code2>` (pseudo-URL)

- `<code3>'{'{Transcript}'}'</code3>` (if audio transcription is enabled)

Agent Outbound attachments: Write `<code1>MEDIA:<path-or-url>'</code1>` (no spaces) on a separate line. For example:

Here is the screenshot.
MEDIA:https://example.com/screenshot.png

OpenClaw parses these lines and sends them as media alongside the text.

openclaw status          # Local status (creds, sessions, queued events)
openclaw status --all    # Full diagnostics (read-only, easy to paste/share)
openclaw status --deep   # Adds gateway health probes (Telegram + Discord)
openclaw health --json   # Gateway health snapshot (WS)

Logs default to `/tmp/openclaw/` (filenames like `openclaw-YYYY-MM-DD.log`).