|
Download docs/reference/wizard.md from shimen/shinclaw: direct link, hf CLI and curl.
- Browser
- Download file 11.4 kB
-
https://huggingface.co/spaces/shimen/shinclaw/resolve/main/docs/reference/wizard.md
- Command line
-
hf download hf://spaces/shimen/shinclaw/docs/reference/wizard.md
-
curl -L -o wizard.md https://huggingface.co/spaces/shimen/shinclaw/resolve/main/docs/reference/wizard.md
11.4 kB
| summary: "Full reference for the CLI onboarding wizard: every step, flag, and config field" | |
| read_when: | |
| - Looking up a specific wizard step or flag | |
| - Automating onboarding with non-interactive mode | |
| - Debugging wizard behavior | |
| title: "Onboarding Wizard Reference" | |
| sidebarTitle: "Wizard Reference" | |
| # Onboarding Wizard Reference | |
| This is the full reference for the `openclaw onboard` CLI wizard. | |
| For a high-level overview, see [Onboarding Wizard](/start/wizard). | |
| ## Flow details (local mode) | |
| <Steps> | |
| <Step title="Existing config detection"> | |
| - If `~/.openclaw/openclaw.json` exists, choose **Keep / Modify / Reset**. | |
| - 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 stops and asks | |
| you to run `openclaw doctor` before continuing. | |
| - Reset uses `trash` (never `rm`) and offers scopes: | |
| - Config only | |
| - Config + credentials + sessions | |
| - Full reset (also removes workspace) | |
| </Step> | |
| <Step title="Model/Auth"> | |
| - **Anthropic API key (recommended)**: uses `ANTHROPIC_API_KEY` if present or prompts for a key, then saves it for daemon use. | |
| - **Anthropic OAuth (Claude Code CLI)**: on macOS the wizard checks Keychain item "Claude Code-credentials" (choose "Always Allow" so launchd starts don't block); on Linux/Windows it reuses `~/.claude/.credentials.json` if present. | |
| - **Anthropic token (paste setup-token)**: run `claude setup-token` on any machine, then paste the token (you can name it; blank = default). | |
| - **OpenAI Code (Codex) subscription (Codex CLI)**: if `~/.codex/auth.json` exists, the wizard can reuse it. | |
| - **OpenAI Code (Codex) subscription (OAuth)**: browser flow; paste the `code#state`. | |
| - Sets `agents.defaults.model` to `openai-codex/gpt-5.2` when model is unset or `openai/*`. | |
| - **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. | |
| - **xAI (Grok) API key**: prompts for `XAI_API_KEY` and configures xAI as a model provider. | |
| - **OpenCode Zen (multi-model proxy)**: prompts for `OPENCODE_API_KEY` (or `OPENCODE_ZEN_API_KEY`, get it at https://opencode.ai/auth). | |
| - **API key**: stores the key for you. | |
| - **Vercel AI Gateway (multi-model proxy)**: prompts for `AI_GATEWAY_API_KEY`. | |
| - More detail: [Vercel AI Gateway](/providers/vercel-ai-gateway) | |
| - **Cloudflare AI Gateway**: prompts for Account ID, Gateway ID, and `CLOUDFLARE_AI_GATEWAY_API_KEY`. | |
| - More detail: [Cloudflare AI Gateway](/providers/cloudflare-ai-gateway) | |
| - **MiniMax M2.1**: config is auto-written. | |
| - More detail: [MiniMax](/providers/minimax) | |
| - **Synthetic (Anthropic-compatible)**: prompts for `SYNTHETIC_API_KEY`. | |
| - More detail: [Synthetic](/providers/synthetic) | |
| - **Moonshot (Kimi K2)**: config is auto-written. | |
| - **Kimi Coding**: config is auto-written. | |
| - More detail: [Moonshot AI (Kimi + Kimi Coding)](/providers/moonshot) | |
| - **Skip**: no auth configured yet. | |
| - Pick a default model from detected options (or enter provider/model manually). | |
| - Wizard runs a model check and warns if the configured model is unknown or missing auth. | |
| - OAuth credentials live in `~/.openclaw/credentials/oauth.json`; auth profiles live in `~/.openclaw/agents/<agentId>/agent/auth-profiles.json` (API keys + OAuth). | |
| - More detail: [/concepts/oauth](/concepts/oauth) | |
| <Note> | |
| Headless/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> | |
| </Step> | |
| <Step title="Workspace"> | |
| - Default `~/.openclaw/workspace` (configurable). | |
| - Seeds the workspace files needed for the agent bootstrap ritual. | |
| - Full workspace layout + backup guide: [Agent workspace](/concepts/agent-workspace) | |
| </Step> | |
| <Step title="Gateway"> | |
| - Port, bind, auth mode, tailscale exposure. | |
| - Auth recommendation: keep **Token** 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 a logged-in user session; for headless, use a custom LaunchDaemon (not shipped). | |
| - Linux (and Windows via WSL2): systemd user unit | |
| - Wizard attempts to enable lingering via `loginctl enable-linger <user>` so the 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/Telegram). Bun is **not recommended**. | |
| </Step> | |
| <Step title="Health check"> | |
| - Starts the Gateway (if needed) and runs `openclaw health`. | |
| - Tip: `openclaw status --deep` adds gateway health probes to status output (requires a reachable gateway). | |
| </Step> | |
| <Step title="Skills (recommended)"> | |
| - Reads the available skills and checks requirements. | |
| - Lets you choose a node manager: **npm / pnpm** (bun not recommended). | |
| - Installs optional dependencies (some use Homebrew on macOS). | |
| </Step> | |
| <Step title="Finish"> | |
| - Summary + next steps, including iOS/Android/macOS apps for extra features. | |
| </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 the Control UI assets are missing, the wizard attempts to build them; fallback is `pnpm ui:build` (auto-installs UI deps). | |
| </Note> | |
| ## Non-interactive mode | |
| Use `--non-interactive` to automate or script onboarding: | |
| ```bash | |
| openclaw onboard --non-interactive \ | |
| --mode local \ | |
| --auth-choice apiKey \ | |
| --anthropic-api-key "$ANTHROPIC_API_KEY" \ | |
| --gateway-port 18789 \ | |
| --gateway-bind loopback \ | |
| --install-daemon \ | |
| --daemon-runtime node \ | |
| --skip-skills | |
| ``` | |
| Add `--json` for a machine‑readable summary. | |
| <Note> | |
| `--json` does **not** imply non-interactive mode. Use `--non-interactive` (and `--workspace`) for scripts. | |
| </Note> | |
| <AccordionGroup> | |
| <Accordion title="Gemini example"> | |
| ```bash | |
| openclaw onboard --non-interactive \ | |
| --mode local \ | |
| --auth-choice gemini-api-key \ | |
| --gemini-api-key "$GEMINI_API_KEY" \ | |
| --gateway-port 18789 \ | |
| --gateway-bind loopback | |
| ``` | |
| </Accordion> | |
| <Accordion title="Z.AI example"> | |
| ```bash | |
| openclaw onboard --non-interactive \ | |
| --mode local \ | |
| --auth-choice zai-api-key \ | |
| --zai-api-key "$ZAI_API_KEY" \ | |
| --gateway-port 18789 \ | |
| --gateway-bind loopback | |
| ``` | |
| </Accordion> | |
| <Accordion title="Vercel AI Gateway example"> | |
| ```bash | |
| openclaw onboard --non-interactive \ | |
| --mode local \ | |
| --auth-choice ai-gateway-api-key \ | |
| --ai-gateway-api-key "$AI_GATEWAY_API_KEY" \ | |
| --gateway-port 18789 \ | |
| --gateway-bind loopback | |
| ``` | |
| </Accordion> | |
| <Accordion title="Cloudflare AI Gateway example"> | |
| ```bash | |
| openclaw onboard --non-interactive \ | |
| --mode local \ | |
| --auth-choice cloudflare-ai-gateway-api-key \ | |
| --cloudflare-ai-gateway-account-id "your-account-id" \ | |
| --cloudflare-ai-gateway-gateway-id "your-gateway-id" \ | |
| --cloudflare-ai-gateway-api-key "$CLOUDFLARE_AI_GATEWAY_API_KEY" \ | |
| --gateway-port 18789 \ | |
| --gateway-bind loopback | |
| ``` | |
| </Accordion> | |
| <Accordion title="Moonshot example"> | |
| ```bash | |
| openclaw onboard --non-interactive \ | |
| --mode local \ | |
| --auth-choice moonshot-api-key \ | |
| --moonshot-api-key "$MOONSHOT_API_KEY" \ | |
| --gateway-port 18789 \ | |
| --gateway-bind loopback | |
| ``` | |
| </Accordion> | |
| <Accordion title="Synthetic example"> | |
| ```bash | |
| openclaw onboard --non-interactive \ | |
| --mode local \ | |
| --auth-choice synthetic-api-key \ | |
| --synthetic-api-key "$SYNTHETIC_API_KEY" \ | |
| --gateway-port 18789 \ | |
| --gateway-bind loopback | |
| ``` | |
| </Accordion> | |
| <Accordion title="OpenCode Zen example"> | |
| ```bash | |
| openclaw onboard --non-interactive \ | |
| --mode local \ | |
| --auth-choice opencode-zen \ | |
| --opencode-zen-api-key "$OPENCODE_API_KEY" \ | |
| --gateway-port 18789 \ | |
| --gateway-bind loopback | |
| ``` | |
| </Accordion> | |
| </AccordionGroup> | |
| ### Add agent (non-interactive) | |
| ```bash | |
| openclaw agents add work \ | |
| --workspace ~/.openclaw/workspace-work \ | |
| --model openai/gpt-5.2 \ | |
| --bind whatsapp:biz \ | |
| --non-interactive \ | |
| --json | |
| ``` | |
| ## 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 `~/.openclaw/tools/signal-cli/<version>/`. | |
| - Writes `channels.signal.cliPath` to your config. | |
| Notes: | |
| - JVM builds require **Java 21**. | |
| - Native builds are used when available. | |
| - Windows uses WSL2; signal-cli install follows the Linux flow inside WSL. | |
| ## What the wizard writes | |
| 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 the 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/`. | |
| Some channels are delivered as plugins. When you pick one during onboarding, the wizard | |
| will prompt to install it (npm or a local path) before it can be configured. | |
| ## Related docs | |
| - Wizard overview: [Onboarding Wizard](/start/wizard) | |
| - macOS app onboarding: [Onboarding](/start/onboarding) | |
| - Config reference: [Gateway configuration](/gateway/configuration) | |
| - Providers: [WhatsApp](/channels/whatsapp), [Telegram](/channels/telegram), [Discord](/channels/discord), [Google Chat](/channels/googlechat), [Signal](/channels/signal), [BlueBubbles](/channels/bluebubbles) (iMessage), [iMessage](/channels/imessage) (legacy) | |
| - Skills: [Skills](/tools/skills), [Skills config](/tools/skills-config) | |