let5see/clawdbot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: recommend global install and daemon onboarding

Browse Source
This commit is contained in:
Peter Steinberger
2026-01-08 09:59:10 +01:00
parent bfd3eb46c7
commit 712cfa94aa
4 changed files with 107 additions and 73 deletions
Download Patch File Download Diff File Expand all files Collapse all files

51
README.md
View File

@@ -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) - 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) - 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. Runtime: **Node ≥22**.
Prefer `pnpm` for builds from source. Bun is optional for running TypeScript directly.
```bash ```bash
# Clone this repo pnpm add -g clawdbot@latest
git clone https://github.com/clawdbot/clawdbot.git # or: npm install -g clawdbot@latest
cd clawdbot
pnpm install clawdbot onboard --install-daemon
pnpm ui:install
pnpm ui:build
pnpm build
pnpm clawdbot onboard
``` ```
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) ## 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) Full beginner guide (auth, pairing, providers): [Getting started](https://docs.clawd.bot/getting-started)
```bash ```bash
pnpm clawdbot onboard clawdbot onboard --install-daemon
pnpm clawdbot gateway --port 18789 --verbose clawdbot gateway --port 18789 --verbose
# Dev loop (auto-reload on TS changes)
pnpm gateway:watch
# Send a message # 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) # 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`). 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) ## Security defaults (DM access)

24
docs/index.md
View File

@@ -98,18 +98,32 @@ Note: legacy Claude/Codex/Gemini/Opencode paths have been removed; Pi is the onl
Runtime requirement: **Node ≥ 22**. Runtime requirement: **Node ≥ 22**.
```bash ```bash
# From source (recommended while the npm package is still settling) # Recommended: global install (npm/pnpm)
pnpm install pnpm add -g clawdbot@latest
pnpm build # or: npm install -g clawdbot@latest
pnpm link --global
# Onboard + install the daemon (launchd/systemd user service)
clawdbot onboard --install-daemon
# Pair WhatsApp Web (shows QR) # Pair WhatsApp Web (shows QR)
clawdbot providers login clawdbot providers login
# Run the Gateway (leave running) # Gateway runs via daemon after onboarding; manual run is still possible:
clawdbot gateway --port 18789 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): Multi-instance quickstart (optional):
```bash ```bash

13
docs/start/clawd.md
View File

@@ -23,13 +23,22 @@ Start conservative:
## Prerequisites ## Prerequisites
- Node **22+** - 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 - 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 ```bash
git clone https://github.com/clawdbot/clawdbot.git
cd clawdbot
pnpm install pnpm install
pnpm ui:install
pnpm ui:build
pnpm build pnpm build
pnpm link --global pnpm link --global
``` ```

92
docs/start/getting-started.md
View File

@@ -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: read_when:
- First time setup from zero - 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 # Getting Started
@@ -22,49 +22,29 @@ If you want the deeper reference pages, jump to: [Wizard](/start/wizard), [Setup
## 0) Prereqs ## 0) Prereqs
- Node `>=22` - Node `>=22`
- `pnpm` (recommended) or `bun` (optional) - `pnpm` (optional; recommended if you build from source)
- Git
macOS: if you plan to build the apps, install Xcode / CLT. For the CLI + gateway only, Node is enough. 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). 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 ```bash
git clone https://github.com/clawdbot/clawdbot.git pnpm add -g clawdbot@latest
cd clawdbot # or: npm install -g clawdbot@latest
pnpm install
``` ```
Note: Bun is optional if you prefer running TypeScript directly: ## 2) Run the onboarding wizard (and install the daemon)
```bash ```bash
bun install clawdbot onboard --install-daemon
```
## 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
``` ```
What you’ll choose: What you’ll choose:
- **Local vs Remote** gateway - **Local vs Remote** gateway
- **Auth**: Anthropic OAuth or OpenAI OAuth (recommended), API key (optional), or skip for now - **Auth**: Anthropic OAuth or OpenAI OAuth (recommended), API key (optional), or skip for now
- **Providers**: WhatsApp QR login, Telegram/Discord bot tokens, etc. - **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) - **Runtime**: Node (recommended; required for WhatsApp) or Bun (faster, but incompatible with WhatsApp)
Wizard doc: [Wizard](/start/wizard) 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. 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 ```bash
# If you installed the CLI (npm/pnpm link --global):
clawdbot gateway --port 18789 --verbose 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/` 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 reconnect. If you use WhatsApp, run the Gateway with **Node** until this is
resolved. Baileys: https://github.com/WhiskeySockets/Baileys · Bun issue: resolved. Baileys: https://github.com/WhiskeySockets/Baileys · Bun issue:
https://github.com/oven-sh/bun/issues/5951 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) ### WhatsApp (QR login)
```bash ```bash
pnpm clawdbot providers login clawdbot providers login
``` ```
Scan via WhatsApp → Settings → Linked Devices. 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. **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. 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: If your first DM gets no reply, approve the pairing:
Approve:
```bash ```bash
pnpm clawdbot pairing list --provider telegram clawdbot pairing list --provider whatsapp
pnpm clawdbot pairing approve --provider telegram <CODE> clawdbot pairing approve --provider whatsapp <code>
``` ```
Pairing doc: [Pairing](/start/pairing) 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 ## 7) Verify end-to-end
In a new terminal: In a new terminal:
```bash ```bash
pnpm clawdbot health clawdbot health
pnpm clawdbot send --to +15555550123 --message "Hello from Clawdbot" 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. 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. Local probe tip: `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). Gateway snapshot: `clawdbot providers status` shows what the gateway reports (use `status --deep` for local-only probes).
## Next steps (optional, but great) ## Next steps (optional, but great)