Docs: streamline start and install docs (#9648)

* docs(start): streamline getting started flow * docs(nav): reorganize start and install sections * docs(style): move custom css to style.css * docs(navigation): align zh-CN ordering * docs(navigation): localize zh-Hans labels
2026-03-12 07:20:45 +00:00 · 2026-02-05 10:09:45 -05:00
parent 8b8451231c
commit 675c26b2b0
11 changed files with 498 additions and 530 deletions
--- a/docs/start/getting-started.md
+++ b/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).
+</Info>

-Recommended path: use the **CLI onboarding wizard** (`openclaw onboard`). It sets up:
+## Prereqs

- model/auth (OAuth recommended)
- gateway settings
- channels (WhatsApp/Telegram/Discord/Mattermost (plugin)/...)
- pairing defaults (secure DMs)
- workspace bootstrap + skills
- optional background service
+- Node 22 or newer

-If you want the deeper reference pages, jump to: [Wizard](/start/wizard), [Setup](/start/setup), [Pairing](/start/pairing), [Security](/gateway/security).
+<Tip>
+Check your Node version with `node --version` if you are unsure.
+</Tip>

-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:
+## Quick setup (CLI)

-```json
-{
-  "routing": {
-    "agents": {
-      "main": {
-        "workspace": "~/.openclaw/workspace",
-        "sandbox": { "mode": "off" }
-      }
-    }
-  }
-}
-```
+<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>

-## 0) Prereqs
+    <Note>
+    Other install methods and requirements: [Install](/install).
+    </Note>

- 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).
+  </Step>
+  <Step title="Run the onboarding wizard">
+    ```bash
+    openclaw onboard --install-daemon
+    ```

-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).
+    The wizard configures auth, gateway settings, and optional channels.
+    See [Onboarding Wizard](/start/wizard) for details.

-## 1) Install the CLI (recommended)
+  </Step>
+  <Step title="Check the Gateway">
+    If you installed the service, it should already be running:

-```bash
-curl -fsSL https://openclaw.ai/install.sh | bash
-```
+    ```bash
+    openclaw gateway status
+    ```

-Installer options (install method, non-interactive, from GitHub): [Install](/install).
+  </Step>
+  <Step title="Open the Control UI">
+    ```bash
+    openclaw dashboard
+    ```
+  </Step>
+</Steps>

-Windows (PowerShell):
+<Check>
+If the Control UI loads, your Gateway is ready for use.
+</Check>

-```powershell
-iwr -useb https://openclaw.ai/install.ps1 | iex
-```
+## Optional checks and extras

-Alternative (global install):
+<AccordionGroup>
+  <Accordion title="Run the Gateway in the foreground">
+    Useful for quick tests or troubleshooting.

-```bash
-npm install -g openclaw@latest
-```
+    ```bash
+    openclaw gateway --port 18789
+    ```

-```bash
-pnpm add -g openclaw@latest
-```
+  </Accordion>
+  <Accordion title="Send a test message">
+    Requires a configured channel.

-## 2) Run the onboarding wizard (and install the service)
+    ```bash
+    openclaw message send --target +15555550123 --message "Hello from OpenClaw"
+    ```

-```bash
-openclaw onboard --install-daemon
-```
+  </Accordion>
+</AccordionGroup>

-What you’ll choose:
+## Go deeper

- **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`.
+<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>

-Wizard doc: [Wizard](/start/wizard)
+## What you will have

-### Auth: where it lives (important)
+- A running Gateway
+- Auth configured
+- Control UI access or a connected channel

- **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.
+## Next steps

- 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)
+- DM safety and approvals: [Pairing](/start/pairing)
+- Connect more channels: [Channels](/channels)
+- Advanced workflows and from source: [Setup](/start/setup)