vilvona 1.0.0

package/docs/start/openclaw.md

@@ -0,0 +1,246 @@
+---
+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
+title: "Personal assistant setup"
+---
+
+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 `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
+
+- OpenClaw installed and onboarded - see [Getting Started](/start/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
+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
+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
+{
+  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 (`gateway.auth.token`), but password auth works too if you switched `gateway.auth.mode` to `password`. 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`, `HEARTBEAT.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). `MEMORY.md` is optional (not auto-created); when present, it is loaded for normal sessions. Subagent sessions only inject `AGENTS.md` and `TOOLS.md`.
+
+<Tip>
+Treat this folder like OpenClaw's memory and make it a git repo (ideally private) so your `AGENTS.md` and memory files are backed up. If git is installed, brand-new workspaces are auto-initialized.
+</Tip>
+
+```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
+{
+  agents: {
+    defaults: {
+      workspace: "~/.openclaw/workspace",
+    },
+  },
+}
+```
+
+If you already ship your own workspace files from a repo, you can disable bootstrap file creation entirely:
+
+```json5
+{
+  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 [`SOUL.md`](/concepts/soul)
+- thinking defaults (if desired)
+- heartbeats (once you trust it)
+
+Example:
+
+```json5
+{
+  logging: { level: "info" },
+  agents: {
+    defaults: {
+      model: { primary: "anthropic/claude-opus-4-6" },
+      workspace: "~/.openclaw/workspace",
+      thinkingDefault: "high",
+      timeoutSeconds: 1800,
+      // Start with 0; enable later.
+      heartbeat: { every: "0m" },
+    },
+    list: [
+      {
+        id: "main",
+        default: true,
+        groupChat: {
+          mentionPatterns: ["@openclaw", "openclaw"],
+        },
+      },
+    ],
+  },
+  channels: {
+    whatsapp: {
+      allowFrom: ["+15555550123"],
+      groups: {
+        "*": { requireMention: true },
+      },
+    },
+  },
+  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, OpenClaw acknowledges the reset without invoking the model.
+- `/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, Markdown/HTML comments, Markdown headings like `# Heading`, fence markers, or empty checklist stubs), 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.
+- By default, heartbeat delivery to DM-style `user:<id>` targets is allowed. Set `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
+{
+  agents: {
+    defaults: {
+      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 use structured media fields on the message tool or reply payload, such as `media`, `mediaUrl`, `mediaUrls`, `path`, or `filePath`. Example message-tool arguments:
+
+```json
+{
+  "message": "Here's the screenshot.",
+  "mediaUrl": "https://example.com/screenshot.png"
+}
+```
+
+OpenClaw sends structured media alongside the text. Legacy final assistant replies may still be normalized for compatibility, but tool output, browser output, streaming blocks, and message actions do not parse text as attachment commands.
+
+Local-path behavior follows the same file-read trust model as the agent:
+
+- If `tools.fs.workspaceOnly` is `true`, outbound local media paths stay restricted to the OpenClaw temp root, the media cache, agent workspace paths, and sandbox-generated files.
+- If `tools.fs.workspaceOnly` is `false`, outbound local media can use host-local files the agent is already allowed to read.
+- Local paths can be absolute, workspace-relative, or home-relative with `~/`.
+- Host-local sends still only allow media and safe document types (images, audio, video, PDF, Office documents, and validated text documents such as Markdown/MD, TXT, JSON, YAML, and YML). This is an extension of the existing host-read trust boundary, not a secret scanner: if the agent can read a host-local `secret.txt` or `config.json`, it can attach that file when the extension and content validation match.
+
+That means generated images/files outside the workspace can now send when your fs policy already allows those reads, while arbitrary host-local text extensions remain blocked. Keep sensitive files outside the agent-readable filesystem, or keep `tools.fs.workspaceOnly=true` for stricter local-path sends.
+
+## Operations checklist
+
+```bash
+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 `/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 Hub: [Windows](/platforms/windows)
+- Linux status: [Linux app](/platforms/linux)
+- Security: [Security](/gateway/security)
+
+## Related
+
+- [Getting started](/start/getting-started)
+- [Setup](/start/setup)
+- [Channels overview](/channels)

package/docs/start/quickstart.md

@@ -0,0 +1,25 @@
+---
+summary: "Quick start has moved to Getting Started."
+read_when:
+  - You are looking for the fastest setup steps
+  - You were sent here from an older link
+title: "Quick start"
+---
+
+<Info>
+Quick start is now part of [Getting Started](/start/getting-started).
+</Info>
+
+<Columns>
+  <Card title="Getting Started" href="/start/getting-started">
+    Install OpenClaw and run your first chat in minutes.
+  </Card>
+  <Card title="Onboarding (CLI)" href="/start/wizard">
+    Full CLI onboarding reference and advanced options.
+  </Card>
+</Columns>
+
+## Related
+
+- [Getting started](/start/getting-started)
+- [Install overview](/install)

package/docs/start/setup.md

@@ -0,0 +1,178 @@
+---
+summary: "Advanced setup and development workflows for OpenClaw"
+read_when:
+  - Setting up a new machine
+  - You want "latest + greatest" without breaking your personal setup
+title: "Setup"
+---
+
+<Note>
+If you are setting up for the first time, start with [Getting Started](/start/getting-started).
+For onboarding details, see [Onboarding (CLI)](/start/wizard).
+</Note>
+
+## TL;DR
+
+Pick a setup workflow based on how often you want updates and whether you want to run the Gateway yourself:
+
+- **Tailoring lives outside the repo:** keep your config and workspace in `~/.openclaw/openclaw.json` and `~/.openclaw/workspace/` so repo updates don't touch them.
+- **Stable workflow (recommended for most):** install the macOS app and let it run the bundled Gateway.
+- **Bleeding edge workflow (dev):** run the Gateway yourself via `pnpm gateway:watch`, then let the macOS app attach in Local mode.
+
+## Prereqs (from source)
+
+- Node 24 recommended (Node 22 LTS, currently `22.19+`, still supported)
+- `pnpm` required for source checkouts. OpenClaw loads bundled plugins from the
+  `extensions/*` pnpm workspace packages in dev mode, so root `npm install` does
+  not prepare the full source tree.
+- Docker (optional; only for containerized setup/e2e - see [Docker](/install/docker))
+
+## Tailoring strategy (so updates do not hurt)
+
+If you want "100% tailored to me" _and_ easy updates, keep your customization in:
+
+- **Config:** `~/.openclaw/openclaw.json` (JSON/JSON5-ish)
+- **Workspace:** `~/.openclaw/workspace` (skills, prompts, memories; make it a private git repo)
+
+Bootstrap once:
+
+```bash
+openclaw setup
+```
+
+From inside this repo, use the local CLI entry:
+
+```bash
+openclaw setup
+```
+
+If you don't have a global install yet, run it via `pnpm openclaw setup`.
+
+## Run the Gateway from this repo
+
+After `pnpm build`, you can run the packaged CLI directly:
+
+```bash
+node openclaw.mjs gateway --port 18789 --verbose
+```
+
+## Stable workflow (macOS app first)
+
+1. Install + launch **OpenClaw.app** (menu bar).
+2. Complete the onboarding/permissions checklist (TCC prompts).
+3. Ensure Gateway is **Local** and running (the app manages it).
+4. Link surfaces (example: WhatsApp):
+
+```bash
+openclaw channels login
+```
+
+5. Sanity check:
+
+```bash
+openclaw health
+```
+
+If onboarding is not available in your build:
+
+- Run `openclaw setup`, then `openclaw channels login`, then start the Gateway manually (`openclaw gateway`).
+
+## Bleeding edge workflow (Gateway in a terminal)
+
+Goal: work on the TypeScript Gateway, get hot reload, keep the macOS app UI attached.
+
+### 0) (Optional) Run the macOS app from source too
+
+If you also want the macOS app on the bleeding edge:
+
+```bash
+./scripts/restart-mac.sh
+```
+
+### 1) Start the dev Gateway
+
+```bash
+pnpm install
+# First run only (or after resetting local OpenClaw config/workspace)
+pnpm openclaw setup
+pnpm gateway:watch
+```
+
+`gateway:watch` starts or restarts the Gateway watch process in a named tmux
+session and auto-attaches from interactive terminals. Non-interactive shells stay
+detached and print `tmux attach -t openclaw-gateway-watch-main`; use
+`OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch` to keep an interactive run
+detached, or `pnpm gateway:watch:raw` for foreground watch mode. The watcher
+reloads on relevant source, config, and bundled-plugin metadata changes. If the
+watched Gateway exits during startup, `gateway:watch` runs
+`openclaw doctor --fix --non-interactive` once and retries; set
+`OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0` to disable that dev-only repair pass.
+`pnpm openclaw setup` is the one-time local config/workspace initialization step for a fresh checkout.
+`pnpm gateway:watch` does not rebuild `dist/control-ui`, so rerun `pnpm ui:build` after `ui/` changes or use `pnpm ui:dev` while developing the Control UI.
+
+### 2) Point the macOS app at your running Gateway
+
+In **OpenClaw.app**:
+
+- Connection Mode: **Local**
+  The app will attach to the running gateway on the configured port.
+
+### 3) Verify
+
+- In-app Gateway status should read **"Using existing gateway …"**
+- Or via CLI:
+
+```bash
+openclaw health
+```
+
+### Common footguns
+
+- **Wrong port:** Gateway WS defaults to `ws://127.0.0.1:18789`; keep app + CLI on the same port.
+- **Where state lives:**
+  - Channel/provider state: `~/.openclaw/credentials/`
+  - Model auth profiles: `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
+  - Sessions: `~/.openclaw/agents/<agentId>/sessions/`
+  - Logs: `/tmp/openclaw/`
+
+## Credential storage map
+
+Use this when debugging auth or deciding what to back up:
+
+- **WhatsApp**: `~/.openclaw/credentials/whatsapp/<accountId>/creds.json`
+- **Telegram bot token**: config/env or `channels.telegram.tokenFile` (regular file only; symlinks rejected)
+- **Discord bot token**: config/env or SecretRef (env/file/exec providers)
+- **Slack tokens**: config/env (`channels.slack.*`)
+- **Pairing allowlists**:
+  - `~/.openclaw/credentials/<channel>-allowFrom.json` (default account)
+  - `~/.openclaw/credentials/<channel>-<accountId>-allowFrom.json` (non-default accounts)
+- **Model auth profiles**: `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
+- **File-backed secrets payload (optional)**: `~/.openclaw/secrets.json`
+- **Legacy OAuth import**: `~/.openclaw/credentials/oauth.json`
+  More detail: [Security](/gateway/security#credential-storage-map).
+
+## Updating (without wrecking your setup)
+
+- Keep `~/.openclaw/workspace` and `~/.openclaw/` as "your stuff"; don't put personal prompts/config into the `openclaw` repo.
+- Updating source: `git pull` + `pnpm install` + keep using `pnpm gateway:watch`.
+
+## Linux (systemd user service)
+
+Linux installs use a systemd **user** service. By default, systemd stops user
+services on logout/idle, which kills the Gateway. Onboarding attempts to enable
+lingering for you (may prompt for sudo). If it's still off, run:
+
+```bash
+sudo loginctl enable-linger $USER
+```
+
+For always-on or multi-user servers, consider a **system** service instead of a
+user service (no lingering needed). See [Gateway runbook](/gateway) for the systemd notes.
+
+## Related docs
+
+- [Gateway runbook](/gateway) (flags, supervision, ports)
+- [Gateway configuration](/gateway/configuration) (config schema + examples)
+- [Discord](/channels/discord) and [Telegram](/channels/telegram) (reply tags + replyToMode settings)
+- [OpenClaw assistant setup](/start/openclaw)
+- [macOS app](/platforms/macos) (gateway lifecycle)