Quick-start and first-run Q&A. For everyday operations, models, auth, sessions, and troubleshooting see the main FAQ.

Quick start and first-run setup

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

In task mode, due timestamps advance only after a real heartbeat run completes.
Skipped runs do not mark tasks as completed.

Docs: [Heartbeat](/gateway/heartbeat), [Automation](/automation).

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`.

- 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://<magicdns>/`. 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`.
- **Tailnet bind**: run `openclaw gateway --bind tailnet --token "<token>"` (or configure password auth), open `http://<tailscale-ip>:18789/`, paste the matching shared secret in dashboard settings.
- **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.

- `approvals.exec` - forwards approval prompts to chat destinations.
- `channels.<channel>.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.
- When a supported native channel can infer approvers safely, OpenClaw auto-enables DM-first native approvals if `channels.<channel>.execApprovals.enabled` is unset or `"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.<channel>.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).

| 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/canvas or command execution. See [Nodes](/nodes).

Full setup walkthrough: [Raspberry Pi](/install/raspberry-pi).

Full guide: [Raspberry Pi](/install/raspberry-pi). Also see [Linux](/platforms/linux).

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

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/<agentId>/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).

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

Still blocked? Docs are mirrored on GitHub:
[https://github.com/openclaw/openclaw/tree/main/docs](https://github.com/openclaw/openclaw/tree/main/docs)

- `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.

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

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

- **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](#quick-start-and-first-run-setup) above.

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

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

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

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

Guides: [exe.dev](/install/exe-dev), [Hetzner](/install/hetzner), [Fly.io](/install/fly).
Remote access: [Gateway remote](/gateway/remote).

- [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/canvas 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).

```bash
openclaw update
openclaw update status
openclaw update --channel stable|extended-stable|beta|dev
openclaw update --tag <dist-tag|version>
openclaw update --no-restart
```

Automating from an agent:

```bash
openclaw update --yes --no-restart
openclaw gateway restart
```

Docs: [Update](/cli/update), [Updating](/install/updating).

1. **Model/Auth** - provider OAuth, API keys, or manual auth (including local options like LM Studio); pick a default model.
2. **Workspace** - location + bootstrap files.
3. **Gateway** - port, bind address, auth mode, Tailscale exposure.
4. **Channels** - built-in and official plugin chat channels: iMessage, Discord, Feishu, Google Chat, Mattermost, Microsoft Teams, QQ Bot, Signal, Slack, Telegram, WhatsApp, and more.
5. **Daemon** - LaunchAgent (macOS), systemd user unit (Linux/WSL2), or native Windows Scheduled Task.
6. **Health check** - starts the Gateway and verifies it is running.
7. **Skills** - installs recommended skills and optional dependencies.

It sets duration expectations up front and warns if your configured model is unknown
or missing auth. Full breakdown: [Onboarding (CLI)](/start/wizard).

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

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

If the message is specifically `Extra usage is required for long context requests`,
the request is trying to use Anthropic's 1M context window (a GA-capable 1M Claude 4.x
model, or legacy `params.context1m: true` config), and your current credential is not
eligible for long-context billing.

Set a **fallback model** so OpenClaw keeps replying while a provider is rate-limited.
See [Models](/cli/models), [OAuth](/concepts/oauth), and
[Anthropic 429 extra usage required for long context](/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context).

- `openai/gpt-5.6-sol` = fresh ChatGPT/Codex subscription setup with the native Codex runtime for agent turns.
- `openai/gpt-5.5` = explicit supported selection for existing config or accounts without GPT-5.6 access.
- Legacy `openai-codex/*` model refs = legacy route repaired by `openclaw doctor --fix`.
- `openai/gpt-5.5` plus an ordered `openai` API-key profile = API-key auth for an OpenAI agent model.
- Legacy `openai-codex` auth profile ids = legacy ids migrated by `openclaw doctor --fix`.

Want direct OpenAI Platform billing? Set `OPENAI_API_KEY`. Want ChatGPT/Codex
subscription auth? Run `openclaw models auth login --provider openai`. Keep
model refs under the canonical `openai/*` provider. Fresh subscription
setup uses exact `openai/gpt-5.6-sol`; doctor repairs legacy Codex-prefixed
refs without upgrading an explicit `openai/gpt-5.5` selection.

`openclaw models status` shows the currently visible provider usage/quota windows, but
does not invent or normalize ChatGPT-web entitlements into direct API access. For the
direct OpenAI Platform billing/limit path, use `openai/*` with an API key.

See [OAuth](/concepts/oauth), [Model providers](/concepts/model-providers), and [Onboarding (CLI)](/start/wizard).

1. Install Gemini CLI locally so `gemini` is on `PATH`:
   - Homebrew: `brew install gemini-cli`
   - npm: `npm install -g @google/gemini-cli`
2. Enable the plugin: `openclaw plugins enable google`
3. Login: `openclaw models auth login --provider google-gemini-cli --set-default`
4. Default model after login: `google/gemini-3.1-pro-preview` (runtime `google-gemini-cli`)
5. Requests failing after login? Set `GOOGLE_CLOUD_PROJECT` or `GOOGLE_CLOUD_PROJECT_ID` on the gateway host and retry.

OAuth tokens are stored in auth profiles on the gateway host. Details: [Google](/providers/google), [Model providers](/concepts/model-providers).

You only need a Mac **for macOS-only tools**. For iMessage, use [iMessage](/channels/imessage)
with `imsg` on any Mac signed into Messages - if the Gateway runs on Linux or elsewhere,
set `channels.imessage.cliPath` to an SSH wrapper that runs `imsg` on that Mac. For other
macOS-only tools, run the Gateway on a Mac or pair a macOS node.

Docs: [iMessage](/channels/imessage), [Nodes](/nodes), [Mac remote mode](/platforms/mac/remote).

Common setups:

- Gateway on Linux/VPS, `channels.imessage.cliPath` set to an SSH wrapper that runs `imsg` on a Mac signed into Messages.
- Everything on one Mac for the simplest single-machine setup.

Docs: [iMessage](/channels/imessage), [Nodes](/nodes), [Mac remote mode](/platforms/mac/remote).

Common pattern: Gateway on the always-on Mac mini; MacBook Pro runs the macOS app or a
node host and pairs to the Gateway. Check with `openclaw nodes status` / `openclaw nodes list`.

Docs: [Nodes](/nodes), [Nodes CLI](/cli/nodes).

Safer (no third-party bot): DM your bot, run `openclaw logs --follow`, read `from.id`.

Official Bot API: DM your bot, call `https://api.telegram.org/bot<bot_token>/getUpdates`, read `message.from.id`.

Third-party (less private): DM `@userinfobot` or `@getidsbot`.

See [Telegram access control](/channels/telegram#access-control-and-activation).

```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> ~/.profile
eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"
brew install <formula>
```

Running OpenClaw via systemd: make sure the service PATH includes
`/home/linuxbrew/.linuxbrew/bin` (or your brew prefix) so `brew`-installed tools
resolve in non-login shells. Recent builds also prepend common user bin dirs on Linux
systemd services (for example `~/.local/bin`, `~/.npm-global/bin`,
`~/.local/share/pnpm`, `~/.bun/bin`) and honor `PNPM_HOME`, `NPM_CONFIG_PREFIX`,
`BUN_INSTALL`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `NVM_DIR`, and `FNM_DIR` when set.

Docs: [Getting started](/start/getting-started), [Updating](/install/updating).

npm to git:

```bash
openclaw update --channel dev
```

git to npm:

```bash
openclaw update --channel stable
```

Add `--dry-run` to preview the planned mode switch first. The updater runs Doctor
follow-ups, refreshes plugin sources for the target channel, and restarts the gateway
unless you pass `--no-restart`.

The installer can force either mode too:

```bash
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method npm
```

Backup tips: [Where things live on disk](/help/faq#where-things-live-on-disk).

**Laptop (local Gateway)**

- **Pros:** no server cost, direct access to local files, a live browser window.
- **Cons:** sleep/network drops disconnect it, OS updates/reboots interrupt it, must stay awake.

**VPS / cloud**

- **Pros:** always-on, stable network, no laptop sleep issues, easier to keep running.
- **Cons:** often headless (use screenshots), remote file access only, SSH needed for updates.

WhatsApp/Telegram/Slack/Mattermost/Discord all work fine from a VPS - the real
trade-off is headless browser vs a visible window. See [Browser](/tools/browser).

Default recommendation: VPS if you have had gateway disconnects before; local is great
when you are actively using the Mac and want local file access or visible-browser UI
automation.

- **Dedicated host (VPS/Mac mini/Raspberry Pi):** always-on, fewer sleep/reboot interruptions, cleaner permissions, easier to keep running.
- **Shared laptop/desktop:** fine for testing and active use, but expect pauses when the machine sleeps or updates.

Best of both worlds: keep the Gateway on a dedicated host and pair your laptop as a
**node** for local screen/camera/exec tools. See [Nodes](/nodes) and [Security](/gateway/security).

OS: **Ubuntu LTS** (or any modern Debian/Ubuntu) - the best-tested Linux install path.

Docs: [Linux](/platforms/linux), [VPS hosting](/vps).

- **Absolute minimum:** 1 vCPU, 1 GB RAM.
- **Recommended:** 2 GB+ RAM for multiple channels, browser automation, or media tools.
- **OS:** Ubuntu LTS or another modern Debian/Ubuntu.

On Windows, use **Windows Hub** for desktop setup, or WSL2 for a Linux-style Gateway VM
with broad tooling compatibility. See [Windows](/platforms/windows), [VPS hosting](/vps).
Running macOS in a VM: see [macOS VM](/install/macos-vm).

Related

• FAQ - the main FAQ (models, sessions, gateway, security, more)
• Install overview
• Getting started
• Troubleshooting

Source: docs/help/faq-first-run.md