@gguf/claw

--- 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)