@termix-it/cryptoclaw 1.0.0

package/docs/start/wizard-cli-reference.md

@@ -0,0 +1,244 @@
+---
+summary: "Complete reference for CLI onboarding flow, auth/model setup, outputs, and internals"
+read_when:
+  - You need detailed behavior for openclaw onboard
+  - You are debugging onboarding results or integrating onboarding clients
+title: "CLI Onboarding Reference"
+sidebarTitle: "CLI reference"
+---
+
+# CLI Onboarding Reference
+
+This page is the full reference for `openclaw onboard`.
+For the short guide, see [Onboarding Wizard (CLI)](/start/wizard).
+
+## What the wizard does
+
+Local mode (default) walks you through:
+
+- Model and auth setup (OpenAI Code subscription OAuth, Anthropic API key or setup token, plus MiniMax, GLM, Moonshot, and AI Gateway options)
+- Workspace location and bootstrap files
+- Gateway settings (port, bind, auth, tailscale)
+- Channels and providers (Telegram, WhatsApp, Discord, Google Chat, Mattermost plugin, Signal)
+- Daemon install (LaunchAgent or systemd user unit)
+- Health check
+- Skills setup
+
+Remote mode configures this machine to connect to a gateway elsewhere.
+It does not install or modify anything on the remote host.
+
+## Local flow details
+
+<Steps>
+  <Step title="Existing config detection">
+    - If `~/.openclaw/openclaw.json` exists, choose Keep, Modify, or Reset.
+    - Re-running the wizard does not wipe anything unless you explicitly choose Reset (or pass `--reset`).
+    - If config is invalid or contains legacy keys, the wizard stops and asks you to run `openclaw doctor` before continuing.
+    - Reset uses `trash` and offers scopes:
+      - Config only
+      - Config + credentials + sessions
+      - Full reset (also removes workspace)
+  </Step>
+  <Step title="Model and auth">
+    - Full option matrix is in [Auth and model options](#auth-and-model-options).
+  </Step>
+  <Step title="Workspace">
+    - Default `~/.openclaw/workspace` (configurable).
+    - Seeds workspace files needed for first-run bootstrap ritual.
+    - Workspace layout: [Agent workspace](/concepts/agent-workspace).
+  </Step>
+  <Step title="Gateway">
+    - Prompts for port, bind, auth mode, and tailscale exposure.
+    - Recommended: keep token auth enabled even for loopback so local WS clients must authenticate.
+    - Disable auth only if you fully trust every local process.
+    - Non-loopback binds still require auth.
+  </Step>
+  <Step title="Channels">
+    - [WhatsApp](/channels/whatsapp): optional QR login
+    - [Telegram](/channels/telegram): bot token
+    - [Discord](/channels/discord): bot token
+    - [Google Chat](/channels/googlechat): service account JSON + webhook audience
+    - [Mattermost](/channels/mattermost) plugin: bot token + base URL
+    - [Signal](/channels/signal): optional `signal-cli` install + account config
+    - [BlueBubbles](/channels/bluebubbles): recommended for iMessage; server URL + password + webhook
+    - [iMessage](/channels/imessage): legacy `imsg` CLI path + DB access
+    - DM security: default is pairing. First DM sends a code; approve via
+      `openclaw pairing approve <channel> <code>` or use allowlists.
+  </Step>
+  <Step title="Daemon install">
+    - macOS: LaunchAgent
+      - Requires logged-in user session; for headless, use a custom LaunchDaemon (not shipped).
+    - Linux and Windows via WSL2: systemd user unit
+      - Wizard attempts `loginctl enable-linger <user>` so gateway stays up after logout.
+      - May prompt for sudo (writes `/var/lib/systemd/linger`); it tries without sudo first.
+    - Runtime selection: Node (recommended; required for WhatsApp and Telegram). Bun is not recommended.
+  </Step>
+  <Step title="Health check">
+    - Starts gateway (if needed) and runs `openclaw health`.
+    - `openclaw status --deep` adds gateway health probes to status output.
+  </Step>
+  <Step title="Skills">
+    - Reads available skills and checks requirements.
+    - Lets you choose node manager: npm or pnpm (bun not recommended).
+    - Installs optional dependencies (some use Homebrew on macOS).
+  </Step>
+  <Step title="Finish">
+    - Summary and next steps, including iOS, Android, and macOS app options.
+  </Step>
+</Steps>
+
+<Note>
+If no GUI is detected, the wizard prints SSH port-forward instructions for the Control UI instead of opening a browser.
+If Control UI assets are missing, the wizard attempts to build them; fallback is `pnpm ui:build` (auto-installs UI deps).
+</Note>
+
+## Remote mode details
+
+Remote mode configures this machine to connect to a gateway elsewhere.
+
+<Info>
+Remote mode does not install or modify anything on the remote host.
+</Info>
+
+What you set:
+
+- Remote gateway URL (`ws://...`)
+- Token if remote gateway auth is required (recommended)
+
+<Note>
+- If gateway is loopback-only, use SSH tunneling or a tailnet.
+- Discovery hints:
+  - macOS: Bonjour (`dns-sd`)
+  - Linux: Avahi (`avahi-browse`)
+</Note>
+
+## Auth and model options
+
+<AccordionGroup>
+  <Accordion title="Anthropic API key (recommended)">
+    Uses `ANTHROPIC_API_KEY` if present or prompts for a key, then saves it for daemon use.
+  </Accordion>
+  <Accordion title="Anthropic OAuth (Claude Code CLI)">
+    - macOS: checks Keychain item "Claude Code-credentials"
+    - Linux and Windows: reuses `~/.claude/.credentials.json` if present
+
+    On macOS, choose "Always Allow" so launchd starts do not block.
+
+  </Accordion>
+  <Accordion title="Anthropic token (setup-token paste)">
+    Run `claude setup-token` on any machine, then paste the token.
+    You can name it; blank uses default.
+  </Accordion>
+  <Accordion title="OpenAI Code subscription (Codex CLI reuse)">
+    If `~/.codex/auth.json` exists, the wizard can reuse it.
+  </Accordion>
+  <Accordion title="OpenAI Code subscription (OAuth)">
+    Browser flow; paste `code#state`.
+
+    Sets `agents.defaults.model` to `openai-codex/gpt-5.3-codex` when model is unset or `openai/*`.
+
+  </Accordion>
+  <Accordion title="OpenAI API key">
+    Uses `OPENAI_API_KEY` if present or prompts for a key, then saves it to
+    `~/.openclaw/.env` so launchd can read it.
+
+    Sets `agents.defaults.model` to `openai/gpt-5.1-codex` when model is unset, `openai/*`, or `openai-codex/*`.
+
+  </Accordion>
+  <Accordion title="OpenCode Zen">
+    Prompts for `OPENCODE_API_KEY` (or `OPENCODE_ZEN_API_KEY`).
+    Setup URL: [opencode.ai/auth](https://opencode.ai/auth).
+  </Accordion>
+  <Accordion title="API key (generic)">
+    Stores the key for you.
+  </Accordion>
+  <Accordion title="Vercel AI Gateway">
+    Prompts for `AI_GATEWAY_API_KEY`.
+    More detail: [Vercel AI Gateway](/providers/vercel-ai-gateway).
+  </Accordion>
+  <Accordion title="Cloudflare AI Gateway">
+    Prompts for account ID, gateway ID, and `CLOUDFLARE_AI_GATEWAY_API_KEY`.
+    More detail: [Cloudflare AI Gateway](/providers/cloudflare-ai-gateway).
+  </Accordion>
+  <Accordion title="MiniMax M2.1">
+    Config is auto-written.
+    More detail: [MiniMax](/providers/minimax).
+  </Accordion>
+  <Accordion title="Synthetic (Anthropic-compatible)">
+    Prompts for `SYNTHETIC_API_KEY`.
+    More detail: [Synthetic](/providers/synthetic).
+  </Accordion>
+  <Accordion title="Moonshot and Kimi Coding">
+    Moonshot (Kimi K2) and Kimi Coding configs are auto-written.
+    More detail: [Moonshot AI (Kimi + Kimi Coding)](/providers/moonshot).
+  </Accordion>
+  <Accordion title="Skip">
+    Leaves auth unconfigured.
+  </Accordion>
+</AccordionGroup>
+
+Model behavior:
+
+- Pick default model from detected options, or enter provider and model manually.
+- Wizard runs a model check and warns if the configured model is unknown or missing auth.
+
+Credential and profile paths:
+
+- OAuth credentials: `~/.openclaw/credentials/oauth.json`
+- Auth profiles (API keys + OAuth): `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
+
+<Note>
+Headless and server tip: complete OAuth on a machine with a browser, then copy
+`~/.openclaw/credentials/oauth.json` (or `$OPENCLAW_STATE_DIR/credentials/oauth.json`)
+to the gateway host.
+</Note>
+
+## Outputs and internals
+
+Typical fields in `~/.openclaw/openclaw.json`:
+
+- `agents.defaults.workspace`
+- `agents.defaults.model` / `models.providers` (if Minimax chosen)
+- `gateway.*` (mode, bind, auth, tailscale)
+- `channels.telegram.botToken`, `channels.discord.token`, `channels.signal.*`, `channels.imessage.*`
+- Channel allowlists (Slack, Discord, Matrix, Microsoft Teams) when you opt in during prompts (names resolve to IDs when possible)
+- `skills.install.nodeManager`
+- `wizard.lastRunAt`
+- `wizard.lastRunVersion`
+- `wizard.lastRunCommit`
+- `wizard.lastRunCommand`
+- `wizard.lastRunMode`
+
+`openclaw agents add` writes `agents.list[]` and optional `bindings`.
+
+WhatsApp credentials go under `~/.openclaw/credentials/whatsapp/<accountId>/`.
+Sessions are stored under `~/.openclaw/agents/<agentId>/sessions/`.
+
+<Note>
+Some channels are delivered as plugins. When selected during onboarding, the wizard
+prompts to install the plugin (npm or local path) before channel configuration.
+</Note>
+
+Gateway wizard RPC:
+
+- `wizard.start`
+- `wizard.next`
+- `wizard.cancel`
+- `wizard.status`
+
+Clients (macOS app and Control UI) can render steps without re-implementing onboarding logic.
+
+Signal setup behavior:
+
+- Downloads the appropriate release asset
+- Stores it under `~/.openclaw/tools/signal-cli/<version>/`
+- Writes `channels.signal.cliPath` in config
+- JVM builds require Java 21
+- Native builds are used when available
+- Windows uses WSL2 and follows Linux signal-cli flow inside WSL
+
+## Related docs
+
+- Onboarding hub: [Onboarding Wizard (CLI)](/start/wizard)
+- Automation and scripts: [CLI Automation](/start/wizard-cli-automation)
+- Command reference: [`openclaw onboard`](/cli/onboard)

package/docs/start/wizard.md

@@ -0,0 +1,108 @@
+---
+summary: "CLI onboarding wizard: guided setup for gateway, workspace, channels, and skills"
+read_when:
+  - Running or configuring the onboarding wizard
+  - Setting up a new machine
+title: "Onboarding Wizard (CLI)"
+sidebarTitle: "Onboarding: CLI"
+---
+
+# Onboarding Wizard (CLI)
+
+The onboarding wizard is the **recommended** way to set up OpenClaw on macOS,
+Linux, or Windows (via WSL2; strongly recommended).
+It configures a local Gateway or a remote Gateway connection, plus channels, skills,
+and workspace defaults in one guided flow.
+
+```bash
+openclaw onboard
+```
+
+<Info>
+Fastest first chat: open the Control UI (no channel setup needed). Run
+`openclaw dashboard` and chat in the browser. Docs: [Dashboard](/web/dashboard).
+</Info>
+
+To reconfigure later:
+
+```bash
+openclaw configure
+openclaw agents add <name>
+```
+
+<Note>
+`--json` does not imply non-interactive mode. For scripts, use `--non-interactive`.
+</Note>
+
+<Tip>
+Recommended: set up a Brave Search API key so the agent can use `web_search`
+(`web_fetch` works without a key). Easiest path: `openclaw configure --section web`
+which stores `tools.web.search.apiKey`. Docs: [Web tools](/tools/web).
+</Tip>
+
+## QuickStart vs Advanced
+
+The wizard starts with **QuickStart** (defaults) vs **Advanced** (full control).
+
+<Tabs>
+  <Tab title="QuickStart (defaults)">
+    - Local gateway (loopback)
+    - Workspace default (or existing workspace)
+    - Gateway port **18789**
+    - Gateway auth **Token** (auto‑generated, even on loopback)
+    - Tailscale exposure **Off**
+    - Telegram + WhatsApp DMs default to **allowlist** (you'll be prompted for your phone number)
+  </Tab>
+  <Tab title="Advanced (full control)">
+    - Exposes every step (mode, workspace, gateway, channels, daemon, skills).
+  </Tab>
+</Tabs>
+
+## What the wizard configures
+
+**Local mode (default)** walks you through these steps:
+
+1. **Model/Auth** — Anthropic API key (recommended), OAuth, OpenAI, or other providers. Pick a default model.
+2. **Workspace** — Location for agent files (default `~/.openclaw/workspace`). Seeds bootstrap files.
+3. **Gateway** — Port, bind address, auth mode, Tailscale exposure.
+4. **Channels** — WhatsApp, Telegram, Discord, Google Chat, Mattermost, Signal, BlueBubbles, or iMessage.
+5. **Daemon** — Installs a LaunchAgent (macOS) or systemd user unit (Linux/WSL2).
+6. **Health check** — Starts the Gateway and verifies it's running.
+7. **Skills** — Installs recommended skills and optional dependencies.
+
+<Note>
+Re-running the wizard does **not** wipe anything unless you explicitly choose **Reset** (or pass `--reset`).
+If the config is invalid or contains legacy keys, the wizard asks you to run `openclaw doctor` first.
+</Note>
+
+**Remote mode** only configures the local client to connect to a Gateway elsewhere.
+It does **not** install or change anything on the remote host.
+
+## Add another agent
+
+Use `openclaw agents add <name>` to create a separate agent with its own workspace,
+sessions, and auth profiles. Running without `--workspace` launches the wizard.
+
+What it sets:
+
+- `agents.list[].name`
+- `agents.list[].workspace`
+- `agents.list[].agentDir`
+
+Notes:
+
+- Default workspaces follow `~/.openclaw/workspace-<agentId>`.
+- Add `bindings` to route inbound messages (the wizard can do this).
+- Non-interactive flags: `--model`, `--agent-dir`, `--bind`, `--non-interactive`.
+
+## Full reference
+
+For detailed step-by-step breakdowns, non-interactive scripting, Signal setup,
+RPC API, and a full list of config fields the wizard writes, see the
+[Wizard Reference](/reference/wizard).
+
+## Related docs
+
+- CLI command reference: [`openclaw onboard`](/cli/onboard)
+- macOS app onboarding: [Onboarding](/start/onboarding)
+- Agent first-run ritual: [Agent Bootstrapping](/start/bootstrapping)

package/docs/style.css

@@ -0,0 +1,3 @@
+#content > h1:first-of-type {
+  display: none !important;
+}