@captain-app/openclaw 2026.2.4

package/docs/images/groups-flow.svg

@@ -0,0 +1,52 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="960" height="260" viewBox="0 0 960 260" role="img" aria-label="Group message flow">
+  <defs>
+    <style>
+      .box { fill: #f6f5f3; stroke: #2b2b2b; stroke-width: 2; }
+      .drop { fill: #fff1f1; stroke: #a33; stroke-width: 2; }
+      .note { fill: #fffaf0; stroke: #9a7b00; stroke-width: 2; }
+      .text { font: 14px "SF Pro Text", -apple-system, Helvetica, Arial, sans-serif; fill: #1a1a1a; }
+      .label { font: 12px "SF Pro Text", -apple-system, Helvetica, Arial, sans-serif; fill: #333; }
+      .arrow { stroke: #2b2b2b; stroke-width: 2; fill: none; marker-end: url(#arrow); }
+    </style>
+    <marker id="arrow" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto">
+      <path d="M0,0 L8,3 L0,6 Z" fill="#2b2b2b" />
+    </marker>
+  </defs>
+
+  <rect class="box" x="20" y="40" width="140" height="60" rx="8" />
+  <text class="text" x="90" y="75" text-anchor="middle">Group message</text>
+
+  <rect class="box" x="200" y="40" width="160" height="60" rx="8" />
+  <text class="text" x="280" y="68" text-anchor="middle">Group policy</text>
+  <text class="label" x="280" y="86" text-anchor="middle">open / disabled / allowlist</text>
+
+  <rect class="box" x="400" y="40" width="150" height="60" rx="8" />
+  <text class="text" x="475" y="75" text-anchor="middle">Allowlist</text>
+
+  <rect class="box" x="580" y="40" width="170" height="60" rx="8" />
+  <text class="text" x="665" y="68" text-anchor="middle">Mention gating</text>
+  <text class="label" x="665" y="86" text-anchor="middle">requireMention</text>
+
+  <rect class="box" x="780" y="40" width="140" height="60" rx="8" />
+  <text class="text" x="850" y="75" text-anchor="middle">Reply</text>
+
+  <line class="arrow" x1="160" y1="70" x2="200" y2="70" />
+  <line class="arrow" x1="360" y1="70" x2="400" y2="70" />
+  <line class="arrow" x1="550" y1="70" x2="580" y2="70" />
+  <line class="arrow" x1="750" y1="70" x2="780" y2="70" />
+
+  <rect class="drop" x="220" y="150" width="120" height="50" rx="8" />
+  <text class="text" x="280" y="180" text-anchor="middle">Drop</text>
+  <line class="arrow" x1="280" y1="100" x2="280" y2="150" />
+  <text class="label" x="250" y="130" text-anchor="end">disabled</text>
+
+  <rect class="drop" x="410" y="150" width="120" height="50" rx="8" />
+  <text class="text" x="470" y="180" text-anchor="middle">Drop</text>
+  <line class="arrow" x1="475" y1="100" x2="470" y2="150" />
+  <text class="label" x="445" y="130" text-anchor="end">not allowed</text>
+
+  <rect class="note" x="600" y="150" width="200" height="50" rx="8" />
+  <text class="text" x="700" y="175" text-anchor="middle">Store for context</text>
+  <text class="label" x="700" y="192" text-anchor="middle">(no mention)</text>
+  <line class="arrow" x1="665" y1="100" x2="700" y2="150" />
+</svg>

package/docs/index.md

@@ -0,0 +1,258 @@
+---
+summary: "Top-level overview of OpenClaw, features, and purpose"
+read_when:
+  - Introducing OpenClaw to newcomers
+title: "OpenClaw"
+---
+
+# OpenClaw 🦞
+
+> _"EXFOLIATE! EXFOLIATE!"_ — A space lobster, probably
+
+<p align="center">
+    <img
+        src="/assets/openclaw-logo-text-dark.png"
+        alt="OpenClaw"
+        width="500"
+        class="dark:hidden"
+    />
+    <img
+        src="/assets/openclaw-logo-text.png"
+        alt="OpenClaw"
+        width="500"
+        class="hidden dark:block"
+    />
+</p>
+
+<p align="center">
+  <strong>Any OS + WhatsApp/Telegram/Discord/iMessage gateway for AI agents (Pi).</strong><br />
+  Plugins add Mattermost and more.
+  Send a message, get an agent response — from your pocket.
+</p>
+
+<p align="center">
+  <a href="https://github.com/openclaw/openclaw">GitHub</a> ·
+  <a href="https://github.com/openclaw/openclaw/releases">Releases</a> ·
+  <a href="/">Docs</a> ·
+  <a href="/start/openclaw">OpenClaw assistant setup</a>
+</p>
+
+OpenClaw bridges WhatsApp (via WhatsApp Web / Baileys), Telegram (Bot API / grammY), Discord (Bot API / channels.discord.js), and iMessage (imsg CLI) to coding agents like [Pi](https://github.com/badlogic/pi-mono). Plugins add Mattermost (Bot API + WebSocket) and more.
+OpenClaw also powers the OpenClaw assistant.
+
+## Start here
+
+- **New install from zero:** [Getting Started](/start/getting-started)
+- **Guided setup (recommended):** [Wizard](/start/wizard) (`openclaw onboard`)
+- **Open the dashboard (local Gateway):** http://127.0.0.1:18789/ (or http://localhost:18789/)
+
+If the Gateway is running on the same computer, that link opens the browser Control UI
+immediately. If it fails, start the Gateway first: `openclaw gateway`.
+
+## Dashboard (browser Control UI)
+
+The dashboard is the browser Control UI for chat, config, nodes, sessions, and more.
+Local default: http://127.0.0.1:18789/
+Remote access: [Web surfaces](/web) and [Tailscale](/gateway/tailscale)
+
+<p align="center">
+  <img src="whatsapp-openclaw.jpg" alt="OpenClaw" width="420" />
+</p>
+
+## How it works
+
+```
+WhatsApp / Telegram / Discord / iMessage (+ plugins)
+        │
+        ▼
+  ┌───────────────────────────┐
+  │          Gateway          │  ws://127.0.0.1:18789 (loopback-only)
+  │     (single source)       │
+  │                           │  http://<gateway-host>:18793
+  │                           │    /__openclaw__/canvas/ (Canvas host)
+  └───────────┬───────────────┘
+              │
+              ├─ Pi agent (RPC)
+              ├─ CLI (openclaw …)
+              ├─ Chat UI (SwiftUI)
+              ├─ macOS app (OpenClaw.app)
+              ├─ iOS node via Gateway WS + pairing
+              └─ Android node via Gateway WS + pairing
+```
+
+Most operations flow through the **Gateway** (`openclaw gateway`), a single long-running process that owns channel connections and the WebSocket control plane.
+
+## Network model
+
+- **One Gateway per host (recommended)**: it is the only process allowed to own the WhatsApp Web session. If you need a rescue bot or strict isolation, run multiple gateways with isolated profiles and ports; see [Multiple gateways](/gateway/multiple-gateways).
+- **Loopback-first**: Gateway WS defaults to `ws://127.0.0.1:18789`.
+  - The wizard now generates a gateway token by default (even for loopback).
+  - For Tailnet access, run `openclaw gateway --bind tailnet --token ...` (token is required for non-loopback binds).
+- **Nodes**: connect to the Gateway WebSocket (LAN/tailnet/SSH as needed); legacy TCP bridge is deprecated/removed.
+- **Canvas host**: HTTP file server on `canvasHost.port` (default `18793`), serving `/__openclaw__/canvas/` for node WebViews; see [Gateway configuration](/gateway/configuration) (`canvasHost`).
+- **Remote use**: SSH tunnel or tailnet/VPN; see [Remote access](/gateway/remote) and [Discovery](/gateway/discovery).
+
+## Features (high level)
+
+- 📱 **WhatsApp Integration** — Uses Baileys for WhatsApp Web protocol
+- ✈️ **Telegram Bot** — DMs + groups via grammY
+- 🎮 **Discord Bot** — DMs + guild channels via channels.discord.js
+- 🧩 **Mattermost Bot (plugin)** — Bot token + WebSocket events
+- 💬 **iMessage** — Local imsg CLI integration (macOS)
+- 🤖 **Agent bridge** — Pi (RPC mode) with tool streaming
+- ⏱️ **Streaming + chunking** — Block streaming + Telegram draft streaming details ([/concepts/streaming](/concepts/streaming))
+- 🧠 **Multi-agent routing** — Route provider accounts/peers to isolated agents (workspace + per-agent sessions)
+- 🔐 **Subscription auth** — Anthropic (Claude Pro/Max) + OpenAI (ChatGPT/Codex) via OAuth
+- 💬 **Sessions** — Direct chats collapse into shared `main` (default); groups are isolated
+- 👥 **Group Chat Support** — Mention-based by default; owner can toggle `/activation always|mention`
+- 📎 **Media Support** — Send and receive images, audio, documents
+- 🎤 **Voice notes** — Optional transcription hook
+- 🖥️ **WebChat + macOS app** — Local UI + menu bar companion for ops and voice wake
+- 📱 **iOS node** — Pairs as a node and exposes a Canvas surface
+- 📱 **Android node** — Pairs as a node and exposes Canvas + Chat + Camera
+
+Note: legacy Claude/Codex/Gemini/Opencode paths have been removed; Pi is the only coding-agent path.
+
+## Quick start
+
+Runtime requirement: **Node ≥ 22**.
+
+```bash
+# Recommended: global install (npm/pnpm)
+npm install -g openclaw@latest
+# or: pnpm add -g openclaw@latest
+
+# Onboard + install the service (launchd/systemd user service)
+openclaw onboard --install-daemon
+
+# Pair WhatsApp Web (shows QR)
+openclaw channels login
+
+# Gateway runs via the service after onboarding; manual run is still possible:
+openclaw gateway --port 18789
+```
+
+Switching between npm and git installs later is easy: install the other flavor and run `openclaw doctor` to update the gateway service entrypoint.
+
+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
+openclaw onboard --install-daemon
+```
+
+If you don’t have a global install yet, run the onboarding step via `pnpm openclaw ...` from the repo.
+
+Multi-instance quickstart (optional):
+
+```bash
+OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \
+OPENCLAW_STATE_DIR=~/.openclaw-a \
+openclaw gateway --port 19001
+```
+
+Send a test message (requires a running Gateway):
+
+```bash
+openclaw message send --target +15555550123 --message "Hello from OpenClaw"
+```
+
+## Configuration (optional)
+
+Config lives at `~/.openclaw/openclaw.json`.
+
+- If you **do nothing**, OpenClaw uses the bundled Pi binary in RPC mode with per-sender sessions.
+- If you want to lock it down, start with `channels.whatsapp.allowFrom` and (for groups) mention rules.
+
+Example:
+
+```json5
+{
+  channels: {
+    whatsapp: {
+      allowFrom: ["+15555550123"],
+      groups: { "*": { requireMention: true } },
+    },
+  },
+  messages: { groupChat: { mentionPatterns: ["@openclaw"] } },
+}
+```
+
+## Docs
+
+- Start here:
+  - [Docs hubs (all pages linked)](/start/hubs)
+  - [Help](/help) ← _common fixes + troubleshooting_
+  - [Configuration](/gateway/configuration)
+  - [Configuration examples](/gateway/configuration-examples)
+  - [Slash commands](/tools/slash-commands)
+  - [Multi-agent routing](/concepts/multi-agent)
+  - [Updating / rollback](/install/updating)
+  - [Pairing (DM + nodes)](/start/pairing)
+  - [Nix mode](/install/nix)
+  - [OpenClaw assistant setup](/start/openclaw)
+  - [Skills](/tools/skills)
+  - [Skills config](/tools/skills-config)
+  - [Workspace templates](/reference/templates/AGENTS)
+  - [RPC adapters](/reference/rpc)
+  - [Gateway runbook](/gateway)
+  - [Nodes (iOS/Android)](/nodes)
+  - [Web surfaces (Control UI)](/web)
+  - [Discovery + transports](/gateway/discovery)
+  - [Remote access](/gateway/remote)
+- Providers and UX:
+  - [WebChat](/web/webchat)
+  - [Control UI (browser)](/web/control-ui)
+  - [Telegram](/channels/telegram)
+  - [Discord](/channels/discord)
+  - [Mattermost (plugin)](/channels/mattermost)
+  - [BlueBubbles (iMessage)](/channels/bluebubbles)
+  - [iMessage (legacy)](/channels/imessage)
+  - [Groups](/concepts/groups)
+  - [WhatsApp group messages](/concepts/group-messages)
+  - [Media: images](/nodes/images)
+  - [Media: audio](/nodes/audio)
+- Companion apps:
+  - [macOS app](/platforms/macos)
+  - [iOS app](/platforms/ios)
+  - [Android app](/platforms/android)
+  - [Windows (WSL2)](/platforms/windows)
+  - [Linux app](/platforms/linux)
+- Ops and safety:
+  - [Sessions](/concepts/session)
+  - [Cron jobs](/automation/cron-jobs)
+  - [Webhooks](/automation/webhook)
+  - [Gmail hooks (Pub/Sub)](/automation/gmail-pubsub)
+  - [Security](/gateway/security)
+  - [Troubleshooting](/gateway/troubleshooting)
+
+## The name
+
+**OpenClaw = CLAW + TARDIS** — because every space lobster needs a time-and-space machine.
+
+---
+
+_"We're all just playing with our own prompts."_ — an AI, probably high on tokens
+
+## Credits
+
+- **Peter Steinberger** ([@steipete](https://x.com/steipete)) — Creator, lobster whisperer
+- **Mario Zechner** ([@badlogicc](https://x.com/badlogicgames)) — Pi creator, security pen-tester
+- **Clawd** — The space lobster who demanded a better name
+
+## Core Contributors
+
+- **Maxim Vovshin** (@Hyaxia, 36747317+Hyaxia@users.noreply.github.com) — Blogwatcher skill
+- **Nacho Iacovino** (@nachoiacovino, nacho.iacovino@gmail.com) — Location parsing (Telegram + WhatsApp)
+
+## License
+
+MIT — Free as a lobster in the ocean 🦞
+
+---
+
+_"We're all just playing with our own prompts."_ — An AI, probably high on tokens

package/docs/install/ansible.md

@@ -0,0 +1,208 @@
+---
+summary: "Automated, hardened OpenClaw installation with Ansible, Tailscale VPN, and firewall isolation"
+read_when:
+  - You want automated server deployment with security hardening
+  - You need firewall-isolated setup with VPN access
+  - You're deploying to remote Debian/Ubuntu servers
+title: "Ansible"
+---
+
+# Ansible Installation
+
+The recommended way to deploy OpenClaw to production servers is via **[openclaw-ansible](https://github.com/openclaw/openclaw-ansible)** — an automated installer with security-first architecture.
+
+## Quick Start
+
+One-command install:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/openclaw/openclaw-ansible/main/install.sh | bash
+```
+
+> **📦 Full guide: [github.com/openclaw/openclaw-ansible](https://github.com/openclaw/openclaw-ansible)**
+>
+> The openclaw-ansible repo is the source of truth for Ansible deployment. This page is a quick overview.
+
+## What You Get
+
+- 🔒 **Firewall-first security**: UFW + Docker isolation (only SSH + Tailscale accessible)
+- 🔐 **Tailscale VPN**: Secure remote access without exposing services publicly
+- 🐳 **Docker**: Isolated sandbox containers, localhost-only bindings
+- 🛡️ **Defense in depth**: 4-layer security architecture
+- 🚀 **One-command setup**: Complete deployment in minutes
+- 🔧 **Systemd integration**: Auto-start on boot with hardening
+
+## Requirements
+
+- **OS**: Debian 11+ or Ubuntu 20.04+
+- **Access**: Root or sudo privileges
+- **Network**: Internet connection for package installation
+- **Ansible**: 2.14+ (installed automatically by quick-start script)
+
+## What Gets Installed
+
+The Ansible playbook installs and configures:
+
+1. **Tailscale** (mesh VPN for secure remote access)
+2. **UFW firewall** (SSH + Tailscale ports only)
+3. **Docker CE + Compose V2** (for agent sandboxes)
+4. **Node.js 22.x + pnpm** (runtime dependencies)
+5. **OpenClaw** (host-based, not containerized)
+6. **Systemd service** (auto-start with security hardening)
+
+Note: The gateway runs **directly on the host** (not in Docker), but agent sandboxes use Docker for isolation. See [Sandboxing](/gateway/sandboxing) for details.
+
+## Post-Install Setup
+
+After installation completes, switch to the openclaw user:
+
+```bash
+sudo -i -u openclaw
+```
+
+The post-install script will guide you through:
+
+1. **Onboarding wizard**: Configure OpenClaw settings
+2. **Provider login**: Connect WhatsApp/Telegram/Discord/Signal
+3. **Gateway testing**: Verify the installation
+4. **Tailscale setup**: Connect to your VPN mesh
+
+### Quick commands
+
+```bash
+# Check service status
+sudo systemctl status openclaw
+
+# View live logs
+sudo journalctl -u openclaw -f
+
+# Restart gateway
+sudo systemctl restart openclaw
+
+# Provider login (run as openclaw user)
+sudo -i -u openclaw
+openclaw channels login
+```
+
+## Security Architecture
+
+### 4-Layer Defense
+
+1. **Firewall (UFW)**: Only SSH (22) + Tailscale (41641/udp) exposed publicly
+2. **VPN (Tailscale)**: Gateway accessible only via VPN mesh
+3. **Docker Isolation**: DOCKER-USER iptables chain prevents external port exposure
+4. **Systemd Hardening**: NoNewPrivileges, PrivateTmp, unprivileged user
+
+### Verification
+
+Test external attack surface:
+
+```bash
+nmap -p- YOUR_SERVER_IP
+```
+
+Should show **only port 22** (SSH) open. All other services (gateway, Docker) are locked down.
+
+### Docker Availability
+
+Docker is installed for **agent sandboxes** (isolated tool execution), not for running the gateway itself. The gateway binds to localhost only and is accessible via Tailscale VPN.
+
+See [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools) for sandbox configuration.
+
+## Manual Installation
+
+If you prefer manual control over the automation:
+
+```bash
+# 1. Install prerequisites
+sudo apt update && sudo apt install -y ansible git
+
+# 2. Clone repository
+git clone https://github.com/openclaw/openclaw-ansible.git
+cd openclaw-ansible
+
+# 3. Install Ansible collections
+ansible-galaxy collection install -r requirements.yml
+
+# 4. Run playbook
+./run-playbook.sh
+
+# Or run directly (then manually execute /tmp/openclaw-setup.sh after)
+# ansible-playbook playbook.yml --ask-become-pass
+```
+
+## Updating OpenClaw
+
+The Ansible installer sets up OpenClaw for manual updates. See [Updating](/install/updating) for the standard update flow.
+
+To re-run the Ansible playbook (e.g., for configuration changes):
+
+```bash
+cd openclaw-ansible
+./run-playbook.sh
+```
+
+Note: This is idempotent and safe to run multiple times.
+
+## Troubleshooting
+
+### Firewall blocks my connection
+
+If you're locked out:
+
+- Ensure you can access via Tailscale VPN first
+- SSH access (port 22) is always allowed
+- The gateway is **only** accessible via Tailscale by design
+
+### Service won't start
+
+```bash
+# Check logs
+sudo journalctl -u openclaw -n 100
+
+# Verify permissions
+sudo ls -la /opt/openclaw
+
+# Test manual start
+sudo -i -u openclaw
+cd ~/openclaw
+pnpm start
+```
+
+### Docker sandbox issues
+
+```bash
+# Verify Docker is running
+sudo systemctl status docker
+
+# Check sandbox image
+sudo docker images | grep openclaw-sandbox
+
+# Build sandbox image if missing
+cd /opt/openclaw/openclaw
+sudo -u openclaw ./scripts/sandbox-setup.sh
+```
+
+### Provider login fails
+
+Make sure you're running as the `openclaw` user:
+
+```bash
+sudo -i -u openclaw
+openclaw channels login
+```
+
+## Advanced Configuration
+
+For detailed security architecture and troubleshooting:
+
+- [Security Architecture](https://github.com/openclaw/openclaw-ansible/blob/main/docs/security.md)
+- [Technical Details](https://github.com/openclaw/openclaw-ansible/blob/main/docs/architecture.md)
+- [Troubleshooting Guide](https://github.com/openclaw/openclaw-ansible/blob/main/docs/troubleshooting.md)
+
+## Related
+
+- [openclaw-ansible](https://github.com/openclaw/openclaw-ansible) — full deployment guide
+- [Docker](/install/docker) — containerized gateway setup
+- [Sandboxing](/gateway/sandboxing) — agent sandbox configuration
+- [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools) — per-agent isolation

package/docs/install/bun.md

@@ -0,0 +1,59 @@
+---
+summary: "Bun workflow (experimental): installs and gotchas vs pnpm"
+read_when:
+  - You want the fastest local dev loop (bun + watch)
+  - You hit Bun install/patch/lifecycle script issues
+title: "Bun (Experimental)"
+---
+
+# Bun (experimental)
+
+Goal: run this repo with **Bun** (optional, not recommended for WhatsApp/Telegram)
+without diverging from pnpm workflows.
+
+⚠️ **Not recommended for Gateway runtime** (WhatsApp/Telegram bugs). Use Node for production.
+
+## Status
+
+- Bun is an optional local runtime for running TypeScript directly (`bun run …`, `bun --watch …`).
+- `pnpm` is the default for builds and remains fully supported (and used by some docs tooling).
+- Bun cannot use `pnpm-lock.yaml` and will ignore it.
+
+## Install
+
+Default:
+
+```sh
+bun install
+```
+
+Note: `bun.lock`/`bun.lockb` are gitignored, so there’s no repo churn either way. If you want _no lockfile writes_:
+
+```sh
+bun install --no-save
+```
+
+## Build / Test (Bun)
+
+```sh
+bun run build
+bun run vitest run
+```
+
+## Bun lifecycle scripts (blocked by default)
+
+Bun may block dependency lifecycle scripts unless explicitly trusted (`bun pm untrusted` / `bun pm trust`).
+For this repo, the commonly blocked scripts are not required:
+
+- `@whiskeysockets/baileys` `preinstall`: checks Node major >= 20 (we run Node 22+).
+- `protobufjs` `postinstall`: emits warnings about incompatible version schemes (no build artifacts).
+
+If you hit a real runtime issue that requires these scripts, trust them explicitly:
+
+```sh
+bun pm trust @whiskeysockets/baileys protobufjs
+```
+
+## Caveats
+
+- Some scripts still hardcode pnpm (e.g. `docs:build`, `ui:*`, `protocol:check`). Run those via pnpm for now.

package/docs/install/development-channels.md

@@ -0,0 +1,75 @@
+---
+summary: "Stable, beta, and dev channels: semantics, switching, and tagging"
+read_when:
+  - You want to switch between stable/beta/dev
+  - You are tagging or publishing prereleases
+title: "Development Channels"
+---
+
+# Development channels
+
+Last updated: 2026-01-21
+
+OpenClaw ships three update channels:
+
+- **stable**: npm dist-tag `latest`.
+- **beta**: npm dist-tag `beta` (builds under test).
+- **dev**: moving head of `main` (git). npm dist-tag: `dev` (when published).
+
+We ship builds to **beta**, test them, then **promote a vetted build to `latest`**
+without changing the version number — dist-tags are the source of truth for npm installs.
+
+## Switching channels
+
+Git checkout:
+
+```bash
+openclaw update --channel stable
+openclaw update --channel beta
+openclaw update --channel dev
+```
+
+- `stable`/`beta` check out the latest matching tag (often the same tag).
+- `dev` switches to `main` and rebases on the upstream.
+
+npm/pnpm global install:
+
+```bash
+openclaw update --channel stable
+openclaw update --channel beta
+openclaw update --channel dev
+```
+
+This updates via the corresponding npm dist-tag (`latest`, `beta`, `dev`).
+
+When you **explicitly** switch channels with `--channel`, OpenClaw also aligns
+the install method:
+
+- `dev` ensures a git checkout (default `~/openclaw`, override with `OPENCLAW_GIT_DIR`),
+  updates it, and installs the global CLI from that checkout.
+- `stable`/`beta` installs from npm using the matching dist-tag.
+
+Tip: if you want stable + dev in parallel, keep two clones and point your gateway at the stable one.
+
+## Plugins and channels
+
+When you switch channels with `openclaw update`, OpenClaw also syncs plugin sources:
+
+- `dev` prefers bundled plugins from the git checkout.
+- `stable` and `beta` restore npm-installed plugin packages.
+
+## Tagging best practices
+
+- Tag releases you want git checkouts to land on (`vYYYY.M.D` or `vYYYY.M.D-<patch>`).
+- Keep tags immutable: never move or reuse a tag.
+- npm dist-tags remain the source of truth for npm installs:
+  - `latest` → stable
+  - `beta` → candidate build
+  - `dev` → main snapshot (optional)
+
+## macOS app availability
+
+Beta and dev builds may **not** include a macOS app release. That’s OK:
+
+- The git tag and npm dist-tag can still be published.
+- Call out “no macOS build for this beta” in release notes or changelog.