From c18452598aa0b6977ad8962c689bed03e144986d Mon Sep 17 00:00:00 2001 From: Seb Slight <19554889+sebslight@users.noreply.github.com> Date: Thu, 5 Feb 2026 17:45:01 -0500 Subject: [PATCH] docs: restructure Get Started tab and improve onboarding flow (#9950) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs: restructure Get Started tab and improve onboarding flow - Flatten nested Onboarding group into linear First Steps flow - Add 'What is OpenClaw?' narrative section to landing page - Split wizard.md into streamlined overview + full reference (reference/wizard.md) - Move Pairing to Channels > Configuration - Move Bootstrapping to Agents > Fundamentals - Move macOS app onboarding to Platforms > macOS companion app - Move Lore to Help > Community - Remove duplicate install instructions from openclaw.md - Mirror navigation changes in zh-CN tabs - No content deleted — all detail preserved or relocated * docs: move deployment pages to install/, fix Platforms tab routing, clarify onboarding paths - Move deployment guides (fly, hetzner, gcp, macos-vm, exe-dev, railway, render, northflank) from platforms/ and root to install/ - Add 'Hosting and deployment' group to Install tab - Slim Gateway & Ops 'Remote access and deployment' down to 'Remote access' - Swap Platforms tab before Gateway & Ops to fix path-prefix routing - Move macOS app onboarding into First steps (parallel to CLI wizard) - Rename sidebar titles to 'Onboarding: CLI' / 'Onboarding: macOS App' - Add redirects for all moved paths - Update all internal links (en + zh-CN) - Fix img tag syntax in onboarding.md --- docs/.DS_Store | Bin 0 -> 10244 bytes docs/docs.json | 315 ++++++++++-------- docs/gateway/remote.md | 2 +- docs/help/faq.md | 10 +- docs/index.md | 15 +- docs/install/docker.md | 2 +- docs/{platforms => install}/exe-dev.md | 0 docs/{platforms => install}/fly.md | 0 docs/{platforms => install}/gcp.md | 0 docs/{platforms => install}/hetzner.md | 0 docs/{platforms => install}/macos-vm.md | 0 docs/{ => install}/northflank.mdx | 0 docs/{ => install}/railway.mdx | 0 docs/{ => install}/render.mdx | 0 docs/platforms/digitalocean.md | 4 +- docs/platforms/index.md | 8 +- docs/platforms/linux.md | 2 +- docs/platforms/oracle.md | 2 +- docs/platforms/raspberry-pi.md | 2 +- docs/reference/.DS_Store | Bin 0 -> 8196 bytes docs/reference/wizard.md | 268 +++++++++++++++ docs/start/onboarding.md | 12 +- docs/start/openclaw.md | 19 +- docs/start/wizard.md | 101 ++++-- docs/vps.md | 12 +- docs/zh-CN/gateway/remote.md | 2 +- docs/zh-CN/help/faq.md | 10 +- docs/zh-CN/install/docker.md | 2 +- docs/zh-CN/{platforms => install}/exe-dev.md | 0 docs/zh-CN/{platforms => install}/fly.md | 0 docs/zh-CN/{platforms => install}/gcp.md | 0 docs/zh-CN/{platforms => install}/hetzner.md | 0 docs/zh-CN/{platforms => install}/macos-vm.md | 0 docs/zh-CN/{ => install}/northflank.mdx | 0 docs/zh-CN/{ => install}/railway.mdx | 0 docs/zh-CN/{ => install}/render.mdx | 0 docs/zh-CN/platforms/digitalocean.md | 4 +- docs/zh-CN/platforms/index.md | 8 +- docs/zh-CN/platforms/linux.md | 2 +- docs/zh-CN/platforms/oracle.md | 2 +- docs/zh-CN/platforms/raspberry-pi.md | 2 +- docs/zh-CN/start/getting-started.md | 2 +- docs/zh-CN/vps.md | 8 +- 43 files changed, 567 insertions(+), 249 deletions(-) create mode 100644 docs/.DS_Store rename docs/{platforms => install}/exe-dev.md (100%) rename docs/{platforms => install}/fly.md (100%) rename docs/{platforms => install}/gcp.md (100%) rename docs/{platforms => install}/hetzner.md (100%) rename docs/{platforms => install}/macos-vm.md (100%) rename docs/{ => install}/northflank.mdx (100%) rename docs/{ => install}/railway.mdx (100%) rename docs/{ => install}/render.mdx (100%) create mode 100644 docs/reference/.DS_Store create mode 100644 docs/reference/wizard.md rename docs/zh-CN/{platforms => install}/exe-dev.md (100%) rename docs/zh-CN/{platforms => install}/fly.md (100%) rename docs/zh-CN/{platforms => install}/gcp.md (100%) rename docs/zh-CN/{platforms => install}/hetzner.md (100%) rename docs/zh-CN/{platforms => install}/macos-vm.md (100%) rename docs/zh-CN/{ => install}/northflank.mdx (100%) rename docs/zh-CN/{ => install}/railway.mdx (100%) rename docs/zh-CN/{ => install}/render.mdx (100%) diff --git a/docs/.DS_Store b/docs/.DS_Store new file mode 100644 index 0000000000000000000000000000000000000000..198784c6ec8036e6b5b9f5087a8ec177cfd28ff6 GIT binary patch literal 10244 zcmeHMX>1)=6~5nf63;Yml5uQjX~y*=F9}(kc!{$(PFlxH+QiP%*s0gVdCzZ>40)b$ z-@IohO|7~JmC_)P06_`MA1J$uSOO`F)KUuk0EAK#RP{%pWl;qPM8#5x2F|^AY+U=f z4Jrvlnvv$7x#!+9^Um@4&Uf!MV+@VCR5fEZV@#u4NHa!Fo=c32d&b2>jTi*kGd9Q) zEX!QxGjGQ1ND)OKia->BC<0Lgq6qvyM1VM3T-tmkqc(~_6oDuLlMxX0!KPcthER?v zDN6@6atlCm4yolu&$JJaHg+f*LOG_SG^KZ{-2*~Xgj)B^9n_Fnto}+!cKXw0}90`V!X+KHhmy$ziH^^31 zT>&qcGk0ELp_p%Asb28Gv zO*u5BuhaEX{z#*r^HPDdZC3-juIc^e(sSo(w{NSktG8_)t+3D4)l^m3wRJV4qqy$r`Hv`f5S9dHOmpx2Y`&#~;U?u>TjZxj~OciUtztfgDYCcBj+r?tM+Z_VHq_M<_?c{zd~cUapHeSaBtCa=NEiqAIGKQ? zu0OtTsl9sLrp?=T?cTHRz~OPTXi;&jG`6I3*bUrd+Bq`frn0BH6TyJvrCjf14~5#x zx+h#GqZgq<@9+|X&iJxhmls=QR{3mJni-4e5oq!URe zZKiZ(R<|Q&bq*_U&DKzPduhz-8t?}P$(10~H8xq+G4a{9M36l=WAa(XINngD21=BeYz6z3vl`aS+SqY+nvJrD*rV)| z?2GIv_FeWgyUdkKyC^1U`c=;mi06zKU<-8GIiq~3@Z%( z&MYV_yKC=V`&!%f-wY^xZlSTNjS)K znU=~TC#|yEV)kqZJwiBg&S(PCW}%uLkFC}SN9J7BT^n1k5rWKls=KkQQX|ZoTy|qM zWwkmX(=1Tkjb+<)&4lXI$9Cz2QFG3?MIgB2wph$$gjo5Ln#=ZRgfsIx0^kaJf&H5O zfxXJEVm?fiVihI*7Sy8!t(5p8?GK|DeK>}GB=B~e#vnX`z**df`!R|K@GwE(Jl=!% z;=_0pAHhfQDLh6n_$)q8Ah?LH;~RJqPvL2NFNDK$1cu+@Pty|oz_bJxiJv#Yhubq= z+V@VXV!+DYlmFVFy@}7P=3xhuH=87`sFi zdzn4UUSz*xe+9!lEI=_zumnr7g6Oppb=ZNO*o8f^%G`~19EU3_%m~KtAd%}ksj|Eu zA0Tr5P*_zyO;zP_swbE51inQT=ZknTk?a~?$*XuZ zujkFYlXvqT-pl*A!#zI2@8_ec;=Ccn=EvY06RfeomIP}M!QOlryg`I(l-r6}X9KiZ zD9|jIjMhqHm2J)?EUE6>jCHm-k8q^A74|0E>-EDc^+s zl#!9Fgi5@HI)QPvD!9RG*P+%*%KdKf@IX zhL`bYvC^ED-uVbNPkK+ISM`#pz4izcsHwI%|8JT7|Nqzi!f0j`fhYnuT?8NNkl|1;ovoWk9p -OpenClaw connects chat apps to coding agents like Pi through a single Gateway process. It powers the OpenClaw assistant and supports local or remote setups. +## What is OpenClaw? + +OpenClaw is a **self-hosted gateway** that connects your favorite chat apps — WhatsApp, Telegram, Discord, iMessage, and more — to AI coding agents like Pi. You run a single Gateway process on your own machine (or a server), and it becomes the bridge between your messaging apps and an always-available AI assistant. + +**Who is it for?** Developers and power users who want a personal AI assistant they can message from anywhere — without giving up control of their data or relying on a hosted service. + +**What makes it different?** + +- **Self-hosted**: runs on your hardware, your rules +- **Multi-channel**: one Gateway serves WhatsApp, Telegram, Discord, and more simultaneously +- **Agent-native**: built for coding agents with tool use, sessions, memory, and multi-agent routing +- **Open source**: MIT licensed, community-driven + +**What do you need?** Node 22+, an API key (Anthropic recommended), and 5 minutes. ## How it works diff --git a/docs/install/docker.md b/docs/install/docker.md index a657cbc1de..788540d9e8 100644 --- a/docs/install/docker.md +++ b/docs/install/docker.md @@ -63,7 +63,7 @@ It writes config/workspace on the host: - `~/.openclaw/` - `~/.openclaw/workspace` -Running on a VPS? See [Hetzner (Docker VPS)](/platforms/hetzner). +Running on a VPS? See [Hetzner (Docker VPS)](/install/hetzner). ### Manual flow (compose) diff --git a/docs/platforms/exe-dev.md b/docs/install/exe-dev.md similarity index 100% rename from docs/platforms/exe-dev.md rename to docs/install/exe-dev.md diff --git a/docs/platforms/fly.md b/docs/install/fly.md similarity index 100% rename from docs/platforms/fly.md rename to docs/install/fly.md diff --git a/docs/platforms/gcp.md b/docs/install/gcp.md similarity index 100% rename from docs/platforms/gcp.md rename to docs/install/gcp.md diff --git a/docs/platforms/hetzner.md b/docs/install/hetzner.md similarity index 100% rename from docs/platforms/hetzner.md rename to docs/install/hetzner.md diff --git a/docs/platforms/macos-vm.md b/docs/install/macos-vm.md similarity index 100% rename from docs/platforms/macos-vm.md rename to docs/install/macos-vm.md diff --git a/docs/northflank.mdx b/docs/install/northflank.mdx similarity index 100% rename from docs/northflank.mdx rename to docs/install/northflank.mdx diff --git a/docs/railway.mdx b/docs/install/railway.mdx similarity index 100% rename from docs/railway.mdx rename to docs/install/railway.mdx diff --git a/docs/render.mdx b/docs/install/render.mdx similarity index 100% rename from docs/render.mdx rename to docs/install/render.mdx diff --git a/docs/platforms/digitalocean.md b/docs/platforms/digitalocean.md index a379d12383..7a92ad6884 100644 --- a/docs/platforms/digitalocean.md +++ b/docs/platforms/digitalocean.md @@ -27,7 +27,7 @@ If you want a $0/month option and don’t mind ARM + provider-specific setup, se **Picking a provider:** - DigitalOcean: simplest UX + predictable setup (this guide) -- Hetzner: good price/perf (see [Hetzner guide](/platforms/hetzner)) +- Hetzner: good price/perf (see [Hetzner guide](/install/hetzner)) - Oracle Cloud: can be $0/month, but is more finicky and ARM-only (see [Oracle guide](/platforms/oracle)) --- @@ -256,7 +256,7 @@ free -h ## See Also -- [Hetzner guide](/platforms/hetzner) — cheaper, more powerful +- [Hetzner guide](/install/hetzner) — cheaper, more powerful - [Docker install](/install/docker) — containerized setup - [Tailscale](/gateway/tailscale) — secure remote access - [Configuration](/gateway/configuration) — full config reference diff --git a/docs/platforms/index.md b/docs/platforms/index.md index 069c05807a..0f37c275cd 100644 --- a/docs/platforms/index.md +++ b/docs/platforms/index.md @@ -26,10 +26,10 @@ Native companion apps for Windows are also planned; the Gateway is recommended v ## VPS & hosting - VPS hub: [VPS hosting](/vps) -- Fly.io: [Fly.io](/platforms/fly) -- Hetzner (Docker): [Hetzner](/platforms/hetzner) -- GCP (Compute Engine): [GCP](/platforms/gcp) -- exe.dev (VM + HTTPS proxy): [exe.dev](/platforms/exe-dev) +- Fly.io: [Fly.io](/install/fly) +- Hetzner (Docker): [Hetzner](/install/hetzner) +- GCP (Compute Engine): [GCP](/install/gcp) +- exe.dev (VM + HTTPS proxy): [exe.dev](/install/exe-dev) ## Common links diff --git a/docs/platforms/linux.md b/docs/platforms/linux.md index 46c60469da..0cce3a54e7 100644 --- a/docs/platforms/linux.md +++ b/docs/platforms/linux.md @@ -21,7 +21,7 @@ Native Linux companion apps are planned. Contributions are welcome if you want t 4. From your laptop: `ssh -N -L 18789:127.0.0.1:18789 @` 5. Open `http://127.0.0.1:18789/` and paste your token -Step-by-step VPS guide: [exe.dev](/platforms/exe-dev) +Step-by-step VPS guide: [exe.dev](/install/exe-dev) ## Install diff --git a/docs/platforms/oracle.md b/docs/platforms/oracle.md index 79f9758238..779027c9f0 100644 --- a/docs/platforms/oracle.md +++ b/docs/platforms/oracle.md @@ -300,4 +300,4 @@ tar -czvf openclaw-backup.tar.gz ~/.openclaw ~/.openclaw/workspace - [Tailscale integration](/gateway/tailscale) — full Tailscale docs - [Gateway configuration](/gateway/configuration) — all config options - [DigitalOcean guide](/platforms/digitalocean) — if you want paid + easier signup -- [Hetzner guide](/platforms/hetzner) — Docker-based alternative +- [Hetzner guide](/install/hetzner) — Docker-based alternative diff --git a/docs/platforms/raspberry-pi.md b/docs/platforms/raspberry-pi.md index 592df13b81..37968735f3 100644 --- a/docs/platforms/raspberry-pi.md +++ b/docs/platforms/raspberry-pi.md @@ -353,6 +353,6 @@ echo 'wireless-power off' | sudo tee -a /etc/network/interfaces - [Linux guide](/platforms/linux) — general Linux setup - [DigitalOcean guide](/platforms/digitalocean) — cloud alternative -- [Hetzner guide](/platforms/hetzner) — Docker setup +- [Hetzner guide](/install/hetzner) — Docker setup - [Tailscale](/gateway/tailscale) — remote access - [Nodes](/nodes) — pair your laptop/phone with the Pi gateway diff --git a/docs/reference/.DS_Store b/docs/reference/.DS_Store new file mode 100644 index 0000000000000000000000000000000000000000..e75f28ce666b8a62ec54253b36c0988f2619b9e3 GIT binary patch literal 8196 zcmeHMYit!o6rOKe=&rc1eE%ER2g2oFnvTj*^IEqm`>VP)@bxx2R) zfre^~5iy#mF$SZ*#Am`UAD}VOsL>y43{;Hqj}l{I{9&T;@k5MfclPoq?LRR!?j$p3 zX3m^5d(ND1rstM1hL(J$p0R4im`K&9$~0=mDL&t?*AyX~DJ2S$XUt+c^O(WhRNyW5Qq}6%o^IMkE)Xy?1})juZQ2>9(BkCn zj2p-%I75;|X+Wtye7JGNs#>j~u3@-VJKWSzSF1HPH4G0+;>_5xHQNXFTUpzAm>Yxe zLSXV3U|E1kD=&uF%+gn7ttd-a1|#zD{T`-175V_91r z*Yq{^B)y4P$zIpVd98uo0Y%BX#&(0$nnOk#DR+}5?e6QW8e=o0Q!}cyMN5`0U$w4z z{iZG3N0su5$|`x5+)EC&J@anU$o1%M+ORXGy>~~!%y|2{hfLQ@Sw@$wXAP+wwbJOE zx$_itzFJdc@r9QKMI|OC^C|N{-t_Jrtt_ulWHq)>5|!6?W#|JtoQ%IyCg7-Q>=se% z^XFT02DN-zR%>r30lmv5JGctDzCn@{w`)H|2N#uB-XTg#W{0Jx3@e;kvzDedcMtL7 z2q$O7MJbtfvRN|H<#TFVyC^Cj_xl^)rMq6|pkZJ7q_&Ns*z4}ob4F)@VzVgGA&SBI z(!4Lyo-sWq$Gs6#w~1npudF$fAwA06d2bg_wfln#b@{u-{4zZz<2lsf8rwk5+tEQs1&M%#lkY7PN)~w2yH^Q&?EE;eZnrm z5Nx3!91(`O1ws*n{h>u65gw$@IJXO7FuYxacP7A~wqfIjO`GM8{~`vznh~IG=B(M( z3l`s2x1#CJmP@h8L%A5eSE3>S!d37IfDi=B*dQi+s`KRFVvJNge5+_Sze+kQwc|WSgS476oKH&hxOWWSt%iK1~-AaQd=r35cy!WyjE69 z38vDhN)V9cnq~qm3pQ!h+BL-o-9H%q-?N|Cuk0cu3jcY~un3J5@~!BgaPPxz^g~CA zLOu%{gE)XgID%muB>)`5aXf-Y@fe=Q2@3yb@f=>n%XkH^;x)WMAUK1!2m&AALwtnK zaTe$B1 + + - If `~/.openclaw/openclaw.json` exists, choose **Keep / Modify / Reset**. + - Re-running the wizard does **not** wipe anything unless you explicitly choose **Reset** + (or pass `--reset`). + - If the config is invalid or contains legacy keys, the wizard stops and asks + you to run `openclaw doctor` before continuing. + - Reset uses `trash` (never `rm`) and offers scopes: + - Config only + - Config + credentials + sessions + - Full reset (also removes workspace) + + + - **Anthropic API key (recommended)**: uses `ANTHROPIC_API_KEY` if present or prompts for a key, then saves it for daemon use. + - **Anthropic OAuth (Claude Code CLI)**: on macOS the wizard checks Keychain item "Claude Code-credentials" (choose "Always Allow" so launchd starts don't block); on Linux/Windows it reuses `~/.claude/.credentials.json` if present. + - **Anthropic token (paste setup-token)**: run `claude setup-token` on any machine, then paste the token (you can name it; blank = default). + - **OpenAI Code (Codex) subscription (Codex CLI)**: if `~/.codex/auth.json` exists, the wizard can reuse it. + - **OpenAI Code (Codex) subscription (OAuth)**: browser flow; paste the `code#state`. + - Sets `agents.defaults.model` to `openai-codex/gpt-5.2` when model is unset or `openai/*`. + - **OpenAI API key**: uses `OPENAI_API_KEY` if present or prompts for a key, then saves it to `~/.openclaw/.env` so launchd can read it. + - **OpenCode Zen (multi-model proxy)**: prompts for `OPENCODE_API_KEY` (or `OPENCODE_ZEN_API_KEY`, get it at https://opencode.ai/auth). + - **API key**: stores the key for you. + - **Vercel AI Gateway (multi-model proxy)**: prompts for `AI_GATEWAY_API_KEY`. + - More detail: [Vercel AI Gateway](/providers/vercel-ai-gateway) + - **Cloudflare AI Gateway**: prompts for Account ID, Gateway ID, and `CLOUDFLARE_AI_GATEWAY_API_KEY`. + - More detail: [Cloudflare AI Gateway](/providers/cloudflare-ai-gateway) + - **MiniMax M2.1**: config is auto-written. + - More detail: [MiniMax](/providers/minimax) + - **Synthetic (Anthropic-compatible)**: prompts for `SYNTHETIC_API_KEY`. + - More detail: [Synthetic](/providers/synthetic) + - **Moonshot (Kimi K2)**: config is auto-written. + - **Kimi Coding**: config is auto-written. + - More detail: [Moonshot AI (Kimi + Kimi Coding)](/providers/moonshot) + - **Skip**: no auth configured yet. + - Pick a default model from detected options (or enter provider/model manually). + - Wizard runs a model check and warns if the configured model is unknown or missing auth. + - OAuth credentials live in `~/.openclaw/credentials/oauth.json`; auth profiles live in `~/.openclaw/agents//agent/auth-profiles.json` (API keys + OAuth). + - More detail: [/concepts/oauth](/concepts/oauth) + + Headless/server tip: complete OAuth on a machine with a browser, then copy + `~/.openclaw/credentials/oauth.json` (or `$OPENCLAW_STATE_DIR/credentials/oauth.json`) to the + gateway host. + + + + - Default `~/.openclaw/workspace` (configurable). + - Seeds the workspace files needed for the agent bootstrap ritual. + - Full workspace layout + backup guide: [Agent workspace](/concepts/agent-workspace) + + + - Port, bind, auth mode, tailscale exposure. + - Auth recommendation: keep **Token** even for loopback so local WS clients must authenticate. + - Disable auth only if you fully trust every local process. + - Non‑loopback binds still require auth. + + + - [WhatsApp](/channels/whatsapp): optional QR login. + - [Telegram](/channels/telegram): bot token. + - [Discord](/channels/discord): bot token. + - [Google Chat](/channels/googlechat): service account JSON + webhook audience. + - [Mattermost](/channels/mattermost) (plugin): bot token + base URL. + - [Signal](/channels/signal): optional `signal-cli` install + account config. + - [BlueBubbles](/channels/bluebubbles): **recommended for iMessage**; server URL + password + webhook. + - [iMessage](/channels/imessage): legacy `imsg` CLI path + DB access. + - DM security: default is pairing. First DM sends a code; approve via `openclaw pairing approve ` or use allowlists. + + + - macOS: LaunchAgent + - Requires a logged-in user session; for headless, use a custom LaunchDaemon (not shipped). + - Linux (and Windows via WSL2): systemd user unit + - Wizard attempts to enable lingering via `loginctl enable-linger ` so the Gateway stays up after logout. + - May prompt for sudo (writes `/var/lib/systemd/linger`); it tries without sudo first. + - **Runtime selection:** Node (recommended; required for WhatsApp/Telegram). Bun is **not recommended**. + + + - Starts the Gateway (if needed) and runs `openclaw health`. + - Tip: `openclaw status --deep` adds gateway health probes to status output (requires a reachable gateway). + + + - Reads the available skills and checks requirements. + - Lets you choose a node manager: **npm / pnpm** (bun not recommended). + - Installs optional dependencies (some use Homebrew on macOS). + + + - Summary + next steps, including iOS/Android/macOS apps for extra features. + + + + +If no GUI is detected, the wizard prints SSH port-forward instructions for the Control UI instead of opening a browser. +If the Control UI assets are missing, the wizard attempts to build them; fallback is `pnpm ui:build` (auto-installs UI deps). + + +## Non-interactive mode + +Use `--non-interactive` to automate or script onboarding: + +```bash +openclaw onboard --non-interactive \ + --mode local \ + --auth-choice apiKey \ + --anthropic-api-key "$ANTHROPIC_API_KEY" \ + --gateway-port 18789 \ + --gateway-bind loopback \ + --install-daemon \ + --daemon-runtime node \ + --skip-skills +``` + +Add `--json` for a machine‑readable summary. + + +`--json` does **not** imply non-interactive mode. Use `--non-interactive` (and `--workspace`) for scripts. + + + + + ```bash + openclaw onboard --non-interactive \ + --mode local \ + --auth-choice gemini-api-key \ + --gemini-api-key "$GEMINI_API_KEY" \ + --gateway-port 18789 \ + --gateway-bind loopback + ``` + + + ```bash + openclaw onboard --non-interactive \ + --mode local \ + --auth-choice zai-api-key \ + --zai-api-key "$ZAI_API_KEY" \ + --gateway-port 18789 \ + --gateway-bind loopback + ``` + + + ```bash + openclaw onboard --non-interactive \ + --mode local \ + --auth-choice ai-gateway-api-key \ + --ai-gateway-api-key "$AI_GATEWAY_API_KEY" \ + --gateway-port 18789 \ + --gateway-bind loopback + ``` + + + ```bash + openclaw onboard --non-interactive \ + --mode local \ + --auth-choice cloudflare-ai-gateway-api-key \ + --cloudflare-ai-gateway-account-id "your-account-id" \ + --cloudflare-ai-gateway-gateway-id "your-gateway-id" \ + --cloudflare-ai-gateway-api-key "$CLOUDFLARE_AI_GATEWAY_API_KEY" \ + --gateway-port 18789 \ + --gateway-bind loopback + ``` + + + ```bash + openclaw onboard --non-interactive \ + --mode local \ + --auth-choice moonshot-api-key \ + --moonshot-api-key "$MOONSHOT_API_KEY" \ + --gateway-port 18789 \ + --gateway-bind loopback + ``` + + + ```bash + openclaw onboard --non-interactive \ + --mode local \ + --auth-choice synthetic-api-key \ + --synthetic-api-key "$SYNTHETIC_API_KEY" \ + --gateway-port 18789 \ + --gateway-bind loopback + ``` + + + ```bash + openclaw onboard --non-interactive \ + --mode local \ + --auth-choice opencode-zen \ + --opencode-zen-api-key "$OPENCODE_API_KEY" \ + --gateway-port 18789 \ + --gateway-bind loopback + ``` + + + +### Add agent (non-interactive) + +```bash +openclaw agents add work \ + --workspace ~/.openclaw/workspace-work \ + --model openai/gpt-5.2 \ + --bind whatsapp:biz \ + --non-interactive \ + --json +``` + +## Gateway wizard RPC + +The Gateway exposes the wizard flow over RPC (`wizard.start`, `wizard.next`, `wizard.cancel`, `wizard.status`). +Clients (macOS app, Control UI) can render steps without re‑implementing onboarding logic. + +## Signal setup (signal-cli) + +The wizard can install `signal-cli` from GitHub releases: + +- Downloads the appropriate release asset. +- Stores it under `~/.openclaw/tools/signal-cli//`. +- Writes `channels.signal.cliPath` to your config. + +Notes: + +- JVM builds require **Java 21**. +- Native builds are used when available. +- Windows uses WSL2; signal-cli install follows the Linux flow inside WSL. + +## What the wizard writes + +Typical fields in `~/.openclaw/openclaw.json`: + +- `agents.defaults.workspace` +- `agents.defaults.model` / `models.providers` (if Minimax chosen) +- `gateway.*` (mode, bind, auth, tailscale) +- `channels.telegram.botToken`, `channels.discord.token`, `channels.signal.*`, `channels.imessage.*` +- Channel allowlists (Slack/Discord/Matrix/Microsoft Teams) when you opt in during the prompts (names resolve to IDs when possible). +- `skills.install.nodeManager` +- `wizard.lastRunAt` +- `wizard.lastRunVersion` +- `wizard.lastRunCommit` +- `wizard.lastRunCommand` +- `wizard.lastRunMode` + +`openclaw agents add` writes `agents.list[]` and optional `bindings`. + +WhatsApp credentials go under `~/.openclaw/credentials/whatsapp//`. +Sessions are stored under `~/.openclaw/agents//sessions/`. + +Some channels are delivered as plugins. When you pick one during onboarding, the wizard +will prompt to install it (npm or a local path) before it can be configured. + +## Related docs + +- Wizard overview: [Onboarding Wizard](/start/wizard) +- macOS app onboarding: [Onboarding](/start/onboarding) +- Config reference: [Gateway configuration](/gateway/configuration) +- Providers: [WhatsApp](/channels/whatsapp), [Telegram](/channels/telegram), [Discord](/channels/discord), [Google Chat](/channels/googlechat), [Signal](/channels/signal), [BlueBubbles](/channels/bluebubbles) (iMessage), [iMessage](/channels/imessage) (legacy) +- Skills: [Skills](/tools/skills), [Skills config](/tools/skills-config) diff --git a/docs/start/onboarding.md b/docs/start/onboarding.md index be8b9713c4..be8710a4dc 100644 --- a/docs/start/onboarding.md +++ b/docs/start/onboarding.md @@ -4,7 +4,7 @@ read_when: - Designing the macOS onboarding assistant - Implementing auth or identity setup title: "Onboarding (macOS App)" -sidebarTitle: "macOS app" +sidebarTitle: "Onboarding: macOS App" --- # Onboarding (macOS App) @@ -16,22 +16,22 @@ wizard, and let the agent bootstrap itself. - + - + - + - + Where does the **Gateway** run? @@ -51,7 +51,7 @@ Where does the **Gateway** run? - + Onboarding requests TCC permissions needed for: diff --git a/docs/start/openclaw.md b/docs/start/openclaw.md index 563c88c9b6..c750fa9c01 100644 --- a/docs/start/openclaw.md +++ b/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: diff --git a/docs/start/wizard.md b/docs/start/wizard.md index 86b207f6b5..c8e3f874b8 100644 --- a/docs/start/wizard.md +++ b/docs/start/wizard.md @@ -4,14 +4,15 @@ read_when: - Running or configuring the onboarding wizard - Setting up a new machine title: "Onboarding Wizard (CLI)" -sidebarTitle: "Wizard (CLI)" +sidebarTitle: "Onboarding: CLI" --- # Onboarding Wizard (CLI) -The CLI onboarding wizard is the recommended setup path for OpenClaw on macOS, -Linux, and Windows (via WSL2). It configures a local gateway or a remote -gateway connection, plus workspace defaults, channels, and skills. +The onboarding wizard is the **recommended** way to set up OpenClaw on macOS, +Linux, or Windows (via WSL2; strongly recommended). +It configures a local Gateway or a remote Gateway connection, plus channels, skills, +and workspace defaults in one guided flow. ```bash openclaw onboard @@ -22,36 +23,7 @@ Fastest first chat: open the Control UI (no channel setup needed). Run `openclaw dashboard` and chat in the browser. Docs: [Dashboard](/web/dashboard). -## QuickStart vs Advanced - -The wizard starts with **QuickStart** (defaults) vs **Advanced** (full control). - - - - - Local gateway on loopback - - Existing workspace or default workspace - - Gateway port `18789` - - Gateway auth token auto-generated (even on loopback) - - Tailscale exposure off - - Telegram and WhatsApp DMs default to allowlist (you may be prompted for your phone number) - - - - Exposes full prompt flow for mode, workspace, gateway, channels, daemon, and skills - - - -## CLI onboarding details - - - - Full local and remote flow, auth and model matrix, config outputs, wizard RPC, and signal-cli behavior. - - - Non-interactive onboarding recipes and automated `agents add` examples. - - - -## Common follow-up commands +To reconfigure later: ```bash openclaw configure @@ -68,6 +40,67 @@ Recommended: set up a Brave Search API key so the agent can use `web_search` which stores `tools.web.search.apiKey`. Docs: [Web tools](/tools/web). +## QuickStart vs Advanced + +The wizard starts with **QuickStart** (defaults) vs **Advanced** (full control). + + + + - Local gateway (loopback) + - Workspace default (or existing workspace) + - Gateway port **18789** + - Gateway auth **Token** (auto‑generated, even on loopback) + - Tailscale exposure **Off** + - Telegram + WhatsApp DMs default to **allowlist** (you'll be prompted for your phone number) + + + - Exposes every step (mode, workspace, gateway, channels, daemon, skills). + + + +## What the wizard configures + +**Local mode (default)** walks you through these steps: + +1. **Model/Auth** — Anthropic API key (recommended), OAuth, OpenAI, or other providers. Pick a default model. +2. **Workspace** — Location for agent files (default `~/.openclaw/workspace`). Seeds bootstrap files. +3. **Gateway** — Port, bind address, auth mode, Tailscale exposure. +4. **Channels** — WhatsApp, Telegram, Discord, Google Chat, Mattermost, Signal, BlueBubbles, or iMessage. +5. **Daemon** — Installs a LaunchAgent (macOS) or systemd user unit (Linux/WSL2). +6. **Health check** — Starts the Gateway and verifies it's running. +7. **Skills** — Installs recommended skills and optional dependencies. + + +Re-running the wizard does **not** wipe anything unless you explicitly choose **Reset** (or pass `--reset`). +If the config is invalid or contains legacy keys, the wizard asks you to run `openclaw doctor` first. + + +**Remote mode** only configures the local client to connect to a Gateway elsewhere. +It does **not** install or change anything on the remote host. + +## Add another agent + +Use `openclaw agents add ` to create a separate agent with its own workspace, +sessions, and auth profiles. Running without `--workspace` launches the wizard. + +What it sets: + +- `agents.list[].name` +- `agents.list[].workspace` +- `agents.list[].agentDir` + +Notes: + +- Default workspaces follow `~/.openclaw/workspace-`. +- Add `bindings` to route inbound messages (the wizard can do this). +- Non-interactive flags: `--model`, `--agent-dir`, `--bind`, `--non-interactive`. + +## Full reference + +For detailed step-by-step breakdowns, non-interactive scripting, Signal setup, +RPC API, and a full list of config fields the wizard writes, see the +[Wizard Reference](/reference/wizard). + ## Related docs - CLI command reference: [`openclaw onboard`](/cli/onboard) diff --git a/docs/vps.md b/docs/vps.md index 50e6036c47..dedccee4b7 100644 --- a/docs/vps.md +++ b/docs/vps.md @@ -13,13 +13,13 @@ deployments work at a high level. ## Pick a provider -- **Railway** (one‑click + browser setup): [Railway](/railway) -- **Northflank** (one‑click + browser setup): [Northflank](/northflank) +- **Railway** (one‑click + browser setup): [Railway](/install/railway) +- **Northflank** (one‑click + browser setup): [Northflank](/install/northflank) - **Oracle Cloud (Always Free)**: [Oracle](/platforms/oracle) — $0/month (Always Free, ARM; capacity/signup can be finicky) -- **Fly.io**: [Fly.io](/platforms/fly) -- **Hetzner (Docker)**: [Hetzner](/platforms/hetzner) -- **GCP (Compute Engine)**: [GCP](/platforms/gcp) -- **exe.dev** (VM + HTTPS proxy): [exe.dev](/platforms/exe-dev) +- **Fly.io**: [Fly.io](/install/fly) +- **Hetzner (Docker)**: [Hetzner](/install/hetzner) +- **GCP (Compute Engine)**: [GCP](/install/gcp) +- **exe.dev** (VM + HTTPS proxy): [exe.dev](/install/exe-dev) - **AWS (EC2/Lightsail/free tier)**: works well too. Video guide: https://x.com/techfrenAJ/status/2014934471095812547 diff --git a/docs/zh-CN/gateway/remote.md b/docs/zh-CN/gateway/remote.md index 5f425e5176..fee241d024 100644 --- a/docs/zh-CN/gateway/remote.md +++ b/docs/zh-CN/gateway/remote.md @@ -35,7 +35,7 @@ x-i18n: - **最佳用户体验：** 保持 `gateway.bind: "loopback"` 并使用 **Tailscale Serve** 作为控制 UI。 - **回退方案：** 保持 loopback + 从任何需要访问的机器建立 SSH 隧道。 -- **示例：** [exe.dev](/platforms/exe-dev)（简易 VM）或 [Hetzner](/platforms/hetzner)（生产 VPS）。 +- **示例：** [exe.dev](/install/exe-dev)（简易 VM）或 [Hetzner](/install/hetzner)（生产 VPS）。 当你的笔记本电脑经常休眠但你希望智能体始终在线时，这是理想的选择。 diff --git a/docs/zh-CN/help/faq.md b/docs/zh-CN/help/faq.md index 2b15d16412..f155112379 100644 --- a/docs/zh-CN/help/faq.md +++ b/docs/zh-CN/help/faq.md @@ -572,7 +572,7 @@ curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git 任何 Linux VPS 都可以。在服务器上安装，然后使用 SSH/Tailscale 访问 Gateway 网关。 -指南：[exe.dev](/platforms/exe-dev)、[Hetzner](/platforms/hetzner)、[Fly.io](/platforms/fly)。 +指南：[exe.dev](/install/exe-dev)、[Hetzner](/install/hetzner)、[Fly.io](/install/fly)。 远程访问：[Gateway 网关远程](/gateway/remote)。 ### 云/VPS 安装指南在哪里 @@ -580,9 +580,9 @@ curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git 我们维护了一个**托管中心**，涵盖常见提供商。选择一个并按指南操作： - [VPS 托管](/vps)（所有提供商汇总） -- [Fly.io](/platforms/fly) -- [Hetzner](/platforms/hetzner) -- [exe.dev](/platforms/exe-dev) +- [Fly.io](/install/fly) +- [Hetzner](/install/hetzner) +- [exe.dev](/install/exe-dev) 在云端的工作方式：**Gateway 网关运行在服务器上**，你通过控制 UI（或 Tailscale/SSH）从笔记本/手机访问。你的状态 + 工作区位于服务器上，因此将主机视为数据来源并做好备份。 @@ -863,7 +863,7 @@ OpenClaw 是轻量级的。对于基本的 Gateway 网关 + 一个聊天渠道 - **操作系统：** Ubuntu LTS 或其他现代 Debian/Ubuntu。 如果你使用 Windows，**WSL2 是最简单的虚拟机式设置**，具有最佳的工具兼容性。参阅 [Windows](/platforms/windows)、[VPS 托管](/vps)。 -如果你在虚拟机中运行 macOS，参阅 [macOS VM](/platforms/macos-vm)。 +如果你在虚拟机中运行 macOS，参阅 [macOS VM](/install/macos-vm)。 ## 什么是 OpenClaw？ diff --git a/docs/zh-CN/install/docker.md b/docs/zh-CN/install/docker.md index 57666fff2a..0b0577738b 100644 --- a/docs/zh-CN/install/docker.md +++ b/docs/zh-CN/install/docker.md @@ -70,7 +70,7 @@ Docker 是**可选的**。仅当你想要容器化的 Gateway 网关或验证 Do - `~/.openclaw/` - `~/.openclaw/workspace` -在 VPS 上运行？参阅 [Hetzner（Docker VPS）](/platforms/hetzner)。 +在 VPS 上运行？参阅 [Hetzner（Docker VPS）](/install/hetzner)。 ### 手动流程（compose） diff --git a/docs/zh-CN/platforms/exe-dev.md b/docs/zh-CN/install/exe-dev.md similarity index 100% rename from docs/zh-CN/platforms/exe-dev.md rename to docs/zh-CN/install/exe-dev.md diff --git a/docs/zh-CN/platforms/fly.md b/docs/zh-CN/install/fly.md similarity index 100% rename from docs/zh-CN/platforms/fly.md rename to docs/zh-CN/install/fly.md diff --git a/docs/zh-CN/platforms/gcp.md b/docs/zh-CN/install/gcp.md similarity index 100% rename from docs/zh-CN/platforms/gcp.md rename to docs/zh-CN/install/gcp.md diff --git a/docs/zh-CN/platforms/hetzner.md b/docs/zh-CN/install/hetzner.md similarity index 100% rename from docs/zh-CN/platforms/hetzner.md rename to docs/zh-CN/install/hetzner.md diff --git a/docs/zh-CN/platforms/macos-vm.md b/docs/zh-CN/install/macos-vm.md similarity index 100% rename from docs/zh-CN/platforms/macos-vm.md rename to docs/zh-CN/install/macos-vm.md diff --git a/docs/zh-CN/northflank.mdx b/docs/zh-CN/install/northflank.mdx similarity index 100% rename from docs/zh-CN/northflank.mdx rename to docs/zh-CN/install/northflank.mdx diff --git a/docs/zh-CN/railway.mdx b/docs/zh-CN/install/railway.mdx similarity index 100% rename from docs/zh-CN/railway.mdx rename to docs/zh-CN/install/railway.mdx diff --git a/docs/zh-CN/render.mdx b/docs/zh-CN/install/render.mdx similarity index 100% rename from docs/zh-CN/render.mdx rename to docs/zh-CN/install/render.mdx diff --git a/docs/zh-CN/platforms/digitalocean.md b/docs/zh-CN/platforms/digitalocean.md index 3d4bf71ad4..2c6576e66f 100644 --- a/docs/zh-CN/platforms/digitalocean.md +++ b/docs/zh-CN/platforms/digitalocean.md @@ -34,7 +34,7 @@ x-i18n: **选择提供商：** - DigitalOcean：最简单的用户体验 + 可预测的设置（本指南） -- Hetzner：性价比高（参见 [Hetzner 指南](/platforms/hetzner)） +- Hetzner：性价比高（参见 [Hetzner 指南](/install/hetzner)） - Oracle Cloud：可以 $0/月，但更麻烦且仅限 ARM（参见 [Oracle 指南](/platforms/oracle)） --- @@ -263,7 +263,7 @@ free -h ## 另请参阅 -- [Hetzner 指南](/platforms/hetzner) — 更便宜、更强大 +- [Hetzner 指南](/install/hetzner) — 更便宜、更强大 - [Docker 安装](/install/docker) — 容器化设置 - [Tailscale](/gateway/tailscale) — 安全远程访问 - [配置](/gateway/configuration) — 完整配置参考 diff --git a/docs/zh-CN/platforms/index.md b/docs/zh-CN/platforms/index.md index 4d0ea4e883..6609ed34aa 100644 --- a/docs/zh-CN/platforms/index.md +++ b/docs/zh-CN/platforms/index.md @@ -33,10 +33,10 @@ Windows 原生配套应用也在计划中；推荐通过 WSL2 使用 Gateway 网 ## VPS 和托管 - VPS 中心：[VPS 托管](/vps) -- Fly.io：[Fly.io](/platforms/fly) -- Hetzner（Docker）：[Hetzner](/platforms/hetzner) -- GCP（Compute Engine）：[GCP](/platforms/gcp) -- exe.dev（VM + HTTPS 代理）：[exe.dev](/platforms/exe-dev) +- Fly.io：[Fly.io](/install/fly) +- Hetzner（Docker）：[Hetzner](/install/hetzner) +- GCP（Compute Engine）：[GCP](/install/gcp) +- exe.dev（VM + HTTPS 代理）：[exe.dev](/install/exe-dev) ## 常用链接 diff --git a/docs/zh-CN/platforms/linux.md b/docs/zh-CN/platforms/linux.md index 1134f65a8d..3634f6c9d4 100644 --- a/docs/zh-CN/platforms/linux.md +++ b/docs/zh-CN/platforms/linux.md @@ -28,7 +28,7 @@ Gateway 网关在 Linux 上完全支持。**Node 是推荐的运行时**。 4. 从你的笔记本电脑：`ssh -N -L 18789:127.0.0.1:18789 @` 5. 打开 `http://127.0.0.1:18789/` 并粘贴你的令牌 -分步 VPS 指南：[exe.dev](/platforms/exe-dev) +分步 VPS 指南：[exe.dev](/install/exe-dev) ## 安装 diff --git a/docs/zh-CN/platforms/oracle.md b/docs/zh-CN/platforms/oracle.md index a880f7ab85..f290c1123d 100644 --- a/docs/zh-CN/platforms/oracle.md +++ b/docs/zh-CN/platforms/oracle.md @@ -307,4 +307,4 @@ tar -czvf openclaw-backup.tar.gz ~/.openclaw ~/.openclaw/workspace - [Tailscale 集成](/gateway/tailscale) — 完整的 Tailscale 文档 - [Gateway 网关配置](/gateway/configuration) — 所有配置选项 - [DigitalOcean 指南](/platforms/digitalocean) — 如果你想要付费 + 更容易注册 -- [Hetzner 指南](/platforms/hetzner) — 基于 Docker 的替代方案 +- [Hetzner 指南](/install/hetzner) — 基于 Docker 的替代方案 diff --git a/docs/zh-CN/platforms/raspberry-pi.md b/docs/zh-CN/platforms/raspberry-pi.md index 3a53dbd8ed..edffc432ed 100644 --- a/docs/zh-CN/platforms/raspberry-pi.md +++ b/docs/zh-CN/platforms/raspberry-pi.md @@ -360,6 +360,6 @@ echo 'wireless-power off' | sudo tee -a /etc/network/interfaces - [Linux 指南](/platforms/linux) — 通用 Linux 设置 - [DigitalOcean 指南](/platforms/digitalocean) — 云替代方案 -- [Hetzner 指南](/platforms/hetzner) — Docker 设置 +- [Hetzner 指南](/install/hetzner) — Docker 设置 - [Tailscale](/gateway/tailscale) — 远程访问 - [节点](/nodes) — 将你的笔记本电脑/手机与 Pi Gateway 网关配对 diff --git a/docs/zh-CN/start/getting-started.md b/docs/zh-CN/start/getting-started.md index b4c6ffd4d4..985122ea02 100644 --- a/docs/zh-CN/start/getting-started.md +++ b/docs/zh-CN/start/getting-started.md @@ -203,4 +203,4 @@ openclaw message send --target +15555550123 --message "Hello from OpenClaw" - macOS 菜单栏应用 + 语音唤醒：[macOS 应用](/platforms/macos) - iOS/Android 节点（Canvas/相机/语音）：[节点](/nodes) - 远程访问（SSH 隧道 / Tailscale Serve）：[远程访问](/gateway/remote) 和 [Tailscale](/gateway/tailscale) -- 常开 / VPN 设置：[远程访问](/gateway/remote)、[exe.dev](/platforms/exe-dev)、[Hetzner](/platforms/hetzner)、[macOS 远程](/platforms/mac/remote) +- 常开 / VPN 设置：[远程访问](/gateway/remote)、[exe.dev](/install/exe-dev)、[Hetzner](/install/hetzner)、[macOS 远程](/platforms/mac/remote) diff --git a/docs/zh-CN/vps.md b/docs/zh-CN/vps.md index 9ce923a1a1..88e527bc39 100644 --- a/docs/zh-CN/vps.md +++ b/docs/zh-CN/vps.md @@ -22,10 +22,10 @@ x-i18n: - **Railway**（一键 + 浏览器设置）：[Railway](/railway) - **Northflank**（一键 + 浏览器设置）：[Northflank](/northflank) - **Oracle Cloud（永久免费）**：[Oracle](/platforms/oracle) — $0/月（永久免费，ARM；容量/注册可能不太稳定） -- **Fly.io**：[Fly.io](/platforms/fly) -- **Hetzner（Docker）**：[Hetzner](/platforms/hetzner) -- **GCP（Compute Engine）**：[GCP](/platforms/gcp) -- **exe.dev**（VM + HTTPS 代理）：[exe.dev](/platforms/exe-dev) +- **Fly.io**：[Fly.io](/install/fly) +- **Hetzner（Docker）**：[Hetzner](/install/hetzner) +- **GCP（Compute Engine）**：[GCP](/install/gcp) +- **exe.dev**（VM + HTTPS 代理）：[exe.dev](/install/exe-dev) - **AWS（EC2/Lightsail/免费套餐）**：也运行良好。视频指南： https://x.com/techfrenAJ/status/2014934471095812547