158 lines
4.7 KiB
Markdown
158 lines
4.7 KiB
Markdown
---
|
||
summary: "CLI onboarding wizard: guided setup for gateway, workspace, providers, and skills"
|
||
read_when:
|
||
- Running or configuring the onboarding wizard
|
||
- Setting up a new machine
|
||
---
|
||
|
||
# Onboarding Wizard (CLI)
|
||
|
||
The onboarding wizard is the **recommended** way to set up Clawdis on any OS.
|
||
It configures a local Gateway or a remote Gateway connection, plus providers, skills,
|
||
and workspace defaults in one guided flow.
|
||
|
||
Primary entrypoint:
|
||
|
||
```bash
|
||
clawdis onboard
|
||
```
|
||
|
||
Follow‑up reconfiguration:
|
||
|
||
```bash
|
||
clawdis configure
|
||
```
|
||
|
||
## What the wizard does
|
||
|
||
**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)
|
||
|
||
**Remote mode** only configures the local client to connect to a Gateway elsewhere.
|
||
It does **not** install or change anything on the remote host.
|
||
|
||
## Flow details (local)
|
||
|
||
1) **Existing config detection**
|
||
- 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)
|
||
|
||
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.
|
||
|
||
3) **Workspace**
|
||
- Default `~/clawd` (configurable).
|
||
- Seeds the workspace files needed for the agent bootstrap ritual.
|
||
|
||
4) **Gateway**
|
||
- Port, bind, auth mode, tailscale exposure.
|
||
- Auth recommendation: keep **Off** for single-machine loopback setups. Use **Token** for multi-machine access or non-loopback binds.
|
||
- Non‑loopback binds require auth.
|
||
|
||
5) **Providers**
|
||
- WhatsApp: optional QR login.
|
||
- Telegram: bot token.
|
||
- Discord: bot token.
|
||
- Signal: optional `signal-cli` install + account config.
|
||
- iMessage: local `imsg` CLI path + DB access.
|
||
|
||
6) **Daemon install**
|
||
- macOS: LaunchAgent
|
||
- Linux: systemd user unit
|
||
- Windows: Scheduled Task
|
||
|
||
7) **Health check**
|
||
- Starts the Gateway (if needed) and runs `clawdis health`.
|
||
|
||
8) **Skills (recommended)**
|
||
- Reads the available skills and checks requirements.
|
||
- Lets you choose a node manager: **npm / pnpm / bun**.
|
||
- Installs optional dependencies (some use Homebrew on macOS).
|
||
|
||
9) **Finish**
|
||
- Summary + next steps, including iOS/Android/macOS apps for extra features.
|
||
|
||
## Remote mode
|
||
|
||
Remote mode configures a local client to connect to a Gateway elsewhere.
|
||
|
||
What you’ll set:
|
||
- Remote Gateway URL (`ws://...`)
|
||
- Optional token
|
||
|
||
Notes:
|
||
- No remote installs or daemon changes are performed.
|
||
- If the Gateway is loopback‑only, use SSH tunneling or a tailnet.
|
||
- Discovery hints:
|
||
- macOS: Bonjour (`dns-sd`)
|
||
- Linux: Avahi (`avahi-browse`)
|
||
|
||
## Non‑interactive mode
|
||
|
||
Use `--non-interactive` to automate or script onboarding:
|
||
|
||
```bash
|
||
clawdis onboard --non-interactive \
|
||
--mode local \
|
||
--auth-choice apiKey \
|
||
--anthropic-api-key "$ANTHROPIC_API_KEY" \
|
||
--gateway-port 18789 \
|
||
--gateway-bind loopback \
|
||
--skip-skills
|
||
```
|
||
|
||
Add `--json` for a machine‑readable summary.
|
||
|
||
## 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 `~/.clawdis/tools/signal-cli/<version>/`.
|
||
- Writes `signal.cliPath` to your config.
|
||
|
||
Notes:
|
||
- JVM builds require **Java 21**.
|
||
- Native builds are used when available.
|
||
- Windows auto‑install is not supported yet (manual install required).
|
||
|
||
## What the wizard writes
|
||
|
||
Typical fields in `~/.clawdis/clawdis.json`:
|
||
- `agent.workspace`
|
||
- `agent.model` / `models.providers` (if Minimax chosen)
|
||
- `gateway.*` (mode, bind, auth, tailscale)
|
||
- `telegram.botToken`, `discord.token`, `signal.*`, `imessage.*`
|
||
- `skills.install.nodeManager`
|
||
- `wizard.lastRunAt`
|
||
- `wizard.lastRunVersion`
|
||
- `wizard.lastRunCommit`
|
||
- `wizard.lastRunCommand`
|
||
- `wizard.lastRunMode`
|
||
|
||
WhatsApp credentials go to `~/.clawdis/credentials/`.
|
||
Sessions are stored under `~/.clawdis/sessions/`.
|
||
|
||
## Related docs
|
||
|
||
- macOS app onboarding: `docs/onboarding.md`
|
||
- Config reference: `docs/configuration.md`
|
||
- Providers: `docs/whatsapp.md`, `docs/telegram.md`, `docs/discord.md`, `docs/signal.md`, `docs/imessage.md`
|
||
- Skills: `docs/skills.md`, `docs/skills-config.md`
|