|
Download docs/start/wizard-cli-reference.md from shimen/shinclaw: direct link, hf CLI and curl.
- Browser
- Download file 10.1 kB
-
https://huggingface.co/spaces/shimen/shinclaw/resolve/main/docs/start/wizard-cli-reference.md
- Command line
-
hf download hf://spaces/shimen/shinclaw/docs/start/wizard-cli-reference.md
-
curl -L -o wizard-cli-reference.md https://huggingface.co/spaces/shimen/shinclaw/resolve/main/docs/start/wizard-cli-reference.md
10.1 kB
| 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="xAI (Grok) API key"> | |
| Prompts for `XAI_API_KEY` and configures xAI as a model provider. | |
| </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="Custom provider"> | |
| Works with OpenAI-compatible and Anthropic-compatible endpoints. | |
| Non-interactive flags: | |
| - `--auth-choice custom-api-key` | |
| - `--custom-base-url` | |
| - `--custom-model-id` | |
| - `--custom-api-key` (optional; falls back to `CUSTOM_API_KEY`) | |
| - `--custom-provider-id` (optional) | |
| - `--custom-compatibility <openai|anthropic>` (optional; default `openai`) | |
| </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) | |