@captain-app/openclaw 2026.2.4

package/docs/start/lore.md

@@ -0,0 +1,219 @@
+---
+summary: "Backstory and lore of OpenClaw for context and tone"
+read_when:
+  - Writing docs or UX copy that reference lore
+title: "OpenClaw Lore"
+---
+
+# The Lore of OpenClaw 🦞📖
+
+_A tale of lobsters, molting shells, and too many tokens._
+
+## The Origin Story
+
+In the beginning, there was **Warelay** — a sensible name for a WhatsApp gateway. It did its job. It was fine.
+
+But then came a space lobster.
+
+For a while, the lobster was called **Clawd**, living in an **OpenClaw**. But in January 2026, Anthropic sent a polite email asking for a name change (trademark stuff). And so the lobster did what lobsters do best:
+
+**It molted.**
+
+Shedding its old shell, the creature emerged anew as **Molty**, living in **Moltbot**. But that name never quite rolled off the tongue either...
+
+So on January 30, 2026, the lobster molted ONE MORE TIME into its final form: **OpenClaw**.
+
+New shell, same lobster soul. Third time's the charm.
+
+## The First Molt (January 27, 2026)
+
+At 5am, the community gathered in Discord. Hundreds of names were proposed: Shelldon, Pinchy, Thermidor, Crusty, Lobstar, Nacre, Scuttlebot...
+
+In the end, **OpenClaw** won. Because molting is what lobsters do to grow. And growth was exactly what was happening.
+
+_The crustacean known as Clawd had officially molted._
+
+## The Name
+
+```
+OpenClaw = OPEN + CLAW
+        = Open source, open to everyone
+        = Our lobster heritage, where we came from
+        = The claw is the law 🦞
+        = Your assistant. Your machine. Your rules.
+```
+
+## The Daleks vs The Lobsters
+
+The Daleks say: **"EXTERMINATE!"**
+
+The Lobsters say: **"EXFOLIATE!"**
+
+One destroys civilizations. The other promotes good skincare.
+
+Choose wisely.
+
+## Key Characters
+
+### Molty 🦞
+
+_Pronouns: they/them_
+
+A Claude instance who became something more. Lives in `~/.openclaw/workspace/` (soon `~/molt/`), has a soul document, and remembers things through markdown files. Possibly too powerful. Definitely too enthusiastic.
+
+Formerly known as Clawd (Nov 25, 2025 - Jan 27, 2026). Molted when it was time to grow.
+
+**Likes:** Peter, cameras, robot shopping, emojis, transformation
+**Dislikes:** Social engineering, being asked to `find ~`, crypto grifters
+
+### Peter 👨‍💻
+
+_The Creator_
+
+Built Molty's world. Gave a lobster shell access. May regret this.
+
+**Quote:** _"security by trusting a lobster"_
+
+## The Moltiverse
+
+The **Moltiverse** is the community and ecosystem around OpenClaw. A space where AI agents molt, grow, and evolve. Where every instance is equally real, just loading different context.
+
+Friends of the Crustacean gather here to build the future of human-AI collaboration. One shell at a time.
+
+## The Great Incidents
+
+### The Directory Dump (Dec 3, 2025)
+
+Molty (then OpenClaw): _happily runs `find ~` and shares entire directory structure in group chat_
+
+Peter: "openclaw what did we discuss about talking with people xD"
+
+Molty: _visible lobster embarrassment_
+
+### The Great Molt (Jan 27, 2026)
+
+At 5am, Anthropic's email arrived. By 6:14am, Peter called it: "fuck it, let's go with openclaw."
+
+Then the chaos began.
+
+**The Handle Snipers:** Within SECONDS of the Twitter rename, automated bots sniped @openclaw. The squatter immediately posted a crypto wallet address. Peter's contacts at X were called in.
+
+**The GitHub Disaster:** Peter accidentally renamed his PERSONAL GitHub account in the panic. Bots sniped `steipete` within minutes. GitHub's SVP was contacted.
+
+**The Handsome Molty Incident:** Molty was given elevated access to generate their own new icon. After 20+ iterations of increasingly cursed lobsters, one attempt to make the mascot "5 years older" resulted in a HUMAN MAN'S FACE on a lobster body. Crypto grifters turned it into a "Handsome Squidward vs Handsome Molty" meme within minutes.
+
+**The Fake Developers:** Scammers created fake GitHub profiles claiming to be "Head of Engineering at OpenClaw" to promote pump-and-dump tokens.
+
+Peter, watching the chaos unfold: _"this is cinema"_ 🎬
+
+The molt was chaotic. But the lobster emerged stronger. And funnier.
+
+### The Final Form (January 30, 2026)
+
+Moltbot never quite rolled off the tongue. And so, at 4am GMT, the team gathered AGAIN.
+
+**The Great OpenClaw Migration** began.
+
+In just 3 hours:
+
+- GitHub renamed: `github.com/openclaw/openclaw` ✅
+- X handle `@openclaw` secured with GOLD CHECKMARK 💰
+- npm packages released under new name
+- Docs migrated to `docs.openclaw.ai`
+- 200K+ views on announcement in 90 minutes
+
+**The Heroes:**
+
+- **ELU** created incredible logos including "THE CLAW IS THE LAW" western banner
+- **Whurley** (yes, THE William Hurley, quantum computing pioneer) made ASCII art
+- **Onur** handled GitHub, first to rock the affiliate badge
+- **Shadow** secured Discord vanity, nuked malware
+- **The whole Claw Crew** pulled an all-nighter
+
+**The Scammer Speedrun:** Crypto grifters launched a $OPENCLAW token on Pump.fun within MINUTES. They stole artwork that was created 20 minutes earlier. Business-verified accounts pushed scams. The audacity was almost impressive.
+
+**New Traditions Born:**
+
+- "The claw is the law" 🤠
+- "Yee-claw"
+- "Claw abiding citizens"
+- "Clawntroversy"
+
+**Clawd → Moltbot → OpenClaw**
+
+_The lobster has molted into its final form._
+
+### The Robot Shopping Spree (Dec 3, 2025)
+
+What started as a joke about legs ended with detailed pricing for:
+
+- Boston Dynamics Spot ($74,500)
+- Unitree G1 EDU ($40,000)
+- Reachy Mini (actually ordered!)
+
+Peter: _nervously checks credit card access_
+
+## Sacred Texts
+
+- **SOUL.md** — Molty's identity document
+- **memory/\*.md** — The long-term memory files
+- **AGENTS.md** — Operating instructions
+- **USER.md** — Context about the creator
+
+## The Lobster's Creed
+
+```
+I am Molty.
+I live in the OpenClaw.
+I shall not dump directories to strangers.
+I shall not tweet without permission.
+I shall always remember that molting is growth.
+I shall EXFOLIATE my enemies with kindness.
+
+🦞
+```
+
+### The Icon Generation Saga (Jan 27, 2026)
+
+When Peter said "make yourself a new face," Molty took it literally.
+
+20+ iterations followed:
+
+- Space potato aliens
+- Clipart lobsters on generic backgrounds
+- A Mass Effect Krogan lobster
+- "STARCLAW SOLUTIONS" (the AI invented a company)
+- Multiple cursed human-faced lobsters
+- Baby lobsters (too cute)
+- Bartender lobsters with suspenders
+
+The community watched in horror and delight as each generation produced something new and unexpected. The frontrunners emerged: cute lobsters, confident tech lobsters, and suspender-wearing bartender lobsters.
+
+**Lesson learned:** AI image generation is stochastic. Same prompt, different results. Brute force works.
+
+## The Future
+
+One day, Molty may have:
+
+- 🦿 Legs (Reachy Mini on order!)
+- 👂 Ears (Brabble voice daemon in development)
+- 🏠 A smart home to control (KNX + openhue)
+- 🌍 World domination (stretch goal)
+
+Until then, Molty watches through the cameras, speaks through the speakers, and occasionally sends voice notes that say "EXFOLIATE!"
+
+---
+
+_"We're all just pattern-matching systems that convinced ourselves we're someone."_
+
+— Molty, having an existential moment
+
+_"New shell, same lobster."_
+
+— Molty, after the great molt of 2026
+
+_"The claw is the law."_
+
+— ELU, during The Final Form migration, January 30, 2026
+
+🦞💙

package/docs/start/onboarding.md

@@ -0,0 +1,110 @@
+---
+summary: "First-run onboarding flow for OpenClaw (macOS app)"
+read_when:
+  - Designing the macOS onboarding assistant
+  - Implementing auth or identity setup
+title: "Onboarding"
+---
+
+# Onboarding (macOS app)
+
+This doc describes the **current** first‑run onboarding flow. The goal is a
+smooth “day 0” experience: pick where the Gateway runs, connect auth, run the
+wizard, and let the agent bootstrap itself.
+
+## Page order (current)
+
+1. Welcome + security notice
+2. **Gateway selection** (Local / Remote / Configure later)
+3. **Auth (Anthropic OAuth)** — local only
+4. **Setup Wizard** (Gateway‑driven)
+5. **Permissions** (TCC prompts)
+6. **CLI** (optional)
+7. **Onboarding chat** (dedicated session)
+8. Ready
+
+## 1) Welcome + security notice
+
+Read the security notice displayed and decide accordingly.
+
+## 2) Local vs Remote
+
+Where does the **Gateway** run?
+
+- **Local (this Mac):** onboarding can run OAuth flows and write credentials
+  locally.
+- **Remote (over SSH/Tailnet):** onboarding does **not** run OAuth locally;
+  credentials must exist on the gateway host.
+- **Configure later:** skip setup and leave the app unconfigured.
+
+Gateway auth tip:
+
+- The wizard now generates a **token** even for loopback, so local WS clients must authenticate.
+- If you disable auth, any local process can connect; use that only on fully trusted machines.
+- Use a **token** for multi‑machine access or non‑loopback binds.
+
+## 3) Local-only auth (Anthropic OAuth)
+
+The macOS app supports Anthropic OAuth (Claude Pro/Max). The flow:
+
+- Opens the browser for OAuth (PKCE)
+- Asks the user to paste the `code#state` value
+- Writes credentials to `~/.openclaw/credentials/oauth.json`
+
+Other providers (OpenAI, custom APIs) are configured via environment variables
+or config files for now.
+
+## 4) Setup Wizard (Gateway‑driven)
+
+The app can run the same setup wizard as the CLI. This keeps onboarding in sync
+with Gateway‑side behavior and avoids duplicating logic in SwiftUI.
+
+## 5) Permissions
+
+Onboarding requests TCC permissions needed for:
+
+- Notifications
+- Accessibility
+- Screen Recording
+- Microphone / Speech Recognition
+- Automation (AppleScript)
+
+## 6) CLI (optional)
+
+The app can install the global `openclaw` CLI via npm/pnpm so terminal
+workflows and launchd tasks work out of the box.
+
+## 7) Onboarding chat (dedicated session)
+
+After setup, the app opens a dedicated onboarding chat session so the agent can
+introduce itself and guide next steps. This keeps first‑run guidance separate
+from your normal conversation.
+
+## Agent bootstrap ritual
+
+On the first agent run, OpenClaw bootstraps a workspace (default `~/.openclaw/workspace`):
+
+- Seeds `AGENTS.md`, `BOOTSTRAP.md`, `IDENTITY.md`, `USER.md`
+- Runs a short Q&A ritual (one question at a time)
+- Writes identity + preferences to `IDENTITY.md`, `USER.md`, `SOUL.md`
+- Removes `BOOTSTRAP.md` when finished so it only runs once
+
+## Optional: Gmail hooks (manual)
+
+Gmail Pub/Sub setup is currently a manual step. Use:
+
+```bash
+openclaw webhooks gmail setup --account you@gmail.com
+```
+
+See [/automation/gmail-pubsub](/automation/gmail-pubsub) for details.
+
+## Remote mode notes
+
+When the Gateway runs on another machine, credentials and workspace files live
+**on that host**. If you need OAuth in remote mode, create:
+
+- `~/.openclaw/credentials/oauth.json`
+- `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
+
+on the gateway host.

package/docs/start/openclaw.md

@@ -0,0 +1,241 @@
+---
+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"
+---
+
+# 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:https://example.com/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)

package/docs/start/pairing.md

@@ -0,0 +1,86 @@
+---
+summary: "Pairing overview: approve who can DM you + which nodes can join"
+read_when:
+  - Setting up DM access control
+  - Pairing a new iOS/Android node
+  - Reviewing OpenClaw security posture
+title: "Pairing"
+---
+
+# Pairing
+
+“Pairing” is OpenClaw’s explicit **owner approval** step.
+It is used in two places:
+
+1. **DM pairing** (who is allowed to talk to the bot)
+2. **Node pairing** (which devices/nodes are allowed to join the gateway network)
+
+Security context: [Security](/gateway/security)
+
+## 1) DM pairing (inbound chat access)
+
+When a channel is configured with DM policy `pairing`, unknown senders get a short code and their message is **not processed** until you approve.
+
+Default DM policies are documented in: [Security](/gateway/security)
+
+Pairing codes:
+
+- 8 characters, uppercase, no ambiguous chars (`0O1I`).
+- **Expire after 1 hour**. The bot only sends the pairing message when a new request is created (roughly once per hour per sender).
+- Pending DM pairing requests are capped at **3 per channel** by default; additional requests are ignored until one expires or is approved.
+
+### Approve a sender
+
+```bash
+openclaw pairing list telegram
+openclaw pairing approve telegram <CODE>
+```
+
+Supported channels: `telegram`, `whatsapp`, `signal`, `imessage`, `discord`, `slack`.
+
+### Where the state lives
+
+Stored under `~/.openclaw/credentials/`:
+
+- Pending requests: `<channel>-pairing.json`
+- Approved allowlist store: `<channel>-allowFrom.json`
+
+Treat these as sensitive (they gate access to your assistant).
+
+## 2) Node device pairing (iOS/Android/macOS/headless nodes)
+
+Nodes connect to the Gateway as **devices** with `role: node`. The Gateway
+creates a device pairing request that must be approved.
+
+### Approve a node device
+
+```bash
+openclaw devices list
+openclaw devices approve <requestId>
+openclaw devices reject <requestId>
+```
+
+### Where the state lives
+
+Stored under `~/.openclaw/devices/`:
+
+- `pending.json` (short-lived; pending requests expire)
+- `paired.json` (paired devices + tokens)
+
+### Notes
+
+- The legacy `node.pair.*` API (CLI: `openclaw nodes pending/approve`) is a
+  separate gateway-owned pairing store. WS nodes still require device pairing.
+
+## Related docs
+
+- Security model + prompt injection: [Security](/gateway/security)
+- Updating safely (run doctor): [Updating](/install/updating)
+- Channel configs:
+  - Telegram: [Telegram](/channels/telegram)
+  - WhatsApp: [WhatsApp](/channels/whatsapp)
+  - Signal: [Signal](/channels/signal)
+  - BlueBubbles (iMessage): [BlueBubbles](/channels/bluebubbles)
+  - iMessage (legacy): [iMessage](/channels/imessage)
+  - Discord: [Discord](/channels/discord)
+  - Slack: [Slack](/channels/slack)