@gguf/claw 2026.2.4 → 2026.2.5

package/docs/start/getting-started.md

@@ -1,208 +1,120 @@
 ---
-summary: "Beginner guide: from zero to first message (wizard, auth, channels, pairing)"
+summary: "Get OpenClaw installed and run your first chat in minutes."
 read_when:
   - First time setup from zero
-  - You want the fastest path from install → onboarding → first message
+  - You want the fastest path to a working chat
 title: "Getting Started"
 ---
 
 # Getting Started
 
-Goal: go from **zero** → **first working chat** (with sane defaults) as quickly as possible.
+Goal: go from zero to a first working chat with minimal setup.
 
+<Info>
 Fastest chat: open the Control UI (no channel setup needed). Run `openclaw dashboard`
-and chat in the browser, or open `http://127.0.0.1:18789/` on the gateway host.
+and chat in the browser, or open `http://127.0.0.1:18789/` on the
+<Tooltip headline="Gateway host" tip="The machine running the OpenClaw gateway service.">gateway host</Tooltip>.
 Docs: [Dashboard](/web/dashboard) and [Control UI](/web/control-ui).
-
-Recommended path: use the **CLI onboarding wizard** (`openclaw onboard`). It sets up:
-
-- model/auth (OAuth recommended)
-- gateway settings
-- channels (WhatsApp/Telegram/Discord/Mattermost (plugin)/...)
-- pairing defaults (secure DMs)
-- workspace bootstrap + skills
-- optional background service
-
-If you want the deeper reference pages, jump to: [Wizard](/start/wizard), [Setup](/start/setup), [Pairing](/start/pairing), [Security](/gateway/security).
-
-Sandboxing note: `agents.defaults.sandbox.mode: "non-main"` uses `session.mainKey` (default `"main"`),
-so group/channel sessions are sandboxed. If you want the main agent to always
-run on host, set an explicit per-agent override:
-
-```json
-{
-  "routing": {
-    "agents": {
-      "main": {
-        "workspace": "~/.openclaw/workspace",
-        "sandbox": { "mode": "off" }
-      }
-    }
-  }
-}
-```
-
-## 0) Prereqs
-
-- Node `>=22`
-- `pnpm` (optional; recommended if you build from source)
-- **Recommended:** Brave Search API key for web search. Easiest path:
-  `openclaw configure --section web` (stores `tools.web.search.apiKey`).
-  See [Web tools](/tools/web).
-
-macOS: if you plan to build the apps, install Xcode / CLT. For the CLI + gateway only, Node is enough.
-Windows: use **WSL2** (Ubuntu recommended). WSL2 is strongly recommended; native Windows is untested, more problematic, and has poorer tool compatibility. Install WSL2 first, then run the Linux steps inside WSL. See [Windows (WSL2)](/platforms/windows).
-
-## 1) Install the CLI (recommended)
-
-```bash
-curl -fsSL https://openclaw.ai/install.sh | bash
-```
-
-Installer options (install method, non-interactive, from GitHub): [Install](/install).
-
-Windows (PowerShell):
-
-```powershell
-iwr -useb https://openclaw.ai/install.ps1 | iex
-```
-
-Alternative (global install):
-
-```bash
-npm install -g openclaw@latest
-```
-
-```bash
-pnpm add -g openclaw@latest
-```
-
-## 2) Run the onboarding wizard (and install the service)
-
-```bash
-openclaw onboard --install-daemon
-```
-
-What you’ll choose:
-
-- **Local vs Remote** gateway
-- **Auth**: OpenAI Code (Codex) subscription (OAuth) or API keys. For Anthropic we recommend an API key; `claude setup-token` is also supported.
-- **Providers**: WhatsApp QR login, Telegram/Discord bot tokens, Mattermost plugin tokens, etc.
-- **Daemon**: background install (launchd/systemd; WSL2 uses systemd)
-  - **Runtime**: Node (recommended; required for WhatsApp/Telegram). Bun is **not recommended**.
-- **Gateway token**: the wizard generates one by default (even on loopback) and stores it in `gateway.auth.token`.
-
-Wizard doc: [Wizard](/start/wizard)
-
-### Auth: where it lives (important)
-
-- **Recommended Anthropic path:** set an API key (wizard can store it for service use). `claude setup-token` is also supported if you want to reuse Claude Code credentials.
-
-- OAuth credentials (legacy import): `~/.openclaw/credentials/oauth.json`
-- Auth profiles (OAuth + API keys): `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
-
-Headless/server tip: do OAuth on a normal machine first, then copy `oauth.json` to the gateway host.
-
-## 3) Start the Gateway
-
-If you installed the service during onboarding, the Gateway should already be running:
-
-```bash
-openclaw gateway status
-```
-
-Manual run (foreground):
-
-```bash
-openclaw gateway --port 18789 --verbose
-```
-
-Dashboard (local loopback): `http://127.0.0.1:18789/`
-If a token is configured, paste it into the Control UI settings (stored as `connect.params.auth.token`).
-
-⚠️ **Bun warning (WhatsApp + Telegram):** Bun has known issues with these
-channels. If you use WhatsApp or Telegram, run the Gateway with **Node**.
-
-## 3.5) Quick verify (2 min)
-
-```bash
-openclaw status
-openclaw health
-openclaw security audit --deep
-```
-
-## 4) Pair + connect your first chat surface
-
-### WhatsApp (QR login)
-
-```bash
-openclaw channels login
-```
-
-Scan via WhatsApp → Settings → Linked Devices.
-
-WhatsApp doc: [WhatsApp](/channels/whatsapp)
-
-### Telegram / Discord / others
-
-The wizard can write tokens/config for you. If you prefer manual config, start with:
-
-- Telegram: [Telegram](/channels/telegram)
-- Discord: [Discord](/channels/discord)
-- Mattermost (plugin): [Mattermost](/channels/mattermost)
-
-**Telegram DM tip:** your first DM returns a pairing code. Approve it (see next step) or the bot won’t respond.
-
-## 5) DM safety (pairing approvals)
-
-Default posture: unknown DMs get a short code and messages are not processed until approved.
-If your first DM gets no reply, approve the pairing:
-
-```bash
-openclaw pairing list whatsapp
-openclaw pairing approve whatsapp <code>
-```
-
-Pairing doc: [Pairing](/start/pairing)
-
-## From source (development)
-
-If you’re hacking on OpenClaw itself, run from source:
-
-```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.
-`pnpm build` also bundles A2UI assets; if you need to run just that step, use `pnpm canvas:a2ui:bundle`.
-
-Gateway (from this repo):
-
-```bash
-node openclaw.mjs gateway --port 18789 --verbose
-```
-
-## 7) Verify end-to-end
-
-In a new terminal, send a test message:
-
-```bash
-openclaw message send --target +15555550123 --message "Hello from OpenClaw"
-```
-
-If `openclaw health` shows “no auth configured”, go back to the wizard and set OAuth/key auth — the agent won’t be able to respond without it.
-
-Tip: `openclaw status --all` is the best pasteable, read-only debug report.
-Health probes: `openclaw health` (or `openclaw status --deep`) asks the running gateway for a health snapshot.
-
-## Next steps (optional, but great)
-
-- macOS menu bar app + voice wake: [macOS app](/platforms/macos)
-- iOS/Android nodes (Canvas/camera/voice): [Nodes](/nodes)
-- Remote access (SSH tunnel / Tailscale Serve): [Remote access](/gateway/remote) and [Tailscale](/gateway/tailscale)
-- Always-on / VPN setups: [Remote access](/gateway/remote), [exe.dev](/platforms/exe-dev), [Hetzner](/platforms/hetzner), [macOS remote](/platforms/mac/remote)
+</Info>
+
+## Prereqs
+
+- Node 22 or newer
+
+<Tip>
+Check your Node version with `node --version` if you are unsure.
+</Tip>
+
+## Quick setup (CLI)
+
+<Steps>
+  <Step title="Install OpenClaw (recommended)">
+    <Tabs>
+      <Tab title="macOS/Linux">
+        ```bash
+        curl -fsSL https://openclaw.ai/install.sh | bash
+        ```
+      </Tab>
+      <Tab title="Windows (PowerShell)">
+        ```powershell
+        iwr -useb https://openclaw.ai/install.ps1 | iex
+        ```
+      </Tab>
+    </Tabs>
+
+    <Note>
+    Other install methods and requirements: [Install](/install).
+    </Note>
+
+  </Step>
+  <Step title="Run the onboarding wizard">
+    ```bash
+    openclaw onboard --install-daemon
+    ```
+
+    The wizard configures auth, gateway settings, and optional channels.
+    See [Onboarding Wizard](/start/wizard) for details.
+
+  </Step>
+  <Step title="Check the Gateway">
+    If you installed the service, it should already be running:
+
+    ```bash
+    openclaw gateway status
+    ```
+
+  </Step>
+  <Step title="Open the Control UI">
+    ```bash
+    openclaw dashboard
+    ```
+  </Step>
+</Steps>
+
+<Check>
+If the Control UI loads, your Gateway is ready for use.
+</Check>
+
+## Optional checks and extras
+
+<AccordionGroup>
+  <Accordion title="Run the Gateway in the foreground">
+    Useful for quick tests or troubleshooting.
+
+    ```bash
+    openclaw gateway --port 18789
+    ```
+
+  </Accordion>
+  <Accordion title="Send a test message">
+    Requires a configured channel.
+
+    ```bash
+    openclaw message send --target +15555550123 --message "Hello from OpenClaw"
+    ```
+
+  </Accordion>
+</AccordionGroup>
+
+## Go deeper
+
+<Columns>
+  <Card title="Onboarding Wizard (details)" href="/start/wizard">
+    Full CLI wizard reference and advanced options.
+  </Card>
+  <Card title="macOS app onboarding" href="/start/onboarding">
+    First run flow for the macOS app.
+  </Card>
+</Columns>
+
+## What you will have
+
+- A running Gateway
+- Auth configured
+- Control UI access or a connected channel
+
+## Next steps
+
+- DM safety and approvals: [Pairing](/start/pairing)
+- Connect more channels: [Channels](/channels)
+- Advanced workflows and from source: [Setup](/start/setup)

package/docs/start/hubs.md

@@ -7,17 +7,23 @@ title: "Docs Hubs"
 
 # Docs hubs
 
+<Note>
+If you are new to OpenClaw, start with [Getting Started](/start/getting-started).
+</Note>
+
 Use these hubs to discover every page, including deep dives and reference docs that don’t appear in the left nav.
 
 ## Start here
 
 - [Index](/)
 - [Getting Started](/start/getting-started)
+- [Quick start](/start/quickstart)
 - [Onboarding](/start/onboarding)
 - [Wizard](/start/wizard)
 - [Setup](/start/setup)
 - [Dashboard (local Gateway)](http://127.0.0.1:18789/)
 - [Help](/help)
+- [Docs directory](/start/docs-directory)
 - [Configuration](/gateway/configuration)
 - [Configuration examples](/gateway/configuration-examples)
 - [OpenClaw assistant](/start/openclaw)
@@ -34,6 +40,7 @@ Use these hubs to discover every page, including deep dives and reference docs t
 ## Core concepts
 
 - [Architecture](/concepts/architecture)
+- [Features](/concepts/features)
 - [Network hub](/network)
 - [Agent runtime](/concepts/agent)
 - [Agent workspace](/concepts/agent-workspace)
@@ -81,6 +88,7 @@ Use these hubs to discover every page, including deep dives and reference docs t
 ## Gateway + operations
 
 - [Gateway runbook](/gateway)
+- [Network model](/gateway/network-model)
 - [Gateway pairing](/gateway/pairing)
 - [Gateway lock](/gateway/gateway-lock)
 - [Background process](/gateway/background-process)
@@ -178,6 +186,10 @@ Use these hubs to discover every page, including deep dives and reference docs t
 - [Research: memory](/experiments/research/memory)
 - [Model config exploration](/experiments/proposals/model-config)
 
+## Project
+
+- [Credits](/reference/credits)
+
 ## Testing + release
 
 - [Testing](/reference/test)

package/docs/start/onboarding.md

@@ -3,108 +3,78 @@ summary: "First-run onboarding flow for OpenClaw (macOS app)"
 read_when:
   - Designing the macOS onboarding assistant
   - Implementing auth or identity setup
-title: "Onboarding"
+title: "Onboarding (macOS App)"
+sidebarTitle: "Onboarding: macOS App"
 ---
 
-# Onboarding (macOS app)
+# 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
+<Steps>
+<Step title="Approve macOS warning">
+<Frame>
+<img src="/assets/macos-onboarding/01-macos-warning.jpeg" alt="" />
+</Frame>
+</Step>
+<Step title="Approve find local networks">
+<Frame>
+<img src="/assets/macos-onboarding/02-local-networks.jpeg" alt="" />
+</Frame>
+</Step>
+<Step title="Welcome and security notice">
+<Frame caption="Read the security notice displayed and decide accordingly">
+<img src="/assets/macos-onboarding/03-security-notice.png" alt="" />
+</Frame>
+</Step>
+<Step title="Local vs Remote">
+<Frame>
+<img src="/assets/macos-onboarding/04-choose-gateway.png" alt="" />
+</Frame>
 
 Where does the **Gateway** run?
 
-- **Local (this Mac):** onboarding can run OAuth flows and write credentials
+- **This Mac (Local only):** 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:
-
+<Tip>
+**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
+</Tip>
+</Step>
+<Step title="Permissions">
+<Frame caption="Choose what permissions do you want to give OpenClaw">
+<img src="/assets/macos-onboarding/05-permissions.png" alt="" />
+</Frame>
 
 Onboarding requests TCC permissions needed for:
 
+- Automation (AppleScript)
 - 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.
+- Microphone
+- Speech Recognition
+- Camera
+- Location
+
+</Step>
+<Step title="CLI">
+  <Info>This step is optional</Info>
+  The app can install the global `openclaw` CLI via npm/pnpm so terminal
+  workflows and launchd tasks work out of the box.
+</Step>
+<Step title="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. See [Bootstrapping](/start/bootstrapping) for
+  what happens on the gateway host during the first agent run.
+</Step>
+</Steps>

package/docs/start/openclaw.md

@@ -26,26 +26,9 @@ Start conservative:
 
 ## Prerequisites
 
-- Node **22+**
-- OpenClaw available on PATH (recommended: global install)
+- 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
 
-```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:
@@ -91,7 +74,7 @@ openclaw gateway --port 18789
 
 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`.
+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: `openclaw dashboard`.
 
 ## Give the agent a workspace (AGENTS)
 
@@ -142,7 +125,7 @@ Example:
 {
   logging: { level: "info" },
   agent: {
-    model: "anthropic/claude-opus-4-5",
+    model: "anthropic/claude-opus-4-6",
     workspace: "~/.openclaw/workspace",
     thinkingDefault: "high",
     timeoutSeconds: 1800,

package/docs/start/quickstart.md

@@ -0,0 +1,22 @@
+---
+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"
+---
+
+# 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 Wizard" href="/start/wizard">
+    Full CLI wizard reference and advanced options.
+  </Card>
+</Columns>

package/docs/start/setup.md

@@ -1,5 +1,5 @@
 ---
-summary: "Setup guide: keep your OpenClaw setup tailored while staying up-to-date"
+summary: "Advanced setup and development workflows for OpenClaw"
 read_when:
   - Setting up a new machine
   - You want “latest + greatest” without breaking your personal setup
@@ -8,6 +8,11 @@ title: "Setup"
 
 # Setup
 
+<Note>
+If you are setting up for the first time, start with [Getting Started](/start/getting-started).
+For wizard details, see [Onboarding Wizard](/start/wizard).
+</Note>
+
 Last updated: 2026-01-01
 
 ## TL;DR
@@ -43,6 +48,14 @@ 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).