Skip to content
RemoteClaw

Personal Assistant Setup

Building a personal assistant with RemoteClaw

RemoteClaw is a WhatsApp + Telegram + Discord + iMessage gateway for Pi agents. Plugins add Mattermost. This guide is the “personal assistant” setup: one dedicated WhatsApp number that behaves like your always-on agent.

⚠️ Safety first

You’re putting an agent in a position to:

  • run commands on your machine (depending on your Pi tool setup)
  • read/write files in your workspace
  • send messages back out via WhatsApp/Telegram/Discord/Mattermost (plugin)

Start conservative:

  • Always set 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 agents.defaults.heartbeat.every: "0m".

Prerequisites

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

You want this:

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 (remoteclaw)<br></b><br>Agent runtime"]

If you link your personal WhatsApp to RemoteClaw, 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):
Terminal window
remoteclaw channels login
  1. Start the Gateway (leave it running):
Terminal window
remoteclaw gateway --port 18789
  1. Put a minimal config in ~/.remoteclaw/remoteclaw.json:
{
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

Now message the assistant number from your allowlisted phone.

When onboarding finishes, we auto-open the dashboard and print a clean (non-tokenized) link. If it prompts for auth, paste the token from gateway.auth.token into Control UI settings. To reopen later: remoteclaw dashboard.

Give the agent a workspace

The workspace is the agent’s working directory. Agents bring their own configuration (e.g. CLAUDE.md for Claude Code, .gemini/ for Gemini CLI). RemoteClaw does not seed or manage template files in the workspace.

There is no built-in workspace path — you must configure one explicitly via agents.defaults.workspace or per-agent agents.list[].workspace.

Terminal window
remoteclaw setup

Tip: treat this folder like the agent’s “memory” and make it a private git repo so memory files are backed up.

Full workspace layout + backup guide: Agent workspace

Optional: choose a different workspace with agents.defaults.workspace (supports ~).

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

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

{
  agent: {
    skipBootstrap: true,
  },
}

The config that turns it into “an assistant”

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

  • persona/instructions via native agent config (e.g. CLAUDE.md)
  • thinking defaults (if desired)
  • heartbeats (once you trust it)

Example:

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

Sessions and memory

  • Session files: ~/.remoteclaw/agents/<agentId>/sessions/{{SessionId}}.jsonl
  • Session metadata (token usage, last route, etc): ~/.remoteclaw/agents/<agentId>/sessions/sessions.json (legacy: ~/.remoteclaw/sessions/sessions.json)
  • /new or /reset starts a fresh session for that chat (configurable via resetTriggers). If sent alone, the agent replies with a short hello to confirm the reset.
  • /compact [instructions] compacts the session context and reports the remaining context budget.

Heartbeats (proactive mode)

By default, RemoteClaw 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. Set agents.defaults.heartbeat.every: "0m" to disable.

  • If HEARTBEAT.md exists but is effectively empty (only blank lines and markdown headers like # Heading), RemoteClaw 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 HEARTBEAT_OK, RemoteClaw suppresses outbound delivery for that heartbeat.
  • Heartbeat delivery to DM-style user:<id> targets is blocked; those runs still execute but skip outbound delivery.
  • Heartbeats run full agent turns — shorter intervals burn more tokens.
{
  agent: {
    heartbeat: { every: "30m" },
  },
}

Media in and out

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

  • {{MediaPath}} (local temp file path)
  • {{MediaUrl}} (pseudo-URL)
  • {{Transcript}} (if audio transcription is enabled)

Outbound attachments from the agent: include MEDIA:<path-or-url> on its own line (no spaces). Example:

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

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

Operations checklist

Terminal window
remoteclaw status          # local status (creds, sessions, queued events)
remoteclaw status --all    # full diagnosis (read-only, pasteable)
remoteclaw status --deep   # adds gateway health probes (Telegram + Discord)
remoteclaw health --json   # gateway health snapshot (WS)

Logs live under /tmp/remoteclaw/ (default: remoteclaw-YYYY-MM-DD.log).

Next steps