mirror of
https://github.com/openclaw/openclaw.git
synced 2026-04-19 05:47:28 +00:00
refactor: rename to openclaw
This commit is contained in:
Peter Steinberger
235
docs/start/openclaw.md
Normal file
235
docs/start/openclaw.md
Normal file
@@ -0,0 +1,235 @@
|
||||
---
|
||||
summary: "End-to-end guide for running OpenClaw as a personal assistant with safety cautions"
|
||||
read_when:
|
||||
- Onboarding a new assistant instance
|
||||
- Reviewing safety/permission implications
|
||||
---
|
||||
# Building a personal assistant with OpenClaw
|
||||
|
||||
OpenClaw 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
|
||||
|
||||
- Node **22+**
|
||||
- OpenClaw available on PATH (recommended: global install)
|
||||
- A second phone number (SIM/eSIM/prepaid) for the assistant
|
||||
|
||||
```bash
|
||||
npm install -g openclaw@latest
|
||||
# or: pnpm add -g openclaw@latest
|
||||
```
|
||||
|
||||
From source (development):
|
||||
|
||||
```bash
|
||||
git clone https://github.com/openclaw/openclaw.git
|
||||
cd openclaw
|
||||
pnpm install
|
||||
pnpm ui:build # auto-installs UI deps on first run
|
||||
pnpm build
|
||||
pnpm link --global
|
||||
```
|
||||
|
||||
## The two-phone setup (recommended)
|
||||
|
||||
You want this:
|
||||
|
||||
```
|
||||
Your Phone (personal) Second Phone (assistant)
|
||||
┌─────────────────┐ ┌─────────────────┐
|
||||
│ Your WhatsApp │ ──────▶ │ Assistant WA │
|
||||
│ +1-555-YOU │ message │ +1-555-ASSIST │
|
||||
└─────────────────┘ └────────┬────────┘
|
||||
│ linked via QR
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ Your Mac │
|
||||
│ (openclaw) │
|
||||
│ Pi 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
|
||||
openclaw channels login
|
||||
```
|
||||
|
||||
2) Start the Gateway (leave it running):
|
||||
|
||||
```bash
|
||||
openclaw gateway --port 18789
|
||||
```
|
||||
|
||||
3) Put a minimal config in `~/.openclaw/openclaw.json`:
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: { whatsapp: { allowFrom: ["+15555550123"] } }
|
||||
}
|
||||
```
|
||||
|
||||
Now message the assistant number from your allowlisted phone.
|
||||
|
||||
When onboarding finishes, we auto-open the dashboard with your gateway token and print the tokenized link. To reopen later: `openclaw dashboard`.
|
||||
|
||||
## Give the agent a workspace (AGENTS)
|
||||
|
||||
OpenClaw reads operating instructions and “memory” from its workspace directory.
|
||||
|
||||
By default, OpenClaw uses `~/.openclaw/workspace` as the agent workspace, and will create it (plus starter `AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`) automatically on setup/first agent run. `BOOTSTRAP.md` is only created when the workspace is brand new (it should not come back after you delete it).
|
||||
|
||||
Tip: treat this folder like OpenClaw’s “memory” and make it a git repo (ideally private) so your `AGENTS.md` + memory files are backed up. If git is installed, brand-new workspaces are auto-initialized.
|
||||
|
||||
```bash
|
||||
openclaw setup
|
||||
```
|
||||
|
||||
Full workspace layout + backup guide: [Agent workspace](/concepts/agent-workspace)
|
||||
Memory workflow: [Memory](/concepts/memory)
|
||||
|
||||
Optional: choose a different workspace with `agents.defaults.workspace` (supports `~`).
|
||||
|
||||
```json5
|
||||
{
|
||||
agent: {
|
||||
workspace: "~/.openclaw/workspace"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
If you already ship your own workspace files from a repo, you can disable bootstrap file creation entirely:
|
||||
|
||||
```json5
|
||||
{
|
||||
agent: {
|
||||
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 `SOUL.md`
|
||||
- thinking defaults (if desired)
|
||||
- heartbeats (once you trust it)
|
||||
|
||||
Example:
|
||||
|
||||
```json5
|
||||
{
|
||||
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
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Sessions and memory
|
||||
|
||||
- Session files: `~/.openclaw/agents/<agentId>/sessions/{{SessionId}}.jsonl`
|
||||
- Session metadata (token usage, last route, etc): `~/.openclaw/agents/<agentId>/sessions/sessions.json` (legacy: `~/.openclaw/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, 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.`
|
||||
Set `agents.defaults.heartbeat.every: "0m"` to disable.
|
||||
|
||||
- If `HEARTBEAT.md` exists but is effectively empty (only blank lines and markdown headers like `# 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 `HEARTBEAT_OK` (optionally with short padding; see `agents.defaults.heartbeat.ackMaxChars`), OpenClaw suppresses outbound delivery for that heartbeat.
|
||||
- Heartbeats run full agent turns — shorter intervals burn more tokens.
|
||||
|
||||
```json5
|
||||
{
|
||||
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:/tmp/screenshot.png
|
||||
```
|
||||
|
||||
OpenClaw extracts these and sends them as media alongside the text.
|
||||
|
||||
## Operations checklist
|
||||
|
||||
```bash
|
||||
openclaw status # local status (creds, sessions, queued events)
|
||||
openclaw status --all # full diagnosis (read-only, pasteable)
|
||||
openclaw status --deep # adds gateway health probes (Telegram + Discord)
|
||||
openclaw health --json # gateway health snapshot (WS)
|
||||
```
|
||||
|
||||
Logs live under `/tmp/openclaw/` (default: `openclaw-YYYY-MM-DD.log`).
|
||||
|
||||
## Next steps
|
||||
|
||||
- WebChat: [WebChat](/web/webchat)
|
||||
- Gateway ops: [Gateway runbook](/gateway)
|
||||
- Cron + wakeups: [Cron jobs](/automation/cron-jobs)
|
||||
- macOS menu bar companion: [OpenClaw macOS app](/platforms/macos)
|
||||
- iOS node app: [iOS app](/platforms/ios)
|
||||
- Android node app: [Android app](/platforms/android)
|
||||
- Windows status: [Windows (WSL2)](/platforms/windows)
|
||||
- Linux status: [Linux app](/platforms/linux)
|
||||
- Security: [Security](/gateway/security)
|
||||
Reference in New Issue
Block a user