From 712cfa94aaccc5890042fbc216702b416b20267e Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Thu, 8 Jan 2026 09:59:10 +0100 Subject: [PATCH] docs: recommend global install and daemon onboarding --- README.md | 51 +++++++++++-------- docs/index.md | 24 +++++++-- docs/start/clawd.md | 13 ++++- docs/start/getting-started.md | 92 ++++++++++++++++++----------------- 4 files changed, 107 insertions(+), 73 deletions(-) diff --git a/README.md b/README.md index b9147af68..4bd2740e1 100644 --- a/README.md +++ b/README.md @@ -37,25 +37,18 @@ Model note: while any model is supported, I strongly recommend **Anthropic Pro/M - Models config + CLI: [Models](https://docs.clawd.bot/models) - Auth profile rotation (OAuth vs API keys) + fallbacks: [Model failover](https://docs.clawd.bot/model-failover) -## Recommended setup (from source) +## Install (recommended) -Do **not** download prebuilt binaries. Run from source. - -Prefer `pnpm` for builds from source. Bun is optional for running TypeScript directly. +Runtime: **Node ≥22**. ```bash -# Clone this repo -git clone https://github.com/clawdbot/clawdbot.git -cd clawdbot +pnpm add -g clawdbot@latest +# or: npm install -g clawdbot@latest -pnpm install -pnpm ui:install -pnpm ui:build -pnpm build -pnpm clawdbot onboard +clawdbot onboard --install-daemon ``` -Note: `pnpm clawdbot ...` runs TypeScript directly (via `tsx`). `pnpm build` produces `dist/` for running via Node / the packaged `clawdbot` binary. +The wizard installs the Gateway daemon (launchd/systemd user service) so it stays running. ## Quick start (TL;DR) @@ -64,23 +57,39 @@ Runtime: **Node ≥22**. Full beginner guide (auth, pairing, providers): [Getting started](https://docs.clawd.bot/getting-started) ```bash -pnpm clawdbot onboard +clawdbot onboard --install-daemon -pnpm clawdbot gateway --port 18789 --verbose - -# Dev loop (auto-reload on TS changes) -pnpm gateway:watch +clawdbot gateway --port 18789 --verbose # Send a message -pnpm clawdbot send --to +1234567890 --message "Hello from Clawdbot" +clawdbot send --to +1234567890 --message "Hello from Clawdbot" # Talk to the assistant (optionally deliver back to WhatsApp/Telegram/Slack/Discord) -pnpm clawdbot agent --message "Ship checklist" --thinking high +clawdbot agent --message "Ship checklist" --thinking high ``` Upgrading? [Updating guide](https://docs.clawd.bot/updating) (and run `clawdbot doctor`). -If you run from source, prefer `pnpm clawdbot …` (not global `clawdbot`). +## From source (development) + +Prefer `pnpm` for builds from source. Bun is optional for running TypeScript directly. + +```bash +git clone https://github.com/clawdbot/clawdbot.git +cd clawdbot + +pnpm install +pnpm ui:install +pnpm ui:build +pnpm build + +pnpm clawdbot onboard --install-daemon + +# Dev loop (auto-reload on TS changes) +pnpm gateway:watch +``` + +Note: `pnpm clawdbot ...` runs TypeScript directly (via `tsx`). `pnpm build` produces `dist/` for running via Node / the packaged `clawdbot` binary. ## Security defaults (DM access) diff --git a/docs/index.md b/docs/index.md index d54c50cfb..bc4e75a44 100644 --- a/docs/index.md +++ b/docs/index.md @@ -98,18 +98,32 @@ Note: legacy Claude/Codex/Gemini/Opencode paths have been removed; Pi is the onl Runtime requirement: **Node ≥ 22**. ```bash -# From source (recommended while the npm package is still settling) -pnpm install -pnpm build -pnpm link --global +# Recommended: global install (npm/pnpm) +pnpm add -g clawdbot@latest +# or: npm install -g clawdbot@latest + +# Onboard + install the daemon (launchd/systemd user service) +clawdbot onboard --install-daemon # Pair WhatsApp Web (shows QR) clawdbot providers login -# Run the Gateway (leave running) +# Gateway runs via daemon after onboarding; manual run is still possible: clawdbot gateway --port 18789 ``` +From source (development): + +```bash +git clone https://github.com/clawdbot/clawdbot.git +cd clawdbot +pnpm install +pnpm ui:install +pnpm ui:build +pnpm build +pnpm clawdbot onboard --install-daemon +``` + Multi-instance quickstart (optional): ```bash diff --git a/docs/start/clawd.md b/docs/start/clawd.md index fb781d7ee..3054588aa 100644 --- a/docs/start/clawd.md +++ b/docs/start/clawd.md @@ -23,13 +23,22 @@ Start conservative: ## Prerequisites - Node **22+** -- CLAWDBOT available on PATH (recommended during development: from source + global link) +- CLAWDBOT available on PATH (recommended: global install) - A second phone number (SIM/eSIM/prepaid) for the assistant -From source (recommended while the npm package is still settling): +```bash +pnpm add -g clawdbot@latest +# or: npm install -g clawdbot@latest +``` + +From source (development): ```bash +git clone https://github.com/clawdbot/clawdbot.git +cd clawdbot pnpm install +pnpm ui:install +pnpm ui:build pnpm build pnpm link --global ``` diff --git a/docs/start/getting-started.md b/docs/start/getting-started.md index 63e14e49d..b2fd93f04 100644 --- a/docs/start/getting-started.md +++ b/docs/start/getting-started.md @@ -1,8 +1,8 @@ --- -summary: "Beginner guide: from repo checkout to first message (wizard, auth, providers, pairing)" +summary: "Beginner guide: from zero to first message (wizard, auth, providers, pairing)" read_when: - First time setup from zero - - You want the fastest path from checkout → onboarding → first message + - You want the fastest path from install → onboarding → first message --- # Getting Started @@ -22,49 +22,29 @@ If you want the deeper reference pages, jump to: [Wizard](/start/wizard), [Setup ## 0) Prereqs - Node `>=22` -- `pnpm` (recommended) or `bun` (optional) -- Git +- `pnpm` (optional; recommended if you build from source) 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 and more problematic. Install WSL2 first, then run the Linux steps inside WSL. See [Windows (WSL2)](/platforms/windows). -## 1) Check out from source +## 1) Install the CLI (recommended) ```bash -git clone https://github.com/clawdbot/clawdbot.git -cd clawdbot -pnpm install +pnpm add -g clawdbot@latest +# or: npm install -g clawdbot@latest ``` -Note: Bun is optional if you prefer running TypeScript directly: +## 2) Run the onboarding wizard (and install the daemon) ```bash -bun install -``` - -## 2) Control UI (auto + fallback) - -The Gateway serves the browser dashboard (Control UI) when assets exist. -The wizard tries to build these for you. If it fails, run: - -```bash -pnpm ui:install -pnpm ui:build -``` - -If you skip UI build, the gateway still works — you just won’t get the dashboard. - -## 3) Run the onboarding wizard - -```bash -pnpm clawdbot onboard +clawdbot onboard --install-daemon ``` What you’ll choose: - **Local vs Remote** gateway - **Auth**: Anthropic OAuth or OpenAI OAuth (recommended), API key (optional), or skip for now - **Providers**: WhatsApp QR login, Telegram/Discord bot tokens, etc. -- **Daemon**: optional background install (launchd/systemd; WSL2 uses systemd) +- **Daemon**: background install (launchd/systemd; WSL2 uses systemd) - **Runtime**: Node (recommended; required for WhatsApp) or Bun (faster, but incompatible with WhatsApp) Wizard doc: [Wizard](/start/wizard) @@ -76,15 +56,18 @@ Wizard doc: [Wizard](/start/wizard) Headless/server tip: do OAuth on a normal machine first, then copy `oauth.json` to the gateway host. -## 4) Start the Gateway +## 3) Start the Gateway -If the wizard didn’t start it for you: +If you installed the daemon during onboarding, the Gateway should already be running: + +```bash +clawdbot daemon status +``` + +Manual run (foreground): ```bash -# If you installed the CLI (npm/pnpm link --global): clawdbot gateway --port 18789 --verbose -# From this repo: -node dist/entry.js gateway --port 18789 --verbose ``` Dashboard (local loopback): `http://127.0.0.1:18789/` @@ -94,12 +77,13 @@ path that is currently incompatible with Bun and can cause memory corruption on reconnect. If you use WhatsApp, run the Gateway with **Node** until this is resolved. Baileys: https://github.com/WhiskeySockets/Baileys · Bun issue: https://github.com/oven-sh/bun/issues/5951 -## 5) Pair + connect your first chat surface + +## 4) Pair + connect your first chat surface ### WhatsApp (QR login) ```bash -pnpm clawdbot providers login +clawdbot providers login ``` Scan via WhatsApp → Settings → Linked Devices. @@ -114,33 +98,51 @@ The wizard can write tokens/config for you. If you prefer manual config, start w **Telegram DM tip:** your first DM returns a pairing code. Approve it (see next step) or the bot won’t respond. -## 6) DM safety (pairing approvals) +## 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: -Approve: - ```bash -pnpm clawdbot pairing list --provider telegram -pnpm clawdbot pairing approve --provider telegram +clawdbot pairing list --provider whatsapp +clawdbot pairing approve --provider whatsapp ``` Pairing doc: [Pairing](/start/pairing) +## From source (development) + +If you’re hacking on Clawdbot itself, run from source: + +```bash +git clone https://github.com/clawdbot/clawdbot.git +cd clawdbot +pnpm install +pnpm ui:install +pnpm ui:build +pnpm build +pnpm clawdbot onboard --install-daemon +``` + +Gateway (from this repo): + +```bash +node dist/entry.js gateway --port 18789 --verbose +``` + ## 7) Verify end-to-end In a new terminal: ```bash -pnpm clawdbot health -pnpm clawdbot send --to +15555550123 --message "Hello from Clawdbot" +clawdbot health +clawdbot send --to +15555550123 --message "Hello from Clawdbot" ``` If `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. -Local probe tip: `pnpm clawdbot status --deep` runs provider checks without needing a gateway connection. -Gateway snapshot: `pnpm clawdbot providers status` shows what the gateway reports (use `status --deep` for local-only probes). +Local probe tip: `clawdbot status --deep` runs provider checks without needing a gateway connection. +Gateway snapshot: `clawdbot providers status` shows what the gateway reports (use `status --deep` for local-only probes). ## Next steps (optional, but great)