docs: refresh onboarding wizard docs
This commit is contained in:
Peter Steinberger
@@ -19,7 +19,9 @@ It answers you on the surfaces you already use (WhatsApp, Telegram, Discord, Web
|
|||||||
|
|
||||||
If you want a private, single-user assistant that feels local, fast, and always-on, this is it.
|
If you want a private, single-user assistant that feels local, fast, and always-on, this is it.
|
||||||
|
|
||||||
Preferred setup: run the onboarding wizard (`clawdis onboard`). It walks through gateway, workspace, providers, and skills. The CLI wizard is the recommended path and works on **macOS, Windows, and Linux** (see `docs/wizard.md`).
|
Website: https://clawd.me · Docs: [`docs/index.md`](docs/index.md) · Wizard: [`docs/wizard.md`](docs/wizard.md)
|
||||||
|
|
||||||
|
Preferred setup: run the onboarding wizard (`clawdis onboard`). It walks through gateway, workspace, providers, and skills. The CLI wizard is the recommended path and works on **macOS, Windows, and Linux**.
|
||||||
|
|
||||||
Using Claude Pro/Max subscription? See `docs/onboarding.md` for the Anthropic OAuth setup.
|
Using Claude Pro/Max subscription? See `docs/onboarding.md` for the Anthropic OAuth setup.
|
||||||
|
|
||||||
@@ -66,6 +68,9 @@ pnpm install
|
|||||||
pnpm build
|
pnpm build
|
||||||
pnpm ui:build
|
pnpm ui:build
|
||||||
|
|
||||||
|
# Recommended: run the onboarding wizard
|
||||||
|
pnpm clawdis onboard
|
||||||
|
|
||||||
# Link WhatsApp (stores creds in ~/.clawdis/credentials)
|
# Link WhatsApp (stores creds in ~/.clawdis/credentials)
|
||||||
pnpm clawdis login
|
pnpm clawdis login
|
||||||
|
|
||||||
@@ -210,6 +215,7 @@ Browser control (optional):
|
|||||||
- [`docs/discovery.md`](docs/discovery.md)
|
- [`docs/discovery.md`](docs/discovery.md)
|
||||||
- [`docs/agent.md`](docs/agent.md)
|
- [`docs/agent.md`](docs/agent.md)
|
||||||
- [`docs/discord.md`](docs/discord.md)
|
- [`docs/discord.md`](docs/discord.md)
|
||||||
|
- [`docs/wizard.md`](docs/wizard.md)
|
||||||
- Webhooks + external triggers: [`docs/webhook.md`](docs/webhook.md)
|
- Webhooks + external triggers: [`docs/webhook.md`](docs/webhook.md)
|
||||||
- Gmail hooks (email → wake): [`docs/gmail-pubsub.md`](docs/gmail-pubsub.md)
|
- Gmail hooks (email → wake): [`docs/gmail-pubsub.md`](docs/gmail-pubsub.md)
|
||||||
|
|
||||||
|
|||||||
282
docs/wizard.md
282
docs/wizard.md
@@ -1,222 +1,150 @@
|
|||||||
---
|
---
|
||||||
summary: "CLI onboarding wizard spec (gateway + workspace + skills + daemon)"
|
summary: "CLI onboarding wizard: guided setup for gateway, workspace, providers, and skills"
|
||||||
read_when:
|
read_when:
|
||||||
- Designing or implementing the onboarding wizard
|
- Running or configuring the onboarding wizard
|
||||||
- Changing gateway install/setup flow
|
- Setting up a new machine
|
||||||
---
|
---
|
||||||
|
|
||||||
# Onboarding Wizard (CLI)
|
# Onboarding Wizard (CLI)
|
||||||
|
|
||||||
Goal: interactive wizards for first-run onboarding **and** ongoing reconfiguration.
|
The onboarding wizard is the **recommended** way to set up Clawdis on any OS.
|
||||||
Uses `@clack/prompts` for arrow-key selection and step UX.
|
It configures a local Gateway or a remote Gateway connection, plus providers, skills,
|
||||||
|
and workspace defaults in one guided flow.
|
||||||
|
|
||||||
Scope: local gateway setup plus **remote gateway client config** (no remote-side installs).
|
Primary entrypoint:
|
||||||
|
|
||||||
## Entry points
|
```bash
|
||||||
|
clawdis onboard
|
||||||
|
```
|
||||||
|
|
||||||
First run:
|
Follow‑up reconfiguration:
|
||||||
- `clawdis onboard` (primary)
|
|
||||||
- `clawdis setup --wizard` (alias)
|
|
||||||
|
|
||||||
Ongoing:
|
```bash
|
||||||
- `clawdis configure` (models/providers/skills/gateway/workspace)
|
clawdis configure
|
||||||
- `clawdis doctor` (health + quick fixes)
|
```
|
||||||
- `clawdis update` (audit + modernize config defaults)
|
|
||||||
|
|
||||||
## Non-interactive mode
|
## What the wizard does
|
||||||
|
|
||||||
`--non-interactive` + flags to skip prompts. `--json` outputs a machine summary.
|
**Local mode (default)** walks you through:
|
||||||
|
- Model/auth (Anthropic OAuth recommended, API key optional, Minimax M2.1 via LM Studio)
|
||||||
|
- Workspace location + bootstrap files
|
||||||
|
- Gateway settings (port/bind/auth/tailscale)
|
||||||
|
- Providers (WhatsApp, Telegram, Discord, Signal)
|
||||||
|
- Daemon install (LaunchAgent / systemd user unit / Scheduled Task)
|
||||||
|
- Health check
|
||||||
|
- Skills (recommended)
|
||||||
|
|
||||||
## Preflight
|
**Remote mode** only configures the local client to connect to a Gateway elsewhere.
|
||||||
|
It does **not** install or change anything on the remote host.
|
||||||
|
|
||||||
- Runtime: Node >=22 (reuse `runtime-guard`).
|
## Flow details (local)
|
||||||
- Detect existing files:
|
|
||||||
- config: `~/.clawdis/clawdis.json`
|
|
||||||
- creds: `~/.clawdis/credentials/`
|
|
||||||
- sessions: `~/.clawdis/sessions/`
|
|
||||||
- workspace: `~/clawd` (or configured)
|
|
||||||
- Detect available package managers: `npm`, `pnpm`, `bun`.
|
|
||||||
- Detect optional tools: `brew`, `uv`, `go`.
|
|
||||||
|
|
||||||
If config exists:
|
1) **Existing config detection**
|
||||||
- Prompt: **Keep / Modify / Reset**
|
- If `~/.clawdis/clawdis.json` exists, choose **Keep / Modify / Reset**.
|
||||||
|
- Reset uses `trash` (never `rm`) and offers scopes:
|
||||||
|
- Config only
|
||||||
|
- Config + credentials + sessions
|
||||||
|
- Full reset (also removes workspace)
|
||||||
|
|
||||||
Reset uses `trash` (never `rm`).
|
2) **Model/Auth**
|
||||||
|
- **Anthropic OAuth (recommended)**: browser flow; paste the `code#state`.
|
||||||
|
- **API key**: stores the key for you.
|
||||||
|
- **Minimax M2.1 (LM Studio)**: config is auto‑written for the LM Studio endpoint.
|
||||||
|
- **Skip**: no auth configured yet.
|
||||||
|
|
||||||
## Flow (interactive)
|
3) **Workspace**
|
||||||
|
- Default `~/clawd` (configurable).
|
||||||
|
- Seeds the workspace files needed for the agent bootstrap ritual.
|
||||||
|
|
||||||
1) **Mode**
|
4) **Gateway**
|
||||||
- Local (full wizard)
|
- Port, bind, auth mode, tailscale exposure.
|
||||||
- Remote (configure client connection only)
|
- Non‑loopback binds require auth.
|
||||||
|
|
||||||
2) **Model/Auth (local only)**
|
5) **Providers**
|
||||||
- Anthropic OAuth (recommended)
|
- WhatsApp: optional QR login.
|
||||||
- API key
|
- Telegram: bot token.
|
||||||
- Minimax M2.1 (LM Studio; recommended local model)
|
- Discord: bot token.
|
||||||
- Skip
|
- Signal: optional `signal-cli` install + account config.
|
||||||
|
|
||||||
3) **Workspace + config**
|
6) **Daemon install**
|
||||||
- Default workspace: `~/clawd`
|
|
||||||
- Writes `agent.workspace` into `~/.clawdis/clawdis.json`
|
|
||||||
- Ensures sessions dir exists
|
|
||||||
|
|
||||||
4) **Gateway config**
|
|
||||||
- Port (default 18789)
|
|
||||||
- Bind: loopback | lan | tailnet | auto
|
|
||||||
- Auth: token | password | off
|
|
||||||
- Tailscale: off | serve | funnel
|
|
||||||
|
|
||||||
5) **Providers (optional)**
|
|
||||||
- WhatsApp: optional `clawdis login` QR flow
|
|
||||||
- Telegram: bot token (config or env)
|
|
||||||
- Discord: bot token (config or env)
|
|
||||||
- Signal: `signal-cli` detection + account config + install option
|
|
||||||
|
|
||||||
6) **Daemon install (local only)**
|
|
||||||
- macOS: LaunchAgent
|
- macOS: LaunchAgent
|
||||||
- Linux: systemd user unit
|
- Linux: systemd user unit
|
||||||
- Windows: Scheduled Task
|
- Windows: Scheduled Task
|
||||||
|
|
||||||
7) **Health**
|
7) **Health check**
|
||||||
- Start/restart daemon
|
- Starts the Gateway (if needed) and runs `clawdis health`.
|
||||||
- `clawdis health` summary
|
|
||||||
|
|
||||||
8) **Skills (recommended)**
|
8) **Skills (recommended)**
|
||||||
- Read from `buildWorkspaceSkillStatus`
|
- Reads the available skills and checks requirements.
|
||||||
- Show eligible vs missing requirements
|
- Lets you choose a node manager: **npm / pnpm / bun**.
|
||||||
- Offer installs via preferred installer
|
- Installs optional dependencies (some use Homebrew on macOS).
|
||||||
- Allow skip
|
|
||||||
|
|
||||||
9) **Finish**
|
9) **Finish**
|
||||||
- Summary + next steps
|
- Summary + next steps, including iOS/Android/macOS apps for extra features.
|
||||||
- Reminder: iOS/Android/macOS node apps add canvas/camera/screen/system features.
|
|
||||||
|
|
||||||
## Remote mode (client config)
|
## Remote mode
|
||||||
|
|
||||||
- Optional Bonjour discovery (macOS: `dns-sd`, Linux: `avahi-browse`)
|
Remote mode configures a local client to connect to a Gateway elsewhere.
|
||||||
- Save `gateway.remote.url` (+ optional `gateway.remote.token`)
|
|
||||||
- Token optional; omit for no-auth gateways
|
|
||||||
- Provide SSH tunnel hint when the gateway is loopback-only
|
|
||||||
- No remote installs or daemon changes from this machine
|
|
||||||
|
|
||||||
## Config writes
|
What you’ll set:
|
||||||
|
- Remote Gateway URL (`ws://...`)
|
||||||
Wizard writes:
|
- Optional token
|
||||||
- `~/.clawdis/clawdis.json`
|
|
||||||
- `agent.workspace`
|
|
||||||
- `agent.model` + `models.providers` (if Minimax selected)
|
|
||||||
- `skills.install.nodeManager` (npm | pnpm | bun)
|
|
||||||
- `skills.entries.<key>.env` / `.apiKey` (if set in skills step)
|
|
||||||
- `telegram.botToken`, `discord.token`, `signal.*` (if set in providers step)
|
|
||||||
- `wizard.lastRunAt`, `wizard.lastRunVersion`, `wizard.lastRunCommit`, `wizard.lastRunCommand`, `wizard.lastRunMode`
|
|
||||||
- `gateway.remote.url`, `gateway.remote.token` (remote mode)
|
|
||||||
|
|
||||||
WhatsApp login writes credentials to `~/.clawdis/credentials/creds.json`.
|
|
||||||
|
|
||||||
## Configure / Doctor / Update flows
|
|
||||||
|
|
||||||
`clawdis configure` offers a menu of sections:
|
|
||||||
- Model/auth
|
|
||||||
- Providers (incl Signal install)
|
|
||||||
- Gateway + daemon
|
|
||||||
- Workspace + bootstrap files
|
|
||||||
- Skills
|
|
||||||
- Health check (optional at end)
|
|
||||||
|
|
||||||
`clawdis doctor`:
|
|
||||||
- Gateway reachability
|
|
||||||
- Provider probes
|
|
||||||
- Skills status
|
|
||||||
- Quick fixes (start gateway, relink WhatsApp, prompt missing tokens)
|
|
||||||
|
|
||||||
`clawdis update`:
|
|
||||||
- Audit config vs defaults
|
|
||||||
- Suggest upgrades/changes
|
|
||||||
- Re-run key steps as needed
|
|
||||||
|
|
||||||
Each wizard run updates `wizard.*` metadata.
|
|
||||||
|
|
||||||
## Signal CLI install (wizard)
|
|
||||||
|
|
||||||
Wizard can install signal-cli from GitHub releases:
|
|
||||||
- Fetch latest release from `https://github.com/AsamK/signal-cli/releases/latest`
|
|
||||||
- Download platform asset (Linux native preferred)
|
|
||||||
- Extract under `~/.clawdis/tools/signal-cli/<version>/`
|
|
||||||
- Set `signal.cliPath` to the detected `signal-cli` binary
|
|
||||||
|
|
||||||
Notes:
|
Notes:
|
||||||
- signal-cli requires Java 21 for JVM builds.
|
- No remote installs or daemon changes are performed.
|
||||||
- Native builds are available for some platforms; fallback to JVM build if native not found.
|
- If the Gateway is loopback‑only, use SSH tunneling or a tailnet.
|
||||||
- Auto-install is not supported on Windows yet.
|
- Discovery hints:
|
||||||
|
- macOS: Bonjour (`dns-sd`)
|
||||||
|
- Linux: Avahi (`avahi-browse`)
|
||||||
|
|
||||||
## Minimax M2.1 (LM Studio) config snippet
|
## Non‑interactive mode
|
||||||
|
|
||||||
```json5
|
Use `--non-interactive` to automate or script onboarding:
|
||||||
{
|
|
||||||
agent: {
|
```bash
|
||||||
model: "Minimax",
|
clawdis onboard --non-interactive \
|
||||||
allowedModels: [
|
--mode local \
|
||||||
"anthropic/claude-opus-4-5",
|
--auth-choice apiKey \
|
||||||
"lmstudio/minimax-m2.1-gs32"
|
--anthropic-api-key "$ANTHROPIC_API_KEY" \
|
||||||
],
|
--gateway-port 18789 \
|
||||||
modelAliases: {
|
--gateway-bind loopback \
|
||||||
Opus: "anthropic/claude-opus-4-5",
|
--skip-skills
|
||||||
Minimax: "lmstudio/minimax-m2.1-gs32"
|
|
||||||
}
|
|
||||||
},
|
|
||||||
models: {
|
|
||||||
mode: "merge",
|
|
||||||
providers: {
|
|
||||||
lmstudio: {
|
|
||||||
baseUrl: "http://127.0.0.1:1234/v1",
|
|
||||||
apiKey: "lmstudio",
|
|
||||||
api: "openai-responses",
|
|
||||||
models: [
|
|
||||||
{
|
|
||||||
id: "minimax-m2.1-gs32",
|
|
||||||
name: "MiniMax M2.1 GS32",
|
|
||||||
reasoning: false,
|
|
||||||
input: ["text"],
|
|
||||||
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
|
|
||||||
contextWindow: 196608,
|
|
||||||
maxTokens: 8192
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## Skills install preferences
|
Add `--json` for a machine‑readable summary.
|
||||||
|
|
||||||
Prompt for node manager:
|
## Signal setup (signal-cli)
|
||||||
- npm
|
|
||||||
- pnpm
|
|
||||||
- bun
|
|
||||||
|
|
||||||
Writes:
|
The wizard can install `signal-cli` from GitHub releases:
|
||||||
|
- Downloads the appropriate release asset.
|
||||||
|
- Stores it under `~/.clawdis/tools/signal-cli/<version>/`.
|
||||||
|
- Writes `signal.cliPath` to your config.
|
||||||
|
|
||||||
```json5
|
Notes:
|
||||||
{
|
- JVM builds require **Java 21**.
|
||||||
skills: {
|
- Native builds are used when available.
|
||||||
install: {
|
- Windows auto‑install is not supported yet (manual install required).
|
||||||
nodeManager: "npm" // npm | pnpm | bun
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Reset scope (decision required)
|
## What the wizard writes
|
||||||
|
|
||||||
Options:
|
Typical fields in `~/.clawdis/clawdis.json`:
|
||||||
- A) Config only (`~/.clawdis/clawdis.json`)
|
- `agent.workspace`
|
||||||
- B) Config + credentials + sessions
|
- `agent.model` / `models.providers` (if Minimax chosen)
|
||||||
- C) Full reset: config + credentials + sessions + workspace
|
- `gateway.*` (mode, bind, auth, tailscale)
|
||||||
|
- `telegram.botToken`, `discord.token`, `signal.*`
|
||||||
|
- `skills.install.nodeManager`
|
||||||
|
- `wizard.lastRunAt`
|
||||||
|
- `wizard.lastRunVersion`
|
||||||
|
- `wizard.lastRunCommit`
|
||||||
|
- `wizard.lastRunCommand`
|
||||||
|
- `wizard.lastRunMode`
|
||||||
|
|
||||||
Wizard should clearly list what will be removed and use `trash`.
|
WhatsApp credentials go to `~/.clawdis/credentials/`.
|
||||||
|
Sessions are stored under `~/.clawdis/sessions/`.
|
||||||
|
|
||||||
## Open questions
|
## Related docs
|
||||||
|
|
||||||
- Confirm “Remote = info-only” is final.
|
- macOS app onboarding: `docs/onboarding.md`
|
||||||
- Confirm reset scope default (A/B/C).
|
- Config reference: `docs/configuration.md`
|
||||||
|
- Providers: `docs/whatsapp.md`, `docs/telegram.md`, `docs/discord.md`, `docs/signal.md`
|
||||||
|
- Skills: `docs/skills.md`, `docs/skills-config.md`
|
||||||
|
|||||||
Reference in New Issue
Block a user