--- summary: "FAQ: install, onboarding, first-run failures, builds, and subscription basics" read_when: - New install, onboarding stuck, or first-run errors - Choosing between stable, beta, and dev builds - Install or onboarding fails on macOS, Linux, Windows, or a Pi title: "FAQ: quick start and first-run setup" sidebarTitle: "Quick start and setup" --- Install, onboarding, and early-failure Q&A. For provider auth, hardware, and where to run the Gateway see [FAQ: providers, hardware, and hosting](/help/faq-first-run/providers-and-hosting). ## Quick start and first-run setup ```bash curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash ``` The installer starts guided onboarding for you, so there is no separate onboarding command to run. When onboarding finishes, press **Ctrl+C** to stop the foreground Gateway and install the background service: ```bash openclaw gateway install ``` Prefer the classic step-by-step wizard and a service install in one command? Run `openclaw onboard --install-daemon` instead of the two commands above. That flag selects the classic flow, so you do not see the guided **Quick start** and **Custom setup** choice. From source (contributors/dev): ```bash git clone https://github.com/openclaw/openclaw.git cd openclaw pnpm install pnpm build pnpm ui:build openclaw onboard ``` No global install yet? Run `pnpm openclaw onboard` instead. If Control UI assets are missing, onboarding tries to build them itself, falling back to `pnpm ui:build`. Use a local AI agent that can **see your machine**. Most "I'm stuck" cases are **local config or environment issues** a remote helper cannot inspect, so this beats asking in Discord. - **Claude Code**: [https://www.anthropic.com/claude-code/](https://www.anthropic.com/claude-code/) - **OpenAI Codex**: [https://openai.com/codex/](https://openai.com/codex/) Give the agent the full source checkout via the hackable (git) install so it can read code + docs and reason about the exact version you run: ```bash curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git ``` Ask the agent to plan and supervise the fix step-by-step, then execute only the necessary commands - smaller diffs are easier to audit. Share these outputs when asking for help (in Discord or a GitHub issue): | Command | Shows | | --- | --- | | `openclaw status` | Gateway/agent health + basic config snapshot | | `openclaw status --all` | Full read-only diagnosis, pasteable | | `openclaw models status` | Provider auth + model availability | | `openclaw doctor` | Validates and repairs common config/state issues | | `openclaw logs --follow` | Live log tail | | `openclaw gateway status --deep` | Deep gateway/config/plugin health check | | `openclaw health --verbose` | Detailed health report | Found a real bug or fix? File an issue or send a PR: [Issues](https://github.com/openclaw/openclaw/issues) / [Pull requests](https://github.com/openclaw/openclaw/pulls). Quick debug loop: [First 60 seconds if something is broken](/help/faq#first-60-seconds-if-something-is-broken). Install docs: [Install](/install), [Installer flags](/install/installer), [Updating](/install/updating). Onboarding opens your browser to a clean (non-tokenized) dashboard URL right after setup and prints the link in the summary. Keep that tab open; if it did not launch, copy/paste the printed URL on the same machine. **Localhost (same machine):** - Open `http://127.0.0.1:18789/`. - If it asks for shared-secret auth, paste the configured token or password into Control UI settings. - Token source: `gateway.auth.token` (or `OPENCLAW_GATEWAY_TOKEN`). - Password source: `gateway.auth.password` (or `OPENCLAW_GATEWAY_PASSWORD`). - No shared secret configured yet? Run `openclaw doctor --generate-gateway-token` (or `openclaw doctor --fix --generate-gateway-token`). **Not on localhost:** - **Tailscale Serve** (recommended): keep bind loopback, run `openclaw gateway --tailscale serve`, open `https:///`. With `gateway.auth.allowTailscale: true`, identity headers satisfy Control UI/WebSocket auth (no pasted shared secret, assumes a trusted gateway host); HTTP APIs still need shared-secret auth unless you deliberately use private-ingress `none` or trusted-proxy HTTP auth. Concurrent bad-auth Serve attempts from the same client are serialized before the failed-auth limiter records them, so a second bad retry can already show `retry later`. - **Identity-aware reverse proxy**: keep the Gateway behind a trusted proxy, set `gateway.auth.mode: "trusted-proxy"`, open the proxy URL. Same-host loopback proxies need explicit `gateway.auth.trustedProxy.allowLoopback: true`. - **SSH tunnel**: `ssh -N -L 18789:127.0.0.1:18789 user@gateway-host`, then open `http://127.0.0.1:18789/`. Shared-secret auth still applies over the tunnel; paste the configured token or password if prompted. See [Dashboard](/web/dashboard) and [Web surfaces](/web) for bind modes and auth details. | Skip reason | Meaning | | --- | --- | | `quiet-hours` | Outside the configured active-hours window | | `empty-heartbeat-file` | Heartbeat monitor scratch exists but only has blank, comment, header, fence, or empty-checklist scaffolding | | `alerts-disabled` | All heartbeat visibility is off (`showOk`, `showAlerts`, and `useIndicator` all disabled) | Older heartbeat `tasks:` blocks migrate to independently scheduled cron jobs with `openclaw doctor --fix`. Docs: [Heartbeat](/gateway/heartbeat), [Automation](/automation). They control different layers: - `approvals.exec` - forwards approval prompts to chat destinations. - `channels..execApprovals` - makes that channel a native approval client for exec approvals. The host exec policy is still the real approval gate; chat config only controls where prompts appear and how people answer them. You rarely need both: - If the chat already supports commands and replies, same-chat `/approve` works through the shared path. - For supported native clients, set `channels..execApprovals.enabled: "auto"` or `true` and configure approvers or the channel's supported owner identity. Discord and Slack require explicit enablement; Telegram treats unset as `"auto"`. - When native approval cards/buttons are available, that UI is primary; only mention a manual `/approve` command if the tool result says chat approvals are unavailable. - Use `approvals.exec` only when prompts must also reach other chats or explicit ops rooms. - Use `channels..execApprovals.target: "channel"` or `"both"` only when you want approval prompts posted back into the originating room/topic. - Plugin approvals are separate: same-chat `/approve` by default, optional `approvals.plugin` forwarding, and only some native channels keep native handling for those too. Short version: forwarding is for routing, native client config is for richer channel-specific UX. See [Exec Approvals](/tools/exec-approvals). Node **24.16+** or **26.1+** is the primary and default runtime (Node 26 recommended); see [Node.js](/install/node) for the maintained requirement. `pnpm` is the repo package manager. Bun 1.4+ builds with WAL-reset-safe `node:sqlite` can run the CLI, Gateway, and managed node host as an explicit opt-in. Yes, but check RAM first: Pi 5 and Pi 4 (2 GB+) are the sweet spot; Pi 3B+ (1 GB) works but is slow; Pi Zero 2 W (512 MB) is not recommended. | Model | RAM | Fit | | --- | --- | --- | | Pi 5 | 4/8 GB | Best | | Pi 4 | 4 GB | Good | | Pi 4 | 2 GB | OK, add swap | | Pi 4 | 1 GB | Tight | | Pi 3B+ | 1 GB | Slow | | Pi Zero 2 W | 512 MB | Not recommended | Absolute minimum: 1 GB RAM, 1 core, 500 MB free disk, 64-bit OS. Since the Pi only runs the Gateway (models call out to cloud APIs), even a modest Pi handles the load. A small Pi/VPS can also host just the Gateway while you pair **nodes** on your laptop/phone for local screen/camera or command execution. A paired Mac can also present hosted widgets in its native panel. See [Nodes](/nodes). Full setup walkthrough: [Raspberry Pi](/install/raspberry-pi). - Use a **64-bit** OS; do not use 32-bit Raspberry Pi OS. - Add swap on 2 GB or smaller boards. - Prefer a **USB SSD** over an SD card for performance and longevity. - Prefer the hackable (git) install so you can see logs and update fast. - Start without channels/skills, add them one by one. - Weird binary failures ("exec format error") are usually a missing ARM64 build for an optional skill tool. Full guide: [Raspberry Pi](/install/raspberry-pi). Also see [Linux](/platforms/linux). That screen depends on the Gateway being reachable and authenticated. The TUI also sends "Wake up, my friend!" automatically on first hatch when a model provider is configured. If you skipped model/auth setup, onboarding shows a "Model auth missing" note and opens the TUI without sending anything — add a provider by running `openclaw onboard` again. That is the one command for changing the model provider or its authentication. If you see the wake-up line with **no reply** and tokens stay at 0, the agent never ran. 1. Restart the Gateway: ```bash openclaw gateway restart ``` 2. Check status + auth: ```bash openclaw status openclaw models status openclaw logs --follow ``` 3. Still hanging? Run: ```bash openclaw doctor ``` If the Gateway is remote, confirm the tunnel/Tailscale connection is up and the UI points at the right Gateway. See [Remote access](/gateway/remote). Yes. Copy the **state directory** and **workspace**, then run Doctor once: 1. Install OpenClaw on the new machine. 2. Copy `$OPENCLAW_STATE_DIR` (default: `~/.openclaw`) from the old machine. 3. Copy your workspace (default: `~/.openclaw/workspace`). 4. Run `openclaw doctor` and restart the Gateway service. This preserves config, auth profiles, WhatsApp creds, sessions, and memory - it keeps your bot exactly the same, as long as you copy **both** locations. In remote mode, the gateway host owns the session store and workspace. **Important:** if you only commit/push your workspace to GitHub, you back up **memory + bootstrap files**, but not session history or auth. Those live under `~/.openclaw/` (for example `~/.openclaw/agents//agent/openclaw-agent.sqlite`). Related: [Migrating](/install/migrating), [Where things live on disk](/help/faq#where-things-live-on-disk), [Agent workspace](/concepts/agent-workspace), [Doctor](/gateway/doctor), [Remote mode](/gateway/remote). Check the GitHub changelog: [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md) Newest entries are at the top. If the top section is **Unreleased**, the next dated section is the latest shipped version. Entries group under **Highlights**, **Changes**, and **Fixes** (plus docs/other sections when needed). Some Comcast/Xfinity connections incorrectly block `docs.openclaw.ai` via Xfinity Advanced Security. Disable it or allowlist `docs.openclaw.ai`, then retry. Help us get it unblocked: [https://spa.xfinity.com/check_url_status](https://spa.xfinity.com/check_url_status). Still blocked? Docs are mirrored on GitHub: [https://github.com/openclaw/openclaw/tree/main/docs](https://github.com/openclaw/openclaw/tree/main/docs) **Stable** and **beta** are **npm dist-tags**, not separate code lines: - `latest` = stable - `beta` = early build for testing (falls back to `latest` when beta is missing or older than the current stable release) A stable release usually lands on **beta** first, then an explicit promotion step moves that same version to `latest` without changing the version number. Maintainers can also publish straight to `latest`. That is why beta and stable can point at the **same version** after promotion. See what changed: [CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md). For install one-liners and the difference between beta and dev, see the next accordion. **Beta** is the npm dist-tag `beta` (may match `latest` after promotion). **Dev** is the moving head of `main` (git); when published to npm it uses dist-tag `dev`. One-liners (macOS/Linux): ```bash curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --beta ``` ```bash curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git ``` Windows installer (PowerShell): `iwr -useb https://openclaw.ai/install.ps1 | iex` More detail: [Development channels](/install/development-channels) and [Installer flags](/install/installer). Two options: 1. **Dev channel (existing install):** ```bash openclaw update --channel dev ``` This switches to a git checkout of `main`, rebases on upstream, builds, and installs the CLI from that checkout. 2. **Hackable (git) install (fresh machine):** ```bash curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git ``` Prefer a manual clone: ```bash git clone https://github.com/openclaw/openclaw.git cd openclaw pnpm install pnpm build ``` Docs: [Update](/cli/update), [Development channels](/install/development-channels), [Install](/install). Rough guide: - **Install:** 2-5 minutes. - **QuickStart onboarding:** a few minutes (loopback gateway, auto token, default workspace). - **Advanced/full onboarding:** longer when provider sign-in, channel pairing, daemon install, network downloads, or skills need extra setup. The wizard shows this timeline up front. Skip optional steps and return later with `openclaw configure`. Hanging? See [I am stuck](#i-am-stuck) above. Re-run with `--verbose`: ```bash curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --verbose curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --beta --verbose curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git --verbose ``` `install.ps1` has no dedicated verbose switch; wrap it in `Set-PSDebug -Trace 1` / `-Trace 0` instead. Full flag reference: [Installer flags](/install/installer). Two common Windows issues: **1) npm error spawn git / git not found** - Install **Git for Windows**, make sure `git` is on PATH. - Close and reopen PowerShell, then re-run the installer. **2) openclaw is not recognized after install** - Your npm global bin folder is not on PATH. - Check it: `npm config get prefix`. - Add that directory to your user PATH (no `\bin` suffix needed; on most systems it is `%AppData%\npm`). - Close and reopen PowerShell. Prefer a desktop app? Use **Windows Hub**. Terminal-only setup: the PowerShell installer and WSL2 Gateway paths are both supported. Docs: [Windows](/platforms/windows). Usually a console code page mismatch on native Windows shells. Symptoms: `system.run`/`exec` output renders Chinese as mojibake; the same command looks fine in another terminal profile. Workaround in PowerShell: ```powershell chcp 65001 [Console]::InputEncoding = [System.Text.UTF8Encoding]::new($false) [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false) $OutputEncoding = [System.Text.UTF8Encoding]::new($false) ``` Then restart the Gateway and retry: ```powershell openclaw gateway restart ``` Still reproducing this on latest OpenClaw? Track/report it: [Issue #30640](https://github.com/openclaw/openclaw/issues/30640). Use the hackable (git) install so you have the full source and docs locally, then ask your bot (or Claude/Codex) **from that folder** so it can read the repo and answer precisely. ```bash curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git ``` More detail: [Install](/install) and [Installer flags](/install/installer). - Linux quick path + service install: [Linux](/platforms/linux). - Full walkthrough: [Getting Started](/start/getting-started). - Installer + updates: [Install & updates](/install/updating). Any Linux VPS works. Install on the server, then reach the Gateway over SSH/Tailscale. Guides: [exe.dev](/install/exe-dev), [Hetzner](/install/hetzner), [Fly.io](/install/fly). Remote access: [Gateway remote](/gateway/remote). Hosting hub with common providers: - [VPS hosting](/vps) (all providers in one place) - [Fly.io](/install/fly) - [Hetzner](/install/hetzner) - [exe.dev](/install/exe-dev) In the cloud, the **Gateway runs on the server** and you access it from your laptop/phone via the Control UI (or Tailscale/SSH). Your state + workspace live on the server, so treat the host as the source of truth and back it up. Pair **nodes** (Mac/iOS/Android/headless) to that cloud Gateway for local screen/camera or command execution on your laptop while the Gateway stays in the cloud. Hub: [Platforms](/platforms). Remote access: [Gateway remote](/gateway/remote). Nodes: [Nodes](/nodes), [Nodes CLI](/cli/nodes). Possible, not recommended. The update flow can restart the Gateway (dropping the active session), may need a clean git checkout, and can prompt for confirmation. Safer to run updates from a shell as the operator. ```bash openclaw update openclaw update status openclaw update --channel beta openclaw update --tag 2026.9.3 openclaw update --no-restart ``` `--channel` accepts `stable`, `extended-stable`, `beta`, or `dev`. `--tag` accepts an npm dist-tag or an exact version. Automating from an agent: ```bash openclaw update --yes --no-restart openclaw gateway restart ``` Docs: [Update](/cli/update), [Updating](/install/updating). `openclaw onboard` is the recommended setup path. On a fresh local install it offers two lanes after a one-line pointer to the [security guide](/gateway/security): - **Quick start** detects the AI access you already have, waits for you to choose a connection, verifies that one choice with a real completion, prepares the agent workspace, and then starts the Gateway in the foreground and opens the browser dashboard. It uses the default agent name `main` and full access, and skips memory import and app recommendations. Choose **Skip for now** in the picker to prepare the local baseline and exit without starting the Gateway or AI chat. - **Custom setup** runs the same guided flow with the telemetry choice, agent name, access mode, and optional setup prompts kept as questions. Both lanes require an explicit provider choice before any live completion, provider installation, model selection, or credential write. The classic step-by-step wizard is still available. Run `openclaw onboard --classic` for its Workspace, Model/Auth, Gateway, Channels, Web search, Skills, Daemon, and Health check steps. The step list is in [Onboarding (CLI)](/start/wizard#what-classic-onboarding-configures). Quick start is not offered for configured installs, remote Gateway chat setup, non-interactive runs, or runs with `--skip-ui` or `--tui`. Full breakdown: [Onboarding (CLI)](/start/wizard). No. Run OpenClaw with **API keys** (Anthropic/OpenAI/others) or **local-only models** so your data stays on your device. Subscriptions (Claude Pro/Max, ChatGPT/Codex) are optional ways to authenticate those providers. For Anthropic: an **API key** gives standard pay-as-you-go billing; **Claude CLI** reuses an existing Claude Code login on the same host. Anthropic currently treats Claude CLI's non-interactive `claude -p` path as Agent SDK/programmatic usage that still draws from your subscription's plan limits - check current Anthropic billing docs before relying on subscription behavior. For long-lived gateway hosts and shared automation, an Anthropic API key is the more predictable choice. OpenAI Codex OAuth (ChatGPT/Codex subscription) is fully supported for agent models. OpenClaw also supports hosted subscription-style options including **Qwen Cloud Coding Plan**, **MiniMax Coding Plan**, and **Z.AI / GLM Coding Plan**. Docs: [Anthropic](/providers/anthropic), [OpenAI](/providers/openai), [Qwen Cloud](/providers/qwen), [MiniMax](/providers/minimax), [Z.AI (GLM)](/providers/zai), [Local models](/gateway/local-models), [Models](/concepts/models). Yes. OpenClaw supports Claude CLI reuse for Pro/Max/Team/Enterprise plans. Anthropic currently treats the `claude -p` path OpenClaw uses as subscription-plan usage subject to your plan's limits, not a separate free allowance - see [Anthropic](/providers/anthropic) for the current billing detail and links to Anthropic's own support articles. For the most predictable server-side setup, use an Anthropic API key instead. Yes, via Claude CLI reuse. Anthropic's billing treatment of `claude -p`/Agent SDK usage has changed over time; see [Anthropic](/providers/anthropic) for the current state and dated links to Anthropic's support articles before relying on specific billing behavior. Anthropic setup-token auth is also still a supported token path, but OpenClaw prefers Claude CLI reuse and `claude -p` when available. For production or multi-user workloads, an Anthropic API key remains the safer, more predictable choice. Other subscription-style hosted options: [OpenAI](/providers/openai), [Qwen Cloud](/providers/qwen), [MiniMax](/providers/minimax), [Z.AI (GLM)](/providers/zai).