clawdbot/docs/wizard.md

summary, read_when

summary	read_when
CLI onboarding wizard: guided setup for gateway, workspace, providers, and skills	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:

clawdis onboard

Follow‑up reconfiguration:

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:

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.

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